@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
|
@@ -0,0 +1,353 @@
|
|
|
1
|
+
import type { BotTurnOutcome } from '@byok-sdk/protocol';
|
|
2
|
+
import { type Json, type Rejection, type Turn, type TurnsState, type Verdict } from './turn.js';
|
|
3
|
+
import { type AutonomyGate } from './autonomy.js';
|
|
4
|
+
/**
|
|
5
|
+
* Cross-Bot delegation as pure rules (#739 D1): budget units, the batch join, verdicts, cancel arbitration and
|
|
6
|
+
* the Cross-Bot Request. Each function changes only the slice that the caller gives, does no I/O and takes `now`
|
|
7
|
+
* from the caller. The Host gives the K4 intent facts of each Turn, stores the slice and sends each emitted row.
|
|
8
|
+
*/
|
|
9
|
+
/**
|
|
10
|
+
* Frozen in the arbitration transaction (§8.8). `delivered` turns true after core.cancel. No `reason` means a user cancel.
|
|
11
|
+
* `target_archived` and `target_suspended` (#1319) are the Host cancel when the target Bot is archived or suspended (§8.4).
|
|
12
|
+
* Their verdict is `refused`.
|
|
13
|
+
*/
|
|
14
|
+
export interface DelegationCancel {
|
|
15
|
+
requestedAt: number;
|
|
16
|
+
targetTurnId: string;
|
|
17
|
+
delivered: boolean;
|
|
18
|
+
reason?: 'main_bot_cancelled' | 'target_archived' | 'target_suspended';
|
|
19
|
+
}
|
|
20
|
+
export interface Delegation {
|
|
21
|
+
id: string;
|
|
22
|
+
root: string;
|
|
23
|
+
fromBotId: string;
|
|
24
|
+
fromTurnId: string;
|
|
25
|
+
fromTaskId: string;
|
|
26
|
+
index: number;
|
|
27
|
+
toBotId: string;
|
|
28
|
+
toAgentRef?: {
|
|
29
|
+
agentId: string;
|
|
30
|
+
profileRevision: string;
|
|
31
|
+
};
|
|
32
|
+
toDeviceId?: string;
|
|
33
|
+
request: string;
|
|
34
|
+
hop: number;
|
|
35
|
+
requestTurnId?: string;
|
|
36
|
+
chainTurnIds: string[];
|
|
37
|
+
batch: string;
|
|
38
|
+
status: 'queued' | 'waiting_device' | 'running' | 'reply_pending' | 'reply_held' | 'uncertain' | 'resolved';
|
|
39
|
+
revision: number;
|
|
40
|
+
nextCheckAt?: number;
|
|
41
|
+
checks?: number;
|
|
42
|
+
pendingSince?: number;
|
|
43
|
+
verdict?: Verdict;
|
|
44
|
+
reason?: string;
|
|
45
|
+
reply?: string;
|
|
46
|
+
continuationRefused?: true;
|
|
47
|
+
partial?: true;
|
|
48
|
+
replyTurnId?: string;
|
|
49
|
+
uncertainSince?: number;
|
|
50
|
+
resolvedAt?: number;
|
|
51
|
+
cancel?: DelegationCancel;
|
|
52
|
+
/** First observed claim of the current chain Turn (§8.3). */
|
|
53
|
+
claimed?: {
|
|
54
|
+
turnId: string;
|
|
55
|
+
at: number;
|
|
56
|
+
};
|
|
57
|
+
/** A chain Turn still open at the verdict. Its later terminal goes to audit only. */
|
|
58
|
+
lateTurnId?: string;
|
|
59
|
+
/** The verdict has no reply Turn because the initiator is archived (§8.5) or suspended (#1319). */
|
|
60
|
+
undelivered?: 'initiator_archived' | 'initiator_suspended';
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* One A outcome. `slots` are the prepaid A reply units of this batch.
|
|
64
|
+
* `released` is set at the first report, or when every accepted delegation is uncertain (§3.5).
|
|
65
|
+
*/
|
|
66
|
+
export interface Batch {
|
|
67
|
+
id: string;
|
|
68
|
+
delegationIds: string[];
|
|
69
|
+
slots: string[];
|
|
70
|
+
released?: true;
|
|
71
|
+
}
|
|
72
|
+
/** `turnId` is the Turn that holds the unit. A free A slot has none. */
|
|
73
|
+
export interface Unit {
|
|
74
|
+
id: string;
|
|
75
|
+
root: string;
|
|
76
|
+
state: 'reserved' | 'spent' | 'released';
|
|
77
|
+
turnId?: string;
|
|
78
|
+
}
|
|
79
|
+
/**
|
|
80
|
+
* The receipt of one accepted Agent message, written while the Turn still runs. A Host shows a reply only when the intent of
|
|
81
|
+
* `turnId` concluded `succeeded` with this task id (#1762): any other reply was accepted, but its Turn outcome was not applied.
|
|
82
|
+
*/
|
|
83
|
+
export interface AcceptedReply {
|
|
84
|
+
/** The intent key. For a Bot Turn, it is the Turn id. */
|
|
85
|
+
turnId: string;
|
|
86
|
+
messageId: string;
|
|
87
|
+
contentHash: string;
|
|
88
|
+
contentType: string;
|
|
89
|
+
acceptedAt: number;
|
|
90
|
+
/** Stored only for delegation chain Turns. */
|
|
91
|
+
body?: string;
|
|
92
|
+
}
|
|
93
|
+
/** The Bot fields that delegation reads. */
|
|
94
|
+
export interface DelegationBot {
|
|
95
|
+
readonly id: string;
|
|
96
|
+
readonly name: string;
|
|
97
|
+
readonly archived: boolean;
|
|
98
|
+
readonly participation?: 'suspended';
|
|
99
|
+
readonly execution: {
|
|
100
|
+
readonly deviceId: string;
|
|
101
|
+
readonly payload: {
|
|
102
|
+
readonly agentRef: {
|
|
103
|
+
readonly agentId: string;
|
|
104
|
+
readonly profileRevision: string;
|
|
105
|
+
};
|
|
106
|
+
};
|
|
107
|
+
};
|
|
108
|
+
}
|
|
109
|
+
/** The collaboration rows that delegation reads and changes. */
|
|
110
|
+
export interface DelegationState extends TurnsState {
|
|
111
|
+
team: {
|
|
112
|
+
bots: Readonly<Record<string, DelegationBot>>;
|
|
113
|
+
};
|
|
114
|
+
delegations: Record<string, Delegation>;
|
|
115
|
+
batches: Record<string, Batch>;
|
|
116
|
+
units: Record<string, Unit>;
|
|
117
|
+
replies: Record<string, AcceptedReply>;
|
|
118
|
+
rejected: Rejection[];
|
|
119
|
+
audit: string[];
|
|
120
|
+
}
|
|
121
|
+
/** The rows that the Cross-Bot Request and the ContextPack delegation views read. */
|
|
122
|
+
export interface DelegationView {
|
|
123
|
+
team: {
|
|
124
|
+
bots: Readonly<Record<string, {
|
|
125
|
+
readonly name: string;
|
|
126
|
+
}>>;
|
|
127
|
+
};
|
|
128
|
+
delegations: Record<string, Delegation>;
|
|
129
|
+
replies: Record<string, AcceptedReply>;
|
|
130
|
+
}
|
|
131
|
+
/** The same values as the K4 intent `Conclusion`. Rules do not import K4 types. */
|
|
132
|
+
export type Conclusion = 'succeeded' | 'failed' | 'declined' | 'cancelled' | 'expired' | 'superseded';
|
|
133
|
+
/** The current K4 intent of one Turn. */
|
|
134
|
+
export interface IntentFact {
|
|
135
|
+
taskId: string;
|
|
136
|
+
conclusion?: Conclusion;
|
|
137
|
+
cancelReason?: 'expired' | 'cancelled';
|
|
138
|
+
}
|
|
139
|
+
/** K4 facts by Turn id. A Turn with no K4 intent has no facts. */
|
|
140
|
+
export interface IntentFacts {
|
|
141
|
+
intent(turnId: string): IntentFact | undefined;
|
|
142
|
+
/** An execution of any generation started, or has a terminal that is not a decline. */
|
|
143
|
+
started(turnId: string): boolean;
|
|
144
|
+
/** The decline code of the current execution's terminal, if it is a decline. */
|
|
145
|
+
declineCode(turnId: string): string | undefined;
|
|
146
|
+
/** The device of a delivered offer of an inflight intent that no device has claimed yet. */
|
|
147
|
+
offeredTo(turnId: string): string | undefined;
|
|
148
|
+
}
|
|
149
|
+
/** Host cap on a delegated Bot's accepted reply (Q8). consumeMessage checks it too. */
|
|
150
|
+
export declare const BOT_REPLY_MAX_BYTES = 8192;
|
|
151
|
+
/** Header, end line and line breaks of one framed block. */
|
|
152
|
+
export declare const FRAME_MAX_BYTES = 96;
|
|
153
|
+
export declare const ROOT_BOT_BUDGET = 12;
|
|
154
|
+
export declare const HOP_LIMIT = 4;
|
|
155
|
+
export declare const DEFAULT_INSTRUCTION_MAX_BYTES = 65536;
|
|
156
|
+
/** Roster entry: 64-byte id, name <= 40 and role <= 80 code points at 6 bytes each, keys. */
|
|
157
|
+
export declare const ROSTER_ENTRY_MAX_BYTES = 848;
|
|
158
|
+
/** historyWindow with its notice, and the keys of truncated arrays. */
|
|
159
|
+
export declare const CONTEXT_FIXED_MAX_BYTES = 1024;
|
|
160
|
+
export declare const REPLY_REQUEST_MAX_BYTES: number;
|
|
161
|
+
export declare const BOT_REQUEST_MAX_BYTES: number;
|
|
162
|
+
export declare const REPLY_RETRY_MAX_MS = 60000;
|
|
163
|
+
export declare const REPLY_UNCERTAIN_AFTER_MS: number;
|
|
164
|
+
/** §8.3 (Q9): a cancel with no terminal, and a claimed attempt with no terminal, show `uncertain`. */
|
|
165
|
+
export declare const DEFAULT_CANCEL_GRACE_MS = 60000;
|
|
166
|
+
export interface DelegationTimers {
|
|
167
|
+
cancelGraceMs: number;
|
|
168
|
+
uncertainAfterMs: number;
|
|
169
|
+
}
|
|
170
|
+
/** §8.8: the Main Bot cancel enum lists at most this many open delegations, newest first. */
|
|
171
|
+
export declare const OPEN_DELEGATIONS_MAX_ITEMS = 24;
|
|
172
|
+
/** Listed entry: three 64-byte ids, status, request <= 80 code points at 6 bytes each, keys. */
|
|
173
|
+
export declare const OPEN_DELEGATION_ENTRY_MAX_BYTES = 768;
|
|
174
|
+
/** The listed entries, the omitted count and its notice, and the keys. */
|
|
175
|
+
export declare const OPEN_DELEGATIONS_MAX_BYTES: number;
|
|
176
|
+
export declare function isCrossBot(turn: Turn): boolean;
|
|
177
|
+
/** UTF-8 bytes of the instruction parts around the Request and ContextPack sections. */
|
|
178
|
+
export declare function instructionOverhead(prompt: string): number;
|
|
179
|
+
/** Construction check (§3.7): P + max(R_reply, R_req) + F_max. A Main Bot reply Turn also lists open delegations (§8.8). */
|
|
180
|
+
export declare function minimumInstructionBytes(prompt: string): number;
|
|
181
|
+
export type Publish = (id: string, value: Json) => void;
|
|
182
|
+
export declare function claimUnit(state: DelegationState, id: string | undefined): void;
|
|
183
|
+
export declare function releaseUnit(state: DelegationState, id: string | undefined): void;
|
|
184
|
+
/** Set the verdict once, then deliver it through the batch join. */
|
|
185
|
+
export declare function resolveDelegation(state: DelegationState, d: Delegation, verdict: Verdict, now: number, emit: Publish, reason?: string, reply?: string): boolean;
|
|
186
|
+
/** Units that a batch with `n` accepted cross-Bot items prepays: n B units and max(n, 1) A reply slots (Q10). */
|
|
187
|
+
export declare function reserveUnits(n: number): number;
|
|
188
|
+
/**
|
|
189
|
+
* Apply every delegate item of one outcome (§3.1). Self items keep the K8a
|
|
190
|
+
* continuation path. The accepted cross-Bot items form one batch (§3.5).
|
|
191
|
+
* #1229: an observing Bot records a cross-Bot item as would-do: no delegation row, no bot_request Turn, no budget unit.
|
|
192
|
+
*/
|
|
193
|
+
export declare function applyDelegate(state: DelegationState, turn: Turn, taskId: string, outcome: BotTurnOutcome, seat: boolean, now: number, emit: Publish, accept: (action: string, work: () => void) => void, gate: AutonomyGate): {
|
|
194
|
+
successor: boolean;
|
|
195
|
+
};
|
|
196
|
+
/** Claim (first observed start spends the unit), the claim time of a chain Turn, and queued -> running. */
|
|
197
|
+
export declare function observeStart(state: DelegationState, turn: Turn, now: number, emit: Publish): void;
|
|
198
|
+
/** Presence is display evidence only. It never controls submit, expiry, or a verdict. */
|
|
199
|
+
export declare function observeDevices(state: DelegationState, facts: IntentFacts, devices: ReadonlyMap<string, boolean>, emit: Publish): void;
|
|
200
|
+
/** The result of an owner cancel (#1405). `cancel_pending` and `already_settled` write nothing and send no cancel. */
|
|
201
|
+
export type CancelOutcome = 'cancelled' | 'cancel_pending' | 'already_settled';
|
|
202
|
+
export interface TurnCancelResult {
|
|
203
|
+
turnId: string;
|
|
204
|
+
result: CancelOutcome;
|
|
205
|
+
conclusion?: string;
|
|
206
|
+
}
|
|
207
|
+
export interface DelegationCancelResult {
|
|
208
|
+
delegationId: string;
|
|
209
|
+
result: CancelOutcome;
|
|
210
|
+
verdict?: Verdict;
|
|
211
|
+
}
|
|
212
|
+
/**
|
|
213
|
+
* `cancelTurn` refuses with `cancelDelegation`'s codes on a chain Turn, and `cancelDelegation` with `unknown_delegation` or with
|
|
214
|
+
* `not_cancellable` for a delegation whose state a cancel cannot act on: end a `reply_held` or `uncertain` one with
|
|
215
|
+
* `abandonDelegation` (#1405). `key` is the delegation id. A delegation is no intent key, so this is not a `HostIntentError`.
|
|
216
|
+
*/
|
|
217
|
+
export declare class DelegationError extends Error {
|
|
218
|
+
readonly key: string;
|
|
219
|
+
readonly code: 'unknown_delegation' | 'not_cancellable';
|
|
220
|
+
constructor(key: string, code: 'unknown_delegation' | 'not_cancellable', message: string);
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* A refused intent key. `cancelHostIntent` (#1320): `unknown_intent` for a key with no Host intent, or `not_host_intent` for a
|
|
224
|
+
* Bot Turn. `failStuckIntent` (#1405): `unknown_intent` for a key with no K4 intent, `already_settled`, or `not_stuck` for an
|
|
225
|
+
* intent whose terminal K8 did not refuse.
|
|
226
|
+
*/
|
|
227
|
+
export declare class HostIntentError extends Error {
|
|
228
|
+
readonly key: string;
|
|
229
|
+
readonly code: 'unknown_intent' | 'not_host_intent' | 'already_settled' | 'not_stuck';
|
|
230
|
+
constructor(key: string, code: 'unknown_intent' | 'not_host_intent' | 'already_settled' | 'not_stuck', message: string);
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* `cancelled`: the intent was not submitted and settled as `cancelled`. `cancel_pending`: the SDK cancel went out, and K4
|
|
234
|
+
* settles the intent at its terminal. `already_settled`: no cancel was sent; `conclusion` is the earlier one.
|
|
235
|
+
*/
|
|
236
|
+
export interface IntentCancelResult<C extends string> {
|
|
237
|
+
key: string;
|
|
238
|
+
result: CancelOutcome;
|
|
239
|
+
conclusion?: C;
|
|
240
|
+
}
|
|
241
|
+
/**
|
|
242
|
+
* The answer of a Host intent cancel that sends nothing, or `undefined` when the cancel goes to K4 (#1320). `intent` is the
|
|
243
|
+
* open or settled intent of a key that has a Host intent record, or `undefined`. Refuses a Bot Turn key and an unknown key.
|
|
244
|
+
*/
|
|
245
|
+
export declare function hostIntentCancelAnswer<C extends string>(key: string, turn: boolean, intent: {
|
|
246
|
+
conclusion?: C;
|
|
247
|
+
} | undefined): Omit<IntentCancelResult<C>, 'key'> | undefined;
|
|
248
|
+
/**
|
|
249
|
+
* The answer of a delegation cancel that writes nothing, or `undefined` when the cancel commits. Refuses before any write what
|
|
250
|
+
* `arbitrateCancel` would refuse, with a code.
|
|
251
|
+
*/
|
|
252
|
+
export declare function delegationCancelAnswer(state: DelegationState, id: string): Omit<DelegationCancelResult, 'delegationId'> | undefined;
|
|
253
|
+
/**
|
|
254
|
+
* The answer of a Turn cancel that writes nothing, or `undefined` when the cancel commits. It follows the `cancel_turn` rule:
|
|
255
|
+
* a chain Turn with no verdict is its delegation's cancel, an input names its batch, and an open batch commits its seal.
|
|
256
|
+
* A missing Turn commits, so the rule refuses it. `intents` holds the K4 intent of the Turn that the cancel targets.
|
|
257
|
+
*/
|
|
258
|
+
export declare function turnCancelAnswer(state: DelegationState & {
|
|
259
|
+
inputs?: Record<string, {
|
|
260
|
+
batchId: string;
|
|
261
|
+
}>;
|
|
262
|
+
inputBatches?: Record<string, {
|
|
263
|
+
id: string;
|
|
264
|
+
state: string;
|
|
265
|
+
}>;
|
|
266
|
+
}, intents: Pick<IntentFacts, 'intent'>, id: string): Omit<TurnCancelResult, 'turnId'> | undefined;
|
|
267
|
+
/** A delegation status that a cancel can act on (§8.8). The owner cancel refuses another one with a code before it commits (#1405). */
|
|
268
|
+
export declare function cancellable(status: Delegation['status']): boolean;
|
|
269
|
+
/**
|
|
270
|
+
* Open delegations that a Main Bot can cancel (§8.8): no verdict, no cancel yet,
|
|
271
|
+
* and a state that a cancel can act on. Newest first; the rest are only counted.
|
|
272
|
+
*/
|
|
273
|
+
export declare function openDelegations(state: Pick<DelegationView, 'delegations'>): {
|
|
274
|
+
items: Delegation[];
|
|
275
|
+
omitted: number;
|
|
276
|
+
};
|
|
277
|
+
/** ContextPack view of the cancel enum. The enum is never cut without this notice. */
|
|
278
|
+
export declare function openDelegationsContext(state: Pick<DelegationView, 'delegations'>): {
|
|
279
|
+
items: {
|
|
280
|
+
id: string;
|
|
281
|
+
from: string;
|
|
282
|
+
to: string;
|
|
283
|
+
status: "queued" | "reply_held" | "reply_pending" | "resolved" | "running" | "uncertain" | "waiting_device";
|
|
284
|
+
request: string;
|
|
285
|
+
}[];
|
|
286
|
+
omitted: number;
|
|
287
|
+
notice: string | null;
|
|
288
|
+
};
|
|
289
|
+
/**
|
|
290
|
+
* Arbitration transaction (§8.8). Freeze the cancel fact on the current chain
|
|
291
|
+
* Turn. That closes its first acceptance and blocks new successors. Without a
|
|
292
|
+
* K4 intent, close queue eligibility and set the verdict now. Returns true when
|
|
293
|
+
* core.cancel must still deliver the cancel. An archived or suspended target is
|
|
294
|
+
* cancelled in every open state (§8.4).
|
|
295
|
+
*/
|
|
296
|
+
export declare function arbitrateCancel(state: DelegationState, facts: Pick<IntentFacts, 'intent'>, d: Delegation, now: number, emit: Publish, reason?: DelegationCancel['reason']): boolean;
|
|
297
|
+
/** B chain end after a success terminal: the Host acceptance record is the body authority (§3.3). */
|
|
298
|
+
export declare function endChain(state: DelegationState, turn: Turn, taskId: string, proposedSelf: boolean, now: number, emit: Publish): void;
|
|
299
|
+
/**
|
|
300
|
+
* Units, claims, cancels, uncertain states, and verdicts of chain ends that did not succeed. Runs inside sync.
|
|
301
|
+
* A later generation reuses the spent unit; a decline terminal is not a run.
|
|
302
|
+
*/
|
|
303
|
+
export declare function settleDelegations(state: DelegationState, facts: IntentFacts, now: number, emit: Publish, timers?: DelegationTimers): void;
|
|
304
|
+
/** "End" (§8.3). An attempt that can still run gets a K4 cancel. Its later terminal goes to audit only. */
|
|
305
|
+
export declare function abandonDelegation(state: DelegationState, facts: Pick<IntentFacts, 'intent'>, d: Delegation, now: number, emit: Publish): boolean;
|
|
306
|
+
/** Next time a delegation timer can change state without other events. */
|
|
307
|
+
export declare function delegationDue(state: Pick<DelegationState, 'delegations'>, timers?: DelegationTimers): number[];
|
|
308
|
+
/** SDK readback for a reply_pending delegation without a Host record (§3.3). */
|
|
309
|
+
export declare function reconcileReply(state: DelegationState, d: Delegation, readback: {
|
|
310
|
+
disposition?: {
|
|
311
|
+
outcome: string;
|
|
312
|
+
};
|
|
313
|
+
} | undefined, now: number, emit: Publish, uncertainAfterMs?: number): void;
|
|
314
|
+
export declare function retryReply(state: DelegationState, d: Delegation, now: number, emit: Publish, uncertainAfterMs?: number): void;
|
|
315
|
+
/** The SDK reply readback that `reconcileReply` reads (`tasks.agentMessage`). */
|
|
316
|
+
export type ReplyReadback = {
|
|
317
|
+
disposition?: {
|
|
318
|
+
outcome: string;
|
|
319
|
+
};
|
|
320
|
+
} | undefined;
|
|
321
|
+
/**
|
|
322
|
+
* One reply check of a delegation's chain end (§3.10). `taskId` is the chain end's task when it has an intent. The check
|
|
323
|
+
* `failed` when the chain end has no intent, or when the SDK read threw.
|
|
324
|
+
*/
|
|
325
|
+
export type ReplyCheck = {
|
|
326
|
+
taskId?: string;
|
|
327
|
+
failed: true;
|
|
328
|
+
} | {
|
|
329
|
+
taskId: string;
|
|
330
|
+
failed: false;
|
|
331
|
+
readback: ReplyReadback;
|
|
332
|
+
};
|
|
333
|
+
/** A delegation whose reply check is due at `now`: it has no verdict, and its check time has come. */
|
|
334
|
+
export declare function replyCheckDue(d: Delegation, now: number): boolean;
|
|
335
|
+
/**
|
|
336
|
+
* The decision of one reply check (§3.10). A reply body that the Host holds answers the delegation; a failed read retries;
|
|
337
|
+
* otherwise the readback decides.
|
|
338
|
+
*/
|
|
339
|
+
export declare function checkReply(state: DelegationState, d: Delegation, check: ReplyCheck, now: number, emit: Publish, uncertainAfterMs?: number): void;
|
|
340
|
+
/** B's delegation block. It is metadata only: the request text stays in the Request section. */
|
|
341
|
+
export declare function delegationBlock(state: Pick<DelegationView, 'team' | 'delegations'>, turn: Turn): {
|
|
342
|
+
delegationId: string;
|
|
343
|
+
from: {
|
|
344
|
+
botId: string;
|
|
345
|
+
name: string;
|
|
346
|
+
};
|
|
347
|
+
hop: number;
|
|
348
|
+
};
|
|
349
|
+
/**
|
|
350
|
+
* Request section of a Cross-Bot Turn (§3.7). Request text and reply bodies
|
|
351
|
+
* appear once as raw UTF-8 in length-framed blocks, with no second JSON encoding.
|
|
352
|
+
*/
|
|
353
|
+
export declare function crossBotRequest(state: DelegationView, turn: Turn): string;
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
import type { Card } from './turn.js';
|
|
2
|
+
import type { CoalesceState } from './coalesce.js';
|
|
3
|
+
import type { Seat } from './rooms.js';
|
|
4
|
+
import { type DelegationState, type DelegationTimers } from './delegation.js';
|
|
5
|
+
/**
|
|
6
|
+
* The times when a Host sync has collaboration work to do (#793 S4): each open input batch's seal, each pending card's
|
|
7
|
+
* expiry, each unreleased seat's deadline, and the delegation times (`delegationDue`: reply checks, the cancel grace and
|
|
8
|
+
* the uncertain timer). L arms its timer with them; H stores their minimum as its scope's due time. Routine slots are K4's.
|
|
9
|
+
*/
|
|
10
|
+
export declare function collaborationDue(state: Pick<DelegationState, 'delegations'> & CoalesceState & {
|
|
11
|
+
readonly cards: Readonly<Record<string, Card>>;
|
|
12
|
+
readonly team: {
|
|
13
|
+
readonly seats: Readonly<Record<string, Seat>>;
|
|
14
|
+
};
|
|
15
|
+
}, timers?: DelegationTimers): number[];
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
/** Bound of one canonical metadata line in the Request section, asserted when the line is built. */
|
|
2
|
+
export declare const REPLY_META_MAX_BYTES = 2048;
|
|
3
|
+
/** One length-framed block of raw UTF-8: a header with the body size, one canonical metadata line, the body and an end line. */
|
|
4
|
+
export declare function frame(label: string, meta: Record<string, unknown>, body: string): string;
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import type { Card, Question } from './turn.js';
|
|
2
|
+
export declare const HISTORY_MAX_BYTES: number;
|
|
3
|
+
export declare const HISTORY_MAX_ITEMS = 100;
|
|
4
|
+
export interface HistoryWindow {
|
|
5
|
+
turnLimit: number;
|
|
6
|
+
maxBytes: number;
|
|
7
|
+
omittedMessages: number;
|
|
8
|
+
/** Room seats only. A Bot Turn counts its omitted turns in `history.omittedTurns`. */
|
|
9
|
+
omittedTurns?: number;
|
|
10
|
+
omittedCards: number;
|
|
11
|
+
omittedQuestions: number;
|
|
12
|
+
omittedPendingCards: number;
|
|
13
|
+
omittedPendingQuestions: number;
|
|
14
|
+
omittedRejections: number;
|
|
15
|
+
currentRequestBytes: number;
|
|
16
|
+
metadataOverBudget: boolean;
|
|
17
|
+
notice: string | null;
|
|
18
|
+
/** Cross-Bot Turns only: omitted team notes, rooms and routines. */
|
|
19
|
+
omittedBackground?: number;
|
|
20
|
+
}
|
|
21
|
+
export declare function historyWindow(kind: 'messages' | 'turns', omitted?: number, turnLimit?: number, maxBytes?: number): HistoryWindow;
|
|
22
|
+
export declare class CurrentRequestTooLargeError extends Error {
|
|
23
|
+
}
|
|
24
|
+
export declare const HISTORY_OMITTED_NOTICE = "Earlier history was omitted.";
|
|
25
|
+
/**
|
|
26
|
+
* Reserve the frozen Request bytes and `reserved` more, then trim copied history arrays only.
|
|
27
|
+
* `background` arrays (copies) are trimmed oldest first after history.
|
|
28
|
+
*/
|
|
29
|
+
export declare function fitHistory<T extends {
|
|
30
|
+
historyWindow: HistoryWindow;
|
|
31
|
+
rejectedActions: unknown[];
|
|
32
|
+
cards?: Card[];
|
|
33
|
+
questions?: Question[];
|
|
34
|
+
}>(context: T, history: unknown[], request: string, background?: unknown[][], reserved?: number): T;
|
|
@@ -0,0 +1,53 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The inbound disposition projection as pure rules (#1229 item 3). It reads the existing inbound, input-batch and Turn
|
|
3
|
+
* rows and returns one destination per recorded inbound human message. It writes nothing and keeps no disposition of its
|
|
4
|
+
* own, so the ledger stays the only authority.
|
|
5
|
+
*/
|
|
6
|
+
/** The five destinations of #1229 item 3. */
|
|
7
|
+
export type InboundDisposition = {
|
|
8
|
+
id: string;
|
|
9
|
+
disposition: 'filtered';
|
|
10
|
+
code: string;
|
|
11
|
+
} | {
|
|
12
|
+
id: string;
|
|
13
|
+
disposition: 'coalesced' | 'answered' | 'failed' | 'cancelled';
|
|
14
|
+
turnId: string;
|
|
15
|
+
};
|
|
16
|
+
/** The inbound fields that the projection reads. The delivery adapter stores more. */
|
|
17
|
+
export interface InboundRow {
|
|
18
|
+
readonly id: string;
|
|
19
|
+
/** The Turn or open input batch that answers the message. Absent on a filtered message. */
|
|
20
|
+
readonly root?: string;
|
|
21
|
+
/** The classification that refused the message before any Turn. */
|
|
22
|
+
readonly filtered?: string;
|
|
23
|
+
/** The ledger sequence, for the oldest-first order. */
|
|
24
|
+
readonly sequence?: number;
|
|
25
|
+
}
|
|
26
|
+
/** The Turn fields that decide a message's destination. */
|
|
27
|
+
export interface InboundTurn {
|
|
28
|
+
readonly id: string;
|
|
29
|
+
readonly root: string;
|
|
30
|
+
readonly status: string;
|
|
31
|
+
readonly conclusion?: string;
|
|
32
|
+
readonly inputIds?: readonly string[];
|
|
33
|
+
}
|
|
34
|
+
export interface InboundState {
|
|
35
|
+
readonly channel?: {
|
|
36
|
+
readonly inbounds?: Readonly<Record<string, InboundRow>>;
|
|
37
|
+
};
|
|
38
|
+
readonly turns: Readonly<Record<string, InboundTurn>>;
|
|
39
|
+
readonly inputBatches?: Readonly<Record<string, {
|
|
40
|
+
readonly state: string;
|
|
41
|
+
}>>;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* One message's current destination.
|
|
45
|
+
* - `filtered` is the classification that refused it before a Turn.
|
|
46
|
+
* - `coalesced` means it is in `turnId`: an open input batch, or a Turn that has not reached a terminal.
|
|
47
|
+
* - `answered` is a succeeded Turn, `cancelled` a cancel, and every other terminal is `failed`.
|
|
48
|
+
* A recorded message with no live Turn and no open batch is `failed`, never silent: retention or a crash cannot make
|
|
49
|
+
* the Host UI report that the message has no destination.
|
|
50
|
+
*/
|
|
51
|
+
export declare function inboundDisposition(state: InboundState, row: InboundRow): InboundDisposition;
|
|
52
|
+
/** Every recorded inbound human message, oldest first. The order is the ledger sequence, never insertion order. */
|
|
53
|
+
export declare function inboundDispositions(state: InboundState): InboundDisposition[];
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
export { cardCallDue, CONNECTOR_OUTCOME_UNKNOWN, reportCardDecisions, settleCardCall } from './cards.js';
|
|
2
|
+
export { COALESCE_DEFAULTS, coalescePolicy, type CoalescePolicy, type InputFields } from './coalesce.js';
|
|
3
|
+
export { commandBots, commitCommand, type KeylessCommand } from './commands.js';
|
|
4
|
+
export type { CommandRecord } from './commit.js';
|
|
5
|
+
export { compactVeto } from './compaction.js';
|
|
6
|
+
export { checkReply, delegationCancelAnswer, hostIntentCancelAnswer, observeDevices, replyCheckDue, settleDelegations, turnCancelAnswer, type DelegationTimers, type IntentCancelResult, type ReplyCheck, type ReplyReadback } from './delegation.js';
|
|
7
|
+
export { collaborationDue } from './due.js';
|
|
8
|
+
export { hostMessageDisposition } from './message.js';
|
|
9
|
+
export { admitDeviceSlot, autonomousIntentIds, userFirst, type DispatchIntent } from './priority.js';
|
|
10
|
+
export { advanceRoomSeats, seatTurn, type SeatFacts } from './rooms.js';
|
|
11
|
+
export { DEVICE_NOT_BOUND, DEVICE_SWITCHING, OFFER_WAIT_MS, syncTurn, type SealedRoutineTemplate, type SyncFacts, type SyncOptions, type SyncRefusal, type SyncStep } from './sync.js';
|
|
12
|
+
export { admitBotToolsets, inactive, requireMain } from './team.js';
|
|
13
|
+
export { addTurn } from './turn.js';
|
|
@@ -0,0 +1,4 @@
|
|
|
1
|
+
export { admitDeviceSlot, autonomousIntentIds, userFirst } from '../chunk-33YA66U7.js';
|
|
2
|
+
export { COALESCE_DEFAULTS, CONNECTOR_OUTCOME_UNKNOWN, DEVICE_NOT_BOUND, DEVICE_SWITCHING, OFFER_WAIT_MS, addTurn, admitBotToolsets, advanceRoomSeats, cardCallDue, checkReply, coalescePolicy, collaborationDue, commandBots, commitCommand, compactVeto, delegationCancelAnswer, hostIntentCancelAnswer, hostMessageDisposition, inactive, observeDevices, replyCheckDue, reportCardDecisions, requireMain, seatTurn, settleCardCall, settleDelegations, syncTurn, turnCancelAnswer } from '../chunk-ZUFZCROA.js';
|
|
3
|
+
//# sourceMappingURL=index.js.map
|
|
4
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import type { Turn } from './turn.js';
|
|
2
|
+
import { type DelegationState } from './delegation.js';
|
|
3
|
+
/**
|
|
4
|
+
* The first acceptance of one Agent message as a pure rule (#739 D1). The SDK has already checked the binding.
|
|
5
|
+
* A delegated reply body is stored with its acceptance record; that record is the only reply body authority (§3.3).
|
|
6
|
+
*/
|
|
7
|
+
export interface MessageFields {
|
|
8
|
+
taskId: string;
|
|
9
|
+
payload: {
|
|
10
|
+
body: string;
|
|
11
|
+
messageId: string;
|
|
12
|
+
contentHash: string;
|
|
13
|
+
contentType: string;
|
|
14
|
+
};
|
|
15
|
+
}
|
|
16
|
+
export type MessageDisposition = {
|
|
17
|
+
outcome: 'accepted';
|
|
18
|
+
} | {
|
|
19
|
+
outcome: 'refused';
|
|
20
|
+
reasonCode: string;
|
|
21
|
+
};
|
|
22
|
+
/**
|
|
23
|
+
* `deliver` stages the body for the Host channel; the Turn's outcome makes it visible (#1762). Absent: the Host has no channel. `hostMessage` (#1356) decides the message of
|
|
24
|
+
* a Host intent whose handler has a message handler. An accepted one is recorded without its body and is not delivered.
|
|
25
|
+
*/
|
|
26
|
+
export declare function acceptMessage(state: DelegationState, turnId: string, input: MessageFields, now: () => number, deliver?: (turn: Turn, key: string, text: string) => void, hostMessage?: () => MessageDisposition): MessageDisposition;
|
|
27
|
+
/**
|
|
28
|
+
* The checked result of a Host intent message handler (#1356). K4 checks only what the Host returns, so the Host checks the
|
|
29
|
+
* handler's result. A thenable throws after its rejection is consumed, and any other shape than a disposition throws.
|
|
30
|
+
*/
|
|
31
|
+
export declare function hostMessageDisposition(result: unknown): MessageDisposition;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { type BotTurnOutcome, type ResultSchema } from '@byok-sdk/protocol';
|
|
2
|
+
import { type Card, type Question, type Turn } from './turn.js';
|
|
3
|
+
import { type DelegationBot, type DelegationState, type IntentFacts, type Publish } from './delegation.js';
|
|
4
|
+
import { type RoomsState } from './rooms.js';
|
|
5
|
+
import { type Autonomy, type AutonomyState } from './autonomy.js';
|
|
6
|
+
/**
|
|
7
|
+
* The outcome of one Bot Turn as pure rules (#739 D1): the frozen-schema check, the audit-only cases,
|
|
8
|
+
* the management gate and the order of the actions. The Host gives the ports for its own stores:
|
|
9
|
+
* team management, K4 routines and the channel outbox. Each port throws to refuse its action.
|
|
10
|
+
*/
|
|
11
|
+
export type Accept = (action: string, work: () => void) => void;
|
|
12
|
+
type Action<K extends 'create_routine' | 'update_routine' | 'cancel_routine'> = NonNullable<BotTurnOutcome[K]>[number];
|
|
13
|
+
export interface OutcomeState extends DelegationState, AutonomyState {
|
|
14
|
+
team: {
|
|
15
|
+
bots: Readonly<Record<string, DelegationBot & {
|
|
16
|
+
readonly mainBot: boolean;
|
|
17
|
+
readonly autonomy?: Autonomy;
|
|
18
|
+
}>>;
|
|
19
|
+
} & RoomsState;
|
|
20
|
+
schemas: Record<string, ResultSchema>;
|
|
21
|
+
cards: Record<string, Card>;
|
|
22
|
+
questions: Record<string, Question>;
|
|
23
|
+
}
|
|
24
|
+
export interface OutcomePorts {
|
|
25
|
+
/** The Host clock. Each action reads it when it runs. */
|
|
26
|
+
now(): number;
|
|
27
|
+
publish: Publish;
|
|
28
|
+
/** The committed K4 intents, for a Main Bot cancel. */
|
|
29
|
+
committed: Pick<IntentFacts, 'intent'>;
|
|
30
|
+
/** Team management actions. Run each one through `managed`. */
|
|
31
|
+
manage(turn: Turn, outcome: BotTurnOutcome, managed: Accept): void;
|
|
32
|
+
createRoutine(turn: Turn, action: Action<'create_routine'>, index: number): void;
|
|
33
|
+
updateRoutine(turn: Turn, action: Action<'update_routine'>): void;
|
|
34
|
+
cancelRoutine(turn: Turn, action: Action<'cancel_routine'>): void;
|
|
35
|
+
/** Capability: queue one channel message. Absent: skipped, the Host has no channel. */
|
|
36
|
+
deliver?(turn: Turn, key: string, text: string): void;
|
|
37
|
+
/**
|
|
38
|
+
* Mode: room history mode (#883). An accepted seat post also publishes `room-message:<roomId>:<messageId>` with the stored
|
|
39
|
+
* message, so the Host can write it to its room authority. Absent: off, no such projection.
|
|
40
|
+
*/
|
|
41
|
+
roomPosts?: boolean;
|
|
42
|
+
}
|
|
43
|
+
/** `turnId` is the Turn of the K4 intent key; `taskId` is the task of the terminal. A refused action goes to `rejected`. */
|
|
44
|
+
export declare function applyTurnOutcome(state: OutcomeState, turnId: string, taskId: string, document: unknown, ports: OutcomePorts): void;
|
|
45
|
+
export {};
|
|
@@ -0,0 +1,52 @@
|
|
|
1
|
+
import type { Turn } from './turn.js';
|
|
2
|
+
/** The background intents that user input overtakes; dream ids already use the ledger's hashed identity. */
|
|
3
|
+
export declare function autonomousIntentIds(turns: readonly Pick<Turn, 'id' | 'source'>[], dreams: readonly string[]): Set<string>;
|
|
4
|
+
/**
|
|
5
|
+
* The reference Host's explicit work priority as pure rules (#1229 item 1). The K4 FIFO keeps its order: one queue per
|
|
6
|
+
* Agent, the lowest sequence is the head, and a submitted execution keeps its taskId generation
|
|
7
|
+
* (docs/host-execution-core.md section 3). These rules change only the sequence of queued, never-submitted intents and
|
|
8
|
+
* the dispatch decision of one device.
|
|
9
|
+
*/
|
|
10
|
+
/** The concurrent task limit of a device, as the daemon maxConcurrentTasks default (#1121). */
|
|
11
|
+
export declare const DEVICE_CONCURRENCY = 8;
|
|
12
|
+
/** The slots of a device that autonomous work may not take, so user input always has one. */
|
|
13
|
+
export declare const USER_RESERVED_SLOTS = 1;
|
|
14
|
+
/** The intent fields that the priority rules read. K4 owns every other field. */
|
|
15
|
+
export interface QueuedIntent {
|
|
16
|
+
readonly id: string;
|
|
17
|
+
readonly agent: string;
|
|
18
|
+
readonly sequence: number;
|
|
19
|
+
readonly phase: string;
|
|
20
|
+
readonly attempts: number;
|
|
21
|
+
}
|
|
22
|
+
/** A dispatched intent: the fields of the device reservation, and whether it currently occupies a slot of its device. */
|
|
23
|
+
export interface DispatchIntent extends QueuedIntent {
|
|
24
|
+
readonly source: 'user' | 'bot' | 'routine';
|
|
25
|
+
readonly deviceId: string;
|
|
26
|
+
/** The intent is submitted or has attempt evidence, so it holds a device slot until its terminal. */
|
|
27
|
+
readonly occupies: boolean;
|
|
28
|
+
}
|
|
29
|
+
/** A queued intent that never reached the SDK: the only rows that a priority rule may move. */
|
|
30
|
+
export declare function isUnsubmitted(row: Pick<QueuedIntent, 'phase' | 'attempts'>): boolean;
|
|
31
|
+
/** The new sequence values of one Agent FIFO, and the counter value after them. */
|
|
32
|
+
export interface SequencePlan {
|
|
33
|
+
assignments: Array<{
|
|
34
|
+
id: string;
|
|
35
|
+
sequence: number;
|
|
36
|
+
}>;
|
|
37
|
+
sequence: number;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* Puts the queued, never-submitted intents of the user intent's Agent FIFO in priority order: every non-autonomous
|
|
41
|
+
* intent keeps its arrival order, then the autonomous ones (the ids in the set) keep theirs.
|
|
42
|
+
* Returns undefined when the user intent is not queued and unsubmitted, or the order already holds.
|
|
43
|
+
* The new values are one block above every current sequence, so a submitted or in-flight intent is never moved.
|
|
44
|
+
*/
|
|
45
|
+
export declare function userFirst(rows: readonly QueuedIntent[], userIntentId: string, autonomous: ReadonlySet<string>, next: number): SequencePlan | undefined;
|
|
46
|
+
/**
|
|
47
|
+
* Whether the Host may begin the intent on its device now. User-source work may use every slot; other work leaves
|
|
48
|
+
* USER_RESERVED_SLOTS free (none when the limit is 1, which has no spare slot). The rows hold the open intents of every
|
|
49
|
+
* Agent on the device; the intent itself is not counted, so the check gives the same answer before and after the intent
|
|
50
|
+
* becomes in-flight.
|
|
51
|
+
*/
|
|
52
|
+
export declare function admitDeviceSlot(intent: DispatchIntent, rows: Iterable<DispatchIntent>, limit?: number): boolean;
|