stitchkit 0.87.1 → 0.88.0

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 32 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 33 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 18 of the 32 minors since 0.56.2, most recently 0.87.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
+| `stitchkit/agent-runtime` | server | evolving<br>_redefined in 19 of the 33 minors since 0.56.2, most recently 0.88.0_ | optional durable conversation/run loop, history, models, prompts, fencing and events |
 | `stitchkit/agent-runtime/testing` | tests on Bun or Node | evolving | credential-free replay, scripted provider faults and deterministic race controls |
 | `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 |
@@ -76,7 +76,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 32 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 33 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 |
@@ -4742,6 +4742,11 @@ root and cwd are path boundaries, not a security sandbox: isolate the process wh
 must not access the rest of the machine. Path admission does not constrain `run_command`; an
 executable requires process isolation for that guarantee. → ADR 0172
 
+An absolute path is still refused. When it is inside the canonical workspace root, the refusal
+includes the exact workspace-relative `recoveryPath`; an absolute path outside the root has no
+suggested replacement. Applying the suggestion still passes the same descriptor-relative
+containment and symlink checks.
+
 `edit_file` replaces one exact snippet. `oldText` is itself the freshness guard for the region it
 changes, so the digest is the optional `expectedSha256` and an edit is one call; pass the digest
 `read_file` returned when you want the whole-file guarantee, and read the `sha256` it returns to
@@ -4765,7 +4770,11 @@ Host-level causes stay scrubbed to `INTERNAL_SERVER_ERROR` and name nothing outs
 `list_directory` marks excluded directories rather than hiding them, and `glob` reports
 `skippedDirectories` beside its matches: an empty result from a tree whose files all live under an
 excluded directory is not "no files", and a model told only "nothing found" concludes the wrong
-thing. `search_files` takes `regex`, `context` lines and an `include` pattern; regex is bounded by
+thing. `search_files` takes `regex`, `context` lines and an anchored `include` pattern matched
+against the whole workspace-relative path. `*` does not cross `/`, so files in subdirectories need
+`**/`; `scannedFiles` counts files admitted by both that filter and host authorization. A `hint`
+explains the zero only when the filter produced it, rejecting every file the scan reached; an empty
+tree and a host refusal return the same empty result without blaming the pattern. Regex is bounded by
 refusing backreferences and lookaround and capping line length rather than by a timeout, because a
 JavaScript `RegExp` cannot be interrupted once it starts backtracking. With an optional `AgentCodingArtifactStore`, shell output beyond the inline
 preview continues into an opaque bounded artifact and `read_output` reads slices without
@@ -4975,10 +4984,14 @@ what was published, so a cursor sees no gap on an ordinary stream.
 
 ### Event ledger, projections and durable capabilities
 
-`AgentRuntimeStore` exposes bounded `readEvents`, declared `appendEvent`,
-canonical `exportConversation` and empty-target `importConversation`. Runtime
-transitions and exact provider requests enter the same append-only ledger; the
-normalized head/run/message tables remain the fast operational projection.
+`AgentRuntimeStore` exposes bounded `readEvents`, declared `appendEvent`, canonical
+`exportConversation` and empty-target `importConversation`. Runtime transitions, exact provider
+requests and completed provider response identities enter the same append-only ledger. A
+`provider/response` payload binds `response: { id, provider? }` to its `runId`, retry `attempt` and
+`stepNumber`; `step-finished.response` projects the same object to the operator sink. The optional
+upstream name comes from the model provider's own `resolveResponseProvider` — `openRouterProvider`
+supplies it — so the runtime carries the fact without learning any gateway's metadata key. The normalized
+head/run/message tables remain the fast operational projection.
 
 Use `defineAgentProjection` with `createSqliteAgentProjectionStore` for a
 deterministic versioned fold. Every value reports `uptoSeq`, so a caller can
@@ -5270,6 +5283,24 @@ own usage. The two channels answer to different readers — delivering a turn tw
 problem, and omitting a run's cost is an operator's.
 `runtime.stop(key)` is the process-local signal-only escape hatch.
 
+When an operator has positive evidence that another process owning one known
+run is gone, close that run through the runtime boundary rather than updating
+an adapter table or JSON payload directly:
+
+```ts
+await runtime.abandon({
+  conversationId,
+  runId,
+  expectedRevision: run.revision,
+  staleOwner: true,
+})
+```
+
+The revision protects against stale operator evidence. The mutation updates the
+canonical run and failed assistant atomically, removes the run from recovery
+indexes, and publishes the resulting `run-state`. A run that moved since it was
+read returns a conflict; `staleOwner: true` is mandatory evidence, not a default.
+
 ## Store operations
 
 `AgentRuntimeStore` remains the runtime-facing aggregate. Application adapters
@@ -5714,6 +5745,10 @@ spent nothing, and an omitted object could not tell you which one you had.
 Two costs in different currencies do not add: the sum reports `unavailable`
 rather than picking a label. The core records a currency and never converts one.
 
+`step-finished.response` identifies the provider response for that one step. The terminal event
+does not copy the last response: response identity remains per-step, while every terminal usage
+figure remains a `computed` aggregate.
+
 **A run's figure is durable, and that is where to read it when a channel loses
 it.** `AgentRun.usage` is written at every checkpoint and again with the terminal
 record, so a crashed process leaves behind what it had already spent and a
@@ -11229,6 +11264,37 @@ 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.88.0
+
+Two mechanical edits, and only if your project builds these values rather than only reading them.
+
+A completed step event now carries the provider's response identity, and the field is required:
+
+```ts
+// before
+{ type: 'step-finished', step: 0, usage }
+
+// after
+{ type: 'step-finished', step: 0, usage, response: { id: generationId } }
+```
+
+Every event the runtime emits already has it, so a sink that only reads them needs no change. A
+fixture, a test double or a pipeline that re-validates events persisted by an earlier version does:
+give the older records a response identity, or keep parsing them with the schema they were written
+under.
+
+If you implement the whole `AgentRuntime` interface — usually a mock — add the new method:
+
+```ts
+// before
+const fake: AgentRuntime = { submit, interrupt, recover, close }
+
+// after
+const fake: AgentRuntime = { submit, interrupt, abandon, recover, close }
+```
+
+No data migration is involved, and nothing in the store changes shape.
+
 ## Released migration: 0.87.0
 
 Only if your project implements `AgentConversationReader` itself. A message page
@@ -15505,6 +15571,7 @@ Server-only optional application runtime. See the
 | `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 causal per-conversation scheduling, context resolver and explicit evidence policy |
+| `AgentRuntimeAbandonInput` | _type_ | one known orphan identity, expected revision and mandatory stale-owner evidence for `runtime.abandon()` |
 | `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 |
@@ -15514,13 +15581,15 @@ Server-only optional application runtime. See the
 | `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 |
+| `AgentProviderResponseSchema` / `AgentProviderResponse` | schema / _type_ | provider-assigned response ID and the optional upstream provider the model's own adapter resolves, shared by `step-finished.response` and durable `provider/response` facts |
+| `AgentStepFinishedEventSchema` / `AgentStepFinishedEvent` | schema / _type_ | one completed provider step with required usage and provider response identity |
 
 ### Durable capability layer
 
 | Export | Kind | Summary |
 |--------|------|---------|
 | `AgentConversationArchiveSchema` / `AgentConversationArchive` / `encodeAgentConversationArchive` / `decodeAgentConversationArchive` / `canonicalAgentJson` | schema / _type_ / functions | canonical validated conversation archive with exact ledger events, recovery projection and durable spill payloads |
-| `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary and bounded page |
+| `AgentStoreEventEnvelopeSchema` / `AgentStoreEventEnvelope` / `AgentStoreEventKindSchema` / `AgentStoreEventKind` / `AgentStoreEventPageSchema` / `AgentStoreEventPage` | schema / _type_ | append-only event envelope, closed current vocabulary (including `provider/request` and `provider/response`) and bounded page |
 | `AppendAgentStoreEventSchema` / `AppendAgentStoreEvent` / `ReadAgentStoreEventsSchema` / `ReadAgentStoreEvents` | schema / _type_ | required append and bounded-read store contracts |
 | `AgentStoreTransitionSchema` / `AgentStoreTransition` / `AgentStoreEventDraft` / `AgentStoreEventDecodeAccepted` / `AgentStoreEventDecodeIgnored` / `AgentStoreEventDecodeResult` / `decodeAgentStoreEvent` | schema / _types_ / function | normalized runtime mutations, append drafts and strict current/ignorable future-event decoding outcomes |
 | `defineAgentProjection` / `AgentProjectionDefinition` / `AgentProjectionValue` / `createAgentProjectionRegistry` / `createSqliteAgentProjectionStore` | functions / _type_ | deterministic folds with persisted version and honest `uptoSeq` checkpoints |
@@ -15543,7 +15612,7 @@ Server-only optional application runtime. See the
 The entrypoint deliberately exports the schemas beside their inferred types so persistence and
 transport adapters validate the same records. Runtime composition types are `AgentRuntime`,
 `AgentRuntimeConfig`, `AgentRuntimeInput`, `AgentRuntimeProtocolInput`, `AgentRuntimeRunContext`,
-`AgentRuntimeResult`, `AgentRuntimeInterruptInput`, `AgentRuntimeRecoveryInput`,
+`AgentRuntimeResult`, `AgentRuntimeInterruptInput`, `AgentRuntimeAbandonInput`, `AgentRuntimeRecoveryInput`,
 `AgentRuntimeRecoveryDecision`, `AgentRuntimeRecoveryOutcome`, `AgentRuntimePublisher`,
 `AgentInputPolicy`, `AgentStopReason`, `AgentCoordinatedRun`, `AgentRunTicket`,
 `AgentSessionCoordinator`, `AgentCompactionContext`, `AgentCompactionResult` and
@@ -15760,6 +15829,13 @@ so denying `credentials` denies `credentials/token.txt` but not `credentials-bac
 admission happens before descent and file admission before opening; `search_files.include` is also
 applied before content is read. Requested paths must use `/` — a backslash is refused, because the
 containment walk reads it as a separator while a callback would read it as one name.
+Absolute paths remain refused; an absolute path inside the canonical root carries an exact
+workspace-relative `recoveryPath`, while one outside the root carries no replacement. The
+`search_files.include` schema states that its pattern is anchored to the whole workspace-relative
+path, `*` does not cross `/`, and `**/` is required for nested matches. `scannedFiles` is the
+post-include/post-authorization comparison count. A `hint` is added only when the filter itself
+produced the zero — it rejected every file the scan reached — never when there was nothing to
+reject or the host refused it.
 `run_command` is intentionally outside this guarantee because an executable needs process isolation,
 not path filtering, to constrain its filesystem access. → ADR 0172.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stitchkit",
-  "version": "0.87.1",
+  "version": "0.88.0",
   "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",