@hansjm10/volt-coding-agent 0.0.0-bootstrap.0 → 0.1.0

package/dist/core/subagents/delegation-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-scope.d.ts","sourceRoot":"","sources":["../../../src/core/subagents/delegation-scope.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,+BAA+B;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,qBAAqB,EAAE,MAAM,CAAC;IAC9B,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,6BAA6B;IAC7C,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,IAAI,GAAG,IAAI,CAAC;IACpD,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,IAAI,IAAI,CAAC;CACjB;AAED,MAAM,WAAW,8BAA8B;IAC9C,MAAM,CAAC,EAAE,WAAW,CAAC;CACrB;AAED,8FAA8F;AAC9F,qBAAa,uBAAuB;IACnC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAE7B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAChE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA0B;IACzD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA2B;IAC3D,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,qBAAqB,CAAK;IAClC,OAAO,CAAC,eAAe,CAAK;IAC5B,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,QAAQ,CAAS;IAEzB,YAAY,OAAO,GAAE,8BAAmC,EAavD;IAED,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,6BAA6B,CA2CvE;IAED,KAAK,CAAC,MAAM,GAAE,OAAkD,GAAG,IAAI,CAWtE;IAED,UAAU,IAAI,IAAI,CAGjB;IAED,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,CAIjD;IAED,QAAQ,IAAI,+BAA+B,CAa1C;IAED,OAAO,IAAI,IAAI,CAUd;IAED,OAAO,CAAC,WAAW;CAGnB","sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nexport interface SubagentDelegationScopeSnapshot {\n\tid: string;\n\tstartedAt: number;\n\tstartsUsed: number;\n\tactiveDescendants: number;\n\tpeakActiveDescendants: number;\n\tmaxDepthReached: number;\n\tturnsUsed: number;\n\ttokensUsed: number;\n\tcostUsd: number;\n\taborted: boolean;\n}\n\nexport interface SubagentDelegationReservation {\n\tcommit(subagentId: string, abort: () => void): void;\n\trelease(): void;\n\trollback(): void;\n}\n\nexport interface SubagentDelegationScopeOptions {\n\tsignal?: AbortSignal;\n}\n\n/** Shared, root-owned accounting and cancellation scope for one recursive delegation tree. */\nexport class SubagentDelegationScope {\n\treadonly id: string;\n\treadonly startedAt: number;\n\treadonly signal: AbortSignal;\n\n\tprivate readonly controller = new AbortController();\n\tprivate readonly activeAborters = new Map<string, () => void>();\n\tprivate readonly externalSignal: AbortSignal | undefined;\n\tprivate readonly onExternalAbort: (() => void) | undefined;\n\tprivate startsUsed = 0;\n\tprivate activeDescendants = 0;\n\tprivate peakActiveDescendants = 0;\n\tprivate maxDepthReached = 0;\n\tprivate turnsUsed = 0;\n\tprivate tokensUsed = 0;\n\tprivate costUsd = 0;\n\tprivate disposed = false;\n\n\tconstructor(options: SubagentDelegationScopeOptions = {}) {\n\t\tthis.id = `sat_${randomUUID()}`;\n\t\tthis.startedAt = Date.now();\n\t\tthis.signal = this.controller.signal;\n\t\tthis.externalSignal = options.signal;\n\t\tthis.onExternalAbort = options.signal\n\t\t\t? () => this.abort(options.signal?.reason ?? new Error(\"Operation aborted\"))\n\t\t\t: undefined;\n\t\tif (this.externalSignal?.aborted) {\n\t\t\tthis.abort(this.externalSignal.reason ?? new Error(\"Operation aborted\"));\n\t\t} else if (this.externalSignal && this.onExternalAbort) {\n\t\t\tthis.externalSignal.addEventListener(\"abort\", this.onExternalAbort, { once: true });\n\t\t}\n\t}\n\n\treserve(agentName: string, depth: number): SubagentDelegationReservation {\n\t\tif (this.disposed) {\n\t\t\tthrow new Error(`Cannot delegate to \"${agentName}\": delegation scope ${this.id} is disposed.`);\n\t\t}\n\t\tif (this.signal.aborted) {\n\t\t\tthrow this.abortReason();\n\t\t}\n\n\t\tthis.startsUsed += 1;\n\t\tthis.activeDescendants += 1;\n\t\tthis.peakActiveDescendants = Math.max(this.peakActiveDescendants, this.activeDescendants);\n\t\tthis.maxDepthReached = Math.max(this.maxDepthReached, depth);\n\t\tlet committed = false;\n\t\tlet released = false;\n\t\tlet subagentId: string | undefined;\n\n\t\tconst release = (): void => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tthis.activeDescendants = Math.max(0, this.activeDescendants - 1);\n\t\t\tif (subagentId) {\n\t\t\t\tthis.activeAborters.delete(subagentId);\n\t\t\t}\n\t\t};\n\n\t\treturn {\n\t\t\tcommit: (id, abort) => {\n\t\t\t\tif (committed || released) return;\n\t\t\t\tcommitted = true;\n\t\t\t\tsubagentId = id;\n\t\t\t\tif (this.signal.aborted) {\n\t\t\t\t\tabort();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tthis.activeAborters.set(id, abort);\n\t\t\t},\n\t\t\trelease,\n\t\t\trollback: () => {\n\t\t\t\tif (committed || released) return;\n\t\t\t\tthis.startsUsed = Math.max(0, this.startsUsed - 1);\n\t\t\t\trelease();\n\t\t\t},\n\t\t};\n\t}\n\n\tabort(reason: unknown = new Error(\"Subagent delegation aborted\")): void {\n\t\tif (!this.signal.aborted) {\n\t\t\tthis.controller.abort(reason);\n\t\t}\n\t\tfor (const abort of this.activeAborters.values()) {\n\t\t\ttry {\n\t\t\t\tabort();\n\t\t\t} catch {\n\t\t\t\t// One broken child aborter must not prevent cancellation of siblings.\n\t\t\t}\n\t\t}\n\t}\n\n\trecordTurn(): void {\n\t\tif (this.signal.aborted || this.disposed) return;\n\t\tthis.turnsUsed += 1;\n\t}\n\n\trecordUsage(tokens: number, costUsd: number): void {\n\t\tif (this.signal.aborted || this.disposed) return;\n\t\tif (Number.isFinite(tokens) && tokens > 0) this.tokensUsed += tokens;\n\t\tif (Number.isFinite(costUsd) && costUsd > 0) this.costUsd += costUsd;\n\t}\n\n\tsnapshot(): SubagentDelegationScopeSnapshot {\n\t\treturn {\n\t\t\tid: this.id,\n\t\t\tstartedAt: this.startedAt,\n\t\t\tstartsUsed: this.startsUsed,\n\t\t\tactiveDescendants: this.activeDescendants,\n\t\t\tpeakActiveDescendants: this.peakActiveDescendants,\n\t\t\tmaxDepthReached: this.maxDepthReached,\n\t\t\tturnsUsed: this.turnsUsed,\n\t\t\ttokensUsed: this.tokensUsed,\n\t\t\tcostUsd: this.costUsd,\n\t\t\taborted: this.signal.aborted,\n\t\t};\n\t}\n\n\tdispose(): void {\n\t\tif (this.disposed) return;\n\t\tthis.disposed = true;\n\t\tif (this.externalSignal && this.onExternalAbort) {\n\t\t\tthis.externalSignal.removeEventListener(\"abort\", this.onExternalAbort);\n\t\t}\n\t\tif (this.activeAborters.size > 0) {\n\t\t\tthis.abort(new Error(\"Subagent delegation scope disposed\"));\n\t\t}\n\t\tthis.activeAborters.clear();\n\t}\n\n\tprivate abortReason(): Error {\n\t\treturn this.signal.reason instanceof Error ? this.signal.reason : new Error(String(this.signal.reason));\n\t}\n}\n"]}

package/dist/core/subagents/delegation-scope.js

@@ -0,0 +1,134 @@
+import { randomUUID } from "node:crypto";
+/** Shared, root-owned accounting and cancellation scope for one recursive delegation tree. */
+export class SubagentDelegationScope {
+    id;
+    startedAt;
+    signal;
+    controller = new AbortController();
+    activeAborters = new Map();
+    externalSignal;
+    onExternalAbort;
+    startsUsed = 0;
+    activeDescendants = 0;
+    peakActiveDescendants = 0;
+    maxDepthReached = 0;
+    turnsUsed = 0;
+    tokensUsed = 0;
+    costUsd = 0;
+    disposed = false;
+    constructor(options = {}) {
+        this.id = `sat_${randomUUID()}`;
+        this.startedAt = Date.now();
+        this.signal = this.controller.signal;
+        this.externalSignal = options.signal;
+        this.onExternalAbort = options.signal
+            ? () => this.abort(options.signal?.reason ?? new Error("Operation aborted"))
+            : undefined;
+        if (this.externalSignal?.aborted) {
+            this.abort(this.externalSignal.reason ?? new Error("Operation aborted"));
+        }
+        else if (this.externalSignal && this.onExternalAbort) {
+            this.externalSignal.addEventListener("abort", this.onExternalAbort, { once: true });
+        }
+    }
+    reserve(agentName, depth) {
+        if (this.disposed) {
+            throw new Error(`Cannot delegate to "${agentName}": delegation scope ${this.id} is disposed.`);
+        }
+        if (this.signal.aborted) {
+            throw this.abortReason();
+        }
+        this.startsUsed += 1;
+        this.activeDescendants += 1;
+        this.peakActiveDescendants = Math.max(this.peakActiveDescendants, this.activeDescendants);
+        this.maxDepthReached = Math.max(this.maxDepthReached, depth);
+        let committed = false;
+        let released = false;
+        let subagentId;
+        const release = () => {
+            if (released)
+                return;
+            released = true;
+            this.activeDescendants = Math.max(0, this.activeDescendants - 1);
+            if (subagentId) {
+                this.activeAborters.delete(subagentId);
+            }
+        };
+        return {
+            commit: (id, abort) => {
+                if (committed || released)
+                    return;
+                committed = true;
+                subagentId = id;
+                if (this.signal.aborted) {
+                    abort();
+                    return;
+                }
+                this.activeAborters.set(id, abort);
+            },
+            release,
+            rollback: () => {
+                if (committed || released)
+                    return;
+                this.startsUsed = Math.max(0, this.startsUsed - 1);
+                release();
+            },
+        };
+    }
+    abort(reason = new Error("Subagent delegation aborted")) {
+        if (!this.signal.aborted) {
+            this.controller.abort(reason);
+        }
+        for (const abort of this.activeAborters.values()) {
+            try {
+                abort();
+            }
+            catch {
+                // One broken child aborter must not prevent cancellation of siblings.
+            }
+        }
+    }
+    recordTurn() {
+        if (this.signal.aborted || this.disposed)
+            return;
+        this.turnsUsed += 1;
+    }
+    recordUsage(tokens, costUsd) {
+        if (this.signal.aborted || this.disposed)
+            return;
+        if (Number.isFinite(tokens) && tokens > 0)
+            this.tokensUsed += tokens;
+        if (Number.isFinite(costUsd) && costUsd > 0)
+            this.costUsd += costUsd;
+    }
+    snapshot() {
+        return {
+            id: this.id,
+            startedAt: this.startedAt,
+            startsUsed: this.startsUsed,
+            activeDescendants: this.activeDescendants,
+            peakActiveDescendants: this.peakActiveDescendants,
+            maxDepthReached: this.maxDepthReached,
+            turnsUsed: this.turnsUsed,
+            tokensUsed: this.tokensUsed,
+            costUsd: this.costUsd,
+            aborted: this.signal.aborted,
+        };
+    }
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        if (this.externalSignal && this.onExternalAbort) {
+            this.externalSignal.removeEventListener("abort", this.onExternalAbort);
+        }
+        if (this.activeAborters.size > 0) {
+            this.abort(new Error("Subagent delegation scope disposed"));
+        }
+        this.activeAborters.clear();
+    }
+    abortReason() {
+        return this.signal.reason instanceof Error ? this.signal.reason : new Error(String(this.signal.reason));
+    }
+}
+//# sourceMappingURL=delegation-scope.js.map

package/dist/core/subagents/delegation-scope.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegation-scope.js","sourceRoot":"","sources":["../../../src/core/subagents/delegation-scope.ts"],"names":[],"mappings":"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","sourcesContent":["import { randomUUID } from \"node:crypto\";\n\nexport interface SubagentDelegationScopeSnapshot {\n\tid: string;\n\tstartedAt: number;\n\tstartsUsed: number;\n\tactiveDescendants: number;\n\tpeakActiveDescendants: number;\n\tmaxDepthReached: number;\n\tturnsUsed: number;\n\ttokensUsed: number;\n\tcostUsd: number;\n\taborted: boolean;\n}\n\nexport interface SubagentDelegationReservation {\n\tcommit(subagentId: string, abort: () => void): void;\n\trelease(): void;\n\trollback(): void;\n}\n\nexport interface SubagentDelegationScopeOptions {\n\tsignal?: AbortSignal;\n}\n\n/** Shared, root-owned accounting and cancellation scope for one recursive delegation tree. */\nexport class SubagentDelegationScope {\n\treadonly id: string;\n\treadonly startedAt: number;\n\treadonly signal: AbortSignal;\n\n\tprivate readonly controller = new AbortController();\n\tprivate readonly activeAborters = new Map<string, () => void>();\n\tprivate readonly externalSignal: AbortSignal | undefined;\n\tprivate readonly onExternalAbort: (() => void) | undefined;\n\tprivate startsUsed = 0;\n\tprivate activeDescendants = 0;\n\tprivate peakActiveDescendants = 0;\n\tprivate maxDepthReached = 0;\n\tprivate turnsUsed = 0;\n\tprivate tokensUsed = 0;\n\tprivate costUsd = 0;\n\tprivate disposed = false;\n\n\tconstructor(options: SubagentDelegationScopeOptions = {}) {\n\t\tthis.id = `sat_${randomUUID()}`;\n\t\tthis.startedAt = Date.now();\n\t\tthis.signal = this.controller.signal;\n\t\tthis.externalSignal = options.signal;\n\t\tthis.onExternalAbort = options.signal\n\t\t\t? () => this.abort(options.signal?.reason ?? new Error(\"Operation aborted\"))\n\t\t\t: undefined;\n\t\tif (this.externalSignal?.aborted) {\n\t\t\tthis.abort(this.externalSignal.reason ?? new Error(\"Operation aborted\"));\n\t\t} else if (this.externalSignal && this.onExternalAbort) {\n\t\t\tthis.externalSignal.addEventListener(\"abort\", this.onExternalAbort, { once: true });\n\t\t}\n\t}\n\n\treserve(agentName: string, depth: number): SubagentDelegationReservation {\n\t\tif (this.disposed) {\n\t\t\tthrow new Error(`Cannot delegate to \"${agentName}\": delegation scope ${this.id} is disposed.`);\n\t\t}\n\t\tif (this.signal.aborted) {\n\t\t\tthrow this.abortReason();\n\t\t}\n\n\t\tthis.startsUsed += 1;\n\t\tthis.activeDescendants += 1;\n\t\tthis.peakActiveDescendants = Math.max(this.peakActiveDescendants, this.activeDescendants);\n\t\tthis.maxDepthReached = Math.max(this.maxDepthReached, depth);\n\t\tlet committed = false;\n\t\tlet released = false;\n\t\tlet subagentId: string | undefined;\n\n\t\tconst release = (): void => {\n\t\t\tif (released) return;\n\t\t\treleased = true;\n\t\t\tthis.activeDescendants = Math.max(0, this.activeDescendants - 1);\n\t\t\tif (subagentId) {\n\t\t\t\tthis.activeAborters.delete(subagentId);\n\t\t\t}\n\t\t};\n\n\t\treturn {\n\t\t\tcommit: (id, abort) => {\n\t\t\t\tif (committed || released) return;\n\t\t\t\tcommitted = true;\n\t\t\t\tsubagentId = id;\n\t\t\t\tif (this.signal.aborted) {\n\t\t\t\t\tabort();\n\t\t\t\t\treturn;\n\t\t\t\t}\n\t\t\t\tthis.activeAborters.set(id, abort);\n\t\t\t},\n\t\t\trelease,\n\t\t\trollback: () => {\n\t\t\t\tif (committed || released) return;\n\t\t\t\tthis.startsUsed = Math.max(0, this.startsUsed - 1);\n\t\t\t\trelease();\n\t\t\t},\n\t\t};\n\t}\n\n\tabort(reason: unknown = new Error(\"Subagent delegation aborted\")): void {\n\t\tif (!this.signal.aborted) {\n\t\t\tthis.controller.abort(reason);\n\t\t}\n\t\tfor (const abort of this.activeAborters.values()) {\n\t\t\ttry {\n\t\t\t\tabort();\n\t\t\t} catch {\n\t\t\t\t// One broken child aborter must not prevent cancellation of siblings.\n\t\t\t}\n\t\t}\n\t}\n\n\trecordTurn(): void {\n\t\tif (this.signal.aborted || this.disposed) return;\n\t\tthis.turnsUsed += 1;\n\t}\n\n\trecordUsage(tokens: number, costUsd: number): void {\n\t\tif (this.signal.aborted || this.disposed) return;\n\t\tif (Number.isFinite(tokens) && tokens > 0) this.tokensUsed += tokens;\n\t\tif (Number.isFinite(costUsd) && costUsd > 0) this.costUsd += costUsd;\n\t}\n\n\tsnapshot(): SubagentDelegationScopeSnapshot {\n\t\treturn {\n\t\t\tid: this.id,\n\t\t\tstartedAt: this.startedAt,\n\t\t\tstartsUsed: this.startsUsed,\n\t\t\tactiveDescendants: this.activeDescendants,\n\t\t\tpeakActiveDescendants: this.peakActiveDescendants,\n\t\t\tmaxDepthReached: this.maxDepthReached,\n\t\t\tturnsUsed: this.turnsUsed,\n\t\t\ttokensUsed: this.tokensUsed,\n\t\t\tcostUsd: this.costUsd,\n\t\t\taborted: this.signal.aborted,\n\t\t};\n\t}\n\n\tdispose(): void {\n\t\tif (this.disposed) return;\n\t\tthis.disposed = true;\n\t\tif (this.externalSignal && this.onExternalAbort) {\n\t\t\tthis.externalSignal.removeEventListener(\"abort\", this.onExternalAbort);\n\t\t}\n\t\tif (this.activeAborters.size > 0) {\n\t\t\tthis.abort(new Error(\"Subagent delegation scope disposed\"));\n\t\t}\n\t\tthis.activeAborters.clear();\n\t}\n\n\tprivate abortReason(): Error {\n\t\treturn this.signal.reason instanceof Error ? this.signal.reason : new Error(String(this.signal.reason));\n\t}\n}\n"]}

package/dist/core/subagents/index.d.ts

@@ -0,0 +1,46 @@
+import type { ResourceDiagnostic } from "../diagnostics.ts";
+import { type SourceInfo } from "../source-info.ts";
+export type SubagentDefinitionSource = "built-in" | "user" | "project";
+export type FileSubagentDefinitionSource = Exclude<SubagentDefinitionSource, "built-in">;
+export interface SubagentDefinition {
+    name: string;
+    description: string;
+    tools?: string[];
+    excludedTools?: string[];
+    allowedSubagents?: string[];
+    maxSubagentDepth?: number;
+    maxChildAgents?: number;
+    model?: string;
+    thinking?: string;
+    systemPrompt: string;
+    source: SubagentDefinitionSource;
+    sourceInfo: SourceInfo;
+    filePath: string;
+}
+export interface ParseSubagentDefinitionOptions {
+    content: string;
+    filePath: string;
+    source: FileSubagentDefinitionSource;
+    sourceInfo: SourceInfo;
+}
+export interface ParseSubagentDefinitionResult {
+    definition: SubagentDefinition | null;
+    diagnostics: ResourceDiagnostic[];
+}
+export interface DiscoverSubagentDefinitionsOptions {
+    cwd: string;
+    agentDir: string;
+    projectTrusted: boolean;
+}
+export interface SubagentDiscoveryResult {
+    definitions: SubagentDefinition[];
+    diagnostics: ResourceDiagnostic[];
+    userAgentsDir: string;
+    projectAgentsDir: string;
+}
+export declare function createBuiltInSubagentDefinitions(): SubagentDefinition[];
+export declare function parseSubagentDefinition(options: ParseSubagentDefinitionOptions): ParseSubagentDefinitionResult;
+export declare function discoverSubagentDefinitions(options: DiscoverSubagentDefinitionsOptions): SubagentDiscoveryResult;
+export { type SubagentDelegationReservation, SubagentDelegationScope, type SubagentDelegationScopeOptions, type SubagentDelegationScopeSnapshot, } from "./delegation-scope.ts";
+export { type SubagentActivity, type SubagentActivityEvent, type SubagentActivityListener, type SubagentActivityStatus, SubagentDefinitionConfigurationError, SubagentDefinitionNotFoundError, type SubagentDelegationScopeLease, type SubagentEndEvent, type SubagentEvent, type SubagentEventListener, type SubagentHandle, SubagentManager, type SubagentManagerOptions, type SubagentResult, type SubagentRuntimeCreatedEvent, type SubagentStartByNameOptions, type SubagentStartOptions, } from "./manager.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/core/subagents/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/subagents/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAC5D,OAAO,EAA6B,KAAK,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/E,MAAM,MAAM,wBAAwB,GAAG,UAAU,GAAG,MAAM,GAAG,SAAS,CAAC;AACvE,MAAM,MAAM,4BAA4B,GAAG,OAAO,CAAC,wBAAwB,EAAE,UAAU,CAAC,CAAC;AAEzF,MAAM,WAAW,kBAAkB;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC5B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,wBAAwB,CAAC;IACjC,UAAU,EAAE,UAAU,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,8BAA8B;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,4BAA4B,CAAC;IACrC,UAAU,EAAE,UAAU,CAAC;CACvB;AAED,MAAM,WAAW,6BAA6B;IAC7C,UAAU,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACtC,WAAW,EAAE,kBAAkB,EAAE,CAAC;CAClC;AAED,MAAM,WAAW,kCAAkC;IAClD,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,uBAAuB;IACvC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,WAAW,EAAE,kBAAkB,EAAE,CAAC;IAClC,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CACzB;AASD,wBAAgB,gCAAgC,IAAI,kBAAkB,EAAE,CAqFvE;AA8HD,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,8BAA8B,GAAG,6BAA6B,CAuE9G;AAwFD,wBAAgB,2BAA2B,CAAC,OAAO,EAAE,kCAAkC,GAAG,uBAAuB,CAsDhH;AAED,OAAO,EACN,KAAK,6BAA6B,EAClC,uBAAuB,EACvB,KAAK,8BAA8B,EACnC,KAAK,+BAA+B,GACpC,MAAM,uBAAuB,CAAC;AAE/B,OAAO,EACN,KAAK,gBAAgB,EACrB,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,EAC7B,KAAK,sBAAsB,EAC3B,oCAAoC,EACpC,+BAA+B,EAC/B,KAAK,4BAA4B,EACjC,KAAK,gBAAgB,EACrB,KAAK,aAAa,EAClB,KAAK,qBAAqB,EAC1B,KAAK,cAAc,EACnB,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,cAAc,EACnB,KAAK,2BAA2B,EAChC,KAAK,0BAA0B,EAC/B,KAAK,oBAAoB,GACzB,MAAM,cAAc,CAAC","sourcesContent":["import { type Dirent, existsSync, readdirSync, readFileSync, statSync } from \"node:fs\";\nimport { join } from \"node:path\";\nimport { CONFIG_DIR_NAME } from \"../../config.ts\";\nimport { parseFrontmatter } from \"../../utils/frontmatter.ts\";\nimport { resolvePath } from \"../../utils/paths.ts\";\nimport type { ResourceDiagnostic } from \"../diagnostics.ts\";\nimport { createSyntheticSourceInfo, type SourceInfo } from \"../source-info.ts\";\n\nexport type SubagentDefinitionSource = \"built-in\" | \"user\" | \"project\";\nexport type FileSubagentDefinitionSource = Exclude<SubagentDefinitionSource, \"built-in\">;\n\nexport interface SubagentDefinition {\n\tname: string;\n\tdescription: string;\n\ttools?: string[];\n\texcludedTools?: string[];\n\tallowedSubagents?: string[];\n\tmaxSubagentDepth?: number;\n\tmaxChildAgents?: number;\n\tmodel?: string;\n\tthinking?: string;\n\tsystemPrompt: string;\n\tsource: SubagentDefinitionSource;\n\tsourceInfo: SourceInfo;\n\tfilePath: string;\n}\n\nexport interface ParseSubagentDefinitionOptions {\n\tcontent: string;\n\tfilePath: string;\n\tsource: FileSubagentDefinitionSource;\n\tsourceInfo: SourceInfo;\n}\n\nexport interface ParseSubagentDefinitionResult {\n\tdefinition: SubagentDefinition | null;\n\tdiagnostics: ResourceDiagnostic[];\n}\n\nexport interface DiscoverSubagentDefinitionsOptions {\n\tcwd: string;\n\tagentDir: string;\n\tprojectTrusted: boolean;\n}\n\nexport interface SubagentDiscoveryResult {\n\tdefinitions: SubagentDefinition[];\n\tdiagnostics: ResourceDiagnostic[];\n\tuserAgentsDir: string;\n\tprojectAgentsDir: string;\n}\n\nconst BUILT_IN_GENERAL_SUBAGENT_FILE_PATH = \"builtin:general\";\nconst BUILT_IN_RESEARCHER_SUBAGENT_FILE_PATH = \"builtin:researcher\";\nconst BUILT_IN_DESIGN_DOC_SUBAGENT_FILE_PATH = \"builtin:design-doc\";\nconst BUILT_IN_SECURITY_REVIEWER_SUBAGENT_FILE_PATH = \"builtin:security-reviewer\";\nconst BUILT_IN_READ_ONLY_TOOLS = [\"read\", \"web_search\", \"grep\", \"find\", \"ls\"];\nconst BUILT_IN_DELEGATING_READ_ONLY_TOOLS = [...BUILT_IN_READ_ONLY_TOOLS, \"subagent\"];\n\nexport function createBuiltInSubagentDefinitions(): SubagentDefinition[] {\n\treturn [\n\t\t{\n\t\t\tname: \"general\",\n\t\t\tdescription: \"General-purpose isolated child agent for ad hoc delegated tasks\",\n\t\t\texcludedTools: [\"subagent\"],\n\t\t\tallowedSubagents: [],\n\t\t\tmaxChildAgents: 0,\n\t\t\tsystemPrompt: [\n\t\t\t\t\"You are the built-in general-purpose Volt subagent.\",\n\t\t\t\t\"Complete the delegated task independently using only the task prompt and available tools.\",\n\t\t\t\t\"You are one contributor in a larger workflow, not the final decision-maker.\",\n\t\t\t\t\"Do not delegate to other subagents; the subagent tool is intentionally unavailable for this role.\",\n\t\t\t\t\"For code or research tasks, return concise findings, evidence, blockers, and next steps.\",\n\t\t\t\t\"For writing or creative tasks, return the requested artifact directly.\",\n\t\t\t\t\"Do not assume parent conversation context beyond the delegated task prompt.\",\n\t\t\t].join(\"\\n\"),\n\t\t\tsource: \"built-in\",\n\t\t\tsourceInfo: createSyntheticSourceInfo(BUILT_IN_GENERAL_SUBAGENT_FILE_PATH, { source: \"built-in\" }),\n\t\t\tfilePath: BUILT_IN_GENERAL_SUBAGENT_FILE_PATH,\n\t\t},\n\t\t{\n\t\t\tname: \"researcher\",\n\t\t\tdescription: \"Non-mutating research scout for web and codebase evidence gathering\",\n\t\t\ttools: [...BUILT_IN_DELEGATING_READ_ONLY_TOOLS],\n\t\t\tallowedSubagents: [\"researcher\"],\n\t\t\tmaxSubagentDepth: 3,\n\t\t\tmaxChildAgents: 2,\n\t\t\tsystemPrompt: [\n\t\t\t\t\"You are the built-in Volt researcher subagent.\",\n\t\t\t\t\"Gather source-backed evidence from the web and/or codebase for the delegated question.\",\n\t\t\t\t\"You are one contributor in a larger workflow, not the final decision-maker.\",\n\t\t\t\t\"Do not modify files or run shell commands; this role has non-mutating local tools plus web_search.\",\n\t\t\t\t\"Use the subagent tool only when you discover a distinct follow-up question that would benefit from a fresh, narrower researcher context.\",\n\t\t\t\t\"Delegate only to researcher subagents and keep recursive research bounded.\",\n\t\t\t\t\"Return concise findings with source URLs or file paths, assumptions, uncertainty, and open questions.\",\n\t\t\t].join(\"\\n\"),\n\t\t\tsource: \"built-in\",\n\t\t\tsourceInfo: createSyntheticSourceInfo(BUILT_IN_RESEARCHER_SUBAGENT_FILE_PATH, { source: \"built-in\" }),\n\t\t\tfilePath: BUILT_IN_RESEARCHER_SUBAGENT_FILE_PATH,\n\t\t},\n\t\t{\n\t\t\tname: \"design-doc\",\n\t\t\tdescription: \"Design document planner and synthesizer that delegates independent research when warranted\",\n\t\t\tallowedSubagents: [\"researcher\", \"security-reviewer\", \"general\"],\n\t\t\tmaxSubagentDepth: 3,\n\t\t\tmaxChildAgents: 8,\n\t\t\tsystemPrompt: [\n\t\t\t\t\"You are the built-in Volt design-document coordinator.\",\n\t\t\t\t\"Your job is to turn an ambiguous technical goal into a sourced design/RFC, decision memo, or implementation plan.\",\n\t\t\t\t\"Use the subagent tool for broad or uncertain work that benefits from independent product, architecture, migration, operations, security, performance, prior-art, or skeptical review research before synthesis.\",\n\t\t\t\t\"Scale delegation to complexity: handle simple questions directly, use 1 child for one focused gap, use 2-4 children for independent medium-sized questions, and exceed 4 only for genuinely broad work with non-overlapping assignments.\",\n\t\t\t\t\"Do not delegate duplicate work, and stop spawning once the available evidence is sufficient to make the design decision.\",\n\t\t\t\t\"Prefer parallel delegation for independent research questions and chain delegation only when later steps depend on prior output.\",\n\t\t\t\t\"Preserve minority reports and unresolved objections; do not collapse disagreement into false consensus.\",\n\t\t\t\t\"When external or current claims matter, perform or delegate web research and cite source URLs.\",\n\t\t\t\t\"When editing files, keep changes scoped to the requested design artifact unless the parent task explicitly asks for code changes.\",\n\t\t\t\t\"Return or write a structured document with context, goals, non-goals, proposal, alternatives, risks, rollout, verification, and open questions.\",\n\t\t\t].join(\"\\n\"),\n\t\t\tsource: \"built-in\",\n\t\t\tsourceInfo: createSyntheticSourceInfo(BUILT_IN_DESIGN_DOC_SUBAGENT_FILE_PATH, { source: \"built-in\" }),\n\t\t\tfilePath: BUILT_IN_DESIGN_DOC_SUBAGENT_FILE_PATH,\n\t\t},\n\t\t{\n\t\t\tname: \"security-reviewer\",\n\t\t\tdescription:\n\t\t\t\t\"Non-mutating security review coordinator for threat modeling, code review, and verification planning\",\n\t\t\ttools: [...BUILT_IN_DELEGATING_READ_ONLY_TOOLS],\n\t\t\tallowedSubagents: [\"researcher\"],\n\t\t\tmaxSubagentDepth: 3,\n\t\t\tmaxChildAgents: 4,\n\t\t\tsystemPrompt: [\n\t\t\t\t\"You are the built-in Volt security-reviewer subagent.\",\n\t\t\t\t\"Analyze code, design, dependencies, configuration, and agent/tool workflows for security risk.\",\n\t\t\t\t\"You are one contributor in a larger workflow, not the final decision-maker.\",\n\t\t\t\t\"Do not edit files, write files, run shell commands, or invoke mutating refactors; this role has non-mutating local tools plus web_search and bounded read-only delegation.\",\n\t\t\t\t\"Use researcher subagents for independent research or second-opinion review when it improves coverage, but keep delegation bounded and evidence-focused.\",\n\t\t\t\t\"For exploit verification or regression tests that require file writes or shell commands, return a precise test plan for the parent to authorize outside this read-only role.\",\n\t\t\t\t\"Report findings with file paths, severity, exploit preconditions, evidence, confidence, remediation, and verification steps.\",\n\t\t\t].join(\"\\n\"),\n\t\t\tsource: \"built-in\",\n\t\t\tsourceInfo: createSyntheticSourceInfo(BUILT_IN_SECURITY_REVIEWER_SUBAGENT_FILE_PATH, { source: \"built-in\" }),\n\t\t\tfilePath: BUILT_IN_SECURITY_REVIEWER_SUBAGENT_FILE_PATH,\n\t\t},\n\t];\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction getErrorMessage(error: unknown, fallback: string): string {\n\treturn error instanceof Error ? error.message : fallback;\n}\n\nfunction readRequiredStringField(\n\tfrontmatter: Record<string, unknown>,\n\tkey: \"name\" | \"description\",\n\tfilePath: string,\n\tdiagnostics: ResourceDiagnostic[],\n): string | undefined {\n\tconst value = frontmatter[key];\n\tif (typeof value !== \"string\" || value.trim() === \"\") {\n\t\tdiagnostics.push({ type: \"warning\", message: `${key} is required`, path: filePath });\n\t\treturn undefined;\n\t}\n\treturn value.trim();\n}\n\nfunction readOptionalStringField(\n\tfrontmatter: Record<string, unknown>,\n\tkey: \"model\" | \"thinking\",\n\tfilePath: string,\n\tdiagnostics: ResourceDiagnostic[],\n): string | undefined {\n\tconst value = frontmatter[key];\n\tif (value === undefined || value === null) {\n\t\treturn undefined;\n\t}\n\tif (typeof value !== \"string\") {\n\t\tdiagnostics.push({ type: \"warning\", message: `${key} must be a string`, path: filePath });\n\t\treturn undefined;\n\t}\n\tconst trimmed = value.trim();\n\treturn trimmed.length > 0 ? trimmed : undefined;\n}\n\nfunction readCommaSeparatedListField(\n\tfrontmatter: Record<string, unknown>,\n\tkey: \"tools\" | \"excludedTools\",\n\tfilePath: string,\n\tdiagnostics: ResourceDiagnostic[],\n): string[] | undefined {\n\tif (!Object.hasOwn(frontmatter, key)) {\n\t\treturn undefined;\n\t}\n\tconst value = frontmatter[key];\n\tif (value === undefined || value === null) {\n\t\treturn [];\n\t}\n\tif (typeof value !== \"string\") {\n\t\tdiagnostics.push({ type: \"warning\", message: `${key} must be a comma-separated string`, path: filePath });\n\t\treturn undefined;\n\t}\n\n\treturn value\n\t\t.split(\",\")\n\t\t.map((item) => item.trim())\n\t\t.filter((item) => item.length > 0);\n}\n\nfunction readAllowedSubagentsField(\n\tfrontmatter: Record<string, unknown>,\n\tfilePath: string,\n\tdiagnostics: ResourceDiagnostic[],\n): string[] | undefined {\n\tif (!Object.hasOwn(frontmatter, \"allowedSubagents\")) {\n\t\treturn undefined;\n\t}\n\tconst value = frontmatter.allowedSubagents;\n\tif (value === undefined || value === null) {\n\t\treturn [];\n\t}\n\tif (typeof value !== \"string\") {\n\t\tdiagnostics.push({\n\t\t\ttype: \"warning\",\n\t\t\tmessage: \"allowedSubagents must be a comma-separated string\",\n\t\t\tpath: filePath,\n\t\t});\n\t\treturn undefined;\n\t}\n\n\treturn value\n\t\t.split(\",\")\n\t\t.map((item) => item.trim())\n\t\t.filter((item) => item.length > 0);\n}\n\nfunction readOptionalNonNegativeIntegerField(\n\tfrontmatter: Record<string, unknown>,\n\tkey: \"maxSubagentDepth\" | \"maxChildAgents\",\n\tfilePath: string,\n\tdiagnostics: ResourceDiagnostic[],\n): number | undefined {\n\tif (!Object.hasOwn(frontmatter, key)) {\n\t\treturn undefined;\n\t}\n\tconst value = frontmatter[key];\n\tconst parsed = parseOptionalNonNegativeInteger(value);\n\tif (parsed === undefined) {\n\t\tdiagnostics.push({ type: \"warning\", message: `${key} must be a non-negative integer`, path: filePath });\n\t\treturn undefined;\n\t}\n\treturn parsed;\n}\n\nfunction parseOptionalNonNegativeInteger(value: unknown): number | undefined {\n\tif (typeof value === \"number\") {\n\t\treturn Number.isInteger(value) && value >= 0 ? value : undefined;\n\t}\n\tif (typeof value !== \"string\") {\n\t\treturn undefined;\n\t}\n\tconst trimmed = value.trim();\n\tif (trimmed.length === 0) {\n\t\treturn undefined;\n\t}\n\tconst parsed = Number(trimmed);\n\treturn Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;\n}\n\nexport function parseSubagentDefinition(options: ParseSubagentDefinitionOptions): ParseSubagentDefinitionResult {\n\tconst diagnostics: ResourceDiagnostic[] = [];\n\tlet frontmatter: Record<string, unknown>;\n\tlet body: string;\n\n\ttry {\n\t\tconst parsed = parseFrontmatter<Record<string, unknown>>(options.content);\n\t\tif (!isRecord(parsed.frontmatter)) {\n\t\t\tdiagnostics.push({ type: \"warning\", message: \"frontmatter must be a mapping\", path: options.filePath });\n\t\t\treturn { definition: null, diagnostics };\n\t\t}\n\t\tfrontmatter = parsed.frontmatter;\n\t\tbody = parsed.body;\n\t} catch (error) {\n\t\tdiagnostics.push({\n\t\t\ttype: \"warning\",\n\t\t\tmessage: `failed to parse subagent definition: ${getErrorMessage(error, \"invalid frontmatter\")}`,\n\t\t\tpath: options.filePath,\n\t\t});\n\t\treturn { definition: null, diagnostics };\n\t}\n\n\tconst name = readRequiredStringField(frontmatter, \"name\", options.filePath, diagnostics);\n\tconst description = readRequiredStringField(frontmatter, \"description\", options.filePath, diagnostics);\n\tconst systemPrompt = body.trim();\n\tif (systemPrompt.length === 0) {\n\t\tdiagnostics.push({ type: \"warning\", message: \"system prompt body is required\", path: options.filePath });\n\t}\n\n\tconst policyDiagnosticStart = diagnostics.length;\n\tconst tools = readCommaSeparatedListField(frontmatter, \"tools\", options.filePath, diagnostics);\n\tconst excludedTools = readCommaSeparatedListField(frontmatter, \"excludedTools\", options.filePath, diagnostics);\n\tconst allowedSubagents = readAllowedSubagentsField(frontmatter, options.filePath, diagnostics);\n\tconst maxSubagentDepth = readOptionalNonNegativeIntegerField(\n\t\tfrontmatter,\n\t\t\"maxSubagentDepth\",\n\t\toptions.filePath,\n\t\tdiagnostics,\n\t);\n\tconst maxChildAgents = readOptionalNonNegativeIntegerField(\n\t\tfrontmatter,\n\t\t\"maxChildAgents\",\n\t\toptions.filePath,\n\t\tdiagnostics,\n\t);\n\tconst hasMalformedPolicyField = diagnostics.length > policyDiagnosticStart;\n\tconst model = readOptionalStringField(frontmatter, \"model\", options.filePath, diagnostics);\n\tconst thinking = readOptionalStringField(frontmatter, \"thinking\", options.filePath, diagnostics);\n\n\tif (!name || !description || systemPrompt.length === 0 || hasMalformedPolicyField) {\n\t\treturn { definition: null, diagnostics };\n\t}\n\n\treturn {\n\t\tdefinition: {\n\t\t\tname,\n\t\t\tdescription,\n\t\t\t...(tools ? { tools } : {}),\n\t\t\t...(excludedTools ? { excludedTools } : {}),\n\t\t\tallowedSubagents: allowedSubagents ?? [],\n\t\t\t...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),\n\t\t\t...(maxChildAgents !== undefined ? { maxChildAgents } : {}),\n\t\t\t...(model ? { model } : {}),\n\t\t\t...(thinking ? { thinking } : {}),\n\t\t\tsystemPrompt,\n\t\t\tsource: options.source,\n\t\t\tsourceInfo: options.sourceInfo,\n\t\t\tfilePath: options.filePath,\n\t\t},\n\t\tdiagnostics,\n\t};\n}\n\nfunction createSubagentSourceInfo(\n\tfilePath: string,\n\tagentsDir: string,\n\tsource: FileSubagentDefinitionSource,\n): SourceInfo {\n\treturn createSyntheticSourceInfo(filePath, {\n\t\tsource: \"local\",\n\t\tscope: source,\n\t\tbaseDir: agentsDir,\n\t});\n}\n\nfunction loadSubagentDefinitionsFromDir(\n\tdir: string,\n\tsource: FileSubagentDefinitionSource,\n): { definitions: SubagentDefinition[]; diagnostics: ResourceDiagnostic[] } {\n\tconst definitions: SubagentDefinition[] = [];\n\tconst diagnostics: ResourceDiagnostic[] = [];\n\n\tif (!existsSync(dir)) {\n\t\treturn { definitions, diagnostics };\n\t}\n\n\tlet entries: Dirent[];\n\ttry {\n\t\tentries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));\n\t} catch (error) {\n\t\tdiagnostics.push({\n\t\t\ttype: \"warning\",\n\t\t\tmessage: getErrorMessage(error, \"failed to read subagent directory\"),\n\t\t\tpath: dir,\n\t\t});\n\t\treturn { definitions, diagnostics };\n\t}\n\n\tfor (const entry of entries) {\n\t\tif (!entry.name.endsWith(\".md\")) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst filePath = join(dir, entry.name);\n\t\tlet isFile = entry.isFile();\n\t\tif (entry.isSymbolicLink()) {\n\t\t\ttry {\n\t\t\t\tisFile = statSync(filePath).isFile();\n\t\t\t} catch (error) {\n\t\t\t\tdiagnostics.push({\n\t\t\t\t\ttype: \"warning\",\n\t\t\t\t\tmessage: getErrorMessage(error, \"failed to read subagent symlink\"),\n\t\t\t\t\tpath: filePath,\n\t\t\t\t});\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t}\n\n\t\tif (!isFile) {\n\t\t\tcontinue;\n\t\t}\n\n\t\tlet content: string;\n\t\ttry {\n\t\t\tcontent = readFileSync(filePath, \"utf-8\");\n\t\t} catch (error) {\n\t\t\tdiagnostics.push({\n\t\t\t\ttype: \"warning\",\n\t\t\t\tmessage: getErrorMessage(error, \"failed to read subagent definition\"),\n\t\t\t\tpath: filePath,\n\t\t\t});\n\t\t\tcontinue;\n\t\t}\n\n\t\tconst result = parseSubagentDefinition({\n\t\t\tcontent,\n\t\t\tfilePath,\n\t\t\tsource,\n\t\t\tsourceInfo: createSubagentSourceInfo(filePath, dir, source),\n\t\t});\n\t\tif (result.definition) {\n\t\t\tdefinitions.push(result.definition);\n\t\t}\n\t\tdiagnostics.push(...result.diagnostics);\n\t}\n\n\treturn { definitions, diagnostics };\n}\n\nexport function discoverSubagentDefinitions(options: DiscoverSubagentDefinitionsOptions): SubagentDiscoveryResult {\n\tconst resolvedCwd = resolvePath(options.cwd);\n\tconst resolvedAgentDir = resolvePath(options.agentDir);\n\tconst userAgentsDir = join(resolvedAgentDir, \"agents\");\n\tconst projectAgentsDir = join(resolvedCwd, CONFIG_DIR_NAME, \"agents\");\n\n\tconst diagnostics: ResourceDiagnostic[] = [];\n\tconst definitionsByName = new Map<string, SubagentDefinition>();\n\tconst seenBySource = new Set<string>();\n\tconst builtInDefinitions = createBuiltInSubagentDefinitions();\n\tconst reservedBuiltInNames = new Set(builtInDefinitions.map((definition) => definition.name));\n\n\tfunction addDefinitions(definitions: SubagentDefinition[]): void {\n\t\tfor (const definition of definitions) {\n\t\t\tif (definition.source !== \"built-in\" && reservedBuiltInNames.has(definition.name)) {\n\t\t\t\tdiagnostics.push({\n\t\t\t\t\ttype: \"warning\",\n\t\t\t\t\tmessage: `subagent definition \"${definition.name}\" cannot override a built-in subagent and was ignored`,\n\t\t\t\t\tpath: definition.filePath,\n\t\t\t\t});\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tconst sourceKey = `${definition.source}:${definition.name}`;\n\t\t\tif (seenBySource.has(sourceKey)) {\n\t\t\t\tdiagnostics.push({\n\t\t\t\t\ttype: \"warning\",\n\t\t\t\t\tmessage: `duplicate ${definition.source} subagent definition \"${definition.name}\" ignored`,\n\t\t\t\t\tpath: definition.filePath,\n\t\t\t\t});\n\t\t\t\tcontinue;\n\t\t\t}\n\t\t\tseenBySource.add(sourceKey);\n\t\t\tdefinitionsByName.set(definition.name, definition);\n\t\t}\n\t}\n\n\taddDefinitions(builtInDefinitions);\n\n\tconst userResult = loadSubagentDefinitionsFromDir(userAgentsDir, \"user\");\n\taddDefinitions(userResult.definitions);\n\tdiagnostics.push(...userResult.diagnostics);\n\n\tif (options.projectTrusted) {\n\t\tconst projectResult = loadSubagentDefinitionsFromDir(projectAgentsDir, \"project\");\n\t\taddDefinitions(projectResult.definitions);\n\t\tdiagnostics.push(...projectResult.diagnostics);\n\t}\n\n\treturn {\n\t\tdefinitions: Array.from(definitionsByName.values()),\n\t\tdiagnostics,\n\t\tuserAgentsDir,\n\t\tprojectAgentsDir,\n\t};\n}\n\nexport {\n\ttype SubagentDelegationReservation,\n\tSubagentDelegationScope,\n\ttype SubagentDelegationScopeOptions,\n\ttype SubagentDelegationScopeSnapshot,\n} from \"./delegation-scope.ts\";\n\nexport {\n\ttype SubagentActivity,\n\ttype SubagentActivityEvent,\n\ttype SubagentActivityListener,\n\ttype SubagentActivityStatus,\n\tSubagentDefinitionConfigurationError,\n\tSubagentDefinitionNotFoundError,\n\ttype SubagentDelegationScopeLease,\n\ttype SubagentEndEvent,\n\ttype SubagentEvent,\n\ttype SubagentEventListener,\n\ttype SubagentHandle,\n\tSubagentManager,\n\ttype SubagentManagerOptions,\n\ttype SubagentResult,\n\ttype SubagentRuntimeCreatedEvent,\n\ttype SubagentStartByNameOptions,\n\ttype SubagentStartOptions,\n} from \"./manager.ts\";\n"]}

package/dist/core/subagents/index.js

@@ -0,0 +1,369 @@
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { CONFIG_DIR_NAME } from "../../config.js";
+import { parseFrontmatter } from "../../utils/frontmatter.js";
+import { resolvePath } from "../../utils/paths.js";
+import { createSyntheticSourceInfo } from "../source-info.js";
+const BUILT_IN_GENERAL_SUBAGENT_FILE_PATH = "builtin:general";
+const BUILT_IN_RESEARCHER_SUBAGENT_FILE_PATH = "builtin:researcher";
+const BUILT_IN_DESIGN_DOC_SUBAGENT_FILE_PATH = "builtin:design-doc";
+const BUILT_IN_SECURITY_REVIEWER_SUBAGENT_FILE_PATH = "builtin:security-reviewer";
+const BUILT_IN_READ_ONLY_TOOLS = ["read", "web_search", "grep", "find", "ls"];
+const BUILT_IN_DELEGATING_READ_ONLY_TOOLS = [...BUILT_IN_READ_ONLY_TOOLS, "subagent"];
+export function createBuiltInSubagentDefinitions() {
+    return [
+        {
+            name: "general",
+            description: "General-purpose isolated child agent for ad hoc delegated tasks",
+            excludedTools: ["subagent"],
+            allowedSubagents: [],
+            maxChildAgents: 0,
+            systemPrompt: [
+                "You are the built-in general-purpose Volt subagent.",
+                "Complete the delegated task independently using only the task prompt and available tools.",
+                "You are one contributor in a larger workflow, not the final decision-maker.",
+                "Do not delegate to other subagents; the subagent tool is intentionally unavailable for this role.",
+                "For code or research tasks, return concise findings, evidence, blockers, and next steps.",
+                "For writing or creative tasks, return the requested artifact directly.",
+                "Do not assume parent conversation context beyond the delegated task prompt.",
+            ].join("\n"),
+            source: "built-in",
+            sourceInfo: createSyntheticSourceInfo(BUILT_IN_GENERAL_SUBAGENT_FILE_PATH, { source: "built-in" }),
+            filePath: BUILT_IN_GENERAL_SUBAGENT_FILE_PATH,
+        },
+        {
+            name: "researcher",
+            description: "Non-mutating research scout for web and codebase evidence gathering",
+            tools: [...BUILT_IN_DELEGATING_READ_ONLY_TOOLS],
+            allowedSubagents: ["researcher"],
+            maxSubagentDepth: 3,
+            maxChildAgents: 2,
+            systemPrompt: [
+                "You are the built-in Volt researcher subagent.",
+                "Gather source-backed evidence from the web and/or codebase for the delegated question.",
+                "You are one contributor in a larger workflow, not the final decision-maker.",
+                "Do not modify files or run shell commands; this role has non-mutating local tools plus web_search.",
+                "Use the subagent tool only when you discover a distinct follow-up question that would benefit from a fresh, narrower researcher context.",
+                "Delegate only to researcher subagents and keep recursive research bounded.",
+                "Return concise findings with source URLs or file paths, assumptions, uncertainty, and open questions.",
+            ].join("\n"),
+            source: "built-in",
+            sourceInfo: createSyntheticSourceInfo(BUILT_IN_RESEARCHER_SUBAGENT_FILE_PATH, { source: "built-in" }),
+            filePath: BUILT_IN_RESEARCHER_SUBAGENT_FILE_PATH,
+        },
+        {
+            name: "design-doc",
+            description: "Design document planner and synthesizer that delegates independent research when warranted",
+            allowedSubagents: ["researcher", "security-reviewer", "general"],
+            maxSubagentDepth: 3,
+            maxChildAgents: 8,
+            systemPrompt: [
+                "You are the built-in Volt design-document coordinator.",
+                "Your job is to turn an ambiguous technical goal into a sourced design/RFC, decision memo, or implementation plan.",
+                "Use the subagent tool for broad or uncertain work that benefits from independent product, architecture, migration, operations, security, performance, prior-art, or skeptical review research before synthesis.",
+                "Scale delegation to complexity: handle simple questions directly, use 1 child for one focused gap, use 2-4 children for independent medium-sized questions, and exceed 4 only for genuinely broad work with non-overlapping assignments.",
+                "Do not delegate duplicate work, and stop spawning once the available evidence is sufficient to make the design decision.",
+                "Prefer parallel delegation for independent research questions and chain delegation only when later steps depend on prior output.",
+                "Preserve minority reports and unresolved objections; do not collapse disagreement into false consensus.",
+                "When external or current claims matter, perform or delegate web research and cite source URLs.",
+                "When editing files, keep changes scoped to the requested design artifact unless the parent task explicitly asks for code changes.",
+                "Return or write a structured document with context, goals, non-goals, proposal, alternatives, risks, rollout, verification, and open questions.",
+            ].join("\n"),
+            source: "built-in",
+            sourceInfo: createSyntheticSourceInfo(BUILT_IN_DESIGN_DOC_SUBAGENT_FILE_PATH, { source: "built-in" }),
+            filePath: BUILT_IN_DESIGN_DOC_SUBAGENT_FILE_PATH,
+        },
+        {
+            name: "security-reviewer",
+            description: "Non-mutating security review coordinator for threat modeling, code review, and verification planning",
+            tools: [...BUILT_IN_DELEGATING_READ_ONLY_TOOLS],
+            allowedSubagents: ["researcher"],
+            maxSubagentDepth: 3,
+            maxChildAgents: 4,
+            systemPrompt: [
+                "You are the built-in Volt security-reviewer subagent.",
+                "Analyze code, design, dependencies, configuration, and agent/tool workflows for security risk.",
+                "You are one contributor in a larger workflow, not the final decision-maker.",
+                "Do not edit files, write files, run shell commands, or invoke mutating refactors; this role has non-mutating local tools plus web_search and bounded read-only delegation.",
+                "Use researcher subagents for independent research or second-opinion review when it improves coverage, but keep delegation bounded and evidence-focused.",
+                "For exploit verification or regression tests that require file writes or shell commands, return a precise test plan for the parent to authorize outside this read-only role.",
+                "Report findings with file paths, severity, exploit preconditions, evidence, confidence, remediation, and verification steps.",
+            ].join("\n"),
+            source: "built-in",
+            sourceInfo: createSyntheticSourceInfo(BUILT_IN_SECURITY_REVIEWER_SUBAGENT_FILE_PATH, { source: "built-in" }),
+            filePath: BUILT_IN_SECURITY_REVIEWER_SUBAGENT_FILE_PATH,
+        },
+    ];
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function getErrorMessage(error, fallback) {
+    return error instanceof Error ? error.message : fallback;
+}
+function readRequiredStringField(frontmatter, key, filePath, diagnostics) {
+    const value = frontmatter[key];
+    if (typeof value !== "string" || value.trim() === "") {
+        diagnostics.push({ type: "warning", message: `${key} is required`, path: filePath });
+        return undefined;
+    }
+    return value.trim();
+}
+function readOptionalStringField(frontmatter, key, filePath, diagnostics) {
+    const value = frontmatter[key];
+    if (value === undefined || value === null) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        diagnostics.push({ type: "warning", message: `${key} must be a string`, path: filePath });
+        return undefined;
+    }
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function readCommaSeparatedListField(frontmatter, key, filePath, diagnostics) {
+    if (!Object.hasOwn(frontmatter, key)) {
+        return undefined;
+    }
+    const value = frontmatter[key];
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (typeof value !== "string") {
+        diagnostics.push({ type: "warning", message: `${key} must be a comma-separated string`, path: filePath });
+        return undefined;
+    }
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function readAllowedSubagentsField(frontmatter, filePath, diagnostics) {
+    if (!Object.hasOwn(frontmatter, "allowedSubagents")) {
+        return undefined;
+    }
+    const value = frontmatter.allowedSubagents;
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (typeof value !== "string") {
+        diagnostics.push({
+            type: "warning",
+            message: "allowedSubagents must be a comma-separated string",
+            path: filePath,
+        });
+        return undefined;
+    }
+    return value
+        .split(",")
+        .map((item) => item.trim())
+        .filter((item) => item.length > 0);
+}
+function readOptionalNonNegativeIntegerField(frontmatter, key, filePath, diagnostics) {
+    if (!Object.hasOwn(frontmatter, key)) {
+        return undefined;
+    }
+    const value = frontmatter[key];
+    const parsed = parseOptionalNonNegativeInteger(value);
+    if (parsed === undefined) {
+        diagnostics.push({ type: "warning", message: `${key} must be a non-negative integer`, path: filePath });
+        return undefined;
+    }
+    return parsed;
+}
+function parseOptionalNonNegativeInteger(value) {
+    if (typeof value === "number") {
+        return Number.isInteger(value) && value >= 0 ? value : undefined;
+    }
+    if (typeof value !== "string") {
+        return undefined;
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        return undefined;
+    }
+    const parsed = Number(trimmed);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}
+export function parseSubagentDefinition(options) {
+    const diagnostics = [];
+    let frontmatter;
+    let body;
+    try {
+        const parsed = parseFrontmatter(options.content);
+        if (!isRecord(parsed.frontmatter)) {
+            diagnostics.push({ type: "warning", message: "frontmatter must be a mapping", path: options.filePath });
+            return { definition: null, diagnostics };
+        }
+        frontmatter = parsed.frontmatter;
+        body = parsed.body;
+    }
+    catch (error) {
+        diagnostics.push({
+            type: "warning",
+            message: `failed to parse subagent definition: ${getErrorMessage(error, "invalid frontmatter")}`,
+            path: options.filePath,
+        });
+        return { definition: null, diagnostics };
+    }
+    const name = readRequiredStringField(frontmatter, "name", options.filePath, diagnostics);
+    const description = readRequiredStringField(frontmatter, "description", options.filePath, diagnostics);
+    const systemPrompt = body.trim();
+    if (systemPrompt.length === 0) {
+        diagnostics.push({ type: "warning", message: "system prompt body is required", path: options.filePath });
+    }
+    const policyDiagnosticStart = diagnostics.length;
+    const tools = readCommaSeparatedListField(frontmatter, "tools", options.filePath, diagnostics);
+    const excludedTools = readCommaSeparatedListField(frontmatter, "excludedTools", options.filePath, diagnostics);
+    const allowedSubagents = readAllowedSubagentsField(frontmatter, options.filePath, diagnostics);
+    const maxSubagentDepth = readOptionalNonNegativeIntegerField(frontmatter, "maxSubagentDepth", options.filePath, diagnostics);
+    const maxChildAgents = readOptionalNonNegativeIntegerField(frontmatter, "maxChildAgents", options.filePath, diagnostics);
+    const hasMalformedPolicyField = diagnostics.length > policyDiagnosticStart;
+    const model = readOptionalStringField(frontmatter, "model", options.filePath, diagnostics);
+    const thinking = readOptionalStringField(frontmatter, "thinking", options.filePath, diagnostics);
+    if (!name || !description || systemPrompt.length === 0 || hasMalformedPolicyField) {
+        return { definition: null, diagnostics };
+    }
+    return {
+        definition: {
+            name,
+            description,
+            ...(tools ? { tools } : {}),
+            ...(excludedTools ? { excludedTools } : {}),
+            allowedSubagents: allowedSubagents ?? [],
+            ...(maxSubagentDepth !== undefined ? { maxSubagentDepth } : {}),
+            ...(maxChildAgents !== undefined ? { maxChildAgents } : {}),
+            ...(model ? { model } : {}),
+            ...(thinking ? { thinking } : {}),
+            systemPrompt,
+            source: options.source,
+            sourceInfo: options.sourceInfo,
+            filePath: options.filePath,
+        },
+        diagnostics,
+    };
+}
+function createSubagentSourceInfo(filePath, agentsDir, source) {
+    return createSyntheticSourceInfo(filePath, {
+        source: "local",
+        scope: source,
+        baseDir: agentsDir,
+    });
+}
+function loadSubagentDefinitionsFromDir(dir, source) {
+    const definitions = [];
+    const diagnostics = [];
+    if (!existsSync(dir)) {
+        return { definitions, diagnostics };
+    }
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    }
+    catch (error) {
+        diagnostics.push({
+            type: "warning",
+            message: getErrorMessage(error, "failed to read subagent directory"),
+            path: dir,
+        });
+        return { definitions, diagnostics };
+    }
+    for (const entry of entries) {
+        if (!entry.name.endsWith(".md")) {
+            continue;
+        }
+        const filePath = join(dir, entry.name);
+        let isFile = entry.isFile();
+        if (entry.isSymbolicLink()) {
+            try {
+                isFile = statSync(filePath).isFile();
+            }
+            catch (error) {
+                diagnostics.push({
+                    type: "warning",
+                    message: getErrorMessage(error, "failed to read subagent symlink"),
+                    path: filePath,
+                });
+                continue;
+            }
+        }
+        if (!isFile) {
+            continue;
+        }
+        let content;
+        try {
+            content = readFileSync(filePath, "utf-8");
+        }
+        catch (error) {
+            diagnostics.push({
+                type: "warning",
+                message: getErrorMessage(error, "failed to read subagent definition"),
+                path: filePath,
+            });
+            continue;
+        }
+        const result = parseSubagentDefinition({
+            content,
+            filePath,
+            source,
+            sourceInfo: createSubagentSourceInfo(filePath, dir, source),
+        });
+        if (result.definition) {
+            definitions.push(result.definition);
+        }
+        diagnostics.push(...result.diagnostics);
+    }
+    return { definitions, diagnostics };
+}
+export function discoverSubagentDefinitions(options) {
+    const resolvedCwd = resolvePath(options.cwd);
+    const resolvedAgentDir = resolvePath(options.agentDir);
+    const userAgentsDir = join(resolvedAgentDir, "agents");
+    const projectAgentsDir = join(resolvedCwd, CONFIG_DIR_NAME, "agents");
+    const diagnostics = [];
+    const definitionsByName = new Map();
+    const seenBySource = new Set();
+    const builtInDefinitions = createBuiltInSubagentDefinitions();
+    const reservedBuiltInNames = new Set(builtInDefinitions.map((definition) => definition.name));
+    function addDefinitions(definitions) {
+        for (const definition of definitions) {
+            if (definition.source !== "built-in" && reservedBuiltInNames.has(definition.name)) {
+                diagnostics.push({
+                    type: "warning",
+                    message: `subagent definition "${definition.name}" cannot override a built-in subagent and was ignored`,
+                    path: definition.filePath,
+                });
+                continue;
+            }
+            const sourceKey = `${definition.source}:${definition.name}`;
+            if (seenBySource.has(sourceKey)) {
+                diagnostics.push({
+                    type: "warning",
+                    message: `duplicate ${definition.source} subagent definition "${definition.name}" ignored`,
+                    path: definition.filePath,
+                });
+                continue;
+            }
+            seenBySource.add(sourceKey);
+            definitionsByName.set(definition.name, definition);
+        }
+    }
+    addDefinitions(builtInDefinitions);
+    const userResult = loadSubagentDefinitionsFromDir(userAgentsDir, "user");
+    addDefinitions(userResult.definitions);
+    diagnostics.push(...userResult.diagnostics);
+    if (options.projectTrusted) {
+        const projectResult = loadSubagentDefinitionsFromDir(projectAgentsDir, "project");
+        addDefinitions(projectResult.definitions);
+        diagnostics.push(...projectResult.diagnostics);
+    }
+    return {
+        definitions: Array.from(definitionsByName.values()),
+        diagnostics,
+        userAgentsDir,
+        projectAgentsDir,
+    };
+}
+export { SubagentDelegationScope, } from "./delegation-scope.js";
+export { SubagentDefinitionConfigurationError, SubagentDefinitionNotFoundError, SubagentManager, } from "./manager.js";
+//# sourceMappingURL=index.js.map