@yaag/runtime 0.11.0 → 0.13.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-compaction.ts +1 -1
- package/src/agent/agent.ts +1 -1
- package/src/agent/define-agent.ts +7 -5
- package/src/agent/spawn-open.ts +2 -0
- package/src/ask/ask-exchange-events.ts +8 -3
- package/src/ask/ask-exchange.ts +6 -9
- package/src/catalog/agent-describe-fixture.ts +121 -0
- package/src/catalog/agent-describe.ts +210 -0
- package/src/catalog/catalog-entry.ts +39 -0
- package/src/catalog/catalog-fixture.ts +87 -0
- package/src/catalog/catalog-match.ts +77 -0
- package/src/catalog/catalog-result.ts +69 -0
- package/src/catalog/index.ts +57 -0
- package/src/catalog/load-catalog.ts +74 -0
- package/src/catalog/program-scan.ts +64 -0
- package/src/catalog/registry-paths.ts +26 -0
- package/src/catalog/registry-reader.ts +115 -0
- package/src/catalog/registry-schema.ts +119 -0
- package/src/config/config-paths.ts +14 -7
- package/src/config/index.ts +1 -0
- package/src/contract/agent-report.ts +42 -0
- package/src/contract/error-codes.ts +65 -0
- package/src/contract/handle.ts +132 -0
- package/src/contract/index.ts +34 -0
- package/src/contract/model-spec.ts +81 -0
- package/src/contract/spawn-options.ts +127 -0
- package/src/error-factories.ts +70 -0
- package/src/errors.ts +22 -118
- package/src/events.ts +13 -2
- package/src/index.ts +45 -0
- package/src/model/index.ts +1 -1
- package/src/model/model-resolution.ts +19 -71
- package/src/model/model-swap.ts +11 -2
- package/src/model/resolution-loop.ts +1 -1
- package/src/model/thinking-level.ts +5 -5
- package/src/public-api.ts +28 -0
- package/src/run/run-context.ts +4 -2
- package/src/summary/summary-agent.ts +8 -2
- package/src/summary/summary-model.ts +5 -1
- package/src/transport/live-transport.ts +2 -3
- package/src/transport/pi-state.ts +29 -9
- package/src/transport/transport.ts +10 -26
- package/src/types.ts +16 -243
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The Handle and its Ask declarations (ADR-0003, ADR-0032, ADR-0044).
|
|
3
|
+
*
|
|
4
|
+
* Types only, and no import outside this directory except `typebox` (ADR-0045).
|
|
5
|
+
*/
|
|
6
|
+
import type { Static, TSchema } from "typebox";
|
|
7
|
+
import type { CompactionResult } from "./agent-report.ts";
|
|
8
|
+
import type { ForkOptions } from "./spawn-options.ts";
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* Options for one Ask (ADR-0003).
|
|
12
|
+
*
|
|
13
|
+
* Soft limits trip at their configured count: turns are `turn_start` frames and
|
|
14
|
+
* tool calls are `tool_execution_start` frames between `agent_start` and
|
|
15
|
+
* `agent_settled`; duration is wall time from prompt send. A trip steers the
|
|
16
|
+
* Agent, permits one further turn (or a fixed duration grace), then aborts and
|
|
17
|
+
* rejects with `ASK_LIMIT` if it has not settled. This leaves the Handle alive.
|
|
18
|
+
* `timeoutMs` is independent: it kills the Agent and rejects with `ASK_TIMEOUT`.
|
|
19
|
+
*
|
|
20
|
+
* A model failure inside an Ask starts Model Fallback and retries the Ask
|
|
21
|
+
* (ADR-0038). Each attempt gets fresh soft limits, a fresh Stall Watchdog and a
|
|
22
|
+
* fresh output collector. `timeoutMs` is the exception: it is the hard ceiling
|
|
23
|
+
* of the whole Ask, and every attempt shares one deadline.
|
|
24
|
+
*/
|
|
25
|
+
export interface AskOptions {
|
|
26
|
+
/** Reject and kill the Agent if it has not settled in time. Unset = no bound. */
|
|
27
|
+
readonly timeoutMs?: number;
|
|
28
|
+
/** Soft budget of `turn_start` frames between `agent_start` and `agent_settled`. */
|
|
29
|
+
readonly maxTurns?: number;
|
|
30
|
+
/** Soft budget of `tool_execution_start` frames between `agent_start` and `agent_settled`. */
|
|
31
|
+
readonly maxToolCalls?: number;
|
|
32
|
+
/** Soft wall-clock budget in milliseconds, measured from prompt send. */
|
|
33
|
+
readonly maxDurationMs?: number;
|
|
34
|
+
/**
|
|
35
|
+
* Maximum silence in milliseconds: rejects with `ASK_STALLED` when no frame
|
|
36
|
+
* arrives for this span. Complementary to `maxDurationMs` (silence vs.
|
|
37
|
+
* trickle) and separate from `timeoutMs`, which always kills. Unset disables
|
|
38
|
+
* idle detection (ADR-0020).
|
|
39
|
+
*/
|
|
40
|
+
readonly idleMs?: number;
|
|
41
|
+
/**
|
|
42
|
+
* Silence budget in milliseconds for the Stall Watchdog, which guards every
|
|
43
|
+
* live Ask by default (ADR-0029). On expiry yaag probes the Agent and either
|
|
44
|
+
* recovers a missed settlement or rejects with `ASK_STALLED`. Omission uses
|
|
45
|
+
* the 10-minute default. `false`, and any value that is not above zero,
|
|
46
|
+
* disable the watchdog for this Ask. `ASK_STALLED` is a generic failure: it
|
|
47
|
+
* never starts Model Fallback. If the silence budget ends the Ask before pi
|
|
48
|
+
* reports a model failure, the Ask fails `ASK_STALLED` and no swap happens
|
|
49
|
+
* (ADR-0029).
|
|
50
|
+
*/
|
|
51
|
+
readonly stallMs?: number | false;
|
|
52
|
+
/** Per-Ask replacement for the runtime's wrap-up steering message. */
|
|
53
|
+
readonly wrapUpPrompt?: string;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Ask options that require a schema and preserve its inferred successful result. */
|
|
57
|
+
export interface StructuredAskOptions<Schema extends TSchema> extends AskOptions {
|
|
58
|
+
/**
|
|
59
|
+
* TypeBox object schema the Agent reports its result against, instead of text.
|
|
60
|
+
*
|
|
61
|
+
* It becomes the input schema of one internal tool, so it must describe an
|
|
62
|
+
* object (ADR-0032).
|
|
63
|
+
*/
|
|
64
|
+
readonly outputSchema: Schema;
|
|
65
|
+
/**
|
|
66
|
+
* Maximum settlements without a reported result that this Ask corrects;
|
|
67
|
+
* defaults to 3 when omitted. Argument repair inside a turn is the Agent's
|
|
68
|
+
* own loop and costs nothing here.
|
|
69
|
+
*/
|
|
70
|
+
readonly maxSteers?: number;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
74
|
+
* A handle to one long-lived Agent.
|
|
75
|
+
* ADR-0003: `ask()` is the only conversational verb; everything else is data.
|
|
76
|
+
*/
|
|
77
|
+
export interface Handle {
|
|
78
|
+
/** Stable identity, used in every Lifecycle Event and log line. */
|
|
79
|
+
readonly name: string;
|
|
80
|
+
/** Resolved absolute working directory; a worktree's actual cwd after spawn resolves. */
|
|
81
|
+
readonly cwd: string;
|
|
82
|
+
/** Fresh branch for a worktree Agent; undefined for ordinary Agents. */
|
|
83
|
+
readonly branch: string | undefined;
|
|
84
|
+
/**
|
|
85
|
+
* Model id as reported by the Agent's own `get_state` — not the requested
|
|
86
|
+
* pattern. A mid-Ask model swap updates it (ADR-0038).
|
|
87
|
+
*/
|
|
88
|
+
readonly model: string;
|
|
89
|
+
|
|
90
|
+
/**
|
|
91
|
+
* Sends a prompt and resolves after the Agent's turn settles.
|
|
92
|
+
*
|
|
93
|
+
* Schema-free calls resolve with the exact final assistant text. Calls with
|
|
94
|
+
* `outputSchema` resolve with the TypeBox-validated value the Agent reports
|
|
95
|
+
* through one internal tool call (ADR-0032). Rejects with a YaagError for a
|
|
96
|
+
* failed or empty turn, timeout, `ASK_LIMIT`, or dead Agent. An Ask that
|
|
97
|
+
* settles without a reported result is corrected at most `maxSteers` times
|
|
98
|
+
* (default 3) and then rejects recoverably with `ASK_INVALID_OUTPUT` after an
|
|
99
|
+
* abort settlement; a reported value the schema rejects fails the same way
|
|
100
|
+
* without a correction. These recoverable outcomes leave the Handle reusable.
|
|
101
|
+
* A retry after a Model Fallback discards the result the failed attempt
|
|
102
|
+
* reported, and arms the collector again, so a stale result cannot settle the
|
|
103
|
+
* retried Ask (ADR-0032, ADR-0038).
|
|
104
|
+
* A concurrent call rejects with `AGENT_BUSY`.
|
|
105
|
+
*/
|
|
106
|
+
ask<Schema extends TSchema>(
|
|
107
|
+
prompt: string,
|
|
108
|
+
options: StructuredAskOptions<Schema>,
|
|
109
|
+
): Promise<Static<Schema>>;
|
|
110
|
+
ask(prompt: string, options?: AskOptions): Promise<string>;
|
|
111
|
+
|
|
112
|
+
/**
|
|
113
|
+
* Spawns a new Agent from a copy of this Agent's session (ADR-0044).
|
|
114
|
+
*
|
|
115
|
+
* The fork point is a settled Ask boundary: a call while an Ask is in flight
|
|
116
|
+
* rejects with `FORK_DURING_ASK`. An Agent that died mid-Ask, or that holds
|
|
117
|
+
* no session file, rejects with `FORK_REFUSED`. An Agent that exited cleanly
|
|
118
|
+
* stays forkable, so a program can build context, let the Agent exit, then
|
|
119
|
+
* fork its final state many times.
|
|
120
|
+
*/
|
|
121
|
+
fork(overrides?: ForkOptions): Promise<Handle>;
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* Replaces this Agent's context with a summary of it (ADR-0043).
|
|
125
|
+
*
|
|
126
|
+
* `instructions` becomes pi's `customInstructions`. A call while an Ask is in
|
|
127
|
+
* flight rejects with `COMPACT_DURING_ASK`; a refusal from pi rejects with
|
|
128
|
+
* `COMPACT_FAILED`. The result reports what the summary call cost; each field
|
|
129
|
+
* is null when pi reported nothing for it.
|
|
130
|
+
*/
|
|
131
|
+
compact(instructions?: string): Promise<CompactionResult>;
|
|
132
|
+
}
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Public surface of the `contract/` module: the declarations an Orchestration
|
|
3
|
+
* Program author reads (ADR-0045).
|
|
4
|
+
*
|
|
5
|
+
* Every file here is type-only and imports nothing outside this directory
|
|
6
|
+
* except `typebox`. That keeps the declaration tree a workspace gets small.
|
|
7
|
+
* Files inside this directory import each other directly.
|
|
8
|
+
*/
|
|
9
|
+
export type { AgentProgress, CompactionResult, TokenBreakdown } from "./agent-report.ts";
|
|
10
|
+
export type {
|
|
11
|
+
AskInvalidOutputOutcome,
|
|
12
|
+
AskLimitKind,
|
|
13
|
+
AskLimitOutcome,
|
|
14
|
+
AskStalledOutcome,
|
|
15
|
+
ModelResolutionOutcome,
|
|
16
|
+
YaagErrorCode,
|
|
17
|
+
} from "./error-codes.ts";
|
|
18
|
+
export type { AskOptions, Handle, StructuredAskOptions } from "./handle.ts";
|
|
19
|
+
export type {
|
|
20
|
+
ModelError,
|
|
21
|
+
ModelErrorReason,
|
|
22
|
+
ModelResolver,
|
|
23
|
+
ModelSelection,
|
|
24
|
+
ModelSpec,
|
|
25
|
+
ThinkingLevel,
|
|
26
|
+
ThinkingResolver,
|
|
27
|
+
ThinkingSpec,
|
|
28
|
+
} from "./model-spec.ts";
|
|
29
|
+
export type {
|
|
30
|
+
ForkOptions,
|
|
31
|
+
ResolvedSpawnOptions,
|
|
32
|
+
SpawnOptions,
|
|
33
|
+
SpawnOverrides,
|
|
34
|
+
} from "./spawn-options.ts";
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Model and thinking declarations of the author contract (ADR-0037, ADR-0045).
|
|
3
|
+
*
|
|
4
|
+
* Types only, and no import outside this directory, so the emitted declaration
|
|
5
|
+
* tree of a workspace stays at the author surface. The values that consume
|
|
6
|
+
* these types stay in `model/`.
|
|
7
|
+
*/
|
|
8
|
+
|
|
9
|
+
/** pi's supported thinking levels. */
|
|
10
|
+
export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* Why one model candidate was rejected by pi (ADR-0037).
|
|
14
|
+
*
|
|
15
|
+
* `not_found`: the pattern matched no model, or pi refused the live swap.
|
|
16
|
+
* `auth`: the provider refused the credentials.
|
|
17
|
+
* `rate_limited`: the provider stayed rate-limited after pi's own retries.
|
|
18
|
+
*
|
|
19
|
+
* These three classes are the only triggers of Model Resolution. A different
|
|
20
|
+
* transport or turn failure stays an ordinary failure and starts no new attempt.
|
|
21
|
+
*/
|
|
22
|
+
export type ModelErrorReason = "not_found" | "auth" | "rate_limited";
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* One failed Model Resolution attempt, handed back to the caller's resolver.
|
|
26
|
+
*
|
|
27
|
+
* yaag gives the full history to each resolver call, oldest attempt first. The
|
|
28
|
+
* first call gets an empty list (ADR-0037).
|
|
29
|
+
*/
|
|
30
|
+
export interface ModelError {
|
|
31
|
+
readonly reason: ModelErrorReason;
|
|
32
|
+
/** The model pattern that failed, after inline-suffix stripping. */
|
|
33
|
+
readonly failedModel: string;
|
|
34
|
+
/** 0-based index of the attempt that produced this error. */
|
|
35
|
+
readonly attempt: number;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* Picks the next model candidate, or `undefined` to give up (ADR-0037).
|
|
40
|
+
*
|
|
41
|
+
* When the resolver gives up, the spawn or the Ask fails with
|
|
42
|
+
* `MODEL_RESOLUTION_FAILED`, which carries the full error history. yaag also
|
|
43
|
+
* refuses a candidate that already failed with `not_found` or `auth` in the
|
|
44
|
+
* same loop, so a resolver cannot loop forever. The resolver must be pure and
|
|
45
|
+
* synchronous.
|
|
46
|
+
*/
|
|
47
|
+
export type ModelResolver = (errors: readonly ModelError[]) => string | undefined;
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Every accepted `model` form: one pattern, an ordered list, or a resolver.
|
|
51
|
+
*
|
|
52
|
+
* An array is the resolver that reads the candidate at the attempt index, and
|
|
53
|
+
* gives `undefined` past the end. One pattern is the one-element list. So the
|
|
54
|
+
* termination rule of `ModelResolver` covers every form (ADR-0037).
|
|
55
|
+
*/
|
|
56
|
+
export type ModelSpec = string | readonly string[] | ModelResolver;
|
|
57
|
+
|
|
58
|
+
/**
|
|
59
|
+
* Picks the thinking level for a settled model, or `undefined` for pi's default.
|
|
60
|
+
*
|
|
61
|
+
* `undefined` means "no thinking preference". It is not a failure, and it does
|
|
62
|
+
* not stop the attempt (ADR-0037).
|
|
63
|
+
*/
|
|
64
|
+
export type ThinkingResolver = (
|
|
65
|
+
selectedModel: string,
|
|
66
|
+
errors: readonly ModelError[],
|
|
67
|
+
) => ThinkingLevel | undefined;
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Every accepted `thinking` form: one level or a resolver.
|
|
71
|
+
*
|
|
72
|
+
* An inline suffix on the resolved model pattern wins over this property
|
|
73
|
+
* (ADR-0037).
|
|
74
|
+
*/
|
|
75
|
+
export type ThinkingSpec = ThinkingLevel | ThinkingResolver;
|
|
76
|
+
|
|
77
|
+
/** One attempt's settled selection; `model: undefined` inherits pi's default model. */
|
|
78
|
+
export interface ModelSelection {
|
|
79
|
+
readonly model: string | undefined;
|
|
80
|
+
readonly thinking: ThinkingLevel | undefined;
|
|
81
|
+
}
|
|
@@ -0,0 +1,127 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Spawn declarations of the author contract (ADR-0001, ADR-0009, ADR-0026).
|
|
3
|
+
*
|
|
4
|
+
* Types only, and no import outside this directory (ADR-0045).
|
|
5
|
+
*/
|
|
6
|
+
|
|
7
|
+
import type { Handle } from "./handle.ts";
|
|
8
|
+
import type { ModelSpec, ThinkingLevel, ThinkingSpec } from "./model-spec.ts";
|
|
9
|
+
|
|
10
|
+
/** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
|
|
11
|
+
export interface SpawnOptions {
|
|
12
|
+
/** Working directory. Defaults to the Orchestrator's cwd. */
|
|
13
|
+
readonly cwd?: string;
|
|
14
|
+
/**
|
|
15
|
+
* Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default.
|
|
16
|
+
*
|
|
17
|
+
* An array is an ordered fallback list and a function picks the next candidate
|
|
18
|
+
* from the failures so far. Any resolved pattern may carry an inline thinking
|
|
19
|
+
* suffix (`"opus-5:medium"`), which wins over `thinking`. Each attempt settles
|
|
20
|
+
* the model first, then the thinking level for that model. yaag starts a new
|
|
21
|
+
* attempt only when pi reports `not_found`, `auth`, or `rate_limited`. See
|
|
22
|
+
* `ModelSpec` and `ModelResolver` for the termination rules (ADR-0037).
|
|
23
|
+
*/
|
|
24
|
+
readonly model?: ModelSpec;
|
|
25
|
+
/**
|
|
26
|
+
* Replaces pi's default system prompt (`pi --system-prompt`), which removes
|
|
27
|
+
* pi's own documentation and tool guidance from the Agent.
|
|
28
|
+
*/
|
|
29
|
+
readonly systemPrompt?: string;
|
|
30
|
+
/**
|
|
31
|
+
* Sets pi's thinking level; omission preserves pi's default. A function picks
|
|
32
|
+
* the level from the settled model, and is not consulted for a model pattern
|
|
33
|
+
* that carries an inline thinking suffix. The resolver runs again for each
|
|
34
|
+
* attempt, with the model that settled for that attempt (ADR-0037).
|
|
35
|
+
*/
|
|
36
|
+
readonly thinking?: ThinkingSpec;
|
|
37
|
+
/** Adds text after pi's default system prompt, which stays (`pi --append-system-prompt`). */
|
|
38
|
+
readonly appendSystemPrompt?: string;
|
|
39
|
+
/**
|
|
40
|
+
* Restores pi discovery. Omission or false selects ADR-0026's hermetic baseline.
|
|
41
|
+
*/
|
|
42
|
+
readonly inherit?: boolean;
|
|
43
|
+
/**
|
|
44
|
+
* Explicit pi extensions layer over either ADR-0026 baseline. Relative entries
|
|
45
|
+
* resolve from the Orchestration Program file; each becomes `pi -e <path>`.
|
|
46
|
+
*/
|
|
47
|
+
readonly extensions?: readonly string[];
|
|
48
|
+
/**
|
|
49
|
+
* Load the Effective Config's `agents.extensions` for this Agent. Default
|
|
50
|
+
* true; false spawns with only the extensions this call declares (ADR-0040).
|
|
51
|
+
*/
|
|
52
|
+
readonly configExtensions?: boolean;
|
|
53
|
+
/**
|
|
54
|
+
* Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
|
|
55
|
+
* `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;
|
|
56
|
+
* a missing promised name rejects spawn.
|
|
57
|
+
*/
|
|
58
|
+
readonly tools?: readonly string[];
|
|
59
|
+
/**
|
|
60
|
+
* Tool denylist applied last under ADR-0026; `['yaag_run']` prevents nested yaag Runs.
|
|
61
|
+
* Denying an absent tool is inert and is not presence-validated.
|
|
62
|
+
*/
|
|
63
|
+
readonly disallowedTools?: readonly string[];
|
|
64
|
+
/**
|
|
65
|
+
* Skill-name allowlist, not filesystem paths, layered over the ADR-0026 baseline.
|
|
66
|
+
* Omission is skill-free when hermetic; `disallowedSkills` applies last. Unknown requested
|
|
67
|
+
* names reject spawn.
|
|
68
|
+
*/
|
|
69
|
+
readonly skills?: readonly string[];
|
|
70
|
+
/** Skill-name denylist discovered from pi and applied last (ADR-0026). */
|
|
71
|
+
readonly disallowedSkills?: readonly string[];
|
|
72
|
+
/** Log and event label. Defaults to a1, a2, …; duplicate names are suffixed. */
|
|
73
|
+
readonly name?: string;
|
|
74
|
+
/** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
|
|
75
|
+
readonly worktree?: boolean;
|
|
76
|
+
/**
|
|
77
|
+
* Names this Agent's parent in the Run tree (Parent Link). Data only: it is
|
|
78
|
+
* no conversation channel and no lifetime rule.
|
|
79
|
+
*/
|
|
80
|
+
readonly parent?: Handle;
|
|
81
|
+
}
|
|
82
|
+
|
|
83
|
+
/**
|
|
84
|
+
* Spawn options after Model Resolution has settled one model and thinking level.
|
|
85
|
+
*
|
|
86
|
+
* This is the settled shape, and it is what the Cassette identity hashes
|
|
87
|
+
* (ADR-0039).
|
|
88
|
+
*
|
|
89
|
+
* `parent` is omitted on purpose: a Handle must never reach this shape, because
|
|
90
|
+
* an Ask records these options into the Cassette. Spawn resolves the Parent
|
|
91
|
+
* Link to a name, which travels in `OpenOptions` and stays out of Ask identity.
|
|
92
|
+
*/
|
|
93
|
+
export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking" | "parent"> {
|
|
94
|
+
readonly model?: string;
|
|
95
|
+
readonly thinking?: ThinkingLevel;
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
/**
|
|
99
|
+
* What a fork may change about the Agent it copies (ADR-0044).
|
|
100
|
+
*
|
|
101
|
+
* A fork inherits the source's resolved spawn options verbatim: model,
|
|
102
|
+
* thinking, tools, skills, system prompt, extensions and Ask defaults. `name`
|
|
103
|
+
* is the exception — the child always gets a fresh auto-name unless this object
|
|
104
|
+
* names one. The fork source becomes the child's default `parent`.
|
|
105
|
+
*
|
|
106
|
+
* The inherited model is the concrete one the source settled on, so the child
|
|
107
|
+
* never re-runs the source's fallback list; `fork({ model })` is the way out.
|
|
108
|
+
* A fork of a Worktree Agent gets its own fresh worktree, branched from the
|
|
109
|
+
* source's branch, so only committed state transfers. The child re-runs the
|
|
110
|
+
* ADR-0026 Tool Contract probe against its own effective options.
|
|
111
|
+
*/
|
|
112
|
+
export interface ForkOptions extends SpawnOptions {
|
|
113
|
+
/** true = pi's default compaction; a string = pi custom instructions. */
|
|
114
|
+
readonly compact?: boolean | string;
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/** Topology-only fields that may change when spawning an Agent Definition. */
|
|
118
|
+
export interface SpawnOverrides {
|
|
119
|
+
/** Log and event label. Defaults to the definition's name; duplicates are suffixed. */
|
|
120
|
+
readonly name?: string;
|
|
121
|
+
/** Working directory. Defaults to the Orchestrator's cwd. */
|
|
122
|
+
readonly cwd?: string;
|
|
123
|
+
/** Request a fresh Git worktree. */
|
|
124
|
+
readonly worktree?: boolean;
|
|
125
|
+
/** Names this Agent's parent in the Run tree (Parent Link). Data only. */
|
|
126
|
+
readonly parent?: Handle;
|
|
127
|
+
}
|
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Constructors for the runtime's recurring `YaagError` messages.
|
|
3
|
+
*
|
|
4
|
+
* They are values, and no author imports them, so they stay out of `errors.ts`
|
|
5
|
+
* and out of the author declaration tree (ADR-0045).
|
|
6
|
+
*/
|
|
7
|
+
import type {
|
|
8
|
+
AskLimitOutcome,
|
|
9
|
+
AskStalledOutcome,
|
|
10
|
+
ModelError,
|
|
11
|
+
YaagErrorCode,
|
|
12
|
+
} from "./contract/index.ts";
|
|
13
|
+
import { YaagError } from "./errors.ts";
|
|
14
|
+
|
|
15
|
+
/** Builds the runtime's uniform agent-scoped error message. */
|
|
16
|
+
export function agentError(agent: string, code: YaagErrorCode, message: string): YaagError {
|
|
17
|
+
return new YaagError(code, `agent "${agent}": ${message}`, agent);
|
|
18
|
+
}
|
|
19
|
+
|
|
20
|
+
/** The ASK_LIMIT rejection for one exhausted soft budget. */
|
|
21
|
+
export function askLimitError(agent: string, outcome: AskLimitOutcome): YaagError {
|
|
22
|
+
return new YaagError(
|
|
23
|
+
"ASK_LIMIT",
|
|
24
|
+
`agent "${agent}": ${outcome.kind} limit reached at ${outcome.count}`,
|
|
25
|
+
agent,
|
|
26
|
+
outcome,
|
|
27
|
+
);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/** The ASK_STALLED rejection for one tripped idle watch. */
|
|
31
|
+
export function askStalledError(agent: string, outcome: AskStalledOutcome): YaagError {
|
|
32
|
+
return new YaagError(
|
|
33
|
+
"ASK_STALLED",
|
|
34
|
+
`agent "${agent}": no frame for ${outcome.idleMs}ms${outcome.destructive ? " (killed)" : ""}`,
|
|
35
|
+
agent,
|
|
36
|
+
outcome,
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
/** The MODEL_RESOLUTION_FAILED rejection for an exhausted or self-repeating resolver. */
|
|
41
|
+
export function modelResolutionError(
|
|
42
|
+
agent: string,
|
|
43
|
+
errors: readonly ModelError[],
|
|
44
|
+
refusedCandidate?: string,
|
|
45
|
+
): YaagError {
|
|
46
|
+
if (errors.length === 0) {
|
|
47
|
+
return new YaagError(
|
|
48
|
+
"MODEL_RESOLUTION_FAILED",
|
|
49
|
+
`agent "${agent}": no model candidate to try`,
|
|
50
|
+
agent,
|
|
51
|
+
{ modelErrors: errors },
|
|
52
|
+
);
|
|
53
|
+
}
|
|
54
|
+
const history = errors.map((error) => `${error.failedModel} (${error.reason})`).join(", ");
|
|
55
|
+
// The guard only refuses a candidate that has a matching permanent entry.
|
|
56
|
+
const refusal =
|
|
57
|
+
refusedCandidate === undefined
|
|
58
|
+
? ""
|
|
59
|
+
: `; refused to retry "${refusedCandidate}", which already failed with ${
|
|
60
|
+
errors.find((error) => error.failedModel === refusedCandidate)?.reason
|
|
61
|
+
}`;
|
|
62
|
+
return new YaagError(
|
|
63
|
+
"MODEL_RESOLUTION_FAILED",
|
|
64
|
+
`agent "${agent}": model resolution gave up after ${errors.length} attempt${
|
|
65
|
+
errors.length === 1 ? "" : "s"
|
|
66
|
+
}: ${history}${refusal}`,
|
|
67
|
+
agent,
|
|
68
|
+
{ modelErrors: errors },
|
|
69
|
+
);
|
|
70
|
+
}
|
package/src/errors.ts
CHANGED
|
@@ -1,65 +1,26 @@
|
|
|
1
|
-
/**
|
|
2
|
-
|
|
1
|
+
/**
|
|
2
|
+
* The runtime's single error class (ADR-0003). Its codes and outcome shapes
|
|
3
|
+
* live in `contract/` so the author declaration tree stays small (ADR-0045).
|
|
4
|
+
*/
|
|
5
|
+
import type {
|
|
6
|
+
AgentProgress,
|
|
7
|
+
AskInvalidOutputOutcome,
|
|
8
|
+
AskLimitKind,
|
|
9
|
+
AskLimitOutcome,
|
|
10
|
+
AskStalledOutcome,
|
|
11
|
+
ModelError,
|
|
12
|
+
ModelResolutionOutcome,
|
|
13
|
+
YaagErrorCode,
|
|
14
|
+
} from "./contract/index.ts";
|
|
3
15
|
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
export type { ModelError } from "./model/index.ts";
|
|
14
|
-
export type { AgentProgress } from "./transport/index.ts";
|
|
15
|
-
|
|
16
|
-
/** The recorded result when yaag rejects an Ask because no frame arrived within `idleMs`. */
|
|
17
|
-
export interface AskStalledOutcome {
|
|
18
|
-
/** The configured silence threshold that tripped. */
|
|
19
|
-
readonly idleMs: number;
|
|
20
|
-
/** True when escalation failed to settle the Agent and yaag killed the process. */
|
|
21
|
-
readonly destructive: boolean;
|
|
22
|
-
/** State the Stall Watchdog probe observed; absent when the probe stayed silent. */
|
|
23
|
-
readonly state?: AgentProgress;
|
|
24
|
-
}
|
|
25
|
-
|
|
26
|
-
/** Recoverable result when all structured-output correction efforts are exhausted. */
|
|
27
|
-
export interface AskInvalidOutputOutcome {
|
|
28
|
-
/** Corrective steers sent before aborting this Ask. */
|
|
29
|
-
readonly steeringEfforts: number;
|
|
30
|
-
/** Final extraction or TypeBox diagnostics, localized to JSON paths. */
|
|
31
|
-
readonly errors: readonly string[];
|
|
32
|
-
}
|
|
33
|
-
|
|
34
|
-
/** The recorded history when every model candidate of one Model Resolution loop failed. */
|
|
35
|
-
export interface ModelResolutionOutcome {
|
|
36
|
-
readonly modelErrors: readonly ModelError[];
|
|
37
|
-
}
|
|
38
|
-
|
|
39
|
-
/** Why an Ask, spawn, or Run failed. Programs may branch on this; most won't. */
|
|
40
|
-
export type YaagErrorCode =
|
|
41
|
-
| "AGENT_FAILED" // turn settled with stopReason error/aborted, or empty text
|
|
42
|
-
| "AGENT_DIED" // process exited with an Ask pending
|
|
43
|
-
| "AGENT_BUSY" // concurrent ask() on one Handle
|
|
44
|
-
| "ASK_TIMEOUT" // timeoutMs elapsed
|
|
45
|
-
| "ASK_LIMIT" // soft Ask budget exceeded after grace
|
|
46
|
-
| "ASK_STALLED" // no frame arrived within the silence budget; escalated, then kill
|
|
47
|
-
| "COMPACT_DURING_ASK" // compact() was called while an Ask was in flight
|
|
48
|
-
| "COMPACT_FAILED" // pi refused or could not summarize the context
|
|
49
|
-
| "FORK_DURING_ASK" // fork() was called while the source Ask was in flight
|
|
50
|
-
| "FORK_REFUSED" // the fork source died mid-Ask, or holds no session file
|
|
51
|
-
| "ASK_INVALID_OUTPUT" // settled text could not be extracted or satisfy outputSchema
|
|
52
|
-
| "ARGS_INVALID" // arguments failed schema validation before the Run started
|
|
53
|
-
| "CONFIG_INVALID" // a config layer is missing, unparsable, or violates the schema
|
|
54
|
-
| "OPTIONS_CONFLICT" // incompatible Run options were supplied
|
|
55
|
-
| "RECORD_PATH_UNUSABLE" // the --record directory could not be created at Run start
|
|
56
|
-
| "REPLAY_DIVERGED" // replayed program differed from its Cassette
|
|
57
|
-
| "RESUME_REFUSED" // resume metadata is absent or the recorded tree moved
|
|
58
|
-
| "RUN_CLOSED" // spawn was requested after the Run began settling
|
|
59
|
-
| "RUN_STOPPED" // the Run's abort signal fired before the program completed
|
|
60
|
-
| "WORKTREE_REFUSED" // base cwd is not a clean Git repository
|
|
61
|
-
| "MODEL_RESOLUTION_FAILED" // the resolver gave up, or every candidate failed; carries the history
|
|
62
|
-
| "SPAWN_FAILED"; // pi failed to start, e.g. a broken tool contract or a startup timeout
|
|
16
|
+
export type {
|
|
17
|
+
AskInvalidOutputOutcome,
|
|
18
|
+
AskLimitKind,
|
|
19
|
+
AskLimitOutcome,
|
|
20
|
+
AskStalledOutcome,
|
|
21
|
+
ModelResolutionOutcome,
|
|
22
|
+
YaagErrorCode,
|
|
23
|
+
} from "./contract/index.ts";
|
|
63
24
|
|
|
64
25
|
/** The single error class of the runtime (ADR-0003). */
|
|
65
26
|
export class YaagError extends Error {
|
|
@@ -120,63 +81,6 @@ export class YaagError extends Error {
|
|
|
120
81
|
}
|
|
121
82
|
}
|
|
122
83
|
|
|
123
|
-
/** Builds the runtime's uniform agent-scoped error message. */
|
|
124
|
-
export function agentError(agent: string, code: YaagErrorCode, message: string): YaagError {
|
|
125
|
-
return new YaagError(code, `agent "${agent}": ${message}`, agent);
|
|
126
|
-
}
|
|
127
|
-
|
|
128
|
-
/** The ASK_LIMIT rejection for one exhausted soft budget. */
|
|
129
|
-
export function askLimitError(agent: string, outcome: AskLimitOutcome): YaagError {
|
|
130
|
-
return new YaagError(
|
|
131
|
-
"ASK_LIMIT",
|
|
132
|
-
`agent "${agent}": ${outcome.kind} limit reached at ${outcome.count}`,
|
|
133
|
-
agent,
|
|
134
|
-
outcome,
|
|
135
|
-
);
|
|
136
|
-
}
|
|
137
|
-
|
|
138
|
-
/** The ASK_STALLED rejection for one tripped idle watch. */
|
|
139
|
-
export function askStalledError(agent: string, outcome: AskStalledOutcome): YaagError {
|
|
140
|
-
return new YaagError(
|
|
141
|
-
"ASK_STALLED",
|
|
142
|
-
`agent "${agent}": no frame for ${outcome.idleMs}ms${outcome.destructive ? " (killed)" : ""}`,
|
|
143
|
-
agent,
|
|
144
|
-
outcome,
|
|
145
|
-
);
|
|
146
|
-
}
|
|
147
|
-
|
|
148
|
-
/** The MODEL_RESOLUTION_FAILED rejection for an exhausted or self-repeating resolver. */
|
|
149
|
-
export function modelResolutionError(
|
|
150
|
-
agent: string,
|
|
151
|
-
errors: readonly ModelError[],
|
|
152
|
-
refusedCandidate?: string,
|
|
153
|
-
): YaagError {
|
|
154
|
-
if (errors.length === 0) {
|
|
155
|
-
return new YaagError(
|
|
156
|
-
"MODEL_RESOLUTION_FAILED",
|
|
157
|
-
`agent "${agent}": no model candidate to try`,
|
|
158
|
-
agent,
|
|
159
|
-
{ modelErrors: errors },
|
|
160
|
-
);
|
|
161
|
-
}
|
|
162
|
-
const history = errors.map((error) => `${error.failedModel} (${error.reason})`).join(", ");
|
|
163
|
-
// The guard only refuses a candidate that has a matching permanent entry.
|
|
164
|
-
const refusal =
|
|
165
|
-
refusedCandidate === undefined
|
|
166
|
-
? ""
|
|
167
|
-
: `; refused to retry "${refusedCandidate}", which already failed with ${
|
|
168
|
-
errors.find((error) => error.failedModel === refusedCandidate)?.reason
|
|
169
|
-
}`;
|
|
170
|
-
return new YaagError(
|
|
171
|
-
"MODEL_RESOLUTION_FAILED",
|
|
172
|
-
`agent "${agent}": model resolution gave up after ${errors.length} attempt${
|
|
173
|
-
errors.length === 1 ? "" : "s"
|
|
174
|
-
}: ${history}${refusal}`,
|
|
175
|
-
agent,
|
|
176
|
-
{ modelErrors: errors },
|
|
177
|
-
);
|
|
178
|
-
}
|
|
179
|
-
|
|
180
84
|
/** Narrows an unknown rejection reason to a YaagError. */
|
|
181
85
|
export function isYaagError(value: unknown): value is YaagError {
|
|
182
86
|
return value instanceof YaagError;
|
package/src/events.ts
CHANGED
|
@@ -7,11 +7,11 @@
|
|
|
7
7
|
* dedicated fd arrives with the extension.
|
|
8
8
|
*/
|
|
9
9
|
import type { SettlementCause } from "./ask/index.ts";
|
|
10
|
-
import type { ModelErrorReason } from "./model/index.ts";
|
|
10
|
+
import type { ModelErrorReason, ThinkingLevel } from "./model/index.ts";
|
|
11
11
|
import type { TokenBreakdown, WorktreeResolution } from "./transport/index.ts";
|
|
12
12
|
|
|
13
13
|
export type { SettlementCause } from "./ask/index.ts";
|
|
14
|
-
export type { ModelErrorReason } from "./model/index.ts";
|
|
14
|
+
export type { ModelErrorReason, ThinkingLevel } from "./model/index.ts";
|
|
15
15
|
|
|
16
16
|
/**
|
|
17
17
|
* A Run's outcome (ADR-0022). `paused` arrives with the pause slice.
|
|
@@ -75,6 +75,12 @@ export type LifecycleEventBody =
|
|
|
75
75
|
readonly parent?: string;
|
|
76
76
|
/** How the Agent came to be; absent means "spawn". */
|
|
77
77
|
readonly origin?: SpawnOrigin;
|
|
78
|
+
/**
|
|
79
|
+
* The thinking level the Agent runs at, as pi reported it in the startup
|
|
80
|
+
* `get_state`. Absent on events from an older CLI and on
|
|
81
|
+
* Cassette-playback Agents; a renderer then shows the model alone.
|
|
82
|
+
*/
|
|
83
|
+
readonly thinking?: ThinkingLevel;
|
|
78
84
|
}
|
|
79
85
|
| {
|
|
80
86
|
readonly type: "ask_start";
|
|
@@ -160,6 +166,11 @@ export type LifecycleEventBody =
|
|
|
160
166
|
readonly agent: string;
|
|
161
167
|
/** pi's concrete `provider/id` for the model the Agent runs now. */
|
|
162
168
|
readonly model: string;
|
|
169
|
+
/**
|
|
170
|
+
* Present only when the swap set a level with `set_thinking_level`. Its
|
|
171
|
+
* absence means the level is unchanged as far as yaag observed.
|
|
172
|
+
*/
|
|
173
|
+
readonly thinking?: ThinkingLevel;
|
|
163
174
|
}
|
|
164
175
|
| {
|
|
165
176
|
readonly type: "agent_usage";
|