stitchkit 0.84.1 → 0.85.1

package/llms-full.txt

@@ -63,11 +63,11 @@ own, recorded as an ADR.
 | `stitchkit/tracking/server` | server (Bun or Node) | evolving | the decisions a tracking backend makes — dispositions, visit lease over an application-owned store, active intervals, presence; no database |
 | `stitchkit/release` | browser **and** server | evolving | a page follows the release it was built for — `createReleaseMarker` on the server, `createReleaseWatcher` in the browser, the `X-Build-Id` header and a socket event between them |
 | `stitchkit/geo` | server (Bun or Node) | evolving | managed GeoIP reader generations, last-known-good reload and the optional MaxMind adapter |
-| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 29 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
+| `stitchkit/observability` | server | stable<br>_redefined in 1 of the 30 minors since 0.56.2, most recently 0.83.0_ | request/tool event projections — `createObservability`, trace context, sanitisation |
 | `stitchkit/testing` | tests on Bun or Node | stable | in-process generated clients over a real Fetch handler, plus the store and managed-resource conformance kits |
 | `stitchkit/declaration` | browser + build and deployment tooling (Bun or Node) | evolving | `ProjectDeclarationSchema` — the one machine-readable statement a repository makes about itself |
 | `stitchkit/react` | browser + server rendering | stable | `createCursorQuery`, `createCacheBridge`, QueryClient and `ApiError` retry policy |
-| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 15 of the 29 minors since 0.56.2, most recently 0.84.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 16 of the 30 minors since 0.56.2, most recently 0.85.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/harness` | server | evolving | resource-aware process-local facade over the canonical Agent runtime; supervision stays outside |
 | `stitchkit/agent-runtime/coding-tools` | server (Bun or Node) | evolving | bounded host-authorized direct file and shell tools; a root boundary, not an OS sandbox |
 | `stitchkit/agent-runtime/openrouter` | server | evolving | isolated OpenRouter language-model adapter |
@@ -75,7 +75,7 @@ own, recorded as an ADR.
 | `stitchkit/agent-runtime/sqlite/bun` | server (Bun) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit/agent-runtime/sqlite/node` | server (Node ≥ 22.5) | evolving | durable built-in SQLite store for the agent runtime |
 | `stitchkit-tui` | terminal (Bun) | evolving | optional official OpenTUI host over a caller-composed headless runtime |
-| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 29 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart and bounded shutdown |
+| `stitchkit/application` | browser + server | evolving<br>_redefined in 7 of the 30 minors since 0.56.2, most recently 0.83.0_ | managed resource graph, readiness, admission, schedules, subtree restart 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` |
 | `stitchkit/application/schemas` | browser + server | evolving | the application's snapshot, health and shutdown schemas alone, without the kernel |
@@ -5273,12 +5273,38 @@ transaction. Drivers without this guarantee must leave the capability absent. Se
   while provider metadata stays inside a validated canonical envelope;
 - `assistant-checkpoint` follows a successful checkpoint CAS;
 - `run-state` follows durable queue/acquire/interrupt transitions;
+- `run-operation` follows a successful operation CAS. Its `operation` is the
+  durable `AgentRun.lastOperation`: `model-request` or `compaction`, with
+  `started`, `first-output`, `completed`, `failed` or `cancelled` phase and the
+  original timestamps. Concrete models use SDK call identity in an awaited model
+  middleware; global provider IDs use a runtime-generated identity during awaited
+  step preparation. Both durably admit the request before entering `doStream`, so a failed
+  write prevents the provider call. This does not claim HTTP transmission is
+  measured. First output is a
+  non-empty text/reasoning/tool-argument delta or complete tool call; metadata,
+  usage, files and sources do not count;
 - `tool-status` is transient lifecycle presentation with JSON-safe input on
   start and output on completion. A mounted typed failure carries the same safe
   `{ error, details?, _hint? }` envelope as the durable result; an unknown
   internal cause remains generic and stays in local observability only;
 - `terminal` follows the winning terminal CAS.
 
+`loop.checkpointEveryEvents` batches ordinary stream parts (default `20`) and
+does not batch live event delivery. Tool call/result/error/denial, approval
+request/response and step-finish boundaries force an assistant checkpoint and
+reset that batch. The checkpoint is awaited after the managed loop observes the
+normalized boundary. It does **not** promise persistence before a tool side
+effect: tool fencing supplies the real ownership checks around execution, while
+cross-crash effect idempotency stays application-owned. The following model
+step waits for the previous step-finish checkpoint before its own durable
+request admission and provider invocation. → ADR 0174.
+
+`compaction` names invocation of the configured callback, including a
+`not_needed` context-budget check; it does not by itself say that history was
+summarized. Operation timestamps are retained wall-clock observations and may
+move backwards after a clock correction. Do not subtract them for duration;
+phase order comes from durable snapshot versions/event order.
+
 These are post-commit notifications, not a transactional outbox: a process can
 crash between the database commit and `publish`. Reconnect should load canonical
 state. Exactly-once external delivery remains an application-owned outbox.
@@ -11022,6 +11048,33 @@ of the range if you want a different one.
 So upgrading is: read the `### ⚠️ Breaking changes` of every version *above* your
 current one *up to* your target, and apply each snippet.
 
+## Released migration: 0.85.0
+
+Only if you implement `AgentRuntimeStore` directly. Add the new durable
+operation mutation beside the existing run mutations:
+
+```ts
+// before
+const store: AgentRuntimeStore = {
+  checkpointRunAssistant,
+  commitRunTerminal,
+  // ...
+}
+
+// after
+const store: AgentRuntimeStore = {
+  checkpointRunAssistant,
+  recordRunOperation,
+  commitRunTerminal,
+  // ...
+}
+```
+
+It must atomically replace `AgentRun.lastOperation`, increment the run revision
+and conversation snapshot version, and enforce the supplied owner, fencing
+token and expected revision. Adapters built with `createAgentRuntimeStore`
+already receive the reference implementation; no driver method is added.
+
 ## What your range does, and does not, do for you
 
 A caret range (`"stitchkit": "^0.71.0"`) is a real gate: it resolves `< 0.72.0`,
@@ -15138,7 +15191,9 @@ Server-only optional application runtime. See the
 | `AgentSessionCloseResult` | _type_ | what `close()` achieved: `settled`, or `timedOut` with `remaining` runs still in flight. Only omitting `forceTimeoutMs` guarantees nothing is in flight on return |
 | `AgentHistoryProjectionOptions` | _type_ | storage-neutral file resolver, explicit unresolved-file behavior, and how an interrupted turn reaches the model (`interruptedAssistant`) |
 | `createAgentToolFenceLifecycle` | function | pre-effect and post-effect run ownership fence for `mountAgent`; compose beside application idempotency for [durable operations](../guide/mcp-and-agents.md#durable-application-owned-execution) |
-| `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/terminal projections |
+| `AgentRuntimeEventSchema` | schema | transient stream lifecycle plus post-commit admission/checkpoint/run-state/run-operation/terminal projections |
+| `AgentRunOperationKindSchema` / `AgentRunOperationPhaseSchema` / `AgentRunOperationSchema` / `AgentRunOperation` | schemas / _type_ | latest durable model-request or compaction phase with operation/step identity and original timestamps; request admission is awaited before provider invocation |
+| `RecordRunOperationSchema` / `RecordRunOperation` | schema / _type_ | owner/fencing/revision-checked mutation of `AgentRun.lastOperation` |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 
 ### Complete runtime inventory
@@ -15268,7 +15323,8 @@ provider and required capabilities without constructing the model; runtime `mode
 runs before durable admission.
 
 Delivery exports are `AgentAdmissionEventSchema`, `AgentCheckpointEventSchema`,
-`AgentRunStateEventSchema`, `AgentTerminalEventSchema`, `AgentTransientDeltaEventSchema`,
+`AgentRunStateEventSchema`, `AgentRunOperationEventSchema`, `AgentTerminalEventSchema`,
+`AgentTransientDeltaEventSchema`,
 `AgentReasoningStartEventSchema`, `AgentReasoningDeltaEventSchema`,
 `AgentReasoningEndEventSchema`, `AgentToolStatusEventSchema`, `AgentRuntimeEvent`,
 `AgentRuntimeEventCursor`, `AgentRuntimeEventCursorSchema`, `AgentRuntimeCursorAdvance`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.84.1",
+  "version": "0.85.1",
   "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",
@@ -285,7 +285,7 @@
     "@types/json-schema": "^7.0.15",
     "@types/react": "^19.2.18",
     "@typescript/typescript6": "^6.0.2",
-    "ai": "^7.0.79",
+    "ai": "^7.0.93",
     "fake-indexeddb": "^6.2.5",
     "grammy": "^1.45.1",
     "react": "^19.2.8",