@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,67 @@
|
|
|
1
|
+
import { type Json } from './turn.js';
|
|
2
|
+
/**
|
|
3
|
+
* Bot autonomy as pure rules (#1229, owner ruling of 2026-10-31). A Bot starts in `observe`: its autonomous actions
|
|
4
|
+
* (`create_routine`, a cross-Bot `delegate` and `room_call`) are recorded as would-do rows instead of being applied.
|
|
5
|
+
* `messageEgress`, `confirmable_action` and `ask_user` are not autonomous actions and are never gated here.
|
|
6
|
+
* Only the owner principal switches a Bot, and only for outcomes recorded after the switch (no replay).
|
|
7
|
+
*/
|
|
8
|
+
export type Autonomy = 'observe' | 'auto';
|
|
9
|
+
/** The default of a new Bot, and of a Bot row that has no autonomy field (an older ledger). */
|
|
10
|
+
export declare const DEFAULT_AUTONOMY: Autonomy;
|
|
11
|
+
/** The three actions that observe records instead of applying. */
|
|
12
|
+
export type WouldDoAction = 'create_routine' | 'delegate' | 'room_call';
|
|
13
|
+
/**
|
|
14
|
+
* One action that an observing Bot would have taken. `id` is stable for the outcome that proposed it, so applying the
|
|
15
|
+
* same outcome twice records one row. `detail` is the frozen-schema action, never a summary written by the model.
|
|
16
|
+
* `turnId` is the Turn whose outcome proposed the action; retention moves the row with that Turn's root.
|
|
17
|
+
*/
|
|
18
|
+
export interface WouldDo {
|
|
19
|
+
id: string;
|
|
20
|
+
botId: string;
|
|
21
|
+
turnId: string;
|
|
22
|
+
taskId: string;
|
|
23
|
+
action: WouldDoAction;
|
|
24
|
+
index: number;
|
|
25
|
+
at: number;
|
|
26
|
+
detail: Json;
|
|
27
|
+
}
|
|
28
|
+
/** The Host state that observe adds. It appears at the first observed action, so an older ledger reads no rows. */
|
|
29
|
+
export interface AutonomyState {
|
|
30
|
+
wouldDo?: Record<string, WouldDo>;
|
|
31
|
+
}
|
|
32
|
+
/** The autonomy of a Bot. An absent row or field is `observe`, the default of a new Bot. */
|
|
33
|
+
export declare function autonomyOf(bot: {
|
|
34
|
+
readonly autonomy?: Autonomy;
|
|
35
|
+
} | undefined): Autonomy;
|
|
36
|
+
/** `taskId` and the action's own index make the row once-only, as the K4 outcome transaction makes the action once-only. */
|
|
37
|
+
export declare function wouldDoId(taskId: string, action: WouldDoAction, index: number): string;
|
|
38
|
+
/** Records one would-do row. Returns the new row, or `undefined` when the same outcome already recorded it. */
|
|
39
|
+
export declare function recordWouldDo(state: AutonomyState, row: Omit<WouldDo, 'id'>): WouldDo | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* Refuses a state that still holds a would-do row from before #1756, which has no `turnId`. Only the one-shot migration
|
|
42
|
+
* links such a row to its Turn, so a store that skipped it fails here instead of keeping the row forever.
|
|
43
|
+
*/
|
|
44
|
+
export declare function refuseUnmigratedWouldDo(state: AutonomyState): void;
|
|
45
|
+
/** The would-do rows of one Bot, or of every Bot, oldest first. A row of the same instant keeps a stable id order. */
|
|
46
|
+
export declare function wouldDoRows(state: AutonomyState, botId?: string): WouldDo[];
|
|
47
|
+
/**
|
|
48
|
+
* The gate that a Turn outcome passes to each autonomous action. `record` writes the would-do row and publishes it for
|
|
49
|
+
* the Host UI; it never applies the action.
|
|
50
|
+
*/
|
|
51
|
+
export interface AutonomyGate {
|
|
52
|
+
readonly autonomy: Autonomy;
|
|
53
|
+
record(action: WouldDoAction, index: number, detail: Json): void;
|
|
54
|
+
}
|
|
55
|
+
/** Whether the gate observes: the action is recorded, not applied. */
|
|
56
|
+
export declare function observes(gate: AutonomyGate): boolean;
|
|
57
|
+
/** The autonomy gate of one outcome (#1229): an observing Bot records its autonomous actions instead of applying them. */
|
|
58
|
+
export declare function autonomyGate(state: AutonomyState & {
|
|
59
|
+
turns: Record<string, {
|
|
60
|
+
botId: string;
|
|
61
|
+
}>;
|
|
62
|
+
team: {
|
|
63
|
+
bots: Record<string, {
|
|
64
|
+
autonomy?: Autonomy;
|
|
65
|
+
} | undefined>;
|
|
66
|
+
};
|
|
67
|
+
}, turnId: string, taskId: string, now: () => number, publish: (id: string, value: Json) => void): AutonomyGate;
|
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
import { type Card, type TurnsState } from './turn.js';
|
|
2
|
+
import type { Publish } from './delegation.js';
|
|
3
|
+
/** Passive expiry: a pending card expires at its `expiresAt`. */
|
|
4
|
+
export declare function expireCard(card: Card, now: number): void;
|
|
5
|
+
/** Runs before the Turn steps, so a ContextPack frozen in the same sync shows each expiry. */
|
|
6
|
+
export declare function expireCards(state: {
|
|
7
|
+
readonly cards: Readonly<Record<string, Card>>;
|
|
8
|
+
}, now: number): void;
|
|
9
|
+
/**
|
|
10
|
+
* The error of a connector call whose outcome is unknown: the call timed out, or a Host found its claim with no settle after
|
|
11
|
+
* a crash. The call may have run, so the card fails and the connector is never called again.
|
|
12
|
+
*/
|
|
13
|
+
export declare const CONNECTOR_OUTCOME_UNKNOWN = "Connector timed out; external outcome is unknown";
|
|
14
|
+
/** A confirmed card waits for its one connector call until it has a result or an error. */
|
|
15
|
+
export declare function cardCallDue(card: Card): boolean;
|
|
16
|
+
/**
|
|
17
|
+
* Writes the outcome of a card's connector call: the result, or the error cut to 1024 characters, and the conclusion. A
|
|
18
|
+
* result that is not JSON is an error. The next sync's `reportCardDecisions` reports the card.
|
|
19
|
+
*/
|
|
20
|
+
export declare function settleCardCall(card: Card, outcome: {
|
|
21
|
+
result: unknown;
|
|
22
|
+
} | {
|
|
23
|
+
error: unknown;
|
|
24
|
+
}): void;
|
|
25
|
+
/**
|
|
26
|
+
* Runs after the Turn steps. A decided card is projected once as `card:<id>:<state>`; a confirmed card waits for its
|
|
27
|
+
* result or error. A confirmed or rejected card then gets its `action_result` Turn under the root of the Turn that made it.
|
|
28
|
+
*/
|
|
29
|
+
export declare function reportCardDecisions(state: TurnsState & {
|
|
30
|
+
readonly cards: Readonly<Record<string, Card>>;
|
|
31
|
+
}, publish: Publish): void;
|
|
@@ -0,0 +1,111 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Input coalescing as pure rules (#606 R2). Each function changes only the input rows that the caller
|
|
3
|
+
* gives, does no I/O and takes `now` from the caller. The Host gives the facts of each Bot. It adds one
|
|
4
|
+
* user Turn for each returned sealed batch, in the returned order, before any other Turn.
|
|
5
|
+
*/
|
|
6
|
+
export type Authority = 'owner' | 'bot';
|
|
7
|
+
/** One durable record per user input while input coalescing is in use. `key` is the caller's input key. */
|
|
8
|
+
export interface UserInput {
|
|
9
|
+
id: string;
|
|
10
|
+
key: string;
|
|
11
|
+
botId: string;
|
|
12
|
+
request: string;
|
|
13
|
+
bytes: number;
|
|
14
|
+
sender: string;
|
|
15
|
+
authority: Authority;
|
|
16
|
+
receivedAt: number;
|
|
17
|
+
batchId: string;
|
|
18
|
+
}
|
|
19
|
+
export type SealReason = 'idle' | 'window' | 'items' | 'bytes' | 'boundary' | 'key_changed' | 'cancel' | 'policy_off' | 'archived';
|
|
20
|
+
/**
|
|
21
|
+
* `id` is the first input's id and the batch Turn id. `key` is the coalescing key.
|
|
22
|
+
* `request` is the rendered Request while the batch is open; sealing moves it into the batch Turn.
|
|
23
|
+
* `bytes` is its UTF-8 size, framing included. `revision` is the last projected revision: 1 is open, 2 is sealed.
|
|
24
|
+
*/
|
|
25
|
+
export interface InputBatch {
|
|
26
|
+
id: string;
|
|
27
|
+
botId: string;
|
|
28
|
+
key: string;
|
|
29
|
+
inputIds: string[];
|
|
30
|
+
bytes: number;
|
|
31
|
+
openedAt: number;
|
|
32
|
+
sealAt: number;
|
|
33
|
+
state: 'open' | 'sealed';
|
|
34
|
+
sealReason?: SealReason;
|
|
35
|
+
request?: string;
|
|
36
|
+
revision?: 1 | 2;
|
|
37
|
+
}
|
|
38
|
+
/** Values that apply when `BotOptions.coalesce` is present (owner ruling on #551). */
|
|
39
|
+
export declare const COALESCE_DEFAULTS: {
|
|
40
|
+
readonly windowMs: 10000;
|
|
41
|
+
readonly maxItems: 8;
|
|
42
|
+
readonly maxBytes: 8192;
|
|
43
|
+
};
|
|
44
|
+
export interface CoalescePolicy {
|
|
45
|
+
windowMs: number;
|
|
46
|
+
maxItems: number;
|
|
47
|
+
maxBytes: number;
|
|
48
|
+
}
|
|
49
|
+
export interface InputFields {
|
|
50
|
+
id: string;
|
|
51
|
+
key: string;
|
|
52
|
+
botId: string;
|
|
53
|
+
request: string;
|
|
54
|
+
sender: string;
|
|
55
|
+
authority: Authority;
|
|
56
|
+
}
|
|
57
|
+
/** The input rows that the rules read and change. Both maps appear at the first coalesced input. */
|
|
58
|
+
export interface CoalesceState {
|
|
59
|
+
inputs?: Record<string, UserInput>;
|
|
60
|
+
inputBatches?: Record<string, InputBatch>;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Facts of one Bot. `busy`: the Bot has a Turn that is neither concluded nor blocked.
|
|
64
|
+
* `configKey`: the values that identify the Bot configuration; inputs merge only while they stay the same.
|
|
65
|
+
* A Bot without facts counts as archived.
|
|
66
|
+
*/
|
|
67
|
+
export interface BotFacts {
|
|
68
|
+
busy: boolean;
|
|
69
|
+
configKey: readonly string[];
|
|
70
|
+
archived: boolean;
|
|
71
|
+
}
|
|
72
|
+
/** A sealed batch becomes one user Turn with these fields. Neither changes after this. */
|
|
73
|
+
export interface BatchTurn {
|
|
74
|
+
id: string;
|
|
75
|
+
botId: string;
|
|
76
|
+
request: string;
|
|
77
|
+
authority: Authority;
|
|
78
|
+
inputIds: string[];
|
|
79
|
+
}
|
|
80
|
+
/**
|
|
81
|
+
* `id` is the Turn that answers the input. With `turn`, the Host adds the input's own Turn with this id,
|
|
82
|
+
* after the Turns of `sealed`. Without it, `id` is a batch id.
|
|
83
|
+
*/
|
|
84
|
+
export interface Admission {
|
|
85
|
+
id: string;
|
|
86
|
+
turn: boolean;
|
|
87
|
+
sealed: BatchTurn[];
|
|
88
|
+
}
|
|
89
|
+
/** Construction check. `maxBytes` is at most a quarter of the ContextPack budget, so a merged Request always fits it. */
|
|
90
|
+
export declare function coalescePolicy(options: Partial<CoalescePolicy>, contextMaxBytes: number): CoalescePolicy;
|
|
91
|
+
/** One input stays raw text. Several inputs are framed once each, in arrival order, after one notice line. */
|
|
92
|
+
export declare function batchRequest(inputs: readonly UserInput[]): string;
|
|
93
|
+
/** Boundary rule: before any other new Turn of a Bot, seal its open batch, so the queue keeps arrival order. */
|
|
94
|
+
export declare function sealAtBoundary(state: CoalesceState, botId: string): BatchTurn | undefined;
|
|
95
|
+
/** Runs first in each Host sync. The window counts from the first input; later inputs never extend it. */
|
|
96
|
+
export declare function sealDueBatches(state: CoalesceState, bots: Readonly<Record<string, BotFacts>>, policy: CoalescePolicy | undefined, now: number): BatchTurn[];
|
|
97
|
+
/**
|
|
98
|
+
* Admit one user input before the Host queues it. `facts.turn` is a Turn that already has the input's id,
|
|
99
|
+
* from a time without coalescing. Without a policy, or with such a Turn, the input keeps its own Turn.
|
|
100
|
+
*/
|
|
101
|
+
export declare function admitUserInput(state: CoalesceState, input: InputFields, facts: {
|
|
102
|
+
bot?: BotFacts;
|
|
103
|
+
turn?: {
|
|
104
|
+
request: string;
|
|
105
|
+
};
|
|
106
|
+
}, policy: CoalescePolicy | undefined, now: number): Admission;
|
|
107
|
+
/** `id` is a batch id or a member input id. An open batch seals first, so the whole batch cancels. */
|
|
108
|
+
export declare function sealBatchForCancel(state: CoalesceState, id: string): {
|
|
109
|
+
id: string;
|
|
110
|
+
sealed?: BatchTurn;
|
|
111
|
+
};
|
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
import type { RoomFields } from '@byok-sdk/protocol';
|
|
2
|
+
import { type Json, type Turn } from './turn.js';
|
|
3
|
+
import { type ExternalTeam, type TeamSnapshot, type TeamSnapshotBot } from './team.js';
|
|
4
|
+
import { type MemberMentions, type Mentions } from './rooms.js';
|
|
5
|
+
import { type InputFields } from './coalesce.js';
|
|
6
|
+
import { type IntentFacts, type Publish } from './delegation.js';
|
|
7
|
+
import { type OutcomePorts, type OutcomeState } from './outcome.js';
|
|
8
|
+
import { type MessageDisposition, type MessageFields } from './message.js';
|
|
9
|
+
import type { Autonomy } from './autonomy.js';
|
|
10
|
+
import { type CommandRecord, type CommitRequest, type CommitResult, type CommitState, type Disposition, type OutboxIntent } from './commit.js';
|
|
11
|
+
export { DEVICE_NOT_BOUND, DEVICE_SWITCHING, OFFER_WAIT_MS, SEALED_ROUTINE_AGENT_CHANGED, SEALED_ROUTINE_TEMPLATE_MISSING, syncTurn, type DeviceRefusal, type FreezeExecution, type SealedRoutineTemplate, type SyncBot, type SyncFacts, type SyncOptions, type SyncRefusal, type SyncState, type SyncStep } from './sync.js';
|
|
12
|
+
export { checkReply, delegationDue, observeDevices, replyCheckDue, settleDelegations, type DelegationTimers, type ReplyCheck, type ReplyReadback } from './delegation.js';
|
|
13
|
+
export { advanceRoomSeats, seatTurn, type SeatFacts } from './rooms.js';
|
|
14
|
+
export { collaborationDue } from './due.js';
|
|
15
|
+
export { compactVeto, type CompactFacts, type CompactState } from './compaction.js';
|
|
16
|
+
export { cardCallDue, CONNECTOR_OUTCOME_UNKNOWN, expireCards, reportCardDecisions, settleCardCall } from './cards.js';
|
|
17
|
+
/** Commands with a caller key or a K4 key. The store records them, so a retry replays the first result. */
|
|
18
|
+
export type KeyedCommand =
|
|
19
|
+
/** Owner input to a Bot. The Turn id comes from the Bot and the caller key. */
|
|
20
|
+
{
|
|
21
|
+
kind: 'input';
|
|
22
|
+
botId: string;
|
|
23
|
+
key: string;
|
|
24
|
+
request: string;
|
|
25
|
+
sender: string;
|
|
26
|
+
}
|
|
27
|
+
/** A received IM message that the Host classified (docs/host-im-adapter.md §3). `key` is its inbound key. */
|
|
28
|
+
| {
|
|
29
|
+
kind: 'receive';
|
|
30
|
+
inbound: 'owner_input';
|
|
31
|
+
key: string;
|
|
32
|
+
botId: string;
|
|
33
|
+
request: string;
|
|
34
|
+
sender: string;
|
|
35
|
+
} | {
|
|
36
|
+
kind: 'receive';
|
|
37
|
+
inbound: 'room_input';
|
|
38
|
+
key: string;
|
|
39
|
+
roomId: string;
|
|
40
|
+
text: string;
|
|
41
|
+
mentions: Mentions;
|
|
42
|
+
from: string;
|
|
43
|
+
} | {
|
|
44
|
+
kind: 'room_input';
|
|
45
|
+
key: string;
|
|
46
|
+
roomId: string;
|
|
47
|
+
text: string;
|
|
48
|
+
mentions: Mentions;
|
|
49
|
+
from?: string;
|
|
50
|
+
} | {
|
|
51
|
+
kind: 'answer';
|
|
52
|
+
questionId: string;
|
|
53
|
+
answer: string;
|
|
54
|
+
} | {
|
|
55
|
+
kind: 'decide';
|
|
56
|
+
cardId: string;
|
|
57
|
+
decision: 'confirmed' | 'rejected';
|
|
58
|
+
}
|
|
59
|
+
/** K4 callback: the outcome document of a success terminal. `turnId` is the intent key. */
|
|
60
|
+
| {
|
|
61
|
+
kind: 'outcome';
|
|
62
|
+
turnId: string;
|
|
63
|
+
taskId: string;
|
|
64
|
+
document: Json;
|
|
65
|
+
}
|
|
66
|
+
/** K4 callback: the first acceptance of an Agent message. */
|
|
67
|
+
| {
|
|
68
|
+
kind: 'message';
|
|
69
|
+
turnId: string;
|
|
70
|
+
message: MessageFields;
|
|
71
|
+
}
|
|
72
|
+
/** K4 callback: the Bot routine occurrence hook. */
|
|
73
|
+
| {
|
|
74
|
+
kind: 'occurrence';
|
|
75
|
+
key: string;
|
|
76
|
+
}
|
|
77
|
+
/** External team mode (#739 Q4c): the authority's team snapshot. The command id comes from its team revision. */
|
|
78
|
+
| {
|
|
79
|
+
kind: 'team_snapshot';
|
|
80
|
+
snapshot: TeamSnapshot;
|
|
81
|
+
}
|
|
82
|
+
/** Owner room (#1321). The Host gives the room id, and the command id comes from it. */
|
|
83
|
+
| {
|
|
84
|
+
kind: 'create_room';
|
|
85
|
+
roomId: string;
|
|
86
|
+
fields: RoomFields;
|
|
87
|
+
};
|
|
88
|
+
/** The same shape as the channel `Conversation`. */
|
|
89
|
+
export interface Conversation {
|
|
90
|
+
kind: 'direct' | 'group';
|
|
91
|
+
id: string;
|
|
92
|
+
}
|
|
93
|
+
/**
|
|
94
|
+
* Owner commands without a caller key (#739 6a). The store keeps no record: each call applies and adds 1 to the revision.
|
|
95
|
+
* Only an explicit expected revision protects a retry. The first commit moves the head, so the retry is `stale_revision`.
|
|
96
|
+
*/
|
|
97
|
+
export type KeylessCommand = {
|
|
98
|
+
kind: 'set_main_bot';
|
|
99
|
+
botId: string;
|
|
100
|
+
mainBot: boolean;
|
|
101
|
+
} | {
|
|
102
|
+
kind: 'update_room';
|
|
103
|
+
roomId: string;
|
|
104
|
+
update: Partial<RoomFields>;
|
|
105
|
+
}
|
|
106
|
+
/** Owner setting (#1230): whether a non-owner structured mention in this group opens seats. */
|
|
107
|
+
| {
|
|
108
|
+
kind: 'set_room_member_mentions';
|
|
109
|
+
roomId: string;
|
|
110
|
+
memberMentions: MemberMentions;
|
|
111
|
+
} | {
|
|
112
|
+
kind: 'retry_persona';
|
|
113
|
+
botId: string;
|
|
114
|
+
}
|
|
115
|
+
/** Host persona mode (#879): the Host applied this profile revision of the Bot's Agent home. */
|
|
116
|
+
| {
|
|
117
|
+
kind: 'persona_ready';
|
|
118
|
+
botId: string;
|
|
119
|
+
revision: string;
|
|
120
|
+
} | {
|
|
121
|
+
kind: 'enable_push_route';
|
|
122
|
+
conversation: Conversation;
|
|
123
|
+
channel: string;
|
|
124
|
+
target: string;
|
|
125
|
+
owner: string;
|
|
126
|
+
} | {
|
|
127
|
+
kind: 'revoke_push_route';
|
|
128
|
+
routeId: string;
|
|
129
|
+
} | {
|
|
130
|
+
kind: 'resend_delivery';
|
|
131
|
+
deliveryId: string;
|
|
132
|
+
} | {
|
|
133
|
+
kind: 'cancel_delegation';
|
|
134
|
+
delegationId: string;
|
|
135
|
+
} | {
|
|
136
|
+
kind: 'abandon_delegation';
|
|
137
|
+
delegationId: string;
|
|
138
|
+
}
|
|
139
|
+
/** A Turn of an open delegation chain cancels the whole delegation (§8.8). */
|
|
140
|
+
| {
|
|
141
|
+
kind: 'cancel_turn';
|
|
142
|
+
turnId: string;
|
|
143
|
+
}
|
|
144
|
+
/** Main Bot `botId` completes any open Bot routine, an archived owner's too (§55c). */
|
|
145
|
+
| {
|
|
146
|
+
kind: 'end_routine';
|
|
147
|
+
botId: string;
|
|
148
|
+
routineId: string;
|
|
149
|
+
}
|
|
150
|
+
/** Owner switch of one Bot's autonomy (#1229). It applies to outcomes recorded after it; nothing replays. */
|
|
151
|
+
| {
|
|
152
|
+
kind: 'set_autonomy';
|
|
153
|
+
botId: string;
|
|
154
|
+
autonomy: Autonomy;
|
|
155
|
+
};
|
|
156
|
+
export type Command = KeyedCommand | KeylessCommand;
|
|
157
|
+
/** The Bot and home rows that the team commands read and change. */
|
|
158
|
+
interface TeamRows {
|
|
159
|
+
team: {
|
|
160
|
+
external?: ExternalTeam;
|
|
161
|
+
bots: Readonly<Record<string, {
|
|
162
|
+
mainBot: boolean;
|
|
163
|
+
archived: boolean;
|
|
164
|
+
participation?: 'suspended';
|
|
165
|
+
readonly revision: string;
|
|
166
|
+
readyRevision: string | null;
|
|
167
|
+
readonly persona: string;
|
|
168
|
+
autonomy?: Autonomy;
|
|
169
|
+
}>>;
|
|
170
|
+
homeOperations: ReadonlyArray<{
|
|
171
|
+
readonly botId: string;
|
|
172
|
+
readonly status: string;
|
|
173
|
+
readonly request: {
|
|
174
|
+
readonly payload: {
|
|
175
|
+
readonly agentRef: {
|
|
176
|
+
readonly profileRevision: string;
|
|
177
|
+
};
|
|
178
|
+
};
|
|
179
|
+
};
|
|
180
|
+
}>;
|
|
181
|
+
};
|
|
182
|
+
}
|
|
183
|
+
export type CommandState = OutcomeState & CommitState & TeamRows;
|
|
184
|
+
/** The state `commandBots` reads. */
|
|
185
|
+
export type CommandScopeState = Pick<CommandState, 'turns' | 'questions' | 'cards' | 'team'>;
|
|
186
|
+
/**
|
|
187
|
+
* The Bots on whose devices a new command would create work (#957, #975). A Host refuses the command in `CommandPorts.admit`
|
|
188
|
+
* while one of their devices is frozen for an owner switch or owned by the other Host, so both Hosts refuse the same commands.
|
|
189
|
+
* `input` and an owner `receive` name their Bot. A room input can seat any Bot member of the room. An answer adds a Turn for
|
|
190
|
+
* the question's Bot, and a decided card adds an `action_result` Turn for the card's Bot and can start its connector call.
|
|
191
|
+
* A suspended room member gets no seat (#1319), so its device never refuses a room input.
|
|
192
|
+
* Any other command, and an unknown Bot, room, question or card, names none: the command refuses an unknown id itself.
|
|
193
|
+
*/
|
|
194
|
+
export declare function commandBots(state: CommandScopeState, command: Command): string[];
|
|
195
|
+
export interface CommandPorts {
|
|
196
|
+
/** The Host clock. A command reads it when it needs a time. */
|
|
197
|
+
now(): number;
|
|
198
|
+
/**
|
|
199
|
+
* Policy: the Host's admission of a new command (#957). It runs after the replay lookup, so an exact replay still returns
|
|
200
|
+
* its first result. It throws to refuse, and the commit writes nothing. A Host that implements the owner switch must
|
|
201
|
+
* pass it. Absent: every command is accepted.
|
|
202
|
+
*/
|
|
203
|
+
admit?(command: Command): void;
|
|
204
|
+
publish: Publish;
|
|
205
|
+
/**
|
|
206
|
+
* Capability: input admission with the Host coalescing policy. Returns the id of the Turn that answers the input.
|
|
207
|
+
* Absent: an owner input is refused with `MissingPortError`.
|
|
208
|
+
*/
|
|
209
|
+
admitInput?(fields: InputFields): string;
|
|
210
|
+
/** Capability: saves the inbound route of a received message. Absent: skipped, the Host has no channel. */
|
|
211
|
+
remember?(root: string): void;
|
|
212
|
+
/**
|
|
213
|
+
* Capability: queues one channel message and returns the delivery id. A `staged` one waits for `promote` (#1762).
|
|
214
|
+
* Absent: skipped, the Host has no channel.
|
|
215
|
+
*/
|
|
216
|
+
deliver?(turn: Turn, key: string, text: string, staged: boolean): string | undefined;
|
|
217
|
+
/** Capability: promotes the staged deliveries of a task and returns their ids. Absent: skipped, the Host has no channel. */
|
|
218
|
+
promote?(taskId: string): readonly string[];
|
|
219
|
+
/**
|
|
220
|
+
* Capability: decides the Agent message of a Host intent whose handler has a message handler (#1356).
|
|
221
|
+
* Absent: the message is refused as `binding_mismatch`.
|
|
222
|
+
*/
|
|
223
|
+
hostMessage?(): MessageDisposition;
|
|
224
|
+
/** Capability: the Host stores of a Turn outcome. Absent: an outcome is refused with `MissingPortError`. */
|
|
225
|
+
outcome?: Omit<OutcomePorts, 'now' | 'publish' | 'deliver'>;
|
|
226
|
+
/** Capability: writes the routine Turn of the occurrence. Absent: an occurrence is refused with `MissingPortError`. */
|
|
227
|
+
occurrence?(): void;
|
|
228
|
+
/** Capability: the K4 intent rows by Turn id, read in the commit transaction. Absent: refused with `MissingPortError`. */
|
|
229
|
+
intents?: Pick<IntentFacts, 'intent'>;
|
|
230
|
+
/**
|
|
231
|
+
* Capability: advances the desired persona revision of a Bot with the Host models and toolset policy.
|
|
232
|
+
* Absent: refused with `MissingPortError`.
|
|
233
|
+
*/
|
|
234
|
+
updatePersona?(botId: string, persona: string): void;
|
|
235
|
+
/**
|
|
236
|
+
* Capability: writes one snapshot Bot's profile with the Host template, and queues its persona projection when the
|
|
237
|
+
* profile changed. Absent: a team snapshot is refused with `MissingPortError`.
|
|
238
|
+
*/
|
|
239
|
+
teamBot?(bot: TeamSnapshotBot): void;
|
|
240
|
+
/**
|
|
241
|
+
* Capability: the channel route rows. Each function returns the id of the row that it wrote.
|
|
242
|
+
* Absent: a route command is refused with `MissingPortError`.
|
|
243
|
+
*/
|
|
244
|
+
routes?: {
|
|
245
|
+
enable(conversation: Conversation, channel: string, target: string, owner: string): string;
|
|
246
|
+
revoke(routeId: string): void;
|
|
247
|
+
resend(deliveryId: string): string;
|
|
248
|
+
};
|
|
249
|
+
/**
|
|
250
|
+
* Capability: the K4 routine rows. `end` completes one open Bot routine, as K4 `setLifecycle('completed')`.
|
|
251
|
+
* Absent: `end_routine` is refused with `MissingPortError`.
|
|
252
|
+
*/
|
|
253
|
+
routines?: {
|
|
254
|
+
end(routineId: string): void;
|
|
255
|
+
};
|
|
256
|
+
}
|
|
257
|
+
/**
|
|
258
|
+
* `recordCallbacks` is false when the caller deduplicates the K4 callbacks durably, as K4 does in L.
|
|
259
|
+
* K4 dedups terminals and occurrences, and accepted messages by their receipt. A refused message still gets a record.
|
|
260
|
+
*/
|
|
261
|
+
/** The identities that retention retires for good (#798). An owner command can bring one back, so each commit checks them. */
|
|
262
|
+
export type RetiredNamespace = 'turn' | 'input' | 'round';
|
|
263
|
+
/** The ids that one `decide` added, by namespace. */
|
|
264
|
+
export type AdmittedIds = Record<RetiredNamespace, string[]>;
|
|
265
|
+
/** A commit would admit an identity that retention retired. The store rolls the commit back. */
|
|
266
|
+
export declare class RetiredIdentityError extends Error {
|
|
267
|
+
readonly namespace: RetiredNamespace;
|
|
268
|
+
readonly id: string;
|
|
269
|
+
readonly code: 'retired_identity';
|
|
270
|
+
constructor(namespace: RetiredNamespace, id: string);
|
|
271
|
+
}
|
|
272
|
+
/**
|
|
273
|
+
* The admission check (#798). Each store calls it inside its commit transaction, before the commit, with the ids from
|
|
274
|
+
* `CommandStore.admitted`. A sync store passes its lookup; an async store loads the tombstones of these ids first.
|
|
275
|
+
*/
|
|
276
|
+
export declare function refuseRetired(ids: AdmittedIds | undefined, isRetired: (namespace: RetiredNamespace, id: string) => boolean): void;
|
|
277
|
+
/**
|
|
278
|
+
* A user input that does not coalesce becomes a Turn with the input's id, and a batch Turn takes its first input's id.
|
|
279
|
+
* The coalescing policy can change between retention and a retry, so a Turn id and an input id are one identity space:
|
|
280
|
+
* each is checked against both namespaces.
|
|
281
|
+
*/
|
|
282
|
+
export declare function retiredIdentity(namespace: RetiredNamespace, id: string, isRetired: (namespace: RetiredNamespace, id: string) => boolean): boolean;
|
|
283
|
+
export interface CommandStore {
|
|
284
|
+
scope: string;
|
|
285
|
+
recordCallbacks: boolean;
|
|
286
|
+
/**
|
|
287
|
+
* A command record that retention moved out of the state (#798). The replay check reads it after the state. A commit
|
|
288
|
+
* that has no command record (a keyless command, or a callback that the caller deduplicates durably) does not read it.
|
|
289
|
+
*/
|
|
290
|
+
archived: (commandId: string) => CommandRecord | undefined;
|
|
291
|
+
/** Receives the ids that `decide` added. Not called for a replay. The store passes them to `refuseRetired`. */
|
|
292
|
+
admitted: (ids: AdmittedIds) => void;
|
|
293
|
+
}
|
|
294
|
+
export declare function isKeyless(command: Command): command is KeylessCommand;
|
|
295
|
+
/** The fields that decide each command's effect: the fields that the existing identity checks compare. */
|
|
296
|
+
export declare function commandEvidence(command: KeyedCommand): Json;
|
|
297
|
+
/** A command needs a capability port that the Host did not pass. The commit writes nothing. */
|
|
298
|
+
export declare class MissingPortError extends Error {
|
|
299
|
+
readonly kind: string;
|
|
300
|
+
readonly code: 'missing_port';
|
|
301
|
+
constructor(kind: string);
|
|
302
|
+
}
|
|
303
|
+
/** Decides one command and changes `state`. Each outbox row that it writes goes to `out`. */
|
|
304
|
+
export declare function decideCommand(state: CommandState, command: Command, ports: CommandPorts, out: (intent: OutboxIntent) => void): Disposition;
|
|
305
|
+
/** One command through the commit contract. The caller runs it inside one store transaction. A keyless command gets no record. */
|
|
306
|
+
export declare function commitCommand(state: CommandState, request: CommitRequest<Command>, store: CommandStore, ports: CommandPorts): CommitResult;
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
import type { Json } from './turn.js';
|
|
2
|
+
/**
|
|
3
|
+
* The collaboration commit contract (#739 D1). One commit takes a scope, a command id, an optional
|
|
4
|
+
* expected revision and the command. It returns the new revision, the disposition and the outbox intents.
|
|
5
|
+
*
|
|
6
|
+
* The store runs `commit` in one transaction with the state change, the command record and the outbox
|
|
7
|
+
* writes. A throw from `commit` or from `decide` must leave all three unchanged.
|
|
8
|
+
*/
|
|
9
|
+
export type Disposition = {
|
|
10
|
+
outcome: 'accepted';
|
|
11
|
+
value?: Json;
|
|
12
|
+
} | {
|
|
13
|
+
outcome: 'refused';
|
|
14
|
+
reasonCode: string;
|
|
15
|
+
reason?: string;
|
|
16
|
+
};
|
|
17
|
+
/** A durable Host outbox row that the commit wrote: a K4 projection id or a channel delivery id. */
|
|
18
|
+
export interface OutboxIntent {
|
|
19
|
+
kind: 'projection' | 'delivery';
|
|
20
|
+
id: string;
|
|
21
|
+
}
|
|
22
|
+
export interface CommitResult {
|
|
23
|
+
revision: number;
|
|
24
|
+
disposition: Disposition;
|
|
25
|
+
outbox: OutboxIntent[];
|
|
26
|
+
}
|
|
27
|
+
export interface CommitRequest<C> {
|
|
28
|
+
/** An opaque key. In K8 it is the ledger tenant: one product account and workspace. */
|
|
29
|
+
scope: string;
|
|
30
|
+
/** A keyless command gets no record, so its id is not a dedup key. */
|
|
31
|
+
commandId: string;
|
|
32
|
+
/** Absent: decide on the head. Present and not the head: a `stale_revision` conflict. */
|
|
33
|
+
expectedRevision?: number;
|
|
34
|
+
command: C;
|
|
35
|
+
}
|
|
36
|
+
/**
|
|
37
|
+
* Dedup evidence. Retention moves a record out of the state and keeps it readable for its retention window.
|
|
38
|
+
* `root`: the root that the command's effect belongs to. The record moves with that root.
|
|
39
|
+
*/
|
|
40
|
+
export interface CommandRecord {
|
|
41
|
+
evidence: string;
|
|
42
|
+
result: CommitResult;
|
|
43
|
+
root?: string;
|
|
44
|
+
}
|
|
45
|
+
/** Both fields are optional: a state without them is at revision 0 and has no record. */
|
|
46
|
+
export interface CommitState {
|
|
47
|
+
revision?: number;
|
|
48
|
+
commands?: Record<string, CommandRecord>;
|
|
49
|
+
}
|
|
50
|
+
export type CommitConflictCode = 'scope_mismatch' | 'identity_conflict' | 'stale_revision';
|
|
51
|
+
export declare class CommitConflict extends Error {
|
|
52
|
+
readonly code: CommitConflictCode;
|
|
53
|
+
constructor(code: CommitConflictCode, message: string);
|
|
54
|
+
}
|
|
55
|
+
/** The command record of a keyed command. */
|
|
56
|
+
export interface RecordOptions {
|
|
57
|
+
/** The fields that decide the command's effect. Only their hash is stored. */
|
|
58
|
+
evidence: Json;
|
|
59
|
+
/** The message of an identity conflict. */
|
|
60
|
+
conflict: () => string;
|
|
61
|
+
/** Which new records to keep. Absent: keep each one. A caller that deduplicates some dispositions itself keeps the rest. */
|
|
62
|
+
keep?: (disposition: Disposition) => boolean;
|
|
63
|
+
/** Read after `decide`: the root of the command's effect, stored on the record. */
|
|
64
|
+
root?: () => string | undefined;
|
|
65
|
+
}
|
|
66
|
+
export interface CommitOptions {
|
|
67
|
+
/** The scope that this store owns. */
|
|
68
|
+
scope: string;
|
|
69
|
+
/**
|
|
70
|
+
* Absent: the commit has no record and no replay. This is so for a keyless command, which applies at each call,
|
|
71
|
+
* and for a callback that the caller already deduplicates durably, as K4 does for terminals.
|
|
72
|
+
*/
|
|
73
|
+
record?: RecordOptions;
|
|
74
|
+
/** A record that retention moved out of the state (#798). The store reads it by command id. */
|
|
75
|
+
archived?: (commandId: string) => CommandRecord | undefined;
|
|
76
|
+
}
|
|
77
|
+
export declare function revisionOf(state: CommitState): number;
|
|
78
|
+
/**
|
|
79
|
+
* Replay first, then the revision check: a retry with its original expected revision gets its original result.
|
|
80
|
+
* Every new commit adds 1 to the revision, also for a refused disposition. A commit without a record is always new.
|
|
81
|
+
*/
|
|
82
|
+
export declare function commit<C>(state: CommitState, request: CommitRequest<C>, options: CommitOptions, decide: (out: (intent: OutboxIntent) => void) => Disposition): CommitResult;
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import type { Turn } from './turn.js';
|
|
2
|
+
import type { AcceptedReply, Delegation } from './delegation.js';
|
|
3
|
+
import type { Seat } from './rooms.js';
|
|
4
|
+
/** The collaboration rows that the compact veto reads. */
|
|
5
|
+
export interface CompactState {
|
|
6
|
+
readonly turns: Readonly<Record<string, Turn>>;
|
|
7
|
+
readonly delegations: Readonly<Record<string, Delegation>>;
|
|
8
|
+
readonly team: {
|
|
9
|
+
readonly seats: Readonly<Record<string, Seat>>;
|
|
10
|
+
};
|
|
11
|
+
readonly replies: Readonly<Record<string, AcceptedReply>>;
|
|
12
|
+
/** The dreams that K8 has not closed, by occurrence key. */
|
|
13
|
+
readonly dreams?: {
|
|
14
|
+
readonly open: Readonly<Record<string, unknown>>;
|
|
15
|
+
};
|
|
16
|
+
}
|
|
17
|
+
/** The store facts that the compact veto reads. */
|
|
18
|
+
export interface CompactFacts {
|
|
19
|
+
/** The Turn has an intent. */
|
|
20
|
+
hasIntent(turnId: string): boolean;
|
|
21
|
+
/** The receipt that the store keeps for the replay of the task's accepted Agent message. */
|
|
22
|
+
receipt(taskId: string): {
|
|
23
|
+
readonly messageId: string;
|
|
24
|
+
readonly contentHash: string;
|
|
25
|
+
} | undefined;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Refuses the compaction of the intent of Turn `key` with a reason, or allows it with `undefined` (#816, #793 S8). A Turn id is
|
|
29
|
+
* its intent key. K8 reads the intent of a Turn until the Turn and its readers settle, so the store keeps it until then.
|
|
30
|
+
* A dream intent has no Turn, and K8 reads it until the sync closes the dream, or the next dream repeats the window (#1490).
|
|
31
|
+
* Any other key without a Turn, for example a Host job, is not a K8 key. L's K4 veto and H's compaction both run this rule.
|
|
32
|
+
*/
|
|
33
|
+
export declare function compactVeto(state: CompactState, key: string, facts: CompactFacts): string | undefined;
|