@xzzpig/pi-subagents 0.1.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 (196) hide show
  1. package/CHANGELOG.md +1621 -0
  2. package/LICENSE +21 -0
  3. package/README.md +118 -0
  4. package/agents/delegate.md +14 -0
  5. package/agents/oracle.md +74 -0
  6. package/agents/researcher.md +52 -0
  7. package/agents/reviewer.md +79 -0
  8. package/agents/scout.md +50 -0
  9. package/agents/worker.md +58 -0
  10. package/index.ts +1 -0
  11. package/inspector-runner.mjs +11 -0
  12. package/install.mjs +93 -0
  13. package/package.json +105 -0
  14. package/prompts/gather-context-and-clarify.md +13 -0
  15. package/prompts/parallel-cleanup.md +59 -0
  16. package/prompts/parallel-research.md +50 -0
  17. package/prompts/parallel-review.md +54 -0
  18. package/prompts/review-loop.md +43 -0
  19. package/skills/pi-subagents/SKILL.md +41 -0
  20. package/skills/pi-subagents/references/constraints-and-recipes.md +251 -0
  21. package/skills/pi-subagents/references/execution-controls.md +428 -0
  22. package/skills/pi-subagents/references/management-authoring-rpc.md +161 -0
  23. package/skills/pi-subagents/references/prompting-and-roles.md +242 -0
  24. package/src/agents/agent-management.ts +1256 -0
  25. package/src/agents/agent-memory.ts +254 -0
  26. package/src/agents/agent-refinements.ts +624 -0
  27. package/src/agents/agent-scope.ts +6 -0
  28. package/src/agents/agent-selection.ts +25 -0
  29. package/src/agents/agent-serializer.ts +163 -0
  30. package/src/agents/agents.ts +1889 -0
  31. package/src/agents/chain-serializer.ts +280 -0
  32. package/src/agents/frontmatter.ts +149 -0
  33. package/src/agents/identity.ts +30 -0
  34. package/src/agents/proactive-skills.ts +194 -0
  35. package/src/agents/skills.ts +761 -0
  36. package/src/api/background-work.ts +197 -0
  37. package/src/api/capability-ceiling.ts +17 -0
  38. package/src/api/control-channel.ts +4 -0
  39. package/src/api/delegation.ts +119 -0
  40. package/src/api/external-runs.ts +129 -0
  41. package/src/api/intercom-bridge.ts +3 -0
  42. package/src/api/pi-args.ts +5 -0
  43. package/src/api/preflight.ts +403 -0
  44. package/src/api/shared-types.ts +19 -0
  45. package/src/extension/config.ts +76 -0
  46. package/src/extension/control-notices.ts +58 -0
  47. package/src/extension/doctor.ts +230 -0
  48. package/src/extension/fanout-child.ts +201 -0
  49. package/src/extension/index.ts +805 -0
  50. package/src/extension/public-execution.ts +71 -0
  51. package/src/extension/rpc.ts +653 -0
  52. package/src/extension/schemas.ts +375 -0
  53. package/src/extension/steering-notices.ts +35 -0
  54. package/src/extension/tool-description.ts +164 -0
  55. package/src/inspectors/herdr/actions.ts +229 -0
  56. package/src/inspectors/herdr/client.ts +130 -0
  57. package/src/inspectors/herdr/inspector-runner.ts +141 -0
  58. package/src/inspectors/herdr/project-panes.ts +154 -0
  59. package/src/integrations/herdr-status.ts +330 -0
  60. package/src/intercom/intercom-bridge.ts +187 -0
  61. package/src/intercom/native-supervisor-channel.ts +715 -0
  62. package/src/intercom/result-intercom.ts +421 -0
  63. package/src/missions/actions.ts +410 -0
  64. package/src/missions/goal-driver.ts +162 -0
  65. package/src/missions/lifecycle.ts +346 -0
  66. package/src/missions/store.ts +507 -0
  67. package/src/missions/types.ts +157 -0
  68. package/src/missions/workflow-state.ts +250 -0
  69. package/src/policy/authority.ts +46 -0
  70. package/src/profiles/profiles.ts +661 -0
  71. package/src/runs/background/async-execution.ts +1574 -0
  72. package/src/runs/background/async-job-tracker.ts +511 -0
  73. package/src/runs/background/async-resume.ts +539 -0
  74. package/src/runs/background/async-status.ts +542 -0
  75. package/src/runs/background/auto-drain.ts +67 -0
  76. package/src/runs/background/chain-append.ts +328 -0
  77. package/src/runs/background/chain-root-attachment.ts +199 -0
  78. package/src/runs/background/completion-batcher.ts +168 -0
  79. package/src/runs/background/completion-dedupe.ts +54 -0
  80. package/src/runs/background/control-channel.ts +692 -0
  81. package/src/runs/background/fleet-view.ts +540 -0
  82. package/src/runs/background/notify.ts +332 -0
  83. package/src/runs/background/parallel-groups.ts +45 -0
  84. package/src/runs/background/process-terminal.ts +280 -0
  85. package/src/runs/background/result-watcher.ts +414 -0
  86. package/src/runs/background/retained-children.ts +68 -0
  87. package/src/runs/background/run-id-resolver.ts +167 -0
  88. package/src/runs/background/run-status.ts +504 -0
  89. package/src/runs/background/scheduled-runs.ts +753 -0
  90. package/src/runs/background/stale-run-reconciler.ts +396 -0
  91. package/src/runs/background/steering.ts +239 -0
  92. package/src/runs/background/subagent-runner.ts +4718 -0
  93. package/src/runs/background/subagent-wait.ts +661 -0
  94. package/src/runs/background/top-level-async.ts +14 -0
  95. package/src/runs/background/wait-completions.ts +112 -0
  96. package/src/runs/background/wait-config.ts +36 -0
  97. package/src/runs/background/wait-subscriptions.ts +253 -0
  98. package/src/runs/background/wait-tool.ts +34 -0
  99. package/src/runs/foreground/async-steering-action.ts +256 -0
  100. package/src/runs/foreground/async-stop-action.ts +65 -0
  101. package/src/runs/foreground/chain-clarify.ts +1354 -0
  102. package/src/runs/foreground/chain-execution.ts +1527 -0
  103. package/src/runs/foreground/execution.ts +1868 -0
  104. package/src/runs/foreground/foreground-control.ts +132 -0
  105. package/src/runs/foreground/subagent-executor.ts +5532 -0
  106. package/src/runs/shared/acceptance.ts +1365 -0
  107. package/src/runs/shared/agent-contract.ts +38 -0
  108. package/src/runs/shared/capability-ceiling.ts +209 -0
  109. package/src/runs/shared/chain-outputs.ts +118 -0
  110. package/src/runs/shared/child-protocol.ts +401 -0
  111. package/src/runs/shared/completion-guard.ts +95 -0
  112. package/src/runs/shared/context-mode.ts +44 -0
  113. package/src/runs/shared/dynamic-fanout.ts +297 -0
  114. package/src/runs/shared/external-cli-runner.ts +130 -0
  115. package/src/runs/shared/long-running-guard.ts +220 -0
  116. package/src/runs/shared/mcp-direct-tool-allowlist.ts +406 -0
  117. package/src/runs/shared/model-fallback.ts +336 -0
  118. package/src/runs/shared/model-scope.ts +128 -0
  119. package/src/runs/shared/nested-events.ts +1076 -0
  120. package/src/runs/shared/nested-path.ts +52 -0
  121. package/src/runs/shared/nested-render.ts +123 -0
  122. package/src/runs/shared/parallel-handoff.ts +238 -0
  123. package/src/runs/shared/parallel-utils.ts +256 -0
  124. package/src/runs/shared/permissions.ts +95 -0
  125. package/src/runs/shared/pi-args.ts +808 -0
  126. package/src/runs/shared/pi-spawn.ts +163 -0
  127. package/src/runs/shared/process-signal.ts +19 -0
  128. package/src/runs/shared/run-history.ts +181 -0
  129. package/src/runs/shared/runtime-acknowledged-extensions.ts +71 -0
  130. package/src/runs/shared/session-lease.ts +299 -0
  131. package/src/runs/shared/single-output.ts +235 -0
  132. package/src/runs/shared/spawn-budget.ts +128 -0
  133. package/src/runs/shared/structured-output.ts +182 -0
  134. package/src/runs/shared/subagent-control.ts +231 -0
  135. package/src/runs/shared/subagent-prompt-runtime.ts +588 -0
  136. package/src/runs/shared/subagent-startup-retry.ts +104 -0
  137. package/src/runs/shared/task-intent.ts +181 -0
  138. package/src/runs/shared/tool-availability.ts +83 -0
  139. package/src/runs/shared/tool-budget.ts +80 -0
  140. package/src/runs/shared/turn-budget.ts +98 -0
  141. package/src/runs/shared/usage-budget.ts +65 -0
  142. package/src/runs/shared/workflow-graph.ts +231 -0
  143. package/src/runs/shared/worktree.ts +759 -0
  144. package/src/shared/accessible-dir.ts +47 -0
  145. package/src/shared/artifacts.ts +285 -0
  146. package/src/shared/atomic-json.ts +61 -0
  147. package/src/shared/child-transcript.ts +264 -0
  148. package/src/shared/file-coalescer.ts +40 -0
  149. package/src/shared/file-system-retry.ts +47 -0
  150. package/src/shared/fork-context.ts +213 -0
  151. package/src/shared/formatters.ts +133 -0
  152. package/src/shared/jsonl-writer.ts +81 -0
  153. package/src/shared/launch-contract.ts +124 -0
  154. package/src/shared/model-info.ts +81 -0
  155. package/src/shared/post-exit-stdio-guard.ts +85 -0
  156. package/src/shared/session-identity.ts +10 -0
  157. package/src/shared/session-tokens.ts +44 -0
  158. package/src/shared/settings.ts +501 -0
  159. package/src/shared/status-format.ts +55 -0
  160. package/src/shared/types.ts +2069 -0
  161. package/src/shared/utils.ts +613 -0
  162. package/src/slash/delegation-adapters.ts +434 -0
  163. package/src/slash/delegation-json.ts +108 -0
  164. package/src/slash/delegation-request.ts +166 -0
  165. package/src/slash/prompt-template-bridge.ts +383 -0
  166. package/src/slash/prompt-workflows.ts +300 -0
  167. package/src/slash/selector.ts +147 -0
  168. package/src/slash/slash-bridge.ts +192 -0
  169. package/src/slash/slash-commands.ts +994 -0
  170. package/src/slash/slash-live-state.ts +296 -0
  171. package/src/slash/subagents-admin.ts +432 -0
  172. package/src/tui/fleet-status.ts +564 -0
  173. package/src/tui/fleet-transcript.ts +577 -0
  174. package/src/tui/fleet.ts +879 -0
  175. package/src/tui/render-helpers.ts +80 -0
  176. package/src/tui/render.ts +2029 -0
  177. package/src/types/pi-runtime-compat.d.ts +8 -0
  178. package/src/watchdog/change-signature.ts +220 -0
  179. package/src/watchdog/child-status.ts +205 -0
  180. package/src/watchdog/emission-guard.ts +123 -0
  181. package/src/watchdog/lsp-diagnostics.ts +537 -0
  182. package/src/watchdog/model-selection.ts +167 -0
  183. package/src/watchdog/permission-arbiter.ts +145 -0
  184. package/src/watchdog/register-child.ts +117 -0
  185. package/src/watchdog/register-main.ts +440 -0
  186. package/src/watchdog/render.ts +54 -0
  187. package/src/watchdog/review.ts +302 -0
  188. package/src/watchdog/runtime.ts +868 -0
  189. package/src/watchdog/scope.ts +62 -0
  190. package/src/watchdog/settings.ts +568 -0
  191. package/src/watchdog/tool-actions.ts +155 -0
  192. package/src/watchdog/turn-delta.ts +161 -0
  193. package/src/watchdog/types.ts +198 -0
  194. package/src/watchdog/warning-format.ts +73 -0
  195. package/src/workflows/chat-progress.ts +140 -0
  196. package/src/workflows/scripted-workflow.ts +506 -0
@@ -0,0 +1,62 @@
1
+ export const WATCHDOG_AUTO_FOLLOW_PROMPT_MARKER = Symbol("subagent-watchdog-auto-follow-prompt");
2
+
3
+ const MAX_SCOPE_ENTRIES = 8;
4
+ const MAX_SCOPE_ENTRY_CHARS = 2_000;
5
+ const MAX_SCOPE_TOTAL_CHARS = 16_000;
6
+
7
+ export interface WatchdogScopeEntry {
8
+ prompt: string;
9
+ createdAt: string;
10
+ }
11
+
12
+ export class WatchdogScopeArtifact {
13
+ private entries: WatchdogScopeEntry[] = [];
14
+
15
+ addPrompt(prompt: string, options: { createdAt?: string } = {}): void {
16
+ const normalized = prompt.trim();
17
+ if (!normalized) return;
18
+ this.entries.push({
19
+ prompt: normalized.length > MAX_SCOPE_ENTRY_CHARS ? normalized.slice(0, MAX_SCOPE_ENTRY_CHARS) : normalized,
20
+ createdAt: options.createdAt ?? new Date().toISOString(),
21
+ });
22
+ this.trim();
23
+ }
24
+
25
+ reset(): void {
26
+ this.entries = [];
27
+ }
28
+
29
+ snapshot(): WatchdogScopeEntry[] {
30
+ return this.entries.map((entry) => ({ ...entry }));
31
+ }
32
+
33
+ render(): string {
34
+ if (!this.entries.length) return "";
35
+ return [
36
+ "Current scope:",
37
+ "The following real user prompts are the current scope record, newest last. Newer prompts supersede and mutate older prompts: they may add, modify, or remove requirements. Flag work that serves no current scope item as category 'scope-drift'.",
38
+ ...this.entries.map((entry, index) => [
39
+ `Scope prompt ${index + 1} (${entry.createdAt}):`,
40
+ entry.prompt,
41
+ ].join("\n")),
42
+ ].join("\n\n");
43
+ }
44
+
45
+ private trim(): void {
46
+ while (this.entries.length > MAX_SCOPE_ENTRIES) this.entries.shift();
47
+ let total = this.entries.reduce((sum, entry) => sum + entry.prompt.length, 0);
48
+ while (this.entries.length > 1 && total > MAX_SCOPE_TOTAL_CHARS) {
49
+ const removed = this.entries.shift();
50
+ if (removed) total -= removed.prompt.length;
51
+ }
52
+ }
53
+ }
54
+
55
+ export function isWatchdogAutoFollowPromptEvent(event: unknown): boolean {
56
+ return Boolean(event && typeof event === "object" && (event as { [WATCHDOG_AUTO_FOLLOW_PROMPT_MARKER]?: unknown })[WATCHDOG_AUTO_FOLLOW_PROMPT_MARKER]);
57
+ }
58
+
59
+ export function markWatchdogAutoFollowPromptEvent<T extends object>(event: T): T {
60
+ Object.defineProperty(event, WATCHDOG_AUTO_FOLLOW_PROMPT_MARKER, { value: true });
61
+ return event;
62
+ }
@@ -0,0 +1,568 @@
1
+ import * as fs from "node:fs";
2
+ import * as path from "node:path";
3
+ import { THINKING_LEVELS, type ThinkingLevel } from "../shared/model-info.ts";
4
+ import { getAgentDir, getProjectConfigDir } from "../shared/utils.ts";
5
+ import {
6
+ WATCHDOG_DELIVERY_MODES,
7
+ WATCHDOG_LATE_WARNING_POLICIES,
8
+ WATCHDOG_WARNING_SEVERITIES,
9
+ type ResolvedWatchdogConfig,
10
+ type WatchdogAsyncCompletionConfig,
11
+ type WatchdogAutoFollowConfig,
12
+ type WatchdogChildOverrideConfig,
13
+ type WatchdogChildrenConfig,
14
+ type WatchdogDeliveryMode,
15
+ type WatchdogEndpointConfig,
16
+ type WatchdogCadenceConfig,
17
+ type WatchdogGuidanceConfig,
18
+ type WatchdogLateWarningPolicy,
19
+ type WatchdogScopeConfig,
20
+ type WatchdogLspConfig,
21
+ type WatchdogSettingsError,
22
+ type WatchdogSettingsResult,
23
+ type WatchdogSettingsSource,
24
+ type WatchdogSeverity,
25
+ type WatchdogSyncBacklog,
26
+ } from "./types.ts";
27
+
28
+ type WatchdogAutoFollowPatch = Partial<WatchdogAutoFollowConfig>;
29
+ type WatchdogGuidancePatch = Partial<WatchdogGuidanceConfig>;
30
+ type WatchdogScopePatch = Partial<WatchdogScopeConfig>;
31
+ type WatchdogCadencePatch = Partial<WatchdogCadenceConfig>;
32
+ type WatchdogEndpointPatch = Partial<WatchdogEndpointConfig>;
33
+ type WatchdogChildOverridePatch = Partial<WatchdogChildOverrideConfig>;
34
+ type WatchdogChildrenPatch = Partial<Omit<WatchdogChildrenConfig, "autoFollow" | "overrides">> & {
35
+ autoFollow?: WatchdogAutoFollowPatch;
36
+ overrides?: Record<string, WatchdogChildOverridePatch>;
37
+ };
38
+ type WatchdogAsyncCompletionPatch = Partial<WatchdogAsyncCompletionConfig>;
39
+ type WatchdogLspPatch = Partial<WatchdogLspConfig>;
40
+
41
+ export type WatchdogSettingsWriteScope = "user" | "project";
42
+ export type WatchdogModelSettingsTarget =
43
+ | { kind: "main" }
44
+ | { kind: "children" }
45
+ | { kind: "child"; agent: string };
46
+
47
+ export interface WatchdogModelSettingsWrite {
48
+ scope: WatchdogSettingsWriteScope;
49
+ cwd?: string;
50
+ target: WatchdogModelSettingsTarget;
51
+ model?: string | null;
52
+ thinking?: ThinkingLevel | false | null;
53
+ }
54
+
55
+ type WatchdogConfigPatch = Partial<Omit<ResolvedWatchdogConfig, "guidance" | "autoFollow" | "scope" | "cadence" | "main" | "children" | "asyncCompletion" | "lsp">> & {
56
+ guidance?: WatchdogGuidancePatch;
57
+ autoFollow?: WatchdogAutoFollowPatch;
58
+ scope?: WatchdogScopePatch;
59
+ cadence?: WatchdogCadencePatch;
60
+ main?: WatchdogEndpointPatch;
61
+ children?: WatchdogChildrenPatch;
62
+ asyncCompletion?: WatchdogAsyncCompletionPatch;
63
+ lsp?: WatchdogLspPatch;
64
+ };
65
+
66
+ interface ParseMeta {
67
+ scope: "user" | "project" | "session";
68
+ path?: string;
69
+ }
70
+
71
+ export const DEFAULT_WATCHDOG_CONFIG: ResolvedWatchdogConfig = {
72
+ enabled: false,
73
+ delivery: "held",
74
+ showDuringRun: false,
75
+ syncBacklog: "off",
76
+ agentEndTimeoutMs: 30_000,
77
+ lateWarningPolicy: "show-stale-no-autofollow",
78
+ severityThreshold: "concern",
79
+ maxWarnings: null,
80
+ guidance: {
81
+ watchdogMd: true,
82
+ systemPromptPath: null,
83
+ },
84
+ autoFollow: {
85
+ blockers: true,
86
+ maxAttempts: 3,
87
+ stalemateRepeats: 3,
88
+ },
89
+ scope: {
90
+ enabled: true,
91
+ },
92
+ cadence: {
93
+ everyNTools: null,
94
+ },
95
+ main: {
96
+ enabled: false,
97
+ },
98
+ children: {
99
+ enabled: false,
100
+ watchdogTailTimeoutMs: 120_000,
101
+ autoFollow: {
102
+ blockers: true,
103
+ maxAttempts: 3,
104
+ stalemateRepeats: 3,
105
+ },
106
+ overrides: {},
107
+ },
108
+ asyncCompletion: {
109
+ enabled: false,
110
+ autoFollowBlockers: false,
111
+ },
112
+ lsp: {
113
+ enabled: true,
114
+ timeoutMs: 3_000,
115
+ maxFiles: 20,
116
+ maxDiagnostics: 50,
117
+ },
118
+ compactAtPercent: 80,
119
+ reviewRetryDelayMs: 1_000,
120
+ maxReviewFailures: 3,
121
+ };
122
+
123
+ const WATCHDOG_FIELDS = new Set([
124
+ "enabled",
125
+ "delivery",
126
+ "showDuringRun",
127
+ "syncBacklog",
128
+ "agentEndTimeoutMs",
129
+ "lateWarningPolicy",
130
+ "severityThreshold",
131
+ "maxWarnings",
132
+ "guidance",
133
+ "autoFollow",
134
+ "scope",
135
+ "cadence",
136
+ "main",
137
+ "children",
138
+ "asyncCompletion",
139
+ "lsp",
140
+ "compactAtPercent",
141
+ "reviewRetryDelayMs",
142
+ "maxReviewFailures",
143
+ ]);
144
+ const GUIDANCE_FIELDS = new Set(["watchdogMd", "systemPromptPath"]);
145
+ const AUTO_FOLLOW_FIELDS = new Set(["blockers", "maxAttempts", "stalemateRepeats"]);
146
+ const SCOPE_FIELDS = new Set(["enabled"]);
147
+ const CADENCE_FIELDS = new Set(["everyNTools"]);
148
+ const ENDPOINT_FIELDS = new Set(["enabled", "model", "thinking"]);
149
+ const CHILDREN_FIELDS = new Set(["enabled", "model", "thinking", "watchdogTailTimeoutMs", "autoFollow", "overrides"]);
150
+ const CHILD_OVERRIDE_FIELDS = new Set(["enabled", "model", "thinking"]);
151
+ const ASYNC_COMPLETION_FIELDS = new Set(["enabled", "autoFollowBlockers"]);
152
+ const LSP_FIELDS = new Set(["enabled", "timeoutMs", "maxFiles", "maxDiagnostics"]);
153
+
154
+ function cloneDefaultConfig(): ResolvedWatchdogConfig {
155
+ return {
156
+ ...DEFAULT_WATCHDOG_CONFIG,
157
+ guidance: { ...DEFAULT_WATCHDOG_CONFIG.guidance },
158
+ autoFollow: { ...DEFAULT_WATCHDOG_CONFIG.autoFollow },
159
+ scope: { ...DEFAULT_WATCHDOG_CONFIG.scope },
160
+ cadence: { ...DEFAULT_WATCHDOG_CONFIG.cadence },
161
+ main: { ...DEFAULT_WATCHDOG_CONFIG.main },
162
+ children: {
163
+ ...DEFAULT_WATCHDOG_CONFIG.children,
164
+ autoFollow: { ...DEFAULT_WATCHDOG_CONFIG.children.autoFollow },
165
+ overrides: {},
166
+ },
167
+ asyncCompletion: { ...DEFAULT_WATCHDOG_CONFIG.asyncCompletion },
168
+ lsp: { ...DEFAULT_WATCHDOG_CONFIG.lsp },
169
+ };
170
+ }
171
+
172
+ function isPlainObject(value: unknown): value is Record<string, unknown> {
173
+ return typeof value === "object" && value !== null && !Array.isArray(value);
174
+ }
175
+
176
+ function sourceName(meta: ParseMeta): string {
177
+ return meta.path ? `'${meta.path}'` : "session override";
178
+ }
179
+
180
+ function invalid(meta: ParseMeta, field: string, expected: string): Error {
181
+ return new Error(`Watchdog settings in ${sourceName(meta)} have invalid '${field}'; expected ${expected}.`);
182
+ }
183
+
184
+ function unknown(meta: ParseMeta, field: string): Error {
185
+ return new Error(`Watchdog settings in ${sourceName(meta)} have unknown field '${field}'.`);
186
+ }
187
+
188
+ function assertKnownFields(input: Record<string, unknown>, allowed: Set<string>, fieldPrefix: string, meta: ParseMeta): void {
189
+ for (const key of Object.keys(input)) {
190
+ if (!allowed.has(key)) throw unknown(meta, `${fieldPrefix}.${key}`);
191
+ }
192
+ }
193
+
194
+ function parseObject(value: unknown, field: string, meta: ParseMeta): Record<string, unknown> {
195
+ if (isPlainObject(value)) return value;
196
+ throw invalid(meta, field, "an object");
197
+ }
198
+
199
+ function parseBoolean(value: unknown, field: string, meta: ParseMeta): boolean {
200
+ if (typeof value === "boolean") return value;
201
+ throw invalid(meta, field, "a boolean");
202
+ }
203
+
204
+ function parseNonEmptyString(value: unknown, field: string, meta: ParseMeta): string {
205
+ if (typeof value === "string" && value.trim()) return value.trim();
206
+ throw invalid(meta, field, "a non-empty string");
207
+ }
208
+
209
+ function parseThinking(value: unknown, field: string, meta: ParseMeta): ThinkingLevel | false {
210
+ if (value === false) return false;
211
+ if (typeof value === "string" && (THINKING_LEVELS as readonly string[]).includes(value)) return value as ThinkingLevel;
212
+ throw invalid(meta, field, `${THINKING_LEVELS.map((level) => `'${level}'`).join(" or ")} or false`);
213
+ }
214
+
215
+ function parseInteger(value: unknown, field: string, meta: ParseMeta, expected: string, check: (value: number) => boolean): number {
216
+ if (typeof value === "number" && Number.isInteger(value) && check(value)) return value;
217
+ throw invalid(meta, field, expected);
218
+ }
219
+
220
+ function parseNullableInteger(value: unknown, field: string, meta: ParseMeta, expected: string, check: (value: number) => boolean): number | null {
221
+ if (value === null) return null;
222
+ return parseInteger(value, field, meta, expected, check);
223
+ }
224
+
225
+ function parseEnum<T extends string>(value: unknown, field: string, meta: ParseMeta, values: readonly T[]): T {
226
+ if (typeof value === "string" && (values as readonly string[]).includes(value)) return value as T;
227
+ throw invalid(meta, field, values.map((item) => `'${item}'`).join(" or "));
228
+ }
229
+
230
+ function parseSyncBacklog(value: unknown, field: string, meta: ParseMeta): WatchdogSyncBacklog {
231
+ if (value === "off") return "off";
232
+ return parseInteger(value, field, meta, "'off' or a positive integer", (candidate) => candidate >= 1);
233
+ }
234
+
235
+ function parseGuidancePatch(value: unknown, field: string, meta: ParseMeta): WatchdogGuidancePatch {
236
+ const input = parseObject(value, field, meta);
237
+ assertKnownFields(input, GUIDANCE_FIELDS, field, meta);
238
+ const patch: WatchdogGuidancePatch = {};
239
+ if ("watchdogMd" in input) patch.watchdogMd = parseBoolean(input.watchdogMd, `${field}.watchdogMd`, meta);
240
+ if ("systemPromptPath" in input) {
241
+ patch.systemPromptPath = input.systemPromptPath === null
242
+ ? null
243
+ : parseNonEmptyString(input.systemPromptPath, `${field}.systemPromptPath`, meta);
244
+ }
245
+ return patch;
246
+ }
247
+
248
+ function parseAutoFollowPatch(value: unknown, field: string, meta: ParseMeta): WatchdogAutoFollowPatch {
249
+ const input = parseObject(value, field, meta);
250
+ assertKnownFields(input, AUTO_FOLLOW_FIELDS, field, meta);
251
+ const patch: WatchdogAutoFollowPatch = {};
252
+ if ("blockers" in input) patch.blockers = parseBoolean(input.blockers, `${field}.blockers`, meta);
253
+ if ("maxAttempts" in input) {
254
+ patch.maxAttempts = parseNullableInteger(input.maxAttempts, `${field}.maxAttempts`, meta, "null or a positive integer", (candidate) => candidate >= 1);
255
+ }
256
+ if ("stalemateRepeats" in input) {
257
+ patch.stalemateRepeats = parseInteger(input.stalemateRepeats, `${field}.stalemateRepeats`, meta, "a positive integer", (candidate) => candidate >= 1);
258
+ }
259
+ return patch;
260
+ }
261
+
262
+ function parseScopePatch(value: unknown, field: string, meta: ParseMeta): WatchdogScopePatch {
263
+ const input = parseObject(value, field, meta);
264
+ assertKnownFields(input, SCOPE_FIELDS, field, meta);
265
+ const patch: WatchdogScopePatch = {};
266
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
267
+ return patch;
268
+ }
269
+
270
+ function parseCadencePatch(value: unknown, field: string, meta: ParseMeta): WatchdogCadencePatch {
271
+ const input = parseObject(value, field, meta);
272
+ assertKnownFields(input, CADENCE_FIELDS, field, meta);
273
+ const patch: WatchdogCadencePatch = {};
274
+ if ("everyNTools" in input) {
275
+ patch.everyNTools = input.everyNTools === null
276
+ ? null
277
+ : parseInteger(input.everyNTools, `${field}.everyNTools`, meta, "null or an integer >= 5", (candidate) => candidate >= 5);
278
+ }
279
+ return patch;
280
+ }
281
+
282
+ function parseEndpointPatch(value: unknown, field: string, meta: ParseMeta): WatchdogEndpointPatch {
283
+ const input = parseObject(value, field, meta);
284
+ assertKnownFields(input, ENDPOINT_FIELDS, field, meta);
285
+ const patch: WatchdogEndpointPatch = {};
286
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
287
+ if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
288
+ if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
289
+ return patch;
290
+ }
291
+
292
+ function parseChildOverridePatch(value: unknown, field: string, meta: ParseMeta): WatchdogChildOverridePatch {
293
+ const input = parseObject(value, field, meta);
294
+ assertKnownFields(input, CHILD_OVERRIDE_FIELDS, field, meta);
295
+ const patch: WatchdogChildOverridePatch = {};
296
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
297
+ if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
298
+ if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
299
+ return patch;
300
+ }
301
+
302
+ function parseChildrenPatch(value: unknown, field: string, meta: ParseMeta): WatchdogChildrenPatch {
303
+ const input = parseObject(value, field, meta);
304
+ assertKnownFields(input, CHILDREN_FIELDS, field, meta);
305
+ const patch: WatchdogChildrenPatch = {};
306
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
307
+ if ("model" in input) patch.model = parseNonEmptyString(input.model, `${field}.model`, meta);
308
+ if ("thinking" in input) patch.thinking = parseThinking(input.thinking, `${field}.thinking`, meta);
309
+ if ("watchdogTailTimeoutMs" in input) {
310
+ patch.watchdogTailTimeoutMs = parseInteger(input.watchdogTailTimeoutMs, `${field}.watchdogTailTimeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
311
+ }
312
+ if ("autoFollow" in input) patch.autoFollow = parseAutoFollowPatch(input.autoFollow, `${field}.autoFollow`, meta);
313
+ if ("overrides" in input) {
314
+ const overrides = parseObject(input.overrides, `${field}.overrides`, meta);
315
+ patch.overrides = {};
316
+ for (const [agent, override] of Object.entries(overrides)) {
317
+ if (!agent.trim()) throw invalid(meta, `${field}.overrides`, "agent names to be non-empty");
318
+ patch.overrides[agent] = parseChildOverridePatch(override, `${field}.overrides.${agent}`, meta);
319
+ }
320
+ }
321
+ return patch;
322
+ }
323
+
324
+ function parseAsyncCompletionPatch(value: unknown, field: string, meta: ParseMeta): WatchdogAsyncCompletionPatch {
325
+ const input = parseObject(value, field, meta);
326
+ assertKnownFields(input, ASYNC_COMPLETION_FIELDS, field, meta);
327
+ const patch: WatchdogAsyncCompletionPatch = {};
328
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
329
+ if ("autoFollowBlockers" in input) patch.autoFollowBlockers = parseBoolean(input.autoFollowBlockers, `${field}.autoFollowBlockers`, meta);
330
+ return patch;
331
+ }
332
+
333
+ function parseLspPatch(value: unknown, field: string, meta: ParseMeta): WatchdogLspPatch {
334
+ const input = parseObject(value, field, meta);
335
+ assertKnownFields(input, LSP_FIELDS, field, meta);
336
+ const patch: WatchdogLspPatch = {};
337
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
338
+ if ("timeoutMs" in input) patch.timeoutMs = parseInteger(input.timeoutMs, `${field}.timeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
339
+ if ("maxFiles" in input) patch.maxFiles = parseInteger(input.maxFiles, `${field}.maxFiles`, meta, "a positive integer", (candidate) => candidate >= 1);
340
+ if ("maxDiagnostics" in input) patch.maxDiagnostics = parseInteger(input.maxDiagnostics, `${field}.maxDiagnostics`, meta, "a non-negative integer", (candidate) => candidate >= 0);
341
+ return patch;
342
+ }
343
+
344
+ function parseWatchdogPatch(value: unknown, field: string, meta: ParseMeta): WatchdogConfigPatch {
345
+ const input = parseObject(value, field, meta);
346
+ assertKnownFields(input, WATCHDOG_FIELDS, field, meta);
347
+ const patch: WatchdogConfigPatch = {};
348
+ if ("enabled" in input) patch.enabled = parseBoolean(input.enabled, `${field}.enabled`, meta);
349
+ if ("delivery" in input) patch.delivery = parseEnum<WatchdogDeliveryMode>(input.delivery, `${field}.delivery`, meta, WATCHDOG_DELIVERY_MODES);
350
+ if ("showDuringRun" in input) patch.showDuringRun = parseBoolean(input.showDuringRun, `${field}.showDuringRun`, meta);
351
+ if ("syncBacklog" in input) patch.syncBacklog = parseSyncBacklog(input.syncBacklog, `${field}.syncBacklog`, meta);
352
+ if ("agentEndTimeoutMs" in input) {
353
+ patch.agentEndTimeoutMs = parseInteger(input.agentEndTimeoutMs, `${field}.agentEndTimeoutMs`, meta, "a positive integer", (candidate) => candidate >= 1);
354
+ }
355
+ if ("lateWarningPolicy" in input) {
356
+ patch.lateWarningPolicy = parseEnum<WatchdogLateWarningPolicy>(input.lateWarningPolicy, `${field}.lateWarningPolicy`, meta, WATCHDOG_LATE_WARNING_POLICIES);
357
+ }
358
+ if ("severityThreshold" in input) {
359
+ patch.severityThreshold = parseEnum<WatchdogSeverity>(input.severityThreshold, `${field}.severityThreshold`, meta, WATCHDOG_WARNING_SEVERITIES);
360
+ }
361
+ if ("maxWarnings" in input) {
362
+ patch.maxWarnings = parseNullableInteger(input.maxWarnings, `${field}.maxWarnings`, meta, "null or a non-negative integer", (candidate) => candidate >= 0);
363
+ }
364
+ if ("guidance" in input) patch.guidance = parseGuidancePatch(input.guidance, `${field}.guidance`, meta);
365
+ if ("autoFollow" in input) patch.autoFollow = parseAutoFollowPatch(input.autoFollow, `${field}.autoFollow`, meta);
366
+ if ("scope" in input) patch.scope = parseScopePatch(input.scope, `${field}.scope`, meta);
367
+ if ("cadence" in input) patch.cadence = parseCadencePatch(input.cadence, `${field}.cadence`, meta);
368
+ if ("main" in input) patch.main = parseEndpointPatch(input.main, `${field}.main`, meta);
369
+ if ("children" in input) patch.children = parseChildrenPatch(input.children, `${field}.children`, meta);
370
+ if ("asyncCompletion" in input) patch.asyncCompletion = parseAsyncCompletionPatch(input.asyncCompletion, `${field}.asyncCompletion`, meta);
371
+ if ("lsp" in input) patch.lsp = parseLspPatch(input.lsp, `${field}.lsp`, meta);
372
+ if ("compactAtPercent" in input) {
373
+ patch.compactAtPercent = parseInteger(input.compactAtPercent, `${field}.compactAtPercent`, meta, "an integer from 50 through 95", (candidate) => candidate >= 50 && candidate <= 95);
374
+ }
375
+ if ("reviewRetryDelayMs" in input) {
376
+ patch.reviewRetryDelayMs = parseInteger(input.reviewRetryDelayMs, `${field}.reviewRetryDelayMs`, meta, "a positive integer", (candidate) => candidate >= 1);
377
+ }
378
+ if ("maxReviewFailures" in input) {
379
+ patch.maxReviewFailures = parseInteger(input.maxReviewFailures, `${field}.maxReviewFailures`, meta, "a positive integer", (candidate) => candidate >= 1);
380
+ }
381
+ return patch;
382
+ }
383
+
384
+ function parseSettingsObject(settings: Record<string, unknown>, meta: ParseMeta): WatchdogConfigPatch {
385
+ if (!("subagents" in settings)) return {};
386
+ const subagents = parseObject(settings.subagents, "subagents", meta);
387
+ if (!("watchdog" in subagents)) return {};
388
+ return parseWatchdogPatch(subagents.watchdog, "subagents.watchdog", meta);
389
+ }
390
+
391
+ function readSettingsFileStrict(filePath: string): Record<string, unknown> {
392
+ if (!fs.existsSync(filePath)) return {};
393
+ let raw: string;
394
+ try {
395
+ raw = fs.readFileSync(filePath, "utf-8");
396
+ } catch (error) {
397
+ const message = error instanceof Error ? error.message : String(error);
398
+ throw new Error(`Failed to read settings file '${filePath}': ${message}`, { cause: error });
399
+ }
400
+
401
+ let parsed: unknown;
402
+ try {
403
+ parsed = JSON.parse(raw);
404
+ } catch (error) {
405
+ const message = error instanceof Error ? error.message : String(error);
406
+ throw new Error(`Failed to parse settings file '${filePath}': ${message}`, { cause: error });
407
+ }
408
+ if (!isPlainObject(parsed)) {
409
+ throw new Error(`Settings file '${filePath}' must contain a JSON object.`);
410
+ }
411
+ return parsed;
412
+ }
413
+
414
+ function isDirectory(dir: string): boolean {
415
+ try {
416
+ return fs.statSync(dir).isDirectory();
417
+ } catch {
418
+ return false;
419
+ }
420
+ }
421
+
422
+ function getUserSettingsPath(): string {
423
+ return path.join(getAgentDir(), "settings.json");
424
+ }
425
+
426
+ export function getWatchdogUserSettingsPath(): string {
427
+ return getUserSettingsPath();
428
+ }
429
+
430
+ function getProjectSettingsPath(cwd: string): string | undefined {
431
+ let currentDir = cwd;
432
+ while (true) {
433
+ if (isDirectory(getProjectConfigDir(currentDir)) || isDirectory(path.join(currentDir, ".agents"))) {
434
+ return path.join(getProjectConfigDir(currentDir), "settings.json");
435
+ }
436
+ const parentDir = path.dirname(currentDir);
437
+ if (parentDir === currentDir) return undefined;
438
+ currentDir = parentDir;
439
+ }
440
+ }
441
+
442
+ export function getWatchdogProjectSettingsPath(cwd: string): string {
443
+ return path.join(getProjectConfigDir(cwd), "settings.json");
444
+ }
445
+
446
+ function deepMerge<T extends Record<string, unknown>>(base: T, patch: Record<string, unknown>): T {
447
+ const next: Record<string, unknown> = { ...base };
448
+ for (const [key, value] of Object.entries(patch)) {
449
+ const current = next[key];
450
+ next[key] = isPlainObject(current) && isPlainObject(value) ? deepMerge(current, value) : value;
451
+ }
452
+ return next as T;
453
+ }
454
+
455
+ function resolvePatch(patch: WatchdogConfigPatch): ResolvedWatchdogConfig {
456
+ const config = deepMerge(cloneDefaultConfig() as unknown as Record<string, unknown>, patch as Record<string, unknown>) as unknown as ResolvedWatchdogConfig;
457
+ config.enabled = patch.enabled ?? DEFAULT_WATCHDOG_CONFIG.enabled;
458
+ config.main.enabled = patch.main?.enabled ?? config.enabled;
459
+ return config;
460
+ }
461
+
462
+ function parseSourceFile(filePath: string, scope: "user" | "project"): WatchdogConfigPatch {
463
+ return parseSettingsObject(readSettingsFileStrict(filePath), { scope, path: filePath });
464
+ }
465
+
466
+ function parseSessionOverride(value: Record<string, unknown>): WatchdogConfigPatch {
467
+ if ("subagents" in value) return parseSettingsObject(value, { scope: "session" });
468
+ return parseWatchdogPatch(value, "subagents.watchdog", { scope: "session" });
469
+ }
470
+
471
+ export function resolveWatchdogConfigStrict(cwd: string, options: { session?: Record<string, unknown> } = {}): ResolvedWatchdogConfig {
472
+ let patch: WatchdogConfigPatch = {};
473
+ patch = deepMerge(patch as Record<string, unknown>, parseSourceFile(getUserSettingsPath(), "user") as Record<string, unknown>) as WatchdogConfigPatch;
474
+ const projectSettingsPath = getProjectSettingsPath(cwd);
475
+ if (projectSettingsPath) {
476
+ patch = deepMerge(patch as Record<string, unknown>, parseSourceFile(projectSettingsPath, "project") as Record<string, unknown>) as WatchdogConfigPatch;
477
+ }
478
+ if (options.session) {
479
+ patch = deepMerge(patch as Record<string, unknown>, parseSessionOverride(options.session) as Record<string, unknown>) as WatchdogConfigPatch;
480
+ }
481
+ return resolvePatch(patch);
482
+ }
483
+
484
+ function ensureObjectField(parent: Record<string, unknown>, key: string, field: string, meta: ParseMeta): Record<string, unknown> {
485
+ if (!(key in parent)) parent[key] = {};
486
+ if (!isPlainObject(parent[key])) throw invalid(meta, field, "an object");
487
+ return parent[key];
488
+ }
489
+
490
+ function ensureWatchdogSettings(settings: Record<string, unknown>, meta: ParseMeta): Record<string, unknown> {
491
+ const subagents = ensureObjectField(settings, "subagents", "subagents", meta);
492
+ return ensureObjectField(subagents, "watchdog", "subagents.watchdog", meta);
493
+ }
494
+
495
+ function settingsPathForWrite(scope: WatchdogSettingsWriteScope, cwd: string | undefined): string {
496
+ return scope === "user" ? getUserSettingsPath() : getWatchdogProjectSettingsPath(cwd ?? process.cwd());
497
+ }
498
+
499
+ function targetSettingsObject(watchdog: Record<string, unknown>, target: WatchdogModelSettingsTarget, meta: ParseMeta): Record<string, unknown> {
500
+ if (target.kind === "main") return ensureObjectField(watchdog, "main", "subagents.watchdog.main", meta);
501
+ const children = ensureObjectField(watchdog, "children", "subagents.watchdog.children", meta);
502
+ if (target.kind === "children") return children;
503
+ if (!target.agent.trim()) throw invalid(meta, "subagents.watchdog.children.overrides.<agent>", "a non-empty agent name");
504
+ const overrides = ensureObjectField(children, "overrides", "subagents.watchdog.children.overrides", meta);
505
+ return ensureObjectField(overrides, target.agent.trim(), `subagents.watchdog.children.overrides.${target.agent.trim()}`, meta);
506
+ }
507
+
508
+ function writeSettingsFile(settingsPath: string, settings: Record<string, unknown>): string {
509
+ fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
510
+ fs.writeFileSync(settingsPath, `${JSON.stringify(settings, null, 2)}\n`, "utf-8");
511
+ return settingsPath;
512
+ }
513
+
514
+ export function writeUserWatchdogEnabled(enabled: boolean): string {
515
+ const settingsPath = getUserSettingsPath();
516
+ const meta: ParseMeta = { scope: "user", path: settingsPath };
517
+ const settings = readSettingsFileStrict(settingsPath);
518
+ const watchdog = ensureWatchdogSettings(settings, meta);
519
+ watchdog.enabled = enabled;
520
+ targetSettingsObject(watchdog, { kind: "main" }, meta).enabled = enabled;
521
+ return writeSettingsFile(settingsPath, settings);
522
+ }
523
+
524
+ export function writeWatchdogModelSettings(input: WatchdogModelSettingsWrite): string {
525
+ const settingsPath = settingsPathForWrite(input.scope, input.cwd);
526
+ const meta: ParseMeta = { scope: input.scope, path: settingsPath };
527
+ const settings = readSettingsFileStrict(settingsPath);
528
+ const watchdog = ensureWatchdogSettings(settings, meta);
529
+ const target = targetSettingsObject(watchdog, input.target, meta);
530
+ if (input.model === null) delete target.model;
531
+ else if (input.model !== undefined) target.model = input.model;
532
+ if (input.thinking === null) delete target.thinking;
533
+ else if (input.thinking !== undefined) target.thinking = input.thinking;
534
+ return writeSettingsFile(settingsPath, settings);
535
+ }
536
+
537
+ export function resolveWatchdogConfig(cwd: string, options: { session?: Record<string, unknown> } = {}): WatchdogSettingsResult {
538
+ const sources: WatchdogSettingsSource[] = [];
539
+ const errors: WatchdogSettingsError[] = [];
540
+ let patch: WatchdogConfigPatch = {};
541
+ const sourceSpecs: Array<{ scope: "user" | "project"; path: string | undefined }> = [
542
+ { scope: "user", path: getUserSettingsPath() },
543
+ { scope: "project", path: getProjectSettingsPath(cwd) },
544
+ ];
545
+ for (const source of sourceSpecs) {
546
+ if (!source.path) continue;
547
+ sources.push({ scope: source.scope, path: source.path, exists: fs.existsSync(source.path) });
548
+ try {
549
+ patch = deepMerge(patch as Record<string, unknown>, parseSourceFile(source.path, source.scope) as Record<string, unknown>) as WatchdogConfigPatch;
550
+ } catch (error) {
551
+ errors.push({ scope: source.scope, path: source.path, message: error instanceof Error ? error.message : String(error) });
552
+ }
553
+ }
554
+ if (options.session) {
555
+ sources.push({ scope: "session", exists: true });
556
+ try {
557
+ patch = deepMerge(patch as Record<string, unknown>, parseSessionOverride(options.session) as Record<string, unknown>) as WatchdogConfigPatch;
558
+ } catch (error) {
559
+ errors.push({ scope: "session", message: error instanceof Error ? error.message : String(error) });
560
+ }
561
+ }
562
+ return {
563
+ ok: errors.length === 0,
564
+ config: errors.length === 0 ? resolvePatch(patch) : cloneDefaultConfig(),
565
+ errors,
566
+ sources,
567
+ };
568
+ }