stitchkit 0.100.0 → 0.100.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (79) hide show
  1. package/CHANGELOG.md +93 -1
  2. package/dist/agent-runtime/invocation-attempt.d.ts +6 -0
  3. package/dist/agent-runtime/invocation-attempt.d.ts.map +1 -1
  4. package/dist/agent-runtime/invocation-payload.d.ts +2 -0
  5. package/dist/agent-runtime/invocation-payload.d.ts.map +1 -1
  6. package/dist/agent-runtime/invocation-read.d.ts.map +1 -1
  7. package/dist/agent-runtime/invocations.d.ts +6 -0
  8. package/dist/agent-runtime/invocations.d.ts.map +1 -1
  9. package/dist/agent-runtime/projections.d.ts.map +1 -1
  10. package/dist/agent-runtime/schedule-dispatch.d.ts +9 -2
  11. package/dist/agent-runtime/schedule-dispatch.d.ts.map +1 -1
  12. package/dist/agent-runtime/schedule-records.d.ts +8 -2
  13. package/dist/agent-runtime/schedule-records.d.ts.map +1 -1
  14. package/dist/agent-runtime/schedules.d.ts +5 -0
  15. package/dist/agent-runtime/schedules.d.ts.map +1 -1
  16. package/dist/agent-runtime/sqlite-events.d.ts.map +1 -1
  17. package/dist/agent-runtime/store-create.d.ts.map +1 -1
  18. package/dist/agent-runtime/store-driver-contract.d.ts +9 -0
  19. package/dist/agent-runtime/store-driver-contract.d.ts.map +1 -1
  20. package/dist/agent-runtime/store-event-once.d.ts +9 -1
  21. package/dist/agent-runtime/store-event-once.d.ts.map +1 -1
  22. package/dist/agent-runtime/store-memory.d.ts.map +1 -1
  23. package/dist/agent-runtime/store.d.ts +6 -0
  24. package/dist/agent-runtime/store.d.ts.map +1 -1
  25. package/dist/application/change-subscription.d.ts.map +1 -1
  26. package/dist/application/notification-delivery.d.ts +24 -1
  27. package/dist/application/notification-delivery.d.ts.map +1 -1
  28. package/dist/application/notification-outbox-state.d.ts +4 -0
  29. package/dist/application/notification-outbox-state.d.ts.map +1 -1
  30. package/dist/application/notification-outbox.d.ts.map +1 -1
  31. package/dist/application/process-lifecycle-transitions.d.ts +13 -2
  32. package/dist/application/process-lifecycle-transitions.d.ts.map +1 -1
  33. package/dist/application/process-lifecycle.d.ts +2 -1
  34. package/dist/application/process-lifecycle.d.ts.map +1 -1
  35. package/dist/application/watch-hub-core.d.ts +14 -79
  36. package/dist/application/watch-hub-core.d.ts.map +1 -1
  37. package/dist/application/watch-hub-source.d.ts +98 -0
  38. package/dist/application/watch-hub-source.d.ts.map +1 -0
  39. package/dist/browser/session-credentials.d.ts +6 -0
  40. package/dist/browser/session-credentials.d.ts.map +1 -1
  41. package/dist/browser/session.d.ts +3 -1
  42. package/dist/browser/session.d.ts.map +1 -1
  43. package/dist/entrypoints/agent-runtime/harness.js +1 -1
  44. package/dist/entrypoints/agent-runtime/sqlite/bun.js +2 -2
  45. package/dist/entrypoints/agent-runtime/sqlite/node.js +2 -2
  46. package/dist/entrypoints/agent-runtime/testing.js +2 -2
  47. package/dist/entrypoints/agent-runtime.js +53 -19
  48. package/dist/entrypoints/application/diagnostic-journal.js +1 -1
  49. package/dist/entrypoints/application.d.ts +2 -2
  50. package/dist/entrypoints/application.d.ts.map +1 -1
  51. package/dist/entrypoints/application.js +285 -193
  52. package/dist/entrypoints/files.js +8 -2
  53. package/dist/entrypoints/index.js +33 -6
  54. package/dist/entrypoints/live.js +16 -12
  55. package/dist/entrypoints/node.js +1 -1
  56. package/dist/entrypoints/server.js +4 -4
  57. package/dist/{index-s84he4v7.js → index-10x2hbx0.js} +4 -1
  58. package/dist/{index-js7gqrb1.js → index-c6bxbsnc.js} +5 -1
  59. package/dist/{index-y9qn426m.js → index-eaysmdtq.js} +10 -1
  60. package/dist/{index-xwhjjw2x.js → index-f4fx2tza.js} +119 -49
  61. package/dist/{index-p3vsv1fb.js → index-hadmp193.js} +14 -5
  62. package/dist/{index-0b1cnze2.js → index-vqr7f7v8.js} +31 -15
  63. package/dist/internal/coalesced-task.d.ts +2 -0
  64. package/dist/internal/coalesced-task.d.ts.map +1 -1
  65. package/dist/internal/process-instance.d.ts.map +1 -1
  66. package/dist/internal/with-exclusive-lock.d.ts.map +1 -1
  67. package/dist/server/realtime.d.ts.map +1 -1
  68. package/llms/agent-runtime.2.txt +13 -5
  69. package/llms/agent-runtime.3.txt +9 -4
  70. package/llms/agent-runtime.txt +8 -3
  71. package/llms/application.2.txt +47 -6
  72. package/llms/application.txt +18 -27
  73. package/llms/live.txt +2 -1
  74. package/llms/server.3.txt +22 -0
  75. package/llms/stitchkit.3.txt +9 -5
  76. package/llms/upgrading-0.74.0-0.100.0.txt +15 -3
  77. package/llms-full.txt +118 -29
  78. package/llms.txt +5 -5
  79. package/package.json +1 -1
package/llms-full.txt CHANGED
@@ -4888,7 +4888,7 @@ description: Configure Stitchkit's optional durable history, stream loop, run co
4888
4888
  type: architecture
4889
4889
  status: active
4890
4890
  created: 2026-08-22
4891
- updated: 2026-09-26 16:00 +07:00
4891
+ updated: 2026-09-28 18:39 +07:00
4892
4892
  ---
4893
4893
 
4894
4894
  # Agent application runtime
@@ -5505,9 +5505,14 @@ has invoked a tool is never automatically replayed.
5505
5505
  `createAgentScheduleService` persists `at`, `after` and `every` input. Repeating
5506
5506
  schedules require an explicit IANA time zone. Dispatch uses a stable
5507
5507
  `schedule:<id>:<occurrence>` idempotency key, and restart lateness is recorded.
5508
- Resolve `void` after durable admission; return `{ status: 'retry', reason }` for a
5508
+ Resolve after durable admission; return `{ status: 'retry', reason }` for a
5509
5509
  transient refusal or `{ status: 'terminal', reason }` to stop the entire schedule in
5510
- `failed` state. Throws retry too. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
5510
+ `failed` state. Only those two shapes are failures: any other returned value — a
5511
+ queue length, a receipt — means the callback returned, so it delivered. Throws retry
5512
+ too. `maxAttempts` (default 1000, about sixteen hours at the retry ceiling) bounds
5513
+ one occurrence: a one-off schedule then becomes `failed`, a recurring one gives up
5514
+ that occurrence (`schedule/failed` with `skipped: true` and the `nextAt` it moves
5515
+ to) and keeps its cadence. A failure reason is kept to 1000 characters. Backoff is 1, 2, 4, 8, 16, 32, then 60 seconds,
5511
5516
  capped at 60 seconds and persisted across restart. `retryAt`, `attempts` and `lastError`
5512
5517
  show retry diagnostics; success resets them. `nextAt` and `lateByMs` retain the original
5513
5518
  occurrence time. Recurring schedules fire once after an idle stretch and advance to the
@@ -6389,15 +6394,23 @@ hashes; `readPayload({ conversationId, artifactId }, context)` separately author
6389
6394
  `read-payload` and checks authentication tags and hashes. `payloadKey` must be 32
6390
6395
  bytes and is copied at construction. Keep it outside the event store/backups; retain
6391
6396
  the appropriate key when restoring an archive. `maxPayloadBytes` defaults to 4 MiB
6392
- (range 1 KiB–64 MiB); streaming output evidence is capped at 1 MiB. Request headers
6397
+ (range 1 KiB–64 MiB). Streaming output evidence keeps parts up to half of it; past
6398
+ that the evidence carries `truncated: { parts, sha256 }` over the whole stream, and
6399
+ the answer itself is never cut. A receipt that cannot be written never changes an
6400
+ outcome: `complete()` returns it with `receiptError` beside it, and a succeeded
6401
+ answer keeps its `text`. Request headers
6393
6402
  are excluded. Protect existing agent history independently: enabling receipts does
6394
6403
  not encrypt its ordinary conversation records.
6395
6404
 
6396
6405
  The built-in memory and SQLite stores implement `appendEventOnce`. Custom stores
6397
6406
  must implement its once-only check and append atomically, returning the original
6398
6407
  event on a duplicate key scoped by conversation and kind. A factory without this
6399
- capability refuses receipt setup. The driver-backed implementation reads bounded
6400
- pages under one transaction, without another table or database.
6408
+ capability refuses receipt setup. The driver-backed implementation finds the keyed
6409
+ event by its identity through the driver's optional `events.find` — one index probe
6410
+ in SQLite — so admission costs the same on a long conversation as on a new one; a
6411
+ custom driver without `find` falls back to paging the log in one transaction.
6412
+ `store.findEventOnce({ conversationId, kind, key })` reads the same event back.
6413
+ Invocation payload artifacts are keyed by their artifact id the same way.
6401
6414
 
6402
6415
  ### Migration from direct SDK completions
6403
6416
 
@@ -6405,8 +6418,8 @@ pages under one transaction, without another table or database.
6405
6418
  Replace the direct `generateText` call with `invocations.complete`, configure host
6406
6419
  authorization and a retained payload key, and pass the same ledger in the agent's
6407
6420
  `invocations` option. Use the returned invocation ID and the paginated `read` method
6408
- for receipt queries; do not import runtime internals. This API is unreleased; it is
6409
- not present in 0.99.0. Existing runtime configurations need no migration.
6421
+ for receipt queries; do not import runtime internals. Available since 0.100.0;
6422
+ existing runtime configurations need no migration.
6410
6423
 
6411
6424
 
6412
6425
  ==============================================================================
@@ -7277,7 +7290,8 @@ ever became ready:
7277
7290
  | none | — | — | `first-boot` | — |
7278
7291
  | recorded `stoppedAt` | — | — | `clean` / `forced` / `startup-failed` / `abnormal` as recorded | unchanged |
7279
7292
  | still open | yes | — | `hot-reload` | `hot-reload`, closed at the new start |
7280
- | still open | no | changed | `handoff` | stays open; it records its own stop later |
7293
+ | still open | no | changed | `handoff` (default) | stays open; it records its own stop later |
7294
+ | still open | no | changed, `versionChangeOverlap: 'abnormal'` | `abnormal` / `startup-failed` | closed at the new start, as for the same version |
7281
7295
  | still open, was ready | no | same | `abnormal` (default) | `abnormal`, closed at the new start — an upper bound, the crash time is unknown |
7282
7296
  | still open, never ready | no | same | `startup-failed` (default) | `startup-failed`, closed at the new start |
7283
7297
 
@@ -7319,7 +7333,22 @@ zero-downtime reload of the same build — pass `sameVersionOverlap: 'handoff'`
7319
7333
  to the ledger, and every open run stays open until it records its own
7320
7334
  shutdown. The cost of that setting is symmetric: a real crash under it is
7321
7335
  reported as a handoff and the dead run stays open in the ledger until
7322
- retention drops it. The list is kept in the order the transitions wrote it —
7336
+ retention drops it.
7337
+
7338
+ A version change is the other axis, and its default is the opposite:
7339
+ `handoff`, because a release that starts the new build before stopping the
7340
+ old one is the common zero-downtime shape. Where builds never overlap — one
7341
+ process per deployment (a pm2 fork, a systemd unit, one container), the old
7342
+ one stopped before the new one starts — pass `versionChangeOverlap:
7343
+ 'abnormal'`. An open predecessor of another build then died without
7344
+ recording its exit, most often killed during the release itself: it is closed
7345
+ as `abnormal` (or `startup-failed`) at the new start, `downtimeMs` is `null`
7346
+ instead of `0`, and `previousVersion` / `versionChanged` still describe the
7347
+ release. A predecessor that did record its stop is read as before, and its
7348
+ downtime is measured. The two settings compose: `sameVersionOverlap:
7349
+ 'handoff'` keeps open only the runs of a build allowed to overlap the new one.
7350
+
7351
+ The list is kept in the order the transitions wrote it —
7323
7352
  every write goes through one atomic update, so that order is the causal one,
7324
7353
  and a successor whose clock lags its predecessor still finds it at the head;
7325
7354
  `startedAt` is data, not the sort key. Retention (`retain`, default 20) drops
@@ -7424,6 +7453,9 @@ Opt into `delivery: { version, actions, project }` on `createNotificationOutbox`
7424
7453
  The pure `actions(payload)` selector runs at enqueue; the versioned plan remains
7425
7454
  fixed throughout retry. Each `send` receives its action and a stable idempotency
7426
7455
  key; return a small JSON receipt such as a remote message or uploaded object ID.
7456
+ An action that returned is confirmed and is never sent again: a result that is not
7457
+ JSON, or does not fit the state's byte budget, is kept as `receipt: null` with
7458
+ `unrecorded: 'not-json' | 'too-large'` and reported to `onError`.
7427
7459
  `project(notification, receipts)` applies all confirmed results locally and must
7428
7460
  be idempotent. Checkpoints and the final projection timestamp live in the existing
7429
7461
  atomic StateStore; completed receipts retain them within retention/byte limits.
@@ -7435,9 +7467,13 @@ not repeat confirmed sends. A crash after remote success but before receipt comm
7435
7467
  is ambiguous: the provider must deduplicate the action key or reconcile its result.
7436
7468
  A projection can also repeat if its completion checkpoint is lost.
7437
7469
 
7438
- A new executor version must explicitly migrate or terminally classify incompatible
7439
- queued plans. Existing `classify`/`onDropped` handles terminal items; a durable
7440
- quarantine is the application's responsibility. Whole-state file and memory stores
7470
+ A plan keeps its actions from enqueue, so an older version needs only its
7471
+ projection to finish: a new executor lists it in `retiredVersions: { v1: project }`
7472
+ until the queue has drained. A plan version the executor does not know is reported
7473
+ to `onError` as `NotificationPlanVersionError` and waits — at least a poll interval,
7474
+ spending no attempt, without `classify` — for a process that knows it: the other
7475
+ side of a rolling deploy, the version a rollback returns to, or this one once it
7476
+ lists the version. Whole-state file and memory stores
7441
7477
  remain supported. Atomic enqueue with an unrelated business transaction is not
7442
7478
  provided by this contract; retain the application's transactional adapter when that
7443
7479
  boundary is required. Send and projection callbacks own their external deadlines.
@@ -9927,6 +9963,28 @@ The nonce is not authorization: the server still admits a verified identity and
9927
9963
  uses `hub.attach(subscriber, { key: verifiedScope, signal: revocationSignal })`.
9928
9964
  The scope key must change with session and permission boundaries.
9929
9965
 
9966
+ One scope and one question share one source and one read, however many client
9967
+ instances watch it: the hub routes each frame to every instance under its own
9968
+ key. A new tab of the same session costs a route, not a read.
9969
+
9970
+ ### Capacity
9971
+
9972
+ A hub admits at most `maxSources` sources (1024) and `maxSubscribers` attached
9973
+ subscribers (1024); a client holds at most `maxKeys` keys (1024) and
9974
+ `maxListenersPerKey` listeners per key (128). Every excess is a refusal, never
9975
+ unbounded state: `open` answers `{ accepted: false, reason }` — including for a
9976
+ subscriber attached over capacity, whose `attach` returns a watcher that refuses
9977
+ every `open` — and a client's `subscribe` throws. A client handle takes its key
9978
+ when it subscribes, so handles a render creates and never subscribes cost
9979
+ nothing. A connection handler that throws closes that connection and is logged;
9980
+ the server goes on. A subscriber attached over capacity is not tracked: its
9981
+ refusals stand until it reconnects.
9982
+
9983
+ A read that fails sends its subscribers `unavailable` / `source-error` with the
9984
+ `code` and `message` of an `AppError`, which is written for its caller. Any other
9985
+ error reaches only the hub's `logger`; the browser reads `The watched read failed`. Set larger finite limits for larger workloads, and
9986
+ `reconcileIntervalMs` when a lost invalidation must recover without a reconnect.
9987
+
9930
9988
  `createCacheBridge` can bind watched handles directly:
9931
9989
 
9932
9990
  ```ts
@@ -13297,7 +13355,10 @@ must recover without a reconnect.
13297
13355
  For multi-action outboxes, enqueue new items with a versioned delivery plan and
13298
13356
  return small JSON receipts from `send`. Existing queued single-send items should
13299
13357
  be drained before enabling a delivery executor on that queue, or migrated under
13300
- the store's atomic transition. Preserve executor versions until their queues drain.
13358
+ the store's atomic transition. When a new executor version ships, list the old
13359
+ version's projection in `delivery.retiredVersions` until its queued items drain;
13360
+ a plan version with no executor waits, reported to `onError` as
13361
+ `NotificationPlanVersionError` (from 0.100.1).
13301
13362
  Make projection idempotent. Provider idempotency/reconciliation remains necessary
13302
13363
  for a crash between remote success and checkpoint. These APIs are available starting with 0.100.0.
13303
13364
 
@@ -13320,7 +13381,9 @@ write the modern record; no journal data migration is needed.
13320
13381
  Darwin distributions must retain the package's architecture-matched native
13321
13382
  `.node` asset for process birth measurement, as for contained filesystem access.
13322
13383
  If native/proc identity cannot be read, new locks explicitly record null and
13323
- recovery refuses rather than treating unknown ownership as death. Existing
13384
+ recovery refuses rather than treating unknown ownership as death. From 0.100.1 a
13385
+ Linux kernel without time namespaces (before 5.6) records the PID namespace alone
13386
+ instead of null, so its locks recover like any other. Existing
13324
13387
  `refuse` policy and the separately configured ownerless-file grace are unchanged.
13325
13388
 
13326
13389
  ## Released migration: 0.99.0
@@ -13338,13 +13401,20 @@ Colliding object/array fields retain their complete structural alternatives:
13338
13401
  { type: ['object', 'array'] }
13339
13402
  // After: structural alternatives live inside the property schema.
13340
13403
  { anyOf: [
13341
- { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
13342
13404
  { type: 'array', items: {
13343
13405
  type: 'object', properties: { id: { type: 'string' } }, required: ['id'],
13344
13406
  } },
13407
+ { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
13345
13408
  ] }
13346
13409
  ```
13347
13410
 
13411
+ Alternatives come in kind order, independent of variant order. The same shape
13412
+ covers every collision of different kinds, scalars included: `string` against
13413
+ `string[]` becomes `{ anyOf: [{ type: 'array', items: { type: 'string' } }, { type:
13414
+ 'string' }] }`. A nullable field keeps `null` in each alternative's `type`, and
13415
+ differing nested object unions remain nested `anyOf` inside the alternatives. Update
13416
+ snapshots to this order.
13417
+
13348
13418
  Traverse each nested alternative when inspecting schemas and regenerate schema
13349
13419
  snapshots. Verify the actual manifest with the chosen provider. Keep flatten
13350
13420
  enabled when a top-level discriminated union needs to be advertised as an
@@ -17292,18 +17362,22 @@ can emit / propagate a `traceparent` (see `HttpClientConfig.trace`).
17292
17362
 
17293
17363
  `createSessionScope` (`stitchkit`) returns the generic `SessionScope`: `replace(context)`
17294
17364
  creates a new login lifetime (including same-account relogin), `capture()` returns
17295
- its `SessionOperation<T>`, `clear()` invalidates it, and `stop()` permanently closes
17296
- the host. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
17365
+ its `SessionOperation<T>`, `clear()` invalidates it, `stop()` permanently closes
17366
+ the host, and `owns(operation)` answers whether an operation is this scope's current
17367
+ one — `current()` alone cannot tell an operation of another scope. Operations expose `id`, `generation`, `context`, `signal`, `current()` and
17297
17368
  `assertCurrent()`. `run(callback)` checks both success and failure across an await;
17298
17369
  `deliver(callback)` admits a synchronous final send/state change or returns false.
17299
17370
  `bindFetch(fetch, headers?)` guards every attempt and scopes its abort signal. Wrap
17300
17371
  the complete client call in `run` too: headers are not the response body boundary.
17301
- Expired work throws `SessionExpiredError`, not a refresh instruction.
17372
+ Expired work throws `SessionExpiredError`, not a refresh instruction; when the work
17373
+ itself failed, that failure is its `cause`.
17302
17374
 
17303
17375
  `createSessionCredentials` accepts `SessionCredentialsConfig`:
17304
17376
  `scope`, `refresh(credentials, signal)`, `storage.write(session, credentials)`,
17305
- `storage.clear()`, `maxPendingWrites` (128), and `refreshTimeoutMs` (30000, at most one
17306
- hour). `SessionCredentials` provides `login`, `logout`, `read(operation)` and
17377
+ `storage.clear()`, `maxPendingWrites` (128), `refreshTimeoutMs` (30000, at most one
17378
+ hour) and `storageTimeoutMs` (30000, at most one hour): a storage call past it
17379
+ rejects and frees the queue, so `logout()` still clears; when the late call settles,
17380
+ storage is written again from memory, or cleared when nobody is logged in. `SessionCredentials` provides `login`, `logout`, `read(operation)` and
17307
17381
  `refresh(operation)`. Concurrent refresh calls in one generation share the same
17308
17382
  promise. Logout invalidates memory before its returned persistence promise settles.
17309
17383
  Storage errors and queue-capacity refusals reject; callers must handle them. All
@@ -17453,7 +17527,8 @@ realtime contract from `stitchkit`, and the server halves live in `stitchkit/app
17453
17527
  ### Session-scoped watch lifetime
17454
17528
 
17455
17529
  `WatchClientConfig.session` captures a `SessionOperation`; `maxKeys` (1024) and
17456
- `maxListenersPerKey` (128) bound retained subscriptions. Its lifetime nonce travels
17530
+ `maxListenersPerKey` (128) bound retained subscriptions; a handle takes its key on
17531
+ `subscribe`, which is where capacity refuses. Its lifetime nonce travels
17457
17532
  in optional `WatchKey.instance`, preventing old-session frames from matching a new
17458
17533
  client on the same socket. This is routing identity, never authorization.
17459
17534
 
@@ -17752,7 +17827,7 @@ cutovers are covered by the executable
17752
17827
  | `LifecycleRunSchema` / `LifecycleRun` / `LifecycleStateSchema` / `LifecycleState` / `LifecycleTerminationSchema` / `LifecycleTermination` | schema / _type_ | versioned process-run state — open (`active`, `draining` with `unavailableAt`) and ended (`clean`, `forced`, `startup-failed`, `hot-reload`, `abnormal`) |
17753
17828
  | `PreviousExitSchema` / `PreviousExit` / `StartFact` / `ReadyFact` / `DrainingFact` / `ShutdownFact` / `ProcessLifecycleFact` | schema / _type_ | first-boot, hot-reload, clean, forced, startup-failed, handoff and abnormal lifecycle facts; `processGapMs` on start, `downtimeMs` (unavailable → ready) on ready |
17754
17829
  | `transitionProcessStart` / `transitionProcessReady` / `transitionProcessDraining` / `transitionProcessShutdown` | function | pure idempotent runId+pid-owned transitions |
17755
- | `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`) and state+fact result |
17830
+ | `LifecycleTransition` / `TransitionStartInput` / `TransitionRunInput` / `TransitionShutdownInput` / `SameVersionOverlap` / `VersionChangeOverlap` | _type_ | pure transition inputs (`TransitionRunInput` for ready and draining, extended with `forced` for shutdown), the same-build overlap policy (`abnormal` default / `handoff`), the version-change overlap policy (`handoff` default / `abnormal`) and state+fact result |
17756
17831
  | `lifecycleLedgerResource` / `LifecycleLedgerResource` / `LifecycleLedgerResourceConfig` | function / _type_ | managed-resource adapter that records start, readiness, admission stop (draining) and shutdown |
17757
17832
  | `createNotificationOutbox` / `NotificationOutbox` / `NotificationOutboxConfig` | function / _type_ | bounded at-least-once queue with durable claims, leases, retries and supersede |
17758
17833
  | `NotificationOutboxItem` / `NotificationOutboxReceipt` / `NotificationOutboxState` / `NotificationSend` / `NotificationFailureClassification` / `DroppedNotification` / `EnqueueNotification` | _type_ | versioned queue records, stable send identity and delivery decisions |
@@ -17966,7 +18041,10 @@ periodically even when no notification arrives.
17966
18041
  `reconcileIntervalMs` (10 ms–1 h). `hub.attach(subscriber, scope?)` accepts a
17967
18042
  `WatchAdmissionScope` containing a **server-verified** `key` (1–512 characters) and
17968
18043
  revocation `signal`. The key separates sharing and is the optional third argument
17969
- of `read(operation, args, scope)`. It must represent account, session and permissions;
18044
+ of `read(operation, args, scope)`; a key's `instance` routes frames and never
18045
+ separates sources. Attached over `maxSubscribers`, a subscriber gets a watcher whose
18046
+ `open` refuses with `Watch subscriber capacity exceeded`; `attach` does not throw
18047
+ for capacity. It must represent account, session and permissions;
17970
18048
  never trust a client-supplied owner ID as that scope.
17971
18049
 
17972
18050
 
@@ -17977,7 +18055,13 @@ never trust a client-supplied owner ID as that scope.
17977
18055
  immutable executor `version`, pure `actions(payload)` plan selector (1–128 unique
17978
18056
  names, each at most 128 characters), and idempotent `project(notification, receipts)`.
17979
18057
  `send` receives optional `action` and stable `idempotencyKey`, and returns a JSON
17980
- remote receipt (void becomes null). `NotificationDeliveryStateSchema` validates the
18058
+ remote receipt (void becomes null). A result that is not JSON or does not fit the
18059
+ byte budget is kept as `receipt: null` with `unrecorded: 'not-json' | 'too-large'`;
18060
+ the action stays confirmed and is not sent again. `retiredVersions` maps earlier
18061
+ plan versions to their `NotificationProjection` so queued items drain after an
18062
+ executor upgrade; an unknown version is reported to `onError` as
18063
+ `NotificationPlanVersionError` and waits, spending no attempt and not consulting
18064
+ `classify`, for an executor that knows it. `NotificationDeliveryStateSchema` validates the
17981
18065
  optional `NotificationDeliveryState` on queued items and completed receipts:
17982
18066
  `version`, `actions`, `receipts` and optional `projectedAt`. Checkpoints share the
17983
18067
  existing atomic StateStore and lease fence. Receipt retention and serialized byte
@@ -18163,7 +18247,7 @@ Server-only optional application runtime. See the
18163
18247
  | `AgentSandboxProcess` / `AgentSandboxOutputStream` | _types_ | structural child/output interface for optional lifecycle-owned `AgentProcessSandbox.spawn`, without Node ambient type dependencies |
18164
18248
  | `AgentEventSearchResultSchema` / `AgentEventSearchResult` / `createSqliteAgentEventSearch` / `createAgentEventSearchTools` | schema / _type_ / functions | authorized FTS5 search with exact event addresses and `session_*` tools |
18165
18249
  | `createSqliteAgentSpillStore` | function | durable content-address-checked artifact storage, bounded read/search, retention facts and archive participation |
18166
- | `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure, bounded dispatch and fenced stable occurrence identity (ADR 0202) |
18250
+ | `AgentScheduleSchema` / `AgentSchedule` / `AgentScheduleService` / `AgentScheduleDeliveryOutcomeSchema` / `AgentScheduleDeliveryOutcome` / `createAgentScheduleService` / `createAgentScheduleTools` | schemas / _types_ / functions | durable `at`/`after`/timezone-explicit `every`, indexed retry eligibility, typed retry/terminal failure (any other returned value delivers), `maxAttempts` (default 1000) per occurrence — a one-off ends `failed`, a recurring schedule skips to its next slot — bounded dispatch and fenced stable occurrence identity (ADR 0202) |
18167
18251
  | `AgentChildBudgetSchema` / `AgentChildBudget` / `AgentChildStateSchema` / `AgentChildState` / `AgentChildRecordSchema` / `AgentChildRecord` | schema / _type_ | durable child graph, bounded seed and measured budget state |
18168
18252
  | `AgentChildBlockingKindSchema` / `AgentChildBlockingKind` / `AgentChildBlockingSourceSchema` / `AgentChildBlockingSource` / `AgentChildBlockingEventSchema` / `AgentChildBlockingEvent` / `AgentChildBlockingDecision` | schemas / _types_ | parent-owned request identities; responses discriminate approval decisions from JSON input values |
18169
18253
  | `AgentChildHandle` / `AgentChildManager` / `SqliteAgentChildManagerConfig` / `createSqliteAgentChildManager` / `createAgentChildTools` / `agentChildBudgetStopPolicy` | _type_ / functions | host execution port, child lifecycle, cascade (given to `createAgentRuntime` as `children`), messaging, Agent tools, and the child runtime's own budget stop policy — `recordStepUsage` at every step boundary, `policy_stop` as `child-budget` when spent |
@@ -18324,7 +18408,9 @@ operator-only observability sink explicitly opts in.
18324
18408
  `ModelInvocationConfig`: the existing store and model registry, a 32-byte payload
18325
18409
  key, required host authorization, optional bounded payload size and `onAttempt`.
18326
18410
  `complete(input, context, signal?)` executes only the supplied prompt, with no tools
18327
- or framework instructions; repeated keys return the existing invocation ID.
18411
+ or framework instructions; repeated keys return the existing invocation ID. It
18412
+ resolves `{ invocationId, outcome, text?, receiptError? }`: `receiptError` says a
18413
+ receipt could not be written and never changes `outcome` or drops `text`.
18328
18414
  `read(input, context)` returns a bounded event page shared by agent and completion;
18329
18415
  `readPayload(input, context)` requires a separate authorization action to decrypt
18330
18416
  one protected artifact. See the [guide and migration example](../guide/agent-runtime.md#plain-completions-and-shared-invocation-receipts).
@@ -18339,8 +18425,11 @@ one protected artifact. See the [guide and migration example](../guide/agent-run
18339
18425
 
18340
18426
  The runtime `invocations` option takes this ledger and a trace callback; it requires
18341
18427
  the same store and preserves the existing tool loop. `AgentRuntimeStore.appendEventOnce`
18342
- is an optional atomic capability required by receipt admission. Built-in stores
18343
- supply it; custom adapters must honor its once-only transaction contract.
18428
+ is an optional atomic capability required by receipt admission, and
18429
+ `AgentRuntimeStore.findEventOnce` reads the event it wrote by kind and key. Built-in
18430
+ stores supply both; custom adapters must honor the once-only transaction contract.
18431
+ A driver's optional `events.find(transaction, { conversationId, eventId })` makes
18432
+ both one lookup instead of a scan of the conversation log.
18344
18433
 
18345
18434
  ## `stitchkit/agent-runtime/testing`
18346
18435
 
package/llms.txt CHANGED
@@ -9,7 +9,7 @@ Build with stitchkit: define a contract once, then `implement` it and serve it (
9
9
  Load the slice for each entrypoint your code imports — `import … from 'stitchkit/server'` → `llms/server.txt`; the root `stitchkit` import → `llms/stitchkit.txt`. A slice holds that entrypoint's API reference section and the guide pages whose home it is; every guide lives in exactly one slice, and a slice that needs another's guide names it under "Also read". Each file is at most 50.0 KB; a longer one continues in numbered parts, each naming the next at its top. Moving across versions: load `llms/upgrading.txt` and the range slices it lists between your version and the target. `llms-full.txt` inlines everything; it is far larger than a context window, so do not read it whole.
10
10
 
11
11
  ## Entrypoint slices
12
- - **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 37.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 15.7 KB
12
+ - **stitchkit**: [llms/stitchkit.txt](llms/stitchkit.txt) 15.6 KB → [llms/stitchkit.2.txt](llms/stitchkit.2.txt) 37.2 KB → [llms/stitchkit.3.txt](llms/stitchkit.3.txt) 16.1 KB
13
13
  - **stitchkit/live**: [llms/live.txt](llms/live.txt) 21.6 KB
14
14
  - **stitchkit/react**: [llms/react.txt](llms/react.txt) 9.0 KB
15
15
  - **stitchkit/tools**: [llms/tools.txt](llms/tools.txt) 45.0 KB → [llms/tools.2.txt](llms/tools.2.txt) 26.3 KB → [llms/tools.3.txt](llms/tools.3.txt) 25.4 KB
@@ -20,9 +20,9 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
20
20
  - **stitchkit/remote**: [llms/remote.txt](llms/remote.txt) 1.0 KB
21
21
  - **stitchkit/contract**: [llms/contract.txt](llms/contract.txt) 31.9 KB
22
22
  - **stitchkit/primitives**: [llms/primitives.txt](llms/primitives.txt) 9.3 KB
23
- - **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 44.3 KB → [llms/server.4.txt](llms/server.4.txt) 37.5 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
23
+ - **stitchkit/server**: [llms/server.txt](llms/server.txt) 45.3 KB → [llms/server.2.txt](llms/server.2.txt) 14.6 KB → [llms/server.3.txt](llms/server.3.txt) 45.6 KB → [llms/server.4.txt](llms/server.4.txt) 37.5 KB → [llms/server.5.txt](llms/server.5.txt) 21.8 KB
24
24
  - **stitchkit/observability**: [llms/observability.txt](llms/observability.txt) 43.4 KB
25
- - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.4 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.1 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 33.8 KB
25
+ - **stitchkit/agent-runtime**: [llms/agent-runtime.txt](llms/agent-runtime.txt) 36.8 KB → [llms/agent-runtime.2.txt](llms/agent-runtime.2.txt) 46.7 KB → [llms/agent-runtime.3.txt](llms/agent-runtime.3.txt) 34.3 KB
26
26
  - **stitchkit/agent-runtime/testing**: [llms/agent-runtime-testing.txt](llms/agent-runtime-testing.txt) 2.2 KB
27
27
  - **stitchkit/agent-runtime/harness**: [llms/agent-runtime-harness.txt](llms/agent-runtime-harness.txt) 4.1 KB
28
28
  - **stitchkit/agent-runtime/coding-tools**: [llms/agent-runtime-coding-tools.txt](llms/agent-runtime-coding-tools.txt) 4.9 KB
@@ -30,7 +30,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
30
30
  - **stitchkit/agent-runtime/openrouter**: [llms/agent-runtime-openrouter.txt](llms/agent-runtime-openrouter.txt) 1.1 KB
31
31
  - **stitchkit/agent-runtime/sqlite/bun**: [llms/agent-runtime-sqlite-bun.txt](llms/agent-runtime-sqlite-bun.txt) 1.8 KB
32
32
  - **stitchkit/agent-runtime/sqlite/node**: [llms/agent-runtime-sqlite-node.txt](llms/agent-runtime-sqlite-node.txt) 1.7 KB
33
- - **stitchkit/application**: [llms/application.txt](llms/application.txt) 46.6 KB → [llms/application.2.txt](llms/application.2.txt) 37.2 KB
33
+ - **stitchkit/application**: [llms/application.txt](llms/application.txt) 46.0 KB → [llms/application.2.txt](llms/application.2.txt) 40.0 KB
34
34
  - **stitchkit/application/grammy**: [llms/application-grammy.txt](llms/application-grammy.txt) 2.3 KB
35
35
  - **stitchkit/application/opentelemetry**: [llms/application-opentelemetry.txt](llms/application-opentelemetry.txt) 1.6 KB
36
36
  - **stitchkit/application/directory-inbox**: [llms/application-directory-inbox.txt](llms/application-directory-inbox.txt) 0.3 KB
@@ -52,7 +52,7 @@ Load the slice for each entrypoint your code imports — `import … from 'stitc
52
52
 
53
53
  ## Upgrading slices
54
54
  - **Upgrading — how to move across versions**: [llms/upgrading.txt](llms/upgrading.txt) 10.3 KB
55
- - **Upgrading 0.74.0 → 0.100.0**: [llms/upgrading-0.74.0-0.100.0.txt](llms/upgrading-0.74.0-0.100.0.txt) 44.3 KB
55
+ - **Upgrading 0.74.0 → 0.100.0**: [llms/upgrading-0.74.0-0.100.0.txt](llms/upgrading-0.74.0-0.100.0.txt) 45.1 KB
56
56
  - **Upgrading 0.61.0 → 0.73.0**: [llms/upgrading-0.61.0-0.73.0.txt](llms/upgrading-0.61.0-0.73.0.txt) 41.2 KB
57
57
  - **Upgrading 0.44.0 → 0.60.0**: [llms/upgrading-0.44.0-0.60.0.txt](llms/upgrading-0.44.0-0.60.0.txt) 43.9 KB
58
58
  - **Upgrading 0.37.0 → 0.37.0**: [llms/upgrading-0.37.0.txt](llms/upgrading-0.37.0.txt) 6.2 KB
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "stitchkit",
3
- "version": "0.100.0",
3
+ "version": "0.100.2",
4
4
  "description": "Contract-first backend framework — one defineContract() into an HTTP API, MCP tools, AI-agent tools and a typed client. Bun and Node.",
5
5
  "keywords": [
6
6
  "bun",