@cef-ai/agent-sdk

Author agents for the Cere Execution Fabric: a small surface of decorators and types that maps directly to the runtime contract.

Install

pnpm add @cef-ai/agent-sdk

For tests, also install the harness:

pnpm add -D @cef-ai/testing

Quickstart

An agent is a default-exported class with decorated methods. @OnEvent binds an event type to a handler; @OnStart and @OnClose are lifecycle hooks. Context is the single object the runtime threads through every call.

import {
  OnClose,
  OnEvent,
  OnStart,
  type Context,
  type Event,
  type OnCloseReason,
} from "@cef-ai/agent-sdk";

interface UserMessage {
  text: string;
}

export default class Echo {
  @OnStart
  async onStart() {
    // Logging + HTTP are plain Web globals, not ctx members:
    console.info("started");
  }

  @OnEvent("user_message")
  async onMessage(event: Event<UserMessage>, ctx: Context) {
    await ctx
      .cubby("history")
      .exec("INSERT INTO messages(text, ts) VALUES (?, ?)", [
        event.payload.text,
        event.ts,
      ]);
    await ctx.publish("ack", { for: event.id });
  }

  @OnClose
  async onClose(_ctx: Context, reason: OnCloseReason) {
    console.info("closing", { reason });
  }
}

ctx carries only the CEF-specific platform calls. For plain capabilities, use the sandbox globals directly: console.* for logging (the runtime captures it) and fetch for HTTP.

Pair the class with a cef.config.ts:

import { defineAgent } from "@cef-ai/agent-sdk/config";

export default defineAgent({
  id: "echo",
  version: "1.0.0",
  entry: "./agent.ts",
  cubbies: [{ alias: "history", migrations: "./migrations/history" }],
});

API summary

| Kind | Symbol | Notes | | --- | --- | --- | | Decorator | @OnEvent(type) | Bind an event type (string literal) to a handler. | | Decorator | @OnStart | Mark the start lifecycle hook. | | Decorator | @OnClose | Mark the close lifecycle hook. | | Type | Context | CEF-specific platform calls only — cubby, models, publish, settings, close. (Log/HTTP are the globals console / fetch.) | | Type | Event<P> | { id, type, ts, from, payload: P }. | | Type | CubbyHandle | query(sql, params) / exec(sql, params) over per-alias storage. | | Type | ModelHandle<I,O> | infer(input) / stream(input) per declared model alias. | | Type | OnCloseReason | "revoked" \| "idle_timeout" \| "closed_by_agent" \| "failed". | | Interface | KnownEventTypes | Declaration-merged event-type map populated by typegen. | | Function | defineAgent(config) | Identity helper that preserves literal types of AgentConfig. | | Type | AgentConfig | Top-level config: id, version, entry, cubbies, models, settings, fetch, publishes, lifecycle. |

How it runs (runtime model)

Per Agent Runtime ADR-001, the Cere Network runtime is a CEF-agnostic bundle executor: it exposes only Web-platform globals (fetch, console, URL, crypto, TextEncoder, timers, …) plus one opaque globalThis.context object, and dispatches invocations as globalThis.__handlers[name](event, context).

ctx is CEF-specific add-ons only — SDK code compiled into your bundle by cef build, not a runtime-provided binding:

• ctx.publish / ctx.cubby / ctx.models[…].infer / ctx.close → fetch calls to the endpoints the orchestrator places in globalThis.context (context.endpoints.*, with context.auth headers).
• ctx.settings → context.settings.

Plain Web-platform capabilities are not mirrored on ctx — use the sandbox globals directly: console.* for logging (captured out-of-band by the runtime) and fetch for HTTP.

You never write the shim code — you author the decorated class, and the shims (the @cef-ai/agent-sdk/runtime subpath) are bundled in automatically.

Inference usage is reported automatically. Each ctx.models[…].infer call captures the gateway's usage and the SDK folds a _modelCalls array into your handler's return value; the orchestrator reads it to record per-model token/GPU usage (ADR-004). _modelCalls is a reserved result key — don't set it yourself.

Subpath exports

| Specifier | Purpose | | --- | --- | | @cef-ai/agent-sdk | Decorators, Context, Event, KnownEventTypes, ModelHandle, CubbyHandle, OnCloseReason. | | @cef-ai/agent-sdk/config | defineAgent and the AgentConfig shape — used in cef.config.ts. | | @cef-ai/agent-sdk/runtime | Build-internal: the ctx shims + registerHandlers that cef build compiles into the bundle. Authors never import this directly. |

For testing, use @cef-ai/testing directly — import { testAgent } from "@cef-ai/testing".

Companion packages

• @cef-ai/cli — cef build (esbuild + manifest), cef typegen (populates KnownEventTypes), cef inspect.
• @cef-ai/testing — simulator harness for unit and integration tests.
• @cef-ai/eslint-plugin — editor-time lints mirroring the build-time checks.

References

• Agent SDK spec: ../../../company-memory-bank/specs/platform/03-components/agent-sdk.md
• Runtime integration contract: ../../../company-memory-bank/specs/platform/03-components/sdk-runtime-integration-contract.md
• Implementation plan: ../../../company-memory-bank/plans/2026-04-27-sdk-implementation-plan.md

The ../company-memory-bank/... paths are local references to an internal sibling repo and are not browsable from a fresh clone.