pi-cowboy 0.17.1 → 0.17.2

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/README.md CHANGED
@@ -28,7 +28,7 @@ Give each agent a smaller, isolated subtask. A single task with clear instructio
28
28
 
29
29
  Multiple agents can edit, build, and run tests at the same time without interfering with each other. Copy-on-write worktrees make high parallelism practical by keeping disk usage small even when your repository is in the magnitude of gigabytes.
30
30
 
31
- The numbers below come from a Git repository with 153,607 files in total (479 MiB tracked, 27 GiB total including untracked files):
31
+ The numbers below come from a Git repository on macOS with 153,607 files in total (479 MiB tracked, 27 GiB total including untracked files):
32
32
 
33
33
  | Method | Including untracked | Size on disk |
34
34
  | ---------------------------------------------- | ------------------- | ------------ |
@@ -21,7 +21,7 @@
21
21
  * the wall holds a `RegisteredHarness` and never branches on origin.
22
22
  */
23
23
  import { type Availability } from "../../availability.js";
24
- import { type AnyHarnessId, type Harness, type HarnessFamily, type HarnessLaunch, type HarnessListModelsRequest, type PluginHarness } from "../harness.js";
24
+ import { type AnyHarnessId, type Harness, type HarnessConfigIssue, type HarnessFamily, type HarnessLaunch, type HarnessListModelsRequest, type PluginHarness } from "../harness.js";
25
25
  /**
26
26
  * Everything one launch needs that a harness can be handed without knowing its
27
27
  * origin: the one contract every implementation presents, plus the identity the
@@ -54,6 +54,16 @@ export interface HarnessRegistry {
54
54
  ids(): readonly AnyHarnessId[];
55
55
  /** The harness for one id, or undefined for an id nothing registered. */
56
56
  get(id: AnyHarnessId): RegisteredHarness | undefined;
57
+ /**
58
+ * Validate every registered harness's configuration section against the
59
+ * session's raw layers, recording the value its launch reads. A codec that
60
+ * declares no project scope receives no project slice; one that throws takes
61
+ * its harness out of the session's vocabulary instead of ending startup.
62
+ */
63
+ validateConfigs(layers: {
64
+ readonly global: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
65
+ readonly project: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
66
+ }, report: (id: AnyHarnessId, issue: HarnessConfigIssue) => void): void;
57
67
  /**
58
68
  * The harness for one id. A caller that reaches here has already narrowed the
59
69
  * id to a registered one (config resolve, request refusal), so an unregistered
@@ -69,6 +79,8 @@ export interface HarnessRegistry {
69
79
  * built-in or plugin — needs the probe to have confirmed it.
70
80
  */
71
81
  runnable(availability: Availability<AnyHarnessId>): AnyHarnessId[];
82
+ /** The value this harness's codec validated, or undefined when it has none. */
83
+ config(id: AnyHarnessId): unknown;
72
84
  /**
73
85
  * Which harness a spawn launches under: the configured one when it is both
74
86
  * registered and launchable here, pi otherwise. Registration is checked as
@@ -20,7 +20,7 @@
20
20
  * over the shared inputs, so it is stored as it registered. Everything above
21
21
  * the wall holds a `RegisteredHarness` and never branches on origin.
22
22
  */
23
- import { assertNever } from "../../utils.js";
23
+ import { assertNever, errorMessage } from "../../utils.js";
24
24
  import { isAvailable, isProven, } from "../../availability.js";
25
25
  import { DEFAULT_HARNESS, HARNESS_IDS, isPiFamilyHarness, parseHarnessId, } from "../harness.js";
26
26
  import { buildPiLaunchArgs, piFamilyListModels } from "./pi-compatible.js";
@@ -126,6 +126,9 @@ function wrapBuiltin(id) {
126
126
  return {
127
127
  id,
128
128
  displayName: BUILTIN_DISPLAY_NAMES[id],
129
+ // The codec is what `validateConfigs` reads for a built-in too, so the
130
+ // uniform entry carries it.
131
+ config: harness.config,
129
132
  agentMultiplexerKind: harness.agentMultiplexerKind,
130
133
  availability: () => harness.availability(),
131
134
  prepare: (request) => withBuiltin(id, request.launch, (typed, launch) => typed.prepare({
@@ -134,6 +137,7 @@ function wrapBuiltin(id) {
134
137
  paneId: request.paneId,
135
138
  cwd: request.cwd,
136
139
  launch,
140
+ config: request.config,
137
141
  })),
138
142
  buildArgs: (launch) => withBuiltin(id, launch, (typed, request) => typed.buildArgs(request)),
139
143
  teardown: (request) => harness.teardown(request),
@@ -150,6 +154,8 @@ export function createHarnessRegistry() {
150
154
  const registered = new Map(HARNESS_IDS.map((id) => [id, wrapBuiltin(id)]));
151
155
  /** The ids this registry's plugins own, so `unregister` cannot remove another's. */
152
156
  const owned = new Set();
157
+ /** Each harness's validated configuration, stored beside the entry. */
158
+ const configs = new Map();
153
159
  const registry = {
154
160
  register(harness) {
155
161
  const refusal = parseHarnessId(harness.id) !== undefined
@@ -170,6 +176,7 @@ export function createHarnessRegistry() {
170
176
  return;
171
177
  registered.delete(id);
172
178
  owned.delete(id);
179
+ configs.delete(id);
173
180
  },
174
181
  ids() {
175
182
  return [...registered.keys()];
@@ -177,6 +184,26 @@ export function createHarnessRegistry() {
177
184
  get(id) {
178
185
  return registered.get(id);
179
186
  },
187
+ validateConfigs(layers, report) {
188
+ for (const [id, harness] of registered) {
189
+ const codec = harness.config;
190
+ if (codec === undefined)
191
+ continue;
192
+ const project = codec.scope === "project" ? layers.project[id] : undefined;
193
+ try {
194
+ configs.set(id, codec.parse({ global: layers.global[id], project }, (issue) => report(id, issue)));
195
+ }
196
+ catch (error) {
197
+ // `parse` is plugin code. A harness whose codec cannot answer would
198
+ // hand `prepare` no config at all, so it leaves the session's
199
+ // vocabulary instead of ending session startup.
200
+ registered.delete(id);
201
+ owned.delete(id);
202
+ configs.delete(id);
203
+ console.warn(`[subagents] Disabling harness "${id}": its configuration codec failed to parse it (${errorMessage(error)}).`);
204
+ }
205
+ }
206
+ },
180
207
  require(id) {
181
208
  const harness = registered.get(id);
182
209
  if (harness === undefined) {
@@ -192,6 +219,9 @@ export function createHarnessRegistry() {
192
219
  .ids()
193
220
  .filter((id) => isPiFamilyHarness(id) || isProven(id, availability));
194
221
  },
222
+ config(id) {
223
+ return configs.get(id);
224
+ },
195
225
  resolve(configured, availability) {
196
226
  return registered.has(configured) && isAvailable(configured, availability)
197
227
  ? configured
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Defines schema, validation, and defaults for `harness.opencode`.
3
+ *
4
+ * Subagents exclude specific OpenCode root configuration keys by default.
5
+ * `configInclude` re-includes one of those roots whole: each entry must name an
6
+ * excluded root. Keys outside the excluded set are copied unconditionally, so
7
+ * naming one in `configInclude` is rejected as redundant.
8
+ *
9
+ * File reading, filtering, and staging live in user-config.ts.
10
+ */
11
+ import type { HarnessConfigCodec } from "../../harness.js";
12
+ /**
13
+ * The roots a staged config never copies unless `configInclude` names one.
14
+ *
15
+ * `mcp` is deliberately absent: a subagent that lost the parent's MCP servers
16
+ * would lose tools the parent's workflow depends on, so they are always copied.
17
+ */
18
+ export declare const EXCLUDED_OPENCODE_CONFIG_ROOTS: readonly ["agent", "agents", "autoupdate", "experimental", "instructions", "mode", "permission", "permissions", "plugin", "plugins", "policies", "reference", "references", "skills", "tools", "update"];
19
+ /** A key `configInclude` may name: one of the roots the staging excludes. */
20
+ export type OpencodeConfigRoot = (typeof EXCLUDED_OPENCODE_CONFIG_ROOTS)[number];
21
+ /** The wording a rejected `configInclude` entry is reported with. */
22
+ export declare const CONFIG_INCLUDE_EXPECTED: string;
23
+ /** True when a value names a root the staged config excludes by default. */
24
+ export declare function isOpencodeConfigIncludeRoot(value: string): value is OpencodeConfigRoot;
25
+ /** The typed slice OpenCode reads from `harness.opencode`. */
26
+ export interface OpencodeConfig {
27
+ readonly configInclude: readonly OpencodeConfigRoot[];
28
+ }
29
+ /**
30
+ * OpenCode's own config validation. It owns the field names and the valid
31
+ * `configInclude` roots; the registry carries the raw slice and formats the
32
+ * issues this reports.
33
+ *
34
+ * Hand-rolled rather than a zod schema: a bad `configInclude` entry is dropped on
35
+ * its own rather than failing the list, the contract is plain data because a
36
+ * plugin package shares no zod instance with pi-cowboy, and an entry reports
37
+ * with the config layer's own warning wording.
38
+ */
39
+ export declare const opencodeConfigCodec: HarnessConfigCodec<OpencodeConfig>;
@@ -0,0 +1,85 @@
1
+ /**
2
+ * Defines schema, validation, and defaults for `harness.opencode`.
3
+ *
4
+ * Subagents exclude specific OpenCode root configuration keys by default.
5
+ * `configInclude` re-includes one of those roots whole: each entry must name an
6
+ * excluded root. Keys outside the excluded set are copied unconditionally, so
7
+ * naming one in `configInclude` is rejected as redundant.
8
+ *
9
+ * File reading, filtering, and staging live in user-config.ts.
10
+ */
11
+ /**
12
+ * The roots a staged config never copies unless `configInclude` names one.
13
+ *
14
+ * `mcp` is deliberately absent: a subagent that lost the parent's MCP servers
15
+ * would lose tools the parent's workflow depends on, so they are always copied.
16
+ */
17
+ export const EXCLUDED_OPENCODE_CONFIG_ROOTS = [
18
+ "agent",
19
+ "agents",
20
+ "autoupdate",
21
+ "experimental",
22
+ "instructions",
23
+ "mode",
24
+ "permission",
25
+ "permissions",
26
+ "plugin",
27
+ "plugins",
28
+ "policies",
29
+ "reference",
30
+ "references",
31
+ "skills",
32
+ "tools",
33
+ "update",
34
+ ];
35
+ const EXCLUDED_ROOTS = new Set(EXCLUDED_OPENCODE_CONFIG_ROOTS);
36
+ /** The wording a rejected `configInclude` entry is reported with. */
37
+ export const CONFIG_INCLUDE_EXPECTED = `one of: ${EXCLUDED_OPENCODE_CONFIG_ROOTS.join(", ")}`;
38
+ /** True when a value names a root the staged config excludes by default. */
39
+ export function isOpencodeConfigIncludeRoot(value) {
40
+ return EXCLUDED_ROOTS.has(value);
41
+ }
42
+ /**
43
+ * OpenCode's own config validation. It owns the field names and the valid
44
+ * `configInclude` roots; the registry carries the raw slice and formats the
45
+ * issues this reports.
46
+ *
47
+ * Hand-rolled rather than a zod schema: a bad `configInclude` entry is dropped on
48
+ * its own rather than failing the list, the contract is plain data because a
49
+ * plugin package shares no zod instance with pi-cowboy, and an entry reports
50
+ * with the config layer's own warning wording.
51
+ */
52
+ export const opencodeConfigCodec = {
53
+ scope: "global",
54
+ parse({ global }, report) {
55
+ const configInclude = [];
56
+ if (global === undefined)
57
+ return { configInclude };
58
+ const raw = global.configInclude;
59
+ if (raw === undefined)
60
+ return { configInclude };
61
+ if (!Array.isArray(raw)) {
62
+ report({
63
+ layer: "global",
64
+ keyPath: "configInclude",
65
+ got: raw,
66
+ expected: "array of root keys",
67
+ });
68
+ return { configInclude };
69
+ }
70
+ for (const [index, entry] of raw.entries()) {
71
+ if (typeof entry !== "string" || !isOpencodeConfigIncludeRoot(entry)) {
72
+ report({
73
+ layer: "global",
74
+ keyPath: `configInclude[${index}]`,
75
+ got: entry,
76
+ expected: CONFIG_INCLUDE_EXPECTED,
77
+ });
78
+ continue;
79
+ }
80
+ if (!configInclude.includes(entry))
81
+ configInclude.push(entry);
82
+ }
83
+ return { configInclude };
84
+ },
85
+ };
@@ -29,4 +29,5 @@
29
29
  * appends it to the model key as `provider/model#variant`.
30
30
  */
31
31
  import type { Harness, OpencodeLaunchRequest } from "../../harness.js";
32
- export declare const opencodeHarness: Harness<OpencodeLaunchRequest>;
32
+ import { type OpencodeConfig } from "./config.js";
33
+ export declare const opencodeHarness: Harness<OpencodeLaunchRequest, OpencodeConfig>;
@@ -30,6 +30,7 @@
30
30
  */
31
31
  import { parseModelKey } from "../../../utils.js";
32
32
  import { installPaneLauncher, singleQuoteShellWord, splitMarker, } from "../pane-launcher.js";
33
+ import { opencodeConfigCodec } from "./config.js";
33
34
  import { removeOpencodeStaging, writeOpencodeStaging } from "./staging.js";
34
35
  import { probeOpencode } from "./version.js";
35
36
  /** Budget for the list command; a hung CLI must not hold a menu open. */
@@ -66,11 +67,24 @@ const MODEL_FAILURE = "Model unavailable";
66
67
  * multi-line task: it becomes the initial message (opencode reads stdin as the
67
68
  * prompt when it is not a terminal), and mini mode then reopens the controlling
68
69
  * terminal for input, so later steers still reach the process.
70
+ *
71
+ * `OPENCODE_CONFIG` names the staged copy of the parent's explicit config
72
+ * file, when the parent had one, and is unset otherwise; either way the spawn
73
+ * reads only files the staging assembled. `OPENCODE_CONFIG_CONTENT` would
74
+ * point opencode at inline config the staging did not assemble, so it is
75
+ * always unset. Update checks are off: nobody can answer an update prompt in a
76
+ * background pane, and an install would replace the binary the parent session
77
+ * is running.
69
78
  */
70
- function launcherBody(configDir, taskFile) {
79
+ function launcherBody(configDir, taskFile, explicitConfigFile) {
71
80
  return [
81
+ explicitConfigFile === undefined
82
+ ? "unset OPENCODE_CONFIG"
83
+ : `export OPENCODE_CONFIG=${singleQuoteShellWord(explicitConfigFile)}`,
84
+ "unset OPENCODE_CONFIG_CONTENT",
72
85
  `export OPENCODE_CONFIG_DIR=${singleQuoteShellWord(configDir)}`,
73
86
  "export OPENCODE_DISABLE_PROJECT_CONFIG=1",
87
+ "export OPENCODE_DISABLE_AUTOUPDATE=1",
74
88
  `command opencode "$@" < ${singleQuoteShellWord(taskFile)}`,
75
89
  ].join("; ");
76
90
  }
@@ -222,6 +236,7 @@ function opencodeAvailability() {
222
236
  }
223
237
  }
224
238
  export const opencodeHarness = {
239
+ config: opencodeConfigCodec,
225
240
  agentMultiplexerKind: "opencode",
226
241
  availability: opencodeAvailability,
227
242
  /**
@@ -230,15 +245,16 @@ export const opencodeHarness = {
230
245
  * launch reaches the CLI through this pane state alone, so it is verified here
231
246
  * rather than assumed.
232
247
  */
233
- async prepare({ pane, paneId, launch, }) {
234
- const configDir = writeOpencodeStaging({
248
+ async prepare({ pane, paneId, launch, config, }) {
249
+ const { configDir, explicitConfigFile } = writeOpencodeStaging({
235
250
  subagentId: launch.subagentId,
236
251
  systemPromptFile: launch.systemPromptFile,
237
252
  toolSelection: launch.toolSelection,
253
+ configInclude: config.configInclude,
238
254
  });
239
255
  await installPaneLauncher(pane, paneId, {
240
256
  commandName: OPENCODE_COMMAND,
241
- body: launcherBody(configDir, launch.taskFile),
257
+ body: launcherBody(configDir, launch.taskFile, explicitConfigFile),
242
258
  signature: LAUNCHER_SIGNATURE,
243
259
  readyMarker: LAUNCHER_READY_MARKER,
244
260
  proof: definitionProof(launch.subagentId),
@@ -6,24 +6,42 @@
6
6
  * project config disabled, so everything the spawn gets is what lands here: the
7
7
  * definition its prompt is read from (definition.ts). Nothing here launches
8
8
  * anything or knows which pane the process will live in.
9
+ *
10
+ * The redirect also shadows the user's own `opencode.json` / `opencode.jsonc`,
11
+ * which is where the providers live; a spawn without them has no provider and
12
+ * fails ("User not found"). So the staging copies the user's own config in,
13
+ * filtered by the extension's excluded roots (config.ts) through
14
+ * user-config.ts. Auth needs no copy:
15
+ * `auth.json` lives in the XDG data directory, which `OPENCODE_CONFIG_DIR` does
16
+ * not redirect.
9
17
  */
10
18
  import type { ToolSelection } from "../../harness.js";
19
+ import type { OpencodeConfigRoot } from "./config.js";
20
+ /** What staging wrote: the config directory, and the explicit config copy if any. */
21
+ export interface OpencodeStaging {
22
+ /** The config directory `OPENCODE_CONFIG_DIR` names. */
23
+ readonly configDir: string;
24
+ /** The staged copy of the parent's `OPENCODE_CONFIG` file, when staging made one. */
25
+ readonly explicitConfigFile?: string;
26
+ }
11
27
  /**
12
28
  * `<subagentResultDirFor(id)>/opencode` — the config dir opencode is pointed at.
13
29
  */
14
30
  export declare function opencodeConfigDir(subagentId: string): string;
15
31
  /**
16
- * Write the whole staging tree and return the config dir.
32
+ * Write the whole staging tree.
17
33
  *
18
34
  * The system prompt is read before anything is created, so an unreadable prompt
19
35
  * file fails the spawn without leaving a half-built tree behind. A definition
20
- * file already in place is overwritten.
36
+ * file already in place is overwritten. The user config copy is best-effort: a
37
+ * user with neither file has no providers to carry.
21
38
  */
22
39
  export declare function writeOpencodeStaging(input: {
23
40
  subagentId: string;
24
41
  systemPromptFile: string;
25
42
  toolSelection: ToolSelection;
26
- }): string;
43
+ configInclude: readonly OpencodeConfigRoot[];
44
+ }): OpencodeStaging;
27
45
  /**
28
46
  * Remove the staging tree: the files each module staged, then the directory that
29
47
  * held them. Best effort and idempotent — every step is a no-op when its target
@@ -6,11 +6,20 @@
6
6
  * project config disabled, so everything the spawn gets is what lands here: the
7
7
  * definition its prompt is read from (definition.ts). Nothing here launches
8
8
  * anything or knows which pane the process will live in.
9
+ *
10
+ * The redirect also shadows the user's own `opencode.json` / `opencode.jsonc`,
11
+ * which is where the providers live; a spawn without them has no provider and
12
+ * fails ("User not found"). So the staging copies the user's own config in,
13
+ * filtered by the extension's excluded roots (config.ts) through
14
+ * user-config.ts. Auth needs no copy:
15
+ * `auth.json` lives in the XDG data directory, which `OPENCODE_CONFIG_DIR` does
16
+ * not redirect.
9
17
  */
10
18
  import fs from "node:fs";
11
19
  import * as path from "node:path";
12
20
  import { subagentResultDirFor } from "../../../paths.js";
13
21
  import { removeAgentDefinition, writeAgentDefinition } from "./definition.js";
22
+ import { writeUserOpencodeConfig } from "./user-config.js";
14
23
  /** The config directory's name inside a spawn's staging directory. */
15
24
  const CONFIG_DIR_NAME = "opencode";
16
25
  /**
@@ -20,11 +29,12 @@ export function opencodeConfigDir(subagentId) {
20
29
  return path.join(subagentResultDirFor(subagentId), CONFIG_DIR_NAME);
21
30
  }
22
31
  /**
23
- * Write the whole staging tree and return the config dir.
32
+ * Write the whole staging tree.
24
33
  *
25
34
  * The system prompt is read before anything is created, so an unreadable prompt
26
35
  * file fails the spawn without leaving a half-built tree behind. A definition
27
- * file already in place is overwritten.
36
+ * file already in place is overwritten. The user config copy is best-effort: a
37
+ * user with neither file has no providers to carry.
28
38
  */
29
39
  export function writeOpencodeStaging(input) {
30
40
  const systemPrompt = fs.readFileSync(input.systemPromptFile, "utf-8");
@@ -34,7 +44,11 @@ export function writeOpencodeStaging(input) {
34
44
  systemPrompt,
35
45
  toolSelection: input.toolSelection,
36
46
  });
37
- return configDir;
47
+ const explicitConfigFile = writeUserOpencodeConfig({
48
+ configDir,
49
+ configInclude: input.configInclude,
50
+ });
51
+ return { configDir, explicitConfigFile };
38
52
  }
39
53
  /**
40
54
  * Remove the staging tree: the files each module staged, then the directory that
@@ -0,0 +1,36 @@
1
+ /**
2
+ * opencode/user-config.ts — stages a filtered copy of the parent's OpenCode
3
+ * configuration in a spawn's config directory.
4
+ *
5
+ * opencode launches with `OPENCODE_CONFIG_DIR` naming the staging tree, so the
6
+ * files the parent session reads are shadowed. The spawn still needs their
7
+ * providers and general settings, but not the parts that belong to that session
8
+ * alone: the definitions in `agent/`, the plugins it loaded, its permission rules,
9
+ * or its update policy. Its MCP servers are copied: they are the parent's tools.
10
+ *
11
+ * Which roots are excluded, and which `configInclude` names are legal, is the
12
+ * slice policy in config.ts. This module reads the files, filters them through
13
+ * that policy, and writes the staged copies. Update checks are the launcher's:
14
+ * it sets `OPENCODE_DISABLE_AUTOUPDATE`, so no staged value decides them.
15
+ */
16
+ import { type OpencodeConfigRoot } from "./config.js";
17
+ /** The names opencode reads its user config under, in either dialect. */
18
+ export declare const USER_CONFIG_FILE_NAMES: readonly ["opencode.json", "opencode.jsonc"];
19
+ /**
20
+ * The config directory the user's own opencode reads: its own
21
+ * `OPENCODE_CONFIG_DIR` when set, else `opencode` under the XDG config home.
22
+ * Resolved per call, like the staging directory.
23
+ */
24
+ export declare function userOpencodeConfigDir(): string;
25
+ /**
26
+ * Write the filtered parent configuration into `configDir`, answering the staged
27
+ * copy of the file `OPENCODE_CONFIG` names when there was one. Each file is read
28
+ * and filtered separately and staged under its own name, so the name opencode
29
+ * would read in the parent's directory resolves to its filtered counterpart
30
+ * here. A missing, unreadable, or non-object file is skipped with a warning; the
31
+ * spawn then starts on the staging alone rather than failing its launch.
32
+ */
33
+ export declare function writeUserOpencodeConfig(input: {
34
+ configDir: string;
35
+ configInclude: readonly OpencodeConfigRoot[];
36
+ }): string | undefined;
@@ -0,0 +1,172 @@
1
+ /**
2
+ * opencode/user-config.ts — stages a filtered copy of the parent's OpenCode
3
+ * configuration in a spawn's config directory.
4
+ *
5
+ * opencode launches with `OPENCODE_CONFIG_DIR` naming the staging tree, so the
6
+ * files the parent session reads are shadowed. The spawn still needs their
7
+ * providers and general settings, but not the parts that belong to that session
8
+ * alone: the definitions in `agent/`, the plugins it loaded, its permission rules,
9
+ * or its update policy. Its MCP servers are copied: they are the parent's tools.
10
+ *
11
+ * Which roots are excluded, and which `configInclude` names are legal, is the
12
+ * slice policy in config.ts. This module reads the files, filters them through
13
+ * that policy, and writes the staged copies. Update checks are the launcher's:
14
+ * it sets `OPENCODE_DISABLE_AUTOUPDATE`, so no staged value decides them.
15
+ */
16
+ import fs from "node:fs";
17
+ import { homedir } from "node:os";
18
+ import * as path from "node:path";
19
+ import { parse as parseJsonc } from "jsonc-parser";
20
+ import { isRecord } from "../../../predicates.js";
21
+ import { errorMessage } from "../../../utils.js";
22
+ import { ensureResultDir, writeResultFile, } from "../../result-file-permissions.js";
23
+ import { EXCLUDED_OPENCODE_CONFIG_ROOTS, } from "./config.js";
24
+ /** The names opencode reads its user config under, in either dialect. */
25
+ export const USER_CONFIG_FILE_NAMES = [
26
+ "opencode.json",
27
+ "opencode.jsonc",
28
+ ];
29
+ /**
30
+ * The name the parent's explicit config file is staged under — not one opencode
31
+ * scans from a config directory. The launcher names this file with
32
+ * `OPENCODE_CONFIG`, leaving opencode's own precedence between it and the staged
33
+ * directory intact.
34
+ */
35
+ const EXPLICIT_CONFIG_FILE_NAME = "explicit-config.json";
36
+ /**
37
+ * The config directory the user's own opencode reads: its own
38
+ * `OPENCODE_CONFIG_DIR` when set, else `opencode` under the XDG config home.
39
+ * Resolved per call, like the staging directory.
40
+ */
41
+ export function userOpencodeConfigDir() {
42
+ const xdgConfigHome = envDir("XDG_CONFIG_HOME") ?? path.join(homedir(), ".config");
43
+ return envDir("OPENCODE_CONFIG_DIR") ?? path.join(xdgConfigHome, "opencode");
44
+ }
45
+ /**
46
+ * Write the filtered parent configuration into `configDir`, answering the staged
47
+ * copy of the file `OPENCODE_CONFIG` names when there was one. Each file is read
48
+ * and filtered separately and staged under its own name, so the name opencode
49
+ * would read in the parent's directory resolves to its filtered counterpart
50
+ * here. A missing, unreadable, or non-object file is skipped with a warning; the
51
+ * spawn then starts on the staging alone rather than failing its launch.
52
+ */
53
+ export function writeUserOpencodeConfig(input) {
54
+ const sourceDir = userOpencodeConfigDir();
55
+ const staged = new Map();
56
+ for (const name of USER_CONFIG_FILE_NAMES) {
57
+ const sourceFile = path.join(sourceDir, name);
58
+ const source = readUserConfig(sourceFile);
59
+ if (source === undefined)
60
+ continue;
61
+ staged.set(name, filterUserConfig(source, input.configInclude, sourceFile));
62
+ }
63
+ writeStagedConfigs(input.configDir, staged);
64
+ return stageExplicitConfig(input.configDir, input.configInclude);
65
+ }
66
+ /**
67
+ * Stage a filtered copy of the file `OPENCODE_CONFIG` names. Handing the spawn
68
+ * the parent's path would also hand it the roots the staging excludes (plugins,
69
+ * permission rules, agent definitions). The launcher points the
70
+ * variable at this copy, so opencode keeps its own precedence between it and the
71
+ * staged directory.
72
+ */
73
+ function stageExplicitConfig(configDir, configInclude) {
74
+ const sourceFile = envDir("OPENCODE_CONFIG");
75
+ if (sourceFile === undefined)
76
+ return undefined;
77
+ const source = readUserConfig(sourceFile);
78
+ if (source === undefined)
79
+ return undefined;
80
+ const stagedFile = path.join(configDir, EXPLICIT_CONFIG_FILE_NAME);
81
+ writeResultFile(stagedFile, `${JSON.stringify(filterUserConfig(source, configInclude, sourceFile), null, 2)}\n`);
82
+ return stagedFile;
83
+ }
84
+ /** Read one config file, or undefined when it is absent or unusable. */
85
+ function readUserConfig(filePath) {
86
+ let text;
87
+ try {
88
+ text = fs.readFileSync(filePath, "utf-8");
89
+ }
90
+ catch (err) {
91
+ if (err?.code === "ENOENT") {
92
+ return undefined;
93
+ }
94
+ console.warn(`[subagents] Could not read the opencode user config ${filePath}: ${errorMessage(err)}. The spawn starts without it.`);
95
+ return undefined;
96
+ }
97
+ const errors = [];
98
+ const parsed = parseJsonc(text, errors, {
99
+ allowTrailingComma: true,
100
+ disallowComments: false,
101
+ });
102
+ if (errors.length > 0) {
103
+ console.warn(`[subagents] Ignoring malformed opencode user config ${filePath}: it is not valid JSONC. The spawn starts without it.`);
104
+ return undefined;
105
+ }
106
+ if (!isRecord(parsed)) {
107
+ console.warn(`[subagents] Ignoring malformed opencode user config ${filePath}: it is not a JSON object. The spawn starts without it.`);
108
+ return undefined;
109
+ }
110
+ return parsed;
111
+ }
112
+ /**
113
+ * Copy the user config without the excluded roots, then copy back the roots
114
+ * `configInclude` names whole. `$schema` never survives: it is a reference to
115
+ * the schema file, not a setting a staged config needs.
116
+ */
117
+ function filterUserConfig(source, configInclude, filePath) {
118
+ const kept = structuredClone(source);
119
+ for (const root of EXCLUDED_OPENCODE_CONFIG_ROOTS)
120
+ delete kept[root];
121
+ delete kept.$schema;
122
+ for (const root of configInclude) {
123
+ if (Object.hasOwn(source, root)) {
124
+ kept[root] = structuredClone(source[root]);
125
+ }
126
+ }
127
+ return rebaseFileReferences(kept, path.dirname(filePath));
128
+ }
129
+ /**
130
+ * `{file:./path}` is resolved against the file that carried it. The staged copy
131
+ * lives elsewhere, so each relative reference becomes the source-relative
132
+ * absolute path; an already-absolute one is left alone.
133
+ */
134
+ const FILE_REFERENCE = /\{file:([^}]+)\}/g;
135
+ function rebaseFileReferences(value, sourceDir) {
136
+ if (typeof value === "string") {
137
+ return value.replace(FILE_REFERENCE, (_match, referenced) => `{file:${absoluteReference(referenced, sourceDir)}}`);
138
+ }
139
+ if (Array.isArray(value)) {
140
+ return value.map((entry) => rebaseFileReferences(entry, sourceDir));
141
+ }
142
+ if (isRecord(value)) {
143
+ return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
144
+ key,
145
+ rebaseFileReferences(entry, sourceDir),
146
+ ]));
147
+ }
148
+ return value;
149
+ }
150
+ function absoluteReference(reference, sourceDir) {
151
+ if (reference.startsWith("~/")) {
152
+ return path.join(homedir(), reference.slice(2));
153
+ }
154
+ return path.isAbsolute(reference)
155
+ ? reference
156
+ : path.resolve(sourceDir, reference);
157
+ }
158
+ /** Write the staged configs, replacing any file a previous staging left. */
159
+ function writeStagedConfigs(configDir, staged) {
160
+ ensureResultDir(configDir);
161
+ for (const name of [...USER_CONFIG_FILE_NAMES, EXPLICIT_CONFIG_FILE_NAME]) {
162
+ fs.rmSync(path.join(configDir, name), { force: true });
163
+ }
164
+ for (const [name, config] of staged) {
165
+ writeResultFile(path.join(configDir, name), `${JSON.stringify(config, null, 2)}\n`);
166
+ }
167
+ }
168
+ /** An environment directory, or undefined when unset or empty (XDG's default). */
169
+ function envDir(name) {
170
+ const value = process.env[name];
171
+ return value === undefined || value === "" ? undefined : value;
172
+ }
@@ -6,4 +6,4 @@
6
6
  * unchanged; only its binary name differs from pi, which the pi-compatible
7
7
  * factory reconciles by pointing the pane's `pi` at `pi-bolt`.
8
8
  */
9
- export declare const piBoltHarness: import("../harness.js").Harness<import("../harness.js").PiFamilyLaunchRequest>;
9
+ export declare const piBoltHarness: import("../harness.js").Harness<import("../harness.js").PiFamilyLaunchRequest, unknown>;
@@ -7,4 +7,4 @@
7
7
  * Only its binary name differs from pi, which the pi-compatible factory
8
8
  * reconciles by pointing the pane's `pi` at `pig`.
9
9
  */
10
- export declare const pigHarness: import("../harness.js").Harness<import("../harness.js").PiFamilyLaunchRequest>;
10
+ export declare const pigHarness: import("../harness.js").Harness<import("../harness.js").PiFamilyLaunchRequest, unknown>;
@@ -239,9 +239,46 @@ export type LaunchRequestFor<K extends HarnessId> = {
239
239
  codex: CodexLaunchRequest;
240
240
  claude: ClaudeLaunchRequest;
241
241
  }[K];
242
+ /**
243
+ * Represents an incompatible value rejected during harness configuration
244
+ * validation. `keyPath` is relative to the harness's section (for example,
245
+ * `configInclude[0]`), and `layer` indicates whether the value originated from
246
+ * the global or project file.
247
+ */
248
+ export interface HarnessConfigIssue {
249
+ readonly layer: "global" | "project";
250
+ readonly keyPath: string;
251
+ readonly got: unknown;
252
+ readonly expected: string;
253
+ }
254
+ /** Callback a codec calls to report each value it rejected. */
255
+ export type HarnessConfigReport = (issue: HarnessConfigIssue) => void;
256
+ /**
257
+ * The configuration slices a codec validates, as the file loader kept them:
258
+ * absent when a file has no section for this harness, else a JSON object.
259
+ * `project` is absent unless the codec declared `scope: "project"`.
260
+ */
261
+ export interface HarnessConfigLayers {
262
+ readonly global?: Readonly<Record<string, unknown>>;
263
+ readonly project?: Readonly<Record<string, unknown>>;
264
+ }
265
+ /**
266
+ * Configuration codec for a harness. Defines the schema, validation rules, and
267
+ * defaults for a harness's configuration section. When `scope` is omitted,
268
+ * validation is global-only and ignores project configuration files. When set
269
+ * to `"project"`, `parse` receives both global and project layers. `parse`
270
+ * always returns a usable value, reporting each rejected value instead of
271
+ * failing the whole section.
272
+ */
273
+ export interface HarnessConfigCodec<T = unknown> {
274
+ readonly scope?: "global" | "project";
275
+ parse(layers: HarnessConfigLayers, report: HarnessConfigReport): T;
276
+ }
242
277
  /** What a harness needs to bring its host pane into the state it launches in. */
243
- export interface HarnessPrepareRequest<L extends SubagentLaunchInputs = HarnessLaunch> {
278
+ export interface HarnessPrepareRequest<L extends SubagentLaunchInputs = HarnessLaunch, C = unknown> {
244
279
  readonly pi: ExtensionAPI;
280
+ /** The validated config for this harness, as its codec produced it. */
281
+ readonly config: C;
245
282
  /**
246
283
  * The pane surface the session's multiplexer offers. A harness types into its
247
284
  * pane through this, never through a multiplexer's own client, so one launch runs
@@ -329,7 +366,12 @@ export type HarnessAvailability = {
329
366
  * implementation: a pi harness cannot name `variant`, and a plugin cannot name
330
367
  * any built-in option at all.
331
368
  */
332
- export interface Harness<L extends SubagentLaunchInputs = HarnessLaunch> {
369
+ export interface Harness<L extends SubagentLaunchInputs = HarnessLaunch, C = unknown> {
370
+ /**
371
+ * Configuration codec for this harness. Validated after plugins register; the
372
+ * parsed value is passed to `prepare` as `request.config`.
373
+ */
374
+ readonly config?: HarnessConfigCodec<C>;
333
375
  /**
334
376
  * The agent kind this harness launches as, in the multiplexer's vocabulary; the only
335
377
  * place a kind appears as a literal. A harness whose binary is not pi's can
@@ -349,7 +391,7 @@ export interface Harness<L extends SubagentLaunchInputs = HarnessLaunch> {
349
391
  * family's own request describes. Idempotent; throws when the state could not
350
392
  * be established.
351
393
  */
352
- prepare(request: HarnessPrepareRequest<L>): Promise<void>;
394
+ prepare(request: HarnessPrepareRequest<L, C>): Promise<void>;
353
395
  /**
354
396
  * The complete argv the pane runs, including how the task rides (the pi
355
397
  * family ends with `@<taskFile>`). Pure: no shellouts, no filesystem writes.
@@ -406,8 +448,9 @@ export type HarnessLaunch = BuiltinLaunchRequest | PluginLaunchRequest;
406
448
  * because it is not keyed in this package's built-in table. The registry holds
407
449
  * it as the same `RegisteredHarness` a built-in becomes (see
408
450
  * harness/harness-registry.ts), so a caller never branches on where it came from.
451
+ * `C` is the value its codec parses, which types the prepare request's config.
409
452
  */
410
- export interface PluginHarness extends Harness<SubagentLaunchInputs> {
453
+ export interface PluginHarness<C = unknown> extends Harness<SubagentLaunchInputs, C> {
411
454
  /** The id config and `harness_type`-shaped values name this harness by. */
412
455
  readonly id: AnyHarnessId;
413
456
  /** The label its settings rows show. */
@@ -364,7 +364,8 @@ export class SubagentSession {
364
364
  const launch = { resultFile: plan.launch.resultFile };
365
365
  this.launchState = launch;
366
366
  launchCwd = plan.cwd;
367
- const harness = getHarnessRegistry().require(plan.harness);
367
+ const harnesses = getHarnessRegistry();
368
+ const harness = harnesses.require(plan.harness);
368
369
  ref =
369
370
  ref ??
370
371
  (await host.hostAt({
@@ -387,6 +388,7 @@ export class SubagentSession {
387
388
  paneId: ref.paneId,
388
389
  cwd: plan.cwd,
389
390
  launch: plan.launch,
391
+ config: harnesses.config(plan.harness),
390
392
  });
391
393
  const supervisor = createPaneSupervisor({
392
394
  host,
@@ -15,6 +15,8 @@ export interface RawConfig {
15
15
  /** The agent keys validation kept, at the types it accepted. */
16
16
  agent?: Partial<SubagentsConfig["agent"]>;
17
17
  concurrency?: RawConcurrency;
18
+ /** Per-harness slices, keyed by harness id, each validated by its harness. */
19
+ harness?: Record<string, Record<string, unknown>>;
18
20
  /** Machine-level: the multiplexer the session runs, by id. */
19
21
  multiplexer?: string;
20
22
  }
@@ -23,6 +25,11 @@ export interface LoadedConfig {
23
25
  project: RawConfig | null;
24
26
  projectStatus: ProjectLayerStatus;
25
27
  }
28
+ /** The files a config layer came from, for warnings the layer formats later. */
29
+ export interface ConfigPaths {
30
+ readonly global: string;
31
+ readonly project?: string;
32
+ }
26
33
  /** Persistence port consumed by ConfigStore. */
27
34
  export interface ConfigIO {
28
35
  load(): LoadedConfig;
@@ -30,6 +37,8 @@ export interface ConfigIO {
30
37
  isGlobalWritable(): boolean;
31
38
  saveGlobal(config: RawConfig): void;
32
39
  saveProject(config: RawConfig): void;
40
+ /** The files this load read, for warnings that name them. */
41
+ paths(): ConfigPaths;
33
42
  }
34
43
  /** Agent keys a project file may set: the model family plus per-type overrides. */
35
44
  export declare const MODEL_FAMILY_KEYS: Set<string>;
@@ -102,6 +102,10 @@ export function createConfigIO(projectDir) {
102
102
  return { global, project: projectRaw, projectStatus };
103
103
  },
104
104
  isGlobalWritable: () => !globalMalformed,
105
+ paths: () => ({
106
+ global: configPath(),
107
+ project: projectPath ?? undefined,
108
+ }),
105
109
  saveGlobal: (config) => {
106
110
  if (globalMalformed) {
107
111
  console.warn("[subagents] Refusing to write global config (malformed); change not saved");
@@ -8,7 +8,7 @@
8
8
  */
9
9
  import type { SubagentsConfig } from "../models/model-precedence.js";
10
10
  import type { AgentManager } from "../agents/agent-manager.js";
11
- import { type AnyHarnessId } from "../agents/harness.js";
11
+ import { type AnyHarnessId, type HarnessConfigIssue } from "../agents/harness.js";
12
12
  import type { ModelsByFamily, SystemPromptMode } from "../agents/types.js";
13
13
  import type { ThinkingLevel } from "../types.js";
14
14
  import { type WorktreeCheckoutType, type WorktreeMaterialization } from "../spawn/worktree-policy.js";
@@ -69,6 +69,13 @@ export declare class ConfigStore {
69
69
  * session without one.
70
70
  */
71
71
  get multiplexer(): string;
72
+ /** The per-harness maps the registry validates after plugins register. */
73
+ harnessConfigLayers(): {
74
+ global: Record<string, Record<string, unknown>>;
75
+ project: Record<string, Record<string, unknown>>;
76
+ };
77
+ /** Warns in the config layer's wording for a harness value its codec rejected. */
78
+ reportHarnessConfigIssue(id: AnyHarnessId, issue: HarnessConfigIssue): void;
72
79
  get concurrency(): ConcurrencyConfig;
73
80
  get sessionDefaultModel(): string | null;
74
81
  sessionModelOverride(type: string): string | null;
@@ -86,10 +93,11 @@ export declare class ConfigStore {
86
93
  /**
87
94
  * Every harness id the config names, wherever it names one: the `harnessType`
88
95
  * setting, the `defaultModelByHarness` keys, the `concurrency.harnesses` keys,
89
- * and the harness qualifier on any `concurrency.providers` / `concurrency.models`
90
- * pool key. A session reports the ids nothing registered — config loads before
91
- * plugins do, so validation cannot answer that question, and a typo would
92
- * otherwise be silent (the launch simply falls back).
96
+ * the harness qualifier on any `concurrency.providers` / `concurrency.models`
97
+ * pool key, and every `harness.<id>` section in either layer. A session
98
+ * reports the ids nothing registered — config loads before plugins do, so
99
+ * validation cannot answer that question, and a typo would otherwise be
100
+ * silent (the launch simply falls back).
93
101
  */
94
102
  configuredHarnessIds(): AnyHarnessId[];
95
103
  hasSessionHarnessDefaultModel(harness: AnyHarnessId): boolean;
@@ -7,13 +7,14 @@
7
7
  * at session_shutdown.
8
8
  */
9
9
  import { harnessDefaultModel, resolveModel, } from "../models/model-precedence.js";
10
- import { DEFAULT_HARNESS } from "../agents/harness.js";
10
+ import { DEFAULT_HARNESS, } from "../agents/harness.js";
11
11
  import { harnessFamilyOf } from "../agents/harness/harness-registry.js";
12
12
  import { parsePoolKey } from "../concurrency-pools.js";
13
13
  import { DEFAULT_WORKTREE_CHECKOUT_TYPE, DEFAULT_WORKTREE_MATERIALIZATION, } from "../spawn/worktree-policy.js";
14
14
  import { DEFAULT_AGENT_TYPE, DEFAULT_ORCHESTRATOR_NAME } from "../types.js";
15
15
  import { CONFIG_AGENT_NON_MODEL_KEYS } from "./types.js";
16
16
  import { LayeredConfig } from "./layered-config.js";
17
+ import { FILE_FIX, incompatibleWarning } from "./config-validation.js";
17
18
  import { MODEL_FAMILY_KEYS, createConfigIO, isProjectAllowedAgentKey, } from "./config-io.js";
18
19
  import { CONCURRENCY_LIMIT_EXPECTED, ConcurrencyLimitSchema, } from "./concurrency-limit.js";
19
20
  const fileConfigIO = createConfigIO();
@@ -108,6 +109,21 @@ export class ConfigStore {
108
109
  get multiplexer() {
109
110
  return this.layers.effective.multiplexer;
110
111
  }
112
+ /** The per-harness maps the registry validates after plugins register. */
113
+ harnessConfigLayers() {
114
+ return {
115
+ global: this.layers.global.harness ?? {},
116
+ project: this.layers.project?.harness ?? {},
117
+ };
118
+ }
119
+ /** Warns in the config layer's wording for a harness value its codec rejected. */
120
+ reportHarnessConfigIssue(id, issue) {
121
+ const paths = this.layers.paths;
122
+ const filePath = issue.layer === "project"
123
+ ? (paths.project ?? paths.global)
124
+ : paths.global;
125
+ console.warn(incompatibleWarning(filePath, `harness.${id}${issue.keyPath === "" ? "" : `.${issue.keyPath}`}`, issue.got, issue.expected, FILE_FIX));
126
+ }
111
127
  get concurrency() {
112
128
  const base = this.layers.effective.concurrency;
113
129
  const session = this.sessionConcurrencyLayer;
@@ -141,10 +157,11 @@ export class ConfigStore {
141
157
  /**
142
158
  * Every harness id the config names, wherever it names one: the `harnessType`
143
159
  * setting, the `defaultModelByHarness` keys, the `concurrency.harnesses` keys,
144
- * and the harness qualifier on any `concurrency.providers` / `concurrency.models`
145
- * pool key. A session reports the ids nothing registered — config loads before
146
- * plugins do, so validation cannot answer that question, and a typo would
147
- * otherwise be silent (the launch simply falls back).
160
+ * the harness qualifier on any `concurrency.providers` / `concurrency.models`
161
+ * pool key, and every `harness.<id>` section in either layer. A session
162
+ * reports the ids nothing registered — config loads before plugins do, so
163
+ * validation cannot answer that question, and a typo would otherwise be
164
+ * silent (the launch simply falls back).
148
165
  */
149
166
  configuredHarnessIds() {
150
167
  const ids = new Set([this.agent.harnessType]);
@@ -153,6 +170,11 @@ export class ConfigStore {
153
170
  }
154
171
  for (const id of Object.keys(this.concurrency.harnesses))
155
172
  ids.add(id);
173
+ const harnessSections = this.harnessConfigLayers();
174
+ for (const id of Object.keys(harnessSections.global))
175
+ ids.add(id);
176
+ for (const id of Object.keys(harnessSections.project))
177
+ ids.add(id);
156
178
  for (const key of [
157
179
  ...Object.keys(this.concurrency.providers),
158
180
  ...Object.keys(this.concurrency.models),
@@ -1,3 +1,7 @@
1
1
  import type { RawConfig } from "./config-io.js";
2
+ /** How a value is fixed when no menu row carries its key. */
3
+ export declare const FILE_FIX = "Edit or delete the key in that file to fix it.";
4
+ /** The one wording every incompatible-value warning uses. */
5
+ export declare function incompatibleWarning(filePath: string, keyPath: string, value: unknown, expected: string, fix: string): string;
2
6
  /** Validate one file layer, dropping invalid values. Never throws: bad input reads as empty. */
3
7
  export declare function validateRawLayer(raw: unknown, filePath: string): RawConfig;
@@ -85,12 +85,17 @@ function describeValue(value) {
85
85
  return "object";
86
86
  return typeof value;
87
87
  }
88
- function formatIncompatibleWarning(filePath, keyPath, value, expected) {
88
+ /** How a value is fixed when the `/cowboy` menu carries a row for its key. */
89
+ const MENU_FIX = "Set it again in the /cowboy menu, or edit or delete the file to fix it.";
90
+ /** How a value is fixed when no menu row carries its key. */
91
+ export const FILE_FIX = "Edit or delete the key in that file to fix it.";
92
+ /** The one wording every incompatible-value warning uses. */
93
+ export function incompatibleWarning(filePath, keyPath, value, expected, fix) {
89
94
  return (`[subagents] Incompatible value in ${filePath}: "${keyPath}" is ${describeValue(value)}, ` +
90
- `expected ${expected}. Set it again in the /cowboy menu, or edit or delete the file to fix it.`);
95
+ `expected ${expected}. ${fix}`);
91
96
  }
92
97
  function warnIncompatible(filePath, keyPath, value, expected) {
93
- console.warn(formatIncompatibleWarning(filePath, keyPath, value, expected));
98
+ console.warn(incompatibleWarning(filePath, keyPath, value, expected, MENU_FIX));
94
99
  }
95
100
  const EXPECTED_OBJECT = "object";
96
101
  /** Validate one file layer, dropping invalid values. Never throws: bad input reads as empty. */
@@ -115,6 +120,11 @@ export function validateRawLayer(raw, filePath) {
115
120
  if (Object.keys(concurrency).length > 0)
116
121
  cleaned.concurrency = concurrency;
117
122
  }
123
+ if (raw.harness !== undefined) {
124
+ const harness = cleanHarnessSections(raw.harness, filePath);
125
+ if (harness !== undefined)
126
+ cleaned.harness = harness;
127
+ }
118
128
  // Machine-level, so it sits at the top of the file rather than under `agent`.
119
129
  if (raw.multiplexer !== undefined) {
120
130
  const parsed = NON_BLANK_STRING.safeParse(raw.multiplexer);
@@ -127,6 +137,28 @@ export function validateRawLayer(raw, filePath) {
127
137
  }
128
138
  return cleaned;
129
139
  }
140
+ /**
141
+ * Validates the structure of the `harness` configuration map. Each entry must be
142
+ * an object. Unrecognized harness IDs are retained so plugins can claim them
143
+ * after loading.
144
+ */
145
+ function cleanHarnessSections(value, filePath) {
146
+ if (!isRecord(value)) {
147
+ console.warn(incompatibleWarning(filePath, "harness", value, EXPECTED_OBJECT, FILE_FIX));
148
+ return undefined;
149
+ }
150
+ const kept = {};
151
+ for (const [id, slice] of Object.entries(value)) {
152
+ if (slice === undefined)
153
+ continue;
154
+ if (!isRecord(slice)) {
155
+ console.warn(incompatibleWarning(filePath, `harness.${id}`, slice, EXPECTED_OBJECT, FILE_FIX));
156
+ continue;
157
+ }
158
+ kept[id] = slice;
159
+ }
160
+ return Object.keys(kept).length > 0 ? kept : undefined;
161
+ }
130
162
  /** An agent key outside the table is a per-type model key. */
131
163
  function cleanAgentEntries(agent, filePath) {
132
164
  const kept = {};
@@ -7,12 +7,14 @@
7
7
  * layer is only ever created by a write.
8
8
  */
9
9
  import type { SubagentsConfig } from "../models/model-precedence.js";
10
- import { type ConfigIO, type ConfigTarget, type RawConfig } from "./config-io.js";
10
+ import { type ConfigIO, type ConfigPaths, type ConfigTarget, type RawConfig } from "./config-io.js";
11
11
  export declare class LayeredConfig {
12
12
  private io;
13
13
  private globalRaw;
14
14
  private projectLayer;
15
15
  constructor(io?: ConfigIO);
16
+ /** The files the current layers came from, for warnings formatted after load. */
17
+ get paths(): ConfigPaths;
16
18
  /** Project file over global file over the built-in defaults. */
17
19
  get effective(): SubagentsConfig;
18
20
  get global(): RawConfig;
@@ -27,6 +27,10 @@ export class LayeredConfig {
27
27
  this.globalRaw = loaded.global;
28
28
  this.projectLayer = projectLayerFrom(loaded);
29
29
  }
30
+ /** The files the current layers came from, for warnings formatted after load. */
31
+ get paths() {
32
+ return this.io.paths();
33
+ }
30
34
  /** Project file over global file over the built-in defaults. */
31
35
  get effective() {
32
36
  return mergeDefaults(mergeLayers(this.globalRaw, this.project));
@@ -151,8 +151,9 @@ export class DelegationProtocol {
151
151
  throw new Error(`Unknown agent type: ${agentType} — nothing was spawned. Use an exact registered name, or omit \`agent_type\` to use the configured default.`);
152
152
  }
153
153
  // An explicit harness is validated here, before any item runs: an unknown
154
- // id and one this machine cannot launch both refuse, because an explicit
155
- // request never falls back to pi. Nothing was spawned either way.
154
+ // id, one this machine cannot launch, and one whose configuration codec
155
+ // failed all refuse, because an explicit request never falls back to pi.
156
+ // Nothing was spawned either way.
156
157
  const requestedHarness = resolveRequestedHarness(params.harness_type);
157
158
  // The harness the launch will use, resolved the way the launch resolves it.
158
159
  // A model key belongs to one harness's catalogue, so model resolution reads
@@ -12,5 +12,5 @@
12
12
  * `Parameters<…>` / `ReturnType<…>` would be a worse contract than naming them.
13
13
  */
14
14
  export type { CowboyPluginApi, CowboyPluginDisposer, CowboyPluginFactory, PluginMultiplexer, PluginHarness, } from "./contract.js";
15
- export type { AnyHarnessId, Harness, HarnessAvailability, HarnessListModelsRequest, HarnessPrepareRequest, HarnessTeardownContext, HarnessTeardownRequest, ModelEntry, SubagentLaunchInputs, ToolSelection, } from "../agents/harness.js";
15
+ export type { AnyHarnessId, Harness, HarnessAvailability, HarnessConfigCodec, HarnessConfigIssue, HarnessConfigLayers, HarnessConfigReport, HarnessListModelsRequest, HarnessPrepareRequest, HarnessTeardownContext, HarnessTeardownRequest, ModelEntry, SubagentLaunchInputs, ToolSelection, } from "../agents/harness.js";
16
16
  export type { AgentMultiplexer, AgentHost, AgentHostRef, AgentMultiplexerKind, AgentView, DeliverOutcome, ExecutionRuntime, HostObservation, PaneControl, PlacementCatalog, PlacementRecord, PlacementWorktree, ViewRequest, } from "../agents/agent-host.js";
@@ -35,8 +35,11 @@ export async function startSessionRuntime(pi, ctx) {
35
35
  if (ctx.hasUI)
36
36
  ctx.ui.notify(message, kind);
37
37
  });
38
- // Configured ids nothing registered: validation cannot see this (config loads
39
- // before plugins register), and silence would let a typo pass for a fallback.
38
+ // Validate harness configuration sections now that all plugin codecs are
39
+ // registered.
40
+ const store = getStore();
41
+ registries.harnesses.validateConfigs(store.harnessConfigLayers(), (id, issue) => store.reportHarnessConfigIssue(id, issue));
42
+ // Report configured harness IDs that do not match any registered harness.
40
43
  reportUnregisteredConfig(ctx, registries);
41
44
  // The multiplexers that detect this process, plugin ones included; a session
42
45
  // runs only inside one of them.
@@ -24,16 +24,18 @@ function harnessDescription(availability) {
24
24
  const base = "Harness that launches agents whose template omits harness_type. pi = the real pi binary; pig and pi-bolt = pi-compatible binaries launched through a shell function in the agent's own pane; opencode and codex = binaries of their own launched as their interactive UIs in the agent's own pane.";
25
25
  const missing = HARNESS_IDS.filter((id) => id !== "pi" && !isAvailable(id, availability));
26
26
  const withMissing = missing.length === 0 ? base : `${base} Not on PATH: ${missing.join(", ")}.`;
27
+ const harnesses = getHarnessRegistry();
27
28
  // A plugin's harness is as launchable a default as a built-in's; name the ones
28
29
  // this machine registered so the row lists everything the value can carry.
29
- const harnesses = getHarnessRegistry();
30
- const plugins = harnesses
31
- .ids()
32
- .filter((id) => parseHarnessId(id) === undefined && isAvailable(id, availability));
30
+ const plugins = offerableHarnesses().filter((id) => parseHarnessId(id) === undefined);
33
31
  return plugins.length === 0
34
32
  ? withMissing
35
33
  : `${withMissing} Plugin harnesses: ${plugins.map((id) => harnesses.displayName(id)).join(", ")}.`;
36
34
  }
35
+ /** The harnesses the row offers: registered and launchable here. */
36
+ function offerableHarnesses() {
37
+ return [...selectable(getHarnessRegistry().ids(), getHarnessAvailability())];
38
+ }
37
39
  export async function showSpawnOptionsMenu(ctx) {
38
40
  const store = getStore();
39
41
  /** " [project]" when the effective value comes from the project layer. */
@@ -76,9 +78,7 @@ export async function showSpawnOptionsMenu(ctx) {
76
78
  id: "harnessType",
77
79
  label: "Default harness",
78
80
  currentValue: getHarnessType(),
79
- values: [
80
- ...selectable(getHarnessRegistry().ids(), getHarnessAvailability()),
81
- ],
81
+ values: offerableHarnesses(),
82
82
  description: harnessDescription(getHarnessAvailability()),
83
83
  },
84
84
  { id: SEPARATOR_ID, label: " ", currentValue: "" },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-cowboy",
3
- "version": "0.17.1",
3
+ "version": "0.17.2",
4
4
  "type": "module",
5
5
  "packageManager": "pnpm@12.9.1",
6
6
  "description": "Agent orchestrator for pi: can manage Codex, Claude Code, OpenCode, pi, pig and pi-bolt as subagents. Runs subagents in background Herdr panes, isolated in copy-on-write Git worktrees.",
@@ -105,6 +105,7 @@
105
105
  "vitest": "^5.0.3"
106
106
  },
107
107
  "dependencies": {
108
+ "jsonc-parser": "^3.3.1",
108
109
  "mustache": "^4.2.0",
109
110
  "smol-toml": "^1.9.0",
110
111
  "yaml": "^2.9.1",