@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.
Files changed (44) hide show
  1. package/package.json +1 -1
  2. package/src/agent/agent-compaction.ts +1 -1
  3. package/src/agent/agent.ts +1 -1
  4. package/src/agent/define-agent.ts +7 -5
  5. package/src/agent/spawn-open.ts +2 -0
  6. package/src/ask/ask-exchange-events.ts +8 -3
  7. package/src/ask/ask-exchange.ts +6 -9
  8. package/src/catalog/agent-describe-fixture.ts +121 -0
  9. package/src/catalog/agent-describe.ts +210 -0
  10. package/src/catalog/catalog-entry.ts +39 -0
  11. package/src/catalog/catalog-fixture.ts +87 -0
  12. package/src/catalog/catalog-match.ts +77 -0
  13. package/src/catalog/catalog-result.ts +69 -0
  14. package/src/catalog/index.ts +57 -0
  15. package/src/catalog/load-catalog.ts +74 -0
  16. package/src/catalog/program-scan.ts +64 -0
  17. package/src/catalog/registry-paths.ts +26 -0
  18. package/src/catalog/registry-reader.ts +115 -0
  19. package/src/catalog/registry-schema.ts +119 -0
  20. package/src/config/config-paths.ts +14 -7
  21. package/src/config/index.ts +1 -0
  22. package/src/contract/agent-report.ts +42 -0
  23. package/src/contract/error-codes.ts +65 -0
  24. package/src/contract/handle.ts +132 -0
  25. package/src/contract/index.ts +34 -0
  26. package/src/contract/model-spec.ts +81 -0
  27. package/src/contract/spawn-options.ts +127 -0
  28. package/src/error-factories.ts +70 -0
  29. package/src/errors.ts +22 -118
  30. package/src/events.ts +13 -2
  31. package/src/index.ts +45 -0
  32. package/src/model/index.ts +1 -1
  33. package/src/model/model-resolution.ts +19 -71
  34. package/src/model/model-swap.ts +11 -2
  35. package/src/model/resolution-loop.ts +1 -1
  36. package/src/model/thinking-level.ts +5 -5
  37. package/src/public-api.ts +28 -0
  38. package/src/run/run-context.ts +4 -2
  39. package/src/summary/summary-agent.ts +8 -2
  40. package/src/summary/summary-model.ts +5 -1
  41. package/src/transport/live-transport.ts +2 -3
  42. package/src/transport/pi-state.ts +29 -9
  43. package/src/transport/transport.ts +10 -26
  44. package/src/types.ts +16 -243
package/src/index.ts CHANGED
@@ -19,6 +19,49 @@ export {
19
19
  replayTransport,
20
20
  resumeTransport,
21
21
  } from "./cassette/index.ts";
22
+ export type {
23
+ AgentDeclaredMetadata,
24
+ AgentDefinitionEntry,
25
+ AgentDescribeFinding,
26
+ AgentDescribeFindingCode,
27
+ AgentDescribeFindingResult,
28
+ AgentDescribeRequest,
29
+ AgentDescribeResult,
30
+ AgentDescribeTranscriptEntry,
31
+ CatalogDiagnostic,
32
+ CatalogKind,
33
+ CatalogLayer,
34
+ CatalogQuery,
35
+ CatalogRequest,
36
+ CatalogResult,
37
+ CatalogRow,
38
+ CatalogSource,
39
+ DescribedAgent,
40
+ NameDeviation,
41
+ ParsedRegistryFile,
42
+ RegistryDocument,
43
+ RegistryLayerRequest,
44
+ } from "./catalog/index.ts";
45
+ export {
46
+ AGENT_DESCRIBE_FINDING_CODES,
47
+ AGENT_DESCRIBE_TRANSCRIPT,
48
+ agentDescribeArgv,
49
+ CATALOG_FIXTURE,
50
+ describedAgent,
51
+ encodeAgentDescribe,
52
+ filterCatalog,
53
+ globalRegistryPath,
54
+ loadCatalog,
55
+ matchesPattern,
56
+ parseAgentDescribe,
57
+ parseRegistryFile,
58
+ projectRegistryPath,
59
+ REGISTRY_FILE_NAME,
60
+ readRegistryDocument,
61
+ readRegistryLayer,
62
+ scanPrograms,
63
+ transcriptFor,
64
+ } from "./catalog/index.ts";
22
65
  export type {
23
66
  ConfigEnvironment,
24
67
  ConfigExtension,
@@ -60,6 +103,8 @@ export type {
60
103
  ThinkingResolver,
61
104
  ThinkingSpec,
62
105
  } from "./model/index.ts";
106
+ // The closed thinking-level list, so a parser outside the runtime has one authority.
107
+ export { isThinkingLevel } from "./model/index.ts";
63
108
  export type { DecodedNode, NodeDecoder, NodePath, NodeSnapshot } from "./node/index.ts";
64
109
  export {
65
110
  agentAskPath,
@@ -30,4 +30,4 @@ export {
30
30
  resolveModel,
31
31
  retryOnModelFailure,
32
32
  } from "./resolution-loop.ts";
33
- export type { ThinkingLevel } from "./thinking-level.ts";
33
+ export { isThinkingLevel, type ThinkingLevel } from "./thinking-level.ts";
@@ -1,76 +1,24 @@
1
+ import type {
2
+ ModelError,
3
+ ModelResolver,
4
+ ModelSelection,
5
+ ModelSpec,
6
+ ThinkingLevel,
7
+ ThinkingResolver,
8
+ ThinkingSpec,
9
+ } from "../contract/index.ts";
1
10
  import { parseModelSuffix } from "./model-suffix.ts";
2
- import { isThinkingLevel, type ThinkingLevel } from "./thinking-level.ts";
11
+ import { isThinkingLevel } from "./thinking-level.ts";
3
12
 
4
- /**
5
- * Why one model candidate was rejected by pi (ADR-0037).
6
- *
7
- * `not_found`: the pattern matched no model, or pi refused the live swap.
8
- * `auth`: the provider refused the credentials.
9
- * `rate_limited`: the provider stayed rate-limited after pi's own retries.
10
- *
11
- * These three classes are the only triggers of Model Resolution. A different
12
- * transport or turn failure stays an ordinary failure and starts no new attempt.
13
- */
14
- export type ModelErrorReason = "not_found" | "auth" | "rate_limited";
15
-
16
- /**
17
- * One failed Model Resolution attempt, handed back to the caller's resolver.
18
- *
19
- * yaag gives the full history to each resolver call, oldest attempt first. The
20
- * first call gets an empty list (ADR-0037).
21
- */
22
- export interface ModelError {
23
- readonly reason: ModelErrorReason;
24
- /** The model pattern that failed, after inline-suffix stripping. */
25
- readonly failedModel: string;
26
- /** 0-based index of the attempt that produced this error. */
27
- readonly attempt: number;
28
- }
29
-
30
- /**
31
- * Picks the next model candidate, or `undefined` to give up (ADR-0037).
32
- *
33
- * When the resolver gives up, the spawn or the Ask fails with
34
- * `MODEL_RESOLUTION_FAILED`, which carries the full error history. yaag also
35
- * refuses a candidate that already failed with `not_found` or `auth` in the
36
- * same loop, so a resolver cannot loop forever. The resolver must be pure and
37
- * synchronous.
38
- */
39
- export type ModelResolver = (errors: readonly ModelError[]) => string | undefined;
40
-
41
- /**
42
- * Every accepted `model` form: one pattern, an ordered list, or a resolver.
43
- *
44
- * An array is the resolver that reads the candidate at the attempt index, and
45
- * gives `undefined` past the end. One pattern is the one-element list. So the
46
- * termination rule of `ModelResolver` covers every form (ADR-0037).
47
- */
48
- export type ModelSpec = string | readonly string[] | ModelResolver;
49
-
50
- /**
51
- * Picks the thinking level for a settled model, or `undefined` for pi's default.
52
- *
53
- * `undefined` means "no thinking preference". It is not a failure, and it does
54
- * not stop the attempt (ADR-0037).
55
- */
56
- export type ThinkingResolver = (
57
- selectedModel: string,
58
- errors: readonly ModelError[],
59
- ) => ThinkingLevel | undefined;
60
-
61
- /**
62
- * Every accepted `thinking` form: one level or a resolver.
63
- *
64
- * An inline suffix on the resolved model pattern wins over this property
65
- * (ADR-0037).
66
- */
67
- export type ThinkingSpec = ThinkingLevel | ThinkingResolver;
68
-
69
- /** One attempt's settled selection; `model: undefined` inherits pi's default model. */
70
- export interface ModelSelection {
71
- readonly model: string | undefined;
72
- readonly thinking: ThinkingLevel | undefined;
73
- }
13
+ export type {
14
+ ModelError,
15
+ ModelErrorReason,
16
+ ModelResolver,
17
+ ModelSelection,
18
+ ModelSpec,
19
+ ThinkingResolver,
20
+ ThinkingSpec,
21
+ } from "../contract/index.ts";
74
22
 
75
23
  /** The canonical shape the spawn loop consumes, whatever form the caller wrote. */
76
24
  export interface ModelResolution {
@@ -1,7 +1,8 @@
1
- import { agentError } from "../errors.ts";
1
+ import { agentError } from "../error-factories.ts";
2
2
  import type { CommandResponse, Frame } from "../transport/index.ts";
3
3
  import { matchAvailableModel, readAvailableModel, readAvailableModels } from "./model-match.ts";
4
4
  import type { ModelSelection } from "./model-resolution.ts";
5
+ import type { ThinkingLevel } from "./thinking-level.ts";
5
6
 
6
7
  /** Sends one command frame to the live Agent. The Connection satisfies it. */
7
8
  export type ModelSwapCommand = (frame: Frame) => Promise<CommandResponse>;
@@ -10,6 +11,11 @@ export type ModelSwapCommand = (frame: Frame) => Promise<CommandResponse>;
10
11
  export interface ModelSwapResult {
11
12
  /** `provider/id` pi reports for the new model. */
12
13
  readonly model: string;
14
+ /**
15
+ * The level `set_thinking_level` landed; absent when the selection named
16
+ * none, in which case yaag never observed a level change.
17
+ */
18
+ readonly thinking?: ThinkingLevel;
13
19
  }
14
20
 
15
21
  /**
@@ -67,7 +73,10 @@ export async function swapModel(options: {
67
73
  throw failed(options.agent, thinking.error ?? "set_thinking_level was rejected");
68
74
  }
69
75
  }
70
- return { model: reportedModel(response.data) ?? `${match.model.provider}/${match.model.id}` };
76
+ return {
77
+ model: reportedModel(response.data) ?? `${match.model.provider}/${match.model.id}`,
78
+ ...(options.selection.thinking === undefined ? {} : { thinking: options.selection.thinking }),
79
+ };
71
80
  }
72
81
 
73
82
  /** pi answers `set_model` with the full Model object it switched to. */
@@ -1,4 +1,4 @@
1
- import { modelResolutionError } from "../errors.ts";
1
+ import { modelResolutionError } from "../error-factories.ts";
2
2
  import { ModelErrorHistory } from "./model-error-history.ts";
3
3
  import { classifyAskFailure, classifyModelFailure } from "./model-failure.ts";
4
4
  import type { ModelFallbackSink } from "./model-fallback.ts";
@@ -1,10 +1,10 @@
1
1
  /**
2
- * pi's supported thinking levels.
3
- *
4
- * Lives in its own leaf module so both `types.ts` and the Model Resolution
5
- * modules can depend on it without forming an import cycle.
2
+ * The value side of pi's thinking levels. The type itself lives in
3
+ * `contract/model-spec.ts` (ADR-0045) and is re-exported here.
6
4
  */
7
- export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
5
+ import type { ThinkingLevel } from "../contract/index.ts";
6
+
7
+ export type { ThinkingLevel } from "../contract/index.ts";
8
8
 
9
9
  /**
10
10
  * The closed level list, authored as a total record so that adding a level to
@@ -0,0 +1,28 @@
1
+ /**
2
+ * The author surface of `@yaag/runtime` (ADR-0045).
3
+ *
4
+ * An Orchestration Program imports exactly `@yaag/runtime` and `typebox`
5
+ * (ADR-0033). This file states the subset a program author may use, and the
6
+ * declaration tree a workspace gets is emitted from it alone.
7
+ *
8
+ * The imports go past the directory indexes on purpose: a directory index
9
+ * states the runtime API, which holds `executeRun`, `Agent`, or `promptGist`
10
+ * as well. This file must not pull those into the emitted tree.
11
+ */
12
+
13
+ export type { AgentConfig, AgentDefinition } from "./agent/define-agent.ts";
14
+ export { defineAgent } from "./agent/define-agent.ts";
15
+ export type {
16
+ AskOptions,
17
+ Handle,
18
+ SpawnOptions,
19
+ SpawnOverrides,
20
+ StructuredAskOptions,
21
+ ThinkingLevel,
22
+ } from "./contract/index.ts";
23
+ export type { YaagErrorCode } from "./errors.ts";
24
+ export { isYaagError, YaagError } from "./errors.ts";
25
+ export { prompt } from "./prompt/prompt.ts";
26
+ export type { OrchestrationProgram, ProgramDefinition } from "./run/define-run.ts";
27
+ export { defineRun } from "./run/define-run.ts";
28
+ export type { RunContext } from "./run/run-context.ts";
@@ -1,5 +1,7 @@
1
- import type { AgentDefinition } from "../agent/index.ts";
2
- import type { Handle, SpawnOptions, SpawnOverrides } from "../types.ts";
1
+ // `../agent/define-agent.ts` is a deep import on purpose: the author
2
+ // declaration tree must not pull the `agent/` barrel (ADR-0045).
3
+ import type { AgentDefinition } from "../agent/define-agent.ts";
4
+ import type { Handle, SpawnOptions, SpawnOverrides } from "../contract/index.ts";
3
5
 
4
6
  /** What an Orchestration Program is handed. */
5
7
  export interface RunContext<Args = unknown> {
@@ -1,9 +1,9 @@
1
- import type { AgentActivity, SpawnOrigin } from "../events.ts";
1
+ import type { AgentActivity, SpawnOrigin, ThinkingLevel } from "../events.ts";
2
2
  import type { TokenBreakdown, WorktreeResolution } from "../transport/index.ts";
3
3
  import type { ModelFallbackInfo } from "./summary-fallbacks.ts";
4
4
  import type { NodeInfo } from "./summary-nodes.ts";
5
5
 
6
- export type { AgentActivity, SpawnOrigin } from "../events.ts";
6
+ export type { AgentActivity, SpawnOrigin, ThinkingLevel } from "../events.ts";
7
7
  export type { ModelFallbackInfo } from "./summary-fallbacks.ts";
8
8
  export type { NodeInfo } from "./summary-nodes.ts";
9
9
 
@@ -27,6 +27,8 @@ interface AgentInfoBase {
27
27
  * A `resolvedModel` pattern never lands here.
28
28
  */
29
29
  readonly model: string | null;
30
+ /** The thinking level the Agent runs at; null when no event ever reported one. */
31
+ readonly thinking: ThinkingLevel | null;
30
32
  readonly cwd: string | null;
31
33
  readonly branch: string | null;
32
34
  /** pi's session file for this Agent, when the spawn reported one; a Peek reads it. */
@@ -111,6 +113,7 @@ export interface AgentExitObservation {
111
113
  export function placeholderAgent(): IdleAgentInfo {
112
114
  return {
113
115
  model: null,
116
+ thinking: null,
114
117
  cwd: null,
115
118
  branch: null,
116
119
  sessionFile: null,
@@ -143,6 +146,7 @@ export function spawnAgent(
143
146
  current: AgentRecord | undefined,
144
147
  identity: {
145
148
  readonly model: string;
149
+ readonly thinking?: ThinkingLevel;
146
150
  readonly cwd: string;
147
151
  readonly branch?: string;
148
152
  readonly sessionFile?: string;
@@ -155,6 +159,7 @@ export function spawnAgent(
155
159
  return {
156
160
  ...placeholderAgent(),
157
161
  model: identity.model,
162
+ thinking: identity.thinking ?? null,
158
163
  cwd: identity.cwd,
159
164
  branch: identity.branch ?? null,
160
165
  sessionFile: identity.sessionFile ?? null,
@@ -166,6 +171,7 @@ export function spawnAgent(
166
171
  return {
167
172
  ...current,
168
173
  model: current.model ?? identity.model,
174
+ thinking: current.thinking ?? identity.thinking ?? null,
169
175
  cwd: current.cwd ?? identity.cwd,
170
176
  branch: current.branch ?? identity.branch ?? null,
171
177
  sessionFile: current.sessionFile ?? identity.sessionFile ?? null,
@@ -11,8 +11,12 @@ type AgentModelEvent = Extract<LifecycleEventBody, { readonly type: "agent_model
11
11
  * `state`, `askIndex`, `activity`, `stateChangedAt` and the bounded fallback
12
12
  * table stay as they are. An exited Agent is skipped, because its model is
13
13
  * frozen together with its final accounting.
14
+ *
15
+ * An event that names no level leaves the last known level standing: yaag only
16
+ * observes a level it set itself (ADR-0038/0041), so a swap without a level
17
+ * reports none rather than an unknown one.
14
18
  */
15
19
  export function applyAgentModel(agent: AgentRecord, event: AgentModelEvent): AgentRecord {
16
20
  if (agent.state === "exited") return agent;
17
- return { ...agent, model: event.model };
21
+ return { ...agent, model: event.model, thinking: event.thinking ?? agent.thinking };
18
22
  }
@@ -1,7 +1,7 @@
1
1
  import { YaagError } from "../errors.ts";
2
2
  import { FrameQueue } from "./frame-queue.ts";
3
3
  import { decodeFrames } from "./jsonl.ts";
4
- import { piCommand, readModel, readSessionFile, readStats } from "./pi-state.ts";
4
+ import { piCommand, readModel, readStartup, readStats } from "./pi-state.ts";
5
5
  import { reap } from "./reap.ts";
6
6
  import { appendStderrTail, stderrDiagnostic } from "./stderr-tail.ts";
7
7
  import {
@@ -103,8 +103,7 @@ class LiveTransport implements AgentTransport {
103
103
  verifyEffectiveTools(contract, await probe.wait());
104
104
  }
105
105
  this.model = model;
106
- const sessionFile = readSessionFile(state);
107
- observeStartup?.(sessionFile === null ? {} : { sessionFile });
106
+ observeStartup?.(readStartup(state));
108
107
  } catch (error) {
109
108
  // Startup has not returned this transport to spawn.ts, so cleanup belongs here.
110
109
  // A secondary stats or reap failure must not hide the startup diagnostic.
@@ -1,4 +1,6 @@
1
1
  import { REPORT_RESULT_EXTENSION_PATH, REPORT_RESULT_TOOL_NAME } from "../ask-contract/index.ts";
2
+ import type { AgentProgress } from "../contract/index.ts";
3
+ import { isThinkingLevel, type ThinkingLevel } from "../model/index.ts";
2
4
  import { SYSTEM_PROMPT_RECORDER_EXTENSION_PATH } from "./system-prompt-recorder.ts";
3
5
  import type {
4
6
  AgentStats,
@@ -6,17 +8,10 @@ import type {
6
8
  Frame,
7
9
  OpenOptions,
8
10
  TokenBreakdown,
11
+ TransportStartup,
9
12
  } from "./transport.ts";
10
13
 
11
- /** What the Agent reported about its own work, read from a `get_state` probe. */
12
- export interface AgentProgress {
13
- /** True while pi streams a completion, compacts its context, or holds a queued prompt. */
14
- readonly working: boolean;
15
- readonly streaming: boolean;
16
- readonly compacting: boolean;
17
- /** Prompts pi has queued but not started. */
18
- readonly pendingMessages: number;
19
- }
14
+ export type { AgentProgress } from "../contract/index.ts";
20
15
 
21
16
  /** The command line for one Agent. */
22
17
  export function piCommand(options: OpenOptions, toolProbeExtensionPath?: string): string[] {
@@ -144,6 +139,31 @@ export function readAgentProgress(data: unknown): AgentProgress | null {
144
139
  };
145
140
  }
146
141
 
142
+ /**
143
+ * The startup facts one `get_state` response reports, as the live transport
144
+ * hands them to its startup observer. A fact pi did not report is left out
145
+ * rather than set to a null, so an observer sees only what pi actually said.
146
+ */
147
+ export function readStartup(response: Frame): TransportStartup {
148
+ const sessionFile = readSessionFile(response);
149
+ const thinking = readThinkingLevel(response);
150
+ return {
151
+ ...(sessionFile === null ? {} : { sessionFile }),
152
+ ...(thinking === null ? {} : { thinking }),
153
+ };
154
+ }
155
+
156
+ /**
157
+ * The Agent's effective thinking level from a startup `get_state` response (pi
158
+ * `docs/rpc.md`, `data.thinkingLevel`). Null when pi reported none or reported
159
+ * an unknown level, so an unrecognized value never reaches a renderer.
160
+ */
161
+ export function readThinkingLevel(response: Frame): ThinkingLevel | null {
162
+ const data: unknown = response.data;
163
+ if (typeof data !== "object" || data === null || !("thinkingLevel" in data)) return null;
164
+ return isThinkingLevel(data.thinkingLevel) ? data.thinkingLevel : null;
165
+ }
166
+
147
167
  /** Returns pi's persisted session path from a startup `get_state` response, when valid. */
148
168
  export function readSessionFile(response: Frame): string | null {
149
169
  const data: unknown = response.data;
@@ -1,7 +1,13 @@
1
1
  import type { CanonicalJsonObject, ReportedResult } from "../ask-contract/index.ts";
2
+ import type {
3
+ AskOptions,
4
+ CompactionResult,
5
+ ResolvedSpawnOptions,
6
+ ThinkingLevel,
7
+ TokenBreakdown,
8
+ } from "../contract/index.ts";
2
9
  import type { AskLimitOutcome, AskStalledOutcome } from "../errors.ts";
3
10
  import type { RecordedSpawnSelection } from "../model/index.ts";
4
- import type { AskOptions, ResolvedSpawnOptions, ThinkingLevel } from "../types.ts";
5
11
 
6
12
  /**
7
13
  * The one seam of the runtime (ticket 04). An AgentTransport represents a whole
@@ -15,14 +21,7 @@ import type { AskOptions, ResolvedSpawnOptions, ThinkingLevel } from "../types.t
15
21
  /** One JSONL frame in either direction. Unknown `type`s must survive (ticket 01). */
16
22
  export type Frame = { readonly type: string; readonly [k: string]: unknown };
17
23
 
18
- /** pi's full token usage for one Agent, as reported by `get_session_stats`. */
19
- export interface TokenBreakdown {
20
- readonly input: number;
21
- readonly output: number;
22
- readonly cacheRead: number;
23
- readonly cacheWrite: number;
24
- readonly total: number;
25
- }
24
+ export type { CompactionResult, TokenBreakdown } from "../contract/index.ts";
26
25
 
27
26
  /** Cost and usage read at Agent shutdown (ADR-0012). */
28
27
  export interface AgentStats {
@@ -31,23 +30,6 @@ export interface AgentStats {
31
30
  readonly cost: number | null;
32
31
  }
33
32
 
34
- /**
35
- * What one compaction of an Agent's context reported (ADR-0043).
36
- *
37
- * Every field is null when pi reported nothing for it: a custom compaction
38
- * handler may answer without usage, and "unknown" must stay distinct from 0.
39
- */
40
- export interface CompactionResult {
41
- /** Context tokens before the summary replaced the transcript. */
42
- readonly tokensBefore: number | null;
43
- /** Estimated context tokens after the summary replaced the transcript. */
44
- readonly tokensAfter: number | null;
45
- /** Token breakdown of the summary call itself. */
46
- readonly tokens: TokenBreakdown | null;
47
- /** Cost of the summary call itself. */
48
- readonly cost: number | null;
49
- }
50
-
51
33
  /** Recorded inputs used to explain an Ask-hash mismatch without changing identity. */
52
34
  export interface AskMarkerContext {
53
35
  readonly prompt: string;
@@ -274,6 +256,8 @@ export interface WorktreeResolution {
274
256
  /** Startup facts a factory may report without widening AgentTransport. */
275
257
  export interface TransportStartup {
276
258
  readonly sessionFile?: string;
259
+ /** The thinking level pi reported at startup; absent when it reported none. */
260
+ readonly thinking?: ThinkingLevel;
277
261
  readonly worktree?: WorktreeResolution;
278
262
  }
279
263