@yaag/runtime 0.24.0 → 0.26.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 +2 -3
- package/src/agent/agent.ts +46 -6
- package/src/agent/ask-user-capability.ts +36 -0
- package/src/agent/index.ts +3 -1
- package/src/agent/spawn-open.ts +24 -5
- package/src/agent/spawn-request.ts +18 -1
- package/src/agent/spawn.ts +31 -9
- package/src/agent/spawnable-definition.ts +9 -0
- package/src/ask/ask-exchange-options.ts +5 -0
- package/src/ask/ask-exchange.ts +67 -2
- package/src/ask/ask-settlement.ts +8 -0
- package/src/ask/idle-watch.ts +12 -2
- package/src/ask/stall-watchdog.ts +13 -3
- package/src/ask-contract/ask-limit.ts +24 -6
- package/src/ask-contract/index.ts +8 -0
- package/src/ask-contract/request-user-input-extension.ts +105 -0
- package/src/ask-contract/request-user-input.ts +58 -0
- package/src/cassette/cassette-loader.ts +50 -1
- package/src/cassette/cassette-schema.ts +27 -0
- package/src/cassette/cassette.ts +49 -0
- package/src/cassette/index.ts +10 -1
- package/src/cassette/replay-divergence.ts +5 -0
- package/src/cassette/resume-preconditions.ts +10 -0
- package/src/cassette/resume-transport.ts +111 -6
- package/src/cassette/run-checkpoint.ts +52 -3
- package/src/cassette/session-answer.ts +163 -0
- package/src/catalog/index.ts +5 -3
- package/src/catalog/registry-reader.ts +1 -1
- package/src/catalog/resolve.ts +184 -0
- package/src/config/config-schema.ts +33 -0
- package/src/config/effective-config.ts +53 -0
- package/src/config/index.ts +4 -0
- package/src/contract/agent-policy.ts +9 -0
- package/src/contract/catalog-resolve.ts +33 -0
- package/src/contract/error-codes.ts +5 -2
- package/src/contract/index.ts +10 -2
- package/src/control/index.ts +2 -0
- package/src/control/pause-drain.ts +81 -24
- package/src/errors.ts +8 -2
- package/src/events.ts +6 -0
- package/src/index.ts +18 -2
- package/src/model/index.ts +1 -1
- package/src/public-api.ts +7 -0
- package/src/question-summary/index.ts +22 -0
- package/src/question-summary/session-copy.ts +169 -0
- package/src/question-summary/summarize-question.ts +129 -0
- package/src/question-summary/summary-policy.ts +25 -0
- package/src/run/agent-questions.ts +75 -0
- package/src/run/answers.ts +70 -0
- package/src/run/index.ts +5 -0
- package/src/run/pause-questions.ts +98 -0
- package/src/run/pause-signal.ts +32 -0
- package/src/run/question-id.ts +18 -0
- package/src/run/questions.ts +31 -0
- package/src/run/run-context.ts +26 -1
- package/src/run/run-result.ts +21 -0
- package/src/run/run-settlement.ts +36 -4
- package/src/run/run.ts +119 -20
- package/src/system-prompt/agent-system-prompt.ts +1 -1
- package/src/transport/pi-state.ts +21 -4
- package/src/transport/tool-probe.ts +4 -0
- package/src/transport/transport.ts +26 -0
|
@@ -1,4 +1,11 @@
|
|
|
1
1
|
import { type Static, Type } from "typebox";
|
|
2
|
+
import { THINKING_LEVELS } from "../model/index.ts";
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* The thinking union, built from `THINKING_LEVELS`, so a level pi adds cannot
|
|
6
|
+
* drift out of the config schema.
|
|
7
|
+
*/
|
|
8
|
+
const ThinkingLevelSchema = Type.Union(THINKING_LEVELS.map((level) => Type.Literal(level)));
|
|
2
9
|
|
|
3
10
|
/**
|
|
4
11
|
* The config document of one layer (spec rule 1): plain JSON, namespaced as
|
|
@@ -9,6 +16,9 @@ import { type Static, Type } from "typebox";
|
|
|
9
16
|
* a newer artifact still loads. A config file is hand-written, so an unknown
|
|
10
17
|
* key is a typo the author wants named, not forward compatibility.
|
|
11
18
|
*
|
|
19
|
+
* `askUser.summary` configures the Question Summary the fork summarizer writes
|
|
20
|
+
* (ADR-0022). Like `profile`, each of its keys is last-layer-wins.
|
|
21
|
+
*
|
|
12
22
|
* `profile` is the one top-level scalar key. Unlike `agents.extensions`, which
|
|
13
23
|
* concatenates across the layers, it does not concatenate: the last layer that
|
|
14
24
|
* states it wins (ADR-0052).
|
|
@@ -22,6 +32,29 @@ export const YaagConfigSchema = Type.Object(
|
|
|
22
32
|
),
|
|
23
33
|
),
|
|
24
34
|
profile: Type.Optional(Type.String()),
|
|
35
|
+
askUser: Type.Optional(
|
|
36
|
+
Type.Object(
|
|
37
|
+
{
|
|
38
|
+
summary: Type.Optional(
|
|
39
|
+
Type.Object(
|
|
40
|
+
{
|
|
41
|
+
policy: Type.Optional(
|
|
42
|
+
Type.Union([
|
|
43
|
+
Type.Literal("never"),
|
|
44
|
+
Type.Literal("always"),
|
|
45
|
+
Type.Literal("when-missing"),
|
|
46
|
+
]),
|
|
47
|
+
),
|
|
48
|
+
model: Type.Optional(Type.String()),
|
|
49
|
+
thinking: Type.Optional(ThinkingLevelSchema),
|
|
50
|
+
},
|
|
51
|
+
{ additionalProperties: false },
|
|
52
|
+
),
|
|
53
|
+
),
|
|
54
|
+
},
|
|
55
|
+
{ additionalProperties: false },
|
|
56
|
+
),
|
|
57
|
+
),
|
|
25
58
|
},
|
|
26
59
|
{ additionalProperties: false },
|
|
27
60
|
);
|
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { ThinkingLevel } from "../model/index.ts";
|
|
1
2
|
import { type ConfigLayer, readConfigLayer } from "./config-file.ts";
|
|
2
3
|
import {
|
|
3
4
|
type ConfigEnvironment,
|
|
@@ -5,6 +6,28 @@ import {
|
|
|
5
6
|
resolveGlobalConfigPath,
|
|
6
7
|
} from "./config-paths.ts";
|
|
7
8
|
|
|
9
|
+
/** When the fork summarizer runs for one Agent Question (ADR-0022). */
|
|
10
|
+
export type QuestionSummaryPolicy = "never" | "always" | "when-missing";
|
|
11
|
+
|
|
12
|
+
/** The resolved `askUser.summary` block; every default is already applied. */
|
|
13
|
+
export interface QuestionSummaryConfig {
|
|
14
|
+
readonly policy: QuestionSummaryPolicy;
|
|
15
|
+
/** Model pattern for the summarizer; absent means the parked Agent's own model. */
|
|
16
|
+
readonly model?: string;
|
|
17
|
+
readonly thinking: ThinkingLevel;
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** Reads the Question Summary settings of one config, defaults included. */
|
|
21
|
+
export function questionSummaryOf(config: EffectiveConfig | undefined): QuestionSummaryConfig {
|
|
22
|
+
return config?.askUserSummary ?? DEFAULT_QUESTION_SUMMARY;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The Question Summary settings of a Run that configured none. */
|
|
26
|
+
export const DEFAULT_QUESTION_SUMMARY: QuestionSummaryConfig = Object.freeze({
|
|
27
|
+
policy: "when-missing" as const,
|
|
28
|
+
thinking: "low" as const,
|
|
29
|
+
});
|
|
30
|
+
|
|
8
31
|
/** Which of the three layers a config value came from. */
|
|
9
32
|
export type ConfigLayerName = "global" | "project" | "run";
|
|
10
33
|
|
|
@@ -30,6 +53,12 @@ export interface EffectiveConfig {
|
|
|
30
53
|
* when no layer stated one.
|
|
31
54
|
*/
|
|
32
55
|
readonly profile?: string;
|
|
56
|
+
/**
|
|
57
|
+
* Resolved Question Summary settings (ADR-0022). Optional on purpose: an
|
|
58
|
+
* `EffectiveConfig` built outside this module stays valid, and every reader
|
|
59
|
+
* goes through `questionSummaryOf`, which applies the defaults.
|
|
60
|
+
*/
|
|
61
|
+
readonly askUserSummary?: QuestionSummaryConfig;
|
|
33
62
|
}
|
|
34
63
|
|
|
35
64
|
/** What to discover and read. */
|
|
@@ -48,6 +77,7 @@ export interface EffectiveConfigRequest {
|
|
|
48
77
|
export const EMPTY_EFFECTIVE_CONFIG: EffectiveConfig = Object.freeze({
|
|
49
78
|
extensions: Object.freeze([]) as readonly ConfigExtension[],
|
|
50
79
|
files: Object.freeze([]) as readonly string[],
|
|
80
|
+
askUserSummary: DEFAULT_QUESTION_SUMMARY,
|
|
51
81
|
});
|
|
52
82
|
|
|
53
83
|
interface LoadedLayer {
|
|
@@ -123,5 +153,28 @@ function mergeLayers(found: readonly LoadedLayer[]): EffectiveConfig {
|
|
|
123
153
|
extensions: Object.freeze(extensions),
|
|
124
154
|
files: Object.freeze(found.map(({ layer }) => layer.file)),
|
|
125
155
|
...(profile === undefined ? {} : { profile }),
|
|
156
|
+
askUserSummary: mergeQuestionSummary(found),
|
|
157
|
+
});
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
/** Last-layer-wins per key, exactly like `profile`; it never concatenates. */
|
|
161
|
+
function mergeQuestionSummary(found: readonly LoadedLayer[]): QuestionSummaryConfig {
|
|
162
|
+
const merged = found.reduce<{
|
|
163
|
+
policy?: QuestionSummaryPolicy;
|
|
164
|
+
model?: string;
|
|
165
|
+
thinking?: ThinkingLevel;
|
|
166
|
+
}>((last, { layer }) => {
|
|
167
|
+
const summary = layer.document.askUser?.summary;
|
|
168
|
+
if (summary === undefined) return last;
|
|
169
|
+
return {
|
|
170
|
+
policy: summary.policy ?? last.policy,
|
|
171
|
+
model: summary.model ?? last.model,
|
|
172
|
+
thinking: summary.thinking ?? last.thinking,
|
|
173
|
+
};
|
|
174
|
+
}, {});
|
|
175
|
+
return Object.freeze({
|
|
176
|
+
policy: merged.policy ?? DEFAULT_QUESTION_SUMMARY.policy,
|
|
177
|
+
...(merged.model === undefined ? {} : { model: merged.model }),
|
|
178
|
+
thinking: merged.thinking ?? DEFAULT_QUESTION_SUMMARY.thinking,
|
|
126
179
|
});
|
|
127
180
|
}
|
package/src/config/index.ts
CHANGED
|
@@ -16,8 +16,12 @@ export type { YaagConfigDocument } from "./config-schema.ts";
|
|
|
16
16
|
export {
|
|
17
17
|
type ConfigExtension,
|
|
18
18
|
type ConfigLayerName,
|
|
19
|
+
DEFAULT_QUESTION_SUMMARY,
|
|
19
20
|
type EffectiveConfig,
|
|
20
21
|
type EffectiveConfigRequest,
|
|
21
22
|
EMPTY_EFFECTIVE_CONFIG,
|
|
22
23
|
loadEffectiveConfig,
|
|
24
|
+
type QuestionSummaryConfig,
|
|
25
|
+
type QuestionSummaryPolicy,
|
|
26
|
+
questionSummaryOf,
|
|
23
27
|
} from "./effective-config.ts";
|
|
@@ -84,6 +84,15 @@ export interface AgentPolicy {
|
|
|
84
84
|
readonly skills?: readonly string[];
|
|
85
85
|
/** Skill-name denylist discovered from pi and applied last (ADR-0026). */
|
|
86
86
|
readonly disallowedSkills?: readonly string[];
|
|
87
|
+
/**
|
|
88
|
+
* Loads yaag's injected `request_user_input` tool, so this Agent can ask the
|
|
89
|
+
* human one question and park its turn on the answer (ADR-0023).
|
|
90
|
+
*
|
|
91
|
+
* The capability is never widened and never dropped in silence: a `tools`
|
|
92
|
+
* allowlist that omits the tool, or a `disallowedTools` that denies it, fails
|
|
93
|
+
* the spawn before the Agent starts.
|
|
94
|
+
*/
|
|
95
|
+
readonly canAskUser?: boolean;
|
|
87
96
|
/**
|
|
88
97
|
* Ask options applied to every Ask on this Agent unless overridden per call.
|
|
89
98
|
* They never enter the recorded spawn options: the Ask hash sees them through
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Catalog Resolve author contract (ADR-0053): what `$yaag.<scope>.importAgent`
|
|
3
|
+
* returns, and the options `createYaagGlobal` takes.
|
|
4
|
+
*
|
|
5
|
+
* Type-only. It is the one file in this directory that names a type from
|
|
6
|
+
* outside it: `SpawnableDefinition` is the union of the two Definition shapes,
|
|
7
|
+
* and both already sit in the emitted author tree (ADR-0045).
|
|
8
|
+
*/
|
|
9
|
+
import type { AgentDefinition } from "../agent/define-agent.ts";
|
|
10
|
+
import type { ProfiledDefinition } from "../profile/use-profile.ts";
|
|
11
|
+
|
|
12
|
+
/** An Agent Definition or a Profiled Definition: what a Catalog Resolve gives back. */
|
|
13
|
+
export type SpawnableDefinition = AgentDefinition | ProfiledDefinition;
|
|
14
|
+
|
|
15
|
+
/** One Catalog scope, global or project. */
|
|
16
|
+
export interface CatalogScope {
|
|
17
|
+
/** Resolves the Spawnable Definition registered under `name` in this scope. */
|
|
18
|
+
importAgent(name: string): Promise<SpawnableDefinition>;
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
/** The `$yaag` global an Orchestration Program reads. */
|
|
22
|
+
export interface YaagGlobal {
|
|
23
|
+
readonly global: CatalogScope;
|
|
24
|
+
readonly project: CatalogScope;
|
|
25
|
+
}
|
|
26
|
+
|
|
27
|
+
/** What `createYaagGlobal` needs to build the two scopes. */
|
|
28
|
+
export interface YaagGlobalOptions {
|
|
29
|
+
/** Absolute path of the global Registry File. The file may not exist. */
|
|
30
|
+
readonly globalRegistryPath: string;
|
|
31
|
+
/** Absolute path of the project Registry File. `undefined` when the Run has no Program Directory. */
|
|
32
|
+
readonly projectRegistryPath: string | undefined;
|
|
33
|
+
}
|
|
@@ -55,15 +55,18 @@ export type YaagErrorCode =
|
|
|
55
55
|
| "ARGS_INVALID" // arguments failed schema validation before the Run started
|
|
56
56
|
| "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema
|
|
57
57
|
| "OPTIONS_CONFLICT" // incompatible Run options were supplied
|
|
58
|
+
| "PAUSE_REFUSED" // two pause questions claim one id (ADR-0022)
|
|
58
59
|
| "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
|
|
59
60
|
| "REPLAY_DIVERGED" // replayed program differed from its Cassette
|
|
60
|
-
| "RESUME_REFUSED" // resume metadata is absent
|
|
61
|
+
| "RESUME_REFUSED" // resume metadata is absent, the recorded tree moved, or an answer is unknown or conflicting (ADR-0022/0023)
|
|
61
62
|
| "PROFILE_NOT_FOUND" // a selected Profile is not declared by the program (ADR-0052)
|
|
62
63
|
| "PROFILE_REQUIRED" // a Profiled Definition was spawned by a program that declares no Profiles
|
|
63
64
|
| "ROLE_NOT_FOUND" // a factory read a Role the program does not declare
|
|
64
65
|
| "RUN_CLOSED" // spawn or Ask requested after the Run began settling
|
|
65
|
-
| "RUN_PAUSED" // an external pause drain settled the Run (ADR-0024)
|
|
66
66
|
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
67
67
|
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
|
68
68
|
| "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
|
|
69
|
+
| "CATALOG_ENTRY_NOT_FOUND" // no Registry File, no Program Directory, or no entry with that name (ADR-0053)
|
|
70
|
+
| "CATALOG_ENTRY_AMBIGUOUS" // two or more registry entries carry that name
|
|
71
|
+
| "CATALOG_ENTRY_UNRESOLVABLE" // the entry exists but did not yield a Spawnable Definition
|
|
69
72
|
| "SPAWN_FAILED"; // the spawn was refused, e.g. a guarded system prompt, a broken tool contract or a startup timeout
|
package/src/contract/index.ts
CHANGED
|
@@ -3,11 +3,19 @@
|
|
|
3
3
|
* Program author reads (ADR-0045).
|
|
4
4
|
*
|
|
5
5
|
* Every file here is type-only and imports nothing outside this directory
|
|
6
|
-
* except `typebox
|
|
7
|
-
*
|
|
6
|
+
* except `typebox`, with one exception: `catalog-resolve.ts` names
|
|
7
|
+
* `AgentDefinition` and `ProfiledDefinition`, type-only, because both already
|
|
8
|
+
* sit in the emitted author tree. That keeps the declaration tree a workspace
|
|
9
|
+
* gets small. Files inside this directory import each other directly.
|
|
8
10
|
*/
|
|
9
11
|
export type { AgentPolicy } from "./agent-policy.ts";
|
|
10
12
|
export type { AgentProgress, CompactionResult, TokenBreakdown } from "./agent-report.ts";
|
|
13
|
+
export type {
|
|
14
|
+
CatalogScope,
|
|
15
|
+
SpawnableDefinition,
|
|
16
|
+
YaagGlobal,
|
|
17
|
+
YaagGlobalOptions,
|
|
18
|
+
} from "./catalog-resolve.ts";
|
|
11
19
|
export type {
|
|
12
20
|
AskInvalidOutputOutcome,
|
|
13
21
|
AskLimitKind,
|
package/src/control/index.ts
CHANGED
|
@@ -16,10 +16,12 @@ export {
|
|
|
16
16
|
} from "./control-commands.ts";
|
|
17
17
|
export {
|
|
18
18
|
type AskInFlight,
|
|
19
|
+
type AskSettled,
|
|
19
20
|
type DrainableAgent,
|
|
20
21
|
drainForPause,
|
|
21
22
|
type PauseDrainOptions,
|
|
22
23
|
type PauseDrainResult,
|
|
24
|
+
type PauseGrace,
|
|
23
25
|
} from "./pause-drain.ts";
|
|
24
26
|
export {
|
|
25
27
|
type ControlRequest,
|
|
@@ -1,16 +1,29 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* The
|
|
2
|
+
* The pause drain, in two grace modes.
|
|
3
|
+
*
|
|
4
|
+
* `bounded` is the external pause of ADR-0024: wrap-up steer, then abort at the
|
|
3
5
|
* deadline, then force-close through the Run's reap ladder.
|
|
4
6
|
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
7
|
-
*
|
|
7
|
+
* `natural` is the program pause of ADR-0022: the program asked its user a
|
|
8
|
+
* question, so nothing is cut short. The drain sends no wrap-up steer, sets no
|
|
9
|
+
* timer, and waits for quiescence. The honest consequence: one sibling Ask
|
|
10
|
+
* that never returns holds the drain open forever. ADR-0022 accepts this — a
|
|
11
|
+
* stop is the way out, and a stop always wins.
|
|
12
|
+
*
|
|
13
|
+
* The function takes structural inputs only — Agent handles, a grace, an
|
|
14
|
+
* admission closer and a stop promise — so both callers use it unchanged.
|
|
8
15
|
*
|
|
9
16
|
* The drain deliberately does not trip `AskLimit`, so an externally paused Ask
|
|
10
17
|
* never misreports `ASK_LIMIT`. A soft budget that trips at the same moment
|
|
11
18
|
* simply sends its own steer first; both paths converge on the same reap ladder.
|
|
12
19
|
*/
|
|
13
20
|
|
|
21
|
+
/** How one Ask left flight. It never rejects; a failed Ask carries its error. */
|
|
22
|
+
export interface AskSettled {
|
|
23
|
+
/** What the Ask rejected with, or absent when it resolved. */
|
|
24
|
+
readonly error?: unknown;
|
|
25
|
+
}
|
|
26
|
+
|
|
14
27
|
/** Controls of one Ask in flight, as the drain sees them; a Handle never exposes these. */
|
|
15
28
|
export interface AskInFlight {
|
|
16
29
|
readonly agent: string;
|
|
@@ -23,7 +36,20 @@ export interface AskInFlight {
|
|
|
23
36
|
/** Aborts the turn. Never throws, and the drain never waits for its answer. */
|
|
24
37
|
abort(): Promise<boolean>;
|
|
25
38
|
/** Resolves when the Ask leaves flight, whatever its outcome. Never rejects. */
|
|
26
|
-
readonly settled: Promise<
|
|
39
|
+
readonly settled: Promise<AskSettled>;
|
|
40
|
+
/**
|
|
41
|
+
* The turn is parked on `request_user_input` (ADR-0023). The drain never
|
|
42
|
+
* waits for it, never steers it, never aborts it, and never names it cut
|
|
43
|
+
* short.
|
|
44
|
+
*/
|
|
45
|
+
readonly parked?: boolean;
|
|
46
|
+
/**
|
|
47
|
+
* Resolves when this Ask parks, also after the drain read its wait set.
|
|
48
|
+
* ADR-0023 ends the drain at quiescence, where every Ask has settled **or**
|
|
49
|
+
* parked, so an Ask that parks later must leave the wait the same way a
|
|
50
|
+
* settled one does.
|
|
51
|
+
*/
|
|
52
|
+
readonly parkedSignal?: Promise<void>;
|
|
27
53
|
}
|
|
28
54
|
|
|
29
55
|
/** What the drain needs from one Agent; `Agent` satisfies it structurally. */
|
|
@@ -32,11 +58,16 @@ export interface DrainableAgent {
|
|
|
32
58
|
readonly askInFlight: AskInFlight | null;
|
|
33
59
|
}
|
|
34
60
|
|
|
61
|
+
/** How long the drain waits, and whether it steers at all. */
|
|
62
|
+
export type PauseGrace =
|
|
63
|
+
| { readonly kind: "bounded"; readonly deadlineMs: number }
|
|
64
|
+
| { readonly kind: "natural" };
|
|
65
|
+
|
|
35
66
|
export interface PauseDrainOptions {
|
|
36
67
|
/** Live reference to the Run's Agent list; read at drain start. */
|
|
37
68
|
readonly agents: readonly DrainableAgent[];
|
|
38
|
-
/** Wall-clock grace before the abort (ADR-0024). */
|
|
39
|
-
readonly
|
|
69
|
+
/** Wall-clock grace before the abort (ADR-0024), or the natural wait (ADR-0022). */
|
|
70
|
+
readonly grace: PauseGrace;
|
|
40
71
|
/** Closes Ask and spawn admission before the first steer. */
|
|
41
72
|
readonly closeAdmission: () => void;
|
|
42
73
|
/** A stop request; it skips the remaining grace and takes the outcome. */
|
|
@@ -45,7 +76,12 @@ export interface PauseDrainOptions {
|
|
|
45
76
|
|
|
46
77
|
/** How one drain ended: paused, naming every Ask it cut short, or overridden by a stop. */
|
|
47
78
|
export type PauseDrainResult =
|
|
48
|
-
| {
|
|
79
|
+
| {
|
|
80
|
+
readonly kind: "paused";
|
|
81
|
+
readonly cutShort: readonly string[];
|
|
82
|
+
/** One line per Ask that rejected during the drain; never an outcome. */
|
|
83
|
+
readonly warnings: readonly string[];
|
|
84
|
+
}
|
|
49
85
|
| { readonly kind: "stopped" };
|
|
50
86
|
|
|
51
87
|
/**
|
|
@@ -56,19 +92,35 @@ export type PauseDrainResult =
|
|
|
56
92
|
*/
|
|
57
93
|
export async function drainForPause(options: PauseDrainOptions): Promise<PauseDrainResult> {
|
|
58
94
|
options.closeAdmission();
|
|
59
|
-
const inFlight = options.agents
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
95
|
+
const inFlight = waitable(options.agents);
|
|
96
|
+
if (inFlight.length === 0) return { kind: "paused", cutShort: [], warnings: [] };
|
|
97
|
+
const warnings: string[] = [];
|
|
98
|
+
for (const ask of inFlight) {
|
|
99
|
+
void ask.settled.then((settled) => {
|
|
100
|
+
if (settled.error !== undefined) warnings.push(warningLine(ask.agent, settled.error));
|
|
101
|
+
});
|
|
102
|
+
}
|
|
63
103
|
// The grace starts before the first steer, so an Agent that never answers a
|
|
64
104
|
// command cannot hold the drain open past the deadline, and a stop always
|
|
65
105
|
// lands. A refused steer is ignored on purpose: the deadline bounds it too.
|
|
66
106
|
const grace = raceGrace(inFlight, options);
|
|
67
|
-
for (const ask of inFlight) void ask.wrapUp();
|
|
107
|
+
if (options.grace.kind === "bounded") for (const ask of inFlight) void ask.wrapUp();
|
|
68
108
|
const outcome = await grace;
|
|
69
109
|
if (outcome === "stopped") return { kind: "stopped" };
|
|
70
|
-
if (outcome === "settled") return { kind: "paused", cutShort: [] };
|
|
71
|
-
return { kind: "paused", cutShort: abortRemaining(options.agents) };
|
|
110
|
+
if (outcome === "settled") return { kind: "paused", cutShort: [], warnings };
|
|
111
|
+
return { kind: "paused", cutShort: abortRemaining(options.agents), warnings };
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/** Every Ask the drain waits for: in flight, and not parked on a user question. */
|
|
115
|
+
function waitable(agents: readonly DrainableAgent[]): readonly AskInFlight[] {
|
|
116
|
+
return agents
|
|
117
|
+
.map((agent) => agent.askInFlight)
|
|
118
|
+
.filter((ask): ask is AskInFlight => ask !== null && ask.parked !== true);
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function warningLine(agent: string, error: unknown): string {
|
|
122
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
123
|
+
return `${agent}: Ask rejected during the pause drain: ${message}`;
|
|
72
124
|
}
|
|
73
125
|
|
|
74
126
|
type GraceOutcome = "settled" | "deadline" | "stopped";
|
|
@@ -79,13 +131,20 @@ function raceGrace(
|
|
|
79
131
|
options: PauseDrainOptions,
|
|
80
132
|
): Promise<GraceOutcome> {
|
|
81
133
|
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
134
|
+
// A parked Ask counts as quiescent: its own promise settles only at the reap,
|
|
135
|
+
// and the natural grace has no deadline that could end the wait (ADR-0023).
|
|
136
|
+
const quiet = inFlight.map((ask) =>
|
|
137
|
+
ask.parkedSignal === undefined
|
|
138
|
+
? ask.settled
|
|
139
|
+
: Promise.race([ask.settled, ask.parkedSignal.then(() => ({}) as AskSettled)]),
|
|
87
140
|
);
|
|
141
|
+
const settled = Promise.all(quiet).then<GraceOutcome>(() => "settled");
|
|
88
142
|
const stopped = options.stopped.then<GraceOutcome>(() => "stopped");
|
|
143
|
+
const grace = options.grace;
|
|
144
|
+
if (grace.kind === "natural") return Promise.race([settled, stopped]);
|
|
145
|
+
const deadline = new Promise<GraceOutcome>((resolve) => {
|
|
146
|
+
timer = setTimeout(() => resolve("deadline"), grace.deadlineMs);
|
|
147
|
+
});
|
|
89
148
|
return Promise.race([settled, deadline, stopped]).finally(() => {
|
|
90
149
|
clearTimeout(timer);
|
|
91
150
|
});
|
|
@@ -94,12 +153,10 @@ function raceGrace(
|
|
|
94
153
|
/**
|
|
95
154
|
* Aborts every Ask still in flight and names its Agent as cut short. The
|
|
96
155
|
* answers are deliberately not awaited: an Agent that swallows the abort must
|
|
97
|
-
* not hold the Run away from its reap ladder.
|
|
156
|
+
* not hold the Run away from its reap ladder. A parked Ask is exempt.
|
|
98
157
|
*/
|
|
99
158
|
function abortRemaining(agents: readonly DrainableAgent[]): readonly string[] {
|
|
100
|
-
const remaining = agents
|
|
101
|
-
.map((agent) => agent.askInFlight)
|
|
102
|
-
.filter((ask): ask is AskInFlight => ask !== null);
|
|
159
|
+
const remaining = waitable(agents);
|
|
103
160
|
for (const ask of remaining) void ask.abort();
|
|
104
161
|
return remaining.map((ask) => ask.agent);
|
|
105
162
|
}
|
package/src/errors.ts
CHANGED
|
@@ -22,7 +22,12 @@ export type {
|
|
|
22
22
|
YaagErrorCode,
|
|
23
23
|
} from "./contract/index.ts";
|
|
24
24
|
|
|
25
|
-
/**
|
|
25
|
+
/**
|
|
26
|
+
* The single error class of the runtime (ADR-0003).
|
|
27
|
+
*
|
|
28
|
+
* The fifth constructor parameter `cause` goes to `Error.prototype.cause`, so
|
|
29
|
+
* a wrapped failure keeps its origin.
|
|
30
|
+
*/
|
|
26
31
|
export class YaagError extends Error {
|
|
27
32
|
readonly code: YaagErrorCode;
|
|
28
33
|
/** Agent name, when the error concerns one. */
|
|
@@ -57,8 +62,9 @@ export class YaagError extends Error {
|
|
|
57
62
|
| AskStalledOutcome
|
|
58
63
|
| AskInvalidOutputOutcome
|
|
59
64
|
| ModelResolutionOutcome,
|
|
65
|
+
cause?: unknown,
|
|
60
66
|
) {
|
|
61
|
-
super(message);
|
|
67
|
+
super(message, { cause });
|
|
62
68
|
this.name = "YaagError";
|
|
63
69
|
this.code = code;
|
|
64
70
|
if (agent !== undefined) this.agent = agent;
|
package/src/events.ts
CHANGED
|
@@ -261,6 +261,12 @@ export type LifecycleEventBody =
|
|
|
261
261
|
* failed. Carries the publication error text. Absent on every other path.
|
|
262
262
|
*/
|
|
263
263
|
readonly checkpointLost?: string;
|
|
264
|
+
/**
|
|
265
|
+
* What went wrong beside the outcome: a sibling Ask that rejected during
|
|
266
|
+
* a pause drain, and (ticket 04) a summarizer failure. It never changes
|
|
267
|
+
* `outcome`. Absent when the Run has nothing to warn about.
|
|
268
|
+
*/
|
|
269
|
+
readonly warnings?: readonly string[];
|
|
264
270
|
/**
|
|
265
271
|
* Path of the Checkpoint this Run published, present only when the Run
|
|
266
272
|
* paused or stopped and publication succeeded (ADR-0054). The Reattach
|
package/src/index.ts
CHANGED
|
@@ -1,5 +1,10 @@
|
|
|
1
1
|
export type { AgentConfig, AgentDefinition } from "./agent/index.ts";
|
|
2
|
-
export {
|
|
2
|
+
export {
|
|
3
|
+
agentDefinitionConfig,
|
|
4
|
+
defineAgent,
|
|
5
|
+
isAgentDefinition,
|
|
6
|
+
isSpawnableDefinition,
|
|
7
|
+
} from "./agent/index.ts";
|
|
3
8
|
export type {
|
|
4
9
|
Cassette,
|
|
5
10
|
CassetteAgent,
|
|
@@ -48,6 +53,7 @@ export {
|
|
|
48
53
|
AGENT_DESCRIBE_TRANSCRIPT,
|
|
49
54
|
agentDescribeArgv,
|
|
50
55
|
CATALOG_FIXTURE,
|
|
56
|
+
createYaagGlobal,
|
|
51
57
|
describedAgent,
|
|
52
58
|
encodeAgentDescribe,
|
|
53
59
|
filterCatalog,
|
|
@@ -159,12 +165,22 @@ export {
|
|
|
159
165
|
} from "./profile/index.ts";
|
|
160
166
|
export { prompt, promptGist } from "./prompt/index.ts";
|
|
161
167
|
export type {
|
|
168
|
+
AskUserOptions,
|
|
162
169
|
OrchestrationProgram,
|
|
163
170
|
ProgramDefinition,
|
|
171
|
+
Question,
|
|
164
172
|
RunContext,
|
|
165
173
|
RunOptions,
|
|
174
|
+
RunResult,
|
|
175
|
+
} from "./run/index.ts";
|
|
176
|
+
export {
|
|
177
|
+
defineRun,
|
|
178
|
+
executeRun,
|
|
179
|
+
isOrchestrationProgram,
|
|
180
|
+
isPauseSignal,
|
|
181
|
+
programDefinition,
|
|
182
|
+
RunPauseSignal,
|
|
166
183
|
} from "./run/index.ts";
|
|
167
|
-
export { defineRun, executeRun, isOrchestrationProgram, programDefinition } from "./run/index.ts";
|
|
168
184
|
export type {
|
|
169
185
|
AgentInfo,
|
|
170
186
|
AgentState,
|
package/src/model/index.ts
CHANGED
package/src/public-api.ts
CHANGED
|
@@ -12,6 +12,12 @@
|
|
|
12
12
|
|
|
13
13
|
export type { AgentConfig, AgentDefinition } from "./agent/define-agent.ts";
|
|
14
14
|
export { defineAgent } from "./agent/define-agent.ts";
|
|
15
|
+
export type {
|
|
16
|
+
CatalogScope,
|
|
17
|
+
SpawnableDefinition,
|
|
18
|
+
YaagGlobal,
|
|
19
|
+
YaagGlobalOptions,
|
|
20
|
+
} from "./contract/catalog-resolve.ts";
|
|
15
21
|
export type {
|
|
16
22
|
AgentPolicy,
|
|
17
23
|
AskOptions,
|
|
@@ -53,6 +59,7 @@ export { isProfiledDefinition, useProfile } from "./profile/use-profile.ts";
|
|
|
53
59
|
export { prompt } from "./prompt/prompt.ts";
|
|
54
60
|
export type { OrchestrationProgram, ProgramDefinition } from "./run/define-run.ts";
|
|
55
61
|
export { defineRun } from "./run/define-run.ts";
|
|
62
|
+
export type { AskUserOptions, Question } from "./run/questions.ts";
|
|
56
63
|
export type { RunContext } from "./run/run-context.ts";
|
|
57
64
|
export type { YaagSystemPromptOptions } from "./system-prompt/agent-system-prompt.ts";
|
|
58
65
|
export { yaagSystemPrompt } from "./system-prompt/agent-system-prompt.ts";
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public surface of the `question-summary/` module: the fork summarizer that
|
|
3
|
+
* fills `summary` on an Agent Question (ADR-0022). It is named for the glossary
|
|
4
|
+
* term, and stays apart from `summary/`, which owns the Run Summary fold.
|
|
5
|
+
* Files inside this directory import each other directly.
|
|
6
|
+
*/
|
|
7
|
+
|
|
8
|
+
export {
|
|
9
|
+
prepareSessionCopy,
|
|
10
|
+
type SessionCopy,
|
|
11
|
+
type SessionCopyRequest,
|
|
12
|
+
SYNTHETIC_TOOL_RESULT_TEXT,
|
|
13
|
+
} from "./session-copy.ts";
|
|
14
|
+
export {
|
|
15
|
+
type InternalOpen,
|
|
16
|
+
type ParkedAgent,
|
|
17
|
+
type QuestionSummaryResult,
|
|
18
|
+
SUMMARIZER_PROMPT,
|
|
19
|
+
type SummarizeQuestionsRequest,
|
|
20
|
+
summarizeQuestions,
|
|
21
|
+
} from "./summarize-question.ts";
|
|
22
|
+
export { summarizes } from "./summary-policy.ts";
|