@frockbot/kernel-do 0.1.3 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frockbot/kernel-do",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "private": false,
   "type": "module",
   "exports": {
@@ -12,8 +12,8 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@frockbot/kernel-composition": "0.1.3",
-    "@frockbot/kernel-contracts": "0.1.3",
+    "@frockbot/kernel-composition": "0.2.0",
+    "@frockbot/kernel-contracts": "0.2.0",
     "cordis": "4.0.0-rc.8"
   },
   "devDependencies": {

package/src/authority.ts

@@ -322,6 +322,7 @@ export class BotDurableAuthority<Snapshot> {
             ? { subagentRole: storedRunSubagentRoleV1(run) }
             : {}),
           ...(run.admission?.origin ? { origin: run.admission.origin } : {}),
+          ...(run.directTool ? { directTool: run.directTool } : {}),
         },
         previousEvents: latest,
         configurationSnapshot: settings,
@@ -717,6 +718,9 @@ export class BotDurableAuthority<Snapshot> {
           command.origin,
           command.subagentRole,
         ),
+        ...(command.directTool
+          ? { directTool: structuredClone(command.directTool) }
+          : {}),
       } satisfies StoredRunV1<Snapshot>);
       await transaction.put({
         [key]: admittedRun,
@@ -980,6 +984,9 @@ export class BotDurableAuthority<Snapshot> {
         ...(recovery.run.admission?.origin
           ? { origin: recovery.run.admission.origin }
           : {}),
+        ...(recovery.run.directTool
+          ? { directTool: recovery.run.directTool }
+          : {}),
       },
       recovery.previous,
       recovery.settings,

package/src/composition-store.test.ts

@@ -161,6 +161,125 @@ describe("Bot Durable Object Composition records", () => {
     await expect(store.propose(next)).rejects.toThrow("already exists");
   });
 
+  test("refuses proposals that remove or replace the first-party bootstrap core", async () => {
+    const storage = new MemoryStorage();
+    const store = createStore(storage);
+    const parent = await store.current();
+    const createdAt = "2026-09-01T00:00:00.000Z";
+
+    const omittedHash = await compositionArtifactSetHashV1([]);
+    await expect(
+      store.propose({
+        schemaVersion: 1,
+        generationId: compositionGenerationIdV1(createdAt, omittedHash),
+        artifactSetHash: omittedHash,
+        parentGenerationId: parent.generationId,
+        createdAt,
+        origin: {
+          kind: "bot-authored",
+          runId: "run-1",
+          sessionId: "s",
+          turnId: "t",
+        },
+        members: [],
+        status: "pending",
+      }),
+    ).rejects.toThrow(/omits required first-party Package "shell"/);
+
+    const shadow: CompositionMemberV1 = {
+      ...authoredMember,
+      packageId: "shell",
+      specifier: "bot-authored:shell",
+      provenance: {
+        ...authoredMember.provenance,
+        packageId: "shell",
+      },
+    };
+    const replacedHash = await compositionArtifactSetHashV1([shadow]);
+    await expect(
+      store.propose({
+        schemaVersion: 1,
+        generationId: compositionGenerationIdV1(createdAt, replacedHash),
+        artifactSetHash: replacedHash,
+        parentGenerationId: parent.generationId,
+        createdAt,
+        origin: {
+          kind: "bot-authored",
+          runId: "run-1",
+          sessionId: "s",
+          turnId: "t",
+        },
+        members: [shadow],
+        status: "pending",
+      }),
+    ).rejects.toThrow(
+      /replaces required first-party Package "shell" with bot provenance/,
+    );
+
+    const catalogShadow: CompositionMemberV1 = {
+      packageId: "shell",
+      specifier: "catalog:shell",
+      version: "0.0.1",
+      manifestHash: authoredMember.manifestHash,
+      provenance: {
+        kind: "catalog",
+        packageId: "shell",
+        version: "0.0.1",
+        catalogId: "shell",
+        catalogGeneration: "catalog-1",
+        contentHash: authoredMember.artifact!.contentHash,
+      },
+      artifact: authoredMember.artifact,
+    };
+    const catalogHash = await compositionArtifactSetHashV1([catalogShadow]);
+    await expect(
+      store.propose({
+        schemaVersion: 1,
+        generationId: compositionGenerationIdV1(createdAt, catalogHash),
+        artifactSetHash: catalogHash,
+        parentGenerationId: parent.generationId,
+        createdAt,
+        origin: {
+          kind: "bot-catalog",
+          action: "install",
+          packageId: "shell",
+          catalogId: "shell",
+          botId: "bot-1",
+          runId: "run-1",
+          sessionId: "s",
+          turnId: "t",
+        },
+        summary: "Added shell",
+        members: [catalogShadow],
+        status: "pending",
+      }),
+    ).rejects.toThrow(
+      /replaces required first-party Package "shell" with catalog provenance/,
+    );
+
+    const changedCore = {
+      ...parent.members[0]!,
+      version: "9.9.9",
+      provenance: {
+        ...parent.members[0]!.provenance,
+        version: "9.9.9",
+      },
+    };
+    const changedHash = await compositionArtifactSetHashV1([changedCore]);
+    await expect(
+      store.propose({
+        schemaVersion: 1,
+        generationId: compositionGenerationIdV1(createdAt, changedHash),
+        artifactSetHash: changedHash,
+        parentGenerationId: parent.generationId,
+        createdAt,
+        origin: { kind: "user-install", userId: "user-1" },
+        members: [changedCore],
+        status: "pending",
+      }),
+    ).resolves.toBeUndefined();
+  });
+
   test("reverting records a new pending generation with the target's members", async () => {
     const storage = new MemoryStorage();
     const store = createStore(
@@ -244,6 +363,41 @@ describe("Bot Durable Object Composition records", () => {
     ]);
   });
 
+  test("a Bot-origin revert is idempotent and cannot mark its generation last-known-good", async () => {
+    const storage = new MemoryStorage();
+    const store = createStore(storage);
+    const bootstrapped = await store.current();
+    const authored = await grownSuccessor(
+      bootstrapped,
+      "2026-09-01T00:00:00.000Z",
+    );
+    await store.propose(authored);
+    await store.commit(authored.generationId);
+    const origin = {
+      kind: "revert" as const,
+      revertsTo: bootstrapped.generationId,
+      botId: "bot-1",
+      runId: "run-undo",
+      turnId: "turn-undo",
+    };
+
+    const reverted = await store.revert(bootstrapped.generationId, origin, {
+      createdAt: "2026-09-02T00:00:00.000Z",
+    });
+    const replay = await store.revert(bootstrapped.generationId, origin, {
+      createdAt: "2026-09-02T00:00:00.000Z",
+    });
+
+    expect(replay).toEqual(reverted);
+    expect((await store.lastKnownGood()).generationId).toBe(
+      authored.generationId,
+    );
+    await store.fail(reverted.generationId, { quarantined: false });
+    expect((await store.lastKnownGood()).generationId).toBe(
+      authored.generationId,
+    );
+  });
+
   test("refuses an unknown target and the generation that is already current", async () => {
     const storage = new MemoryStorage();
     const store = createStore(

package/src/composition-store.ts

@@ -162,6 +162,8 @@ export class DurableCompositionStore implements CompositionStore {
     await assertCompositionArtifactSetHashV1(proposed);
     await this.materialize();
     await this.ctx.storage.transaction(async (transaction) => {
+      const bootstrap = await this.bootstrapGeneration(transaction);
+      this.assertRequiredCoreSet(bootstrap, proposed);
       const key = compositionGenerationKey(proposed.generationId);
       if ((await transaction.get<unknown>(key)) !== undefined) {
         throw new Error(
@@ -342,6 +344,7 @@ export class DurableCompositionStore implements CompositionStore {
   async revert(
     toGenerationId: string,
     origin: Extract<CompositionOriginV1, { kind: "revert" }>,
+    options: { createdAt?: string } = {},
   ): Promise<CompositionGenerationV1> {
     if (origin.kind !== "revert" || origin.revertsTo !== toGenerationId) {
       throw new Error("composition revert origin does not name its target");
@@ -356,7 +359,7 @@ export class DurableCompositionStore implements CompositionStore {
     if (!target) {
       throw new Error(`composition generation "${toGenerationId}" is unknown`);
     }
-    const createdAt = this.now().toISOString();
+    const createdAt = options.createdAt ?? this.now().toISOString();
     const generation = decodeCompositionGenerationV1({
       schemaVersion: 1,
       generationId: compositionGenerationIdV1(
@@ -370,6 +373,18 @@ export class DurableCompositionStore implements CompositionStore {
       members: target.members,
       status: "pending",
     });
+    const existing = await this.read(generation.generationId);
+    if (existing) {
+      if (
+        existing.artifactSetHash === generation.artifactSetHash &&
+        JSON.stringify(existing.origin) === JSON.stringify(origin)
+      ) {
+        return existing;
+      }
+      throw new Error(
+        `composition generation "${generation.generationId}" already exists for another operation`,
+      );
+    }
     await this.propose(generation, { pin: true });
     return generation;
   }
@@ -431,6 +446,34 @@ export class DurableCompositionStore implements CompositionStore {
     return decodeCompositionGenerationV1(stored);
   }
 
+  /**
+   * Every first-party bootstrap member is required core. No proposal path may
+   * remove it or replace its provenance: callers can update reviewed
+   * first-party members, but cannot turn them into User- or Bot-authored code.
+   */
+  private assertRequiredCoreSet(
+    bootstrap: CompositionGenerationV1,
+    proposed: CompositionGenerationV1,
+  ): void {
+    for (const required of bootstrap.members.filter(
+      (member) => member.provenance.kind === "first-party",
+    )) {
+      const candidate = proposed.members.find(
+        (member) => member.packageId === required.packageId,
+      );
+      if (!candidate) {
+        throw new Error(
+          `composition generation "${proposed.generationId}" omits required first-party Package "${required.packageId}"`,
+        );
+      }
+      if (candidate.provenance.kind !== "first-party") {
+        throw new Error(
+          `composition generation "${proposed.generationId}" replaces required first-party Package "${required.packageId}" with ${candidate.provenance.kind} provenance`,
+        );
+      }
+    }
+  }
+
   /**
    * The durable, visible record that quarantine had no last known good to fail
    * into. Written against the generation that was named last known good, whose

package/src/direct-tool-command.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import {
+  botTurnCommandFingerprintV1,
+  createStoredRunCodecV1,
+} from "./run-records.js";
+import { planBotRunRecovery } from "./run-recovery.js";
+
+describe("durable direct tool commands", () => {
+  const directTool = {
+    generationId: "generation-1",
+    packageId: "weather-page",
+    name: "weather_lookup",
+    input: { city: "Sydney" },
+  };
+
+  test("survives the exact stored-run codec for eviction recovery", () => {
+    const codec = createStoredRunCodecV1({
+      decodeRunId: (value) => {
+        if (typeof value !== "string") throw new Error("invalid");
+        return value;
+      },
+      decodeConfigurationSnapshot: (value) => value,
+    });
+    const run = codec.require({
+      runId: "command-1",
+      commandFingerprint: "fingerprint",
+      sessionId: "user:bot",
+      acceptedAt: "2026-09-02T00:00:00.000Z",
+      input: "Weather page · weather_lookup",
+      events: [],
+      effectAdmissions: [],
+      status: "running",
+      phase: "admitted",
+      compositionGenerationId: "generation-1",
+      configurationSnapshot: {},
+      previousEventCount: 0,
+      directTool,
+    });
+    expect(run.directTool).toEqual(directTool);
+  });
+
+  test("is part of the admitted command idempotency fingerprint", () => {
+    const base = {
+      userId: "user",
+      botId: "bot",
+      runId: "command-1",
+      sessionId: "user:bot",
+      acceptedAt: "2026-09-02T00:00:00.000Z",
+      text: "Weather page · weather_lookup",
+    };
+    expect(botTurnCommandFingerprintV1({ ...base, directTool })).not.toBe(
+      botTurnCommandFingerprintV1(base),
+    );
+  });
+
+  test("resumes after eviction without requiring a synthetic model request", () => {
+    const codec = createStoredRunCodecV1({
+      decodeRunId: (value) => {
+        if (typeof value !== "string") throw new Error("invalid");
+        return value;
+      },
+      decodeConfigurationSnapshot: (value) => value,
+    });
+    const run = codec.require({
+      runId: "command-1",
+      commandFingerprint: "fingerprint",
+      sessionId: "user:bot",
+      acceptedAt: "2026-09-02T00:00:00.000Z",
+      input: "Weather page · weather_lookup",
+      events: [],
+      effectAdmissions: [],
+      status: "running",
+      phase: "executing",
+      compositionGenerationId: "generation-1",
+      configurationSnapshot: {},
+      previousEventCount: 0,
+      directTool,
+    });
+    expect(planBotRunRecovery(run, [], codec)).toEqual({ kind: "resume" });
+  });
+});

package/src/run-records.ts

@@ -11,9 +11,9 @@ import {
  * The kernel records the Composition/configuration snapshot a Turn was admitted
  * under, but never interprets it: the owning Package supplies the decoder.
  */
-export interface StoredRunCodecOptionsV1 {
+export interface StoredRunCodecOptionsV1<Snapshot> {
   decodeRunId(value: unknown): string;
-  decodeConfigurationSnapshot(value: unknown): unknown;
+  decodeConfigurationSnapshot(value: unknown): Snapshot;
 }
 
 export interface StoredRunCodecV1<Snapshot> {
@@ -112,6 +112,15 @@ export interface StoredRunV1<Snapshot = unknown> {
   previousEventCount: number;
   /** Absent ⇒ the run was admitted as a `chat` Turn. */
   admission?: StoredRunAdmissionV1;
+  /** An ordinary admitted Turn whose only action is one caller-selected tool. */
+  directTool?: DirectToolCommandV1;
+}
+
+export interface DirectToolCommandV1 {
+  generationId: string;
+  packageId: string;
+  name: string;
+  input: unknown;
 }
 
 /** The subagent role a stored run re-mounts under, if any. */
@@ -185,6 +194,7 @@ const STORED_RUN_OPTIONAL_KEYS = [
   "failure",
   "stopRequestedAt",
   "admission",
+  "directTool",
 ] as const;
 const UTF8_ENCODER = new TextEncoder();
 
@@ -200,6 +210,44 @@ function boundedString(
   );
 }
 
+function decodeDirectToolCommandV1(value: unknown): DirectToolCommandV1 {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new Error("stored run has invalid direct tool command");
+  }
+  const candidate = value as Record<PropertyKey, unknown>;
+  const fields = ["generationId", "packageId", "name", "input"];
+  if (
+    Reflect.ownKeys(candidate).length !== fields.length ||
+    Object.keys(candidate).length !== fields.length ||
+    !fields.every((field) => Object.hasOwn(candidate, field)) ||
+    !boundedString(candidate.generationId, 256) ||
+    !boundedString(candidate.packageId, 64) ||
+    !boundedString(candidate.name, 64) ||
+    !/^[a-z][a-z0-9_]{0,63}$/.test(candidate.name)
+  ) {
+    throw new Error("stored run has invalid direct tool command fields");
+  }
+  let input: unknown;
+  try {
+    const encoded = JSON.stringify(candidate.input);
+    if (
+      encoded === undefined ||
+      UTF8_ENCODER.encode(encoded).byteLength > 64_000
+    ) {
+      throw new Error("invalid input");
+    }
+    input = JSON.parse(encoded) as unknown;
+  } catch {
+    throw new Error("stored run has invalid direct tool input");
+  }
+  return {
+    generationId: candidate.generationId,
+    packageId: candidate.packageId,
+    name: candidate.name,
+    input,
+  };
+}
+
 /**
  * Exact fields, per origin kind. Each kind gets its own branch rather than a
  * union of optional fields: a `routine` origin carrying a `taskId` is not a
@@ -374,7 +422,7 @@ function decodeStoredEffectAdmissions(value: unknown): StoredEffectAdmission[] {
 }
 
 export function createStoredRunCodecV1<Snapshot>(
-  options: StoredRunCodecOptionsV1,
+  options: StoredRunCodecOptionsV1<Snapshot>,
 ): StoredRunCodecV1<Snapshot> {
   const require = (input: unknown): StoredRunV1<Snapshot> =>
     requireStoredRunRecordV1(input, options);
@@ -386,7 +434,7 @@ export function createStoredRunCodecV1<Snapshot>(
 
 function requireStoredRunRecordV1<Snapshot>(
   input: unknown,
-  options: StoredRunCodecOptionsV1,
+  options: StoredRunCodecOptionsV1<Snapshot>,
 ): StoredRunV1<Snapshot> {
   if (!input || typeof input !== "object" || Array.isArray(input)) {
     throw new Error("stored run is invalid");
@@ -451,7 +499,9 @@ function requireStoredRunRecordV1<Snapshot>(
   ) {
     throw new Error(`run "${runId}" has no valid previous event count`);
   }
-  options.decodeConfigurationSnapshot(candidate.configurationSnapshot);
+  const configurationSnapshot = options.decodeConfigurationSnapshot(
+    candidate.configurationSnapshot,
+  );
   if (
     candidate.responseText !== undefined &&
     !boundedString(candidate.responseText, 64_000, true)
@@ -505,7 +555,7 @@ function requireStoredRunRecordV1<Snapshot>(
     status,
     phase,
     compositionGenerationId: candidate.compositionGenerationId,
-    configurationSnapshot: candidate.configurationSnapshot as Snapshot,
+    configurationSnapshot,
     previousEventCount: candidate.previousEventCount as number,
     ...(candidate.responseText === undefined
       ? {}
@@ -519,6 +569,9 @@ function requireStoredRunRecordV1<Snapshot>(
     ...(candidate.admission === undefined
       ? {}
       : { admission: decodeStoredRunAdmission(candidate.admission, runId) }),
+    ...(candidate.directTool === undefined
+      ? {}
+      : { directTool: decodeDirectToolCommandV1(candidate.directTool) }),
   };
 }
 
@@ -548,6 +601,7 @@ export interface BotTurnCommand {
    * command, so it must not collide on an idempotency record.
    */
   skills?: SkillRefV1[];
+  directTool?: DirectToolCommandV1;
 }
 
 /**
@@ -566,7 +620,8 @@ export function botTurnCommandFingerprintV1(
     turnType !== "chat" ||
     command.origin !== undefined ||
     command.subagentRole !== undefined ||
-    skills.length > 0
+    skills.length > 0 ||
+    command.directTool !== undefined
   ) {
     return `bot-turn-command-v2:${JSON.stringify({
       userId: command.userId,
@@ -577,6 +632,7 @@ export function botTurnCommandFingerprintV1(
       ...(command.subagentRole ? { subagentRole: command.subagentRole } : {}),
       ...(command.origin ? { origin: command.origin } : {}),
       ...(skills.length > 0 ? { skills: skills.map(formatSkillRefV1) } : {}),
+      ...(command.directTool ? { directTool: command.directTool } : {}),
     })}`;
   }
   return `bot-turn-command-v1:${JSON.stringify({

package/src/run-recovery.ts

@@ -97,6 +97,11 @@ export function planBotRunRecovery<Snapshot>(
         lastAssistant?.type === "assistant/message" ? lastAssistant.text : "",
     };
   }
+  // A direct tool Turn has no model request by construction. Its single
+  // synthetic assistant/tool occurrence is nevertheless resumable at every
+  // durable boundary: before intent it can start, after intent it reconciles,
+  // and after result it only needs its terminal events appended.
+  if (run.directTool) return { kind: "resume" };
   const modelState = latestModelRequestJournalState(run.events);
   if (modelState.status === "no-effect") {
     try {