stitchkit 0.106.1 → 0.107.0

package/llms/{upgrading-0.55.0-0.68.0.txt → upgrading-0.59.0-0.71.0.txt}

@@ -1,14 +1,160 @@
-# Upgrading 0.55.0 → 0.68.0 — stitchkit docs slice
+# Upgrading 0.59.0 → 0.71.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.59.0 → 0.71.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.55.0 → 0.68.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.59.0 → 0.71.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.71.0
+
+The Agent coding tools. Two of the three changes are visible to the compiler;
+the third is the one to read carefully, because nothing will point at it.
+
+### If you implement `authorize`
+
+The operation union gained `edit`, `list` and `glob` and lost `patch`. An
+exhaustive matcher stops compiling and the compiler shows you every arm. **A
+matcher with a default branch does not**, and that is the dangerous case:
+
+```ts
+// before — and after this upgrade, silently wrong in both directions
+if (request.operation === 'patch') return reviewPatch(request)
+return true            // now also authorizes edit, list and glob
+// …or: return false   // now also kills edit_file
+```
+
+```ts
+// after
+switch (request.operation) {
+  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
+  case 'list':
+  case 'glob':   return true                  // or your own policy
+  // …existing read / write / search / shell / artifact-read arms
+}
+```
+
+`write` gained `createsDirectories` — the workspace-relative directories the
+call would create, outermost first, reported **before** anything is created. A
+host that wants to refuse implicit directory creation now can.
+
+### If you call `apply_patch`
+
+It is `edit_file`, and it is one call:
+
+```ts
+// before
+const read = await readFile({ path })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
+await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
+
+// after
+await editFile({ path, oldText, newText })
+```
+
+`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
+you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
+never needs to re-read. If you key an approval policy or a UI label on the string
+`apply_patch`, update the key — nothing will fail loudly.
+
+### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
+
+Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
+existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
+`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
+Code that treated any coding-tool failure as an internal fault will now see
+codes it did not before; code that showed the model an empty error now has a
+sentence and a `hint` to show it. Host-level causes are unchanged and still
+scrubbed.
+
+### If you write files into new directories
+
+Nothing to change: `write_file` creates missing parents inside the root. Read
+`createdDirectories` in the result if you want to notice a typo — a path that
+was a failure before is now a successful write into a new tree.
+
+### If you want a step to know its context budget
+
+Opt in by reading it; nothing is injected for you:
+
+```ts
+loop: {
+  prepareStep: ({ contextUsage }) => {
+    const used = contextUsage?.usedTokens
+    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
+    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
+    // …render it wherever you put it
+    return {}
+  },
+}
+```
+
+Put it at the **tail** of the conversation rather than in the system
+instructions unless you have a reason: changing the system prompt on every step
+invalidates the provider's prefix cache for the whole conversation, and on a long
+run that is a multiple of the input cost.
+
+## Released migration: 0.70.0
+
+### Descriptor-backed Agent filesystem containment
+
+Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
+that can address an opened directory descriptor: Linux `/proc/self/fd`, or the packaged macOS
+Node-API backend added in 0.70.1. This is what keeps a mutable parent rename or outside-symlink replacement from changing
+the authorized target between validation and the actual effect.
+
+No call-site change is needed on those platforms. The 0.70.0 notes incorrectly inferred macOS and
+FreeBSD support from `/dev/fd`; macOS is restored by 0.70.1 and FreeBSD remains unsupported. On
+Windows or another platform without that
+boundary, move the built-in filesystem operations to a supported worker or replace them with
+application-owned tools backed by an equivalent native handle API. They fail closed rather than
+falling back to path spelling. `run_command` remains separately available under its explicit
+executable alias and authorization policy; this change does not claim an executable sandbox.
+
+## Released migration: 0.69.0
+
+### Direct coding-tool operation names
+
+`createAgentCodingTools` no longer prefixes durable operation identity with `coding_`, and the
+unguarded exact-string edit tool is gone. Update approval maps, presenters and tests together:
+
+```ts
+// before
+{ coding_read_file: 'approved', coding_search: 'approved', coding_patch_file: 'user-approval' }
+
+// after
+{ read_file: 'approved', search_files: 'approved', apply_patch: 'user-approval' }
+```
+
+The full mapping is `coding_read_file → read_file`, `coding_write_file → write_file`,
+`coding_search → search_files`, `coding_patch_file → apply_patch`, `coding_shell → run_command`,
+`coding_read_artifact → read_output` and `harness_read_resource → read_resource`. Replace
+`coding_edit_file` with `read_file` followed by guarded `apply_patch`; `read_file` now returns the
+required SHA-256. If the host declares no executable aliases, expect `run_command` to be absent.
+
+### Durable Agent approval message variants
+
+If a renderer, store adapter or export pipeline exhaustively switches over
+`AgentMessage.role`, add the `tool` branch. If it switches over
+`AgentMessagePart.type`, add `tool-approval-request` and `tool-approval-response`.
+They are durable provider-continuation evidence: preserve them in storage and provider history;
+a UI may render them as approval state or intentionally omit their visual row.
+
+```ts
+// before
+const unreachable: never = message.role
+
+// after
+if (message.role === 'tool') renderToolContinuation(message.parts)
+else renderExistingRole(message)
+```
+
+No data migration is needed. The schema still accepts all earlier records, and applications that
+do not exhaustively branch over these unions compile unchanged.
+
 ## Released migration: 0.68.0
 
 ### Make Unix transport selection explicit outside Bun
@@ -994,209 +1140,3 @@ createAgentRuntimeStore({
 `runAgentStoreConformance()` against the migrated adapter before switching production traffic.
 If an application implements `AgentRuntimeStore` directly, its duplicate result must also include
 the canonical `run` and the retained `assistant` for a terminal run.
-
-## Released migration: 0.58.0
-
-### The default history projection rejects invalid chronology
-
-`projectAgentHistory` no longer forwards records a provider contract cannot
-accept. A completed assistant record before the first user message, and an
-assistant record whose tool calls have no matching results, are omitted with an
-inspectable decision instead of being sent upstream:
-
-```ts
-// before — a leading assistant record was forwarded as-is
-projectAgentHistory(messages)
-// after — opt in explicitly, and only where the provider contract permits it
-projectAgentHistory(messages, { leadingAssistant: 'allow' })
-```
-
-Two consequences the changelog does not spell out. First, the projection can now
-return **fewer** messages than the history holds, so any assertion or metric
-that compared projected length against stored length will move; read the
-detailed projection instead — it reports what was omitted and why, which is the
-supported way to see the difference. Second, the omission is silent to the
-provider but not to you: if a conversation suddenly loses its leading context,
-the decision record is where that shows up, not the transcript.
-
-### Operator events redact `internalCause` by default
-
-Raw provider and tool failures no longer travel in operator events unless the
-sink asks for them:
-
-```ts
-// before — internalCause was present
-createAgentObservability({ write })
-// after — an explicit operator-only opt-in
-createAgentObservability({ write, includeInternalCause: true })
-```
-
-The consequence to check before upgrading: any dashboard, alert or log
-processor keyed on `internalCause` goes blind the moment you upgrade, and it
-goes blind quietly — the field is absent, not empty. Set the flag on the
-operator sink you own. Product delivery stays redacted regardless of the flag;
-this option cannot widen what reaches a user.
-
-## Released migration: 0.57.0
-
-### Duplicate admission results carry the complete identity
-
-Custom `AgentRuntimeStore` adapters must persist and return the input and
-assistant identities associated with an idempotency key:
-
-```ts
-// before
-return { outcome: 'duplicate', runId, snapshot }
-
-// after
-return { outcome: 'duplicate', input, inputMessageId, runId, assistantMessageId, snapshot }
-```
-
-Prefer replacing the custom aggregate reducer with `createAgentRuntimeStore()`;
-its admission record and transaction driver implement this contract
-automatically. Historical note: 0.59.0 reshaped this driver again, so an adapter
-crossing both versions should read that section first and migrate once.
-
-### `AgentRuntimeEvent` adds a post-commit `admission` variant
-
-Add it to any exhaustive publisher switch. Its `assistant` is either the pending
-placeholder for a new assignment or the canonical persisted assistant for a
-duplicate:
-
-```ts
-case 'admission':
-  await persistProductProjection(event.input, event.run, event.assistant)
-  break
-```
-
-The consequence for an exhaustive switch written without a `default` branch is a
-compile error, which is the point. The consequence for a switch that *has* a
-`default` is worse and silent: post-commit admissions fall into it and are
-projected as an unknown event. Grep for publisher switches before upgrading.
-
-## Released migration: 0.56.0
-
-### Surface manifests are version 2
-
-`operation.tools` could not describe a role-selected MCP surface, a different
-Agent or CLI selection, or an advertised `extend` schema, so projections moved
-out of the canonical operation:
-
-```ts
-// before
-manifest.operations[0].tools.MCP
-// after
-manifest.toolSurfaces.find((s) => s.transport === 'MCP' && s.surface === null)?.tools
-
-// before
-buildSurfaceManifest({ mcpSurfaces: { admin: { services, extend } } })
-// after
-buildSurfaceManifest({ mcpSurfaces: { admin: { services } }, mcpPreparation: { extend } })
-```
-
-A committed snapshot is regenerated once, deliberately: `manifestVersion` is
-`2`, and `ConformanceTransport` gained `REALTIME`, so any exhaustive
-`Record<ConformanceTransport, …>` must handle it.
-
-### `FILE_*` codes joined the error registry
-
-`StitchErrorCode` gained `FILE_INVALID_PATH`, `FILE_OUTSIDE_ROOT`,
-`FILE_NOT_FOUND`, `FILE_NOT_REGULAR`, `FILE_INSPECTION_REJECTED`,
-`FILE_TOO_LARGE` and `FILE_EXISTS`. Only exhaustive maps break:
-
-```ts
-// before — compiled while the registry had no file codes
-const copy: Record<StitchErrorCode, string> = { …, RATE_LIMITED: '…' }
-// after — add the seven managed-file codes (or use Partial<Record<…>>)
-```
-
-Unexpected IO stays scrubbed as `INTERNAL_SERVER_ERROR`: the new codes are the
-caller-safe ones only.
-
-### `ScopedAuthHook` is nominal
-
-A hand-written function shaped like an auth hook is no longer assignable —
-identity now comes from the factory, so scope ownership and the inferred
-context cannot drift apart:
-
-```ts
-// before — a structural stand-in
-const auth: ScopedAuthHook<Scopes> = async (ctx, endpoint) => { … }
-// after — create it, then compose domains
-const auth = createAuthHook({ resolve, rules })
-const composed = composeAuthHooks({ hooks: [auth, billingAuth], defaultScope: 'public' })
-```
-
-### Managed-file inspectors also run on reads
-
-An inspector is no longer write-only, and it has a finite default deadline
-(15 s). Make it read-aware and idempotent — a read carries no
-`declaredMediaType`:
-
-```ts
-// before
-inspect: ({ declaredMediaType }) => inspectDeclaredType(declaredMediaType!)
-// after
-inspect: ({ prefix, declaredMediaType, signal }) =>
-  inspectBytes(prefix, { declaredMediaType, signal })
-```
-
-Set `inspectionTimeoutMs` explicitly when 15 seconds is the wrong budget.
-
-### Direct async-operation binding needs a wire-stable ID
-
-A direct binding reuses the start output as the follow-up wire input, so the ID
-schema must parse to itself (`z.input` equals `z.output`, no transform,
-coercion, default or overwrite). Anything else is parsed twice:
-
-```ts
-// before — a transform silently ran on start and again on every follow-up
-defineAsyncOperationContract({ binding: 'direct', id: z.string().transform(Number) })
-// after — keep the wire shape, adapt explicitly
-defineAsyncOperationContract({
-  binding: 'adapted',
-  id,
-  adapters: { idFromStart, inputFor },
-})
-```
-
-## Released migration: 0.55.0
-
-### Peer-free `implementRemote`
-
-`implementRemote` now has one canonical, optional-peer-free owner. This keeps
-MCP SDK and AI SDK modules out of CLI bundles that only proxy HTTP calls:
-
-```ts
-// before
-import { implementRemote } from 'stitchkit/tools'
-// after
-import { implementRemote } from 'stitchkit/remote'
-```
-
-### Managed file boundary and strict auth returns
-
-Create one boundary during application bootstrap and pass the capability, never
-a per-call directory or host path:
-
-```ts
-import { createManagedFileBoundary } from 'stitchkit/files'
-
-const files = await createManagedFileBoundary({ root: '/srv/app-files' })
-
-// before
-defineDownloadTool({ defaultDir: '/srv/app-files', resolveUrl, ...common })
-defineUploadTool({ upload: (path) => provider.uploadFile(path), ...common })
-defineViewFileTool({ baseDir: '/srv/app-files', ...common })
-
-// after
-defineDownloadTool({ files, resolveUrl, ...common })
-defineUploadTool({ files, upload: ({ bytes }) => provider.upload(bytes), ...common })
-defineViewFileTool({ files, ...common })
-```
-
-Downloaded `path` is now relative to the boundary and MIME metadata is named
-`mediaType`. Update raw `mountDownload`/`mountUpload`/`mountViewFile` configs the
-same way. Auth predicates must explicitly return `true`, `false`, or a plain
-object of context fields; replace accidental `undefined` fallthroughs with the
-intended boolean.

package/llms/{upgrading-0.69.0-0.95.0.txt → upgrading-0.72.0-0.97.0.txt}

@@ -1,14 +1,87 @@
-# Upgrading 0.69.0 → 0.95.0 — stitchkit docs slice
+# Upgrading 0.72.0 → 0.97.0 — stitchkit docs slice
 
 > Generated from the `docs/` tree by `bun run gen:llms`. The index of all slices is
 > `llms.txt` in this package.
 
-Contains: Guide: Upgrading, 0.69.0 → 0.95.0  (docs/guide/upgrading.md)
+Contains: Guide: Upgrading, 0.72.0 → 0.97.0  (docs/guide/upgrading.md)
 
 ==============================================================================
-# Guide: Upgrading, 0.69.0 → 0.95.0  (docs/guide/upgrading.md)
+# Guide: Upgrading, 0.72.0 → 0.97.0  (docs/guide/upgrading.md)
 ==============================================================================
 
+## Released migration: 0.97.0
+
+### schedule delivery
+
+**Who must act:** consumers of `createAgentScheduleService`, exhaustive switches on
+`AgentSchedule.state`, and operators opening existing agent-runtime SQLite stores.
+
+- Stop old scheduler processes and back up SQLite before startup. The store migrates
+  transactionally to v4; old binaries cannot open it. Rollback uses the backup.
+- Handle `failed` as a terminal schedule state. To refuse future delivery (including
+  recurring delivery), return `{ status: 'terminal', reason: 'destination closed' }`.
+  The occurrence remains unadvanced; `schedule/failed` carries `terminal: true`.
+- A throw or `{ status: 'retry', reason: 'temporarily unavailable' }` retries the same
+  key after 1, 2, 4, 8, 16, 32, then 60 seconds. `nextAt` remains the original due time;
+  `retryAt`, `attempts` and `lastError` expose retry diagnostics. Success clears them.
+- Resolve `void` only after durable consumer admission. Honor the supplied `signal`:
+  dispatch has a 30-second deadline and a 60-second lease. Durable deduplication by
+  `idempotencyKey` is required even after abort or crash; do not implement sleeps in dispatch.
+- Stale/cancelled attempts emit no `schedule/fired` or `schedule/late`. Observe the
+  cancellation event instead of relying on a synthetic cancelled firing.
+
+```ts
+// before
+async function dispatch(request) {
+  if (await destinationClosed(request.conversationId)) throw new Error('closed')
+  await admit(request)
+}
+// after: use this callback as createAgentScheduleService({ dispatch, ... })
+async function dispatch(request) {
+  if (await destinationClosed(request.conversationId)) {
+    return { status: 'terminal', reason: 'destination closed' }
+  }
+  await admit({ ...request, signal: request.signal }) // durably deduplicates idempotencyKey
+}
+```
+
+## Released migration: 0.96.0
+
+### resource-context-admission
+
+One breaking change in `stitchkit/application`: `ManagedResourceContext` gains a
+required `admission`. Every context the kernel hands a resource already carries
+it; only a context built by hand needs it.
+
+1. **Give a hand-built resource context an `admission`.** **Who must act:** a
+   project whose tests call a resource's phase directly with a context object
+   they wrote themselves (`resource.close?.({ applicationId, signal, … })`).
+   The type checker names each one:
+
+   ```ts
+   // before
+   await resource.close?.({ applicationId: 'test', signal, now, reportHealth, use })
+   // after
+   await resource.close?.({
+     applicationId: 'test',
+     signal,
+     now,
+     reportHealth,
+     use,
+     admission: { acquire: () => null, acquireWhenAccepting: () => new Promise(() => {}) },
+   })
+   ```
+
+   A test that needs real admission starts the resource inside
+   `createApplication` instead.
+
+2. **Nothing to do for grammY polling, but know what changed.** **Who must
+   act:** nobody. `grammyPollingResource` now admits updates by batch: it does
+   not fetch while the application is not accepting, and finishes the batch in
+   hand before `bot.stop()`. A project that wrote its own `getUpdates`
+   transformer for this (waiting on `app.admission` before returning a batch)
+   deletes it; keeping both waits twice and is harmless.
+
 ## Released migration: 0.95.0
 
 One breaking change in `stitchkit/application`: the process lifecycle ledger
@@ -1003,149 +1076,3 @@ const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /*
 // after
 const snapshot: CreditWindowSnapshot = { state: 'open', capacityBytes: 100, /* … */ waiting: 0 }
 ```
-
-## Released migration: 0.71.0
-
-The Agent coding tools. Two of the three changes are visible to the compiler;
-the third is the one to read carefully, because nothing will point at it.
-
-### If you implement `authorize`
-
-The operation union gained `edit`, `list` and `glob` and lost `patch`. An
-exhaustive matcher stops compiling and the compiler shows you every arm. **A
-matcher with a default branch does not**, and that is the dangerous case:
-
-```ts
-// before — and after this upgrade, silently wrong in both directions
-if (request.operation === 'patch') return reviewPatch(request)
-return true            // now also authorizes edit, list and glob
-// …or: return false   // now also kills edit_file
-```
-
-```ts
-// after
-switch (request.operation) {
-  case 'edit':   return reviewEdit(request)   // the old `patch` payload, unchanged
-  case 'list':
-  case 'glob':   return true                  // or your own policy
-  // …existing read / write / search / shell / artifact-read arms
-}
-```
-
-`write` gained `createsDirectories` — the workspace-relative directories the
-call would create, outermost first, reported **before** anything is created. A
-host that wants to refuse implicit directory creation now can.
-
-### If you call `apply_patch`
-
-It is `edit_file`, and it is one call:
-
-```ts
-// before
-const read = await readFile({ path })
-await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: true })
-await applyPatch({ path, baseSha256: read.sha256, oldText, newText, dryRun: false })
-
-// after
-await editFile({ path, oldText, newText })
-```
-
-`expectedSha256` is optional and still refuses a stale base with `CONFLICT` when
-you pass it; `edit_file` returns the resulting `sha256`, so a chain of edits
-never needs to re-read. If you key an approval policy or a UI label on the string
-`apply_patch`, update the key — nothing will fail loudly.
-
-### If you match on `INTERNAL_SERVER_ERROR` from a coding tool
-
-Ordinary outcomes no longer arrive that way. A missing file is `NOT_FOUND`, an
-existing file without `overwrite` is `CONFLICT`, an ambiguous snippet is
-`CONFLICT` with the occurrence count, a path outside the root is `FORBIDDEN`.
-Code that treated any coding-tool failure as an internal fault will now see
-codes it did not before; code that showed the model an empty error now has a
-sentence and a `hint` to show it. Host-level causes are unchanged and still
-scrubbed.
-
-### If you write files into new directories
-
-Nothing to change: `write_file` creates missing parents inside the root. Read
-`createdDirectories` in the result if you want to notice a typo — a path that
-was a failure before is now a successful write into a new tree.
-
-### If you want a step to know its context budget
-
-Opt in by reading it; nothing is injected for you:
-
-```ts
-loop: {
-  prepareStep: ({ contextUsage }) => {
-    const used = contextUsage?.usedTokens
-    if (used?.provenance === 'unavailable') return {}      // no step has landed yet
-    const fraction = (used?.value ?? 0) / (contextUsage?.contextWindow ?? 1)
-    // …render it wherever you put it
-    return {}
-  },
-}
-```
-
-Put it at the **tail** of the conversation rather than in the system
-instructions unless you have a reason: changing the system prompt on every step
-invalidates the provider's prefix cache for the whole conversation, and on a long
-run that is a multiple of the input cost.
-
-## Released migration: 0.70.0
-
-### Descriptor-backed Agent filesystem containment
-
-Built-in coding file/search tools and `createAgentHarnessFileResources` now require a runtime
-that can address an opened directory descriptor: Linux `/proc/self/fd`, or the packaged macOS
-Node-API backend added in 0.70.1. This is what keeps a mutable parent rename or outside-symlink replacement from changing
-the authorized target between validation and the actual effect.
-
-No call-site change is needed on those platforms. The 0.70.0 notes incorrectly inferred macOS and
-FreeBSD support from `/dev/fd`; macOS is restored by 0.70.1 and FreeBSD remains unsupported. On
-Windows or another platform without that
-boundary, move the built-in filesystem operations to a supported worker or replace them with
-application-owned tools backed by an equivalent native handle API. They fail closed rather than
-falling back to path spelling. `run_command` remains separately available under its explicit
-executable alias and authorization policy; this change does not claim an executable sandbox.
-
-## Released migration: 0.69.0
-
-### Direct coding-tool operation names
-
-`createAgentCodingTools` no longer prefixes durable operation identity with `coding_`, and the
-unguarded exact-string edit tool is gone. Update approval maps, presenters and tests together:
-
-```ts
-// before
-{ coding_read_file: 'approved', coding_search: 'approved', coding_patch_file: 'user-approval' }
-
-// after
-{ read_file: 'approved', search_files: 'approved', apply_patch: 'user-approval' }
-```
-
-The full mapping is `coding_read_file → read_file`, `coding_write_file → write_file`,
-`coding_search → search_files`, `coding_patch_file → apply_patch`, `coding_shell → run_command`,
-`coding_read_artifact → read_output` and `harness_read_resource → read_resource`. Replace
-`coding_edit_file` with `read_file` followed by guarded `apply_patch`; `read_file` now returns the
-required SHA-256. If the host declares no executable aliases, expect `run_command` to be absent.
-
-### Durable Agent approval message variants
-
-If a renderer, store adapter or export pipeline exhaustively switches over
-`AgentMessage.role`, add the `tool` branch. If it switches over
-`AgentMessagePart.type`, add `tool-approval-request` and `tool-approval-response`.
-They are durable provider-continuation evidence: preserve them in storage and provider history;
-a UI may render them as approval state or intentionally omit their visual row.
-
-```ts
-// before
-const unreachable: never = message.role
-
-// after
-if (message.role === 'tool') renderToolContinuation(message.parts)
-else renderExistingRole(message)
-```
-
-No data migration is needed. The schema still accepts all earlier records, and applications that
-do not exhaustively branch over these unions compile unchanged.