@cef-ai/cli

cef — build, typegen, and inspect agents from the command line. Mirrors the Agent Runtime contract (ADR-001): bundles install a flat handler map at globalThis.__handlers, manifests carry the routing table the orchestrator reads.

Install

pnpm add -D @cef-ai/cli

This adds the cef binary to node_modules/.bin. In a workspace project, invoke it via pnpm exec cef <subcommand>.

Subcommands

| Subcommand | Status | Description | | --- | --- | --- | | cef build | shipped | Lint the agent entry, bundle with esbuild (the bundle imports the SDK runtime shims and installs globalThis.__handlers), emit dist/<agentId>/{bundle.js,manifest.json}. | | cef typegen | shipped | Generate .cef/generated.d.ts (declaration-merged KnownEventTypes) and refresh cef.lock.json. | | cef inspect <agentDir> | shipped | Read a built manifest.json, run the bundle in node:vm, and report the handler names exposed on __handlers plus any routing targets the manifest references but the bundle doesn't expose. | | cef test | stub | Placeholder — use vitest directly with @cef-ai/testing until the integrated runner lands. | | cef publish | stub | Placeholder — pending the Marketplace API. | | cef dev | stub | Placeholder — pending the packaged platform image. |

cef build writes one directory per declared agent:

dist/
  <agentId>/
    bundle.js      # IIFE that installs globalThis.__handlers — a flat map
                   # of handler functions the runtime dispatches as
                   # __handlers[name](event, context). Event handlers are
                   # keyed "<engagementId>::<method>"; lifecycle hooks under
                   # the fixed keys onStart / onClose.
    manifest.json  # AgentManifest body — bundle embedded inline; each
                   # engagement carries handles{eventType -> handlerName}
                   # (namespaced) and hooks[] ("start"/"close"). Identity /
                   # signature fields are blank until `cef publish` signs.

The handler-name namespacing (<engagementId>::<method>) keeps the flat __handlers map collision-free when multiple engagements declare a method of the same name; the orchestrator returns these strings verbatim from HandlerFor, so AR looks them up directly. Lifecycle hooks are NOT namespaced — the orchestrator hardcodes onStart / onClose — so a method name may be reused as an event handler across engagements, but only one engagement per agent may own each lifecycle hook (cef build errors on a collision).

cef typegen reads cef.config.ts (and publishes declarations) and writes .cef/generated.d.ts, populating KnownEventTypes so authors get string-literal autocompletion on @OnEvent and ctx.publish. The cef.lock.json snapshot is rewritten on every run so VCS diffs surface typegen drift.

Quickstart

pnpm add -D @cef-ai/cli
pnpm exec cef build
pnpm exec cef inspect dist/<agentId>

Programmatic API

Every subcommand has a corresponding function exported from the package root, useful from tests and scripts:

import { cefBuild, cefTypegen, cefInspect } from "@cef-ai/cli";

const build = await cefBuild({ cwd: process.cwd(), outDir: "dist" });
for (const a of build.agents) {
  console.log(a.agentId, a.bundlePath, a.bundleBytes);
}

await cefTypegen({ configPath: "./cef.config.ts" });

const inspected = await cefInspect({
  agentDir: "dist/echo",
  print: false,
});
for (const e of inspected.engagements) {
  console.log(e.id, e.handles, e.hooks, e.exposedMethods, e.missingMethods);
}

Build-time lints

cef build runs a syntactic lint pass over the agent's entry file before bundling. Failures abort the build with a single, actionable message. The rules mirror those in @cef-ai/eslint-plugin so editor warnings agree with CI failures.

• @OnEvent(...) argument must be a string literal.
• ctx.publish(t, ...) first argument must be a string literal.
• ctx.cubby("alias") argument must be a literal AND a declared alias in cef.config.ts cubbies[].alias.
• ctx.models.X member must reference a declared model alias.
• Imports must not target the banned module list (Node built-ins like fs, net, http, child_process, plus sync DB / network npm packages). Agents use the global fetch for HTTP and ctx.cubby for state; globalThis.crypto (WebCrypto) replaces node:crypto.

The full banned-module list and rationale live in agent-sdk.md §7.

Companion packages

• @cef-ai/agent-sdk — the decorators, Context, and defineAgent consumed by the agent code being built.
• @cef-ai/testing — simulator harness used by cef test once it lands.
• @cef-ai/eslint-plugin — editor-time lints that match the build-time enforcement.

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

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