@byok-sdk/bot-collaboration 0.0.0-stage → 0.43.0

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 (74) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +2075 -2
  3. package/dist/adapter-steps.d.ts +49 -0
  4. package/dist/channel.d.ts +111 -0
  5. package/dist/chunk-33YA66U7.js +7 -0
  6. package/dist/chunk-33YA66U7.js.map +1 -0
  7. package/dist/chunk-6Y2B2XCP.js +12 -0
  8. package/dist/chunk-6Y2B2XCP.js.map +1 -0
  9. package/dist/chunk-QZRWFFHM.js +12 -0
  10. package/dist/chunk-QZRWFFHM.js.map +1 -0
  11. package/dist/chunk-ZX6C5U2S.js +27 -0
  12. package/dist/chunk-ZX6C5U2S.js.map +1 -0
  13. package/dist/coalesce.d.ts +18 -0
  14. package/dist/commit-vectors.test-support.d.ts +173 -0
  15. package/dist/commit.d.ts +53 -0
  16. package/dist/compaction.d.ts +13 -0
  17. package/dist/delegation.d.ts +12 -0
  18. package/dist/delivery-routing.d.ts +63 -0
  19. package/dist/delivery-vectors.test-support.d.ts +78 -0
  20. package/dist/delivery.d.ts +20 -0
  21. package/dist/dream.d.ts +88 -0
  22. package/dist/home-projections.d.ts +5 -0
  23. package/dist/host-kit.d.ts +60 -0
  24. package/dist/host-kit.js +11 -0
  25. package/dist/host-kit.js.map +1 -0
  26. package/dist/host.d.ts +472 -0
  27. package/dist/inbound.d.ts +17 -0
  28. package/dist/index.d.ts +6 -0
  29. package/dist/index.js +19 -0
  30. package/dist/index.js.map +1 -0
  31. package/dist/k4-fixtures.test-support.d.ts +10 -0
  32. package/dist/l-test-host.test-support.d.ts +72 -0
  33. package/dist/migration.d.ts +251 -0
  34. package/dist/model.d.ts +89 -0
  35. package/dist/persona.d.ts +2 -0
  36. package/dist/retention-vectors.test-support.d.ts +17 -0
  37. package/dist/retention.d.ts +61 -0
  38. package/dist/rooms.d.ts +22 -0
  39. package/dist/routine-vectors.test-support.d.ts +81 -0
  40. package/dist/routines.d.ts +110 -0
  41. package/dist/rules/autonomy.d.ts +67 -0
  42. package/dist/rules/cards.d.ts +31 -0
  43. package/dist/rules/coalesce.d.ts +111 -0
  44. package/dist/rules/commands.d.ts +306 -0
  45. package/dist/rules/commit.d.ts +82 -0
  46. package/dist/rules/compaction.d.ts +33 -0
  47. package/dist/rules/context.d.ts +484 -0
  48. package/dist/rules/delegation.d.ts +366 -0
  49. package/dist/rules/due.d.ts +15 -0
  50. package/dist/rules/frame.d.ts +4 -0
  51. package/dist/rules/history.d.ts +34 -0
  52. package/dist/rules/inbound.d.ts +53 -0
  53. package/dist/rules/index.d.ts +13 -0
  54. package/dist/rules/index.js +4 -0
  55. package/dist/rules/index.js.map +1 -0
  56. package/dist/rules/message.d.ts +31 -0
  57. package/dist/rules/outcome.d.ts +45 -0
  58. package/dist/rules/priority.d.ts +52 -0
  59. package/dist/rules/rooms.d.ts +187 -0
  60. package/dist/rules/schema.d.ts +110 -0
  61. package/dist/rules/sync.d.ts +157 -0
  62. package/dist/rules/team.d.ts +119 -0
  63. package/dist/rules/turn.d.ts +129 -0
  64. package/dist/schema.d.ts +154 -0
  65. package/dist/store-compatibility.d.ts +3 -0
  66. package/dist/switch.d.ts +53 -0
  67. package/dist/team-model.d.ts +54 -0
  68. package/dist/team.d.ts +56 -0
  69. package/dist/testing.d.ts +6 -0
  70. package/dist/testing.js +20 -0
  71. package/dist/testing.js.map +1 -0
  72. package/dist/toolset-policy.d.ts +2 -0
  73. package/dist/topology.d.ts +49 -0
  74. package/package.json +80 -4
package/README.md CHANGED
@@ -1,3 +1,2076 @@
1
- # Temporary Holding Version
1
+ # Bot collaboration
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ `@byok-sdk/bot-collaboration` implements K8a and K8b in the Bot PRD. A Host
4
+ installs it with the other SDK packages of the same version. It uses the K4
5
+ Host execution core (`@byok-sdk/server/execution-core`) and the K8-S public
6
+ schema and calendar APIs. It has no paid runtime call. Tests use a synthetic
7
+ adapter with the real SDK, daemon, HTTP transport, SQLite stores, and
8
+ `submit_result` helper.
9
+
10
+ ## Entries
11
+
12
+ Each symbol has one entry (#1845). K4 needs Node 24.22.1 or later, because its ledger uses `node:sqlite`.
13
+
14
+ | Entry | Contents | Loads where |
15
+ | --- | --- | --- |
16
+ | `.` | `BotCollaboration` and its option types, `botCompactVeto`, `createBotPersonaProjection`, `teamSnapshot` and its errors | Node only. It loads the L Host and `@byok-sdk/client`. |
17
+ | `./host-kit` | The L modules a Host adapter composes: model, channel, delivery, routines, team, migration, retention, dreaming, adapter steps | Node or a Worker. It loads the K4 root entry, but not the L Host or `@byok-sdk/client`. The hosted Worker example bundles it. |
18
+ | `./rules` | The pure rules that the two entries above do not export | Anywhere. It loads only `@byok-sdk/protocol` and `@byok-sdk/server/execution-core/canonical`, so no `node:sqlite`. |
19
+ | `./testing` | The shared vectors, the L test Host, and the K4 test data `policy` and `template` | Tests on Node. It needs the optional peers `vitest` and `@hono/node-server`. |
20
+
21
+ `openLTestHost` requires a `deviceCredentials` backend from the caller. In tests,
22
+ import `InMemoryDeviceCredentialBackend` from `@byok-sdk/client/testing` and pass
23
+ `deviceCredentials: new InMemoryDeviceCredentialBackend()` along with `consume`.
24
+ The fixture passes that backend to its daemon; it supplies no default.
25
+
26
+ ## Run
27
+
28
+ Use Node 24.15 or later and Bun. From the repository root:
29
+
30
+ ```sh
31
+ bun install --frozen-lockfile
32
+ bun run build
33
+ bun run --cwd packages/bot-collaboration typecheck
34
+ bun run --cwd packages/bot-collaboration test
35
+ ```
36
+
37
+ `src/host.test.ts` shows the embedded setup. Create one `BotCollaboration`
38
+ per tenant and ledger. Open that ledger with the K8 compact veto:
39
+ `new HostLedger(file, tenant, { compactVeto: botCompactVeto })`. The
40
+ constructor refuses a ledger without it ([Compaction](#compaction)). Give it a valid Agent execution template and a Host
41
+ connector. Route the embedded server's `wake.consume` to `bot.consume`.
42
+ Route its `agentMessage.consume` to `bot.consumeMessage`.
43
+ Call `bot.recover()` after startup. Call `bot.close()` before closing the SDK
44
+ server or the ledger. Do not call the K4 core's mutation methods directly.
45
+ Use `input`, `answer`, `decide`, `cancelTurn`, `enqueueHostIntent`, `cancelHostIntent`, `updateRoutine`, `setRoutineLifecycle`, `endRoutine`, `cancelDelegation`, and `abandonDelegation`.
46
+ Use `receive` for IM messages ([IM channel input](#im-channel-input)).
47
+ Use `autonomy`, `wouldDoRecords` and `setBotAutonomy` for the owner's observe/auto switch
48
+ ([Bot autonomy](#bot-autonomy-observe-and-auto-1229)).
49
+ Read `inboundDispositions` for the destination of every inbound human message
50
+ ([Inbound disposition](#inbound-disposition-1229)).
51
+ Read `snapshot` or upload K4 projections with `core.flushProjections`.
52
+ Read `inputRoot` to learn whether an `input` committed ([Input root](#input-root-1407)).
53
+
54
+ The execution template selects this Bot's Agent. It must use a runtime profile
55
+ without external-effect connector tools or ambient credentials. Required MCP
56
+ toolsets are refused by default. A Host may explicitly declare logical IDs with
57
+ `readOnlyToolsets: ['market.read']` when it controls the local tool server and
58
+ enforces read-only behavior there. The execution's `requiredToolsets` still
59
+ selects those IDs through the ordinary daemon admission path. This declaration
60
+ is not inferred from model output or MCP annotations and is not proof that a
61
+ tool has no effects. The Host connector stays outside the Agent. This example does not
62
+ provide a runtime sandbox. The deployment owns that boundary.
63
+
64
+ The constructor owns copies of execution/model templates and the allowlist;
65
+ mutating the caller's configuration later cannot widen admission. Every model, restored non-archived Bot execution and outstanding frozen intent/execution
66
+ must satisfy the policy, as must Bot creation,
67
+ updates and turn enqueue. A restart with a narrower policy fails closed when
68
+ persisted Bot templates or pending execution inputs require removed IDs. The
69
+ check covers the current Bot template, so it skips archived Bots. An archived
70
+ Bot never runs a new Turn. Its outstanding frozen work still must satisfy the
71
+ policy. Settled historical execution records remain readable. Change those
72
+ templates through an authorized Host migration before reopening; this slice adds
73
+ no migration API.
74
+ Effectful actions still use `confirmable_action` and owner confirmation.
75
+ This is the same-device read-only toolset slice of #606; external-authority
76
+ storage and two-process relay remain separate.
77
+
78
+ `bot.core` is public, but the rule to avoid direct K4 mutation calls still
79
+ holds. To run the Host's own work on this tenant's core, register a handler in
80
+ `hostIntents` and call `enqueueHostIntent(input, handler)` (#882). One ledger
81
+ transaction enqueues the K4 intent and stores the handler name, so the owner of
82
+ the intent survives a restart. A restart refuses an open Host intent whose
83
+ handler is not registered. At a `task.complete` terminal, the handler runs
84
+ synchronously in the terminal transaction with the result document. Bot output
85
+ never reaches it. The call uses the Host's own authority and bypasses Bot
86
+ policy. Its execution still passes the read-only toolset admission, because a
87
+ restart admits every open intent. A Host intent shares the FIFO of its Agent: on
88
+ a Bot's agentRef, that Bot's later Turns wait until it settles. An exact replay
89
+ returns the same intent while K4 keeps it.
90
+
91
+ An Agent message of a Host intent goes to the message handler of the same name
92
+ in `hostIntentMessages` (#1356). The handler runs synchronously in the K4
93
+ message transaction and returns the `MessageDisposition` that K4 records:
94
+ `{ outcome: 'accepted' }` or `{ outcome: 'refused', reasonCode }`. K8 does not
95
+ deliver the body; the handler delivers it with `tx.publish` or the Host's own
96
+ channel. A handler that throws rolls the transaction back, so neither K8 nor K4
97
+ writes anything, and a handler that returns a promise or another shape throws
98
+ too. An accepted message is recorded in `replies` under its task id, with the
99
+ intent key as `turnId` and no body, so a replay is accepted without the
100
+ handler. A refused message keeps its command record, so a replay gets the same
101
+ refusal without the handler and other content for the same message id gets
102
+ `message_conflict`. A Host intent whose name has no message handler refuses its
103
+ messages with `binding_mismatch`. A name in `hostIntentMessages` needs a
104
+ `hostIntents` handler. `enqueueHostIntent` refuses an execution with
105
+ `messageEgress` whose name has no message handler, and a restart refuses an
106
+ open such intent whose message handler is not registered. The pass that removes
107
+ a compacted Host intent's record also removes its replies.
108
+
109
+ Cancel a Host intent with the owner call `cancelHostIntent(key)` (#1320), not
110
+ with `bot.core.cancel`. K4 records the cancel on the intent row, so a restart
111
+ reads the same fact. For an intent that was not submitted, `{ result: 'cancelled' }`
112
+ confirms that the cancel committed. Its `conclusion` is optional: if `drainError`
113
+ or `wakePending` accompanies an unfinished settlement, the field is absent until
114
+ a later successful drain settles it as `cancelled`. Its handler does not run,
115
+ and settlement advances its FIFO. A submitted or running intent gets an SDK cancel, and
116
+ the call returns `{ result: 'cancel_pending' }` at once. K4 then settles it: a
117
+ cancelled terminal runs no handler, but a `task.complete` that arrived before the
118
+ cancel still runs the handler once. Read the final conclusion with
119
+ `bot.core.intent(key)`. A settled intent returns `{ result: 'already_settled' }`
120
+ with its conclusion and sends nothing, so a replay does not fail. After retrying
121
+ pending work with `drain()` or recovery, replay `cancelHostIntent(key)` to obtain
122
+ `already_settled` with the conclusion, or `cancel_pending` while a submitted
123
+ intent awaits its terminal. A queued intent whose settlement still fails can
124
+ again return `cancelled` without a conclusion. Check `'drainError' in result`
125
+ for post-commit failures; the coalesced drain may have failed on other Host work.
126
+ The call throws
127
+ `HostIntentError` with `unknown_intent` for a key that is not a Host intent and
128
+ `not_host_intent` for a Bot Turn key; cancel a Bot Turn with `cancelTurn`. A
129
+ cancel does not release a `handler_failed` intent, because K4 applies its
130
+ terminal again; `failStuckIntent` below is the way out.
131
+
132
+ `cancelHostIntents(keys)` cancels a chosen set atomically without a pass (#2003).
133
+ It refuses the entire set if any key is unknown, a Bot Turn or in flight;
134
+ `HostIntentError.rejected` lists every refused key and code in input order.
135
+ Settled keys return their earlier conclusion. After K4 compacts an intent, a
136
+ replay of that key returns `unknown_intent` instead of `already_settled`.
137
+ No handler runs for cancelled keys.
138
+ Successors wait for a later pass; call `drain()` to start them immediately.
139
+ A frozen device accepts this call. Duplicate keys and non-owner calls are refused.
140
+
141
+ A K4 terminal that K8 cannot apply leaves its intent open: a key that is neither
142
+ a Bot Turn nor a Host intent, for example from a direct `bot.core.enqueue`
143
+ (`unknown_intent`), a Host handler that throws or returns a promise
144
+ (`handler_failed`), or a Bot Turn whose outcome commit throws, for example a
145
+ document outside its frozen schema (`outcome_failed`). After the owner call, the
146
+ next sync settles such a Bot Turn as `failed` and reports it. Then `drain()` rejects with
147
+ `IntentOutcomeError`, and so does every API that runs a pass, including `input`
148
+ and the `wake.consume` hook. The audit gets one row for each key and reason. The
149
+ intent stays at the head of its FIFO until its outcome applies, for example
150
+ after a restart with a fixed handler, or until the owner calls
151
+ `failStuckIntent(key)`. That call runs a K4 drain first, so it also works right
152
+ after a restart. If that drain refuses the intent's terminal again, one
153
+ transaction settles the intent as `failed` with the K4 `settle` transition and
154
+ adds the audit row `Intent failed by owner <code>: <key> <reason>`. The settle
155
+ runs no handler, and the intent records no terminal; the server task keeps it.
156
+ The drain before the settle applies the terminal once more, so a `handler_failed`
157
+ handler runs once inside the call. If that drain applies the outcome, the call
158
+ refuses with `already_settled`. If that drain rejects and the intent has
159
+ no refusal of its own, the call throws the drain error. Later drains move past
160
+ the intent. The call settles the key first. Its closing pass, like every API
161
+ that runs a pass, rejects if another intent is stuck, and a retry for this key
162
+ then refuses with `already_settled`. A Host intent keeps its `hostIntents` record until K4 compacts it,
163
+ so an exact replay of `enqueueHostIntent` returns the failed intent. The call
164
+ refuses with `HostIntentError`: `unknown_intent` for a key with no K4 intent,
165
+ `already_settled` for a settled intent, and `not_stuck` for an intent whose
166
+ terminal K8 did not refuse, such as one still running. The settle of a Bot Turn
167
+ also writes the refusal code to the Turn as `settleCode: 'outcome_failed'`, in
168
+ the ledger and in its `bot-turn:<id>` projection, so a reader does not match the
169
+ audit row (#1405). A Host intent and a key that K8 did not write keep the code
170
+ only in the audit row. `BotOptions` passes `reconcileMs` (default 100) and
171
+ `onOutbox` to the K4 core.
172
+
173
+ ### Idempotent owner cancels (#1405)
174
+
175
+ `cancelTurn(id)` and `cancelDelegation(id)` return a result in the shape of
176
+ `cancelHostIntent`, read from the ledger, so a replay and a restart give the
177
+ same answer: `TurnCancelResult` `{ turnId, result, conclusion? }` and
178
+ `DelegationCancelResult` `{ delegationId, result, verdict? }`.
179
+
180
+ - `cancelled`: this call committed the cancel.
181
+ - `cancel_pending`: an earlier cancel has no terminal yet: the Turn's K4 intent
182
+ has a `cancelReason`, or the delegation has a cancel fact and no verdict. The
183
+ call writes nothing and does not call `core.cancel`. A cancel fact that is not
184
+ delivered yet still goes out with the next pass.
185
+ - `already_settled`: the target had ended, and the call writes nothing. A Turn
186
+ gives its earlier `conclusion` (its K4 intent's when it has one), a
187
+ delegation its `verdict`.
188
+
189
+ `cancelTurn` on B's chain Turn whose delegation has no verdict answers as
190
+ `cancelDelegation` does; once the verdict is in, it answers from the Turn. An
191
+ input batch id or a member input id names the batch Turn, and an open batch
192
+ commits its seal, so it gives `cancelled`. A Turn id that is not in the state
193
+ still throws `Turn not found`.
194
+
195
+ `cancelDelegation` refuses with `DelegationError`, whose `key` is the
196
+ delegation id: `unknown_delegation`, and `not_cancellable` for a `reply_held`
197
+ or `uncertain` delegation; end those with `abandonDelegation`. Both error
198
+ classes extend `Error`, so an `instanceof Error` check still holds, and the
199
+ messages are the same as before.
200
+
201
+ ### Input root (#1407)
202
+
203
+ `input` commits first and then runs a pass, so it can reject with a drain error
204
+ after the input committed, and the Turn still runs. `inputRoot(key, botId)` is
205
+ read-only: it returns the id that `input` returns for that key and Bot, from the
206
+ input's command record, or `undefined` when no input with that key committed.
207
+ It runs no pass, writes nothing and does not change the K8 revision, so it
208
+ gives the same answer after a restart. A record that retention moved still
209
+ answers until its row expires; the key then reads as not committed. The call
210
+ checks no principal and does not compare the request text: a replay of `input`
211
+ does both.
212
+
213
+ ## Reply visibility
214
+
215
+ A Bot reply is visible iff its Turn's intent concluded `succeeded` with that
216
+ reply's task id (#1762). The SDK accepts the reply while the Turn still runs, so
217
+ an accepted reply is not yet a Turn that happened: the Turn can still fail, for
218
+ example when the daemon stops before its outcome commits.
219
+
220
+ - K8's channel outbox follows this itself. An accepted reply's delivery is
221
+ `staged`, and no sender takes it. The outcome transaction that concludes the
222
+ intent `succeeded` promotes it to `pending`. A staged delivery whose intent
223
+ concludes otherwise becomes `rejected` with code `outcome_not_applied` at the
224
+ next sync, and its reply stays only as an audit fact.
225
+ - `replies` records every accepted reply, including withheld ones. A Host that
226
+ shows or uploads replies from `replies` checks the conclusion first: skip a
227
+ reply unless `core.intent(turnId)` has `conclusion === 'succeeded'` and
228
+ `taskId` equal to the reply's task id. For example, AiphaBee adds this check
229
+ to its `k8RootUploads` before it returns a body. A failed Turn then shows its
230
+ failure, never its reply.
231
+ - The conclusion check covers replies that K8 accepted while the Turn was
232
+ running. K4 `consumeMessage` has no conclusion check, so a message that
233
+ arrives after its intent concluded is still accepted and recorded in
234
+ `replies`, and the check passes it when the intent concluded `succeeded`.
235
+ K8 stages any delivery it queues for that message, and the next sync
236
+ withholds it as `outcome_not_applied`. The SDK daemon is not expected to
237
+ publish such a message, but a Host with a channel takes K8's delivery state
238
+ as the authority: it shows a reply only when its delivery was promoted, not
239
+ `staged` and not rejected `outcome_not_applied`. A Host without a channel has
240
+ only the conclusion check.
241
+ - A Turn that outlives its reply route token cannot answer on that route. If
242
+ the token has expired at acceptance, K8 queues the reply on the conversation's
243
+ active push route, or records `reply_route_expired` and queues nothing. If it
244
+ expires after acceptance, the promoted delivery is rejected
245
+ `reply_route_expired`, and an active push route gets a new delivery with its
246
+ own id.
247
+ - A send is at-least-once from the durable outbox. The receiver deduplicates by
248
+ the delivery id, which stays the same across resends of one row; a Host
249
+ upload deduplicates by task id, and only the task that concluded the intent
250
+ can pass the check above.
251
+
252
+ ## Would-do rows
253
+
254
+ Each would-do row names the Turn whose outcome proposed it, in `turnId`
255
+ (#1756). Retention moves the row with that Turn's root into the `wouldDo`
256
+ application rows, so `wouldDoRecords` lists only the rows of roots that are
257
+ still in the state. A Host that keeps the would-do feed longer copies the rows
258
+ before it acknowledges the root.
259
+
260
+ A ledger written by an earlier version has rows without `turnId`. Run
261
+ `migrateWouldDo(ledger)` from `./host-kit` once per ledger, before the new version
262
+ serves. It fills `turnId` from the K4 task id of each live Turn intent, over
263
+ every generation, and moves each row whose intent K4 already compacted, or
264
+ whose Turn left the state, to the `wouldDo` application rows. It returns
265
+ `{ backfilled, archived }`. `archived` counts rows that leave the feed early;
266
+ they are history of settled Turns, so no Turn reads them. A second run returns
267
+ zeros. A switch export or import refuses a would-do row without `turnId`, so
268
+ migrate the source before a switch. For example, AiphaBee runs it on each
269
+ device ledger in its runtime update.
270
+
271
+ ## Actions and context
272
+
273
+ The Host applies management actions, Main Bot delegation cancels, routine
274
+ actions, confirmation cards, questions, then delegations. Each turn freezes
275
+ the ordinary Bot schema and its ContextPack
276
+ when its K4 intent is enqueued. Waiting turns and retries reuse that frozen
277
+ input. The wait limit is five minutes before execution starts. For a routine
278
+ Turn, it counts from the occurrence record. A started
279
+ execution waits for canonical device terminal evidence.
280
+ The schema offers delegation, `ask_user`, `confirmable_action`, and the
281
+ three routine actions. It offers all current routine ids, up to eight.
282
+ It never offers a `target` field. A user input starts one
283
+ root budget. Self delegation permits four continuations for that root. A
284
+ continuation keeps the hop, authority, and open delegation of its parent.
285
+ It does not consume the Bot budget. A refused action
286
+ enters only its originating Bot's `ContextPack.rejectedActions`. Other accepted actions still apply.
287
+ A Bot in `observe` records `create_routine`, a cross-Bot `delegate` and
288
+ `room_call` instead of applying them; every other action applies as above
289
+ ([Bot autonomy](#bot-autonomy-observe-and-auto-1229)).
290
+
291
+ `BotOptions.outcome` narrows that offer (#881). `actions.turn` lists the
292
+ actions of a Bot Turn outside a room, from `delegate`, `ask_user`,
293
+ `confirmable_action` and the three routine actions. `actions.main` lists the
294
+ extra actions of an owner Main Bot Turn, from the Bot and room management
295
+ actions, `team_note` and `cancel_delegation`. A list only removes actions, and
296
+ an empty list removes all of that kind. `timeZones` holds 1 to 8 IANA zones for
297
+ `create_routine` and `update_routine`, checked by the `@byok-sdk/protocol` routine
298
+ calendar. The default is `UTC` and `America/New_York`. `confirmable` holds 1 to
299
+ 16 `confirmable_action` branches, each an action name and its draft schema. The
300
+ default is `send_message`, and the connector receives only the offered names.
301
+ Sixteen branches with the `send_message` draft and 64-byte names fit both
302
+ bounds with eight long time zones at the eight-routine limit, with room for
303
+ heavier drafts (`CONFIRMABLE_MAX`).
304
+ The constructor checks the offer and composes one schema with it. Turns that
305
+ froze before keep their schema. A room seat always gets `speech`. A schema
306
+ that is over budget blocks its Turn. The H
307
+ sync takes the same offer as `SyncOptions.offer`, a value from `outcomeOffer`.
308
+ An offer with `actions.turn` also narrows the system
309
+ prompt of a Bot Turn: it keeps only the sentences for every Bot Turn and for the
310
+ actions in that Turn's frozen schema (`systemPrompt`, `promptActions`). With only
311
+ `delegate`, the prompt names no `ask_user`, `confirmable_action` or routine.
312
+ A narrowed prompt never names `speech` or `room_call`, which only a room seat
313
+ gets. An offer without `actions.turn` keeps
314
+ `SYSTEM_PROMPT`. A narrowed prompt is shorter, so the
315
+ `minimumInstructionBytes(SYSTEM_PROMPT)` check still bounds it.
316
+
317
+ Questions support text and single choice. An answer creates an `answer` turn.
318
+ It is a new user input with its own stable budget root. Replaying the same
319
+ answer does not reset that budget. The rules that read only the outcome are
320
+ `bot-turn-outcome.v1` contract rules (#1374, #1375): blank model text after
321
+ `trim()`, a repeated option id, delegate target, `create_bot` localId,
322
+ cancel id, room member or weekday, a `create_room` admin outside its members,
323
+ an update that changes nothing, and an invalid schedule. The device refuses
324
+ such an outcome on `submit_result`, and the Host refuses it whole.
325
+ An expired card can appear in the recent ContextPack window. It creates no model turn.
326
+ A confirmation card starts as `pending`. The owner can choose `confirmed` or
327
+ `rejected`. A card becomes `expired` after 24 hours. Only a committed
328
+ `confirmed` card calls the Host connector. Confirmation results and explicit
329
+ rejection return as an `action_result` turn. Passive expiry creates no turn.
330
+ Connector success, error, and external id enter that turn.
331
+ Late and conflicting decisions return an error. Replaying the same completed
332
+ decision is idempotent. Decision projections are committed once, so uploading
333
+ them does not cause later syncs to publish them again.
334
+
335
+ The connector receives an AbortSignal and must deduplicate by the card id.
336
+ The Host enforces `connectorTimeoutMs` (default 30 seconds), even if the
337
+ connector ignores cancellation. A timeout releases the serial chain and
338
+ commits a failed action_result with an unknown external outcome. A late connector
339
+ result cannot overwrite that committed result. The Host calls the connector at
340
+ most once per card (#958): one transaction claims the call before it runs, and
341
+ the transaction that commits its result or error drops the claim. A claim found
342
+ with no result at a later pass (a crash after the call, or a failed result
343
+ commit) ends the card the same way as a timeout, with no second call. No
344
+ exactly-once external effect is claimed.
345
+
346
+ The system rules are in `src/rules/schema.ts`. K4 carries them in the instruction.
347
+ They require an acknowledgement and self delegation for long work. Final text
348
+ uses messageEgress. Progress uses messageDraft or typed activity. A failed,
349
+ cancelled, or missing-outcome continuation has a failed owner projection.
350
+ The Host publishes final turns with `owner`, source, status, and conclusion.
351
+ It does not turn an outcome document into a second chat message. K8 stores no
352
+ reply text that the user saw. In history mode the external authority gives it
353
+ as a row's `reply` (see External history authority).
354
+
355
+ `src/rules/` holds the collaboration rules as pure functions (#606, #739 D1):
356
+ room seats, input coalescing, Turns, delegation, the result schema, the
357
+ ContextPack and the order of outcome actions. They take rows and K4 intent
358
+ facts, do no I/O and import no ledger type. The ContextPack functions take the
359
+ Bot's history as an argument. This example reads that history from the device
360
+ ledger. The other `src/` files are the K8 adapter around these rules.
361
+
362
+ From K4, the rules import only `hash` and `canonical`, from the
363
+ `@byok-sdk/server/execution-core/canonical` entry (#884). That entry
364
+ imports only `node:crypto`. The K4 root entry also loads `node:sqlite` and
365
+ `node:async_hooks`, so the rules never import it. `src/rules-boundary.test.ts`
366
+ holds both rules. The rules still need `node:crypto` and the global `Buffer`.
367
+ Workers with `nodejs_compat` have both.
368
+
369
+ ## Bot autonomy: observe and auto (#1229)
370
+
371
+ A Bot's autonomous actions start in `observe`. The owner sees what the
372
+ Bot would do, then switches the Bot to `auto` per Bot. This is the
373
+ owner ruling of 2026-10-31 on #1229. It is Host policy over the same
374
+ frozen schema. K4, K8-S, the SDK wire and the protocol do not change.
375
+
376
+ | Action | observe | auto |
377
+ | --- | --- | --- |
378
+ | `create_routine` | Recorded as would-do. No K4 routine, occurrence or wake. | Applied. |
379
+ | `delegate` to another Bot | Recorded as would-do. No delegation row, `bot_request` Turn or budget unit. | Applied. |
380
+ | `room_call` of a seat | Recorded as would-do. No new round or seat. The seat's speech still applies. | Applied. |
381
+ | Self `delegate` (continuation) | Applied, as in auto. | Applied. |
382
+ | `messageEgress`, `confirmable_action`, `ask_user` | Applied, as in auto. | Applied. |
383
+
384
+ An outcome is still checked against its frozen schema in observe, and a
385
+ would-do row is keyed by `hash([taskId, 'would-do', action, index])`. So
386
+ applying the same outcome twice records one row. The row holds the frozen
387
+ action itself, never a model summary. Rows live in
388
+ `snapshot().wouldDo` and are published once as `would-do:<id>`, so a
389
+ Host UI reads either the ledger or that projection. They are Host UI
390
+ history: never in a ContextPack and never on the wire. Each row names its
391
+ Turn in `turnId`, and retention moves it with that Turn's root (#1756), so
392
+ `wouldDoRecords` lists only the rows of roots still in the state.
393
+
394
+ The default of a new Bot is `observe`. A Bot profile without the field
395
+ (an older ledger) reads as `observe` too. Only the owner principal
396
+ switches it:
397
+
398
+ ```ts
399
+ // The Host UI: the would-do feed and one switch per Bot.
400
+ const records = bot.wouldDoRecords(reviewerId); // oldest first; omit the id for every Bot
401
+ const current = bot.autonomy(reviewerId); // 'observe' | 'auto'
402
+ await bot.setBotAutonomy(reviewerId, 'auto', principal); // owner only
403
+ ```
404
+
405
+ `setBotAutonomy` writes `bot-autonomy:<botId>:<revision>` for the Host
406
+ UI. It applies to outcomes recorded after the switch. It does not replay
407
+ a would-do row. A non-owner fails with `not_owner`; an unverified caller
408
+ fails with `unverified_sender`. Both write an audit row first. The team
409
+ authority's profile does not own this field, so a team snapshot cannot
410
+ change it.
411
+
412
+ Coalesced input is a policy before enqueue: see
413
+ [User input priority](#user-input-priority-1229) for how it interacts
414
+ with queued autonomous work.
415
+
416
+ ## Routine invariants
417
+
418
+ Bot routines are K4 routines. Each one is a `hostOccurrence` definition with
419
+ the `bot-routine` hook. The K4 ledger stores the definition, the pending
420
+ version, the reserved slot, the occurrences and the wake outbox. K8 keeps no
421
+ routine state. The Host core uses `nextRoutineOccurrence` as its calendar: a
422
+ routine rule is a `RoutineSchedule` whose `tz` is the definition time zone.
423
+ K4, K8-S and the SDK all use the 368-day wake horizon.
424
+
425
+ K8 keeps the Bot policy. A Bot creates routines only for itself. Each owner
426
+ has at most eight routines that are not completed. The routine id is
427
+ `hash([taskId, 'create_routine', index])`. The hook input holds `owner`,
428
+ `authority` and `prompt`, and a new version keeps the owner and the authority.
429
+ An update must change the schedule or the prompt, and a schedule repeats no
430
+ weekday. The contract checks an outcome's routine actions; the owner
431
+ `updateRoutine` and the sealed create and reseal check the same at their entry.
432
+ The routine actions run as K4 routine commands in the outcome
433
+ commit. A refused action changes no routine.
434
+
435
+ The hook writes the routine Turn in the occurrence commit. The Turn id is the
436
+ K4 intent key `occurrence:<occurrence key>`. The next sync promotes the Turn
437
+ with `promoteOccurrence` and its frozen schema and ContextPack. Its wait limit
438
+ is five minutes from the occurrence record, not from the promotion. A routine
439
+ Turn that ends before promotion, for example on cancel or for an archived
440
+ owner, concludes its occurrence as `cancelled`. Redelivery reads the stored
441
+ occurrence and does not call the hook again.
442
+
443
+ K4 keeps a running occurrence and only the latest queued one. A new slot
444
+ settles an older queued routine Turn as `superseded`. On update, the new
445
+ version stays `pending` while an occurrence is unsettled or an old slot is
446
+ due. The old chain gets no new slot, and the version switches when that work
447
+ settles. K4 stores only the current and the pending definition; the Host
448
+ service keeps the version history. Pause cancels the reserved slot. Resume
449
+ keeps the current version while work is unsettled. Cancel marks the routine
450
+ completed and stops new occurrences. Accepted work finishes with its old
451
+ version. To stop an execution too, use K4 cancellation explicitly. Routine
452
+ results are owner turns with source `routine`.
453
+
454
+ `updateRoutine` and `setRoutineLifecycle` change only the routines of this
455
+ Host's Bot. `endRoutine(id)` runs the keyless `end_routine` command (§55c): the
456
+ Main Bot completes any open Bot routine, an archived owner's too, as cancel
457
+ does. Without it, the routine of an archived Bot would fire at every slot. The
458
+ command needs the Main Bot role and gets the K4 rows through the
459
+ `CommandPorts.routines` port.
460
+
461
+ ### Sealed Bot routines
462
+
463
+ A sealed Bot routine (#953, #654 E3d-4) is a `bot-routine` whose Turn
464
+ instruction only a member and the device can read. The owner's member endpoint
465
+ seals the whole instruction once per routine version with K4
466
+ `sealRoutineTemplate`. The instruction is `sealedRoutineInstruction(prompt)`:
467
+ the K8 Turn frame with every action, `Request:` and the prompt, and no
468
+ ContextPack, because v1 has no plaintext field for Host content next to a
469
+ sealed instruction. The Turn's frozen outcome schema stays the authority on
470
+ which actions the Bot may take.
471
+
472
+ - `sealedDefinition` makes version 1. The member picks the routine id, a fresh
473
+ UUID, because the template binds it, and an id that any routine row already
474
+ has is refused. `resealDefinition` stages the next version of a sealed
475
+ routine only. A template sealed for another version throws
476
+ `SealedRoutineVersionError`, and nothing is written. Both check that
477
+ `sealing.categories` is exactly `['task-input']`, that the template is
478
+ sealed for the Bot's current Agent revision, and that the occurrence offer
479
+ parses. A sealed routine counts toward the limit of eight.
480
+ - The authority is `owner`, and a routine stays sealed. `update_routine`, from
481
+ a Bot or the owner, is refused on a sealed routine, and the outcome schema
482
+ offers no sealed id for it. Cancel and `end_routine` complete it as any
483
+ routine.
484
+ - The view in each ContextPack shows `sealed: true` and nothing of the
485
+ template.
486
+ - The hook writes the occurrence Turn with an empty `request` and
487
+ `sealedRoutine: { routineId, definitionVersion }`. The sync freezes it from
488
+ the Host's `sealedTemplate` lookup: the Bot's execution template with
489
+ `sealing`, the template byte for byte as `sealed`, and `routineRef`, with no
490
+ `instruction`, no history and the plaintext `bot-turn-outcome.v1` contract.
491
+ K4 then promotes it as a sealed occurrence intent.
492
+ - A Turn whose template is missing (`sealed_routine_template_missing`), or
493
+ whose Bot Agent revision differs from the one the template is sealed for
494
+ (`sealed_routine_agent_changed`), ends `failed` with the projection
495
+ `sealed-routine-failed:<turnId>`. It never blocks: a blocked routine Turn
496
+ keeps its occurrence open, and that stops the version switch a reseal needs.
497
+ An outcome schema over budget depends on the state, not on the version, so
498
+ it blocks a sealed Turn as a plain one until the state shrinks.
499
+ - The outcome and every projection stay plaintext, even when they carry
500
+ content derived from the sealed instruction.
501
+
502
+ L has no sealed dispatch. Its embedded server declares no `e2ee.member`, so
503
+ no daemon paired to it advertises `sealed-payload-v1`, and its K4 port has no
504
+ `submitSealed`: L has no command that creates a sealed routine, and a sealed
505
+ intent would fail with `sealed_dispatch_unavailable` before any submit. H
506
+ runs sealed routines on a cloud tenant.
507
+
508
+ `compact` removes settled routine rows: a promoted
509
+ occurrence through its intent key, and a concluded occurrence through its
510
+ occurrence key. `botRoutines` reads the Bot routine views from the K4 rows.
511
+ Other K4 routines of the Host, for example Host jobs from `BotOptions.hostJobs`,
512
+ are not Bot routines. A Host job may return only a summary: L sets K4
513
+ `hostJobExecution: 'fail'`, so a result with `execution` concludes its
514
+ occurrence `failed` and promotes nothing, as H does, because no K8 Turn could
515
+ settle that intent. K4 alone promotes it by default.
516
+
517
+ K8 owns only Turn intents, Host intents (#882) and dream intents (#1475), so L
518
+ also sets K4 `executionRoutines: 'refuse'`; H refuses them too (#954). An
519
+ `execution` routine is refused at creation, from `bot.core.addRoutine`,
520
+ `bot.core.updateRoutine` or a Host intent handler's `tx.routines`, and no routine
521
+ row is written. The constructor refuses a ledger that still holds one that is
522
+ not completed. Only K8's own hooks promote an occurrence: the routine Turn and
523
+ `bot-dream`. Host code that needs Agent work for an occurrence calls
524
+ `enqueueHostIntent` itself, outside a Host job handler, with its own key.
525
+ `enqueueHostIntent` refuses `occurrence:<key>`.
526
+
527
+ ### Dreaming (#1475)
528
+
529
+ Each unarchived Bot with a usable model template has a dream routine: a daily
530
+ task that checks and tidies its memory against the Host's history, built with
531
+ `buildDreamInstruction`. Dreaming is on by default.
532
+
533
+ **Cost.** The default is one run per Bot per day that had a new completed Turn,
534
+ on the Bot's own model. Set `dreaming.models` to cheap templates, or pass
535
+ `dreaming: false` to turn it off for the whole Host.
536
+
537
+ ```ts
538
+ new BotCollaboration(server, ledger, { ...options,
539
+ dreaming: { timeZone: 'Asia/Hong_Kong', models: ['cheap', 'fast'], maxDurationMs: 900_000 } });
540
+ ```
541
+
542
+ - **Lifecycle.** Every sync adds the routine of a new Bot, ends the routine of an
543
+ archived Bot, and with `dreaming: false` ends them all. `recover()` is a sync,
544
+ so it does both. A routine whose template goes away later stays and records
545
+ `model_unavailable`. `dreaming: false` ends routines for good, so turning it
546
+ back on creates a new routine id with the same record. Default-on needs
547
+ `wake.consume` routed to `bot.consume` even with no Bot routines, and a Host clock
548
+ outside the years 2000 to 2200 throws in sync unless `dreaming: false`.
549
+ - **Time.** 03:00 daily, in `dreaming.timeZone`. Without it, the routine takes this
550
+ process's local zone when it is created and stores it in its definition, so a
551
+ later restart in another zone does not move it. A Host on a server should set
552
+ `dreaming.timeZone`: server clocks are usually UTC, and 03:00 UTC may be the
553
+ middle of the user's day.
554
+ - **Model.** A dream always runs on the Bot's own device, because its memory home
555
+ is there. It takes the first name in `dreaming.models` that exists in the current
556
+ `models` and is on that device. Otherwise it falls back to the Bot's own template,
557
+ with or without a list. Only the list decides what is cheap: K8 infers nothing
558
+ from a runtime name.
559
+ - **Task.** A fresh writer with `agentMemory: 'none'` and no `agentMemoryCommit`, on
560
+ every platform, and `terminalProjection: { mode: 'none' }`. The offer always sets
561
+ `agentMemory: 'none'`: with it unset, a daemon could attach the memory MCP, and a
562
+ `MEMORY.md` over its limit would then fail the dream before it starts, though the
563
+ dream is what repairs it. There is no rollback, so the instruction orders every
564
+ step to leave usable memory. It carries no message egress and no toolsets, and
565
+ drops the template's `homeAccess`, `preparation` and `agentMemoryCommit`.
566
+ - **Memory paths.** The task is not `homeAccess`, so its cwd is the Bot's home. In
567
+ `none` mode the device injects no `MEMORY.md` and no memory guidance.
568
+ `MEMORY.md` and `notes/` in the instruction resolve from the cwd, and the runtime
569
+ uses its own file tools.
570
+ - **Input.** The Bot's completed Turns after the last successful dream's mark, up
571
+ to the first Turn that is still queued or processing, so a Turn that user input
572
+ overtook is covered by a later dream. A blocked Turn does not stop the run; if it
573
+ later completes, no dream covers it. With `BotOptions.history`, K8 reads the rows
574
+ there with `turnId` set to the dream's intent key. The mark advances only through
575
+ the settled rows that history returned. A failed read skips that day; no completed
576
+ row read after the mark skips it with `no_new_turns`, leaving the mark unchanged,
577
+ just as in K8-state mode. A Bot whose history authority never returns completed
578
+ rows never dreams. The pack fills what `instructionMaxBytes` leaves after the fixed text.
579
+ The first dream window starts when dreaming was set up for the Bot; older Turns
580
+ of an upgraded ledger still go into its pack.
581
+ - **Native sessions.** `dreaming.nativeSessions` defaults to `true` and requests
582
+ native session input for the same window when the device advertises support.
583
+ Set it to `false` to omit the request. The device switch is off by default;
584
+ see [Native session input](../../docs/security.md#native-session-input) for
585
+ what it sends to the configured model provider.
586
+ - **Queue.** A dream joins the Bot's FIFO behind the Turns of its sync, and user
587
+ input goes ahead of a dream that has not started (#1229). A running dream is not
588
+ interrupted, so user input waits for it, at most `maxDurationMs` (default 15
589
+ minutes). A queued dream waits at most an hour, and a newer slot supersedes it.
590
+ - **Record.** `snapshot().dreams.bots[botId]` holds `since`, `throughTurn` and `last`:
591
+ the occurrence's outcome, its reason, the template and whether it was a fallback.
592
+ A dream that does not succeed leaves `since` and `throughTurn`, so the next one
593
+ covers the same Turns. A skip concludes its occurrence `cancelled`, with one of
594
+ `no_new_turns`, `model_unavailable`, `history_unavailable`, `bot_not_ready`,
595
+ `bot_archived`, `bot_suspended`, `device_unavailable`, `dreaming_off` or
596
+ `superseded` (concluded `superseded`).
597
+ - **Owner.** `dreams.open` owns each dream intent, so its terminal never reaches a
598
+ Host intent handler. `cancelHostIntent` and `failStuckIntent` refuse it.
599
+ - **On H.** H does not run dreams yet. An owner switch moves the routines and the
600
+ record, and H concludes each `bot-dream` occurrence `cancelled` with no task,
601
+ recording `H does not support dreaming yet`. A dream queued or running at export
602
+ blocks it like other open work, until it settles.
603
+
604
+ ### Compaction
605
+
606
+ A Turn id is its K4 intent key. K8 reads the intent of a Turn after K4 settles
607
+ it: the next pass copies the conclusion into the Turn, and delegation, room and
608
+ reply checks read it later. So `botCompactVeto` refuses an acknowledged key
609
+ while one of these holds:
610
+
611
+ - its Turn is not concluded, or the Turn still has its K4 intent and its
612
+ conclusion is not reported;
613
+ - a delegation without a verdict has the Turn in `chainTurnIds` or as
614
+ `cancel.targetTurnId`, or any delegation has it as `lateTurnId`;
615
+ - its room seat is not released;
616
+ - one of its reply receipts is not settled: K4 does not hold the receipt for
617
+ message replay, or a delegated reply body has no verdict yet;
618
+ - it is the intent of a dream that the sync has not closed (`dreams.open`), so
619
+ the dream's result is not in K8 yet.
620
+
621
+ K4 runs the veto inside `compact`'s own transaction. A refusal throws
622
+ `CompactVetoError` and changes nothing. Retry the key after a later pass.
623
+ Any other key without a Turn, for example a Host job, is not a K8 key.
624
+
625
+ The veto guards each `HostLedger` instance that has it. Another instance on
626
+ the same file without the veto can still compact a Turn intent early. Then the
627
+ next pass fails that Turn with conclusion `failed`, because K8 did not see the
628
+ K4 result. It writes an audit line and reports the Turn once, with
629
+ `reason: 'result_retired'`. The Turn fails even when K4 already applied its
630
+ outcome, because K8 does not read the K4 application tombstone. A routine
631
+ Turn's intent tombstone expires with its slot. K4 removes the occurrence with
632
+ the intent, so the pass also fails a routine Turn whose occurrence is gone,
633
+ after its tombstone expired. The check runs before the archived Bot check, so a
634
+ retired Turn of an archived Bot also fails with `result_retired`. The archived
635
+ Bot check cancels only a Turn that has no conclusion. A retired room seat Turn
636
+ also releases its seat as `failed`, with reason `result_retired`, so its round
637
+ moves on. At Host start, a business reply receipt of a compacted Turn stays,
638
+ also for a routine Turn after its tombstone expired. A due reply check of a compacted chain intent takes
639
+ the failed readback path. The Host keeps processing other work.
640
+
641
+ ### Retention
642
+
643
+ Every transaction reads and rewrites the collaboration state, so settled
644
+ history must leave it. `bot.retain({ acknowledgedRoots, now, retentionMs })`
645
+ does that on the Host's explicit acknowledgement. It never runs on its own.
646
+
647
+ - A root is the `root` field of a Turn projection, the round root that
648
+ `roomInput` and a room `receive` return, or the `root` field of a
649
+ `room-seat:` or `room-root:` projection. One root holds its Turns,
650
+ budget, delegations and their batches and units, replies, schemas, cards,
651
+ questions, the rejections that its Turns consumed, its input batch and
652
+ inputs, its rounds with their seats, seat Turns and `team.roots` row, its
653
+ inbounds, and the deliveries that its Turns queued (each delivery stores
654
+ its `turnId`). A seat Turn belongs to its round's root, but
655
+ its projection shows its seat id as `root`. Acknowledging a seat id throws
656
+ `RetentionRefused` with code `seat_root` and the round's root in
657
+ `roundRoot`. Acknowledge that root instead.
658
+ - One ledger transaction moves every row of each acknowledged root into K4
659
+ application rows by map name and id (the K4 row port). It retires the
660
+ root's Turn, input and round ids for good.
661
+ - `RetentionRefused` with code `protected_root` rolls back the whole call while a
662
+ root is still in use: a Turn that is not concluded, or that still has its
663
+ K4 intent and is not reported; an unresolved delegation, an unreleased
664
+ batch or a reserved unit; an open card or question; an open input batch; an
665
+ open round or seat; an open delivery or a live reply route; an open routine
666
+ occurrence; or a Turn, card or question in the ContextPack window of its
667
+ Bot (the Turns from the oldest turn of its handoff pack to its newest, and
668
+ the last 12 cards and questions, bounded by `contextTurnLimit`).
669
+ Unconsumed rejections stay in the state.
670
+ - An unknown root throws. A root that is already archived counts as
671
+ `alreadyArchivedRoots`.
672
+ - Each call also moves the command records of archived roots and the records
673
+ with no root. They answer replays for at least `retentionMs`, which must be
674
+ seven days or more; a later call removes them after that. A retry after the
675
+ window decides again, and an archived Turn, input or round id makes the
676
+ commit throw `RetiredIdentityError` and change nothing. A store makes that
677
+ check itself: `commitCommand` hands the ids that `decide` added to
678
+ `CommandStore.admitted`, and the store calls `refuseRetired` before it
679
+ commits. Sync fails a Turn with a retired id instead of running it. A Turn
680
+ id and an input id are one identity space (`retiredIdentity`): an input
681
+ that does not coalesce becomes a Turn with its own id, and the coalescing
682
+ policy can change between retention and a retry.
683
+ - The handoff pack of the window leaves out the Bot's Turns that can still
684
+ freeze (queued or blocked), and its total is at least `recentBytes +
685
+ earlyBytes` plus the pack frame, so `earlier` always gets all of `earlyBytes`.
686
+ A freeze has no more than that, a Cross-Bot Turn often less, and the Turns it
687
+ adds only start `earlier` at a newer turn, so no freeze reads a turn older
688
+ than the window. `Host.retain` uses the `handoff` budgets of a freeze, and
689
+ `RetentionLimits.handoff` is required, so a store that calls `retainRoots`
690
+ passes the budgets it freezes with. Room messages and rejections still go by
691
+ `contextTurnLimit`.
692
+ - Each call moves the audit lines, revoked push routes that no delivery uses,
693
+ and settled persona deliveries: applied ones except the newest of each Bot,
694
+ and failures of an older profile revision. These archived rows stay.
695
+ - `historyWindow.omitted*` counts only rows still in the state.
696
+ - Each call moves the room messages of archived roots to application rows in
697
+ namespace `roomMessages`, by message id, with or without `roomHistory`. The
698
+ last `contextTurnLimit` messages of each room stay, because a seat
699
+ ContextPack reads at most that many. A message of a root that is still in
700
+ the state stays too. The same call recomputes `visibleFrom`: it is an offset
701
+ in the kept list, so each member sees the same kept messages as before. The
702
+ state, and so a snapshot, no longer holds the whole room history.
703
+ `historyWindow.omittedMessages` and `notice` of a seat ContextPack count only
704
+ messages still in the state, as `history.omittedTurns` does; a count over moved
705
+ messages would need a stored count for each Bot.
706
+
707
+ After retention, a late message for an archived Turn gets `binding_mismatch`,
708
+ and an echo can no longer match an archived delivery. Back up the whole SQLite
709
+ database: a JSON-only restore loses the archived rows and tombstones.
710
+
711
+ `CollaborationState.version` is 3. Version 1 kept the routines in K8 state.
712
+ The Host refuses a version 1 ledger and changes nothing. Restore a ledger
713
+ backup made before this change, or start a new ledger.
714
+
715
+ The Host drains application commands until all new turns have a K4 intent.
716
+ An immediate terminal cannot leave a continuation without a wake.
717
+ K4 schedules and cancels routine wakes through its outbox. A resume of the
718
+ same key replaces a pending cancel with the schedule, so the SDK holds one
719
+ wake. A failed SDK wake call rejects the K4 drain, and the Host call that
720
+ started it rejects after its commit. The K4 outbox keeps the row with
721
+ `lastError`. The K4 retry timer retries it with backoff from 1 s to 60 s, for
722
+ at most about 5 min, and each later drain, wake delivery or `recover()` also
723
+ retries it. A failed K4 drain does
724
+ not stop the rest of its process pass, and the pass arms the timer, so card
725
+ expiry, delivery retries, reply checks, seat deadlines and input batch seals
726
+ keep their times. The pass then rethrows the drain error. Startup schedules a reserved wake that the SDK
727
+ no longer holds. K4 rejects a wake whose time differs from its reservation,
728
+ and the SDK delivers it again. K4 records an unknown, inactive or superseded
729
+ wake in `ignoredWakes`. Calendar errors stop the chain, record an audit, and
730
+ let the accepted occurrence finish. Pause and resume retry the calendar.
731
+
732
+ ## Boundaries
733
+
734
+ The collaboration state has version 3. The Host rejects version 2, unsupported
735
+ and unversioned stored state. It does not reset or migrate that state. A
736
+ version 2 ledger cannot hold archived rows, so restore a ledger backup made
737
+ before this change, or start a new ledger.
738
+
739
+ This example has one team and one owner per ledger. Paid Pi success-rate
740
+ measurement belongs to [WO-10b](../../docs/submit-result-measurement.md); the method defines per-runtime/model/platform cells and does not supply live data. Retention of the
741
+ collaboration history is explicit ([Retention](#retention)). K4 routine
742
+ versions have no retention policy in this small example.
743
+
744
+ ## Commit contract
745
+
746
+ Each collaboration command goes through one commit (#739 D1,
747
+ `src/rules/commit.ts`). A commit takes a scope, a command id, an optional
748
+ expected revision and the command. It returns the new revision, the
749
+ disposition and the outbox rows that it wrote. One store transaction holds
750
+ the state change, the command record and the outbox rows.
751
+
752
+ - A replay of a command id with the same evidence returns the first result
753
+ and changes nothing. The evidence is the hash of the fields that decide the
754
+ command's effect.
755
+ - The same command id with other evidence is an `identity_conflict`. The Host
756
+ keeps the existing error text, for example `Input identity conflict`.
757
+ - Without an expected revision, the commit decides on the head. An explicit
758
+ revision that is not the head is a `stale_revision` conflict. A replay is
759
+ checked first, so a retry with its original revision gets its first result.
760
+ - The revision counts committed commands only (#739 6b). Each new commit adds
761
+ 1, also for a refused disposition. A command that throws commits nothing.
762
+ Host passes that only apply evidence (sync, reconcile, reply checks,
763
+ deliveries, device refresh) do not change the revision.
764
+ - A keyless command has no record (#739 6a). Each call applies and adds 1 to
765
+ the revision, so its command id is not a dedup key. Only an explicit expected
766
+ revision protects a retry: the first commit moved the head, so the retry is a
767
+ `stale_revision` conflict.
768
+
769
+ The keyed commands are owner input, received IM input, room input, answers,
770
+ card decisions, team snapshots, and three K4 callbacks: a terminal outcome, an Agent message
771
+ and a Bot routine occurrence. The keyless commands are `setMainBot`,
772
+ `updateRoom`, `retryPersona`, `personaReady`, `enablePushRoute`, `revokePushRoute`,
773
+ `resendDelivery`, `cancelDelegation`, `abandonDelegation`, `cancelTurn` and `endRoutine`.
774
+ A `cancelTurn` or `cancelDelegation` that answers `cancel_pending` or
775
+ `already_settled` commits nothing ([idempotent owner cancels](#idempotent-owner-cancels-1405)).
776
+ `src/rules/commands.ts` decides all of them. The Host checks the principal
777
+ and the channel before the commit, and it calls K4 cancel and delivers cancel
778
+ facts after the commit. `updateRoutine` and `setRoutineLifecycle` are K4
779
+ commands on K4 rows and do not commit here; `endRoutine` commits `end_routine`,
780
+ whose port runs K4 `setLifecycle`.
781
+
782
+ In this L example the scope is the ledger tenant. Owner APIs pass no expected
783
+ revision. K4 already deduplicates terminals (`applied`) and accepted messages (the
784
+ message receipt), so L stores no record for those callbacks. K4 writes no
785
+ receipt for a refused message, so L keeps a record for it: a retry gets the
786
+ same refusal and does not change the revision. When retention moves that
787
+ record, the message hook reads it from the K4 rows of its own transaction. Other content for the same
788
+ message id is refused with `message_conflict`. The D1 vectors in
789
+ `src/commit-vectors.test-support.ts` run against a pure in-memory store and
790
+ against the L ledger; the D2 H adapter runs the same vectors.
791
+
792
+ ### Sync step
793
+
794
+ A sync step freezes the offer of a Turn without an intent, and settles the
795
+ Turn of a concluded intent (#793 D2b). `syncTurn` in `src/rules/sync.ts`
796
+ decides it for one Turn. `src/rules/commands.ts` exports it with the
797
+ commands. The rule changes the state, publishes projections and returns the
798
+ write for the store:
799
+
800
+ - `freeze`: store this intent input (`key`, `source`, `waitUntil`,
801
+ `execution`). The rule sets `waitUntil` to `now` plus 5 minutes.
802
+ - `routine`: a routine Turn joins the FIFO as its occurrence intent.
803
+ - `cancel`: the Bot is archived. Cancel the intent, which has not started.
804
+ - `ended`: the Turn has no intent and is concluded. A routine Turn concludes
805
+ its open occurrence.
806
+
807
+ A Host that binds devices gives the step the optional fact
808
+ `deviceRefusal(botId)` (#956, §55a): `unbound`, `revoked`, `mode` or
809
+ `switching` for the device of the Bot's current execution template, which a
810
+ freeze would use. The step then holds that Bot's Turns that have no intent: it
811
+ returns no write, sets `held` on the Turn, publishes the hold once, and adds an
812
+ audit row with the reason. `unbound`, `revoked` and `mode` hold with
813
+ `device_not_bound` and publish `held:<turnId>`; `switching` (#957) holds with
814
+ `device_switching` and publishes `held-switching:<turnId>`. Each body is
815
+ `{ owner, turnId, code }`. The rest of the scope syncs. The hold comes before
816
+ the profile check, since a refused device may never apply a profile. The next
817
+ sync with no refusal (the device is bound, or a `team_snapshot` moved the Bot)
818
+ clears `held` and freezes the Turn with the current template. A held room
819
+ seat Turn waits for its seat deadline, as any seat that does not start. Each
820
+ hold code has its own projection id with one body, so a changed reason never
821
+ conflicts. L sets the fact from its topology records (see "Topology switch").
822
+ `DEVICE_NOT_BOUND` is H's `DeviceBindingError` code.
823
+
824
+ A store runs the step for each stored Turn, in insertion order, in one
825
+ transaction under the same scope lock as a commit. It reads the facts inside
826
+ that transaction. The projections that the step publishes reach the store's
827
+ outbox in the same transaction. A projection with the same id and the same
828
+ body adds nothing. Another body for that id throws `Projection identity
829
+ conflict`. The step is a Host pass that only applies evidence, so it writes
830
+ no command record and keeps the revision. A client's expected revision does
831
+ not go stale because of a sync. If one Turn throws, the store writes nothing.
832
+ L runs the step in its sync transaction through `syncTurnInLedger`
833
+ (`src/commit.ts`), which keeps the K4 writes: `enqueue`, `promoteOccurrence`,
834
+ the intent cancel and the occurrence conclusion. The L sync transaction also
835
+ runs other Host steps before and after the per-Turn steps. Before them, it
836
+ seals due input batches, expires pending cards and advances rooms. After
837
+ them, it settles delegations, reports card decisions and adds their action
838
+ result Turns, cleans reply tokens and projects input batches. The card steps
839
+ are the K8 rule `src/rules/cards.ts` (`expireCards`, `reportCardDecisions`),
840
+ which the `cardVectors` hold for L and H. This contract
841
+ defines only the per-Turn step. The `syncVectors` in
842
+ `src/commit-vectors.test-support.ts` hold these rules for the in-memory store
843
+ and for L. The `coalesceVectors` there hold the batch seal before the
844
+ per-Turn steps and the batch projection after them, for L and H.
845
+
846
+ `collaborationDue(state, timers)` in `src/rules/due.ts` lists the times when a
847
+ sync has collaboration work to do: each open input batch's seal, each pending
848
+ card's expiry, each unreleased seat's deadline, and the delegation times
849
+ (`delegationDue`). `src/rules/commands.ts` exports it. L arms its timer with
850
+ these times and its own L-only ones. H stores their minimum as the scope's due
851
+ time (#793 S4). Routine slots are K4's, so they are not in the list.
852
+
853
+ The room step of a Host sync is `advanceRoomSeats(state, facts, now, add, publish)`
854
+ in `src/rules/rooms.ts` (#793 S6). It runs `advanceRooms` on the seat facts,
855
+ fails a seat Turn whose work was not admitted, queues each new seat Turn
856
+ through `add` (`seatTurn` gives its fields), publishes the room projections
857
+ of the seats that became terminal through `publish`, and returns the seats
858
+ whose admitted work the Host cancels. `src/rules/commands.ts` exports both. L builds
859
+ the facts from its K4 intents; H builds them from its intent rows. A Turn
860
+ step can release a seat (a blocked or retired seat Turn). Both Hosts then run
861
+ the room step and the Turn steps again in the same sync, so the next seat gets
862
+ its Turn: L in `advanceRoomsAndTurns` (`src/rooms.ts`), H in its sync loop.
863
+ The `roomVectors` run on both.
864
+
865
+ `checkReply(state, d, check, now, emit, uncertainAfterMs)` in
866
+ `src/rules/delegation.ts` decides one reply check of a `reply_pending`
867
+ delegation: a reply body that the Host holds answers it, a failed read
868
+ retries with backoff, and otherwise the SDK readback decides.
869
+ `replyCheckDue(d, now)` selects the due checks. `src/rules/commands.ts`
870
+ exports both. L's `flushReplies` runs them with its own SDK read, and H runs
871
+ them in `HostedReplyChecker` (#793 S7). The `replyVectors` hold the decision
872
+ for L and H.
873
+
874
+ Known L limit: K4 stores the whole Host ledger, with the collaboration state,
875
+ in one JSON row per tenant. Turns, replies, audit rows and command records
876
+ make that row grow. Command records are dedup evidence; retention must not
877
+ delete a record while a retry of its command can still arrive. Per-entity L
878
+ storage and K8 retention are #798.
879
+
880
+ ## External history authority
881
+
882
+ With the `history` option, the ContextPack history of a Bot Turn comes from an
883
+ external authority, not from this ledger (#739 D1, #606). Before a Bot Turn
884
+ freezes its offer, the Host reads the Bot's earlier history outside the ledger
885
+ transaction. Then one transaction freezes the offer with those rows. The
886
+ transaction freezes only a Turn that still has no offer.
887
+
888
+ - The authority returns rows in the ContextPack row shape: `id`, `root`,
889
+ `source`, `request`, `hop`, `status`, optional `conclusion`,
890
+ `outcomeSummary`, and optional `reply`, the reply text that the user saw for
891
+ that Turn (#1318). Rows in another shape are refused, as is a `reply` that
892
+ is not a string.
893
+ - `historyRowFromTurn` builds one row from a `bot-turn:<id>` projection value
894
+ and the caller's `reply`, so the authority does not derive `outcomeSummary`
895
+ itself. `contextTurns` checks rows in this shape and returns them as
896
+ `ContextTurn[]`. The K8 entry exports both and the `ContextTurn` type
897
+ (#1356).
898
+ - A row's `request` and `reply` become the lines of its turn in `history`, and
899
+ the handoff budgets bound them as for stored Turns (see
900
+ [Group chat and Main Bot](#group-chat-and-main-bot)).
901
+ - The rows replace the stored Turns in that ContextPack. The current Turn
902
+ always comes from this ledger.
903
+ - The collaboration state does not store the rows. The Turn keeps their hash
904
+ in `historyDigest`, which covers `reply`. K4 keeps the frozen instruction
905
+ of the offer, as for every offer.
906
+ - Cards, questions and rejected actions stay Host state. Room seats read room
907
+ messages, so they read no history.
908
+ - A read that throws or returns another shape leaves the Turn queued. The
909
+ timer reads again after about one second.
910
+ - A read still open after `historyTimeoutMs` (default 10 seconds) counts as
911
+ failed, so a stalled authority cannot hold the Host queue. The Host does
912
+ not abort the read. Reads run one after another, so a pass waits at most
913
+ `historyTimeoutMs` for each Turn that reads.
914
+
915
+ With the `roomHistory` option, the room messages of a seat ContextPack come
916
+ from an external authority too (#883). Before a seat Turn freezes its offer,
917
+ the Host calls `roomHistory({ roomId, botId, turnId })` outside the ledger
918
+ transaction, in the same phase as `history`.
919
+
920
+ - The authority returns the messages that this seat's Bot can see, oldest
921
+ first, as `{ id, from, text, late }` rows. The authority selects them for
922
+ that Bot, so K8 applies no `visibleFrom` of its own. Rows in another shape
923
+ are refused.
924
+ - The rows replace `room.messages` in that ContextPack, in the same message
925
+ window. The state does not store them. The seat Turn keeps their hash in
926
+ `historyDigest`.
927
+ - K8 still writes `room.messages`. Round counts, mention seats and the seat
928
+ request text read it.
929
+ - A read that throws or returns another shape leaves the seat queued, and the
930
+ timer reads again. A read still open after `historyTimeoutMs` or at the
931
+ seat deadline counts as failed.
932
+ The seat deadline still applies, so a seat whose read never succeeds is
933
+ released as `busy` and its Turn expires.
934
+ - Each accepted seat post also publishes the projection
935
+ `room-message:<roomId>:<messageId>` with `{ roomId, id, from, text, late }`,
936
+ the row that `room.messages` stores. The message id is the seat id, so a
937
+ replay has the same id and body; the uploader delivers it at least once, and
938
+ the Host deduplicates by id. A `pass` and a refused post publish no
939
+ `room-message:` projection; their seats have `room-seat:` projections.
940
+ Without the option, no `room-message:` projection exists.
941
+ - The next seat of a room is not read while that room has an undelivered
942
+ `room-message:` projection. K4 drops a projection only after the Host
943
+ uploader's `deliver` resolved, so the Host's `deliver` must resolve only
944
+ after its write can be read back from the authority. The held seat waits
945
+ like a failed read, and its deadline still applies: a projection that never
946
+ delivers releases each later seat of its room as `busy` at its deadline.
947
+ - Room input that the Host gives K8 (`roomInput`, or `receive` for a group
948
+ message) is not projected. The Host writes it to its authority first, then
949
+ calls K8, so the next seat reads it.
950
+ - The ledger does not store the mode. Each time a Host turns the option on, it
951
+ first writes the posts made while it was off to its authority, deduplicated
952
+ by id. Turn the option on before the first retention: retention moves the
953
+ room messages of archived roots out of `snapshot().team.rooms` (see
954
+ Retention). After a retention, the backfill also reads the archived rows of
955
+ namespace `roomMessages`, which the owner switch export carries in its
956
+ `archived` section.
957
+
958
+ The team comes from this ledger, unless the `team: 'external'` option is set.
959
+
960
+ ## External team authority
961
+
962
+ With `team: 'external'`, an external authority owns the Bots (#739 Q4c). The
963
+ constructor creates no Main Bot. The authority sends team snapshots with
964
+ `applyTeam({ revision, bots })`. Each Bot has `id`, `name`, `role`,
965
+ `persona`, `model` and `mainBot`. The Host maps `model` to its own execution
966
+ template.
967
+
968
+ - The team revision is the authority's revision. It is not the collaboration
969
+ commit revision. It must be a safe integer of 1 or more, and each new
970
+ snapshot must have a higher revision.
971
+ - A newer snapshot archives each Bot that it does not list, as `delete_bot`
972
+ does. A new Bot gets its first persona projection. A changed name, role,
973
+ persona or model queues the same projection as `update_bot`. A change of the
974
+ Main Bot flag only sets the flag.
975
+ - An archived Bot cannot come back. A snapshot that lists one is refused, and
976
+ nothing changes.
977
+ - The command id is the team revision. The same revision with the same Bots
978
+ replays, in any Bot order. The same revision with other Bots is an
979
+ `identity_conflict`. The replay check comes first, so an exact retry of an
980
+ applied older snapshot gets its first result.
981
+ - A revision that is not newer and was not applied before refuses with
982
+ `stale_team`. The refusal is a commit, so it adds 1 to the collaboration
983
+ revision.
984
+ - The snapshot covers the Bots only. `setMainBot`, `create_bot`, `update_bot`
985
+ and `delete_bot` refuse with `external_team`, and the Main Bot schema does
986
+ not offer those three actions. Team notes and persona retries stay local.
987
+ Rooms stay local too, unless the external rooms mode below is on.
988
+ - The ledger stores the mode. A ledger with a local team cannot open in
989
+ external mode, and an external ledger cannot open without the option.
990
+
991
+ A snapshot Bot can carry `participation: 'suspended'` (#1319). The Bot stays in
992
+ the team, its rooms and its routines, but takes no new K8 work. `participation`
993
+ is `'suspended'` or absent; any other value refuses the whole snapshot as
994
+ `Invalid team snapshot Bot`, and nothing changes. A suspended Bot:
995
+
996
+ - leaves the `delegate.to` and `room_call` member lists of every schema frozen
997
+ after the snapshot, and gets no room seat, even when a message names it;
998
+ - ends its open work as an archived Bot's does: a Turn that has not frozen
999
+ concludes `cancelled`, a frozen intent that has not started is cancelled, and
1000
+ work that started runs on with its outcome kept as audit only. An open
1001
+ delegation to it resolves `refused` with reason `target_suspended`; a verdict
1002
+ for a delegation that it started gets no reply Turn
1003
+ (`undelivered: 'initiator_suspended'`);
1004
+ - refuses `input`, an owner `receive`, `answer` of its question and `decide` of
1005
+ its card with `TeamModeError` code `bot_suspended`
1006
+ (`bot_suspended: Bot <id> is not participating`), and the commit writes
1007
+ nothing. `setAutonomy`, `persona_ready` and push routes stay available.
1008
+
1009
+ A later snapshot without the field restores the Bot as it was: its profile
1010
+ revision, `readyRevision`, autonomy, room memberships and routines are kept.
1011
+ Work cancelled or refused while it was suspended, and routine slots that it
1012
+ missed, do not come back. Archive stays for a deleted Bot: a suspended Bot that
1013
+ a snapshot no longer lists is archived.
1014
+
1015
+ With `persona: 'external'` as well, the Host owns the persona projection of
1016
+ each Bot (#879). The Host projects the Agent home with its own daemon hook, so
1017
+ there is one projection writer and one revision for each agentRef.
1018
+
1019
+ - Each snapshot Bot carries the Host's `profileRevision`, a decimal string.
1020
+ K8 uses it as the Bot revision and as the agentRef `profileRevision` of its
1021
+ execution. K8 queues no projection and counts no revision of its own.
1022
+ - The revision never goes back. A changed name, role, persona or model needs a
1023
+ newer revision. A snapshot that breaks either rule is refused, and nothing
1024
+ changes. Without the option, a snapshot with `profileRevision` is refused.
1025
+ - `personaReady(botId, revision)` reports that the Host applied this revision.
1026
+ The current revision readies the Bot, an older one changes nothing, and a
1027
+ newer one refuses. A Bot's Turns freeze their offers only when it is ready,
1028
+ as before. After a newer revision, the Bot keeps its last ready revision, so
1029
+ it stays a delegate target while its Turns wait. The Host reports
1030
+ `personaReady` only after the snapshot that introduces that revision
1031
+ resolves: an earlier report is refused, not stored.
1032
+ - `retryPersona` refuses with `external_persona`.
1033
+ - The ledger stores this mode too, so a restart cannot change it. The mode is
1034
+ fixed once stored, with no migration. The option needs `team: 'external'`.
1035
+
1036
+ With `rooms: 'external'` as well, the team snapshot also owns the rooms
1037
+ (#1321). Each snapshot carries `rooms`, the authority's whole room list, and
1038
+ `applyTeam({ revision, bots, rooms })` writes it after the Bots. Without the
1039
+ mode, a snapshot with `rooms` is refused; with it, a snapshot without `rooms`
1040
+ is refused, and nothing changes.
1041
+
1042
+ - A room has `id`, `name`, `members`, and optionally `admin`, `mode`,
1043
+ `announcement` and `memberMentions`. The id matches
1044
+ `^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$` and is not an `Object.prototype` key.
1045
+ The rules are those of `create_room`, with one difference: a room can have
1046
+ no member. Its members are Bots of the same snapshot, 0 to 12 and distinct,
1047
+ and its admin is a member. `mode` is `mention` or omitted, `memberMentions`
1048
+ is `execute`, `ignore` or omitted. A snapshot holds at most
1049
+ `TEAM_ROOM_LIMIT` (64) rooms, and room order is not content.
1050
+ - A new room starts with no visible history for its members. A listed room
1051
+ takes the snapshot's fields as a whole: an omitted admin, announcement or
1052
+ `memberMentions` is cleared, and `memberMentions` returns to `execute`. A
1053
+ member that stays keeps its visibility, a new member sees messages from now
1054
+ on, and a member that left and came back starts again from now.
1055
+ - A room that the snapshot no longer lists is archived for good: it shows
1056
+ `archived: true`, with no member, no visibility and no admin. At the next
1057
+ pass its seats are removed as for a member that left: a seat that has not
1058
+ started is cancelled, a seat that started runs on and its speech is kept as
1059
+ audit only, and the round closes once every seat is released. `roomInput`,
1060
+ a room `receive` and a `room_call` round in it throw `Room is archived`, so
1061
+ the Host stops giving K8 its inbound messages first. A snapshot that lists
1062
+ an archived room is refused, and nothing changes.
1063
+ - `createRoom`, `updateRoom` and `setMemberMentions` refuse with
1064
+ `external_rooms`. The Main Bot schema offers neither `create_room` nor
1065
+ `update_room`, and an outcome that has one is refused with `external_rooms`.
1066
+ - A suspended Bot (#1319) can be a room member, under the suspension rules
1067
+ above.
1068
+ - The ledger stores this mode too, so a restart cannot change it. The mode is
1069
+ fixed once stored, with no migration. The option needs `team: 'external'`.
1070
+
1071
+ With `history` and `team: 'external'` together, the device ledger holds
1072
+ neither the history nor the team authority.
1073
+
1074
+ ## Group chat and Main Bot
1075
+
1076
+ The supplied Agent template is the initial Main Bot. A team can have multiple
1077
+ Main Bots. `setMainBot(botId, value)` is an owner API. The Host must authenticate
1078
+ its owner APIs before calling them, unless it passes a verified principal
1079
+ ([IM channel input](#im-channel-input)). `input(key, request, botId)` selects a Bot.
1080
+ The default is the initial Main Bot. Ordinary turns keep the K8a actions.
1081
+
1082
+ Give the Host the real server home projection API. Install
1083
+ `createBotPersonaProjection()` as the daemon's `agentHome.projection` consumer.
1084
+ It validates the opaque profile digest. It writes persona text to the Bot's
1085
+ own `AGENTS.md` with the SDK `writeHomeFile`, under the SDK writer lease. New
1086
+ profiles and updates wait for an exact `applied` or `idempotent` readback.
1087
+ The readback must match device,
1088
+ AgentRef, request id, and digest. New execution input then uses that revision.
1089
+ Already frozen executions keep their old input. A pending projection does not
1090
+ permit dispatch. All management actions participate in the K4 outcome commit.
1091
+
1092
+ Main Bot schemas offer six actions: `create_bot`, `update_bot`, `delete_bot`,
1093
+ `create_room`, `update_room`, and `team_note`. The Host checks the current role
1094
+ again when applying each action. Creation offers three local Bot slots and one
1095
+ local room slot. A room can use those Bot slots in the same outcome. Model ids
1096
+ come from `BotOptions.models`. The default model id is `default`. Each model
1097
+ has a Host-owned execution template. A Bot update cannot move its device.
1098
+ The Host can replace the templates at run time with `setModels(models)`, for
1099
+ example after a device key changed (#1357). Construction and `setModels` apply
1100
+ each template by model name to every unarchived Bot, a suspended one too. The
1101
+ Bot keeps its device and its profile; its agentRef follows its profile
1102
+ revision. No profile revision, readiness or persona projection changes. A Turn
1103
+ that froze before keeps the execution it froze with, also while it waits in
1104
+ the K4 FIFO. A template outside `readOnlyToolsets` refuses the call, which then
1105
+ changes nothing. A Bot whose model has no template keeps its stored template,
1106
+ and each of its Turns, a sealed routine Turn too, blocks with
1107
+ `Unavailable model: <name>` before it freezes (`blocked:<turnId>`). It freezes
1108
+ once a later `setModels` or restart provides the template. No write entry
1109
+ refuses a missing template of an existing Bot: a snapshot or `update_bot` that
1110
+ names such a model stores the profile and keeps the stored template. A new Bot
1111
+ still needs a template, since its device comes from it. A sealed routine's
1112
+ template is the sealed copy and is not re-projected.
1113
+ Profiles cap the active team at 24 Bots. Team notes cap at 20 entries of 300
1114
+ characters. Every team Bot receives these notes. Other Bots' private turns and
1115
+ persona text do not enter its ContextPack. No cross-home memory read occurs.
1116
+ `delete_bot` archives the profile and cancels unstarted work. Running results
1117
+ become audit only. Delegated work for the archived Bot is also cancelled when
1118
+ it runs (see Cross-Bot delegation). It does not delete the Agent home.
1119
+
1120
+ Profile deliveries share the Host serial consumer. The consumer waits for known
1121
+ old intents to settle. Device terminal readback can precede writer cleanup.
1122
+ A projection can therefore stay pending after it hits that lease. The Host
1123
+ reads every prior delivery before retry. It stores a new delivery id before
1124
+ sending the same revision and digest. Delay starts at one second and caps at
1125
+ 60 seconds. Recovery reuses stored ids. Old duplicate controls cannot replace
1126
+ a newer revision. Each revision remains gated on an exact accepted readback.
1127
+
1128
+ Use `roomInput(key, roomId, text, mentions, principal)` for a user message. `mentions` is
1129
+ an ordered Bot id list or the structured value `all`. The default is empty.
1130
+ The optional `principal` is the verified sender ([IM channel input](#im-channel-input)).
1131
+ The Host never scans text for names or `[PASS]`. Rooms support mention mode.
1132
+ An admin identity grants a larger budget. It does not create an implicit seat.
1133
+ A room has no admin mode, so the outcome fragment offers only `mention`. `updateRoom` is an authenticated owner API
1134
+ for membership, admin, name, and announcement changes.
1135
+
1136
+ `createRoom(roomId, fields)` is an authenticated owner API that creates a room
1137
+ with a Host room id and no model run (#1321). The id follows the snapshot room
1138
+ id rule ([External team authority](#external-team-authority)), and the fields
1139
+ follow `create_room`: 1 to 12 distinct active members, an admin that is a
1140
+ member, and mention mode only. The command id comes from the room id. The same
1141
+ id with the same name, members, admin and announcement replays the first
1142
+ result, and other fields are an `identity_conflict` (`Room identity conflict`).
1143
+ An id that already has a room, also one that a Main Bot outcome created, throws
1144
+ `Room already exists`. A new room starts with no visible history for its
1145
+ members. Later membership changes follow `updateRoom`. A local room cannot be
1146
+ deleted. In the external rooms mode, `createRoom` refuses with
1147
+ `external_rooms`.
1148
+
1149
+ `setMemberMentions(roomId, value, principal)` is an owner API for the
1150
+ `memberMentions` setting of a room (#1230). The value is `execute` or `ignore`;
1151
+ the default is `execute`. With `execute`, a structured mention from any verified
1152
+ human opens a seat. With `ignore`, a structured mention from a human who is not
1153
+ the owner opens no seat: the message stays room background, with no device work
1154
+ and no BYOK key. The owner's own mention still opens seats. Only the owner
1155
+ changes the setting, and only inbound messages that arrive after it see the new
1156
+ value; an open root and an established seat keep their admission
1157
+ ([R6](../../docs/host-im-adapter.md#r6-structured-mentions)).
1158
+
1159
+ A room turn is a fresh member Agent execution. It uses `bot-turn-outcome.v1`
1160
+ with required `speech`, plus optional `room_call`. It has no messageEgress.
1161
+ `{ speech: { kind: 'post', text: 'Evidence' } }` writes shared history.
1162
+ `{ speech: { kind: 'pass' } }` is an explicit pass. Empty or blank speech,
1163
+ missing outcome, and execution failure are visible seat failures. A textual
1164
+ mention in a post cannot create a seat. Main Bot room seats have the same speech-only authority as other members.
1165
+ Management actions are available only outside room seats. Only structured `room_call.members` can add seats after a Bot speaks.
1166
+
1167
+ Seats run in reservation order within a round. Each seat enters the same K4
1168
+ FIFO as that Bot's own turns. The waiting grace is 240 seconds. First observed claim starts a separate
1169
+ 240-second running grace. This persisted deadline does not reset on later
1170
+ scans or recovery. The K4 fallback
1171
+ waiting bound stays at 300 seconds. Room admission cancels waiting work first.
1172
+ If the member is still waiting at grace, the seat becomes `busy`. If it has
1173
+ started, the round can proceed while its writer stays held in K4. A later post
1174
+ uses its seat id and enters history once. Removed waiting seats are invalid.
1175
+ Removed running members can produce audit evidence, but cannot post or call.
1176
+ Already completed post, pass, and failure states remain unchanged.
1177
+
1178
+ A round permits initial seats + 4, plus 4 when it has an admin. Each member
1179
+ gets at most two seats; the round admin gets at most four. A reservation spends
1180
+ budget even if it fails, passes, or times out. Batch room calls are atomic.
1181
+ A late room_call after a round closes can open a new round. At most three such
1182
+ rounds share one user root. At most ten late posts share that root. A new user
1183
+ message starts a new root. ContextPack selects up to the most recent 100
1184
+ eligible messages. The 32 KiB budget counts the UTF-8 bytes of the frozen
1185
+ Request plus the serialized ContextPack. `historyWindow.currentRequestBytes`
1186
+ records the exact Request size, including the room request wrapper. The Host
1187
+ drops oldest whole rows until that budget fits. `historyWindow.notice` reports
1188
+ omitted messages and refusals.
1189
+ History overflow does not block a seat. The frozen Request section keeps the
1190
+ complete accepted request. Only a Request that alone exceeds 32 KiB blocks
1191
+ the turn. The seat reason and blocked projection report its byte count, the
1192
+ limit, and a request to shorten the input.
1193
+ For room_call seats, the visible caller post is the current request and its
1194
+ author id is retained. A pass inherits the earlier visible trigger. This
1195
+ request is preserved even if it has left the recent message window.
1196
+ The ledger retains its full audit history. No Summary is generated. Authority
1197
+ enums and required control metadata are not silently truncated. If non-history
1198
+ metadata plus the accepted Request exceeds the budget after history is removed,
1199
+ the notice reports that separate condition. That condition does not block.
1200
+ A Bot Turn outside a room carries its history in `history`, the
1201
+ `@byok-sdk/protocol` `buildHandoffPack` result (#1446). A row becomes a turn:
1202
+ `lines` is `{ speaker: source, text: request }`, then
1203
+ `{ speaker: 'bot', text: reply }` when the row has a reply, and `meta` is
1204
+ `{ id, root, hop, status, conclusion?, outcomeSummary }`. `history.recent`
1205
+ holds the newest whole turns, `history.earlier` holds excerpts of the turns
1206
+ before them, and `history.omittedTurns` counts the rest. The `handoff` option
1207
+ sets `recentBytes`, `earlyBytes` and `totalBytes`, by default 40 KiB, 6 KiB and
1208
+ 46 KiB (`DEFAULT_HANDOFF_BUDGETS`), and construction refuses a value that
1209
+ `buildHandoffPack` refuses. A snapshot view from `contextPack` has the
1210
+ candidate as the newest turn of `recent`, which may be cut; an empty `recent`
1211
+ with turns in the input means the candidate did not fit, and the last turn of
1212
+ `earlier` is not the candidate. `contextMaxBytes` covers the Request and the
1213
+ ContextPack without `history`. `contextTurnLimit` selects no history; it still
1214
+ bounds refusals, cards, questions and the room messages that retention keeps.
1215
+ A room seat keeps `room.messages`, as above.
1216
+
1217
+ Cards and questions each retain at most 12 items. Pending work takes priority.
1218
+ The Host removes old refusals, settled items, old messages, then pending items.
1219
+ `historyWindow.turnLimit` names the message or item count limit. Both room and
1220
+ private context also report `omittedMessages`, `omittedCards`,
1221
+ `omittedQuestions`, `omittedPendingCards`, `omittedPendingQuestions`, and
1222
+ `omittedRejections`, and a room seat reports `omittedTurns`. Zero counts remain
1223
+ explicit. `historyWindow.notice` also reports turns that `history` omits. Full
1224
+ outcomes stay in the ledger. Context includes action names and the current
1225
+ routine definition.
1226
+
1227
+ Rejected feedback is private to its Bot. The next frozen input reserves it.
1228
+ An execution that fails before it starts releases that reservation.
1229
+ A turn that cannot pass Request or schema admission has status `blocked` and
1230
+ `blockedReason`. It creates no intent. `cancelTurn` can cancel it before admission.
1231
+ Other schema composition errors propagate as Host defects.
1232
+
1233
+ Unmentioned messages are stored as background. They do not create a seat, but
1234
+ a later selected member can see eligible background messages. Each member has
1235
+ a persisted offset into `room.messages` in `visibleFrom`. New members see only
1236
+ messages appended after joining. Retained members keep their offset; retention
1237
+ lowers it by the messages that it moves from before it, so the member sees the
1238
+ same kept messages. Leaving and
1239
+ rejoining resets it. Both owner edits and Main Bot room edits use this rule.
1240
+ A pre-join root request is also excluded from a new member's Request section.
1241
+ A delayed post appended after joining is visible. Already frozen offers keep
1242
+ their selected window. A room without an earlier offset starts at the next
1243
+ user input; its older history is not disclosed.
1244
+
1245
+ A room Turn never gets `memory_save` (#1446): other users' and Bots' text
1246
+ reaches it, and what a Turn saves comes back in every later Turn of that Bot.
1247
+ `syncTurn` freezes a `room_slot` Turn with a lower `payload.agentMemory`:
1248
+ `read-write` becomes `read`, `read-write-if-admitted` becomes
1249
+ `read-if-admitted`, and a template without the field freezes as
1250
+ `read-if-admitted`. `none`, `read` and `read-if-admitted` stay. The mode only
1251
+ goes down. Every other source keeps the template value, a sealed routine Turn
1252
+ too, and the frozen execution stores the mode that the offer carries, so replay
1253
+ does not change. `read-if-admitted` needs a device that advertises
1254
+ `agent-memory-selection` and `agent-memory-read-if-admitted`; a daemon with an
1255
+ Agent home advertises both.
1256
+
1257
+ Read-only here means no `memory_save` and no memory-writing guidance. The SDK
1258
+ does not make memory files read-only ([protocol](../../docs/protocol.md)
1259
+ §2.2): a Bot whose toolset can write files can still change `MEMORY.md` from a
1260
+ room Turn. A Host that needs to stop that narrows the toolset or the file scope
1261
+ of the Bot's template.
1262
+
1263
+ `src/group-chat.test.ts` uses a real embedded SDK, daemon, HTTP transport,
1264
+ SQLite reopen, persona writes, and submit_result helper. `src/rooms.test.ts`
1265
+ checks budgets, authority, atomic refusal, and context limits as state rules.
1266
+ `roomInput` and all other mutations use the same serial Host consumer. Do not
1267
+ call K4 mutation APIs directly. Upload projections with `core.flushProjections`
1268
+ or read `snapshot().team` for seats, profile delivery state and the room
1269
+ messages that retention has not moved.
1270
+
1271
+ ### Room seat projections
1272
+
1273
+ K8 publishes how each seat of a room round ended, and when a round root has
1274
+ ended, in every mode, with or without `roomHistory` (#1393). The state does
1275
+ not store them; each is published once, in the transaction that makes it
1276
+ true.
1277
+
1278
+ - `room-seat:<roomId>:<seatId>` with `{ roomId, root, roundId, seatId, botId,
1279
+ status, late, reason?, triggerMessageId? }`, when the seat becomes terminal: `post`, `pass`,
1280
+ `failed`, `busy`, `removed` or `blocked`. `late` is not terminal; a late
1281
+ seat is published when its Turn ends. `reason` is the conclusion or block
1282
+ reason that the seat stores. A seat with no admitted Turn, such as a
1283
+ waiting seat whose Bot left the room, is published too, though it has no
1284
+ `bot-turn:` projection. Only a seat that a `room_call` opened has
1285
+ `triggerMessageId`, the message the seat answers: the caller's post (its
1286
+ seat id), or, when the caller passed, the message the caller answered (its
1287
+ own `triggerMessageId`, else the root). A Host tells a mentioned seat from a
1288
+ `room_call` seat by this field and does not derive it from the seat id. A
1289
+ seat opened before the release that added the field is not backfilled.
1290
+ - `room-root:<roomId>:<root>` with `{ roomId, root, seats }`, when every seat
1291
+ of every round of the root is terminal, the seats that a `room_call` added
1292
+ included. `seats` lists their ids in reservation order; each has its
1293
+ `room-seat:` projection in the same or an earlier transaction. A root that
1294
+ opens no seat is published in its `room_input` or `receive` transaction,
1295
+ with `seats: []`. The root is the id that `retain` acknowledges.
1296
+ - A Host must handle both prefixes before it upgrades to the release that
1297
+ adds them: a Host that refuses an unknown projection prefix fails its flush
1298
+ on the first one.
1299
+
1300
+ ## Persona delivery failures
1301
+
1302
+ A stale or conflicting persona completion stays in the owner ledger. It emits
1303
+ an owner projection with the Bot id, revision, reason, and recoverable status.
1304
+ Waiting turns expose `profileFailure`. They remain queued and cannot execute
1305
+ with an unconfirmed persona. The authenticated owner can call
1306
+ `retryPersona(botId)` after resolving the device-side problem. This creates
1307
+ the same desired persona at the next profile revision. It retains the failed
1308
+ operation for audit. An exact accepted readback still gates dispatch. Retry
1309
+ also survives a Host restart. It does not bypass schema or persona admission.
1310
+ A stale device may need profile-state reconciliation before retry can succeed.
1311
+ Transient delivery errors remain pending and use the existing automatic retry.
1312
+
1313
+ The supplied `createBotPersonaProjection` consumer writes `AGENTS.md` with
1314
+ the SDK `writeHomeFile` (#738). It runs on Windows, Linux and macOS. After a
1315
+ process crash, `AGENTS.md` has its old or its new persona. On POSIX, an
1316
+ `applied` readback means that the file and its directory are flushed. On
1317
+ Windows, it means that the file only is flushed. There, an OS crash or a power
1318
+ loss after the readback can bring back the old persona while the SDK record
1319
+ keeps the new revision. This Host does not deliver an acknowledged revision
1320
+ again, so the old file stays until the next persona update writes it. A process
1321
+ crash can leave an `AGENTS.md.<pid>-<n>.tmp` file in the home. The next
1322
+ `writeHomeFile` call for `AGENTS.md` removes it when that process has ended.
1323
+ The Host failure and retry API does not change these limits.
1324
+
1325
+
1326
+ ## Deferred Main Bot routine target
1327
+
1328
+ Main Bot `create_routine.target` for another Bot is not implemented. Routine
1329
+ creation remains self-only in this example. Aimpact did not approve that
1330
+ extension for this PR. A later K8b work order must add it. Cross-Bot delegation
1331
+ also stays outside this history-window change.
1332
+
1333
+ ## Cross-Bot delegation
1334
+
1335
+ This section covers slices X1–X6 and X2M of the
1336
+ [approved plan](../../docs/adr/ADR-041-k8b-cross-bot.md).
1337
+ See the [acceptance matrix](VALIDATION.md) for evidence and open rows.
1338
+ A Bot can delegate requests to other Bots of the same team. The `to` enum
1339
+ lists this Bot first, then each active team Bot after its first persona
1340
+ readback. It lists Bot ids only. A room seat has no `delegate` fragment.
1341
+
1342
+ One outcome can hold two cross-Bot items. The Host refuses an item with
1343
+ a delegation verdict and a reason: `room_seat`,
1344
+ `target_archived`, `hop_limit`, or `budget_exhausted`.
1345
+ A refusal also enters the initiator's `rejectedActions`.
1346
+ An accepted item creates a `bot_request` Turn for the target. Its id is
1347
+ `H(taskId, 'delegate', index)`. Its hop is the initiator's hop plus one, at
1348
+ most four. B's ContextPack holds B's own history and a `delegation` block.
1349
+ B's reply cap is `BOT_REPLY_MAX_BYTES` (8 192 UTF-8 bytes).
1350
+
1351
+ Each Turn stores `authority`: `owner` for user input and answers, `bot` for a
1352
+ `bot_request`. Continuations, replies, action results, and routine Turns
1353
+ inherit it. Management needs a Main Bot and `owner` authority, both in the
1354
+ schema and at apply time.
1355
+
1356
+ `consumeMessage` checks the exact task, device, AgentRef, and destination
1357
+ binding in one ledger transaction. It stores an accepted delegated reply by
1358
+ task id. That record is the only reply body authority. At the chain end, the
1359
+ verdict is `answered` when the record exists. Otherwise the delegation is
1360
+ `reply_pending`. The Host timer reads `tasks.agentMessage` with a backoff from
1361
+ 1 to 60 seconds. It does not wait for a K4 scan. No message gives `failed`
1362
+ (`no_reply`). Held gives `reply_held`; `abandonDelegation` then sets
1363
+ `abandoned`. After `uncertainAfterMs` (default 30 minutes) without a result,
1364
+ the delegation is `uncertain`.
1365
+
1366
+ Other chain ends map to verdicts as follows. `failed` gives `failed`.
1367
+ `declined` gives `failed` with `busy` or the decline code. `expired` gives
1368
+ `expired`. A Host cancel with reason `expired` gives `expired`
1369
+ (`claim_raced_deadline`). A user cancel gives `cancelled` (`user_cancelled`).
1370
+
1371
+ `cancelDelegation(id)` works while the delegation is queued, `waiting_device`,
1372
+ running, or `reply_pending`. `cancelTurn` on a chain Turn calls it. One transaction
1373
+ freezes `cancel = { requestedAt, targetTurnId, delivered }` on the current
1374
+ chain Turn. That Turn then accepts no first message and applies no outcome.
1375
+ Without a K4 intent, the transaction closes the Turn and sets `cancelled`.
1376
+ It does not call `core.cancel`. With an intent, the Host calls `core.cancel`
1377
+ after the commit and then sets `delivered`. Each `process` pass delivers an
1378
+ undelivered cancel to its frozen target, so a restart completes it. When
1379
+ `core.cancel` fails, `cancelDelegation` rejects, but the cancel stays
1380
+ committed and the timer delivers it. A repeat gives `cancel_pending` until the
1381
+ verdict and `already_settled` with the verdict after it; neither writes or calls
1382
+ `core.cancel` ([idempotent owner cancels](#idempotent-owner-cancels-1405)).
1383
+
1384
+ A message accepted before the cancel stays. The verdict is then `cancelled`
1385
+ with that reply marked `partial`. A message after the cancel is refused
1386
+ (`delegation_cancelled`). A cancel with no terminal after `cancelGraceMs`
1387
+ (default 60 seconds) shows `uncertain`. A claimed chain Turn with no terminal
1388
+ after `uncertainAfterMs` also shows `uncertain`. The Host never resubmits and
1389
+ never starts a new generation. A later terminal gives the normal verdict.
1390
+
1391
+ A Main Bot cancels through the `cancel_delegation` outcome fragment. Only a
1392
+ Main Bot Turn with `authority = owner` outside a room seat gets it. Its
1393
+ `delegationId` enum lists open delegations: no verdict, no cancel yet, and
1394
+ status `queued`, `waiting_device`, `running`, or `reply_pending`. The list is
1395
+ newest first and has at most 24 ids. The ContextPack `openDelegations` block shows each listed
1396
+ id with its Bots, status, and the first 80 code points of the request. It
1397
+ also counts the omitted delegations and shows a notice. The owner cancels
1398
+ those with `cancelDelegation`. Apply runs after the management actions and
1399
+ before the routine actions. It checks room seat, owner authority, and the
1400
+ Main Bot role again. Then it runs the same arbitration transaction. The cancel fact records
1401
+ `reason: 'main_bot_cancelled'`, and the verdict keeps that reason. A resolved
1402
+ delegation gives the rejected action `already_resolved` and no second
1403
+ verdict. The Main Bot sees it in its next ContextPack.
1404
+
1405
+ `abandonDelegation(id)` ends a `reply_held` or `uncertain` delegation with
1406
+ `abandoned`. When the attempt can still run, it also writes a K4 cancel. A
1407
+ terminal after the verdict goes to `audit` only.
1408
+
1409
+ When the target Bot is archived, the next `process` pass cancels its open
1410
+ delegations. It uses the same arbitration transaction, with the cancel reason
1411
+ `target_archived`. This applies in every open state: queued, `waiting_device`, running,
1412
+ `reply_pending`, `reply_held`, and `uncertain`. A Turn without a K4 intent
1413
+ closes at once. A queued intent settles as `cancelled`. A submitted attempt
1414
+ gets `tasks.cancel` and an attempt readback. A claimed attempt gets
1415
+ `tasks.cancel`, and the Host waits for its terminal. The verdict is `refused`
1416
+ (`target_archived`). A reply accepted before the archive does not go to the
1417
+ initiator. The Host writes an `audit` note for it. A cancel with no terminal
1418
+ follows the `uncertain` rules above. Archived Bots leave the `to` enum and the
1419
+ roster at the next schema build. A delegation cancelled by the archive leaves
1420
+ the `cancel_delegation` enum.
1421
+
1422
+ When the initiator is archived, the target's work continues. The verdict is
1423
+ still written, but the Host creates no `bot_reply` Turn and releases the free
1424
+ reply slots. The delegation row and its projection show
1425
+ `undelivered: 'initiator_archived'`.
1426
+
1427
+ Every verdict reaches the initiator once, in a `bot_reply` Turn. The accepted
1428
+ items of one outcome form a batch. The first report waits until each accepted
1429
+ item has a verdict or is `uncertain`. It holds every verdict of the batch so
1430
+ far, refusals included. Its id is `H('bot_reply', taskId)` for two accepted
1431
+ items and `H('bot_reply', delegationId)` for one. When every accepted item is
1432
+ `uncertain`, there is no batch Turn. A verdict after the first report, or
1433
+ after that state, reports in its own Turn `H('bot_reply', delegationId)`.
1434
+ When an outcome has no accepted item, one refusal report Turn
1435
+ `H('bot_reply', taskId)` holds all its refusals. That
1436
+ report has no `delegate` fragment. Status changes publish
1437
+ `delegation:<id>:<revision>` projections with `id`, `revision`, `root`,
1438
+ `fromBotId`, `toBotId`, `request`, `status`, and `verdict`, `reason`,
1439
+ `replyTurnId` and `undelivered` once set. `root` is the delegation's root, so a
1440
+ Host can place a cross-Bot delegation under the conversation of its root
1441
+ (#1356).
1442
+
1443
+ The root Bot budget is 12 units. An outcome with `n` accepted items reserves
1444
+ `n + max(n, 1)` units: one B unit and one A reply slot for each item.
1445
+ Admission counts every open reservation on the root. When the units are not
1446
+ free, the Host refuses accepted items from the last index
1447
+ (`budget_exhausted`) and checks again. After each report, the batch releases
1448
+ its free slots above the number of unreported items. A refusal report
1449
+ reserves one slot when one is free. Otherwise
1450
+ it is delivery only: it does not start a model, and it enters the next
1451
+ ContextPack. A unit is spent at the first observed claim and released when it
1452
+ can no longer be needed. `spent + reserved <= 12` holds after each transaction.
1453
+
1454
+ A `bot_request` or `bot_reply` instruction puts request text and reply bodies
1455
+ once, as raw UTF-8 in length-framed blocks. Team notes, rooms, and routines
1456
+ are trimmed oldest first, and background has priority: `history` gets only the
1457
+ bytes left after it, up to `handoff.totalBytes`. A larger
1458
+ `instructionMaxBytes` can therefore leave less history, because more background
1459
+ stays. `instructionMaxBytes` (default 65 536) bounds the whole instruction.
1460
+ Construction refuses a value below
1461
+ `minimumInstructionBytes(SYSTEM_PROMPT)`. The minimum includes the
1462
+ `openDelegations` block of a Main Bot reply Turn.
1463
+
1464
+ A Main Bot with 24 Bots, 8 routines, and a room exceeds the outcome schema cap
1465
+ of 16 384 bytes. The Host blocks such a Turn with a visible reason. It does
1466
+ not cut an enum. Without the room, 24 open delegations in the
1467
+ `cancel_delegation` enum still fit (15 949 bytes).
1468
+
1469
+ ### Topology switch (§4.1)
1470
+
1471
+ L is the old owner when a device moves from L to H (#957). L keeps one owner
1472
+ record per device in its ledger, as §4.1 records the mode per device: one L
1473
+ Host can own Bots on two devices (see "Second-device placement"). A device with
1474
+ no record is `{ mode: 'L', revision: 0 }`. `topology(deviceId)` reads it.
1475
+ The product runs the switch with these calls, each on the revision it expects.
1476
+ A stale revision throws `CommitConflict` with `stale_revision`, and each step
1477
+ except the export raises the revision:
1478
+
1479
+ 1. `freezeForSwitch(deviceId, revision)` writes `{ mode: 'L', switching: 'H' }`
1480
+ and returns the record read back from the ledger.
1481
+ 2. `drainForSwitch(deviceId, { cancel })` returns the device's open work:
1482
+ - open K4 intents whose execution names the device;
1483
+ - Turns of its Bots with no conclusion and no intent;
1484
+ - open input batches;
1485
+ - Agent home writes that were sent and have no terminal readback. A write
1486
+ is marked sent in the transaction before the send, so a crash or a
1487
+ failed send still counts it.
1488
+
1489
+ With `cancel`, it cancels the intents, Turns and batches first, then runs a
1490
+ pass. A tried intent concludes only from its SDK terminal, so it stays
1491
+ listed until the reconciler reads one. The drain waits for nothing: no
1492
+ timeout counts as stop evidence.
1493
+ 3. `exportForSwitch(devices, exportedAt?)` seals the whole domain into a
1494
+ switch export once every device in `devices` is frozen at its revision and
1495
+ drained (see "Owner switch on L" below).
1496
+ 4. After the new owner imported and verified the export,
1497
+ `commitSwitch(deviceId, revision, receipt)` writes `{ mode: 'H' }` for every
1498
+ device of the export in one transaction, when `receipt` is the export's
1499
+ digest and `deviceId` at `revision` is one of its devices. It refuses while
1500
+ the same transaction finds open work. `abortSwitch(deviceId, revision)`
1501
+ instead writes `{ mode: 'L' }`, so L owns the device again and its held
1502
+ Turns run.
1503
+
1504
+ While the device is frozen, each entry that can create execution for it throws
1505
+ `DeviceSwitchingError` (`code: 'device_switching'`) and writes nothing:
1506
+
1507
+ - `input`, and `receive` owner input, for a Bot on the device;
1508
+ - `roomInput`, and `receive` room input or bot background, when any Bot member
1509
+ of the room is on the device;
1510
+ - `answer`, when the question's Bot is on the device, and `decide` (either
1511
+ decision), when the card's Bot is on the device, since each adds a Turn for
1512
+ that Bot;
1513
+ - `enqueueHostIntent` on the device.
1514
+
1515
+ The check runs after the replay lookup (the new `CommandPorts.admit` port), so
1516
+ an exact replay of a command or Host intent that L accepted before the freeze
1517
+ still returns its first result.
1518
+
1519
+ The Bots each command reaches are a pure rule, `commandBots(state, command)` from
1520
+ `./rules/commands` (#975). L refuses a command when one of those Bots' devices
1521
+ refuses work. H passes the same rule to its `CommandPorts.admit`, so both Hosts
1522
+ refuse the same commands during a freeze. A frozen domain then starts no new
1523
+ Turn and no new card connector call.
1524
+
1525
+ After the commit these entries throw `DeviceModeError` (`code:
1526
+ 'device_not_bound'`, `reason: 'mode'`, as H's refusal of a device in the other
1527
+ mode), for good.
1528
+
1529
+ Other refusals and holds:
1530
+
1531
+ - **Routine slot:** a slot of a routine whose Bot is on the device throws from
1532
+ the routine hook. K4 then records neither the slot nor a Turn, and the SDK
1533
+ delivers the wake again later, so a slot is never dropped. It runs after an
1534
+ abort. From the export on every slot refuses, also after the commit, and the
1535
+ new owner schedules the routine's wakes on its own SDK.
1536
+ - **Sync:** any other path that adds a Turn for a Bot on the device is held.
1537
+ This covers a Bot outcome that delegates, a room round, and a batch that
1538
+ seals.
1539
+ - **Agent home:** a home write for the device's Bots is not sent, so one Agent
1540
+ home never has two writers. A sent write is still read back. A write that
1541
+ was never sent is not read back and arms no timer, so after a commit nothing
1542
+ polls it.
1543
+ - **K4 submit:** L gives K4 `admitSubmit`, which reads the same record. K4 then
1544
+ sends nothing to the device, in the transaction that begins a submit and in
1545
+ the readback right before the SDK call. That holds for a queued intent from
1546
+ before the freeze, a `backoff` intent (it keeps its generation), the K4 timer
1547
+ drain and an intent added through `bot.core` directly. A held intent is sent
1548
+ after an abort; the drain with `cancel` settles it.
1549
+
1550
+ Commands that add no execution still run, since the drain needs some of them:
1551
+ cancels, team and routine lifecycle changes, `consumeMessage` and retention.
1552
+
1553
+ Each check reads the record in the transaction that would write the work. The
1554
+ constructor reads every record first and refuses a malformed one, so a restart
1555
+ admits nothing before it knows the freeze.
1556
+
1557
+ Once a device is in mode H, every step on this ledger refuses. A domain moves
1558
+ back to L by an import into a new L tenant (below).
1559
+
1560
+ ### Owner switch on L (#975)
1561
+
1562
+ `src/switch.ts` reads an L ledger into the switch format and writes the format
1563
+ into an L tenant. One function, `switchContent`, serves both the old owner's
1564
+ export and the new owner's read-back, so one function states what an L ledger
1565
+ holds. The whole coordination domain moves together.
1566
+
1567
+ **Old owner (L → H).** `exportForSwitch(devices, exportedAt?)` runs in one
1568
+ synchronous step: it dumps the ledger (K4 `dumpForSwitch`), checks it, seals it
1569
+ (`sealSwitchExport`) and records the export mark. It refuses:
1570
+
1571
+ - a device that is not switching at its revision, or still has open work;
1572
+ - a live Bot on a device it does not name, and every other state the format
1573
+ refuses (`SwitchExportError`);
1574
+ - Agent memory state, which binds the tenant inside its digests;
1575
+ - a pending projection: upload them with `core.flushProjections` first;
1576
+ - a pending submit or Host job, which K4 would run while the export waits;
1577
+ - a stored copy that differs from the value it is derived from, with
1578
+ `reference`: an intent's `agent` (K4 `agentKey`), task id (K4 `taskId`) and
1579
+ frozen input of each generation, K4 `applied` (the current task of each
1580
+ succeeded intent), each occurrence's wake key (K4 `parseRoutineWakeKey`), its
1581
+ slot, intent id and conclusion, a routine's next wake key, and the
1582
+ `attempts` of intents and occurrences;
1583
+ - a K4 or K8 record with a field the format does not name, which would be
1584
+ dropped.
1585
+
1586
+ From the mark on, also after a restart, this Host writes nothing to the
1587
+ ledger. Each K8 write refuses with `SwitchExportedError` (`code:
1588
+ 'switch_exported'`) after the write runs, so a new command on a frozen or
1589
+ H-owned device still gets its device refusal. A refusal the write raises first
1590
+ also comes before the export's: a replayed command id (also on a frozen
1591
+ device), an id conflict, `stale_revision` and `RetentionRefused`. Each refusal
1592
+ writes nothing. That holds for the root entries a product calls directly too: `commitInLedger`, `retainInLedger`,
1593
+ `callCardsInLedger` (before the connector runs) and `syncTurnInLedger`. The
1594
+ passes and the timer run nothing, the K4 hooks and the routine lifecycle and
1595
+ update entries refuse, and the compact veto (`botCompactVeto`) refuses every
1596
+ intent with `switch_exported`. The mark stays after the commit, so the old
1597
+ ledger keeps the exported state.
1598
+
1599
+ Do not compact an exported ledger. `ledger.compact` with no acknowledged
1600
+ intent still deletes expired tombstones, which the veto does not see. Before
1601
+ the commit that makes the commit refuse, so the switch is aborted and exported
1602
+ again; after the commit it does no harm.
1603
+
1604
+ `commitSwitch` checks the receipt against the mark, then seals the ledger
1605
+ again under the export's header and refuses a different digest. That check
1606
+ covers the K4 core, which writes on its own timers: a routine that is pacing a
1607
+ schedule retry, or that switches to a pending version, can change between the
1608
+ export and the commit. The commit then refuses, and the switch is aborted and
1609
+ exported again. The commit moves every device of the export at once, so a
1610
+ domain is never split between the owners. An abort of a device of the export
1611
+ ends the export, and the new owner discards its import; after the commit no
1612
+ device of it aborts.
1613
+
1614
+ **New owner (H → L).** On a new, empty ledger tenant (a switch back to L opens
1615
+ a new tenant), and with no `BotCollaboration` on it:
1616
+
1617
+ 1. `importForSwitch(ledger, document)` verifies the H export and writes it
1618
+ with each device owned by H and an import record, in one transaction (K4
1619
+ `loadForSwitch`). Before that transaction commits, K4 reads the tenant's
1620
+ rows back, and they must seal to the document's digest under its header;
1621
+ otherwise it throws `SwitchExportError` with `manifest` and writes nothing.
1622
+ So an import is either verified or not there. It returns the receipt
1623
+ `{ digest, devices }` that the old owner commits away on.
1624
+ 2. After the old owner committed, `commitImport(ledger, digest)` gives L each
1625
+ device of the import and deletes the import record.
1626
+ 3. `discardImport(ledger)` deletes an import that is not to be committed (K4
1627
+ `discard`). It first marks the import as being discarded, so a commit
1628
+ refuses it from then on.
1629
+
1630
+ A `BotCollaboration` refuses to open a ledger with an import record, and the
1631
+ root entries (`commitInLedger`, `retainInLedger`, `callCardsInLedger`,
1632
+ `syncTurnInLedger`) refuse it the same way before they run. So no work runs on
1633
+ an import before its commit, and a committed tenant has no record to discard. The import writes each derived value from the format: `agent` for the
1634
+ new tenant, the task ids and inputs of every generation, `applied`, slots, wake
1635
+ keys, intent ids, `attempts` and the Host intent handlers. A concluded intent
1636
+ gets K4's cursors of a new row (`phase: 'settled'`, `notBefore: 0`). Routines
1637
+ and occurrences go in the order of their ordinals, which the format makes their
1638
+ positions.
1639
+
1640
+ **Ordering.** The receipt is the export's digest, and nothing between the two
1641
+ Hosts proves that the target imported it: there is no authentication between
1642
+ them. The product runs the steps in order and keeps the document:
1643
+
1644
+ - The old owner commits away only after the target reported its import
1645
+ verified.
1646
+ - The export document is kept until the target committed toward its owner.
1647
+ - If an import is lost after the old owner committed away, the kept document
1648
+ is imported into a new tenant.
1649
+ - Only one import of a digest is committed; every other one is discarded. The
1650
+ receipt names no tenant, so one document can be imported into two tenants.
1651
+ - From the export on the old owner refuses all work, so two owners never run
1652
+ the domain at the same time.
1653
+
1654
+ Not moved: the source SDK's wakes, that is the `schedule` and `cancel-wake`
1655
+ rows and the scan wake. The new owner's `recover()` schedules each routine's
1656
+ next wake on its own SDK. K4 `ignoredWakes` does not move either. It is an
1657
+ optional audit of wake deliveries that the source SDK made and K4 ignored, at
1658
+ most `IGNORED_WAKE_AUDIT_LIMIT` rows, and no rule reads it. A target starts
1659
+ without it, as a new ledger does, and an export is not refused for it.
1660
+
1661
+ ### Owner switch export format (#975)
1662
+
1663
+ The `./migration` entry (`src/migration.ts`) is the one form in which a whole
1664
+ coordination domain moves between owners: an L ledger tenant or an H scope.
1665
+ Neither Host's storage is the format. The old owner builds a `SwitchContent`
1666
+ once every device of the domain is frozen and drained, and
1667
+ `sealSwitchExport` checks it, orders each section by its identity and adds a
1668
+ manifest. The manifest has the count and the `hash(canonical(section))` of
1669
+ each list section, and one digest over them and the header (source, domain,
1670
+ frozen device revisions, export time). The collaboration digest is the hash
1671
+ of its JSON text, because the insertion order of its maps is state: K8 reads
1672
+ Turns in that order for context and retention, so a target must keep it. The new owner runs `verifySwitchExport` on
1673
+ the document before it writes anything, and again on its own rows read back
1674
+ into this form, so the digest it records in its receipt is the source's. The
1675
+ digest covers the header, and `domain` is the source's tenant or scope id (a
1676
+ switch back to L opens a new tenant). So the read-back copies the document's
1677
+ header as it is and rebuilds only the sections from the target's rows. Devices
1678
+ are in JS string order of their id, and each section in JS string order of
1679
+ `canonical(identity)`, so a read-back sorts that way in JS or reseals; a
1680
+ database `ORDER BY` may give `unsorted`.
1681
+
1682
+ A record holds what a target needs to rebuild the row, with values the source
1683
+ stores, never a default. Routines and occurrences carry their ordinal, which is
1684
+ their position in their section, exactly 0 to n - 1: what moves is their order,
1685
+ which is all K4 stores, and H stores the position in its column. An intent
1686
+ carries K4 `sequence` or H `ordinal` as it is, gaps included, and its frozen
1687
+ input (a sealed one stays sealed). H stores only part of this
1688
+ today: the K4-only fields get H columns in the H slice that imports them.
1689
+ Every object has an exact set of keys.
1690
+
1691
+ A value that a Host derives from others is not in a record, and the target
1692
+ derives its own. The format never sees the source's stored copies, so each
1693
+ Host's export builder checks them against these rules and refuses to build an
1694
+ export where one differs:
1695
+ - an intent's FIFO key, K4 `agentKey(domain, execution)`, from the target's
1696
+ own tenant or scope and the device and Agent of the frozen input;
1697
+ - the execution input of each earlier generation (`input` with that
1698
+ generation's task id), and K4 `intent.execution` (`input` without
1699
+ `taskId`), which hold while K4 runs without its memory option, as K8 does;
1700
+ - K4 `applied`: the current task id exactly when the intent `succeeded`;
1701
+ - a K4 occurrence's wake key and slot (K4 `routineWakeKey`). Each occurrence
1702
+ has exactly one slot on both Hosts, so the format has no slot section;
1703
+ - an occurrence's intent id (K4 `occurrenceIntentKey`), and K4 `attempts`,
1704
+ which `switchAttempts` derives for both Hosts.
1705
+
1706
+ An intent carries the K4 execution of each earlier generation (submission,
1707
+ start, attempt, terminal and message receipt), because K4 compacts an intent
1708
+ only with the execution of every generation. A message for an earlier task is
1709
+ answered from its execution: by its receipt, or else `stale_generation`.
1710
+ Nothing relies on a replay after the switch getting `accepted`: the target's
1711
+ SDK passes an Agent message to the Host only when its own stores hold the
1712
+ device's task and offer binding, which this export does not carry.
1713
+
1714
+ The format refuses, with `SwitchExportError` and a `reason`:
1715
+ - the source's owner records (L `topology`, and L `hostIntents`, whose handler
1716
+ each intent carries);
1717
+ - a K4 message receipt, of the current generation or an earlier one, that is
1718
+ not the K8 accepted reply of the same task id, or a reply with no receipt
1719
+ (`receipt_mismatch`);
1720
+ - a record that names one the export does not hold (`reference`): an
1721
+ occurrence intent (K4's `occurrence:<sha-256>` key) or Host job outbox row
1722
+ without its occurrence, an occurrence without its routine, an occurrence key
1723
+ that is not K4's hash of its routine slot and trigger, or a task id that is
1724
+ not `hash([key, generation])`;
1725
+ - state that K4 cannot produce (`invalid`): a retry policy outside K4's
1726
+ `validateRetry` bounds, on an intent or a routine definition; a generation at
1727
+ or past `maxAttempts`; a `reserved` intent past generation 0 or with
1728
+ anything from a submission; an earlier generation without its terminal and
1729
+ attempt, or that was not begun; an occurrence that does not match its
1730
+ routine's run kind (a Host job routine's occurrence has a job, is never
1731
+ promoted, since L runs K4 with `hostJobExecution: 'fail'` and H concludes a
1732
+ job result with an execution `failed`, and has a pending job exactly while it
1733
+ is open; a hook routine's has no job); a routine
1734
+ or occurrence ordinal that is not its position; and two occurrences of one
1735
+ slot (`duplicate`);
1736
+ - an execution routine (`execution_routine`): a K8 domain holds only Turn and
1737
+ Host intents (#954), L refuses execution routines and H refuses them at
1738
+ create, and K8 Bot routines are occurrence hooks;
1739
+ - a live Bot on a device the export does not move;
1740
+ - open work: an open Turn or input batch, an intent with no conclusion, or a
1741
+ card call in flight;
1742
+ - a pending Agent home write that is `sent` or has a `retryAt`, because it may
1743
+ have reached the device. An unsent one moves and is sent by the new owner;
1744
+ - a pending projection (`projection_pending`): H's receiver deduplicates by
1745
+ `(scope, id)`, and L does not record whether it was sent (H raises `tries`
1746
+ before the send), so the source flushes its projections first;
1747
+ - rows out of identity order, a repeated identity or ordinal, a key outside the
1748
+ format, malformed fields, a value that is not JSON by K4's `validateJson`
1749
+ (`NaN`, `undefined`, a class instance, checked before the seal clones the
1750
+ content), and a manifest that does not match the content.
1751
+
1752
+ A channel delivery moves under its id,
1753
+ `hash([taskId, messageId, routeKey, nonce?])`, which names no Host domain, so
1754
+ the target's readback or resend of a `sending` or `unknown` delivery uses the
1755
+ source's idempotency key. Whether a platform honors that key is its adapter's
1756
+ concern (`docs/host-im-adapter.md`); the switch does not change it.
1757
+
1758
+ This entry has no I/O. L's export, import and commit are in "Owner switch on L";
1759
+ H's are in the hosted example README, "Owner switch export (#975)" and "Owner switch
1760
+ import (#975)".
1761
+
1762
+ ### Second-device placement and device wait
1763
+
1764
+ One embedded server and one Host ledger can serve Bots on two enrolled
1765
+ devices. Supply `BotOptions.models` with Host-owned templates for each device:
1766
+
1767
+ ```ts
1768
+ const models = {
1769
+ local: localExecution,
1770
+ remote: { ...remoteExecution, deviceId: enrolledSecondDeviceId },
1771
+ };
1772
+ ```
1773
+
1774
+ A `create_bot` action selects `model: 'remote'`. The Host copies that
1775
+ execution template's device into the Bot profile. A model update keeps the
1776
+ Bot's device. This is creation placement, not home migration. A changed
1777
+ `remote` template, passed to `setModels` or at a restart, is re-projected onto
1778
+ each Bot of that model on its own device; it does not move a Bot either.
1779
+ Install `createBotPersonaProjection()` on both daemons. Wait for exact persona
1780
+ readback before dispatch. Device B needs SDK daemon and runtime code, with
1781
+ its own credential store and Agent homes. It needs no collaboration Host.
1782
+
1783
+ Supply `server.machines.list` for wait display. A delivered, unclaimed offer
1784
+ shows `waiting_device` only when that device's presence has expired. Persona
1785
+ and FIFO waits remain queued. Missing or failed discovery, including the
1786
+ one-second I/O bound, supplies no new offline fact. Presence does not control
1787
+ dispatch or verdicts. K4 keeps the original five-minute deadline. Reconnect
1788
+ can claim the same frozen task. Expiry cancels and reads the attempt before
1789
+ reporting `expired` once to A. A claim race still needs terminal evidence.
1790
+
1791
+ See [Second device and relay contract](SECOND-DEVICE.md). Its two-process
1792
+ Topology L relay is a contract only. The synthetic two-daemon test proves
1793
+ the embedded-server path. Hosted `submitAgentExecution`, two physical
1794
+ computers, two Host processes, and paid Pi behavior remain outside that proof.
1795
+
1796
+ ## Input coalescing
1797
+
1798
+ This section covers slice I1 of the Octop plan for issue #551.
1799
+ Input coalescing is an optional Host policy. It runs before K4 enqueue.
1800
+ K4, the SDK, and the wire do not change.
1801
+
1802
+ `BotOptions.coalesce` turns it on. Without it, `input` makes the same state
1803
+ change as before: one Turn, one K4 intent, and one execution for each input.
1804
+ A field that you do not give takes its default. Construction refuses a value
1805
+ that is not an integer or is out of range.
1806
+
1807
+ | Field | Default | Range |
1808
+ | --- | --- | --- |
1809
+ | `windowMs` | 10 000 | 1 000 to 60 000 |
1810
+ | `maxItems` | 8 | 2 to 16 |
1811
+ | `maxBytes` | 8 192 | 1 024 to `contextMaxBytes / 4` |
1812
+
1813
+ A Bot is busy when it has a Turn that is not concluded and not blocked.
1814
+ An input to an idle Bot seals at once as a one-input batch. Its Turn id,
1815
+ Request, intent key, and frozen instruction are the same as without the policy.
1816
+ An input to a busy Bot opens a batch or joins the open batch of that Bot.
1817
+ A Bot has at most one open batch. Inputs join one batch only when the Bot,
1818
+ conversation, sender principal id, authority, Bot revision, and Bot model are
1819
+ the same. In this example, each Bot has one 1:1 conversation, so the Bot id
1820
+ also identifies the conversation. Room input never coalesces.
1821
+
1822
+ A sealed batch becomes one `user` Turn. Its id is the id of the first input.
1823
+ `input` returns this id for each member. The K4 intent key is this Turn id, so
1824
+ task identity, FIFO order, generation, and cancel readback do not change. The
1825
+ batch Turn is the budget root. Continuation and delegation budgets count once
1826
+ for the whole batch, not once for each input. Neither the batch nor its Turn
1827
+ changes after the seal. The Host never changes an enqueued intent.
1828
+
1829
+ A one-input batch keeps the raw text as its Request. A batch with more inputs
1830
+ has one notice line, then each input in arrival order. Each input is framed
1831
+ once as raw UTF-8, with the frame of Cross-Bot replies. The metadata line holds
1832
+ `inputId` and `receivedAt`. The Host renders the merged Request before each
1833
+ join. If it is larger than `maxBytes`, the Host seals the batch and opens a new
1834
+ batch for the input. So a merged Request always fits the ContextPack budget.
1835
+ A long single input stays alone and unframed. An input over the ContextPack
1836
+ budget blocks with a visible reason, as before.
1837
+
1838
+ | Seal reason | Condition |
1839
+ | --- | --- |
1840
+ | `idle` | The Bot is idle. |
1841
+ | `window` | `windowMs` passed after the first input. Later inputs do not extend it. |
1842
+ | `items` | The batch has `maxItems` inputs. |
1843
+ | `bytes` | The next input makes the merged Request larger than `maxBytes`. |
1844
+ | `boundary` | Another new Turn of this Bot arrives. |
1845
+ | `key_changed` | The sender, authority, or Bot configuration changed. |
1846
+ | `cancel` | `cancelTurn` names the batch or a member input. |
1847
+ | `policy_off` | The Host restarted without `coalesce`. |
1848
+ | `archived` | The Bot is archived. |
1849
+
1850
+ Every other new Turn of the Bot seals its open batch first: `answer`,
1851
+ `action_result`, `routine`, `room_slot`, `bot_request`, `bot_reply`, and
1852
+ `continuation`. So the queue keeps arrival order. A replayed Turn does not
1853
+ seal. The seal check runs at the start of each Host sync and before each new
1854
+ input. `recover()` runs a sync first, so a due batch seals after a restart.
1855
+
1856
+ `cancelTurn` takes a batch id or a member input id. It cancels the whole batch.
1857
+ A replay of `input` with the same key and text returns the batch Turn id and
1858
+ does not join again. A replay with a changed text throws
1859
+ `Input identity conflict`. Each input has a durable record in
1860
+ `snapshot().inputs` with its `batchId`. `snapshot().inputBatches` holds the
1861
+ batches. The `bot-turn:<id>` projection carries `inputIds` in arrival order.
1862
+ Show the one reply once, and mark each member message from `inputIds`.
1863
+
1864
+ From the second input, a reply can wait up to `windowMs` plus the running
1865
+ execution. A batch Turn freezes its ContextPack at enqueue, as every waiting
1866
+ Turn does. The Host does not read message text for meaning, so a later input
1867
+ such as "never mind" does not withdraw an earlier input. The model reads all
1868
+ inputs in order and answers them together.
1869
+
1870
+ This example does not yet arm a timer at the window end, or publish
1871
+ `input-batch` projections (slice I2). Until then, a batch of a busy Bot seals
1872
+ at the next Host call or when the Bot becomes idle.
1873
+
1874
+ ## User input priority (#1229)
1875
+
1876
+ The K4 FIFO stays one queue per `(tenant, deviceId, agentId)`, ordered by
1877
+ the ledger's `sequence` (`docs/host-execution-core.md` §3). The reference Host
1878
+ adds one explicit rule on top of it. A **user-source** intent goes ahead of
1879
+ the queued, never-submitted `routine` and `bot_request` intents of the same
1880
+ Agent FIFO. "User-source" is the K4 `source: 'user'`: an owner input, and
1881
+ an `answer` Turn. The rule runs in the same ledger transaction that enqueues
1882
+ the user intent, so it is durable and survives a restart.
1883
+
1884
+ - Only intents with `phase: 'queued'` and `attempts: 0` move. A submitted or
1885
+ in-flight execution keeps its `sequence`, its `taskId` and its generation,
1886
+ and a cancel is not issued to make room.
1887
+ - The user intents and the autonomous intents keep their own arrival order.
1888
+ A self continuation, an `action_result` or a Bot reply keeps its position.
1889
+ - `setBotAutonomy` and the observe mode never reorder anything.
1890
+ - A standalone K4 reader sees a plain ledger: the order is just `sequence`
1891
+ values. No memory state and no second queue.
1892
+
1893
+ The Host also reserves **one slot per device** for user work. The limit is
1894
+ `BotOptions.deviceConcurrency` (default 8, the SDK daemon's
1895
+ `maxConcurrentTasks` default). An intent occupies a slot once it is submitted
1896
+ or has attempt evidence. Autonomous work may fill `limit - 1` slots;
1897
+ user-source work may fill all of them. A limit of 1 has no spare slot, so the
1898
+ reservation is off there. A refused begin stays queued and is retried when a
1899
+ slot frees; a submitted execution is never cancelled.
1900
+
1901
+ ```ts
1902
+ const bot = new BotCollaboration(server, ledger, { ...options, deviceConcurrency: 8 });
1903
+ ```
1904
+
1905
+ The rule has no effect on the SDK wire, the protocol or the K4 FIFO contract.
1906
+ It changes only the `sequence` of intents that never reached the SDK.
1907
+
1908
+ `coalesce` is a policy before enqueue, so an open batch has no intent yet.
1909
+ A batch seals when its Bot is idle (`idle`) or at its other seal reasons. A
1910
+ queued `bot_request` keeps the Bot busy, so with coalescing on, an open batch
1911
+ waits behind that work and its Turn joins the FIFO after the seal. Without
1912
+ coalescing, the user input becomes the next submitted intent. A Host that
1913
+ needs the strict order with coalescing must seal its batch sooner or leave
1914
+ coalescing off. This is the remaining interaction of #1229 item 1.
1915
+
1916
+ ## Inbound disposition (#1229)
1917
+
1918
+ Every inbound human message gets one deterministic destination, derived from
1919
+ the rows the Host already writes. There is no second disposition table:
1920
+ `inboundDispositions()` reads the inbound, input-batch and Turn rows.
1921
+
1922
+ | Destination | Meaning |
1923
+ | --- | --- |
1924
+ | `filtered(code)` | Refused before a Turn: `unverified_sender` or `not_owner`. The audit row stays. |
1925
+ | `coalesced(turnId)` | In the Turn `turnId`, including a merged input whose batch is still open. |
1926
+ | `answered(turnId)` | The Turn succeeded. |
1927
+ | `failed(turnId)` | The Turn failed, expired or was superseded. |
1928
+ | `cancelled(turnId)` | The owner cancelled the Turn or its batch. |
1929
+
1930
+ A 1:1 input names the batch Turn that answers it. A room input names its round
1931
+ id; the round's seat Turns decide the destination. A recorded message whose
1932
+ Turn was retained away reads `failed`, never nothing, so the Host UI cannot
1933
+ show a message with no destination.
1934
+
1935
+ ```ts
1936
+ const rows = bot.inboundDispositions(); // oldest first, from the ledger
1937
+ ```
1938
+
1939
+ Each transition is published once as
1940
+ `inbound:<id>:<destination>:<turnId>` (or `inbound:<id>:filtered:<code>`).
1941
+ The id names the destination, so a projection value never changes. The rows
1942
+ are Host UI history: never in a ContextPack and never on the wire.
1943
+
1944
+ `echo`, a direct bot message (`bot_audit`) and a group bot message
1945
+ (`bot_background`) keep their delivery, audit and round rows; this projection
1946
+ covers every inbound human message.
1947
+
1948
+ ## IM channel input
1949
+
1950
+ This section covers slices M2 and M3 of the Octop plan for issue #552.
1951
+ The rules are in the [Host IM adapter guide](../../docs/host-im-adapter.md).
1952
+ A channel adapter takes the sender from authenticated platform data and gives
1953
+ a `Principal` with an `id` and the `kind` `human` or `bot`. Give principal ids
1954
+ a namespace that no Bot id uses, for example `im:<platform user id>`. Room
1955
+ history shows both kinds of id in `from`. The adapter maps the platform chat
1956
+ to a Bot id (`direct`) or a room id (`group`). It maps mention entities to Bot
1957
+ ids.
1958
+
1959
+ `receive(message)` classifies one `InboundMessage` with `classifyInbound`, in
1960
+ the order of the guide's §3. The first match wins.
1961
+
1962
+ | Sender and conversation | Result |
1963
+ | --- | --- |
1964
+ | No verified principal | `unverified_sender`. Audit only. |
1965
+ | Own bot account, listed in `channel.self` | `echo`. Exact delivery reconciliation only. No Turn or seat. |
1966
+ | Bot, 1:1 | `bot_audit`. Audit only. No Turn. |
1967
+ | Bot, group | `bot_background`. A room message without a seat, also with mention entities. |
1968
+ | Owner, 1:1 | `owner_input`. `input` with the principal. |
1969
+ | Other human, 1:1 | `not_owner`. Audit only. |
1970
+ | Human, group | `room_input`. `roomInput` with the principal. Mention entities select seats. |
1971
+
1972
+ The input key is `inboundKey(message)`, the hash of channel, conversation id,
1973
+ and platform message id. A redelivered event returns the same id. The Host
1974
+ never scans text for mentions.
1975
+
1976
+ `BotOptions.owner` is the owner principal id. The default is `owner`. Only the
1977
+ human principal with this id passes the owner check. These owner APIs take an
1978
+ optional last `principal`: `input`, `answer`, `decide`, `cancelTurn`,
1979
+ `cancelDelegation`, and `abandonDelegation`. The check runs first. Without a
1980
+ principal argument, the call acts as the owner, so the Host must authenticate
1981
+ the caller. A given `undefined`, `null`, or malformed principal is refused with
1982
+ `unverified_sender`. Any other principal that is not the owner is refused with
1983
+ `not_owner`. Each refusal writes an audit row before the call rejects. For an
1984
+ IM action, pass the principal that the adapter verified. Accept an approval
1985
+ only from a verified button callback, never from a text command.
1986
+
1987
+ `roomInput` takes the same optional `principal`, with the same
1988
+ `unverified_sender` rule. Any verified human can post. The room message
1989
+ records the principal id in `from`, and a seat request records it in
1990
+ `requestFrom`. Without a principal, `from` is `user`. A bot principal's
1991
+ mentions select no seat. The delivery owner APIs below use the same principal rule.
1992
+
1993
+ ### Delivery outbox
1994
+
1995
+ Set `BotOptions.channel` to enable the Host outbox:
1996
+
1997
+ ```ts
1998
+ channel: {
1999
+ port: channelPort,
2000
+ self: { slack: ['im:our-bot-account'] },
2001
+ sendTimeoutMs: 15_000,
2002
+ }
2003
+ ```
2004
+
2005
+ `ChannelPort` sends final text and can read back a delivery id. Its `send`
2006
+ result is `accepted` with a platform message id, or an explicit `rejected`
2007
+ result with a code, retryability and optional `retryAfterMs`. The port owns
2008
+ platform authentication and keeps bot tokens in the Host credential broker.
2009
+ The Host never puts the port or a channel secret in a Bot toolset.
2010
+
2011
+ Add a `replyRoute` to an authenticated `InboundMessage`. Its channel must
2012
+ match the message, and its `inboundId` must equal `platformMessageId`.
2013
+ The Host saves it with input admission, before it can process a reply.
2014
+ An input batch uses its newest member's route. The route reference in a
2015
+ Delivery is the Host's `inboundKey`; the port receives the original platform
2016
+ inbound id and credential. Reply tokens stay in Host-only ledger state.
2017
+ Do not publish or log the raw ledger or `snapshot()` as an IM view.
2018
+
2019
+ Push is off by default. These owner APIs operate on a direct Bot conversation
2020
+ or a group room:
2021
+
2022
+ ```ts
2023
+ const routeId = await bot.enablePushRoute(
2024
+ { kind: 'direct', id: 'main' }, 'slack', 'platform-conversation-id', principal,
2025
+ );
2026
+ await bot.revokePushRoute(routeId, principal);
2027
+ const newDeliveryId = await bot.resendDelivery(unknownDeliveryId, principal);
2028
+ ```
2029
+
2030
+ Enabling a replacement revokes the old push route of that conversation.
2031
+ A push target is a non-secret platform target, never a reply credential.
2032
+ Only the owner can enable, revoke or resend. As with the other owner APIs,
2033
+ an omitted principal means that the Host already authenticated the owner.
2034
+ A manual resend requires a usable reply route or an active push route. It
2035
+ creates a new id and preserves the old unknown row. It can show a duplicate
2036
+ message if the original send arrived.
2037
+
2038
+ `consumeMessage` records first acceptance and its pending Delivery in the
2039
+ same SQLite transaction. Exact redelivery creates no second row. Applied
2040
+ room posts, confirmation summaries and questions also create deliveries in
2041
+ their acceptance transaction. Drafts and typed activity create no delivery.
2042
+ Routine output uses only its own conversation's opted-in push route.
2043
+ Without a route, the Host keeps the content in its UI and audits
2044
+ `no_push_route` or `reply_route_expired`.
2045
+
2046
+ Each process pass calls `flushDeliveries`. It commits `sending` and an
2047
+ attempt increment before calling the port. The default business deadline is
2048
+ 15 seconds. A timeout, exception or lost connection gives `unknown` and no
2049
+ automatic resend. An explicit retryable rejection waits for the larger of
2050
+ Retry-After and exponential backoff. At most three sends run. A required
2051
+ wait above 60 seconds is final rejection; it is never shortened.
2052
+
2053
+ Call `recover()` before serving work after restart. It maps persisted
2054
+ `sending` to `unknown`. A port's optional readback can confirm `accepted`,
2055
+ prove `absent`, or return `unsupported`. Only proven absence permits a
2056
+ bounded retry. Readback must complete within the adapter's own I/O budget.
2057
+ Unknown rows have no automatic retry timer. A Host drain can check readback;
2058
+ an authenticated echo can reconcile them without a drain.
2059
+
2060
+ An echo must come from a verified bot principal listed in `channel.self`
2061
+ for that channel. Match its conversation and either `deliveryId` from native
2062
+ platform data or an already-known `platformMessageId`. Never take an echo id
2063
+ from message text. A different bot, human, channel or conversation cannot
2064
+ confirm a delivery. Echoes can arrive while `send` is pending; they do not
2065
+ wait behind the send operation.
2066
+
2067
+ Reply tokens are removed at expiry. They are also removed after the root
2068
+ has no open Turn or seat and no pending/sending delivery on that route.
2069
+ Metadata and delivery audit remain. All delivery state is Host state; it
2070
+ does not change K4, K7, the SDK message disposition or wire messages.
2071
+
2072
+ The ledger is a single-owner reference. Use one Host instance per tenant.
2073
+ The reusable fake-channel test factory is `channelContract` in
2074
+ `src/channel-contract.ts`. Its harness lets downstream adapters run the same
2075
+ Host delivery cases with controlled platform results. A real platform adapter
2076
+ still needs the downstream acceptance in M4.