@frockbot/kernel-contracts 0.3.1 → 0.3.2

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/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 (