@cef-ai/cli

cef — build, typegen, and inspect agents from the command line. Mirrors the runtime contract: bundles emit globalThis.__cefAgent, manifests carry the routing table the runtime 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 (IIFE footer), 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 methods exposed on __cefAgent plus any missing routing targets. | | 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 assigns an instance to globalThis.__cefAgent
    manifest.json  # AgentManifest body (per prototype.md) — bundle is also
                   # embedded inline; identity / signature fields are blank
                   # until `cef publish` signs and uploads.

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,
});
console.log(inspected.exposedMethods, inspected.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 call ctx.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.