@frockbot/kernel-contracts 0.3.1 → 0.3.3

package/src/isolate-context-catalog.generated.ts

@@ -1,6 +1,6 @@
 // Generated by scripts/generate-isolate-context-catalog.ts. Do not edit.
 export const BOT_ISOLATE_CONTEXT_DTS_V1 =
-  "/**\n * The common exact `ctx` passed to a Bot-authored Package's tool and hook.\n * The model-facing declarations are generated from these interfaces, and the\n * wrapper's implementation is compile- and test-checked against the same\n * keys.\n */\ninterface BotPackageContextV1 {\n    readonly tool?: string;\n    readonly event?: BotIsolateHookEventNameV1;\n    readonly botId: string;\n    readonly sessionId: string;\n    readonly runId: string;\n    readonly turnId: string;\n    readonly generationId: string;\n    readonly packageId: string;\n    readonly deadlineMs: number;\n    readonly bindings: string[];\n    readonly capabilities: {\n        list(): Promise<IsolateCapabilityListOutcomeV1>;\n    };\n    readonly model: {\n        invoke(request: NormalizedModelRequest): Promise<BotPackageModelOutcomeV1>;\n    };\n    readonly tools: {\n        /** Runs through the trusted registry's active-Composition and deny guards. */\n        invoke(request: IsolateToolRequestV1): Promise<IsolateToolOutcomeV1>;\n    };\n    readonly memory: {\n        read(request: IsolateMemoryReadRequestV1): Promise<IsolateMemoryOutcomeV1>;\n        write(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>;\n        forget(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>;\n    };\n    readonly workspace: {\n        read(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>;\n        list(request: IsolateWorkspaceListRequestV1): Promise<IsolateWorkspaceOutcomeV1>;\n        stat(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>;\n        write(request: IsolateWorkspaceWriteRequestV1): Promise<IsolateWorkspaceOutcomeV1>;\n        delete(request: IsolateWorkspaceDeleteRequestV1): Promise<IsolateWorkspaceOutcomeV1>;\n    };\n    connection(connectionId: string): Promise<IsolateConnectionOutcomeV1>;\n    notify(request: IsolateNotificationRequestV1): Promise<IsolateNotificationOutcomeV1>;\n    schedule(request: IsolateScheduleRequestV1): Promise<IsolateScheduleOutcomeV1>;\n}\n\ninterface BotPackageExecutionContextV1 extends BotPackageContextV1 {\n    readonly tool: string;\n    readonly event?: never;\n}\n\ninterface BotPackageHookContextV1 extends BotPackageContextV1 {\n    readonly tool?: never;\n    readonly event: BotIsolateHookEventNameV1;\n}";
+  "/**\n * The common exact `ctx` passed to a Bot-authored Package's tool and hook.\n * The model-facing declarations are generated from these interfaces, and the\n * wrapper's implementation is compile- and test-checked against the same\n * keys.\n */\ninterface BotPackageContextV1 {\n    readonly tool?: string;\n    readonly event?: BotIsolateHookEventNameV1;\n    readonly botId: string;\n    readonly sessionId: string;\n    readonly runId: string;\n    readonly turnId: string;\n    readonly generationId: string;\n    readonly packageId: string;\n    readonly deadlineMs: number;\n    readonly bindings: string[];\n    readonly capabilities: {\n        list(): Promise<IsolateCapabilityListOutcomeV1>;\n    };\n    readonly model: {\n        invoke(request: NormalizedModelRequest): Promise<BotPackageModelOutcomeV1>;\n    };\n    readonly tools: {\n        /** Runs through the trusted registry's active-Composition and deny guards. */\n        invoke(request: IsolateToolRequestV1): Promise<IsolateToolOutcomeV1>;\n    };\n    readonly memory: {\n        read(request: IsolateMemoryReadRequestV1): Promise<IsolateMemoryOutcomeV1>;\n        write(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>;\n        forget(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>;\n    };\n    readonly workspace: {\n        read(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>;\n        list(request: IsolateWorkspaceListRequestV1): Promise<IsolateWorkspaceOutcomeV1>;\n        stat(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>;\n        write(request: IsolateWorkspaceWriteRequestV1): Promise<IsolateWorkspaceOutcomeV1>;\n        delete(request: IsolateWorkspaceDeleteRequestV1): Promise<IsolateWorkspaceOutcomeV1>;\n    };\n    /**\n     * The User's Applets (ADR 0022). Account-wide: every Bot of this User sees\n     * every Applet. `publish` is a durable effect — it reads the built Applet\n     * from the Applets Package's durable root, verifies its manifest against the\n     * bytes, writes immutable artifacts, records the generation, mounts it, and\n     * proposes a new Composition generation for this Bot.\n     */\n    readonly applets: {\n        list(): Promise<IsolateAppletsOutcomeV1>;\n        create(input: {\n            displayName: string;\n        }): Promise<IsolateAppletsOutcomeV1>;\n        publish(input: {\n            appletId: string;\n        }): Promise<IsolateAppletsOutcomeV1>;\n        revert(input: {\n            appletId: string;\n            generationId: string;\n        }): Promise<IsolateAppletsOutcomeV1>;\n        delete(input: {\n            appletId: string;\n        }): Promise<IsolateAppletsOutcomeV1>;\n        focus(input: {\n            appletId: string | null;\n        }): Promise<IsolateAppletsOutcomeV1>;\n        generations(input: {\n            appletId: string;\n        }): Promise<IsolateAppletsOutcomeV1>;\n    };\n    connection(connectionId: string): Promise<IsolateConnectionOutcomeV1>;\n    notify(request: IsolateNotificationRequestV1): Promise<IsolateNotificationOutcomeV1>;\n    schedule(request: IsolateScheduleRequestV1): Promise<IsolateScheduleOutcomeV1>;\n}\n\ninterface BotPackageExecutionContextV1 extends BotPackageContextV1 {\n    readonly tool: string;\n    readonly event?: never;\n}\n\ninterface BotPackageHookContextV1 extends BotPackageContextV1 {\n    readonly tool?: never;\n    readonly event: BotIsolateHookEventNameV1;\n}";
 export const BOT_ISOLATE_CONTEXT_KEYS_V1 = [
   "tool",
   "event",
@@ -17,9 +17,10 @@ export const BOT_ISOLATE_CONTEXT_KEYS_V1 = [
   "tools",
   "memory",
   "workspace",
+  "applets",
   "connection",
   "notify",
   "schedule",
 ] as const;
 export const BOT_ISOLATE_CONTEXT_SUMMARY_V1 =
-  "Package execute and hook ctx share: readonly tool?: string; readonly event?: BotIsolateHookEventNameV1; readonly botId: string; readonly sessionId: string; readonly runId: string; readonly turnId: string; readonly generationId: string; readonly packageId: string; readonly deadlineMs: number; readonly bindings: string[]; readonly capabilities: { list(): Promise<IsolateCapabilityListOutcomeV1>; }; readonly model: { invoke(request: NormalizedModelRequest): Promise<BotPackageModelOutcomeV1>; }; readonly tools: { /** Runs through the trusted registry's active-Composition and deny guards. */ invoke(request: IsolateToolRequestV1): Promise<IsolateToolOutcomeV1>; }; readonly memory: { read(request: IsolateMemoryReadRequestV1): Promise<IsolateMemoryOutcomeV1>; write(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>; forget(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>; }; readonly workspace: { read(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>; list(request: IsolateWorkspaceListRequestV1): Promise<IsolateWorkspaceOutcomeV1>; stat(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>; write(request: IsolateWorkspaceWriteRequestV1): Promise<IsolateWorkspaceOutcomeV1>; delete(request: IsolateWorkspaceDeleteRequestV1): Promise<IsolateWorkspaceOutcomeV1>; }; connection(connectionId: string): Promise<IsolateConnectionOutcomeV1>; notify(request: IsolateNotificationRequestV1): Promise<IsolateNotificationOutcomeV1>; schedule(request: IsolateScheduleRequestV1): Promise<IsolateScheduleOutcomeV1>;";
+  "Package execute and hook ctx share: readonly tool?: string; readonly event?: BotIsolateHookEventNameV1; readonly botId: string; readonly sessionId: string; readonly runId: string; readonly turnId: string; readonly generationId: string; readonly packageId: string; readonly deadlineMs: number; readonly bindings: string[]; readonly capabilities: { list(): Promise<IsolateCapabilityListOutcomeV1>; }; readonly model: { invoke(request: NormalizedModelRequest): Promise<BotPackageModelOutcomeV1>; }; readonly tools: { /** Runs through the trusted registry's active-Composition and deny guards. */ invoke(request: IsolateToolRequestV1): Promise<IsolateToolOutcomeV1>; }; readonly memory: { read(request: IsolateMemoryReadRequestV1): Promise<IsolateMemoryOutcomeV1>; write(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>; forget(request: IsolateMemoryWriteRequestV1): Promise<IsolateMemoryOutcomeV1>; }; readonly workspace: { read(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>; list(request: IsolateWorkspaceListRequestV1): Promise<IsolateWorkspaceOutcomeV1>; stat(path: IsolateWorkspacePathV1): Promise<IsolateWorkspaceOutcomeV1>; write(request: IsolateWorkspaceWriteRequestV1): Promise<IsolateWorkspaceOutcomeV1>; delete(request: IsolateWorkspaceDeleteRequestV1): Promise<IsolateWorkspaceOutcomeV1>; }; /** * The User's Applets (ADR 0022). Account-wide: every Bot of this User sees * every Applet. `publish` is a durable effect — it reads the built Applet * from the Applets Package's durable root, verifies its manifest against the * bytes, writes immutable artifacts, records the generation, mounts it, and * proposes a new Composition generation for this Bot. */ readonly applets: { list(): Promise<IsolateAppletsOutcomeV1>; create(input: { displayName: string; }): Promise<IsolateAppletsOutcomeV1>; publish(input: { appletId: string; }): Promise<IsolateAppletsOutcomeV1>; revert(input: { appletId: string; generationId: string; }): Promise<IsolateAppletsOutcomeV1>; delete(input: { appletId: string; }): Promise<IsolateAppletsOutcomeV1>; focus(input: { appletId: string | null; }): Promise<IsolateAppletsOutcomeV1>; generations(input: { appletId: string; }): Promise<IsolateAppletsOutcomeV1>; }; connection(connectionId: string): Promise<IsolateConnectionOutcomeV1>; notify(request: IsolateNotificationRequestV1): Promise<IsolateNotificationOutcomeV1>; schedule(request: IsolateScheduleRequestV1): Promise<IsolateScheduleOutcomeV1>;";

package/src/isolate.ts

@@ -230,6 +230,25 @@ export interface IsolateNotificationRequestV1 {
 export type IsolateNotificationOutcomeV1 =
   { status: "recorded" } | IsolateCapabilityFailureV1;
 
+/**
+ * The Applet capability a Bot isolate calls (ADR 0022, plan §3).
+ *
+ * One tagged request rather than seven methods on the stub: the operations
+ * share a scope, an authority, and an outcome shape, and the wrapper narrows
+ * them back into the seven-verb `ctx.applets` a Bot author writes against.
+ */
+export type IsolateAppletsRequestV1 =
+  | { op: "list" }
+  | { op: "create"; displayName: string }
+  | { op: "publish"; appletId: string }
+  | { op: "revert"; appletId: string; generationId: string }
+  | { op: "delete"; appletId: string }
+  | { op: "focus"; appletId: string | null }
+  | { op: "generations"; appletId: string };
+
+export type IsolateAppletsOutcomeV1 =
+  { status: "available"; value: unknown } | IsolateCapabilityFailureV1;
+
 /** A durable Routine operation attributed to one Package call. */
 export interface IsolateScheduleRequestV1 {
   callId: string;
@@ -303,6 +322,7 @@ export interface BotCapabilitiesStub {
   schedule(
     request: IsolateScheduleRequestV1,
   ): Promise<IsolateScheduleOutcomeV1>;
+  applets(request: IsolateAppletsRequestV1): Promise<IsolateAppletsOutcomeV1>;
 }
 
 /** The model outcome Bot-authored `package.js` receives after wrapper narrowing. */
@@ -363,6 +383,25 @@ export interface BotPackageContextV1 {
       request: IsolateWorkspaceDeleteRequestV1,
     ): Promise<IsolateWorkspaceOutcomeV1>;
   };
+  /**
+   * The User's Applets (ADR 0022). Account-wide: every Bot of this User sees
+   * every Applet. `publish` is a durable effect — it reads the built Applet
+   * from the Applets Package's durable root, verifies its manifest against the
+   * bytes, writes immutable artifacts, records the generation, mounts it, and
+   * proposes a new Composition generation for this Bot.
+   */
+  readonly applets: {
+    list(): Promise<IsolateAppletsOutcomeV1>;
+    create(input: { displayName: string }): Promise<IsolateAppletsOutcomeV1>;
+    publish(input: { appletId: string }): Promise<IsolateAppletsOutcomeV1>;
+    revert(input: {
+      appletId: string;
+      generationId: string;
+    }): Promise<IsolateAppletsOutcomeV1>;
+    delete(input: { appletId: string }): Promise<IsolateAppletsOutcomeV1>;
+    focus(input: { appletId: string | null }): Promise<IsolateAppletsOutcomeV1>;
+    generations(input: { appletId: string }): Promise<IsolateAppletsOutcomeV1>;
+  };
   connection(connectionId: string): Promise<IsolateConnectionOutcomeV1>;
   notify(
     request: IsolateNotificationRequestV1,
@@ -999,6 +1038,65 @@ export function decodeIsolateScheduleRequestV1(
   };
 }
 
+const APPLET_CAPABILITY_ID = /^[a-z0-9][a-z0-9-]{0,63}\.[a-z0-9-]{1,64}$/;
+
+export function decodeIsolateAppletsRequestV1(
+  input: unknown,
+  label = "isolate Applets request",
+): IsolateAppletsRequestV1 {
+  const value = record(input, label);
+  const appletId = (): string => {
+    const id = boundedString(value.appletId, `${label}.appletId`, 129);
+    if (!APPLET_CAPABILITY_ID.test(id)) {
+      throw new Error(`${label}.appletId is invalid`);
+    }
+    return id;
+  };
+  switch (value.op) {
+    case "list":
+      exactKeys(value, ["op"], label);
+      return { op: "list" };
+    case "create":
+      exactKeys(value, ["op", "displayName"], label);
+      return {
+        op: "create",
+        displayName: boundedString(
+          value.displayName,
+          `${label}.displayName`,
+          128,
+        ),
+      };
+    case "publish":
+      exactKeys(value, ["op", "appletId"], label);
+      return { op: "publish", appletId: appletId() };
+    case "revert":
+      exactKeys(value, ["op", "appletId", "generationId"], label);
+      return {
+        op: "revert",
+        appletId: appletId(),
+        generationId: boundedString(
+          value.generationId,
+          `${label}.generationId`,
+          128,
+        ),
+      };
+    case "delete":
+      exactKeys(value, ["op", "appletId"], label);
+      return { op: "delete", appletId: appletId() };
+    case "focus":
+      exactKeys(value, ["op", "appletId"], label);
+      return {
+        op: "focus",
+        appletId: value.appletId === null ? null : appletId(),
+      };
+    case "generations":
+      exactKeys(value, ["op", "appletId"], label);
+      return { op: "generations", appletId: appletId() };
+    default:
+      throw new Error(`${label}.op is invalid`);
+  }
+}
+
 const MEMORY_SCOPES = ["bot", "user", "project"] as const;
 const MEMORY_TIERS = ["profile", "log", "note"] as const;
 

package/src/superseded-history.test.ts

@@ -0,0 +1,145 @@
+/**
+ * What a Turn the User's next message replaced looks like to the model request
+ * that follows it.
+ *
+ * The whole answer is in the durable log: `deriveMessages` walks the events and
+ * reads nothing else, so a superseded Turn contributes exactly what it made
+ * durable — what it said, and what its tools actually returned. There is no
+ * branch for supersede here, and that is the point: the next request is
+ * reconstructed from events, so a Turn that ended early is a Turn with fewer
+ * events, not a Turn with a special case.
+ */
+import { describe, expect, test } from "bun:test";
+import { Session } from "./session.js";
+import type { SessionEvent } from "./types.js";
+
+const timestamp = "2026-09-03T00:00:00.000Z";
+
+function session(): Session {
+  return new Session("user-1:primary", () => {});
+}
+
+/**
+ * A Turn that sent a line, completed one tool call, and had a second still in
+ * flight when the User's next message arrived.
+ */
+function supersededTurn(target: Session): void {
+  target.appendBatch([
+    { type: "turn/start", turn: 1 },
+    { type: "step/start", turn: 1, step: 1 },
+    { type: "user/message", turn: 1, step: 1, messageId: "m-1", text: "go" },
+    {
+      type: "assistant/message",
+      turn: 1,
+      step: 1,
+      requestId: "request-1",
+      text: "starting",
+      toolCalls: [
+        { id: "call-a", name: "read", input: {} },
+        { id: "call-b", name: "write", input: {} },
+      ],
+    },
+    {
+      type: "tool/call",
+      turn: 1,
+      step: 1,
+      occurrenceId: "tool:1:1:0",
+      name: "read",
+      input: {},
+    },
+    {
+      type: "tool/result",
+      turn: 1,
+      step: 1,
+      occurrenceId: "tool:1:1:0",
+      name: "read",
+      content: "the notes say hello",
+      isError: false,
+      status: "completed",
+    },
+    {
+      type: "tool/call",
+      turn: 1,
+      step: 1,
+      occurrenceId: "tool:1:1:1",
+      name: "write",
+      input: {},
+    },
+  ]);
+}
+
+describe("the next Turn's request derives from what the superseded Turn recorded", () => {
+  test("its sends and completed tool results are visible; the in-flight one is not claimed", () => {
+    const target = session();
+    supersededTurn(target);
+    // The interrupt: every unresolved effect is closed as interrupted, and the
+    // Turn is ended. This is the same repair a Stop makes.
+    target.reconcileInterrupted();
+
+    const messages = target.deriveMessages();
+
+    expect(messages).toEqual([
+      { role: "user", content: "go" },
+      {
+        role: "assistant",
+        content: "starting",
+        toolCalls: [
+          { id: "call-a", name: "read", input: {} },
+          { id: "call-b", name: "write", input: {} },
+        ],
+      },
+      {
+        role: "tool",
+        callId: "call-a",
+        name: "read",
+        content: "the notes say hello",
+        isError: false,
+      },
+      {
+        role: "tool",
+        callId: "call-b",
+        name: "write",
+        content: "Interrupted before a durable result was recorded.",
+        isError: true,
+      },
+    ]);
+    // The Turn ended, and the log says so. Nothing was invented for the effect
+    // that never returned: it is present, and it is an error.
+    expect(target.events.at(-1)).toMatchObject({
+      type: "turn/end",
+      outcome: "interrupted",
+    });
+  });
+
+  test("the new Turn's own message is simply the next one in the log", () => {
+    const target = session();
+    supersededTurn(target);
+    target.reconcileInterrupted();
+    target.appendBatch([
+      { type: "turn/start", turn: 2 },
+      { type: "step/start", turn: 2, step: 1 },
+      {
+        type: "user/message",
+        turn: 2,
+        step: 1,
+        messageId: "m-2",
+        text: "actually, do this instead",
+      },
+    ]);
+
+    const messages = target.deriveMessages();
+
+    expect(messages.at(-1)).toEqual({
+      role: "user",
+      content: "actually, do this instead",
+    });
+    // Deterministic: the same events derive the same request every time.
+    expect(target.deriveMessages()).toEqual(messages);
+    const replayed = new Session(
+      "user-1:primary",
+      () => {},
+      target.events as readonly SessionEvent[],
+    );
+    expect(replayed.deriveMessages()).toEqual(messages);
+  });
+});

package/src/tool-execution.ts

@@ -125,6 +125,12 @@ export type ToolEffectReconciliation =
   | { status: "unavailable"; reason: string };
 
 export interface ToolDefinition extends ToolSchema {
+  /**
+   * A dynamic Tool Namespace. Absent means the tool is native and its schema
+   * is offered to the model directly; present means the schema is disclosed
+   * and the tool is invoked only through the registry's two meta-tools.
+   */
+  namespace?: string;
   idempotent?: boolean;
   /** The turn types this tool is offered on. Absent means all of them. */
   admission?: TurnAdmissionV1;
@@ -185,10 +191,24 @@ export interface ToolRegistrationOptions {
   subagentRoleCeiling?: readonly string[];
 }
 
+export interface ToolNamespaceRegistration {
+  name: string;
+  description?: string;
+  status?: "ready" | "needsAuth" | "error";
+  /** External namespaces require call metadata before an effect is admitted. */
+  external?: boolean;
+  /** Namespace-level instructions rendered in the dynamic catalog prompt. */
+  useInstructions?: string;
+}
+
 /** Contributing Packages register tool definitions through this surface. */
 export interface ToolRegistration {
-  /** Every registered name, before turn/role admission trims the catalog. */
+  /**
+   * Every registered identity, before turn/role admission trims the catalog.
+   * Native tools use their bare name; dynamic tools use `namespace/name`.
+   */
   registeredNames?(): string[];
+  registerNamespace(namespace: ToolNamespaceRegistration): () => void;
   register(
     definition: ToolDefinition,
     options?: ToolRegistrationOptions,

package/src/types.ts

@@ -611,7 +611,10 @@ export interface SessionEventMap {
    *
    * `reason` is why the sync ran: `open` before the Turn's first Computer tool
    * call, `signal` when the on-Computer watcher reported a change mid-Turn,
-   * `turn-end` after a Turn that used the Computer.
+   * `turn-end` after a Turn that used the Computer, and `publish` for the one
+   * sanctioned reconciliation outside that policy — a single declared root
+   * pulled and pushed so an Applet publish can read the artifact `applet
+   * build` left on the Computer (ADR 0022 decision 7).
    */
   /**
    * A background process on the Computer changed hands: it was launched,
@@ -640,7 +643,7 @@ export interface SessionEventMap {
   };
   "computer/sync": {
     turn: number;
-    reason: "open" | "signal" | "turn-end";
+    reason: "open" | "signal" | "turn-end" | "publish";
     status: "ok" | "unavailable" | "refused" | "skipped";
     detail: string;
     pulled: number;
@@ -1875,7 +1878,11 @@ export function decodeSessionEvent(input: unknown): SessionEvent {
         "session event",
       );
       turn();
-      if (!["open", "signal", "turn-end"].includes(event.reason as string)) {
+      if (
+        !["open", "signal", "turn-end", "publish"].includes(
+          event.reason as string,
+        )
+      ) {
         throw new Error("session event.reason is invalid");
       }
       if (