@cef-ai/cli 1.4.0 → 1.6.0

package/templates/hello-world/AGENTS.md

@@ -0,0 +1,41 @@
+# {{projectName}} — agent context
+
+This is a **CEF agent** project. Agents are authored with `@cef-ai/agent-sdk`,
+built/shipped with the `cef` CLI, and run on the Cere Agent Runtime.
+
+## Dev loop
+
+- `pnpm test` — run the agent test (`@cef-ai/testing`).
+- `pnpm run build` — `cef build`: lint + bundle to `dist/<agentId>/`.
+- `pnpm run push` — `cef push`: upload bundle + widgets to DDC. Needs a DDC bucket id,
+  a **registry access token minted in the ROC UI** (`--access-token` / `$CEF_DDC_ACCESS_TOKEN`),
+  and your AS pubkey (`--as-pubkey`) — both from ROC.
+- `pnpm run deploy` — `cef deploy`: apply the `deployments/` folder to make a
+  version live/testable (incl. sandbox). Needs the platform `--endpoint`
+  (defaults to dev) + AS pubkey. **This — not publish — is what makes an agent run.**
+- `pnpm run publish` — `cef publish`: **optional, last.** Lists the card in the
+  marketplace for discovery (needs AS credentials). Skip for debug/test.
+
+## Structure
+
+- `cef.config.ts` — declares id, cubbies, widgets.
+- `src/agent.ts` — default-exported class; `@Engagement`, `@OnEvent`, `@OnStart`, `@OnClose`.
+- `migrations/history/*.sql` — schema for the `history` cubby (used via `ctx.cubby`).
+- `widgets/hello/` — a self-contained static widget.
+- `deployments/*.jsonc` — deployment records (one per file, filename = name)
+  applied by `cef deploy`; `default.jsonc` is the required catch-all. `targeting`
+  (CEL over `vault.*`/`event.type`) + `priority`/`weight` express audiences / A-B.
+- `test/agent.test.ts` — `testAgent` → dispatch an event → assert output.
+
+## Runtime constraints (important)
+
+- No Node built-ins (`fs`, `net`, `http`, `child_process`, …). Use the global
+  `fetch` for HTTP and `ctx.cubby` for state.
+- Use `globalThis.crypto` (WebCrypto), not `node:crypto`.
+- `@OnEvent("...")` and `ctx.publish("...")` take **string literals**.
+- `ctx.cubby("alias")` must reference a cubby declared in `cef.config.ts`.
+
+## Deeper guidance
+
+The full authoring playbook lives in the `cef` Claude Code plugin
+(`CEF-AI/cef-plugins`) — see `.claude/settings.json`, which auto-wires it.

package/templates/hello-world/CLAUDE.md

@@ -0,0 +1,9 @@
+@AGENTS.md
+
+## Claude Code notes
+
+- This project auto-wires the **`cef`** authoring plugin via
+  `.claude/settings.json`. When available, the `cef:develop` skill (authoring)
+  and `cef:deploy` skill (build → push → deploy) load automatically.
+- If the plugin isn't installed, add it once:
+  `/plugin marketplace add CEF-AI/cef-plugins` then `/plugin install cef@cef`.

package/templates/hello-world/README.md

@@ -0,0 +1,55 @@
+# {{projectName}}
+
+A hello-world **CEF agent** scaffolded by `cef init`. It has one engagement,
+one cubby (SQLite state), one widget, and a passing test.
+
+## Layout
+
+- `cef.config.ts` — agent id, cubbies, widgets (read by the `cef` CLI).
+- `src/agent.ts` — the agent class (`@Engagement` / `@OnEvent` / lifecycle).
+- `migrations/history/` — SQL migrations for the `history` cubby.
+- `widgets/hello/` — a self-contained widget.
+- `deployments/` — deployment records (which version runs for which audience),
+  applied by `cef deploy`. `default.jsonc` is the required catch-all.
+- `test/agent.test.ts` — a `@cef-ai/testing` test.
+
+## Develop
+
+```sh
+pnpm test          # run the agent test
+pnpm run build     # cef build → dist/<agentId>/{bundle.js,manifest.json}
+```
+
+## Ship (build → push → deploy)
+
+Each step and the external inputs it needs:
+
+1. `pnpm run build` — no external inputs.
+2. `pnpm run push` — uploads the bundle + widgets to DDC. Needs a **DDC bucket
+   id**, a **registry access token you mint in the ROC UI** (ROC → your Agent
+   Service → **Access** → generate token), and your **AS pubkey** (also shown
+   in ROC):
+   `cef push --bucket <id> --access-token <token> --as-pubkey <hex>`
+   (or set `$CEF_DDC_ACCESS_TOKEN`; see `cef push --help`).
+3. `pnpm run deploy` — **makes a version live so you can run and test the agent**
+   (including in a sandbox). Applies the `deployments/` folder; edit those files
+   to target audiences or run A/B splits. Needs the platform `--endpoint`
+   (defaults to dev; `$CEF_ENDPOINT` to override) + your AS pubkey.
+4. `pnpm run publish` — **optional, and last.** Lists the agent's card in the
+   marketplace for discovery (needs your **AS Ed25519 credentials** —
+   `cef keypair generate` if you don't have them). Skip it for debug/test/sandbox;
+   an agent runs because it's *deployed*, not because it's published.
+
+## AI-assisted development (Claude Code)
+
+This project auto-wires the **`cef`** authoring plugin via
+`.claude/settings.json` — trust the folder and Claude Code installs it and
+keeps it updated. To install it manually / at user scope:
+
+```
+/plugin marketplace add CEF-AI/cef-plugins
+/plugin install cef@cef
+```
+
+Then just ask Claude to help build the agent — the `cef:develop` skill loads
+automatically; `cef:deploy` walks you through shipping.

package/templates/hello-world/cef.config.ts

@@ -0,0 +1,47 @@
+import { defineAgent } from "@cef-ai/agent-sdk/config";
+
+export default defineAgent({
+  id: "{{agentId}}",
+  version: "0.1.0",
+  entry: "./src/agent.ts",
+  // Terminate an idle Job after 30s (default is "30m"). Fine for a test agent;
+  // raise it for long-lived / real-time agents.
+  idleTimeout: "30s",
+  card: {
+    name: "{{agentId}}",
+    description: "A hello-world CEF agent scaffolded by `cef init`.",
+  },
+  // One cubby (SQLite) for durable per-stream state.
+  cubbies: [{ alias: "history", migrations: "./migrations/history" }],
+  // One self-contained widget shipped with the agent.
+  widgets: [
+    {
+      id: "hello",
+      name: "Hello",
+      description: "Minimal hello-world widget.",
+      cubbyAlias: "history",
+      dir: "./widgets/hello",
+      // index.html so the CDN serves it at the widget's directory URL
+      // (…/widgets/hello) without naming the file.
+      entry: "index.html",
+    },
+  ],
+  // Schemas for events this agent owns (handled + published). `cef build` folds
+  // these into the manifest so the platform and any peer agent that imports
+  // this one get the event contract. (Note: `cef typegen` currently types only
+  // *peer* events locally — it does not yet type your own events from these.)
+  eventSchemas: {
+    user_message: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+      additionalProperties: false,
+    },
+    reply: {
+      type: "object",
+      properties: { text: { type: "string" } },
+      required: ["text"],
+      additionalProperties: false,
+    },
+  },
+});

package/templates/hello-world/claude/settings.json

@@ -0,0 +1,23 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(cef build)",
+      "Bash(cef typegen)",
+      "Bash(cef inspect:*)",
+      "Bash(vitest run)",
+      "Bash(pnpm test)",
+      "Bash(pnpm run build)",
+      "Bash(git status)",
+      "Bash(git diff:*)"
+    ]
+  },
+  "extraKnownMarketplaces": {
+    "cef": {
+      "source": { "source": "github", "repo": "CEF-AI/cef-plugins" },
+      "autoUpdate": true
+    }
+  },
+  "enabledPlugins": {
+    "cef@cef": true
+  }
+}

package/templates/hello-world/deployments/default.jsonc

@@ -0,0 +1,9 @@
+// The mandatory catch-all deployment. Exactly one file must have empty
+// targeting; a HIGH priority number keeps it the lowest-priority fallthrough,
+// so more specific deployments you add later win for their audience.
+{
+  "priority": 99,
+  "targeting": "", // empty => always eligible (the one required default)
+  "version": "latest", // simplest "go live"; pin a semver for production
+  "weight": 1
+}

package/templates/hello-world/deployments/sandbox-canary.jsonc

@@ -0,0 +1,12 @@
+// Example audience deployment: only sandbox vaults get this pinned build;
+// everyone else falls through to default.jsonc. Edit or delete freely.
+//
+// targeting is a CEL expression over vault.id / vault.scope / event.type.
+// Among matching deployments the LOWEST priority wins; within a tier, traffic
+// splits by weight (that's how you run an A/B test).
+{
+  "priority": 10, // lower than the default (99) => wins for matching vaults
+  "targeting": "vault.scope == 'sandbox'",
+  "version": "0.1.0",
+  "weight": 1
+}

package/templates/hello-world/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.cef/

package/templates/hello-world/migrations/history/001-init.sql

@@ -0,0 +1,5 @@
+CREATE TABLE messages (
+  id   INTEGER PRIMARY KEY,
+  text TEXT NOT NULL,
+  ts   INTEGER NOT NULL
+);

package/templates/hello-world/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "build": "cef build",
+    "typegen": "cef typegen",
+    "test": "vitest run",
+    "push": "cef push",
+    "deploy": "cef deploy",
+    "publish": "cef publish"
+  },
+  "dependencies": {
+    "@cef-ai/agent-sdk": "^1.4.0"
+  },
+  "devDependencies": {
+    "@cef-ai/cli": "^1.4.0",
+    "@cef-ai/testing": "^1.1.9",
+    "typescript": "^5.4.0",
+    "vitest": "^1.5.0"
+  }
+}

package/templates/hello-world/src/agent.ts

@@ -0,0 +1,57 @@
+import {
+  Engagement,
+  OnEvent,
+  OnStart,
+  OnClose,
+  type Context,
+  type Event,
+} from "@cef-ai/agent-sdk";
+
+interface UserMessage {
+  text: string;
+}
+
+@Engagement({
+  id: "default",
+  goal: "reply to a user message and remember it",
+})
+export default class HelloAgent {
+  @OnStart
+  async onStart() {
+    // Plain logging goes to the sandbox console; `ctx` is only for
+    // CEF-specific calls (cubby / publish / models / close).
+    console.info("hello-world agent started");
+  }
+
+  @OnEvent("user_message")
+  async onMessage(event: Event<UserMessage>, ctx: Context) {
+    // Never assume a well-formed event. A missing/empty payload must NOT throw
+    // — an unhandled error in a handler can leave the Job stuck. Guard first.
+    const text =
+      typeof event.payload?.text === "string" ? event.payload.text.trim() : "";
+    if (!text) {
+      await ctx.publish("reply", { text: 'no text received — send { "text": "..." }' });
+      return;
+    }
+
+    try {
+      await ctx
+        .cubby("history")
+        .exec("INSERT INTO messages(id, text, ts) VALUES (?, ?, ?)", [
+          Date.now(),
+          text,
+          event.ts,
+        ]);
+    } catch (err) {
+      // A storage hiccup shouldn't crash the handler; log and still reply.
+      console.error("failed to persist message", err);
+    }
+
+    await ctx.publish("reply", { text: `hello — you said: ${text}` });
+  }
+
+  @OnClose
+  async onClose(_ctx: Context, reason: string) {
+    console.info("hello-world agent closing", { reason });
+  }
+}

package/templates/hello-world/test/agent.test.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect, afterEach } from "vitest";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { testAgent, type TestHarness } from "@cef-ai/testing";
+import HelloAgent from "../src/agent.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const HISTORY_MIGRATIONS = path.resolve(__dirname, "../migrations/history");
+
+describe("hello-world agent", () => {
+  let h: TestHarness | undefined;
+  afterEach(() => h?.dispose());
+
+  it("replies to user_message and persists to history", async () => {
+    h = testAgent(HelloAgent, {
+      cubbies: [{ alias: "history", migrations: HISTORY_MIGRATIONS }],
+    });
+    const events = await h.dispatch({
+      type: "user_message",
+      payload: { text: "hi" },
+    });
+    expect(events.map((e) => e.type)).toContain("reply");
+    const rows = await h
+      .cubby("history")
+      .query<{ text: string }>("SELECT text FROM messages");
+    expect(rows.map((r) => r.text)).toEqual(["hi"]);
+  });
+
+  it("handles an empty payload without throwing or persisting", async () => {
+    h = testAgent(HelloAgent, {
+      cubbies: [{ alias: "history", migrations: HISTORY_MIGRATIONS }],
+    });
+    // An event with no `text` must not crash the handler.
+    const events = await h.dispatch({ type: "user_message", payload: {} });
+    expect(events.map((e) => e.type)).toContain("reply");
+    const rows = await h
+      .cubby("history")
+      .query<{ text: string }>("SELECT text FROM messages");
+    expect(rows).toEqual([]); // nothing persisted for an empty payload
+  });
+});

package/templates/hello-world/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022", "WebWorker"],
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true,
+    "resolveJsonModule": true,
+    "experimentalDecorators": true,
+    "emitDecoratorMetadata": false,
+    "noEmit": true
+  },
+  "include": ["src/**/*", "test/**/*", "cef.config.ts"],
+  "exclude": ["dist", ".cef", "node_modules"]
+}

package/templates/hello-world/widgets/hello/app.js

@@ -0,0 +1,8 @@
+// A minimal, self-contained widget (plain HTML + JS — no build step).
+//
+// When the @cef-ai/widget-runtime ships, you can read this agent's cubby
+// and publish events from here, e.g.:
+//   const { rows } = await window.WidgetRuntime.query("SELECT text FROM messages");
+//   await window.WidgetRuntime.publish("user_message", { text: "hi" });
+document.getElementById("root").textContent =
+  "hello from {{agentId}} — this is your widget";

package/templates/hello-world/widgets/hello/index.html

@@ -0,0 +1,5 @@
+<!doctype html>
+<meta charset="utf-8" />
+<title>Hello — {{agentId}}</title>
+<div id="root"></div>
+<script src="./app.js"></script>