@yaag/runtime 0.20.0 → 0.21.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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@yaag/runtime",
3
- "version": "0.20.0",
3
+ "version": "0.21.0",
4
4
  "publishConfig": {
5
5
  "access": "public"
6
6
  },
@@ -226,6 +226,7 @@ export class Agent implements Handle {
226
226
  {
227
227
  name: this.name,
228
228
  spawnOptions: this.#spawnOptions,
229
+ askDefaults: Object.keys(this.#askDefaults).length === 0 ? undefined : this.#askDefaults,
229
230
  sessionFile,
230
231
  worktree: this.#worktree(),
231
232
  settledAsks: this.#settledAsks,
@@ -1,51 +1,15 @@
1
- import type { AskOptions, ModelSpec, ThinkingSpec } from "../contract/index.ts";
1
+ import type { AgentPolicy } from "../contract/index.ts";
2
2
 
3
3
  export type { ThinkingLevel } from "../contract/index.ts";
4
4
 
5
- /** What `defineAgent` is given: the policy of one Agent, never its topology. */
6
- export interface AgentConfig {
5
+ /**
6
+ * What `defineAgent` is given: the Agent Policy of one Agent, never its
7
+ * topology. Every field is the one `SpawnOptions` carries under the same name;
8
+ * only `name` is required here (ADR-0019 amendment).
9
+ */
10
+ export interface AgentConfig extends AgentPolicy {
7
11
  /** Stable identity, used in every Lifecycle Event and log line. */
8
12
  readonly name: string;
9
- /** Text added after pi's own system prompt, which stays, unless `overrideSystemPrompt`. */
10
- readonly prompt?: string;
11
- /**
12
- * Replace pi's system prompt with `prompt` instead of appending to it, which
13
- * removes pi's own documentation and tool guidance from the Agent.
14
- */
15
- readonly overrideSystemPrompt?: boolean;
16
- /**
17
- * Model id handed to `pi --model`. Unset = pi's default. An array is an ordered
18
- * fallback list, a function picks the next candidate from the failures so far,
19
- * and any pattern may carry an inline thinking suffix (`"opus-5:medium"`),
20
- * which wins over `thinking`. Each attempt settles the model first, then the
21
- * thinking level for that model. yaag starts a new attempt only when pi
22
- * reports `not_found`, `auth`, or `rate_limited` (ADR-0037).
23
- */
24
- readonly model?: ModelSpec;
25
- /**
26
- * Thinking budget for the Agent's turns, as a level or a resolver. The
27
- * resolver runs again for each attempt, with the model that settled for that
28
- * attempt. A resolver kept in a definition is frozen policy, so it must stay
29
- * pure and synchronous (ADR-0037).
30
- */
31
- readonly thinking?: ThinkingSpec;
32
- /** Allow-list of tool names. Unset = pi's default tool set. */
33
- readonly tools?: readonly string[];
34
- /** Deny-list of tool names, applied after `tools`. */
35
- readonly disallowedTools?: readonly string[];
36
- /** Allow-list of skill names. Unset = pi's default skill set. */
37
- readonly skills?: readonly string[];
38
- /** Deny-list of skill names, applied after `skills`. */
39
- readonly disallowedSkills?: readonly string[];
40
- /**
41
- * Load the Effective Config's `agents.extensions` for Agents of this
42
- * definition. Default true. A spawn's own `SpawnOptions.configExtensions`
43
- * wins over this value; spawn *overrides* stay topology-only, so the opt-out
44
- * is not one of them (ADR-0019, ADR-0040).
45
- */
46
- readonly configExtensions?: boolean;
47
- /** Ask options applied to every Ask on this Agent unless overridden per call. */
48
- readonly askDefaults?: AskOptions;
49
13
  }
50
14
 
51
15
  /** Not exported, so the config is unreachable outside this module. */
@@ -56,7 +20,13 @@ export interface AgentDefinition {
56
20
  readonly [definition]: AgentConfig;
57
21
  }
58
22
 
59
- const arrayFields = ["tools", "disallowedTools", "skills", "disallowedSkills"] as const;
23
+ const arrayFields = [
24
+ "tools",
25
+ "disallowedTools",
26
+ "skills",
27
+ "disallowedSkills",
28
+ "extensions",
29
+ ] as const;
60
30
 
61
31
  /**
62
32
  * Declares an Agent Definition: reusable policy, independent of where it runs.
package/src/agent/fork.ts CHANGED
@@ -1,11 +1,19 @@
1
1
  import type { WorktreeResolution } from "../transport/index.ts";
2
- import type { ForkOptions, Handle, ResolvedSpawnOptions, SpawnOptions } from "../types.ts";
2
+ import type {
3
+ AskOptions,
4
+ ForkOptions,
5
+ Handle,
6
+ ResolvedSpawnOptions,
7
+ SpawnOptions,
8
+ } from "../types.ts";
3
9
 
4
10
  /** What one Agent hands the spawn gate when it is forked (ADR-0044). */
5
11
  export interface ForkSource {
6
12
  readonly name: string;
7
13
  /** The options the source settled on; the verbatim inheritance base. */
8
14
  readonly spawnOptions: ResolvedSpawnOptions;
15
+ /** The source's Ask defaults; inherited verbatim unless the fork gives its own. */
16
+ readonly askDefaults: AskOptions | undefined;
9
17
  /** pi's session file for the source; a fork without one is refused. */
10
18
  readonly sessionFile: string | undefined;
11
19
  readonly worktree: WorktreeResolution | undefined;
@@ -33,6 +41,8 @@ export interface ForkRequest {
33
41
  readonly spawnOptions: SpawnOptions;
34
42
  /** The raw Parent Link, defaulting to the fork source. */
35
43
  readonly parent: unknown;
44
+ /** The fork's own `askDefaults` when given, else the source's; never merged. */
45
+ readonly askDefaults: AskOptions | undefined;
36
46
  readonly fork: ForkIdentity;
37
47
  readonly compact: boolean | string | undefined;
38
48
  }
@@ -43,17 +53,19 @@ export interface ForkRequest {
43
53
  * Inheritance is verbatim, with two deliberate exceptions: `name` is dropped,
44
54
  * so the child gets a fresh auto-name unless the overrides give it one, and
45
55
  * `compact` never reaches the spawn options, because it is a fork verb rather
46
- * than a property of the Agent.
56
+ * than a property of the Agent. `askDefaults` travels beside the spawn
57
+ * options, as on every spawn path, and an explicit one replaces the source's.
47
58
  */
48
59
  export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRequest {
49
60
  if (source.sessionFile === undefined) {
50
61
  throw new Error("a fork source must hold a session file");
51
62
  }
52
63
  const { name: _name, ...inherited } = source.spawnOptions;
53
- const { compact, parent, ...explicit } = overrides ?? {};
64
+ const { compact, parent, askDefaults, ...explicit } = overrides ?? {};
54
65
  return {
55
66
  spawnOptions: { ...inherited, ...stripUndefined(explicit) },
56
67
  parent: parent ?? source.handle,
68
+ askDefaults: askDefaults ?? source.askDefaults,
57
69
  fork: {
58
70
  forkOf: source.name,
59
71
  forkAsks: source.settledAsks,
@@ -68,7 +80,9 @@ export function forkRequest(source: ForkSource, overrides?: ForkOptions): ForkRe
68
80
  * Drops explicitly undefined overrides, so `fork({ model: undefined })` keeps
69
81
  * the inherited value instead of erasing it.
70
82
  */
71
- function stripUndefined(options: Omit<ForkOptions, "compact" | "parent">): SpawnOptions {
83
+ function stripUndefined(
84
+ options: Omit<ForkOptions, "compact" | "parent" | "askDefaults">,
85
+ ): SpawnOptions {
72
86
  const entries = Object.entries(options).filter(([, value]) => value !== undefined);
73
87
  return Object.fromEntries(entries) as SpawnOptions;
74
88
  }
@@ -21,8 +21,10 @@ interface ValidatedOverrides {
21
21
  /**
22
22
  * Builds the open request of one ordinary spawn.
23
23
  *
24
- * A plain options object passes through as topology. An Agent Definition
25
- * supplies the policy, and the overrides supply the topology (ADR-0019).
24
+ * A plain options object passes through. An Agent Definition supplies the
25
+ * policy, and the overrides supply the topology (ADR-0019). On both paths
26
+ * `askDefaults` leaves the spawn options and travels beside them, so it never
27
+ * enters the recorded spawn options or the Cassette.
26
28
  * Throws a TypeError when the overrides are not an object, when they name a
27
29
  * key that is not `name`, `cwd`, `worktree` or `parent`, or when one of those
28
30
  * carries the wrong type. `parent` stays raw: `resolveParent` checks it.
@@ -32,39 +34,33 @@ export function resolveRequest(
32
34
  overrides: SpawnOverrides | undefined,
33
35
  ): OpenAgentRequest {
34
36
  if (!isAgentDefinition(definitionOrOptions)) {
35
- const { parent, ...spawnOptions } = definitionOrOptions;
36
- return { spawnOptions, parent, askDefaults: undefined, definitionName: undefined };
37
+ const { parent, askDefaults, ...spawnOptions } = definitionOrOptions;
38
+ return { spawnOptions, parent, askDefaults, definitionName: undefined };
37
39
  }
38
40
  const { topology, parent } = validateOverrides(overrides);
39
- const config = agentDefinitionConfig(definitionOrOptions);
41
+ const { name, askDefaults, ...policy } = agentDefinitionConfig(definitionOrOptions);
40
42
  return {
41
43
  spawnOptions: {
42
- name: topology.name ?? config.name,
44
+ ...definedFields(policy),
45
+ name: topology.name ?? name,
43
46
  ...(topology.cwd === undefined ? {} : { cwd: topology.cwd }),
44
47
  ...(topology.worktree === undefined ? {} : { worktree: topology.worktree }),
45
- ...(config.model === undefined ? {} : { model: config.model }),
46
- ...(config.thinking === undefined ? {} : { thinking: config.thinking }),
47
- ...(config.tools === undefined ? {} : { tools: config.tools }),
48
- ...(config.disallowedTools === undefined ? {} : { disallowedTools: config.disallowedTools }),
49
- ...(config.skills === undefined ? {} : { skills: config.skills }),
50
- ...(config.configExtensions === undefined
51
- ? {}
52
- : { configExtensions: config.configExtensions }),
53
- ...(config.disallowedSkills === undefined
54
- ? {}
55
- : { disallowedSkills: config.disallowedSkills }),
56
- ...(config.prompt === undefined
57
- ? {}
58
- : config.overrideSystemPrompt === true
59
- ? { systemPrompt: config.prompt }
60
- : { appendSystemPrompt: config.prompt }),
61
48
  },
62
49
  parent,
63
- askDefaults: config.askDefaults,
64
- definitionName: config.name,
50
+ askDefaults,
51
+ definitionName: name,
65
52
  };
66
53
  }
67
54
 
55
+ /** The policy without its `undefined` fields, so an absent field stays absent. */
56
+ function definedFields<T extends object>(policy: T): Partial<T> {
57
+ const copy: Partial<T> = {};
58
+ for (const key of Object.keys(policy) as (keyof T)[]) {
59
+ if (policy[key] !== undefined) copy[key] = policy[key];
60
+ }
61
+ return copy;
62
+ }
63
+
68
64
  function validateOverrides(overrides: unknown): ValidatedOverrides {
69
65
  if (overrides === undefined) return { topology: {}, parent: undefined };
70
66
  if (typeof overrides !== "object" || overrides === null || Array.isArray(overrides)) {
@@ -49,7 +49,7 @@ export function makeSpawn(deps: SpawnDependencies): SpawnGate {
49
49
  const handle = await openAgent(context, {
50
50
  spawnOptions: request.spawnOptions,
51
51
  parent: request.parent,
52
- askDefaults: undefined,
52
+ askDefaults: request.askDefaults,
53
53
  definitionName: undefined,
54
54
  fork: request.fork,
55
55
  });
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Agent Policy: the per-Agent settings an Agent Definition and a spawn call
3
+ * share (ADR-0019 amendment). `SpawnOptions` adds topology to this shape;
4
+ * `AgentConfig` makes `name` required.
5
+ *
6
+ * Types only, and no import outside this directory (ADR-0045).
7
+ */
8
+
9
+ import type { AskOptions } from "./handle.ts";
10
+ import type { ModelSpec, ThinkingSpec } from "./model-spec.ts";
11
+
12
+ /** What one Agent is, independent of where it runs. */
13
+ export interface AgentPolicy {
14
+ /** Log and event label. Optional at spawn (a1, a2, …), required in a definition. */
15
+ readonly name?: string;
16
+ /**
17
+ * Model pattern, e.g. "anthropic/claude-haiku-4". Unset inherits the user's default.
18
+ *
19
+ * An array is an ordered fallback list and a function picks the next candidate
20
+ * from the failures so far. Any resolved pattern may carry an inline thinking
21
+ * suffix (`"opus-5:medium"`), which wins over `thinking`. Each attempt settles
22
+ * the model first, then the thinking level for that model. yaag starts a new
23
+ * attempt only when pi reports `not_found`, `auth`, or `rate_limited`. See
24
+ * `ModelSpec` and `ModelResolver` for the termination rules (ADR-0037).
25
+ */
26
+ readonly model?: ModelSpec;
27
+ /**
28
+ * Sets pi's thinking level; omission preserves pi's default. A function picks
29
+ * the level from the settled model, and is not consulted for a model pattern
30
+ * that carries an inline thinking suffix. The resolver runs again for each
31
+ * attempt, with the model that settled for that attempt. A resolver kept in
32
+ * a definition is frozen policy, so it must stay pure and synchronous (ADR-0037).
33
+ */
34
+ readonly thinking?: ThinkingSpec;
35
+ /**
36
+ * Replaces pi's default system prompt (`pi --system-prompt`), which removes
37
+ * pi's own documentation and tool guidance from the Agent.
38
+ */
39
+ readonly systemPrompt?: string;
40
+ /** Adds text after pi's default system prompt, which stays (`pi --append-system-prompt`). */
41
+ readonly appendSystemPrompt?: string;
42
+ /**
43
+ * Restores pi discovery. Omission or false selects ADR-0026's hermetic baseline.
44
+ */
45
+ readonly inherit?: boolean;
46
+ /**
47
+ * Explicit pi extensions layer over either ADR-0026 baseline. Relative entries
48
+ * resolve from the Orchestration Program file, also when the policy comes
49
+ * from an Agent Definition in another module; each becomes `pi -e <path>`.
50
+ */
51
+ readonly extensions?: readonly string[];
52
+ /**
53
+ * Load the Effective Config's `agents.extensions` for this Agent. Default
54
+ * true; false spawns with only the extensions this policy declares (ADR-0040).
55
+ */
56
+ readonly configExtensions?: boolean;
57
+ /**
58
+ * Tool allowlist layered over the ADR-0026 baseline; omission is tool-free when hermetic.
59
+ * `disallowedTools` applies last. A non-empty surviving allowlist is verified after startup;
60
+ * a missing promised name rejects spawn.
61
+ */
62
+ readonly tools?: readonly string[];
63
+ /**
64
+ * Tool denylist applied last under ADR-0026; `['yaag_run']` prevents nested yaag Runs.
65
+ * Denying an absent tool is inert and is not presence-validated.
66
+ */
67
+ readonly disallowedTools?: readonly string[];
68
+ /**
69
+ * Skill-name allowlist, not filesystem paths, layered over the ADR-0026 baseline.
70
+ * Omission is skill-free when hermetic; `disallowedSkills` applies last. Unknown requested
71
+ * names reject spawn.
72
+ */
73
+ readonly skills?: readonly string[];
74
+ /** Skill-name denylist discovered from pi and applied last (ADR-0026). */
75
+ readonly disallowedSkills?: readonly string[];
76
+ /**
77
+ * Ask options applied to every Ask on this Agent unless overridden per call.
78
+ * They never enter the recorded spawn options: the Ask hash sees them through
79
+ * the merged Ask options instead.
80
+ */
81
+ readonly askDefaults?: AskOptions;
82
+ }
@@ -6,6 +6,7 @@
6
6
  * except `typebox`. That keeps the declaration tree a workspace gets small.
7
7
  * Files inside this directory import each other directly.
8
8
  */
9
+ export type { AgentPolicy } from "./agent-policy.ts";
9
10
  export type { AgentProgress, CompactionResult, TokenBreakdown } from "./agent-report.ts";
10
11
  export type {
11
12
  AskInvalidOutputOutcome,
@@ -4,73 +4,17 @@
4
4
  * Types only, and no import outside this directory (ADR-0045).
5
5
  */
6
6
 
7
+ import type { AgentPolicy } from "./agent-policy.ts";
7
8
  import type { Handle } from "./handle.ts";
8
- import type { ModelSpec, ThinkingLevel, ThinkingSpec } from "./model-spec.ts";
9
+ import type { ThinkingLevel } from "./model-spec.ts";
9
10
 
10
- /** Options for spawning one Agent (ADR-0001, ADR-0009, ADR-0026). */
11
- export interface SpawnOptions {
11
+ /**
12
+ * Options for spawning one Agent: an Agent Policy plus its topology
13
+ * (ADR-0001, ADR-0009, ADR-0026).
14
+ */
15
+ export interface SpawnOptions extends AgentPolicy {
12
16
  /** Working directory. Defaults to the Orchestrator's cwd. */
13
17
  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
18
  /** Request a fresh Git worktree. The requested cwd remains the base until spawn resolves. */
75
19
  readonly worktree?: boolean;
76
20
  /**
@@ -89,8 +33,11 @@ export interface SpawnOptions {
89
33
  * `parent` is omitted on purpose: a Handle must never reach this shape, because
90
34
  * an Ask records these options into the Cassette. Spawn resolves the Parent
91
35
  * Link to a name, which travels in `OpenOptions` and stays out of Ask identity.
36
+ * `askDefaults` is omitted too: the Ask hash sees the defaults through the
37
+ * merged Ask options, so they never enter the recorded spawn options.
92
38
  */
93
- export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thinking" | "parent"> {
39
+ export interface ResolvedSpawnOptions
40
+ extends Omit<SpawnOptions, "model" | "thinking" | "parent" | "askDefaults"> {
94
41
  readonly model?: string;
95
42
  readonly thinking?: ThinkingLevel;
96
43
  }
@@ -101,7 +48,8 @@ export interface ResolvedSpawnOptions extends Omit<SpawnOptions, "model" | "thin
101
48
  * A fork inherits the source's resolved spawn options verbatim: model,
102
49
  * thinking, tools, skills, system prompt, extensions and Ask defaults. `name`
103
50
  * 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`.
51
+ * names one. The fork source becomes the child's default `parent`. An
52
+ * `askDefaults` given here replaces the source's object; it does not merge.
105
53
  *
106
54
  * The inherited model is the concrete one the source settled on, so the child
107
55
  * never re-runs the source's fallback list; `fork({ model })` is the way out.
package/src/index.ts CHANGED
@@ -193,6 +193,7 @@ export {
193
193
  worktreeTransport,
194
194
  } from "./transport/index.ts";
195
195
  export type {
196
+ AgentPolicy,
196
197
  AskOptions,
197
198
  ForkOptions,
198
199
  Handle,
package/src/public-api.ts CHANGED
@@ -13,6 +13,7 @@
13
13
  export type { AgentConfig, AgentDefinition } from "./agent/define-agent.ts";
14
14
  export { defineAgent } from "./agent/define-agent.ts";
15
15
  export type {
16
+ AgentPolicy,
16
17
  AskOptions,
17
18
  Handle,
18
19
  SpawnOptions,
package/src/types.ts CHANGED
@@ -5,6 +5,7 @@
5
5
  * except `typebox` (ADR-0045). This file keeps the historic import path.
6
6
  */
7
7
  export type {
8
+ AgentPolicy,
8
9
  AgentProgress,
9
10
  AskOptions,
10
11
  CompactionResult,