@yaag/runtime 0.26.0 → 0.27.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/package.json +1 -1
- package/src/agent/agent.ts +29 -17
- package/src/agent/fork.ts +40 -12
- package/src/agent/host-fork.ts +85 -0
- package/src/agent/spawn-definition-request.ts +38 -3
- package/src/agent/spawn-open.ts +43 -103
- package/src/agent/spawn-plan.ts +114 -0
- package/src/agent/spawn-request.ts +16 -2
- package/src/agent/spawn.ts +20 -3
- package/src/ask/ask-exchange-options.ts +3 -6
- package/src/ask/ask-exchange.ts +48 -108
- package/src/ask/ask-guard.ts +207 -0
- package/src/ask/ask-timing.ts +12 -0
- package/src/ask/index.ts +1 -0
- package/src/cassette/cassette-loader.ts +9 -20
- package/src/cassette/cassette-schema.ts +10 -1
- package/src/cassette/cassette.ts +11 -34
- package/src/cassette/checkpoint.ts +306 -0
- package/src/cassette/index.ts +16 -7
- package/src/cassette/parked-asks.ts +38 -0
- package/src/cassette/replay-divergence.ts +7 -102
- package/src/cassette/resume-identity.ts +5 -1
- package/src/cassette/resume-preconditions.ts +14 -0
- package/src/cassette/resume-transport.ts +26 -32
- package/src/cassette/run-identity.ts +109 -0
- package/src/cassette/session-answer.ts +51 -114
- package/src/cassette/spawn-identity.ts +318 -0
- package/src/contract/error-codes.ts +1 -0
- package/src/contract/index.ts +1 -0
- package/src/contract/spawn-options.ts +33 -2
- package/src/error-factories.ts +8 -0
- package/src/events.ts +4 -2
- package/src/index.ts +4 -0
- package/src/pi-session/append-tool-result.ts +165 -0
- package/src/pi-session/index.ts +30 -0
- package/src/pi-session/pi-session-error.ts +34 -0
- package/src/pi-session/session-copy.ts +113 -0
- package/src/pi-session/session-entries.ts +130 -0
- package/src/question-summary/index.ts +4 -8
- package/src/question-summary/summarize-question.ts +1 -1
- package/src/question-summary/summary-policy.ts +5 -2
- package/src/run/agent-questions.ts +82 -0
- package/src/run/answers.ts +22 -1
- package/src/run/host-session.ts +233 -0
- package/src/run/index.ts +7 -0
- package/src/run/run-context.ts +3 -0
- package/src/run/run.ts +191 -181
- package/src/transport/live-transport.ts +19 -0
- package/src/transport/pi-state.ts +10 -1
- package/src/transport/transport.ts +13 -9
- package/src/types.ts +1 -0
- package/src/cassette/checkpoint-flush.ts +0 -101
- package/src/cassette/run-checkpoint.ts +0 -272
- package/src/question-summary/session-copy.ts +0 -169
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one refusal type of the pi session editor.
|
|
3
|
+
*
|
|
4
|
+
* Not a `YaagError`: the editor has no `YaagErrorCode` of its own, and each
|
|
5
|
+
* caller maps the `reason` to its own error kind.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
/** Why the editor refused to write. */
|
|
9
|
+
export type PiSessionErrorReason =
|
|
10
|
+
/** No entry holds the `toolCall` part with this id. */
|
|
11
|
+
| "no-such-call"
|
|
12
|
+
/** The call already has a result, and its text is another one (ADR-0022). */
|
|
13
|
+
| "different-result"
|
|
14
|
+
/** The session file cannot be read. */
|
|
15
|
+
| "unreadable"
|
|
16
|
+
/** A line other than the last one is not a session entry. */
|
|
17
|
+
| "bad-line";
|
|
18
|
+
|
|
19
|
+
export class PiSessionError extends Error {
|
|
20
|
+
readonly reason: PiSessionErrorReason;
|
|
21
|
+
/** The text already recorded for the call; set for `different-result` only. */
|
|
22
|
+
readonly existing?: string;
|
|
23
|
+
|
|
24
|
+
constructor(reason: PiSessionErrorReason, message: string, existing?: string) {
|
|
25
|
+
super(message);
|
|
26
|
+
this.name = "PiSessionError";
|
|
27
|
+
this.reason = reason;
|
|
28
|
+
if (existing !== undefined) this.existing = existing;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function isPiSessionError(error: unknown): error is PiSessionError {
|
|
33
|
+
return error instanceof PiSessionError;
|
|
34
|
+
}
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* One pi session copy: the copy the fork summarizer opens (ADR-0022) and the
|
|
3
|
+
* copy a Host Fork is spawned from.
|
|
4
|
+
*
|
|
5
|
+
* A session with an open tool call cannot be continued: pi refuses a session
|
|
6
|
+
* whose last assistant message has an unanswered tool call. So yaag copies the
|
|
7
|
+
* session file and closes the open call in the copy with a result text. The
|
|
8
|
+
* source file stays untouched.
|
|
9
|
+
*
|
|
10
|
+
* The write belongs to the pi session editor, so the result parents on the
|
|
11
|
+
* entry that holds the call (ADR-0023), not on the last entry. This module owns
|
|
12
|
+
* the temp path, the removal, the result text and the tool name it gives down,
|
|
13
|
+
* and the option that tolerates a call which is already answered.
|
|
14
|
+
*/
|
|
15
|
+
import { copyFile, rm } from "node:fs/promises";
|
|
16
|
+
import { tmpdir } from "node:os";
|
|
17
|
+
import { join } from "node:path";
|
|
18
|
+
import { appendToolResult } from "./append-tool-result.ts";
|
|
19
|
+
import { isPiSessionError } from "./pi-session-error.ts";
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* What the summarizer session reads in place of the human's answer. It states
|
|
23
|
+
* three facts: no answer arrived, this session is a copy, and the task is over.
|
|
24
|
+
*/
|
|
25
|
+
export const SYNTHETIC_TOOL_RESULT_TEXT =
|
|
26
|
+
"The human has not answered yet. This session is a copy of your session, made " +
|
|
27
|
+
"only to summarize your question. Do not continue your task.";
|
|
28
|
+
|
|
29
|
+
/** One prepared copy: where it is, and how to remove it again. */
|
|
30
|
+
export interface SessionCopy {
|
|
31
|
+
/** Absolute path of the copy; hand it to `pi --session`. */
|
|
32
|
+
readonly path: string;
|
|
33
|
+
/** Removes the copy. Best effort: it never throws. */
|
|
34
|
+
remove(): Promise<void>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
/** What one copy needs: the source session and the call to close. */
|
|
38
|
+
export interface SessionCopyRequest {
|
|
39
|
+
readonly sessionFile: string;
|
|
40
|
+
readonly toolCallId: string;
|
|
41
|
+
/** Where the copy goes; the OS temp directory by default. */
|
|
42
|
+
readonly directory?: string;
|
|
43
|
+
/** The result text written into the copy; the synthetic text by default. */
|
|
44
|
+
readonly text?: string;
|
|
45
|
+
/** The tool name the result is recorded under; `request_user_input` by default. */
|
|
46
|
+
readonly toolName?: string;
|
|
47
|
+
/**
|
|
48
|
+
* When true, a call that is already answered is not a refusal: the copy is
|
|
49
|
+
* made, nothing is appended, and the copy is used as it is. A result with the
|
|
50
|
+
* same text is a success in both cases; this field adds the result with
|
|
51
|
+
* another text (`different-result`) to it.
|
|
52
|
+
*/
|
|
53
|
+
readonly toleratesAnsweredCall?: boolean;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Copies one pi session and closes the named call in the copy.
|
|
58
|
+
*
|
|
59
|
+
* A refusal of the editor removes the copy and comes out as the
|
|
60
|
+
* `PiSessionError` the editor threw, so its `reason` reaches the caller. Only
|
|
61
|
+
* an error of another kind gets the wrapper below.
|
|
62
|
+
*/
|
|
63
|
+
export async function prepareSessionCopy(request: SessionCopyRequest): Promise<SessionCopy> {
|
|
64
|
+
const path = join(
|
|
65
|
+
request.directory ?? tmpdir(),
|
|
66
|
+
`yaag-summary-${Date.now()}-${Math.random().toString(16).slice(2)}.jsonl`,
|
|
67
|
+
);
|
|
68
|
+
const copy: SessionCopy = {
|
|
69
|
+
path,
|
|
70
|
+
remove: async (): Promise<void> => {
|
|
71
|
+
try {
|
|
72
|
+
await rm(path, { force: true });
|
|
73
|
+
} catch {
|
|
74
|
+
// best effort: a leftover temp file must never fail a Run
|
|
75
|
+
}
|
|
76
|
+
},
|
|
77
|
+
};
|
|
78
|
+
try {
|
|
79
|
+
await appendToolResult({
|
|
80
|
+
sessionFile: request.sessionFile,
|
|
81
|
+
toolCallId: request.toolCallId,
|
|
82
|
+
text: request.text ?? SYNTHETIC_TOOL_RESULT_TEXT,
|
|
83
|
+
...(request.toolName === undefined ? {} : { toolName: request.toolName }),
|
|
84
|
+
into: path,
|
|
85
|
+
});
|
|
86
|
+
} catch (error) {
|
|
87
|
+
return await onRefusal(request, copy, error);
|
|
88
|
+
}
|
|
89
|
+
return copy;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/** What one refusal becomes: a tolerated copy, or the error the caller reads. */
|
|
93
|
+
async function onRefusal(
|
|
94
|
+
request: SessionCopyRequest,
|
|
95
|
+
copy: SessionCopy,
|
|
96
|
+
error: unknown,
|
|
97
|
+
): Promise<SessionCopy> {
|
|
98
|
+
if (
|
|
99
|
+
request.toleratesAnsweredCall === true &&
|
|
100
|
+
isPiSessionError(error) &&
|
|
101
|
+
error.reason === "different-result"
|
|
102
|
+
) {
|
|
103
|
+
// The editor refused before it made the copy, so this branch copies.
|
|
104
|
+
await copyFile(request.sessionFile, copy.path);
|
|
105
|
+
return copy;
|
|
106
|
+
}
|
|
107
|
+
await copy.remove();
|
|
108
|
+
// The `reason` must reach the runtime, which maps it to its own error kind.
|
|
109
|
+
if (isPiSessionError(error)) throw error;
|
|
110
|
+
throw new Error(
|
|
111
|
+
`cannot prepare a session copy: ${error instanceof Error ? error.message : String(error)}`,
|
|
112
|
+
);
|
|
113
|
+
}
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The one parse policy of a pi session file, and the two structural lookups
|
|
3
|
+
* every caller of it needs.
|
|
4
|
+
*
|
|
5
|
+
* The file is JSONL, one entry per line, pi session version 3. A *half-written*
|
|
6
|
+
* last line is tolerated, because pi may have died mid-write: the writer
|
|
7
|
+
* truncates it away, so the file the append leaves behind parses whole and a
|
|
8
|
+
* second append reads it the same way. Every other bad line is a refusal,
|
|
9
|
+
* including a last line that parses whole but is no entry — those are bytes pi
|
|
10
|
+
* meant to write, and they are never deleted.
|
|
11
|
+
*
|
|
12
|
+
* The "holds this tool call" check is structural: a `toolCall` content part
|
|
13
|
+
* with this id. Never a substring scan, because the same id can appear inside
|
|
14
|
+
* message text, and a false positive appends a dangling result.
|
|
15
|
+
*/
|
|
16
|
+
import { PiSessionError } from "./pi-session-error.ts";
|
|
17
|
+
|
|
18
|
+
/** One parsed session entry; only the fields the callers read are named. */
|
|
19
|
+
export interface SessionEntry {
|
|
20
|
+
readonly id?: unknown;
|
|
21
|
+
readonly message?: unknown;
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** One content part of a message entry, as pi writes it. */
|
|
25
|
+
export interface ContentPart {
|
|
26
|
+
readonly type?: unknown;
|
|
27
|
+
readonly id?: unknown;
|
|
28
|
+
readonly name?: unknown;
|
|
29
|
+
readonly text?: unknown;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** What one parse yields: the entries, and where an incomplete tail starts. */
|
|
33
|
+
export interface ParsedSession {
|
|
34
|
+
readonly entries: readonly SessionEntry[];
|
|
35
|
+
/**
|
|
36
|
+
* Byte offset of the half-written last line, when there is one. The writer
|
|
37
|
+
* truncates the file here, so the partial line never survives the append.
|
|
38
|
+
*
|
|
39
|
+
* Bytes, never characters: `truncate` takes a byte length, and one non-ASCII
|
|
40
|
+
* character earlier in the session would otherwise move the cut inside a real
|
|
41
|
+
* entry — including the one that holds the parked call.
|
|
42
|
+
*/
|
|
43
|
+
readonly truncatedTailAtByte?: number;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
export function isRecord(value: unknown): value is Record<string, unknown> {
|
|
47
|
+
return typeof value === "object" && value !== null && !Array.isArray(value);
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* Parses every non-empty line of one session text. Only the last line may be
|
|
52
|
+
* incomplete; every other unparsable or non-entry line throws a
|
|
53
|
+
* `PiSessionError` with reason `bad-line`.
|
|
54
|
+
*/
|
|
55
|
+
export function parseSession(text: string, path: string): ParsedSession {
|
|
56
|
+
const lines: { line: string; number: number; byte: number }[] = [];
|
|
57
|
+
let byte = 0;
|
|
58
|
+
for (const [index, line] of text.split("\n").entries()) {
|
|
59
|
+
if (line.trim().length > 0) lines.push({ line, number: index + 1, byte });
|
|
60
|
+
// The separator this split consumed is one byte, and so is every newline.
|
|
61
|
+
byte += Buffer.byteLength(line, "utf8") + 1;
|
|
62
|
+
}
|
|
63
|
+
const entries: SessionEntry[] = [];
|
|
64
|
+
let truncatedTailAtByte: number | undefined;
|
|
65
|
+
for (const [index, item] of lines.entries()) {
|
|
66
|
+
const parsed = parseLine(item.line);
|
|
67
|
+
if (parsed.kind === "entry") {
|
|
68
|
+
entries.push(parsed.entry);
|
|
69
|
+
continue;
|
|
70
|
+
}
|
|
71
|
+
if (index === lines.length - 1 && parsed.kind === "incomplete") {
|
|
72
|
+
truncatedTailAtByte = item.byte;
|
|
73
|
+
continue;
|
|
74
|
+
}
|
|
75
|
+
throw new PiSessionError(
|
|
76
|
+
"bad-line",
|
|
77
|
+
`session ${path} line ${item.number} is not a session entry`,
|
|
78
|
+
);
|
|
79
|
+
}
|
|
80
|
+
return truncatedTailAtByte === undefined ? { entries } : { entries, truncatedTailAtByte };
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* One line, read three ways: an entry, a complete value that is no entry, or a
|
|
85
|
+
* half-written line. Only the last of the three may be dropped.
|
|
86
|
+
*/
|
|
87
|
+
type ParsedLine =
|
|
88
|
+
| { readonly kind: "entry"; readonly entry: SessionEntry }
|
|
89
|
+
| { readonly kind: "not-an-entry" }
|
|
90
|
+
| { readonly kind: "incomplete" };
|
|
91
|
+
|
|
92
|
+
function parseLine(line: string): ParsedLine {
|
|
93
|
+
let parsed: unknown;
|
|
94
|
+
try {
|
|
95
|
+
parsed = JSON.parse(line);
|
|
96
|
+
} catch {
|
|
97
|
+
return { kind: "incomplete" };
|
|
98
|
+
}
|
|
99
|
+
return isRecord(parsed) ? { kind: "entry", entry: parsed } : { kind: "not-an-entry" };
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/** The entry that holds one tool call, and the tool name that call carries. */
|
|
103
|
+
export interface ToolCallHolder {
|
|
104
|
+
readonly entry: SessionEntry;
|
|
105
|
+
/** The `name` of the `toolCall` part; absent when pi wrote none. */
|
|
106
|
+
readonly toolName?: string;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** The first entry that holds the call as a real `toolCall` part. */
|
|
110
|
+
export function findToolCall(
|
|
111
|
+
entries: readonly SessionEntry[],
|
|
112
|
+
toolCallId: string,
|
|
113
|
+
): ToolCallHolder | undefined {
|
|
114
|
+
for (const entry of entries) {
|
|
115
|
+
const part = contentParts(entry).find(
|
|
116
|
+
(candidate) => candidate.type === "toolCall" && candidate.id === toolCallId,
|
|
117
|
+
);
|
|
118
|
+
if (part === undefined) continue;
|
|
119
|
+
return typeof part.name === "string" ? { entry, toolName: part.name } : { entry };
|
|
120
|
+
}
|
|
121
|
+
return undefined;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
export function contentParts(entry: SessionEntry): readonly ContentPart[] {
|
|
125
|
+
const message = entry.message;
|
|
126
|
+
if (!isRecord(message)) return [];
|
|
127
|
+
const content = message.content;
|
|
128
|
+
if (!Array.isArray(content)) return [];
|
|
129
|
+
return content.filter((part): part is ContentPart => isRecord(part));
|
|
130
|
+
}
|
|
@@ -1,16 +1,12 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* Public surface of the `question-summary/` module: the fork summarizer that
|
|
3
|
-
* fills `summary` on an Agent Question (ADR-0022)
|
|
4
|
-
*
|
|
3
|
+
* fills `summary` on an Agent Question (ADR-0022): the policy table and the
|
|
4
|
+
* one-Ask orchestration. The session copy lives in `pi-session/`. It is named
|
|
5
|
+
* for the glossary term, and stays apart from `summary/`, which owns the Run
|
|
6
|
+
* Summary fold.
|
|
5
7
|
* Files inside this directory import each other directly.
|
|
6
8
|
*/
|
|
7
9
|
|
|
8
|
-
export {
|
|
9
|
-
prepareSessionCopy,
|
|
10
|
-
type SessionCopy,
|
|
11
|
-
type SessionCopyRequest,
|
|
12
|
-
SYNTHETIC_TOOL_RESULT_TEXT,
|
|
13
|
-
} from "./session-copy.ts";
|
|
14
10
|
export {
|
|
15
11
|
type InternalOpen,
|
|
16
12
|
type ParkedAgent,
|
|
@@ -8,8 +8,8 @@
|
|
|
8
8
|
*/
|
|
9
9
|
import type { SpawnGate } from "../agent/index.ts";
|
|
10
10
|
import type { QuestionSummaryConfig } from "../config/index.ts";
|
|
11
|
+
import { prepareSessionCopy } from "../pi-session/index.ts";
|
|
11
12
|
import type { AgentQuestions } from "../run/index.ts";
|
|
12
|
-
import { prepareSessionCopy } from "./session-copy.ts";
|
|
13
13
|
import { summarizes } from "./summary-policy.ts";
|
|
14
14
|
|
|
15
15
|
/**
|
|
@@ -9,11 +9,14 @@ import type { Question } from "../run/index.ts";
|
|
|
9
9
|
* True when this Question earns a Question Summary.
|
|
10
10
|
*
|
|
11
11
|
* A program Question never does: it has no Agent, so there is no session to
|
|
12
|
-
* copy and no reasoning to summarize.
|
|
13
|
-
*
|
|
12
|
+
* copy and no reasoning to summarize. A Question that already carries a summary
|
|
13
|
+
* never does either: a resume re-opens the Checkpoint's Question with its
|
|
14
|
+
* summary, and it must cost no second model call (ADR-0022). `when-missing`,
|
|
15
|
+
* the default, runs only when the Agent supplied no `context` of its own.
|
|
14
16
|
*/
|
|
15
17
|
export function summarizes(policy: QuestionSummaryPolicy, question: Question): boolean {
|
|
16
18
|
if (question.agent === undefined) return false;
|
|
19
|
+
if ((question.summary ?? "").trim().length > 0) return false;
|
|
17
20
|
switch (policy) {
|
|
18
21
|
case "never":
|
|
19
22
|
return false;
|
|
@@ -5,6 +5,7 @@
|
|
|
5
5
|
* program asks: a question raised from an Ask's frame handler must never throw,
|
|
6
6
|
* so this registry refuses nothing and repeats are inert.
|
|
7
7
|
*/
|
|
8
|
+
import type { ParkedAsk } from "../cassette/index.ts";
|
|
8
9
|
import { agentQuestionId } from "./question-id.ts";
|
|
9
10
|
import type { Question } from "./questions.ts";
|
|
10
11
|
|
|
@@ -16,6 +17,20 @@ export interface AgentQuestionRequest {
|
|
|
16
17
|
readonly context?: string;
|
|
17
18
|
}
|
|
18
19
|
|
|
20
|
+
/** The parked call alone: the Agent name and the tool call id that key it. */
|
|
21
|
+
export interface AgentParkRequest {
|
|
22
|
+
readonly agent: string;
|
|
23
|
+
readonly toolCallId: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** One Question a resume re-opens, with the parked call it belongs to. */
|
|
27
|
+
export interface SeededQuestion {
|
|
28
|
+
/** The recorded Question: id, text, context and Question Summary. */
|
|
29
|
+
readonly question: Question;
|
|
30
|
+
/** The parked call the incomplete marker names. */
|
|
31
|
+
readonly parked: AgentQuestionRequest;
|
|
32
|
+
}
|
|
33
|
+
|
|
19
34
|
/** The Agent questions of one Run, and the signal the Run races. */
|
|
20
35
|
export interface AgentQuestions {
|
|
21
36
|
/**
|
|
@@ -23,6 +38,18 @@ export interface AgentQuestions {
|
|
|
23
38
|
* durable id of the Question. Idempotent per id.
|
|
24
39
|
*/
|
|
25
40
|
raise(request: AgentQuestionRequest): string;
|
|
41
|
+
/**
|
|
42
|
+
* Holds the open Questions of a Checkpoint apart, ready for the Ask that
|
|
43
|
+
* parks on them. A seeded Question is invisible until it is parked, and
|
|
44
|
+
* seeding raises no pause signal: a resume that diverges before the parked
|
|
45
|
+
* Ask must publish no Question (ADR-0022/0023).
|
|
46
|
+
*/
|
|
47
|
+
seed(seeds: readonly SeededQuestion[]): void;
|
|
48
|
+
/**
|
|
49
|
+
* Marks the parked call open, and returns the durable id of its Question. A
|
|
50
|
+
* seeded Question keeps its recorded text, context and summary.
|
|
51
|
+
*/
|
|
52
|
+
park(request: AgentParkRequest): string;
|
|
26
53
|
readonly questions: readonly Question[];
|
|
27
54
|
/**
|
|
28
55
|
* The parked calls, keyed by Question id. The fork summarizer reads the tool
|
|
@@ -46,10 +73,24 @@ export function createAgentQuestions(): AgentQuestions {
|
|
|
46
73
|
const raised = new Promise<void>((resolve) => {
|
|
47
74
|
signal = resolve;
|
|
48
75
|
});
|
|
76
|
+
const seeded = new Map<string, SeededQuestion>();
|
|
77
|
+
/** Moves one seeded Question into the open set, with its recorded record. */
|
|
78
|
+
const promote = (id: string): boolean => {
|
|
79
|
+
const seed = seeded.get(id);
|
|
80
|
+
if (seed === undefined) return false;
|
|
81
|
+
seeded.delete(id);
|
|
82
|
+
if (!byId.has(id)) {
|
|
83
|
+
parked.set(id, seed.parked);
|
|
84
|
+
byId.set(id, seed.question);
|
|
85
|
+
}
|
|
86
|
+
signal();
|
|
87
|
+
return true;
|
|
88
|
+
};
|
|
49
89
|
return {
|
|
50
90
|
raise(request: AgentQuestionRequest): string {
|
|
51
91
|
// The ADR's key: the Agent name and the tool call id of the parked call.
|
|
52
92
|
const id = agentQuestionId(request.agent, request.toolCallId);
|
|
93
|
+
if (promote(id)) return id;
|
|
53
94
|
if (byId.has(id)) return id;
|
|
54
95
|
parked.set(id, request);
|
|
55
96
|
byId.set(id, {
|
|
@@ -61,6 +102,18 @@ export function createAgentQuestions(): AgentQuestions {
|
|
|
61
102
|
signal();
|
|
62
103
|
return id;
|
|
63
104
|
},
|
|
105
|
+
seed(seeds: readonly SeededQuestion[]): void {
|
|
106
|
+
for (const seed of seeds) {
|
|
107
|
+
const id = seed.question.id;
|
|
108
|
+
if (byId.has(id) || seeded.has(id)) continue;
|
|
109
|
+
seeded.set(id, seed);
|
|
110
|
+
}
|
|
111
|
+
},
|
|
112
|
+
park(request: AgentParkRequest): string {
|
|
113
|
+
const id = agentQuestionId(request.agent, request.toolCallId);
|
|
114
|
+
if (!promote(id)) signal();
|
|
115
|
+
return id;
|
|
116
|
+
},
|
|
64
117
|
get questions(): readonly Question[] {
|
|
65
118
|
return [...byId.values()];
|
|
66
119
|
},
|
|
@@ -73,3 +126,32 @@ export function createAgentQuestions(): AgentQuestions {
|
|
|
73
126
|
raised,
|
|
74
127
|
};
|
|
75
128
|
}
|
|
129
|
+
|
|
130
|
+
/**
|
|
131
|
+
* Seeds the registry from the open Questions of a Checkpoint (ADR-0022/0023).
|
|
132
|
+
*
|
|
133
|
+
* Only a Question that an Agent raised is seeded, and only when an incomplete
|
|
134
|
+
* marker names it: a program Question is raised again by the program itself.
|
|
135
|
+
*/
|
|
136
|
+
export function seedFromResume(options: {
|
|
137
|
+
readonly questions: AgentQuestions;
|
|
138
|
+
readonly open: readonly Question[];
|
|
139
|
+
readonly parked: readonly ParkedAsk[];
|
|
140
|
+
}): void {
|
|
141
|
+
const seeds: SeededQuestion[] = [];
|
|
142
|
+
for (const question of options.open) {
|
|
143
|
+
if (question.agent === undefined) continue;
|
|
144
|
+
const mark = options.parked.find((entry) => entry.questionId === question.id);
|
|
145
|
+
if (mark === undefined) continue;
|
|
146
|
+
seeds.push({
|
|
147
|
+
question,
|
|
148
|
+
parked: {
|
|
149
|
+
agent: mark.agent,
|
|
150
|
+
toolCallId: mark.toolCallId,
|
|
151
|
+
question: question.question,
|
|
152
|
+
...(question.context === undefined ? {} : { context: question.context }),
|
|
153
|
+
},
|
|
154
|
+
});
|
|
155
|
+
}
|
|
156
|
+
options.questions.seed(seeds);
|
|
157
|
+
}
|
package/src/run/answers.ts
CHANGED
|
@@ -5,8 +5,9 @@
|
|
|
5
5
|
* what an earlier resume already resolved. Every refusal happens here, at
|
|
6
6
|
* construction, before the first Agent starts.
|
|
7
7
|
*/
|
|
8
|
-
import type { CassetteAnswer, CassetteQuestion } from "../cassette/index.ts";
|
|
8
|
+
import type { CassetteAnswer, CassetteQuestion, ParkedAsk } from "../cassette/index.ts";
|
|
9
9
|
import { YaagError } from "../errors.ts";
|
|
10
|
+
import type { Question } from "./questions.ts";
|
|
10
11
|
|
|
11
12
|
/** What one resume knows about its answers. */
|
|
12
13
|
export interface AnswerLedger {
|
|
@@ -14,6 +15,12 @@ export interface AnswerLedger {
|
|
|
14
15
|
take(id: string): string | undefined;
|
|
15
16
|
/** Every resolved step the successor Cassette must carry. */
|
|
16
17
|
resolved(): readonly CassetteAnswer[];
|
|
18
|
+
/**
|
|
19
|
+
* The Questions of the resume source that no answer resolves. They are the
|
|
20
|
+
* Questions of this resume: id, text, context and Question Summary come from
|
|
21
|
+
* the run block, not from the recorded frames (ADR-0022).
|
|
22
|
+
*/
|
|
23
|
+
open(): readonly Question[];
|
|
17
24
|
}
|
|
18
25
|
|
|
19
26
|
export interface AnswerLedgerOptions {
|
|
@@ -23,6 +30,8 @@ export interface AnswerLedgerOptions {
|
|
|
23
30
|
readonly questions: readonly CassetteQuestion[];
|
|
24
31
|
/** The answers the resume source already resolved. */
|
|
25
32
|
readonly inherited: readonly CassetteAnswer[];
|
|
33
|
+
/** The incomplete-Ask markers of the resume source (ADR-0023). */
|
|
34
|
+
readonly parked?: readonly ParkedAsk[];
|
|
26
35
|
}
|
|
27
36
|
|
|
28
37
|
/**
|
|
@@ -54,6 +63,15 @@ export function createAnswerLedger(options: AnswerLedgerOptions): AnswerLedger {
|
|
|
54
63
|
}
|
|
55
64
|
resolved.set(id, answer);
|
|
56
65
|
}
|
|
66
|
+
for (const mark of options.parked ?? []) {
|
|
67
|
+
if (open.has(mark.questionId) || resolved.has(mark.questionId)) continue;
|
|
68
|
+
throw new YaagError(
|
|
69
|
+
"RESUME_REFUSED",
|
|
70
|
+
`the checkpoint records agent "${mark.agent}" parked on question ` +
|
|
71
|
+
`"${mark.questionId}", and its run block holds no such question — ` +
|
|
72
|
+
"the checkpoint is incomplete",
|
|
73
|
+
);
|
|
74
|
+
}
|
|
57
75
|
return {
|
|
58
76
|
take(id: string): string | undefined {
|
|
59
77
|
return resolved.get(id);
|
|
@@ -61,6 +79,9 @@ export function createAnswerLedger(options: AnswerLedgerOptions): AnswerLedger {
|
|
|
61
79
|
resolved(): readonly CassetteAnswer[] {
|
|
62
80
|
return [...resolved].map(([id, answer]) => ({ id, answer }));
|
|
63
81
|
},
|
|
82
|
+
open(): readonly Question[] {
|
|
83
|
+
return options.questions.filter((question) => !resolved.has(question.id));
|
|
84
|
+
},
|
|
64
85
|
};
|
|
65
86
|
}
|
|
66
87
|
|