stitchkit 0.68.4 → 0.68.6

package/dist/testing.js

@@ -1,7 +1,7 @@
 import {
   AgentMessageSchema,
   AgentRunSchema
-} from "./index-fhsmrzj7.js";
+} from "./index-ysphyxax.js";
 import {
   createApplication
 } from "./index-6wzr93cg.js";
@@ -25,7 +25,7 @@ import {
 import {
   createClient,
   createClients
-} from "./index-thcy3w8c.js";
+} from "./index-n34x0q5e.js";
 import"./index-r5s4wqb5.js";
 import {
   joinRoutePath
@@ -145,7 +145,14 @@ function requireOutcome(actual, expected) {
 async function runAgentStoreConformance(config) {
   const run = `conformance-${crypto.randomUUID()}`;
   const context = {
-    conversationIds: [run, `${run}-recovery`, `${run}-absorb`, `${run}-causal-history`]
+    conversationIds: [
+      run,
+      `${run}-recovery`,
+      `${run}-absorb`,
+      `${run}-causal-history`,
+      `${run}-causal-active`,
+      `${run}-interrupt-priority`
+    ]
   };
   const store = await config.createStore(context);
   let failure;
@@ -169,10 +176,12 @@ async function conformanceScenario(store, conversationIds) {
     conversationId,
     recoveryConversationId,
     absorbConversationId,
-    causalHistoryConversationId
+    causalHistoryConversationId,
+    causalActiveConversationId,
+    interruptPriorityConversationId
   ] = conversationIds;
-  if (!conversationId || !recoveryConversationId || !absorbConversationId || !causalHistoryConversationId) {
-    throw new Error("Agent store conformance requires four conversation identities");
+  if (!conversationId || !recoveryConversationId || !absorbConversationId || !causalHistoryConversationId || !causalActiveConversationId || !interruptPriorityConversationId) {
+    throw new Error("Agent store conformance requires six conversation identities");
   }
   const absentConversationId = `${conversationId}-absent`;
   const firstInput = userMessage(conversationId, "input-1");
@@ -554,8 +563,110 @@ async function conformanceScenario(store, conversationIds) {
     throw new Error("Abandon recovery did not atomically terminalize its assistant record");
   }
   await assertCausalHistoryOrder(store, causalHistoryConversationId);
+  await assertActiveRunCausalOrder(store, causalActiveConversationId);
+  await assertInterruptPriorityOrder(store, interruptPriorityConversationId);
   await assertAbsorptionIsAtomic(store, absorbConversationId);
 }
+async function assertInterruptPriorityOrder(store, conversationId) {
+  const inputs = ["priority-a", "priority-b", "priority-c"].map((id) => userMessage(conversationId, id));
+  const [inputA, inputB, inputC] = inputs;
+  if (!inputA || !inputB || !inputC)
+    throw new Error("Priority fixture is incomplete");
+  const runA = queuedRun(conversationId, inputA.id, "priority-run-a");
+  const runB = queuedRun(conversationId, inputB.id, "priority-run-b");
+  const runC = AgentRunSchema.parse({
+    ...queuedRun(conversationId, inputC.id, "priority-run-c"),
+    queuePriority: "interrupt-next"
+  });
+  requireOutcome(await store.acceptInputAndAssignRun({ idempotencyKey: runA.id, input: inputA, run: runA }), "applied");
+  const acquiredA = await store.acquireRun({
+    conversationId,
+    runId: runA.id,
+    expectedRevision: runA.revision,
+    ownerId: "priority-owner-a"
+  });
+  requireOutcome(acquiredA, "applied");
+  const runningA = acquiredA.snapshot.runs.find((run) => run.id === runA.id);
+  if (!runningA)
+    throw new Error("Priority lead run disappeared after acquisition");
+  requireOutcome(await store.acceptInputAndAssignRun({ idempotencyKey: runB.id, input: inputB, run: runB }), "applied");
+  requireOutcome(await store.acceptInputAndAssignRun({ idempotencyKey: runC.id, input: inputC, run: runC }), "applied");
+  const active = await store.listActiveRuns(conversationId);
+  if (active.map((run) => run.id).join(",") !== `${runA.id},${runC.id},${runB.id}`) {
+    throw new Error("Active runs did not place urgent work before ordinary pending work");
+  }
+  requireOutcome(await store.acquireRun({
+    conversationId,
+    runId: runB.id,
+    expectedRevision: runB.revision,
+    ownerId: "priority-owner-b"
+  }), "conflict");
+  const abandonedA = await store.recoverRun({
+    conversationId,
+    runId: runA.id,
+    expectedRevision: runningA.revision,
+    action: "abandon"
+  });
+  requireOutcome(abandonedA, "applied");
+  const queuedC = abandonedA.snapshot.runs.find((run) => run.id === runC.id);
+  if (!queuedC)
+    throw new Error("Urgent run disappeared after predecessor settlement");
+  const acquiredC = await store.acquireRun({
+    conversationId,
+    runId: runC.id,
+    expectedRevision: queuedC.revision,
+    ownerId: "priority-owner-c"
+  });
+  requireOutcome(acquiredC, "applied");
+  const runningC = acquiredC.snapshot.runs.find((run) => run.id === runC.id);
+  if (!runningC)
+    throw new Error("Urgent run disappeared after acquisition");
+  requireOutcome(await store.acquireRun({
+    conversationId,
+    runId: runB.id,
+    expectedRevision: runB.revision,
+    ownerId: "priority-owner-b"
+  }), "conflict");
+  const abandonedC = await store.recoverRun({
+    conversationId,
+    runId: runC.id,
+    expectedRevision: runningC.revision,
+    action: "abandon"
+  });
+  requireOutcome(abandonedC, "applied");
+  const queuedB = abandonedC.snapshot.runs.find((run) => run.id === runB.id);
+  if (!queuedB)
+    throw new Error("Ordinary run disappeared after urgent settlement");
+  const acquiredB = await store.acquireRun({
+    conversationId,
+    runId: runB.id,
+    expectedRevision: queuedB.revision,
+    ownerId: "priority-owner-b"
+  });
+  requireOutcome(acquiredB, "applied");
+  const ordered = acquiredB.snapshot.runs.map((run) => run.id).join(",");
+  if (ordered !== `${runA.id},${runC.id},${runB.id}`) {
+    throw new Error(`Durable execution order was not preserved: ${ordered}`);
+  }
+  const [sequenceA, sequenceC, sequenceB] = acquiredB.snapshot.runs.map((run) => run.executionSequence);
+  if (sequenceA === undefined || sequenceC === undefined || sequenceB === undefined || !(sequenceA < sequenceC && sequenceC < sequenceB)) {
+    throw new Error("Acquisition did not persist increasing execution sequence values");
+  }
+}
+async function assertActiveRunCausalOrder(store, conversationId) {
+  for (const id of ["z-causal-run", "a-causal-run"]) {
+    const input = userMessage(conversationId, `${id}-input`);
+    requireOutcome(await store.acceptInputAndAssignRun({
+      idempotencyKey: id,
+      input,
+      run: queuedRun(conversationId, input.id, id)
+    }), "applied");
+  }
+  const active = await store.listActiveRuns(conversationId);
+  if (active.map((run) => run.id).join(",") !== "z-causal-run,a-causal-run") {
+    throw new Error("listActiveRuns must preserve causal history order for timestamp ties");
+  }
+}
 async function assertCausalHistoryOrder(store, conversationId) {
   const leadInput = userMessage(conversationId, "causal-input-1");
   const leadRun = queuedRun(conversationId, leadInput.id, "causal-run-1");

package/llms-full.txt

@@ -61,6 +61,7 @@ own, recorded as an ADR.
 | `stitchkit/react` | browser | stable | `createCursorQuery`, `createCacheBridge` |
 | `stitchkit/agent-runtime` | server | evolving<br>_redefined in 9 of the 13 minors since 0.56.2, most recently 0.66.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
+| `stitchkit/agent-runtime/browser` | browser + server | evolving | canonical agent records, events and reconnect cursor without execution or sinks |
 | `stitchkit/application` | server | evolving<br>_redefined in 3 of the 13 minors since 0.56.2, most recently 0.67.0_ | managed resource graph, readiness, admission, schedules and bounded shutdown |
 | `stitchkit/application/grammy` | server | evolving | isolated grammY polling and webhook lifecycle adapters |
 | `stitchkit/application/opentelemetry` | server | evolving | maps application snapshots onto an injected OpenTelemetry `Meter` |
@@ -2428,6 +2429,13 @@ wire `end` frame and, when declared, at least one matching terminal item; EOF is
 converge on the request operation. See the
 [server half](./server.md#contract-first-streams). → ADR 0117.
 
+The request deadline bounds the wait for response headers. Once headers arrive,
+that timer is cleared, while the caller signal remains attached to the response
+body until it ends or is cancelled. This is the same for a Fetch-config client,
+`createHttpClient`, the Bun-only `unix` convenience and an injected portable
+Unix transport. Cancelling a quiet stream therefore releases its server source
+and transport connection instead of only settling the local iterator.
+
 An established NDJSON protocol may keep its item schema as the complete wire
 frame. This mode requires a terminal item because an unwrapped response has no
 separate safe error/end envelope:
@@ -3742,6 +3750,21 @@ If the application already owns that loop, continue importing `mountAgent` from
 this entrypoint uses the tool executor from it, but pulls no MCP peer, so
 choosing `mountAgent` alone costs you nothing from here.
 
+UI and shared DTO code must import canonical records and delivery validation from
+`stitchkit/agent-runtime/browser`, not from the server runtime barrel:
+
+```ts
+import {
+  AgentRunSchema,
+  AgentRuntimeEventSchema,
+  advanceAgentRuntimeEventCursor,
+} from 'stitchkit/agent-runtime/browser'
+```
+
+This browser-safe entrypoint re-exports the same schemas and inferred types used
+by the runtime. It intentionally excludes model construction, execution,
+persistence, event sinks and every Node context dependency.
+
 ## Install
 
 ```sh
@@ -3941,15 +3964,22 @@ input + queued run → running → execution settled → terminal CAS → succes
 
 ## What happens to a run when new input arrives
 
-`runs.inputPolicy` decides. It takes four values, or a function returning one:
+`runs.inputPolicy` decides. It takes five values, or a function returning one:
 
 | policy | the run in flight | what it already produced |
 |--------|-------------------|--------------------------|
 | `queue` (default) | finishes first | kept |
 | `inject` | continues, and answers the new input too | kept, and built on |
 | `interrupt` | ends | kept, and marked as cut off |
+| `interrupt-next` | ends; this input runs before ordinary queued work | kept, and marked as cut off |
 | `supersede` | ends | discarded from the prompt, kept in the record |
 
+`interrupt-next` is the explicit priority path for an urgent input. If A is
+running, ordinary B is queued, and urgent C arrives, the coordinator aborts A,
+waits for A to settle and then runs C before B. B keeps its durable identity and
+eventually runs. Urgent inputs remain FIFO among themselves. They do not
+coalesce into an ordinary pending run: that would erase the priority boundary.
+
 `interrupt` and `supersede` differ in exactly one thing, and the question that
 picks between them is **not** "was the run interrupted" but **"did anyone see
 what it produced"**:
@@ -4190,12 +4220,20 @@ checkpoint/terminal CAS and tool context, so a distributed adapter can reject an
 an owner label is reused. Lease expiry and renewal remain application-owned.
 
 On startup, `runtime.recover({ resolveContext })` consumes bounded lightweight
-pages. Its safe default resumes queued runs and reports acquired or
+pages, then restores each conversation's durable execution order before any run
+acquires. Persisted `executionSequence` orders work that started; queued
+`interrupt-next` work precedes ordinary queued work with FIFO preserved inside
+each class. Scan identifiers, equal timestamps and page boundaries therefore
+never become queue order. Its safe default resumes queued runs and reports acquired or
 `interrupt_requested` runs as skipped. A policy may requeue acquired work only
 with explicit replay-safe evidence, or abandon it only with stale-owner
-evidence. Each attempted run returns its own outcome/error; `pageSize`,
-`maxRuns`, and `signal` bound the pass. `runtime.resume(...)` remains available
-for one known queued record.
+evidence. Each attempted run returns its own outcome/error; a `resumed` or
+`requeued` outcome also exposes the terminal `result` promise. The outcome is
+reported only after durable acquisition, so a lost acquisition is `failed`
+rather than a successful-looking handoff. `pageSize`, `maxRuns`, and `signal`
+bound the pass. `runtime.resume(...)` remains available for one known queued
+record; its `accepted` promise likewise means that the recovered run acquired
+durable ownership, while `result` carries terminal completion.
 
 Canonical records currently write `schemaVersion: 1`. A durable adapter owns
 read-time migration of older rows: migrate to the current shape at its storage
@@ -4470,7 +4508,8 @@ outbox.
 `createAgentRaceTrace`. Barriers have bounded teardown, traces assert exact partial order, and the
 helpers are exercised from packed Bun and Node consumers. `runAgentStoreConformance` runs duplicate,
 coalescing, collision, stale checkpoint, replay safety, terminal race, absorption, bounded reads,
-causal queued-history order, compaction and recovery invariants against any fresh durable adapter.
+causal queued-history order, durable interrupt priority, compaction and recovery invariants against
+any fresh durable adapter.
 
 It picks its conversation identities itself and passes them to `createStore(context)` **before the
 first mutation**, so an adapter whose runtime rows reference an application-owned conversation row
@@ -11495,6 +11534,7 @@ Server-only optional application runtime. See the
 | `defineAgentProtocol` | function | declare context, input metadata, canonical parts and optional pre-CAS terminal acceptance (`allow-empty`, `require-output` or callback) |
 | `hasAgentTerminalOutput` | function | generic `require-output` predicate for non-blank text, generated files, structured provider parts and explicit tool-only policy stops |
 | `AgentMessageSchema` / `AgentRunSchema` / `AgentSnapshotSchema` | schema | versioned canonical engine records |
+| `AgentRunQueuePrioritySchema` | schema | durable opt-in priority for queued `interrupt-next` runs |
 | `AgentRuntimeStore` | _type_ | aggregate CAS transaction boundary for message, run and compaction mutations |
 | `createAgentRuntimeStore` | function | build the aggregate store from one coherent transaction driver; framework owns every state transition |
 | `AgentRuntimeStoreDriver` | _type_ | ORM-neutral transaction over a bounded head, normalized runs/admissions, product history and indexed run recovery |
@@ -11516,7 +11556,7 @@ Server-only optional application runtime. See the
 | `AgentRuntimeAdmission` | _type_ | canonical committed input, assigned run, pending assistant projection, compatibility IDs and snapshot version |
 | `AgentAdmissionEventSchema` | schema | post-commit admission projection; removes store rereads but does not imply exactly-once delivery |
 | `AgentRunMetricsSchema` | schema | optional provenance-aware usage and timings; `partial` says the provider never reported the run finished, so the figure beside it is not a confirmed total |
-| `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with context resolver and explicit evidence policy |
+| `AgentRuntimeRecoverOptions` | _type_ | bounded paged startup recovery with causal per-conversation scheduling, context resolver and explicit evidence policy |
 | `AgentRuntimeConflictError` | class | thrown when a store mutation loses to a concurrent writer — catchable by type from `stitchkit/agent-runtime` |
 | `AgentSessionCloseOptions` | _type_ | `gracePeriodMs` for natural settlement, then abort, then `forceTimeoutMs` for bounded settlement after it |
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
@@ -11544,7 +11584,8 @@ Canonical protocol exports are `AgentProtocol`, `AgentProtocolConfig`, `AgentTer
 `AgentToolCallPartSchema`, `AgentToolResultPartSchema`, `AgentOpaquePartSchema`,
 `AgentControlPartSchema`, `AgentMessageRoleSchema`, `AgentMessageStatusSchema`, `AgentMessage`,
 `AgentAssistantPlaceholderSchema`, `AgentAssistantPlaceholder`, `AgentRunStateSchema`,
-`AgentTerminalReasonSchema`, `AgentTerminalReason`, `AgentRun`, `AgentSnapshot`,
+`AgentTerminalReasonSchema`, `AgentTerminalReason`, `AgentRunQueuePrioritySchema`,
+`AgentRunQueuePriority`, `AgentRun`, `AgentSnapshot`,
 `AgentUsageValueSchema`, `AgentCostValueSchema`, `AgentUsageSchema`, `AgentUsage` and
 `AgentRunMetrics`.
 
@@ -11560,7 +11601,7 @@ integer — `AgentUsageValueSchema` and `AgentTokenCountSchema` refuse a fractio
 provider figure that is not a whole number is normalised to `unavailable` rather than thrown.
 `AgentCostValueSchema.value` stays fractional, because money is.
 
-`runs.inputPolicy` takes `queue` (default), `inject`, `interrupt` or `supersede`, or a function of
+`runs.inputPolicy` takes `queue` (default), `inject`, `interrupt`, `interrupt-next` or `supersede`, or a function of
 the raw input returning one. `inject` lets a run in flight take a newly arrived input into its prompt
 at a step boundary and answer it too; the absorption is committed in the **same transaction** as that
 run's terminal record, via `CommitRunTerminal.absorb`, so a run that ends any other way leaves an
@@ -11569,6 +11610,12 @@ ordinary queued successor. The absorbed run ends with `terminalReason: 'absorbed
 its own**; a submission on its idempotency key resolves through that pointer to the answer
 (→ ADR 0113).
 
+`interrupt-next` interrupts the active run, waits for its real settlement and then executes the new
+input before ordinary pending work. Ordinary work is not dropped or re-admitted, and urgent work is
+FIFO within its own class. `AgentRun.queuePriority` persists the pending class;
+`AgentRun.executionSequence` persists the actual first-acquisition order, so recovery and canonical
+history preserve the same `A → C → B` order across equal timestamps and scan pages (→ ADR 0127).
+
 With `queue`, a durable successor admission is not prompt eligibility: the current executor sees
 only records through its own run boundary. Snapshot history is normalized to causal turn order
 (assigned input(s), assistant, then successor input(s)) even when the storage codec physically
@@ -11577,7 +11624,7 @@ appended the successor before the predecessor checkpoint.
 `AgentRuntimeStore` has two **bounded** reads beside `loadSnapshot`:
 `loadRun({ conversationId, runId })` returns an `AgentRunView` — the run, the conversation version it
 was read at, and the retained answer once the run is terminal — or `undefined`; `listActiveRuns(conversationId)`
-returns the runs that have not ended, ordered by `createdAt` then `id`. Neither reads history, so
+returns the runs that have not ended in durable execution/priority order. Neither reads history, so
 neither grows with the length of the conversation, and neither needs anything new from
 `AgentRuntimeStoreDriver`. `loadSnapshot` and every mutation result still carry the whole
 conversation — that is what the store's reducer validates against, and what the runtime builds a
@@ -11629,6 +11676,20 @@ Managed effects and operator telemetry additionally export `AgentToolFenceConfig
 may accompany checkpoint/terminal writes and tool context; internal causes are redacted unless an
 operator-only observability sink explicitly opts in.
 
+## `stitchkit/agent-runtime/browser`
+
+Browser-safe canonical agent data. It re-exports the run, message, part, usage,
+terminal and provider-envelope schemas/types listed under
+`stitchkit/agent-runtime`, together with all runtime delivery event schemas,
+`AgentRuntimeEventCursorSchema`, `advanceAgentRuntimeEventCursor` and
+`agentDurableEventId`. It imports no model provider, executor, store, event sink
+or Node context module.
+
+Use this entrypoint from client components and shared DTO packages. The full
+`stitchkit/agent-runtime` entrypoint remains server-only.
+
+---
+
 ## `stitchkit/agent-runtime/openrouter`
 
 | Export | Kind | Summary |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.68.4",
+  "version": "0.68.6",
   "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
   "keywords": [
     "bun",
@@ -84,6 +84,10 @@
       "types": "./dist/agent-runtime.d.ts",
       "import": "./dist/agent-runtime.js"
     },
+    "./agent-runtime/browser": {
+      "types": "./dist/agent-runtime-browser.d.ts",
+      "import": "./dist/agent-runtime-browser.js"
+    },
     "./agent-runtime/openrouter": {
       "types": "./dist/agent-runtime-openrouter.d.ts",
       "import": "./dist/agent-runtime-openrouter.js"
@@ -122,7 +126,7 @@
   },
   "scripts": {
     "check": "bun x tsc --noEmit",
-    "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts src/declaration.ts --outdir dist --target node --packages external --splitting --root src",
+    "build:browser": "bun build src/index.ts src/react.ts src/contract/index.ts src/declaration.ts src/agent-runtime-browser.ts --outdir dist --target node --packages external --splitting --root src",
     "build:server": "bun build src/server/index.ts src/node.ts src/tools.ts src/tool-invoker.ts src/cli.ts src/remote.ts src/files.ts src/testing.ts src/observability/index.ts src/agent-runtime.ts src/agent-runtime-openrouter.ts src/application.ts src/application-grammy.ts src/application-opentelemetry.ts --outdir dist --target node --packages external --splitting --root src",
     "build:js": "bun run build:browser && bun run build:server && bun scripts/preserve-webpack-ignore.mjs",
     "build:types": "bun x tsc -p tsconfig.build.json --emitDeclarationOnly && bun scripts/rewrite-declaration-specifiers.mjs",