@theoremjs/agents 0.3.5-next.935.ga3dc485 → 0.3.5-next.938.g3cbd0dd

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/README.md CHANGED
@@ -426,6 +426,8 @@ Import from the narrowest entrypoint that has what you need. Each row gives the
426
426
  | `jsr:@theoremjs/agents/cli` / `@theoremjs/agents/cli` | Profile inspection and stress-test CLI (`agents` binary on npm). `agents studio …` runs the studio the project installed. |
427
427
  | `jsr:@theoremjs/agents/schema` / `@theoremjs/agents/schema` | Profile vocabulary and field catalog (closed unions, field metadata) for host UIs and docs; no Deno APIs. |
428
428
  | `jsr:@theoremjs/agents/evals` / `@theoremjs/agents/evals` | Graders that read trace records and write their results as trace records through the same sink. |
429
+ | `jsr:@theoremjs/agents/conversation` / `@theoremjs/agents/conversation` | One reply at a time per conversation: the inbox contract your storage implements, the policy for what the model may be told now, and `runConversation`, which runs each reply under a hold. |
430
+ | `jsr:@theoremjs/agents/conversation/testing` / `@theoremjs/agents/conversation/testing` | The scenarios every conversation inbox must pass (`conversationScenarios`). Test only. |
429
431
 
430
432
  The studio is a separate package, `@theoremjs/studio`. It is never part of the kernel package. Install it beside the kernel to open your project's agents in a local studio: `npm install -D @theoremjs/studio`, then `npx theorem-studio`. It needs Deno. The same package shows the studio as a screen in your own app, with one server handler. Its README has both.
431
433
 
@@ -0,0 +1,36 @@
1
+ /**
2
+ * A conversation inbox kept in memory, for tests and single-process apps. It also does the app's
3
+ * own writes (an arrival, a reply's save, and a paused reply's save), which a durable store does
4
+ * in the same write as the item or the reply.
5
+ *
6
+ * @module
7
+ */
8
+ import type { ConversationInbox, InboxItem } from './types.js';
9
+ /** Options for {@link createMemoryInbox}. */
10
+ export interface MemoryInboxOptions {
11
+ /** How long a hold has a conversation after it opens or renews, in milliseconds. */
12
+ leaseMs: number;
13
+ /** The clock, in epoch milliseconds. */
14
+ now?: () => number;
15
+ }
16
+ /** The in-memory inbox, with the app's writes. */
17
+ export interface MemoryInbox<Item extends InboxItem> extends ConversationInbox<Item> {
18
+ /** Saves an item for the conversation, and moves its version. */
19
+ arrive(conversation: string, item: Item): void;
20
+ /**
21
+ * A reply's save: marks `ids` told by `reply`. Only while `hold` still has the conversation and
22
+ * `reply` was handed each id; false, and nothing marked, otherwise.
23
+ */
24
+ settle(conversation: string, hold: string, reply: string, ids: readonly string[]): boolean;
25
+ /**
26
+ * A paused reply's save: keeps `ids` with `reply` until a later reply resumes it, past any
27
+ * lease. Fenced as `settle` is.
28
+ */
29
+ pause(conversation: string, hold: string, reply: string, ids: readonly string[]): boolean;
30
+ /** Each item's state, for tests. */
31
+ states(conversation: string): ReadonlyMap<string, ItemState>;
32
+ }
33
+ /** Where an item is. */
34
+ export type ItemState = 'waiting' | 'handed' | 'paused' | 'told' | 'given_up';
35
+ /** Creates an in-memory {@link ConversationInbox}. */
36
+ export declare function createMemoryInbox<Item extends InboxItem>(options: MemoryInboxOptions): MemoryInbox<Item>;
@@ -0,0 +1,157 @@
1
+ /**
2
+ * A conversation inbox kept in memory, for tests and single-process apps. It also does the app's
3
+ * own writes (an arrival, a reply's save, and a paused reply's save), which a durable store does
4
+ * in the same write as the item or the reply.
5
+ *
6
+ * @module
7
+ */
8
+ /** Creates an in-memory {@link ConversationInbox}. */
9
+ export function createMemoryInbox(options) {
10
+ const now = options.now ?? Date.now;
11
+ const conversations = new Map();
12
+ const conversationOf = (key) => {
13
+ const found = conversations.get(key);
14
+ if (found)
15
+ return found;
16
+ const made = { leasedUntil: 0, version: 0, entries: new Map() };
17
+ conversations.set(key, made);
18
+ return made;
19
+ };
20
+ const has = (c, hold) => c.hold === hold && c.leasedUntil > now();
21
+ const heldLive = (c, entry) => entry.state === 'handed' && entry.holder !== undefined && has(c, entry.holder.hold);
22
+ /** Handed under a hold that lost the conversation. */
23
+ const lapsed = (c, entry) => entry.state === 'handed' && !heldLive(c, entry);
24
+ /** Waiting for any reply: never handed, given back, or lapsed and not a paused reply's. */
25
+ const readable = (c, entry) => entry.state === 'waiting' || (lapsed(c, entry) && entry.pausedWith === undefined);
26
+ /** Kept for the paused reply: paused, or resumed under a hold that lost the conversation. */
27
+ const keptFor = (c, entry, paused) => entry.pausedWith === paused && (entry.state === 'paused' || lapsed(c, entry));
28
+ /** The item as a reply sees it: the handovers before the current one. */
29
+ const view = (entry) => ({
30
+ ...entry.item,
31
+ handovers: entry.state === 'handed' ? entry.handovers.slice(0, -1) : [...entry.handovers],
32
+ });
33
+ const handedTo = (entry, hold, reply) => entry?.state === 'handed' && entry.holder?.hold === hold && entry.holder.reply === reply;
34
+ const handTo = (entry, hold, handover) => {
35
+ entry.state = 'handed';
36
+ entry.holder = { hold, reply: handover.reply };
37
+ entry.handovers.push({ ...handover, hold, at: now() });
38
+ };
39
+ const mark = (c, hold, reply, ids, state) => {
40
+ if (!has(c, hold))
41
+ return false;
42
+ if (!ids.every((id) => handedTo(c.entries.get(id), hold, reply)))
43
+ return false;
44
+ for (const id of ids) {
45
+ const entry = c.entries.get(id);
46
+ if (!entry)
47
+ continue;
48
+ entry.state = state;
49
+ entry.holder = undefined;
50
+ entry.pausedWith = state === 'paused' ? reply : undefined;
51
+ }
52
+ return true;
53
+ };
54
+ return {
55
+ open(conversation, hold) {
56
+ const c = conversationOf(conversation);
57
+ if (c.hold !== undefined && c.hold !== hold && c.leasedUntil > now()) {
58
+ return Promise.resolve({ outcome: 'held', leasedUntil: c.leasedUntil });
59
+ }
60
+ c.hold = hold;
61
+ c.leasedUntil = now() + options.leaseMs;
62
+ return Promise.resolve({ outcome: 'opened' });
63
+ },
64
+ takeOver(conversation, hold) {
65
+ const c = conversationOf(conversation);
66
+ c.hold = hold;
67
+ c.leasedUntil = now() + options.leaseMs;
68
+ return Promise.resolve();
69
+ },
70
+ renew(conversation, hold) {
71
+ const c = conversationOf(conversation);
72
+ if (!has(c, hold))
73
+ return Promise.resolve(false);
74
+ c.leasedUntil = now() + options.leaseMs;
75
+ return Promise.resolve(true);
76
+ },
77
+ read(conversation) {
78
+ const c = conversationOf(conversation);
79
+ const items = [...c.entries.values()].filter((entry) => readable(c, entry)).map(view);
80
+ return Promise.resolve({ items, version: String(c.version) });
81
+ },
82
+ hand(conversation, hold, handover, ids) {
83
+ const c = conversationOf(conversation);
84
+ if (!has(c, hold))
85
+ return Promise.resolve([]);
86
+ const handed = [];
87
+ for (const id of ids) {
88
+ const entry = c.entries.get(id);
89
+ if (!entry || !readable(c, entry))
90
+ continue;
91
+ handTo(entry, hold, handover);
92
+ handed.push(view(entry));
93
+ }
94
+ return Promise.resolve(handed);
95
+ },
96
+ giveBack(conversation, hold, reply, ids) {
97
+ const c = conversationOf(conversation);
98
+ for (const id of ids) {
99
+ const entry = c.entries.get(id);
100
+ if (!entry || !handedTo(entry, hold, reply))
101
+ continue;
102
+ entry.state = entry.pausedWith === undefined ? 'waiting' : 'paused';
103
+ entry.holder = undefined;
104
+ }
105
+ return Promise.resolve();
106
+ },
107
+ resume(conversation, hold, paused, handover) {
108
+ const c = conversationOf(conversation);
109
+ if (!has(c, hold))
110
+ return Promise.resolve([]);
111
+ const resumed = [];
112
+ for (const entry of c.entries.values()) {
113
+ if (!keptFor(c, entry, paused))
114
+ continue;
115
+ handTo(entry, hold, handover);
116
+ resumed.push(view(entry));
117
+ }
118
+ return Promise.resolve(resumed);
119
+ },
120
+ giveUp(conversation, hold, ids) {
121
+ const c = conversationOf(conversation);
122
+ if (!has(c, hold))
123
+ return Promise.resolve([]);
124
+ const given = [];
125
+ for (const id of ids) {
126
+ const entry = c.entries.get(id);
127
+ if (!entry || !readable(c, entry))
128
+ continue;
129
+ entry.state = 'given_up';
130
+ entry.holder = undefined;
131
+ given.push(view(entry));
132
+ }
133
+ return Promise.resolve(given);
134
+ },
135
+ release(conversation, hold, version) {
136
+ const c = conversationOf(conversation);
137
+ if (c.hold !== hold)
138
+ return Promise.resolve('lost');
139
+ if (String(c.version) !== version)
140
+ return Promise.resolve('moved');
141
+ c.hold = undefined;
142
+ c.leasedUntil = 0;
143
+ return Promise.resolve('released');
144
+ },
145
+ arrive(conversation, item) {
146
+ const c = conversationOf(conversation);
147
+ c.entries.set(item.id, { item, state: 'waiting', handovers: [...item.handovers] });
148
+ c.version += 1;
149
+ },
150
+ settle: (conversation, hold, reply, ids) => mark(conversationOf(conversation), hold, reply, ids, 'told'),
151
+ pause: (conversation, hold, reply, ids) => mark(conversationOf(conversation), hold, reply, ids, 'paused'),
152
+ states(conversation) {
153
+ const c = conversationOf(conversation);
154
+ return new Map([...c.entries].map(([id, entry]) => [id, entry.state]));
155
+ },
156
+ };
157
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * The conversation layer: one hold at a time reads a conversation's inbox, and an item reaches the
3
+ * model only through the hold, told once the reply that read it is saved. The app gives the
4
+ * storage (a {@link ConversationInbox}) and the rule for what may be told now (an
5
+ * {@link InboxPolicy}); {@link runConversation} runs each reply under a hold. No HTTP, no
6
+ * transcript. The scenarios every inbox must pass are in `@theoremjs/agents/conversation/testing`.
7
+ *
8
+ * @module
9
+ */
10
+ import "../../_dnt.polyfills.js";
11
+ export { createMemoryInbox, type ItemState, type MemoryInbox, type MemoryInboxOptions, } from './memory.js';
12
+ export { type RunConversationOptions, runConversation } from './run.js';
13
+ export type { ConversationInbox, ConversationRun, Handover, InboxItem, InboxPolicy, InboxRead, Opened, PolicyChoice, PolicyMoment, ReplyRun, ReplyStart, TakeAt, } from './types.js';
@@ -0,0 +1,12 @@
1
+ /**
2
+ * The conversation layer: one hold at a time reads a conversation's inbox, and an item reaches the
3
+ * model only through the hold, told once the reply that read it is saved. The app gives the
4
+ * storage (a {@link ConversationInbox}) and the rule for what may be told now (an
5
+ * {@link InboxPolicy}); {@link runConversation} runs each reply under a hold. No HTTP, no
6
+ * transcript. The scenarios every inbox must pass are in `@theoremjs/agents/conversation/testing`.
7
+ *
8
+ * @module
9
+ */
10
+ import "../../_dnt.polyfills.js";
11
+ export { createMemoryInbox, } from './memory.js';
12
+ export { runConversation } from './run.js';
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Runs one reply in a conversation under a hold: the reply reads what the policy lets it read as it
3
+ * opens and at each later moment, and the hold lets the conversation go only once nothing waits
4
+ * that may be told.
5
+ *
6
+ * @module
7
+ */
8
+ import type { ConversationInbox, ConversationRun, InboxItem, InboxPolicy, PolicyMoment, ReplyRun, ReplyStart } from './types.js';
9
+ /** Options for {@link runConversation}. */
10
+ export interface RunConversationOptions<Item extends InboxItem> {
11
+ conversation: string;
12
+ inbox: ConversationInbox<Item>;
13
+ policy: InboxPolicy<Item>;
14
+ start: ReplyStart;
15
+ /** Makes the ids of holds and replies. */
16
+ newId: () => string;
17
+ /** How often the hold renews its lease while the reply runs, in milliseconds. */
18
+ renewEveryMs: number;
19
+ /**
20
+ * The reply. Its save marks told what it told, and a paused save keeps what it read: both in the
21
+ * same write as the reply, and only while its hold still has the conversation. Whatever it read
22
+ * and neither told nor kept goes back for a later reply.
23
+ */
24
+ reply: (run: ReplyRun<Item>) => Promise<void>;
25
+ /** Called once with the items the policy gave up, at the moment it gave them up. */
26
+ gaveUp: (items: readonly Item[], moment: PolicyMoment) => Promise<void> | void;
27
+ }
28
+ /** Runs one reply under a hold of the conversation. See {@link ConversationRun}. */
29
+ export declare function runConversation<Item extends InboxItem>(options: RunConversationOptions<Item>): Promise<ConversationRun>;
@@ -0,0 +1,100 @@
1
+ /**
2
+ * Runs one reply in a conversation under a hold: the reply reads what the policy lets it read as it
3
+ * opens and at each later moment, and the hold lets the conversation go only once nothing waits
4
+ * that may be told.
5
+ *
6
+ * @module
7
+ */
8
+ /** Runs one reply under a hold of the conversation. See {@link ConversationRun}. */
9
+ export async function runConversation(options) {
10
+ const { conversation, inbox, start } = options;
11
+ const hold = start.opening === 'follow_up' ? start.hold : options.newId();
12
+ // why: A follow-up's hold is checked where it acts: handing, giving up, and before `continue`.
13
+ if (start.opening === 'message' && start.takeOver) {
14
+ await inbox.takeOver(conversation, hold);
15
+ }
16
+ else if (start.opening !== 'follow_up') {
17
+ const opened = await inbox.open(conversation, hold);
18
+ if (opened.outcome === 'held')
19
+ return opened;
20
+ }
21
+ const lease = new AbortController();
22
+ const renewing = setInterval(() => {
23
+ inbox.renew(conversation, hold).then((kept) => {
24
+ if (!kept)
25
+ lease.abort();
26
+ }, () => lease.abort());
27
+ }, options.renewEveryMs);
28
+ try {
29
+ const failure = await runReply(options, hold, lease.signal);
30
+ const ended = (run) => failure === undefined ? run : { ...run, failure: failure.thrown };
31
+ for (;;) {
32
+ if (lease.signal.aborted)
33
+ return ended({ outcome: 'lost' });
34
+ const { tell, version } = await choose(options, hold, {
35
+ stage: 'pre_turn',
36
+ step: 0,
37
+ opening: 'follow_up',
38
+ });
39
+ if (tell.length > 0) {
40
+ const kept = await inbox.renew(conversation, hold);
41
+ return ended(kept ? { outcome: 'continue', hold } : { outcome: 'lost' });
42
+ }
43
+ const released = await inbox.release(conversation, hold, version);
44
+ if (released === 'released')
45
+ return ended({ outcome: 'released' });
46
+ if (released === 'lost')
47
+ return ended({ outcome: 'lost' });
48
+ }
49
+ }
50
+ finally {
51
+ clearInterval(renewing);
52
+ }
53
+ }
54
+ /** Reads the inbox and asks the policy; gives up and reports what it gives up. */
55
+ async function choose(options, hold, moment) {
56
+ const { conversation, inbox } = options;
57
+ const { items, version } = await inbox.read(conversation);
58
+ const choice = await options.policy(items, moment);
59
+ if (choice.giveUp !== undefined && choice.giveUp.length > 0) {
60
+ const given = await inbox.giveUp(conversation, hold, choice.giveUp);
61
+ if (given.length > 0)
62
+ await options.gaveUp(given, moment);
63
+ }
64
+ return { tell: choice.tell, version };
65
+ }
66
+ /** Runs the reply, gives back what it read and did not tell, and returns what it threw. */
67
+ async function runReply(options, hold, signal) {
68
+ const { conversation, inbox, start } = options;
69
+ const reply = options.newId();
70
+ const handed = new Set();
71
+ const kept = (items) => {
72
+ for (const item of items)
73
+ handed.add(item.id);
74
+ return items;
75
+ };
76
+ const take = async (at) => {
77
+ if (signal.aborted)
78
+ return [];
79
+ const { tell } = await choose(options, hold, { ...at, opening: start.opening });
80
+ if (tell.length === 0)
81
+ return [];
82
+ return kept(await inbox.hand(conversation, hold, { reply, ...at }, tell));
83
+ };
84
+ const resume = async (paused) => kept(await inbox.resume(conversation, hold, paused, { reply, stage: 'pre_turn', step: 0 }));
85
+ try {
86
+ const opened = await take({ stage: 'pre_turn', step: 0 });
87
+ if (start.opening !== 'message' && opened.length === 0)
88
+ return undefined;
89
+ await options.reply({ hold, reply, opening: start.opening, opened, take, resume, signal });
90
+ return undefined;
91
+ }
92
+ catch (thrown) {
93
+ return { thrown };
94
+ }
95
+ finally {
96
+ // invariant: Told and paused items are past giving back; the rest go back with this handover kept.
97
+ if (handed.size > 0)
98
+ await inbox.giveBack(conversation, hold, reply, [...handed]);
99
+ }
100
+ }
@@ -0,0 +1,36 @@
1
+ /**
2
+ * Scenarios any conversation inbox must pass under {@link runConversation}: an item arrives at each
3
+ * moment a reply can be in, and each is told exactly once, given up and reported once, or left for
4
+ * a hold that still has the conversation.
5
+ *
6
+ * @module
7
+ */
8
+ import "../../_dnt.polyfills.js";
9
+ import type { ConversationInbox, InboxItem } from './types.js';
10
+ /** One inbox for one scenario, with the app's own writes. */
11
+ export interface ScenarioHarness<Item extends InboxItem> {
12
+ inbox: ConversationInbox<Item>;
13
+ conversation: string;
14
+ /** Saves an item with this id, as the app does when one arrives. */
15
+ arrive(id: string): Promise<void>;
16
+ /** A reply's save: marks `ids` told by `reply`. False when the hold no longer has it. */
17
+ settle(hold: string, reply: string, ids: readonly string[]): Promise<boolean>;
18
+ /** A paused reply's save: keeps `ids` with `reply`. False when the hold no longer has it. */
19
+ pause(hold: string, reply: string, ids: readonly string[]): Promise<boolean>;
20
+ /** Moves the clock past every lease. */
21
+ lapse(): Promise<void>;
22
+ /** The ids told so far, once for each time one was told. */
23
+ told(): Promise<readonly string[]>;
24
+ }
25
+ /** One scenario: `run` throws when the inbox fails it. */
26
+ export interface ConversationScenario {
27
+ name: string;
28
+ run(): Promise<void>;
29
+ }
30
+ /** Options for {@link conversationScenarios}. */
31
+ export interface ConversationScenariosOptions<Item extends InboxItem> {
32
+ /** A fresh harness for each scenario. */
33
+ makeHarness(): Promise<ScenarioHarness<Item>>;
34
+ }
35
+ /** The scenarios, each on a fresh harness from `options.makeHarness`. */
36
+ export declare function conversationScenarios<Item extends InboxItem>(options: ConversationScenariosOptions<Item>): ConversationScenario[];
@@ -0,0 +1,366 @@
1
+ /**
2
+ * Scenarios any conversation inbox must pass under {@link runConversation}: an item arrives at each
3
+ * moment a reply can be in, and each is told exactly once, given up and reported once, or left for
4
+ * a hold that still has the conversation.
5
+ *
6
+ * @module
7
+ */
8
+ import "../../_dnt.polyfills.js";
9
+ import { runConversation } from './run.js';
10
+ /** Long enough that no renewal runs inside a scenario; a scenario lapses the lease itself. */
11
+ const RENEW_EVERY_MS = 60_000;
12
+ const newId = () => crypto.randomUUID();
13
+ const idsOf = (items) => items.map((item) => item.id);
14
+ const tellAll = (items) => ({ tell: idsOf(items) });
15
+ function fail(message) {
16
+ throw new Error(message);
17
+ }
18
+ function expectOutcome(run, outcome, when) {
19
+ if (run.outcome !== outcome)
20
+ fail(`${when}: the run ended ${run.outcome}, not ${outcome}`);
21
+ }
22
+ /** A scenario's harness, with the runs it makes and what was given up. */
23
+ class Scene {
24
+ h;
25
+ gaveUp = [];
26
+ constructor(h) {
27
+ this.h = h;
28
+ }
29
+ /** One run whose reply does `body`, by default telling all it read. */
30
+ run(start, body = (reply) => this.tellRead(reply, []), policy = tellAll) {
31
+ return runConversation({
32
+ conversation: this.h.conversation,
33
+ inbox: this.h.inbox,
34
+ policy,
35
+ start,
36
+ newId,
37
+ renewEveryMs: RENEW_EVERY_MS,
38
+ reply: body,
39
+ gaveUp: (items) => {
40
+ this.gaveUp.push(...idsOf(items));
41
+ },
42
+ });
43
+ }
44
+ /** Saves the reply, telling what it opened with and `later`. */
45
+ async tellRead(reply, later) {
46
+ const read = idsOf([...reply.opened, ...later]);
47
+ if (!(await this.h.settle(reply.hold, reply.reply, read)))
48
+ fail('the save was turned away');
49
+ }
50
+ /** Runs follow-ups until the conversation is let go. */
51
+ async drain(first) {
52
+ let last = first;
53
+ for (let turns = 0; last.outcome === 'continue'; turns += 1) {
54
+ if (turns > 3)
55
+ fail('the follow-ups did not end');
56
+ last = await this.run({ opening: 'follow_up', hold: last.hold });
57
+ }
58
+ expectOutcome(last, 'released', 'after the follow-ups');
59
+ }
60
+ async expectTold(expected) {
61
+ const told = await this.h.told();
62
+ for (const id of expected) {
63
+ const times = told.filter((each) => each === id).length;
64
+ if (times !== 1)
65
+ fail(`${id} was told ${times} times, not once`);
66
+ }
67
+ const extra = told.filter((id) => !expected.includes(id));
68
+ if (extra.length > 0)
69
+ fail(`told what it should not have: ${extra.join(', ')}`);
70
+ }
71
+ async expectUnread() {
72
+ const { items } = await this.h.inbox.read(this.h.conversation);
73
+ if (items.length > 0)
74
+ fail(`still waiting: ${idsOf(items).join(', ')}`);
75
+ }
76
+ }
77
+ /** Answers the paused reply: the reply that goes on resumes it, tells what it got, and is saved. */
78
+ async function answerPaused(s, paused, told, label) {
79
+ const answered = await s.run({ opening: 'message' }, async (reply) => s.tellRead(reply, await reply.resume(paused)));
80
+ expectOutcome(answered, 'released', label);
81
+ await s.expectTold(told);
82
+ }
83
+ /** Runs a wake whose reply pauses with what it opened with; returns the paused reply. */
84
+ async function pauseWith(s) {
85
+ let paused;
86
+ const ran = await s.run({ opening: 'wake' }, async (reply) => {
87
+ paused = reply.reply;
88
+ if (!(await s.h.pause(reply.hold, reply.reply, idsOf(reply.opened)))) {
89
+ fail('the pause was turned away');
90
+ }
91
+ });
92
+ expectOutcome(ran, 'released', 'the paused wake');
93
+ if (paused === undefined)
94
+ fail('the reply did not pause');
95
+ return paused;
96
+ }
97
+ /** The scenarios, each on a fresh harness from `options.makeHarness`. */
98
+ export function conversationScenarios(options) {
99
+ const scenario = (name, body) => ({
100
+ name,
101
+ run: async () => body(new Scene(await options.makeHarness())),
102
+ });
103
+ return [
104
+ scenario('an item that arrives before a reply is told as it opens', async (s) => {
105
+ await s.h.arrive('a');
106
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'the wake');
107
+ await s.expectTold(['a']);
108
+ }),
109
+ scenario('a wake with nothing waiting runs no reply and lets the conversation go', async (s) => {
110
+ let replied = false;
111
+ const ran = await s.run({ opening: 'wake' }, () => {
112
+ replied = true;
113
+ return Promise.resolve();
114
+ });
115
+ expectOutcome(ran, 'released', 'the wake');
116
+ if (replied)
117
+ fail('a wake with nothing waiting ran a reply');
118
+ expectOutcome(await s.run({ opening: 'message' }), 'released', 'the next message');
119
+ }),
120
+ scenario('an item that arrives during a step is read at the next moment', async (s) => {
121
+ const ran = await s.run({ opening: 'message' }, async (reply) => {
122
+ await s.h.arrive('b');
123
+ await s.tellRead(reply, await reply.take({ stage: 'post_tool', step: 1 }));
124
+ });
125
+ expectOutcome(ran, 'released', 'the message');
126
+ await s.expectTold(['b']);
127
+ }),
128
+ scenario('an item that arrives while the reply saves is told by a follow-up', async (s) => {
129
+ const ran = await s.run({ opening: 'message' }, async (reply) => {
130
+ await s.h.arrive('c');
131
+ if (await s.h.settle(reply.hold, reply.reply, ['c']))
132
+ fail('saved an item it never read');
133
+ await s.tellRead(reply, []);
134
+ });
135
+ expectOutcome(ran, 'continue', 'the message');
136
+ await s.drain(ran);
137
+ await s.expectTold(['c']);
138
+ }),
139
+ scenario('an item that arrives as the hold lets go keeps the conversation', async (s) => {
140
+ const inbox = s.h.inbox;
141
+ let arrived = false;
142
+ const racing = new Scene({
143
+ ...s.h,
144
+ inbox: {
145
+ open: (c, hold) => inbox.open(c, hold),
146
+ takeOver: (c, hold) => inbox.takeOver(c, hold),
147
+ renew: (c, hold) => inbox.renew(c, hold),
148
+ read: (c) => inbox.read(c),
149
+ hand: (c, hold, handover, ids) => inbox.hand(c, hold, handover, ids),
150
+ giveBack: (c, hold, reply, ids) => inbox.giveBack(c, hold, reply, ids),
151
+ resume: (c, hold, paused, handover) => inbox.resume(c, hold, paused, handover),
152
+ giveUp: (c, hold, ids) => inbox.giveUp(c, hold, ids),
153
+ release: async (c, hold, version) => {
154
+ if (!arrived) {
155
+ arrived = true;
156
+ await s.h.arrive('d');
157
+ }
158
+ return inbox.release(c, hold, version);
159
+ },
160
+ },
161
+ });
162
+ const ran = await racing.run({ opening: 'message' });
163
+ expectOutcome(ran, 'continue', 'the message');
164
+ await racing.drain(ran);
165
+ await s.expectTold(['d']);
166
+ }),
167
+ scenario('a wake that finds a reply running is told once that reply ends', async (s) => {
168
+ let woke;
169
+ const ran = await s.run({ opening: 'message' }, async (reply) => {
170
+ await s.h.arrive('e');
171
+ woke = await s.run({ opening: 'wake' });
172
+ await s.tellRead(reply, []);
173
+ });
174
+ if (woke === undefined)
175
+ fail('the wake did not run');
176
+ expectOutcome(woke, 'held', 'the wake');
177
+ expectOutcome(ran, 'continue', 'the message');
178
+ await s.drain(ran);
179
+ await s.expectTold(['e']);
180
+ }),
181
+ scenario('two replies that open at once never run together', async (s) => {
182
+ await s.h.arrive('f');
183
+ let running = 0;
184
+ const body = async (reply) => {
185
+ running += 1;
186
+ if (running > 1)
187
+ fail('two replies ran at once');
188
+ await new Promise((resolve) => setTimeout(resolve, 1));
189
+ await s.tellRead(reply, []);
190
+ running -= 1;
191
+ };
192
+ const both = await Promise.all([
193
+ s.run({ opening: 'message' }, body),
194
+ s.run({ opening: 'message' }, body),
195
+ ]);
196
+ for (const ran of both) {
197
+ if (ran.outcome === 'continue')
198
+ await s.drain(ran);
199
+ else if (ran.outcome !== 'held' && ran.outcome !== 'released') {
200
+ fail(`a racing reply ended ${ran.outcome}`);
201
+ }
202
+ }
203
+ await s.expectTold(['f']);
204
+ }),
205
+ scenario('an item a paused reply read waits for it, and is told once it goes on', async (s) => {
206
+ await s.h.arrive('g');
207
+ const paused = await pauseWith(s);
208
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'a wake during the pause');
209
+ await s.h.lapse();
210
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'a wake after the lease');
211
+ await s.expectTold([]);
212
+ await answerPaused(s, paused, ['g'], 'the answer');
213
+ }),
214
+ scenario('a resumed reply that fails leaves the item with the paused reply', async (s) => {
215
+ await s.h.arrive('h');
216
+ const paused = await pauseWith(s);
217
+ const failed = await s.run({ opening: 'message' }, async (reply) => {
218
+ await reply.resume(paused);
219
+ throw new Error('the model failed');
220
+ });
221
+ expectOutcome(failed, 'released', 'the failed answer');
222
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'a wake after the failure');
223
+ await s.expectUnread();
224
+ await answerPaused(s, paused, ['h'], 'the second answer');
225
+ }),
226
+ scenario('a resumed reply that pauses again keeps the item for its own pause', async (s) => {
227
+ await s.h.arrive('i');
228
+ const first = await pauseWith(s);
229
+ let second;
230
+ await s.run({ opening: 'message' }, async (reply) => {
231
+ const resumed = await reply.resume(first);
232
+ second = reply.reply;
233
+ if (!(await s.h.pause(reply.hold, reply.reply, idsOf(resumed))))
234
+ fail('pause turned away');
235
+ });
236
+ if (second === undefined)
237
+ fail('the answer did not pause');
238
+ const again = second;
239
+ await s.run({ opening: 'message' }, async (reply) => {
240
+ if ((await reply.resume(first)).length > 0)
241
+ fail('the first pause still had the item');
242
+ await s.tellRead(reply, await reply.resume(again));
243
+ });
244
+ await s.expectTold(['i']);
245
+ }),
246
+ scenario('a reply whose lease ran out cannot save what another hold told', async (s) => {
247
+ await s.h.arrive('j');
248
+ let late;
249
+ const first = await s.run({ opening: 'wake' }, async (reply) => {
250
+ await s.h.lapse();
251
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'the second hold');
252
+ late = await s.h.settle(reply.hold, reply.reply, idsOf(reply.opened));
253
+ });
254
+ if (late !== false)
255
+ fail('the first hold saved after its lease ran out');
256
+ expectOutcome(first, 'lost', 'the first hold');
257
+ await s.expectTold(['j']);
258
+ }),
259
+ scenario('of two replies whose holds overlap, at most one saves', async (s) => {
260
+ await s.h.arrive('k');
261
+ let late;
262
+ let second;
263
+ const first = await s.run({ opening: 'wake' }, async (reply) => {
264
+ await s.h.lapse();
265
+ // why: The second reply reads nothing as it runs, so only the fences stand between them.
266
+ const ran = await s.run({ opening: 'message' }, async (own) => {
267
+ if ((await reply.take({ stage: 'post_tool', step: 1 })).length > 0) {
268
+ fail('a hold that lost its lease took an item');
269
+ }
270
+ late = await s.h.settle(reply.hold, reply.reply, idsOf(reply.opened));
271
+ second = await s.h.settle(own.hold, own.reply, []);
272
+ }, (items, moment) => ({ tell: moment.opening === 'follow_up' ? idsOf(items) : [] }));
273
+ await s.drain(ran);
274
+ });
275
+ if (late === undefined || second === undefined)
276
+ fail('the replies did not save');
277
+ if (late && second)
278
+ fail('both replies saved');
279
+ expectOutcome(first, 'lost', 'the first hold');
280
+ await s.expectTold(['k']);
281
+ }),
282
+ scenario('a message takes the conversation from a running wake, and tells what it read', async (s) => {
283
+ await s.h.arrive('q');
284
+ let late;
285
+ const woke = await s.run({ opening: 'wake' }, async (reply) => {
286
+ const message = await s.run({ opening: 'message', takeOver: true });
287
+ expectOutcome(message, 'released', 'the message');
288
+ late = await s.h.settle(reply.hold, reply.reply, idsOf(reply.opened));
289
+ });
290
+ if (late !== false)
291
+ fail('the wake saved after a message took the conversation');
292
+ expectOutcome(woke, 'lost', 'the wake');
293
+ await s.expectTold(['q']);
294
+ }),
295
+ scenario('a hold that lost its lease ends lost, and the next hold tells what came', async (s) => {
296
+ const first = await s.run({ opening: 'message' }, async (reply) => {
297
+ await s.h.lapse();
298
+ await s.h.arrive('l');
299
+ // why: Whether a lapsed hold may still save depends on the store's fences; either way it ends lost.
300
+ await s.h.settle(reply.hold, reply.reply, []);
301
+ });
302
+ if (first.outcome !== 'lost')
303
+ fail(`the lapsed message ended ${first.outcome}, not lost`);
304
+ if (first.failure !== undefined)
305
+ fail('the lapsed message failed');
306
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'the next wake');
307
+ await s.expectTold(['l']);
308
+ }),
309
+ scenario('a follow-up under a hold that lapsed ends lost, and runs no reply', async (s) => {
310
+ const first = await s.run({ opening: 'message' }, async (reply) => {
311
+ await s.h.arrive('m');
312
+ await s.tellRead(reply, []);
313
+ });
314
+ if (first.outcome !== 'continue')
315
+ fail(`the message ended ${first.outcome}, not continue`);
316
+ await s.h.lapse();
317
+ let replied = false;
318
+ const late = await s.run({ opening: 'follow_up', hold: first.hold }, () => {
319
+ replied = true;
320
+ return Promise.resolve();
321
+ });
322
+ expectOutcome(late, 'lost', 'the late follow-up');
323
+ if (replied)
324
+ fail('a follow-up ran a reply under a hold it lost');
325
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'the next wake');
326
+ await s.expectTold(['m']);
327
+ }),
328
+ scenario('a reply that throws gives back what it read, with its handover', async (s) => {
329
+ await s.h.arrive('n');
330
+ const thrown = new Error('the model failed');
331
+ const ran = await s.run({ opening: 'wake' }, () => Promise.reject(thrown));
332
+ if (ran.outcome !== 'continue')
333
+ fail(`the failed wake ended ${ran.outcome}, not continue`);
334
+ if (ran.failure !== thrown)
335
+ fail('the failure was not returned');
336
+ const { items } = await s.h.inbox.read(s.h.conversation);
337
+ const back = items.find((item) => item.id === 'n');
338
+ if (back === undefined)
339
+ fail('the item was not given back');
340
+ if (back.handovers.length !== 1)
341
+ fail(`the item has ${back.handovers.length} handovers, not 1`);
342
+ await s.drain(ran);
343
+ await s.expectTold(['n']);
344
+ }),
345
+ scenario('an item a reply fails on is given up once the policy says so', async (s) => {
346
+ await s.h.arrive('o');
347
+ const twice = (items) => ({
348
+ tell: idsOf(items.filter((item) => item.handovers.length < 2)),
349
+ giveUp: idsOf(items.filter((item) => item.handovers.length >= 2)),
350
+ });
351
+ const failing = () => Promise.reject(new Error('the model failed'));
352
+ let last = await s.run({ opening: 'wake' }, failing, twice);
353
+ for (let turns = 0; last.outcome === 'continue'; turns += 1) {
354
+ if (turns > 3)
355
+ fail('the failing follow-ups did not end');
356
+ last = await s.run({ opening: 'follow_up', hold: last.hold }, failing, twice);
357
+ }
358
+ expectOutcome(last, 'released', 'after giving up');
359
+ if (s.gaveUp.join() !== 'o')
360
+ fail(`gave up ${s.gaveUp.join() || 'nothing'}, not o once`);
361
+ await s.expectUnread();
362
+ expectOutcome(await s.run({ opening: 'wake' }), 'released', 'a wake after giving up');
363
+ await s.expectTold([]);
364
+ }),
365
+ ];
366
+ }
@@ -0,0 +1,173 @@
1
+ /**
2
+ * The conversation layer's contract: what an app's storage gives the runner, and what the runner
3
+ * gives the app's reply. One holder at a time reads a conversation's inbox; an item reaches the
4
+ * model only through the holder, and is told once the reply that read it is saved.
5
+ *
6
+ * @module
7
+ */
8
+ import type { TurnInjectStage } from '../kernel/schema.js';
9
+ /** A reply an item was handed to, which did not tell it. */
10
+ export interface Handover {
11
+ /** The hold the reply ran under. One hold can run several replies. */
12
+ hold: string;
13
+ /** The reply it was handed to. */
14
+ reply: string;
15
+ stage: TurnInjectStage;
16
+ /** The model steps the reply had taken when it was handed; 0 as it opened. */
17
+ step: number;
18
+ /** Epoch milliseconds. */
19
+ at: number;
20
+ }
21
+ /**
22
+ * Something saved for a conversation that no saved reply has told: a call's late result, a due
23
+ * reminder, a fact from outside. The app names the kinds.
24
+ */
25
+ export interface InboxItem<Kind extends string = string> {
26
+ id: string;
27
+ kind: Kind;
28
+ /**
29
+ * Each reply it was handed to that ended without telling it, oldest first. A reply that reads it
30
+ * again can say what came of those earlier ones.
31
+ */
32
+ handovers: readonly Handover[];
33
+ }
34
+ /** What `open` finds: the conversation is now this hold's, or another hold has it until then. */
35
+ export type Opened = {
36
+ outcome: 'opened';
37
+ } | {
38
+ outcome: 'held';
39
+ leasedUntil: number;
40
+ };
41
+ /** The items `read` returns, and the inbox's version as it read them. */
42
+ export interface InboxRead<Item extends InboxItem> {
43
+ items: readonly Item[];
44
+ /** Moves each time an item arrives. `release` compares it. */
45
+ version: string;
46
+ }
47
+ /** Where a reply takes items: the moment, and the reply's step. */
48
+ export interface TakeAt {
49
+ stage: TurnInjectStage;
50
+ step: number;
51
+ }
52
+ /**
53
+ * The app's storage for its conversations: one lock and one inbox each. An item arrives through the
54
+ * app's own write, which moves the version. The reply's own save marks the items it told, in the
55
+ * same write as the reply, and only while its hold still has the conversation.
56
+ */
57
+ export interface ConversationInbox<Item extends InboxItem = InboxItem> {
58
+ /** Takes the conversation for `hold`, on a lease, or says until when another hold has it. */
59
+ open(conversation: string, hold: string): Promise<Opened>;
60
+ /**
61
+ * Takes the conversation for `hold` from any hold that has it, as a person's message does. The
62
+ * hold that had it can no longer renew, hand, or save, and what it was handed waits again.
63
+ */
64
+ takeOver(conversation: string, hold: string): Promise<void>;
65
+ /** Extends `hold`'s lease. False when the hold no longer has the conversation. */
66
+ renew(conversation: string, hold: string): Promise<boolean>;
67
+ /**
68
+ * The untold items no live hold has: those never handed, those given back, and those handed
69
+ * under a hold whose lease ran out. Items a paused reply holds are not among them.
70
+ */
71
+ read(conversation: string): Promise<InboxRead<Item>>;
72
+ /**
73
+ * Hands `ids` to `reply` under `hold`, and returns the items it handed. Only the hold that has
74
+ * the conversation can hand. The version does not move.
75
+ */
76
+ hand(conversation: string, hold: string, handover: Omit<Handover, 'hold' | 'at'>, ids: readonly string[]): Promise<readonly Item[]>;
77
+ /**
78
+ * Gives back the items `reply` read and did not tell, because it ended unsaved: an item it
79
+ * resumed goes back to the reply that paused with it, and the rest wait for a later reply. Each
80
+ * keeps the handover, so a later reply knows. The version does not move.
81
+ */
82
+ giveBack(conversation: string, hold: string, reply: string, ids: readonly string[]): Promise<void>;
83
+ /**
84
+ * Hands what a paused reply kept to `handover.reply`, as it goes on, and returns those items.
85
+ * Only the hold that has the conversation can resume.
86
+ */
87
+ resume(conversation: string, hold: string, paused: string, handover: Omit<Handover, 'hold' | 'at'>): Promise<readonly Item[]>;
88
+ /**
89
+ * Gives up the items among `ids` that no live hold has: no reply reads them again. Returns
90
+ * those it gave up. Only the hold that has the conversation can give up.
91
+ */
92
+ giveUp(conversation: string, hold: string, ids: readonly string[]): Promise<readonly Item[]>;
93
+ /**
94
+ * Lets the conversation go, only while the inbox is still at `version`. `moved` when an item
95
+ * arrived since: `hold` keeps the conversation and reads again. `lost` when `hold` no longer
96
+ * has it.
97
+ */
98
+ release(conversation: string, hold: string, version: string): Promise<'released' | 'moved' | 'lost'>;
99
+ }
100
+ /**
101
+ * What opens a reply. A `message` or a `wake` opens the conversation under a new hold; a message
102
+ * with `takeOver` takes it from any hold that has it. A `follow_up` runs under the hold a run
103
+ * before it returned with `continue`.
104
+ */
105
+ export type ReplyStart = {
106
+ opening: 'message';
107
+ takeOver?: boolean;
108
+ } | {
109
+ opening: 'wake';
110
+ } | {
111
+ opening: 'follow_up';
112
+ hold: string;
113
+ };
114
+ /** When the policy is asked: the moment, and what opened the reply. */
115
+ export interface PolicyMoment extends TakeAt {
116
+ /**
117
+ * `message` for a reply to the person's message, `wake` for a reply to no message, and
118
+ * `follow_up` at the end of a hold's reply, for items that arrived while it ran.
119
+ */
120
+ opening: 'message' | 'wake' | 'follow_up';
121
+ }
122
+ /**
123
+ * What the policy chose among the items: those the model reads now, and those no reply will read.
124
+ * The rest stay for later.
125
+ */
126
+ export interface PolicyChoice {
127
+ tell: readonly string[];
128
+ /** Items to give up, such as one a reply failed on too many times. They are reported once. */
129
+ giveUp?: readonly string[];
130
+ }
131
+ /**
132
+ * The app's rule for what may be told now. It must change nothing: the runner asks it again at
133
+ * each moment.
134
+ */
135
+ export type InboxPolicy<Item extends InboxItem = InboxItem> = (items: readonly Item[], moment: PolicyMoment) => PolicyChoice | Promise<PolicyChoice>;
136
+ /** One reply under a hold, as the runner gives it to the app. */
137
+ export interface ReplyRun<Item extends InboxItem = InboxItem> {
138
+ hold: string;
139
+ reply: string;
140
+ opening: PolicyMoment['opening'];
141
+ /** The items the reply reads as it opens. */
142
+ opened: readonly Item[];
143
+ /** The items the reply reads at this later moment, handed to it as they are returned. */
144
+ take(at: TakeAt): Promise<readonly Item[]>;
145
+ /**
146
+ * What the paused reply kept, handed to this reply as it goes on. If this reply ends without
147
+ * telling them, they go back to the paused reply.
148
+ */
149
+ resume(paused: string): Promise<readonly Item[]>;
150
+ /** Aborts once the hold no longer has the conversation: the reply must not save. */
151
+ signal: AbortSignal;
152
+ }
153
+ /**
154
+ * What one run of a conversation ended with. `held`: another hold has it, and tells what waits.
155
+ * `released`: nothing waits that may be told now. `continue`: items wait that may be told now, and
156
+ * the hold keeps the conversation for the caller's next reply. `lost`: the hold no longer has the
157
+ * conversation, so another hold tells what waits. `failure` is what the reply threw: its items were given
158
+ * back, and the caller reports it.
159
+ */
160
+ export type ConversationRun = {
161
+ outcome: 'held';
162
+ leasedUntil: number;
163
+ } | {
164
+ outcome: 'released';
165
+ failure?: unknown;
166
+ } | {
167
+ outcome: 'continue';
168
+ hold: string;
169
+ failure?: unknown;
170
+ } | {
171
+ outcome: 'lost';
172
+ failure?: unknown;
173
+ };
@@ -0,0 +1,8 @@
1
+ /**
2
+ * The conversation layer's contract: what an app's storage gives the runner, and what the runner
3
+ * gives the app's reply. One holder at a time reads a conversation's inbox; an item reaches the
4
+ * model only through the holder, and is told once the reply that read it is saved.
5
+ *
6
+ * @module
7
+ */
8
+ export {};
@@ -70,6 +70,7 @@ export interface ProfileImageSpec {
70
70
  */
71
71
  includeText?: boolean;
72
72
  }
73
+ import type { InboxItem, InboxPolicy } from '../conversation/types.js';
73
74
  import type { DecisionModelBinding, ModelBinding } from './protocols/binding.js';
74
75
  import type { ProviderHostOptions } from './protocols/runtime.js';
75
76
  export type { DecisionModelBinding, ModelBinding };
@@ -1270,13 +1271,12 @@ export interface LateResult {
1270
1271
  operationId: string;
1271
1272
  outcome: ToolOperationOutcome;
1272
1273
  }
1273
- /** A chat's ended results that no reply has read, as a {@linkcode LateResultsDecider} is asked. */
1274
- export interface LateResultsAsk {
1275
- /** The turn's `host`: what the app makes of the request. */
1276
- host: unknown;
1277
- /** The conversation reference the page holds. */
1278
- conversation: string;
1279
- results: readonly LateResult[];
1274
+ /**
1275
+ * A background call's end in a chat's inbox: the item a {@linkcode LateResultsDecider}'s policy
1276
+ * reads. Its `id` is the call's `operationId`.
1277
+ */
1278
+ export interface LateResultItem extends InboxItem<'late_result'> {
1279
+ outcome: ToolOperationOutcome;
1280
1280
  }
1281
1281
  /** A background call ended, and what Theorem lets the decider do about it. */
1282
1282
  export interface LateResultEnded {
@@ -1284,34 +1284,29 @@ export interface LateResultEnded {
1284
1284
  host: unknown;
1285
1285
  result: LateResult;
1286
1286
  /**
1287
- * Runs a reply to no message in `conversation`, as a page's wake does: the decider's `give` is
1288
- * asked with `reason: 'wake'`. It runs nothing while a reply waits on gates or answers a
1289
- * message, and a message posted meanwhile wins. The reference must stay the same across
1290
- * writes, so a store whose reference changes with each write cannot wake from the server.
1287
+ * Runs a reply to no message in `conversation`, as a page's wake does, for what the policy tells
1288
+ * at `opening: 'wake'`. While another reply holds the chat, that reply's hold tells what waits
1289
+ * as it ends, and this wake tries once more when the hold's lease runs out. The reference must
1290
+ * stay the same across writes, so a store whose reference changes with each write cannot wake
1291
+ * from the server.
1291
1292
  */
1292
1293
  wake(conversation: string): Promise<void>;
1293
1294
  /** Tells the pages open on the session to read the chat again. */
1294
1295
  notify(): Promise<void>;
1295
1296
  }
1296
1297
  /**
1297
- * Who tells the model that a background call ended. Theorem runs; the decider decides, and it
1298
- * keeps its own count of what it told, such as a cap or quiet hours.
1298
+ * Who tells the model that a background call ended. Theorem runs the replies under a hold of the
1299
+ * chat; the decider's policy chooses what each reply reads, and it keeps its own count of what it
1300
+ * told, such as a cap or quiet hours.
1299
1301
  */
1300
1302
  export interface LateResultsDecider {
1301
1303
  /**
1302
- * The results a reply gives the model, by `operationId`. `reason` is `'message'` for a reply to
1303
- * the person's message and `'wake'` for a reply to no message. Asked once for each reply, before
1304
- * its model runs. The model reads each result you return once. One you leave out stays for a
1305
- * later reply. A wake you give nothing runs no reply and leaves no mark.
1306
- */
1307
- give(ask: LateResultsAsk & {
1308
- reason: 'message' | 'wake';
1309
- }): readonly string[] | Promise<readonly string[]>;
1310
- /**
1311
- * Whether a page open on the chat wakes it now. Asked each time a page reads the chat, so it
1312
- * must change nothing. Say yes only when `give` would give something. Unset, no page wakes it.
1304
+ * What a reply reads now, and what no reply reads again. Asked as a reply opens, at its later
1305
+ * moments, as its hold ends (`opening: 'follow_up'`), and each time a page reads the chat
1306
+ * (`opening: 'wake'`, to say whether the page wakes it). It must change nothing. A result it
1307
+ * leaves waits for a later reply; one it gives up is reported once to `onError`.
1313
1308
  */
1314
- due?(ask: LateResultsAsk): boolean | Promise<boolean>;
1309
+ policy: InboxPolicy<LateResultItem>;
1315
1310
  /** A background call ended. Use `wake` to reply from the server, with no page open. */
1316
1311
  ended?(ended: LateResultEnded): void | Promise<void>;
1317
1312
  }
@@ -1336,8 +1331,8 @@ export interface TurnWiring {
1336
1331
  /**
1337
1332
  * Who tells the model that a background call ended, and when. Theorem runs the replies; this
1338
1333
  * decides. Unset, the model is never told: no page wakes the chat, and no reply reads a late
1339
- * result. `pageWakes` from `@theoremjs/web/server` lets the open page wake the chat, for an app
1340
- * with no server of its own.
1334
+ * result. `tellEveryResult` from `@theoremjs/web/server` tells each result to the first reply
1335
+ * that runs, and lets the open page wake the chat, for an app with no server of its own.
1341
1336
  */
1342
1337
  lateResultsDecider?: LateResultsDecider;
1343
1338
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.935.ga3dc485",
3
+ "version": "0.3.5-next.938.g3cbd0dd",
4
4
  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
5
5
  "keywords": [
6
6
  "agent",
@@ -67,6 +67,12 @@
67
67
  },
68
68
  "./evals": {
69
69
  "import": "./esm/src/evals/mod.js"
70
+ },
71
+ "./conversation": {
72
+ "import": "./esm/src/conversation/mod.js"
73
+ },
74
+ "./conversation/testing": {
75
+ "import": "./esm/src/conversation/testing.js"
70
76
  }
71
77
  },
72
78
  "scripts": {},