@frockbot/kernel-do 0.3.12 → 0.3.14

package/package.json

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

package/src/authority.ts

@@ -34,6 +34,7 @@ import {
 import {
   eventsForFailedRun,
   latestModelRequestJournalState,
+  latestModelRequestProviderV1,
   planBotRunRecovery,
   type ProviderReconcilesV1,
   repairedSessionLogV1,
@@ -256,7 +257,7 @@ export class BotDurableAuthority<Snapshot> {
     // Turn is durable either way and the alarm retries it; admission now
     // refuses or supersedes on its own terms.
     await this.recoverActiveRun().catch(() => undefined);
-    const replay = await this.settledRunResult(command);
+    const replay = await this.settledReplayResult(command);
     if (replay) return replay;
     const admission = await this.acceptRun(command);
     if (admission.kind === "queued") {
@@ -496,7 +497,7 @@ export class BotDurableAuthority<Snapshot> {
       // followed 500'd on the half-repaired record. The run is durable and
       // terminal by this point, and its own record says why it ended, so the
       // caller is handed that record and reads the reason from the transcript.
-      const settled = await this.settledReconciliationResult(runId);
+      const settled = await this.settledTerminalRunResult(runId);
       if (settled) return settled;
       throw error;
     }
@@ -507,7 +508,7 @@ export class BotDurableAuthority<Snapshot> {
    * resolving has reached a terminal state — whatever that state turned out to
    * be. Anything still open is not this method's to answer for.
    */
-  private async settledReconciliationResult(
+  private async settledTerminalRunResult(
     runId: string,
   ): Promise<BotTurnCompletion | undefined> {
     const run = this.codec.optional(
@@ -607,7 +608,7 @@ export class BotDurableAuthority<Snapshot> {
           modelState.status === "unresolved") &&
         !runWasDiscardedV1(durableRun)
       ) {
-        await this.requireRunReconciliation(
+        const settled = await this.parkOrSettleUnresolvedRun(
           command.runId,
           previous,
           events,
@@ -615,10 +616,19 @@ export class BotDurableAuthority<Snapshot> {
             ? unresolvedModelRequestFailure(events, modelState.request)
             : message,
         );
+        if (settled) return settled;
         throw new Error(message);
       }
       await this.failRun(command.runId, previous, events, message);
-      const settled = await this.discardedRunResult(command.runId);
+      // `settledTerminalRunResult`, not `discardedRunResult`: a Turn the Package failed
+      // outright — a provider 401, a step limit — reaches a `turn/end` and a
+      // durable `failed` record just as surely as a stopped one does, and
+      // rethrowing over the top of that settlement is what made the Worker log
+      // `Uncaught Error: Bot turn ended with outcome model-error: Model request
+      // failed (401)` and answer 500. The run is terminal by this point and its
+      // record says why; the caller is handed that record and the client reads
+      // the sentence for the outcome off it.
+      const settled = await this.settledTerminalRunResult(command.runId);
       if (settled) return settled;
       throw new Error(message);
     } finally {
@@ -748,7 +758,7 @@ export class BotDurableAuthority<Snapshot> {
           modelState.status === "unresolved") &&
         !runWasDiscardedV1(durableRun)
       ) {
-        await this.requireRunReconciliation(
+        const parked = await this.parkOrSettleUnresolvedRun(
           run.runId,
           previous,
           events,
@@ -756,10 +766,11 @@ export class BotDurableAuthority<Snapshot> {
             ? unresolvedModelRequestFailure(events, modelState.request)
             : message,
         );
+        if (parked) return parked;
         throw new Error(message);
       }
       await this.failRun(run.runId, previous, events, message);
-      const settled = await this.discardedRunResult(run.runId);
+      const settled = await this.settledTerminalRunResult(run.runId);
       if (settled) return settled;
       throw new Error(message);
     } finally {
@@ -783,7 +794,7 @@ export class BotDurableAuthority<Snapshot> {
     });
   }
 
-  private async settledRunResult(
+  private async settledReplayResult(
     command: OwnedBotTurnCommand,
   ): Promise<BotTurnCompletion | undefined> {
     const { runId } = command;
@@ -1728,6 +1739,48 @@ export class BotDurableAuthority<Snapshot> {
     });
   }
 
+  /**
+   * Settles a Turn whose model outcome is unknown, or parks it when somebody
+   * can still be asked — and never lets the uncertainty escape as a throw.
+   *
+   * This is ADR 0028 applied to the live path. Recovery already refuses to park
+   * a run whose provider offers no retrieval, because parking there is not
+   * caution but a dead end; the executing path did not, and the asymmetry is
+   * what produced the blocker. A model request that ran past its budget threw
+   * out of the Agent as an uncertain outcome, this method's predecessor parked
+   * the run and rethrew, and the `POST /turns` the composer was holding open
+   * answered 500 — so the person read "Couldn't reach the Bot. Check your
+   * connection", which blamed their network for a model that took too long,
+   * and the Bot stayed wedged behind a banner whose only possible resolution
+   * was the settlement we could have written here.
+   *
+   * When the provider does reconcile, nothing changes: the run parks, the
+   * caller still rethrows, and a later attempt can genuinely retrieve the
+   * effect. Uncertainty is never assumed away in either branch — the request is
+   * not re-sent, and every streamed word stays in the journal.
+   *
+   * Returns the settled completion when it settled, `undefined` when it parked.
+   */
+  private async parkOrSettleUnresolvedRun(
+    runId: string,
+    previous: SessionEvent[],
+    events: SessionEvent[],
+    reason: string,
+  ): Promise<BotTurnCompletion | undefined> {
+    const provider = latestModelRequestProviderV1(events);
+    const reconciles = this.hooks.providerReconciles ?? (() => true);
+    if (provider === undefined || reconciles(provider)) {
+      await this.requireRunReconciliation(runId, previous, events, reason);
+      return undefined;
+    }
+    // `failRun` runs the ordinary terminal settlement: the open Turn is closed
+    // with a `turn/end`, the partial text is kept, and the record carries the
+    // reason. The reason is a diagnostic for the debug surface — what the
+    // person reads is the client's own copy for the outcome.
+    await this.failRun(runId, previous, events, reason);
+    return this.settledTerminalRunResult(runId);
+  }
+
   /**
    * Starts the Turn that was waiting when the object last stopped.
    *

package/src/model-timeout-settlement.test.ts

@@ -0,0 +1,265 @@
+// A model request that ran out of time settles the Turn instead of escaping.
+//
+// The blocker this file describes: a tool-heavy step against a real Flock AI
+// model crossed the gateway's sixty-second budget, the abort surfaced out of
+// the Agent as `Model response outcome is uncertain: The operation was aborted
+// due to timeout`, the authority parked the run on a reconciliation and
+// rethrew — and the `POST /api/bots/<bot>/turns` the composer was holding open
+// answered 500 after 65 seconds. On screen: "Couldn't reach the Bot. Check your
+// connection and try again", blaming a network that was fine, over a Bot that
+// stayed wedged behind a banner nothing could ever resolve.
+//
+// ADR 0028 already settled the question for recovery: park only when somebody
+// can be asked, and Flock AI keeps no addressable copy of a completion, so
+// nobody can. This is that rule on the live path.
+import { describe, expect, test } from "bun:test";
+import {
+  bootstrapGeneration,
+  type CompositionGenerationV1,
+} from "@frockbot/kernel-composition/generation";
+import {
+  MODEL_FIRST_BYTE_DEADLINE_REASON_V1,
+  type SessionEvent,
+} from "@frockbot/kernel-contracts";
+import {
+  BotDurableAuthority,
+  type BotDurableAuthorityHooks,
+  type OwnedBotTurnCommand,
+} from "./authority.ts";
+import { MemoryStorage } from "./memory-storage.fixture.ts";
+import {
+  BotTurnExecutionError,
+  BotTurnReconciliationRequiredError,
+} from "./turn-errors.ts";
+import { createStoredRunCodecV1, type StoredRunV1 } from "./run-records.ts";
+
+const codec = createStoredRunCodecV1<undefined>({
+  decodeRunId: (value) => value as string,
+  decodeConfigurationSnapshot: () => undefined,
+});
+
+const identity = { userId: "user-1", botId: "primary" };
+const SESSION_ID = "user-1:primary";
+
+/** Providers that keep an addressable copy of a completion. Neither does. */
+const RECONCILING_PROVIDERS = new Set(["foundation"]);
+
+function bootstrap(): Promise<CompositionGenerationV1> {
+  return bootstrapGeneration(
+    [
+      {
+        packageId: "shell",
+        specifier: "@frockbot/plugin-shell",
+        version: "0.0.1",
+        manifest: { id: "shell", version: "0.0.1" },
+      },
+    ],
+    { createdAt: "2026-09-03T00:00:00.000Z" },
+  );
+}
+
+function command(runId: string, text: string): OwnedBotTurnCommand {
+  return {
+    ...identity,
+    runId,
+    sessionId: SESSION_ID,
+    acceptedAt: "2026-09-03T00:00:01.000Z",
+    text,
+  };
+}
+
+/**
+ * An authority whose Package stalls its model request past the budget: it
+ * journals the request, streams a first line, then unwinds exactly as the
+ * Agent loop does on a deadline — a `model/reconciliation-required` carrying
+ * the deadline's own sentence, and no `turn/end`.
+ */
+function createAuthority(
+  storage: MemoryStorage,
+  provider: string,
+  options: { providerReconciles?: boolean; refuseWith?: string } = {},
+): BotDurableAuthority<undefined> {
+  const hooks: BotDurableAuthorityHooks<undefined> = {
+    resolveAdmissionSnapshot: () => Promise.resolve(undefined),
+    bootstrapComposition: () => bootstrap(),
+    admittedSnapshot: () => Promise.resolve(undefined),
+    ...(options.providerReconciles === undefined
+      ? { providerReconciles: (id: string) => RECONCILING_PROVIDERS.has(id) }
+      : { providerReconciles: () => options.providerReconciles as boolean }),
+    executeTurn: async (input) => {
+      let seq = input.previousEvents.length;
+      const appended: SessionEvent[] = [];
+      const persist = async (
+        ...events: Omit<SessionEvent, "seq" | "timestamp">[]
+      ) => {
+        const stamped = events.map(
+          (event) =>
+            ({
+              ...event,
+              seq: seq++,
+              timestamp: "2026-09-03T00:00:10.000Z",
+            }) as SessionEvent,
+        );
+        appended.push(...stamped);
+        await input.persistSessionEvents(input.command.sessionId, stamped);
+      };
+      await persist(
+        { type: "turn/start", turn: 1 } as never,
+        { type: "step/start", turn: 1, step: 1 } as never,
+        {
+          type: "user/message",
+          turn: 1,
+          step: 1,
+          messageId: "message-1",
+          text: input.command.text,
+        } as never,
+        {
+          type: "model/request",
+          turn: 1,
+          step: 1,
+          request: {
+            requestId: "request-1",
+            provider,
+            model: "@flock/auto",
+            system: "system",
+            messages: [{ role: "user", content: input.command.text }],
+            tools: [],
+          },
+        } as never,
+        {
+          type: "assistant/chunk",
+          turn: 1,
+          step: 1,
+          requestId: "request-1",
+          text: "On it — building it now.",
+        } as never,
+      );
+      // A provider that refused definitively — a revoked key answering 401 —
+      // reaches a real `turn/end`, the way the Agent loop settles a model
+      // error it never has to reconcile.
+      if (options.refuseWith) {
+        await persist(
+          {
+            type: "model/effect-not-started",
+            turn: 1,
+            step: 1,
+            requestId: "request-1",
+            reason: options.refuseWith,
+          } as never,
+          {
+            type: "step/end",
+            turn: 1,
+            step: 1,
+            outcome: "model-error",
+          } as never,
+          {
+            type: "turn/end",
+            turn: 1,
+            outcome: "model-error",
+            reason: options.refuseWith,
+          } as never,
+        );
+        throw new BotTurnExecutionError(
+          `Bot turn ended with outcome model-error: ${options.refuseWith}`,
+          appended,
+        );
+      }
+      const reason = `Model response outcome is uncertain: ${MODEL_FIRST_BYTE_DEADLINE_REASON_V1}`;
+      await persist({
+        type: "model/reconciliation-required",
+        turn: 1,
+        step: 1,
+        requestId: "request-1",
+        reason,
+      } as never);
+      throw new BotTurnReconciliationRequiredError(reason, appended);
+    },
+    notification: () => undefined,
+    scheduledDeadlines: () => Promise.resolve([]),
+    scheduledWorkInFlight: () => false,
+    deferScheduledWork: () => Promise.resolve(),
+    settleScheduledWork: () => Promise.resolve(),
+    interruptTurn: () => {},
+  };
+  return new BotDurableAuthority<undefined>({
+    state: { storage } as unknown as DurableObjectState,
+    codec,
+    hooks,
+  });
+}
+
+function storedRun(
+  storage: MemoryStorage,
+  runId: string,
+): StoredRunV1<undefined> {
+  return codec.require(storage.values.get(`run:${runId}`));
+}
+
+describe("a model request that ran out of time", () => {
+  test("settles the Turn and answers the caller instead of throwing", async () => {
+    const storage = new MemoryStorage();
+    const authority = createAuthority(storage, "flock-ai");
+
+    // The `POST /turns` the composer is holding open. It resolves — this is
+    // the whole defect: it used to reject, and the route answered 500.
+    const completion = await authority.run(command("run-1", "build me one"));
+
+    expect(completion.runId).toBe("run-1");
+    const run = storedRun(storage, "run-1");
+    expect(run.status).toBe("failed");
+    // The ordinary run-terminal path: the open Turn is closed rather than left
+    // for the next message to trip over.
+    const terminal = run.events.findLast((event) => event.type === "turn/end");
+    expect(terminal).toMatchObject({ turn: 1, outcome: "interrupted" });
+    // The words the person watched arrive are kept.
+    expect(run.events.some((event) => event.type === "assistant/chunk")).toBe(
+      true,
+    );
+    // The stored reason is the diagnostic, and it carries the sentence the
+    // client's copy layer reads back out of it.
+    expect(run.failure).toContain(MODEL_FIRST_BYTE_DEADLINE_REASON_V1);
+    // Nothing is left holding the Bot: the next message is admitted.
+    expect(storage.values.get("active-run")).toBeUndefined();
+  });
+
+  test("still parks when the provider can actually be asked", async () => {
+    const storage = new MemoryStorage();
+    const authority = createAuthority(storage, "foundation");
+
+    // A provider that keeps a durable copy loses nothing by waiting, so the
+    // uncertainty is preserved exactly as before and the caller still learns
+    // the Turn did not settle.
+    await expect(
+      authority.run(command("run-1", "build me one")),
+    ).rejects.toThrow();
+
+    const run = storedRun(storage, "run-1");
+    expect(run.status).toBe("reconciliation-required");
+    expect(run.events.some((event) => event.type === "turn/end")).toBe(false);
+  });
+
+  // The same leak, one layer over: a Turn that reached a real `turn/end` and a
+  // durable `failed` record was *still* rethrown, so the Worker logged
+  // `Uncaught Error: Bot turn ended with outcome model-error: Model request
+  // failed (401)` and the route answered 500 over a settlement that had
+  // already happened.
+  test("a provider that refused settles and answers, with no uncaught error", async () => {
+    const storage = new MemoryStorage();
+    const authority = createAuthority(storage, "flock-ai", {
+      refuseWith: "Model request failed (401)",
+    });
+
+    const completion = await authority.run(command("run-1", "hello"));
+
+    expect(completion.runId).toBe("run-1");
+    const run = storedRun(storage, "run-1");
+    expect(run.status).toBe("failed");
+    expect(
+      run.events.findLast((event) => event.type === "turn/end"),
+    ).toMatchObject({ outcome: "model-error" });
+    // The provider's own words stay on the record for the debug surface; the
+    // client maps the outcome to a sentence (`runFailureCopyV1`).
+    expect(run.failure).toContain("401");
+    expect(storage.values.get("active-run")).toBeUndefined();
+  });
+});