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