@frockbot/kernel-contracts 0.1.3 → 0.2.0

package/src/send-to-user.ts

@@ -12,18 +12,16 @@
 // type admits, when a payload ends a Turn, or how a client draws one.
 //
 // Only the `widget` shape is host-source (§4.2 of `docs/research/
-// grokbot-computer.md`). The other four members are named in the same section
+// grokbot-computer.md`). The other members are named in the same section
 // but their field lists are not recorded, so they are declared here in the
 // narrowest shape that carries the observed meaning, and widened when a
 // primary source says more.
 //
-// `approval` has no GrokBot payload behind it at all: row 53
-// records only the harness sentence "when your own action needs approval". It
-// is declared here because the constitution's *Self-modification* rule — "a
-// request for more becomes a durable pending decision for the User, never a
-// grant" — needs one shape to carry that request, and a card the Bot sends is
-// the only path a Turn has to a person. Like `widget` it ends the Turn: the
-// Bot has nothing to do until a human answers.
+// `approval` has no GrokBot payload behind it at all: row 53 records only the
+// harness sentence "when your own action needs approval". It carries a human
+// confirmation required by a deny-only guard; it never widens Bot authority.
+// Like `widget` it ends the Turn: the Bot has nothing to do until a human
+// answers.
 
 /** The widget shape, verbatim from §4.2: `options` holds 1–6 entries. */
 export interface SendToUserWidgetV1 {
@@ -40,22 +38,6 @@ export type SendToUserPayloadV1 =
   | { type: "widget"; widget: SendToUserWidgetV1 }
   | { type: "secret-request"; prompt: string; secretName: string }
   | { type: "agent-card"; agentId: string; title: string; body?: string }
-  /**
-   * A Connection the Bot has recorded a pending authorization decision for.
-   *
-   * There is deliberately **no URL** on this payload, and there never will be.
-   * A Bot may create a durable *request* for authorization; only an
-   * authenticated User action mints a redirect, and a single-use ten-minute
-   * link sitting in a client-readable transcript would outlive the decision it
-   * belonged to. The client draws a card from the Connection's own projection
-   * and the User presses it; the host authors the link at that moment.
-   */
-  | {
-      type: "connect-card";
-      connectionId: string;
-      title: string;
-      body?: string;
-    }
   | {
       type: "approval";
       /** The Bot's own id for the decision, and the key it is recorded under. */
@@ -76,15 +58,7 @@ export const SEND_TO_USER_APPROVAL_RISKS_V1: readonly SendToUserApprovalRiskV1[]
   ["low", "medium", "high"];
 
 export const SEND_TO_USER_PAYLOAD_TYPES_V1: readonly SendToUserPayloadV1["type"][] =
-  [
-    "text",
-    "attachment",
-    "widget",
-    "secret-request",
-    "agent-card",
-    "connect-card",
-    "approval",
-  ];
+  ["text", "attachment", "widget", "secret-request", "agent-card", "approval"];
 
 /**
  * Bounds, so a payload cannot be the way a Turn writes an unbounded record
@@ -103,7 +77,6 @@ export const SEND_TO_USER_LIMITS_V1 = {
   maxOptions: 6,
   secretName: 128,
   agentId: 128,
-  connectionId: 128,
   title: 200,
   body: 8_000,
   approvalId: 128,
@@ -356,28 +329,6 @@ export function decodeSendToUserPayloadV1(
         ...(body === undefined ? {} : { body }),
       };
     }
-    case "connect-card": {
-      exactPayloadKeys(
-        payload,
-        ["type", "connectionId", "title", "body"],
-        label,
-      );
-      const body = optionalBoundedString(
-        payload.body,
-        limits.body,
-        `${label}.body`,
-      );
-      return {
-        type: "connect-card",
-        connectionId: boundedString(
-          payload.connectionId,
-          limits.connectionId,
-          `${label}.connectionId`,
-        ),
-        title: boundedString(payload.title, limits.title, `${label}.title`),
-        ...(body === undefined ? {} : { body }),
-      };
-    }
     default:
       throw new Error(`${label}.type is invalid`);
   }

package/src/session.test.ts

@@ -39,6 +39,22 @@ afterEach(async () => {
   await Promise.all(roots.splice(0).map((root) => root.fiber.dispose()));
 });
 
+test("a Bot-isolate hook failure is an exact durable session event", () => {
+  const event = {
+    type: "package/hook-failed",
+    packageId: "bot-authored",
+    event: "agent/tool-exposure",
+    generationId: "gen-1",
+    message: "hook exploded",
+    seq: 0,
+    timestamp,
+  } as const;
+  expect(decodeSessionEvent(event)).toEqual(event);
+  expect(() => decodeSessionEvent({ ...event, retry: true })).toThrow(
+    /invalid fields/,
+  );
+});
+
 describe("SessionStore", () => {
   test("accepts resumable tool crash states only while their step is open", () => {
     const assistant = [

package/src/tool-execution.ts

@@ -187,12 +187,28 @@ export interface ToolRegistrationOptions {
 
 /** Contributing Packages register tool definitions through this surface. */
 export interface ToolRegistration {
+  /** Every registered name, before turn/role admission trims the catalog. */
+  registeredNames?(): string[];
   register(
     definition: ToolDefinition,
     options?: ToolRegistrationOptions,
   ): () => void;
+  /**
+   * First-party, deny-only policy evaluated after `tools/pre-execute` and
+   * before `tools/execute`. The isolate contract never exposes this method.
+   */
+  guard(guard: ToolGuard): () => void;
 }
 
+export interface ToolGuardDenial {
+  reason: string;
+}
+
+export type ToolGuard = (
+  call: ToolCall,
+  context: ToolExecutionContext,
+) => ToolGuardDenial | undefined | Promise<ToolGuardDenial | undefined>;
+
 declare module "cordis" {
   interface Context {
     tools: ToolExecution & ToolRegistration;

package/src/types.ts

@@ -328,6 +328,27 @@ export interface SessionEventMap {
     /** Durable references to binaries the tool produced. Never their bytes. */
     attachments?: ToolAttachmentV1[];
   };
+  /** A tool one loaded Package invoked through the Bot's shared registry. */
+  "package/tool-call": {
+    turn: number;
+    step: number;
+    effectId: string;
+    packageId: string;
+    callId: string;
+    name: string;
+    input: unknown;
+  };
+  /** The exact result returned to that Package. */
+  "package/tool-result": {
+    turn: number;
+    step: number;
+    effectId: string;
+    packageId: string;
+    callId: string;
+    name: string;
+    content: string;
+    isError: boolean;
+  };
   /**
    * The Bot recorded the intent to author a Package, before the bundler ran.
    * Constitution, Durable effects: intent is recorded before the effect.
@@ -349,6 +370,48 @@ export interface SessionEventMap {
     contentHash: string;
     generationId: string;
   };
+  /** A Bot-isolate loop hook failed open for one invocation. */
+  "package/hook-failed": {
+    packageId: string;
+    event: string;
+    generationId: string;
+    message: string;
+  };
+  /** Durable session intent before a Catalog installation effect. */
+  "package/catalog-change-intent": {
+    turn: number;
+    step: number;
+    effectId: string;
+    action: "install" | "update" | "remove";
+    catalogId?: string;
+    packageId?: string;
+    contentHash?: string;
+  };
+  /** The pending Composition generation produced by that Catalog change. */
+  "package/catalog-changed": {
+    turn: number;
+    step: number;
+    effectId: string;
+    action: "install" | "update" | "remove";
+    packageId: string;
+    contentHash?: string;
+    generationId: string;
+  };
+  /** Durable intent before a Bot-origin Composition revert is proposed. */
+  "package/undo-intent": {
+    turn: number;
+    step: number;
+    effectId: string;
+    requestedGenerationId?: string;
+  };
+  /** The new pending generation recorded by a Bot-origin revert. */
+  "package/undo-recorded": {
+    turn: number;
+    step: number;
+    effectId: string;
+    generationId: string;
+    targetGenerationId: string;
+  };
   /**
    * The Skills this Turn loaded as instructions, and the candidates it
    * refused. Constitution, Memory: "the session event log records exactly what
@@ -1179,6 +1242,54 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
         );
       }
       break;
+    case "package/tool-call":
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "effectId",
+          "packageId",
+          "callId",
+          "name",
+          "input",
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      eventString(event.packageId, "session event.packageId");
+      eventString(event.callId, "session event.callId");
+      eventString(event.name, "session event.name");
+      requireJsonValue(event.input, "session event.input");
+      break;
+    case "package/tool-result":
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "effectId",
+          "packageId",
+          "callId",
+          "name",
+          "content",
+          "isError",
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      eventString(event.packageId, "session event.packageId");
+      eventString(event.callId, "session event.callId");
+      eventString(event.name, "session event.name");
+      eventString(event.content, "session event.content", true);
+      if (typeof event.isError !== "boolean") {
+        throw new Error("session event.isError must be a boolean");
+      }
+      break;
     case "package/author-intent":
       requireEventKeys(
         event,
@@ -1213,6 +1324,124 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
       eventString(event.contentHash, "session event.contentHash");
       eventString(event.generationId, "session event.generationId");
       break;
+    case "package/hook-failed":
+      requireEventKeys(
+        event,
+        keys("packageId", "event", "generationId", "message"),
+        "session event",
+      );
+      eventString(event.packageId, "session event.packageId");
+      eventString(event.event, "session event.event");
+      eventString(event.generationId, "session event.generationId");
+      eventString(event.message, "session event.message");
+      break;
+    case "package/catalog-change-intent":
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "effectId",
+          "action",
+          ...(Object.hasOwn(event, "catalogId") ? ["catalogId"] : []),
+          ...(Object.hasOwn(event, "packageId") ? ["packageId"] : []),
+          ...(Object.hasOwn(event, "contentHash") ? ["contentHash"] : []),
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      if (
+        event.action !== "install" &&
+        event.action !== "update" &&
+        event.action !== "remove"
+      ) {
+        throw new Error("session event.action is invalid");
+      }
+      if (event.catalogId !== undefined)
+        eventString(event.catalogId, "session event.catalogId");
+      if (event.packageId !== undefined)
+        eventString(event.packageId, "session event.packageId");
+      if (event.contentHash !== undefined)
+        eventString(event.contentHash, "session event.contentHash");
+      if (
+        (event.action === "remove" &&
+          (event.packageId === undefined ||
+            event.catalogId !== undefined ||
+            event.contentHash !== undefined)) ||
+        (event.action !== "remove" &&
+          (event.catalogId === undefined ||
+            event.contentHash === undefined ||
+            event.packageId !== undefined))
+      ) {
+        throw new Error("session Catalog change intent identity is invalid");
+      }
+      break;
+    case "package/catalog-changed":
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "effectId",
+          "action",
+          "packageId",
+          "generationId",
+          ...(Object.hasOwn(event, "contentHash") ? ["contentHash"] : []),
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      eventString(event.packageId, "session event.packageId");
+      eventString(event.generationId, "session event.generationId");
+      if (event.contentHash !== undefined)
+        eventString(event.contentHash, "session event.contentHash");
+      if (
+        event.action !== "install" &&
+        event.action !== "update" &&
+        event.action !== "remove"
+      ) {
+        throw new Error("session event.action is invalid");
+      }
+      break;
+    case "package/undo-intent":
+      requireEventKeys(
+        event,
+        keys(
+          "turn",
+          "step",
+          "effectId",
+          ...(Object.hasOwn(event, "requestedGenerationId")
+            ? ["requestedGenerationId"]
+            : []),
+        ),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      if (event.requestedGenerationId !== undefined) {
+        eventString(
+          event.requestedGenerationId,
+          "session event.requestedGenerationId",
+        );
+      }
+      break;
+    case "package/undo-recorded":
+      requireEventKeys(
+        event,
+        keys("turn", "step", "effectId", "generationId", "targetGenerationId"),
+        "session event",
+      );
+      turn();
+      step();
+      eventString(event.effectId, "session event.effectId");
+      eventString(event.generationId, "session event.generationId");
+      eventString(event.targetGenerationId, "session event.targetGenerationId");
+      break;
     case "skill/injected": {
       requireEventKeys(
         event,