stitchkit 0.68.8 → 0.68.9

package/llms-full.txt

@@ -3533,6 +3533,36 @@ const exportOperation = defineAsyncOperation({
 const runtimeTools = exportOperation.runtimeTools
 ```
 
+#### Durable application-owned execution
+
+The executable reference
+[`durable-async-operation-harness.ts`](../../packages/core/examples/durable-async-operation-harness.ts)
+shows the complete boundary behind that surface. It composes
+`defineAsyncOperationContract`, `defineAsyncOperation`, `createApplication`,
+`createBoundedAdmission`, managed shutdown and `createAgentToolFenceLifecycle`
+around an injected store and provider.
+
+The store transactionally owns the idempotency key **and normalized request
+hash**. Reusing both returns the existing operation; reusing the key with a
+different hash conflicts. Every mutation is an expected-revision CAS. Before an
+external call, the application persists a unique attempt/effect key and marks
+the dispatch `possibly-dispatched`; a lost response is therefore reconciled by
+that key after restart and is never treated as permission to submit the effect
+again. Provider acknowledgement, progress, cancellation intent, result and
+artifact references remain durable application state.
+
+Agent tool fencing and operation idempotency are separate guarantees. The fence
+prevents a stale run owner from crossing an effect boundary; the transactional
+idempotency record makes a repeated current call converge on one operation.
+Neither replaces the other.
+
+Stitchkit deliberately does **not** own the durable queue, operation database,
+lease renewal, provider retry/reconciliation protocol, asset catalog or domain
+states. The process-local application resource stops admission and drains
+accepted work; unresolved durable records survive shutdown for the next
+recovery pass. The packed consumer lane executes this composition from the
+published package on Bun and Node.
+
 Every follow-up repeats `authorize`; an opaque id is never authority. Aborting
 `wait` only stops waiting and never calls optional domain `cancel`.
 
@@ -4348,6 +4378,43 @@ 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.
 
+### External channel ingress and delivery
+
+The executable
+[`external-channel-harness.ts`](../../packages/core/examples/external-channel-harness.ts)
+is the reference composition for webhooks, polling transports and local-device
+adapters. Its generic boundary injects a runtime, durable store and delivery
+adapter; the optional
+[`external-channel-grammy.ts`](../../packages/core/examples/external-channel-grammy.ts)
+attaches the same ingress function to grammY polling or webhook lifecycle
+without putting provider types in the agent runtime.
+
+Inbound update identity, principal resolution, conversation mapping and reply
+target are application policy. Persist and deduplicate the update before
+`runtime.submit`, use the stored idempotency key on crash recovery, then persist
+the admitted `runId`. A duplicate arriving after restart resolves to that same
+mapping instead of creating another model turn.
+
+For output, choose `terminal-only` or `streaming` explicitly. Stable durable
+`eventId` values and transient `(runtimeEpoch, sequence)` identities become
+outbox keys; the application store assigns causal ordinals. A bounded channel
+is only a process-local wakeup and never the durable authority. Before sending,
+persist one of these states:
+
+| State | Recovery action |
+| --- | --- |
+| `not-dispatched` | may dispatch once |
+| `possibly-dispatched` | reconcile with the adapter or remain unresolved |
+| `acknowledged` | deduplicate; delivery is complete |
+
+The agent `terminal` event and the adapter's delivery receipt are intentionally
+different records. A successful run does not prove that a reply reached its
+channel, and a delivery failure never rewrites the canonical agent result.
+Shutdown stops ingress, drains accepted process-local work and leaves ambiguous
+outbox records visible for a later reconciliation pass. Stitchkit does not own
+a channel database, durable broker, provider payload schema or application
+identity policy.
+
 Durable event IDs are derived from run, event type and snapshot version. Use
 `advanceAgentRuntimeEventCursor` to classify delivery.
 
@@ -11646,7 +11713,7 @@ Server-only optional application runtime. See the
 | `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 |
 | `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` |
+| `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 |
 | `createAgentObservability` | function | separate agent-run sink over the shared bounded observability lifecycle |
 
@@ -12035,8 +12102,8 @@ runtime-tool runner, plus deliberate raw MCP adapters over the same mechanics.
 | `NativeToolIdentity` | _type_ | pathless service/action/scope/meta identity; semantic method is factory-owned |
 | `ManagedWaitRender` | _type_ | optional managed wait terminal text and failure classification |
 | `UploadToolInputSchema` | constant | fixed `{ path: string }` input schema for `defineUploadTool` |
-| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions |
-| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities |
+| `defineAsyncOperation` | function | runtime-only start/status/wait plus configured cancel/result/artifacts definitions; see the [durable application-owned recipe](../guide/mcp-and-agents.md#durable-application-owned-execution) |
+| `defineAsyncOperationContract` | function | define one canonical Zod-first HTTP contract for start/status/wait plus optional capabilities; execution and recovery remain application-owned |
 | `bindContractAsyncOperation` | function | bind literal methods from an existing contract without creating another HTTP surface |
 | `createAsyncOperationSnapshotSchema` | function | canonical pending/running/succeeded/failed/cancelled Zod snapshot |
 | `AsyncOperationCancelResultSchema` | constant | validated accepted/already_terminal/rejected cancellation result |

package/package.json

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