@cef-ai/cli 1.5.0 → 1.7.0

package/dist/lib/widget-manifest.js

@@ -0,0 +1,91 @@
+/**
+ * Widget manifest builder (build-time tooling).
+ *
+ * `@cef-ai/widget-runtime` *reads* a `WidgetManifest` at boot but never builds
+ * one — that is the CLI's job. This module assembles the arguments for the
+ * runtime's `buildWidgetManifest` from a `cef.config.ts` widget declaration, the
+ * resolved `--env` endpoints (see `./env.ts`), and the agent's AS pubkey.
+ *
+ * Used by both `cef build` (bakes the manifest into `dist/…/widgets/<id>/`) and
+ * `cef dev` (serves it inline), so the embedded and standalone paths get an
+ * identical manifest.
+ */
+import { buildWidgetManifest, } from "@cef-ai/widget-runtime/build-tools";
+import { envConfig, resolveEnv } from "./env.js";
+/** Runtime-known widget kinds. `WidgetDecl.kind` is free-form, so unrecognized
+ *  values are dropped from the baked manifest (see below). */
+const KNOWN_KINDS = new Set([
+    "record",
+    "list",
+    "dashboard",
+    "submit",
+    "conversation",
+    "custom",
+    "composite",
+]);
+/**
+ * Build a `WidgetManifest` for one widget declaration + resolved env.
+ *
+ * Deliberately tolerant: an unknown `kind` (WidgetDecl.kind is free-form) is
+ * dropped with a warning rather than throwing, so a `cef build` never fails on
+ * a widget the runtime doesn't render as a config-driven kind — the widget can
+ * still query the cubby via `window.WidgetRuntime`.
+ */
+export function buildWidgetManifestForDecl(args) {
+    const { widget, alias } = args;
+    const env = resolveEnv(args.env);
+    const cfg = envConfig(args.env);
+    const warnings = [];
+    const asPubkey = args.asPubkey?.trim();
+    let agentId;
+    if (asPubkey) {
+        agentId = `${asPubkey}:${alias}`;
+    }
+    else {
+        agentId = alias;
+        warnings.push(`widget "${widget.id}": no --as-pubkey given — manifest.agentId is the ` +
+            `bare alias "${alias}". Cubby queries need the full "<asPubkey>:${alias}" ` +
+            `agentId; pass --as-pubkey to bake it in.`);
+    }
+    // `WidgetDecl.kind` is a free-form string; only forward it (and its config)
+    // when it maps to a runtime kind, so buildWidgetManifest's validateConfig
+    // doesn't reject an author's host-specific hint (e.g. "panel").
+    let kind;
+    let config;
+    if (widget.kind !== undefined) {
+        if (KNOWN_KINDS.has(widget.kind)) {
+            kind = widget.kind;
+            config = widget.config;
+        }
+        else {
+            warnings.push(`widget "${widget.id}": kind "${widget.kind}" is not a runtime widget ` +
+                `kind (${[...KNOWN_KINDS].join(", ")}); dropping kind/config from the ` +
+                `baked manifest (the widget still runs as a custom UI).`);
+        }
+    }
+    const manifest = buildWidgetManifest({
+        widgetId: widget.id,
+        name: widget.name ?? widget.id,
+        agentId,
+        ...(widget.cubbyAlias !== undefined ? { cubbyAlias: widget.cubbyAlias } : { cubbyAlias: "" }),
+        wallet: {
+            appId: args.walletAppId ?? process.env.CEF_WALLET_APP_ID ?? cfg.wallet.appId,
+            env: cfg.wallet.env,
+        },
+        endpoints: {
+            vault: cfg.vault,
+            gar: cfg.gar,
+            marketplace: cfg.marketplace,
+            s3GatewayAuthInfo: cfg.s3GatewayAuthInfo,
+            rpc: cfg.rpc,
+        },
+        ...(widget.queries && widget.queries.length > 0 ? { queries: widget.queries } : {}),
+        ...(widget.events && widget.events.length > 0
+            ? { events: widget.events.map((type) => ({ type })) }
+            : {}),
+        ...(kind !== undefined ? { kind } : {}),
+        ...(config !== undefined ? { config } : {}),
+    });
+    return { manifest, env, warnings };
+}
+//# sourceMappingURL=widget-manifest.js.map

package/dist/lib/widget-manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-manifest.js","sourceRoot":"","sources":["../../src/lib/widget-manifest.ts"],"names":[],"mappings":"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"}

package/dist/lib/widget-runtime-bundle.d.ts

@@ -0,0 +1,7 @@
+export declare const WIDGET_RUNTIME_BUNDLE_BASENAME = "widget-runtime.js";
+/**
+ * Absolute path to `@cef-ai/widget-runtime/dist/widget-runtime.js`, or `null`
+ * if the package (or its build output) can't be resolved.
+ */
+export declare function resolveWidgetRuntimeBundle(): string | null;
+//# sourceMappingURL=widget-runtime-bundle.d.ts.map

package/dist/lib/widget-runtime-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-runtime-bundle.d.ts","sourceRoot":"","sources":["../../src/lib/widget-runtime-bundle.ts"],"names":[],"mappings":"AAgBA,eAAO,MAAM,8BAA8B,sBAAsB,CAAC;AAElE;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,MAAM,GAAG,IAAI,CAY1D"}

package/dist/lib/widget-runtime-bundle.js

@@ -0,0 +1,31 @@
+/**
+ * Locate the built `@cef-ai/widget-runtime` IIFE bundle
+ * (`dist/widget-runtime.js`) that `cef build` vendors into each widget's dist
+ * dir and `cef dev` serves at `/widget-runtime.js`.
+ *
+ * The package's `.` export resolves to `dist/index.js`; the IIFE sits next to
+ * it as `dist/widget-runtime.js`. Resolving through `createRequire` keeps this
+ * working both in the monorepo (workspace symlink) and in a published install
+ * (real dependency).
+ */
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+const require = createRequire(import.meta.url);
+export const WIDGET_RUNTIME_BUNDLE_BASENAME = "widget-runtime.js";
+/**
+ * Absolute path to `@cef-ai/widget-runtime/dist/widget-runtime.js`, or `null`
+ * if the package (or its build output) can't be resolved.
+ */
+export function resolveWidgetRuntimeBundle() {
+    let mainEntry;
+    try {
+        mainEntry = require.resolve("@cef-ai/widget-runtime");
+    }
+    catch {
+        return null;
+    }
+    const bundle = path.join(path.dirname(mainEntry), WIDGET_RUNTIME_BUNDLE_BASENAME);
+    return fs.existsSync(bundle) ? bundle : null;
+}
+//# sourceMappingURL=widget-runtime-bundle.js.map

package/dist/lib/widget-runtime-bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-runtime-bundle.js","sourceRoot":"","sources":["../../src/lib/widget-runtime-bundle.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAE/C,MAAM,CAAC,MAAM,8BAA8B,GAAG,mBAAmB,CAAC;AAElE;;;GAGG;AACH,MAAM,UAAU,0BAA0B;IACxC,IAAI,SAAiB,CAAC;IACtB,IAAI,CAAC;QACH,SAAS,GAAG,OAAO,CAAC,OAAO,CAAC,wBAAwB,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CACtB,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,EACvB,8BAA8B,CAC/B,CAAC;IACF,OAAO,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;AAC/C,CAAC"}

package/dist/lib.d.ts

@@ -7,6 +7,10 @@ export { cefInit, detectPackageManager } from "./commands/init.js";
 export type { CefInitOptions, CefInitResult, PackageManager, } from "./commands/init.js";
 export { cefBuild } from "./commands/build.js";
 export type { CefBuildOptions, CefBuildResult } from "./commands/build.js";
+export { cefDev } from "./commands/dev.js";
+export type { CefDevOptions, CefDevHandle } from "./commands/dev.js";
+export { buildWidgetManifestForDecl } from "./lib/widget-manifest.js";
+export type { BuildWidgetManifestArgs, BuildWidgetManifestOutput, } from "./lib/widget-manifest.js";
 export { cefTypegen } from "./commands/typegen.js";
 export type { CefTypegenOptions, CefTypegenResult, } from "./commands/typegen.js";
 export { cefInspect } from "./commands/inspect.js";

package/dist/lib.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACnE,YAAY,EACV,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"lib.d.ts","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AACnE,YAAY,EACV,cAAc,EACd,aAAa,EACb,cAAc,GACf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE3E,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAErE,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AACtE,YAAY,EACV,uBAAuB,EACvB,yBAAyB,GAC1B,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEjF,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,YAAY,EACV,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAExE,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,YAAY,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAE9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,YAAY,EACV,yBAAyB,EACzB,wBAAwB,GACzB,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EACV,aAAa,EACb,gBAAgB,EAChB,yBAAyB,GAC1B,MAAM,sBAAsB,CAAC"}

package/dist/lib.js

@@ -5,6 +5,8 @@
  */
 export { cefInit, detectPackageManager } from "./commands/init.js";
 export { cefBuild } from "./commands/build.js";
+export { cefDev } from "./commands/dev.js";
+export { buildWidgetManifestForDecl } from "./lib/widget-manifest.js";
 export { cefTypegen } from "./commands/typegen.js";
 export { cefInspect } from "./commands/inspect.js";
 export { cefPublish } from "./commands/publish.js";

package/dist/lib.js.map

@@ -1 +1 @@
-{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAOnE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGnD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAM3D,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"lib.js","sourceRoot":"","sources":["../src/lib.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAOnE,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAG/C,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAG3C,OAAO,EAAE,0BAA0B,EAAE,MAAM,0BAA0B,CAAC;AAMtE,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAGnD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAMnD,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAG7C,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAGjD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAM3D,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,0BAA0B,GAC3B,MAAM,sBAAsB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cef-ai/cli",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,8 +21,9 @@
     "esbuild": "^0.21.0",
     "json-schema-to-typescript": "^14.0.0",
     "typescript": "^5.4.0",
-    "@cef-ai/agent-sdk": "1.4.0",
-    "@cef-ai/transport": "1.0.0"
+    "@cef-ai/agent-sdk": "2.0.0",
+    "@cef-ai/transport": "1.0.0",
+    "@cef-ai/widget-runtime": "0.2.0"
   },
   "optionalDependencies": {
     "@cere-ddc-sdk/ddc-client": "^2.16.1"

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

@@ -4,21 +4,56 @@ 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.
+  // One self-contained widget shipped with the agent. `cef dev` serves it
+  // locally (browser wallet connect → queries your dev vault); `cef build`
+  // bakes the manifest + runtime so the pushed widget works standalone too.
   widgets: [
     {
       id: "hello",
       name: "Hello",
-      description: "Minimal hello-world widget.",
+      description: "Lists recent messages from the history cubby.",
       cubbyAlias: "history",
+      // A "list" widget. The named query below reads the cubby; `app.js` calls
+      // `window.WidgetRuntime.query("recent")` and renders the rows.
+      kind: "list",
+      queries: [
+        {
+          id: "recent",
+          label: "Recent messages",
+          sql: "SELECT text, ts FROM messages ORDER BY ts DESC LIMIT 20",
+        },
+      ],
       dir: "./widgets/hello",
-      entry: "hello.html",
+      // 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/package.json

@@ -4,6 +4,7 @@
   "private": true,
   "type": "module",
   "scripts": {
+    "dev": "cef dev",
     "build": "cef build",
     "typegen": "cef typegen",
     "test": "vitest run",
@@ -19,5 +20,10 @@
     "@cef-ai/testing": "^1.1.9",
     "typescript": "^5.4.0",
     "vitest": "^1.5.0"
+  },
+  "pnpm": {
+    "onlyBuiltDependencies": [
+      "better-sqlite3"
+    ]
   }
 }

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

@@ -25,16 +25,34 @@ export default class HelloAgent {
 
   @OnEvent("user_message")
   async onMessage(event: Event<UserMessage>, ctx: Context) {
-    await ctx
-      .cubby("history")
-      .exec("INSERT INTO messages(id, text, ts) VALUES (?, ?, ?)", [
-        Date.now(),
-        event.payload.text,
-        event.ts,
-      ]);
-    await ctx.publish("reply", {
-      text: `hello — you said: ${event.payload.text}`,
-    });
+    // 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 {
+      // Record time = now. (The runtime hands handlers the published event
+      // verbatim — it carries an ISO `timestamp` string, not the `ts: number`
+      // the SDK `Event` type currently claims — so `event.ts` is undefined;
+      // don't bind a missing value into the NOT NULL `ts` column.)
+      const now = Date.now();
+      await ctx
+        .cubby("history")
+        .exec("INSERT INTO messages(id, text, ts) VALUES (?, ?, ?)", [
+          now,
+          text,
+          now,
+        ]);
+    } 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

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

@@ -25,4 +25,17 @@ describe("hello-world agent", () => {
       .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

@@ -3,7 +3,7 @@
     "target": "ES2022",
     "module": "NodeNext",
     "moduleResolution": "NodeNext",
-    "lib": ["ES2022"],
+    "lib": ["ES2022", "WebWorker"],
     "strict": true,
     "esModuleInterop": true,
     "skipLibCheck": true,

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

@@ -1,8 +1,118 @@
-// A minimal, self-contained widget (plain HTML + JS — no build step).
+// A real, 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";
+// It reads this agent's `history` cubby through the injected
+// `window.WidgetRuntime` and renders the rows. `window.WidgetRuntime` is
+// provided by `@cef-ai/widget-runtime`, whose <script> + manifest are baked
+// into the page head by `cef dev` (local) and `cef build` (production).
+//
+// Run it locally with:  cef dev
+//   → opens a URL; connect your Cere wallet in the browser; the widget then
+//     queries your dev vault. Publish messages (e.g. via the agent) and refresh.
+
+(function () {
+  var app = document.getElementById("app");
+
+  function el(tag, attrs, text) {
+    var node = document.createElement(tag);
+    if (attrs) for (var k in attrs) node.setAttribute(k, attrs[k]);
+    if (text != null) node.textContent = text;
+    return node;
+  }
+
+  function clear() {
+    while (app.firstChild) app.removeChild(app.firstChild);
+  }
+
+  function fmtTime(ts) {
+    var n = Number(ts);
+    if (!isFinite(n)) return String(ts);
+    // Rows store epoch millis; fall back gracefully for seconds.
+    var d = new Date(n < 1e12 ? n * 1000 : n);
+    return isNaN(d.getTime()) ? String(ts) : d.toLocaleString();
+  }
+
+  function renderHeader() {
+    app.appendChild(el("h1", null, "{{agentId}}"));
+    app.appendChild(el("p", { class: "sub" }, "Recent messages from the history cubby"));
+  }
+
+  function renderRefresh() {
+    var btn = el("button", null, "Refresh");
+    btn.addEventListener("click", function () {
+      btn.disabled = true;
+      btn.textContent = "Refreshing…";
+      load(); // re-runs the "recent" query; load() re-renders (button included)
+    });
+    app.appendChild(btn);
+  }
+
+  function renderRows(result) {
+    clear();
+    renderHeader();
+    renderRefresh();
+    var cols = result.columns || [];
+    var textIdx = cols.indexOf("text");
+    var tsIdx = cols.indexOf("ts");
+    var rows = result.rows || [];
+    if (rows.length === 0) {
+      app.appendChild(el("p", { class: "muted" }, "No messages yet."));
+      return;
+    }
+    var ul = el("ul");
+    rows.forEach(function (row) {
+      var li = el("li");
+      li.appendChild(el("div", null, textIdx >= 0 ? String(row[textIdx]) : JSON.stringify(row)));
+      if (tsIdx >= 0) li.appendChild(el("div", { class: "time" }, fmtTime(row[tsIdx])));
+      ul.appendChild(li);
+    });
+    app.appendChild(ul);
+  }
+
+  function renderConnect() {
+    clear();
+    renderHeader();
+    app.appendChild(el("p", { class: "muted" }, "Connect your account to load your messages."));
+    var btn = el("button", null, "Connect");
+    btn.addEventListener("click", function () {
+      btn.disabled = true;
+      btn.textContent = "Connecting…";
+      window.WidgetRuntime
+        .connectAgent()
+        .then(load)
+        .catch(function (err) {
+          btn.disabled = false;
+          btn.textContent = "Connect";
+          renderError(err);
+        });
+    });
+    app.appendChild(btn);
+  }
+
+  function renderError(err) {
+    clear();
+    renderHeader();
+    app.appendChild(el("p", { class: "error" }, "Error: " + (err && err.message ? err.message : String(err))));
+  }
+
+  function load() {
+    if (!window.WidgetRuntime) {
+      renderError(new Error("WidgetRuntime unavailable — open this widget via `cef dev` or the CDN link."));
+      return;
+    }
+    window.WidgetRuntime
+      .query("recent")
+      .then(renderRows)
+      .catch(function (err) {
+        // The cubby throws AgentNotConnectedError until the user connects the
+        // agent to their vault. Offer a Connect button in that case.
+        if (err && err.name === "AgentNotConnectedError") renderConnect();
+        else renderError(err);
+      });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", load, { once: true });
+  } else {
+    load();
+  }
+})();

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

@@ -0,0 +1,20 @@
+<!doctype html>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>Hello — {{agentId}}</title>
+<style>
+  body { font: 15px/1.5 system-ui, sans-serif; margin: 0; padding: 24px; color: #111; background: #fafafa; }
+  h1 { font-size: 18px; margin: 0 0 4px; }
+  .sub { color: #666; margin: 0 0 16px; }
+  ul { list-style: none; padding: 0; margin: 0; }
+  li { padding: 10px 12px; background: #fff; border: 1px solid #eee; border-radius: 8px; margin-bottom: 8px; }
+  .time { color: #888; font-size: 12px; }
+  button { font: inherit; padding: 8px 14px; border-radius: 8px; border: 1px solid #ccc; background: #fff; cursor: pointer; }
+  .muted { color: #888; }
+  .error { color: #b00020; }
+</style>
+<div id="app">Loading…</div>
+<!-- The @cef-ai/widget-runtime <script> + window.WidgetSandbox manifest are
+     injected into <head> by `cef dev` / `cef build`, so window.WidgetRuntime is
+     ready by the time app.js runs. -->
+<script src="./app.js"></script>

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

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