@cosmicdrift/kumiko-framework 0.235.2 → 0.235.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.235.2",
+  "version": "0.235.3",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -198,7 +198,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.235.2",
+    "@cosmicdrift/kumiko-types": "0.235.3",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -214,7 +214,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-dispatcher-live": "0.235.2",
+    "@cosmicdrift/kumiko-dispatcher-live": "0.235.3",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/__tests__/upgrade-cli.test.ts

@@ -507,3 +507,88 @@ describe("upgrade command — --apply", () => {
     expect(existsSync(join(target, ".kumiko/upgrade-state.json"))).toBe(true);
   });
 });
+
+// Bug: without --from, the filter baseline used to be the installed
+// version, not the recorded marker — a bare `--apply` always reported
+// "Nothing new" and bootstrapped the marker onto the installed version,
+// hiding changelog entries the marker never actually saw (fw#2371-style).
+describe("upgrade command — filter baseline is the marker, not the installed version", () => {
+  const marker = (version: string): string =>
+    JSON.stringify({ version, appliedAt: "2024-01-01T00:00:00Z", codemods: [] });
+
+  test("bare --apply with a marker below installed: the entry between them is pending, not 'Nothing new'", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+      "packages/bundled-features/package.json": JSON.stringify({ version: "0.190.0" }),
+      ".kumiko/upgrade-state.json": marker("0.160.0"),
+      "legacy-test-helper.ts": LEGACY_IMPORT_FIXTURE,
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--apply"], cwd, spy.out, { repoRoot: REAL_REPO_ROOT });
+
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).not.toContain("Nothing new since your version");
+    const rewritten = readFileSync(join(cwd, "legacy-test-helper.ts"), "utf-8");
+    expect(rewritten).toContain('from "@cosmicdrift/kumiko-framework/testing"');
+    const updatedMarker = JSON.parse(
+      readFileSync(join(cwd, ".kumiko/upgrade-state.json"), "utf-8"),
+    );
+    expect(updatedMarker.version).toBe("0.167.0");
+  });
+
+  test("bare --apply with a manual breaking change: marker is not stamped to installed, pendingManual records it", async () => {
+    const manualEntry = { version: "0.185.0", type: "breaking", title: "manual breaking change" };
+    const fixEntry = { version: "0.188.0", type: "fix", title: "later fix" };
+    const cwd = tmp({
+      "packages/framework/src/changes.json": JSON.stringify([manualEntry, fixEntry]),
+      "packages/bundled-features/package.json": JSON.stringify({ version: "0.195.0" }),
+      ".kumiko/upgrade-state.json": marker("0.180.0"),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--apply"], cwd, spy.out, { repoRoot: REAL_REPO_ROOT });
+
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("no codemod, manual migration required");
+    const updatedMarker = JSON.parse(
+      readFileSync(join(cwd, ".kumiko/upgrade-state.json"), "utf-8"),
+    );
+    // Stamped to the trailing non-breaking entry's version (0.188.0), not
+    // blindly hoisted to the installed version (0.195.0) — proof both
+    // entries were actually seen and run through markerVersionForPending,
+    // rather than filtered out entirely by a too-high baseline.
+    expect(updatedMarker.version).toBe("0.188.0");
+    expect(updatedMarker.version).not.toBe("0.195.0");
+  });
+
+  test("bare --apply with no marker (bootstrap): behaves as before, marker is written at the installed version", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": breakingEntryWithCodemod(REAL_CODEMOD),
+      "packages/framework/package.json": JSON.stringify({ version: "0.170.0" }),
+    });
+    const spy = makeSpyOutput();
+
+    const exit = await runUpgradeCli(["--apply"], cwd, spy.out, { repoRoot: REAL_REPO_ROOT });
+
+    expect(exit).toBe(0);
+    expect(spy.logs.join("\n")).toContain("Nothing new since your version");
+    const updatedMarker = JSON.parse(
+      readFileSync(join(cwd, ".kumiko/upgrade-state.json"), "utf-8"),
+    );
+    expect(updatedMarker.version).toBe("0.170.0");
+  });
+
+  test("--from wins over an existing marker", async () => {
+    const cwd = tmp({
+      "packages/framework/src/changes.json": JSON.stringify([
+        { version: "0.175.0", type: "fix", title: "explicit-from-test-entry" },
+      ]),
+      ".kumiko/upgrade-state.json": marker("0.180.0"),
+    });
+
+    const result = await runJson(cwd, "0.170.0");
+
+    expect(result.pending.map((e) => e.title)).toEqual(["explicit-from-test-entry"]);
+  });
+});

package/src/db/queries/event-consumer.ts

@@ -57,6 +57,33 @@ export async function markConsumerProcessing(
   );
 }
 
+// Best-effort record of an infra-level pass failure (event-dispatcher.ts's
+// processConsumer catch) — called OUTSIDE the transaction that just rolled
+// back, since that tx's own markProcessing/updateConsumerDeliveryOutcome
+// writes never committed. Must NOT touch "attempts": that counter is
+// deliverEvents' poison-pill/dead-letter budget, incremented only on a
+// handler throw inside an actual delivery pass. Spending it here would let
+// repeated infra blips (the exact case this backoff exists for) dead-letter
+// the consumer on the next real handler failure instead of after
+// maxAttempts. Visibility is covered by last_error, updated_at, and the
+// caller's console.error — status and the cursor are left as-is too, since
+// we don't know at this point whether the consumer should be "dead" (that's
+// the deliverEvents/maxAttempts contract, which never ran this pass).
+export async function recordConsumerPassFailure(
+  db: AnyDb,
+  name: string,
+  instanceId: string,
+  errorMessage: string,
+): Promise<void> {
+  await asRawClient(db).unsafe(
+    `UPDATE "kumiko_event_consumers" SET
+       "last_error" = $1,
+       "updated_at" = now()
+     WHERE "name" = $2 AND "instance_id" = $3`,
+    [errorMessage, name, instanceId],
+  );
+}
+
 export type ConsumerDeliveryOutcome = {
   readonly cursor: bigint;
   readonly attempts: number;

package/src/engine/__tests__/build-app-schema.test.ts

@@ -432,6 +432,7 @@ describe("buildAppSchema", () => {
       "allowPlaintext", // PII-audit reason string, not a renderer concern
       "lookupable", // blind-index equality lookup, server-side query concern
       "subjectRef", // GDPR-hook-coverage marker, not a renderer concern
+      "description", // AI-agent manifest hint, never rendered to the user
     ] as const;
 
     type Classified = (typeof FORWARDED_KEYS)[number] | (typeof SERVER_ONLY_KEYS)[number];
@@ -459,6 +460,7 @@ describe("buildAppSchema", () => {
           allowPlaintext: "is_business_data",
           lookupable: true,
           subjectRef: true,
+          description: "tags for the thing",
         },
       },
     } as unknown as EntityDefinition;

package/src/engine/access.ts

@@ -12,7 +12,10 @@ import type { AccessRule, SessionUser } from "./types";
 // list `anonymous` in `roles` (e.g. `roles: ["anonymous", "customer"]`).
 // Without this guard, enabling `anonymousAccess` on the server would silently
 // turn every existing `openToAll: true` handler into a public endpoint.
-export function hasAccess(user: SessionUser, access: AccessRule | undefined): boolean {
+export function hasAccess(
+  user: Pick<SessionUser, "roles">,
+  access: AccessRule | undefined,
+): boolean {
   if (!access) return false;
   if ("openToAll" in access) {
     if (access.openToAll !== true) return false;

package/src/engine/feature-ast/__tests__/parse.test.ts

@@ -1588,6 +1588,63 @@ defineFeature("f", (r) => {
     });
   });
 
+  test("object form: description + agent hints are extracted", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler({
+    name: "task:approve",
+    schema: z.object({ id: z.string() }),
+    handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
+    description: "Approves a pending task.",
+    agent: { expose: true, risk: "high" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:approve",
+      description: "Approves a pending task.",
+      agent: { expose: true, risk: "high" },
+    });
+  });
+
+  test("object form: an unknown agent.risk value is dropped, not passed through", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler({
+    name: "task:approve",
+    schema: z.object({ id: z.string() }),
+    handler: async (event, ctx) => ({ isSuccess: true, data: {} }),
+    agent: { expose: true, risk: "bogus" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      agent: { expose: true },
+    });
+    expect((result.patterns[0] as { agent?: { risk?: unknown } }).agent?.risk).toBeUndefined();
+  });
+
+  test("4-argument form: description + agent hints are read from the options object", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.writeHandler("task:create", z.object({ title: z.string() }), async (event, ctx) => {
+    return { isSuccess: true, data: {} };
+  }, { description: "Creates a task.", agent: { risk: "mid" } });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "writeHandler",
+      handlerName: "task:create",
+      description: "Creates a task.",
+      agent: { risk: "mid" },
+    });
+  });
+
   test("resolves a same-file identifier arg to its object-literal form (#1007)", () => {
     const result = parseInline(`
 const h = {
@@ -1636,6 +1693,27 @@ defineFeature("f", (r) => {
       handlerName: "task:list",
     });
   });
+
+  test("object form: description + agent hints are extracted", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.queryHandler({
+    name: "task:list",
+    schema: z.object({}),
+    handler: async (q, ctx) => [],
+    description: "Lists tasks.",
+    agent: { risk: "low" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).toMatchObject({
+      kind: "queryHandler",
+      handlerName: "task:list",
+      description: "Lists tasks.",
+      agent: { risk: "low" },
+    });
+  });
 });
 
 describe("extractStreamHandler", () => {
@@ -1688,6 +1766,23 @@ defineFeature("f", (r) => {
     });
     expect(result.errors).toEqual([]);
   });
+
+  test("description/agent are NOT part of StreamHandlerPattern's runtime shape", () => {
+    const result = parseInline(`
+defineFeature("f", (r) => {
+  r.streamHandler({
+    name: "chat:complete",
+    schema: z.object({ prompt: z.string() }),
+    handler: async function* (input, ctx) { yield "token"; },
+    description: "Should be ignored for streamHandler.",
+    agent: { risk: "high" },
+  });
+});
+`);
+
+    expect(result.patterns[0]).not.toHaveProperty("description");
+    expect(result.patterns[0]).not.toHaveProperty("agent");
+  });
 });
 
 describe("extractJob", () => {

package/src/engine/feature-ast/__tests__/render-roundtrip.test.ts

@@ -201,14 +201,14 @@ defineFeature("workflow", (r) => {
     async (event, ctx) => {
       return { isSuccess: true, data: { id: "x" } };
     },
-    { access: { roles: ["user"] } },
+    { access: { roles: ["user"] }, description: "Creates a step.", agent: { expose: true, risk: "high" } },
   );
 
   r.queryHandler(
     "step:list",
     z.object({}),
     async (q, ctx) => [],
-    { access: { openToAll: true } },
+    { access: { openToAll: true }, description: "Lists steps.", agent: { risk: "low" } },
   );
 
   r.streamHandler(

package/src/engine/feature-ast/extractors/handlers.ts

@@ -1,6 +1,11 @@
-import type { CallExpression, Node, SourceFile } from "ts-morph";
+import type { CallExpression, Node, ObjectLiteralExpression, SourceFile } from "ts-morph";
 import { SyntaxKind } from "ts-morph";
-import type { AccessRule, RateLimitOption } from "../../types/handlers";
+import type {
+  AccessRule,
+  AgentHandlerHints,
+  AgentRisk,
+  RateLimitOption,
+} from "../../types/handlers";
 import type { QueryHandlerPattern, StreamHandlerPattern, WriteHandlerPattern } from "../patterns";
 import type { SourceLocation } from "../source-location";
 import { sourceLocationFromNode } from "../source-location";
@@ -23,10 +28,78 @@ export type ParsedHandlerCall = {
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
 };
 
+const AGENT_RISK_VALUES: readonly AgentRisk[] = ["low", "mid", "high"];
+
+function isAgentRisk(value: unknown): value is AgentRisk {
+  return typeof value === "string" && (AGENT_RISK_VALUES as readonly string[]).includes(value);
+}
+
+export function readOptionalAgentHints(value: unknown): AgentHandlerHints | undefined {
+  if (!isPlainObject(value)) return undefined;
+  const expose = typeof value["expose"] === "boolean" ? value["expose"] : undefined;
+  const risk = isAgentRisk(value["risk"]) ? value["risk"] : undefined;
+  if (expose === undefined && risk === undefined) return undefined;
+  return {
+    ...(expose !== undefined && { expose }),
+    ...(risk !== undefined && { risk }),
+  };
+}
+
+/**
+ * Reads the two AI-agent-manifest slots (`description`, `agent`) off an
+ * object-form handler-call literal. Factored out of parseHandlerCall to
+ * keep that function's branching flat — both fields are optional and
+ * independent of the rest of the header (access/rateLimit/schema/handler).
+ */
+function readDescriptionAndAgent(
+  obj: ObjectLiteralExpression,
+): Pick<ParsedHandlerCall, "description" | "agent"> {
+  const descriptionLiteral = obj
+    .getProperty("description")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer()
+    ?.asKind(SyntaxKind.StringLiteral);
+  const agentInit = obj
+    .getProperty("agent")
+    ?.asKind(SyntaxKind.PropertyAssignment)
+    ?.getInitializer();
+  const agent = agentInit ? readOptionalAgentHints(readDataLiteralNode(agentInit)) : undefined;
+  return {
+    ...(descriptionLiteral !== undefined && { description: descriptionLiteral.getLiteralValue() }),
+    ...(agent !== undefined && { agent }),
+  };
+}
+
+/**
+ * Reads `access`/`rateLimit`/`description`/`agent` off the positional
+ * 4th-argument options object (the inline-authoring form). Mirrors
+ * readDescriptionAndAgent's role for the object-form branch — keeping
+ * parseHandlerCall's positional branch to a single assignment instead of
+ * four independent mutable locals.
+ */
+function readOptionsFields(
+  options: unknown,
+): Pick<ParsedHandlerCall, "access" | "rateLimit" | "description" | "agent"> {
+  if (!isPlainObject(options)) return {};
+  const access = readOptionalAccessRule(options["access"]);
+  const rateLimit = readOptionalRateLimit(options["rateLimit"]);
+  const description =
+    typeof options["description"] === "string" ? options["description"] : undefined;
+  const agent = readOptionalAgentHints(options["agent"]);
+  return {
+    ...(access !== undefined && { access }),
+    ...(description !== undefined && { description }),
+    ...(agent !== undefined && { agent }),
+    ...(rateLimit !== undefined && { rateLimit }),
+  };
+}
+
 /**
  * Resolves an argument standing in for a handler-call's object-form body:
  * either it's already an object literal, or a bare identifier declared
@@ -113,6 +186,7 @@ export function parseHandlerCall(
     const rateLimit = rateLimitInit
       ? readOptionalRateLimit(readDataLiteralNode(rateLimitInit))
       : undefined;
+    const { description, agent } = readDescriptionAndAgent(obj);
     const skip = readBooleanProperty(obj, "unsafeSkipTransitionGuard");
     return ok({
       source: sourceLocationFromNode(call, sourceFile),
@@ -120,6 +194,8 @@ export function parseHandlerCall(
       schemaSource: sourceLocationFromNode(schemaInit, sourceFile),
       handlerBody: sourceLocationFromNode(fn, sourceFile),
       ...(access !== undefined && { access }),
+      ...(description !== undefined && { description }),
+      ...(agent !== undefined && { agent }),
       ...(rateLimit !== undefined && { rateLimit }),
       ...(skip === true && { unsafeSkipTransitionGuard: true }),
     });
@@ -168,22 +244,13 @@ export function parseHandlerCall(
     );
   }
   const optionsArg = args[3];
-  let access: AccessRule | undefined;
-  let rateLimit: RateLimitOption | undefined;
-  if (optionsArg) {
-    const options = readDataLiteralNode(optionsArg);
-    if (isPlainObject(options)) {
-      access = readOptionalAccessRule(options["access"]);
-      rateLimit = readOptionalRateLimit(options["rateLimit"]);
-    }
-  }
+  const optionsFields = optionsArg ? readOptionsFields(readDataLiteralNode(optionsArg)) : {};
   return ok({
     source: sourceLocationFromNode(call, sourceFile),
     handlerName,
     schemaSource: sourceLocationFromNode(schemaArg, sourceFile),
     handlerBody: sourceLocationFromNode(fn, sourceFile),
-    ...(access !== undefined && { access }),
-    ...(rateLimit !== undefined && { rateLimit }),
+    ...optionsFields,
   });
 }
 
@@ -200,6 +267,8 @@ export function extractWriteHandler(
     schemaSource: parsed.pattern.schemaSource,
     handlerBody: parsed.pattern.handlerBody,
     ...(parsed.pattern.access !== undefined && { access: parsed.pattern.access }),
+    ...(parsed.pattern.description !== undefined && { description: parsed.pattern.description }),
+    ...(parsed.pattern.agent !== undefined && { agent: parsed.pattern.agent }),
     ...(parsed.pattern.rateLimit !== undefined && { rateLimit: parsed.pattern.rateLimit }),
     ...(parsed.pattern.unsafeSkipTransitionGuard === true && { unsafeSkipTransitionGuard: true }),
   });
@@ -222,9 +291,17 @@ export function extractQueryHandler(
 ): ExtractOutput<QueryHandlerPattern> {
   const parsed = parseHandlerCall(call, sourceFile, "queryHandler");
   if (parsed.kind === "error") return parsed;
-  return ok({ kind: "queryHandler", ...readHandlerFields(parsed) });
+  return ok({
+    kind: "queryHandler",
+    ...readHandlerFields(parsed),
+    ...(parsed.pattern.description !== undefined && { description: parsed.pattern.description }),
+    ...(parsed.pattern.agent !== undefined && { agent: parsed.pattern.agent }),
+  });
 }
 
+// streamHandler shares parseHandlerCall with writeHandler/queryHandler, but
+// StreamHandlerDef carries neither `description` nor `agent` at runtime —
+// readHandlerFields intentionally does not forward them here.
 export function extractStreamHandler(
   call: CallExpression,
   sourceFile: SourceFile,

package/src/engine/feature-ast/patterns.ts

@@ -66,7 +66,12 @@ import type {
 } from "../types/config";
 import type { MetricOptions, SecretOptions } from "../types/feature";
 import type { EntityDefinition } from "../types/fields";
-import type { AccessRule, ClaimKeyType, RateLimitOption } from "../types/handlers";
+import type {
+  AccessRule,
+  AgentHandlerHints,
+  ClaimKeyType,
+  RateLimitOption,
+} from "../types/handlers";
 import type { HookPhase } from "../types/hooks";
 import type { HttpRouteMethod } from "../types/http-route";
 import type { NavDefinition } from "../types/nav";
@@ -87,6 +92,10 @@ import type { SourceLocation } from "./source-location";
 // framework derives the aggregate table, CRUD events, and the read-side
 // projection from it at boot. Fully static — the Designer renders it as a
 // form, the AI patcher edits it as pure data.
+//
+// Carries `definition.description` transitively (no dedicated field here):
+// that prose feeds the AI-agent manifest output. An entity without it still
+// works, but the agent has nothing to say about it in the tool catalogue.
 export type EntityPattern = {
   readonly kind: "entity";
   readonly source: SourceLocation;
@@ -333,6 +342,10 @@ export type ScreenOpaqueMarker = typeof SCREEN_OPAQUE_MARKER;
 // entity-bound screens reference a registered entity and that column/form
 // field refs name real fields. Closure-valued props (visibility conditions,
 // row-action payloads, custom renderers) stay opaque — see `opaqueProps`.
+//
+// Carries `definition.description` transitively (no dedicated field here):
+// that prose feeds the AI-agent manifest output. A `type: "custom"` screen
+// without it renders a `renderer` closure the agent has no way to explain.
 export type ScreenPattern = {
   readonly kind: "screen";
   readonly source: SourceLocation;
@@ -346,6 +359,13 @@ export type ScreenPattern = {
 // `r.writeHandler(...)` — registers a command handler: name, Zod input
 // schema, handler closure, plus optional `access` and `rateLimit` rules.
 // The header is declarative; schema and body stay opaque source spans.
+//
+// `description` is the prose the AI agent sees as this handler's tool
+// description in the manifest — without it, the handler stays invisible to
+// the agent (fail-closed: no description, no exposure). `agent.expose`
+// overrides that derivation explicitly (force-show or force-hide);
+// `agent.risk` ("low" | "mid" | "high") classifies the action's blast
+// radius, defaulting to "mid" for a write handler.
 export type WriteHandlerPattern = {
   readonly kind: "writeHandler";
   readonly source: SourceLocation;
@@ -364,6 +384,8 @@ export type WriteHandlerPattern = {
   // generates raw TypeScript, no DSL interpretation.
   readonly handlerBody?: SourceLocation;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
   readonly unsafeSkipTransitionGuard?: boolean;
 };
@@ -372,6 +394,12 @@ export type WriteHandlerPattern = {
 // handler closure, plus optional `access` and `rateLimit` rules. Read-side
 // counterpart of `r.writeHandler` with the same header/body split. Opaque
 // (no handlerName) for the same single-reference case as WriteHandlerPattern.
+//
+// `description` and `agent` mirror WriteHandlerPattern: `description` is the
+// prose the AI agent shows as this query's tool description (absent →
+// invisible to the agent), `agent.expose` overrides that, and `agent.risk`
+// defaults to "low" for a query handler (reads carry less blast radius than
+// writes).
 export type QueryHandlerPattern = {
   readonly kind: "queryHandler";
   readonly source: SourceLocation;
@@ -379,6 +407,8 @@ export type QueryHandlerPattern = {
   readonly schemaSource?: SourceLocation;
   readonly handlerBody?: SourceLocation;
   readonly access?: AccessRule;
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
   readonly rateLimit?: RateLimitOption;
 };
 

package/src/engine/feature-ast/render.ts

@@ -404,6 +404,8 @@ function renderWriteHandler(p: WriteHandlerPattern): string {
   lines.push(`  schema: ${reindentBody(p.schemaSource?.raw ?? "", PATTERN_INDENT)},`);
   lines.push(`  handler: ${reindentBody(p.handlerBody?.raw ?? "", PATTERN_INDENT)},`);
   if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
+  if (p.description !== undefined) lines.push(`  description: ${JSON.stringify(p.description)},`);
+  if (p.agent !== undefined) lines.push(`  agent: ${renderValue(p.agent)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
   if (p.unsafeSkipTransitionGuard === true) lines.push("  unsafeSkipTransitionGuard: true,");
   lines.push("});");
@@ -417,6 +419,8 @@ function renderQueryHandler(p: QueryHandlerPattern): string {
   lines.push(`  schema: ${reindentBody(p.schemaSource?.raw ?? "", PATTERN_INDENT)},`);
   lines.push(`  handler: ${reindentBody(p.handlerBody?.raw ?? "", PATTERN_INDENT)},`);
   if (p.access !== undefined) lines.push(`  access: ${renderValue(p.access)},`);
+  if (p.description !== undefined) lines.push(`  description: ${JSON.stringify(p.description)},`);
+  if (p.agent !== undefined) lines.push(`  agent: ${renderValue(p.agent)},`);
   if (p.rateLimit !== undefined) lines.push(`  rateLimit: ${renderValue(p.rateLimit)},`);
   lines.push("});");
   return lines.join("\n");

package/src/engine/feature-entity-handlers.ts

@@ -14,6 +14,7 @@ import { resolveName } from "./handler-helpers";
 import { splitNamedDefinition } from "./object-form";
 import type {
   AccessRule,
+  AgentHandlerHints,
   EntityDefinition,
   EntityRef,
   HandlerRef,
@@ -54,6 +55,16 @@ function tryMapEntity(state: FeatureBuilderState, name: string, handlerName: str
   }
 }
 
+function agentSlots(source: {
+  readonly description?: string;
+  readonly agent?: AgentHandlerHints;
+}): { description?: string; agent?: AgentHandlerHints } {
+  return {
+    ...(source.description !== undefined && { description: source.description }),
+    ...(source.agent && { agent: source.agent }),
+  };
+}
+
 // Builds entity/relation/writeHandler/queryHandler — the registrar
 // methods that create or reference entities.
 export function buildEntityHandlerMethods<TName extends string>(
@@ -96,7 +107,12 @@ export function buildEntityHandlerMethods<TName extends string>(
       nameOrDef: string | WriteHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
       handler?: WriteHandlerFn<z.infer<TSchema>>,
-      options?: { access?: AccessRule; rateLimit?: RateLimitOption },
+      options?: {
+        access?: AccessRule;
+        rateLimit?: RateLimitOption;
+        description?: string;
+        agent?: AgentHandlerHints;
+      },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
         const def = nameOrDef;
@@ -113,6 +129,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           // is what fails). Explicit cast is the right tool.
           handler: def.handler as WriteHandlerFn,
           ...(def.access && { access: def.access }),
+          ...agentSlots(def),
           ...(def.unsafeSkipTransitionGuard && { unsafeSkipTransitionGuard: true }),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
           // Forward the pipeline-build closure so boot-validators and
@@ -135,6 +152,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         schema,
         handler: handler as WriteHandlerFn, // @cast-boundary engine-bridge
         ...(options?.access && { access: options.access }),
+        ...agentSlots(options ?? {}),
         ...(options?.rateLimit && { rateLimit: options.rateLimit }),
       };
       tryMapEntity(state, name, nameOrDef);
@@ -144,7 +162,13 @@ export function buildEntityHandlerMethods<TName extends string>(
       nameOrDef: string | QueryHandlerDefinition<TName, TSchema>,
       schema?: TSchema,
       handler?: QueryHandlerFn<z.infer<TSchema>>,
-      options?: { access?: AccessRule; rateLimit?: RateLimitOption; outputSchema?: ZodType },
+      options?: {
+        access?: AccessRule;
+        rateLimit?: RateLimitOption;
+        outputSchema?: ZodType;
+        description?: string;
+        agent?: AgentHandlerHints;
+      },
     ): HandlerRef {
       if (typeof nameOrDef === "object") {
         const def = nameOrDef;
@@ -154,6 +178,7 @@ export function buildEntityHandlerMethods<TName extends string>(
           // @cast-boundary engine-bridge — typed Dev-API → erased internal storage
           handler: def.handler as QueryHandlerFn, // @cast-boundary engine-bridge
           ...(def.access && { access: def.access }),
+          ...agentSlots(def),
           ...(def.rateLimit && { rateLimit: def.rateLimit }),
           ...(def.outputSchema && { outputSchema: def.outputSchema }),
           // Carry the definePagedQueryHandler brand through — this rebuild
@@ -170,6 +195,7 @@ export function buildEntityHandlerMethods<TName extends string>(
         schema,
         handler: handler as QueryHandlerFn, // @cast-boundary engine-bridge
         ...(options?.access && { access: options.access }),
+        ...agentSlots(options ?? {}),
         ...(options?.rateLimit && { rateLimit: options.rateLimit }),
         ...(options?.outputSchema && { outputSchema: options.outputSchema }),
       };

package/src/engine/index.ts

@@ -279,6 +279,9 @@ export {
 export type {
   AccessRule,
   ActionFormScreenDefinition,
+  AgentExposure,
+  AgentHandlerHints,
+  AgentRisk,
   AppContext,
   AppendEventArgs,
   AppendEventFn,
@@ -469,7 +472,7 @@ export type {
   WriteHandlerFn,
   WriteResult,
 } from "./types";
-export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases } from "./types";
+export { DEFAULT_CURRENCIES, DEFAULT_LOCALES, HookPhases, resolveAgentExposure } from "./types";
 export { isSystemTenant, isUuid, parseTenantId, SYSTEM_TENANT_ID } from "./types/identifiers";
 export type {
   AwaitedEventType,