@theoremjs/agents 0.3.5-next.933.gfc0e83b → 0.3.5-next.936.ga984349
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 +2 -0
- package/esm/src/conversation/memory.d.ts +36 -0
- package/esm/src/conversation/memory.js +157 -0
- package/esm/src/conversation/mod.d.ts +13 -0
- package/esm/src/conversation/mod.js +12 -0
- package/esm/src/conversation/run.d.ts +29 -0
- package/esm/src/conversation/run.js +100 -0
- package/esm/src/conversation/testing.d.ts +36 -0
- package/esm/src/conversation/testing.js +366 -0
- package/esm/src/conversation/types.d.ts +173 -0
- package/esm/src/conversation/types.js +8 -0
- package/esm/src/guardrails/labels.js +1 -1
- package/esm/src/guardrails/tool-fence.d.ts +9 -4
- package/esm/src/guardrails/tool-fence.js +16 -5
- package/esm/src/interface/blocks.js +1 -0
- package/esm/src/interface/history.js +2 -2
- package/esm/src/interface/types.d.ts +3 -1
- package/esm/src/kernel/api-catalog.js +4 -4
- package/esm/src/kernel/engine/compaction.js +4 -2
- package/esm/src/kernel/engine/runner/gates.js +1 -1
- package/esm/src/kernel/engine/runner/mod.js +8 -6
- package/esm/src/kernel/engine/runner/stages.d.ts +22 -1
- package/esm/src/kernel/engine/runner/stages.js +58 -3
- package/esm/src/kernel/engine/runner/state.d.ts +24 -7
- package/esm/src/kernel/engine/runner/state.js +38 -17
- package/esm/src/kernel/engine/runner/steps.js +10 -1
- package/esm/src/kernel/field-docs.js +1 -1
- package/esm/src/kernel/turn-events.d.ts +9 -4
- package/esm/src/kernel/turn-events.js +5 -1
- package/esm/src/kernel/types.d.ts +53 -38
- package/package.json +7 -1
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[];
|