openhorse 0.2.19 → 0.2.21

package/dist/runtime/subagents/budget.js

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * Subagent budget ledger: reserve before launch, reconcile after completion.
+ *
+ * The root turn owns an aggregate budget (model requests, tool calls,
+ * model-visible bytes, wall-clock time). Children draw against it. To avoid
+ * over-spending, the Supervisor reserves a per-task allowance up front and
+ * releases the difference once the real usage is known.
+ *
+ * This ledger is the single source of truth for child aggregate usage; the
+ * root loop reads it to fold child cost into `/cost` and loop stats.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SubagentBudgetLedger = exports.TurnTaskState = void 0;
+exports.budgetLimitsFromConfig = budgetLimitsFromConfig;
+const types_1 = require("./types");
+/**
+ * R6: turn-level mutable state shared across all `subtask` calls within one
+ * root turn. Lives on the SubagentTurnBundle so multiple `subtask` tool calls
+ * in the same turn see a consistent counter - the per-batch reset that
+ * previously let a turn exceed `maxTasksPerTurn` is gone.
+ */
+class TurnTaskState {
+    constructor() {
+        this.started = 0;
+    }
+    /** Increment by `n` and return the new total. Called atomically by the
+     * supervisor after policy allows a batch. */
+    addStarted(n) {
+        this.started += n;
+        return this.started;
+    }
+    /** Total tasks started in this root turn (across all `subtask` calls). */
+    tasksStarted() {
+        return this.started;
+    }
+    reset() {
+        this.started = 0;
+    }
+}
+exports.TurnTaskState = TurnTaskState;
+/**
+ * Aggregate budget ledger for one root turn. Not thread-safe by itself;
+ * the Supervisor serializes mutations.
+ *
+ * R6: observed usage is recorded faithfully (never clamped to hide overage).
+ * The enforced allowance and observed usage are modeled separately, so `/cost`
+ * and telemetry reflect the truth while the runtime still stops children that
+ * exceed their allowance.
+ */
+class SubagentBudgetLedger {
+    constructor(limits) {
+        this.reserved = new Map();
+        this.reconciled = [];
+        this.violations = [];
+        this.limits = limits;
+    }
+    /** Reserve model-request slots for a task. Returns false if unavailable. */
+    reserve(taskId, requestedRequests) {
+        if (this.reserved.has(taskId))
+            return null;
+        const want = Math.max(1, Math.min(requestedRequests, this.limits.maxModelRequestsPerTask));
+        if (want > this.availableModelRequests())
+            return null;
+        this.reserved.set(taskId, want);
+        return { taskId, modelRequests: want };
+    }
+    /** Release a reservation without consuming (e.g. task rejected after reserve). */
+    release(taskId) {
+        this.reserved.delete(taskId);
+    }
+    /**
+     * Reconcile actual usage for a task. Releases its reservation and debits
+     * the REAL usage (never clamped). Records a violation if observed usage
+     * exceeded an enforced per-task or aggregate ceiling. Returns true if the
+     * aggregate turn limit is still respected.
+     *
+     * R6: observed usage is stored as-is so `/cost` and telemetry are truthful.
+     */
+    reconcile(taskId, actual) {
+        this.reserved.delete(taskId);
+        // Record observed usage faithfully - do NOT clamp to hide overage.
+        this.reconciled.push({ ...actual });
+        // Record violations: observed exceeded an enforced ceiling.
+        if (actual.modelRequests > this.limits.maxModelRequestsPerTask) {
+            this.violations.push({
+                taskId,
+                limit: 'maxModelRequestsPerTask',
+                observed: actual.modelRequests,
+                enforced: this.limits.maxModelRequestsPerTask,
+            });
+        }
+        if (actual.toolCalls > this.limits.maxToolCallsPerTask) {
+            this.violations.push({
+                taskId,
+                limit: 'maxToolCallsPerTask',
+                observed: actual.toolCalls,
+                enforced: this.limits.maxToolCallsPerTask,
+            });
+        }
+        if (actual.durationMs > this.limits.timeoutMs) {
+            this.violations.push({
+                taskId,
+                limit: 'timeoutMs',
+                observed: actual.durationMs,
+                enforced: this.limits.timeoutMs,
+            });
+        }
+        return this.aggregateUsedModelRequests() <= this.limits.maxModelRequestsPerTurn;
+    }
+    availableModelRequests() {
+        return Math.max(0, this.limits.maxModelRequestsPerTurn - this.aggregateReservedOrUsed());
+    }
+    /**
+     * Whether `count` new tasks can each reserve at least one model request.
+     * NOTE: this checks the minimum (1 request per task), not the full
+     * per-task cap. The supervisor's reserve loop (supervisor.ts:158-179)
+     * handles per-task reserve amounts individually.
+     */
+    canReserveBatch(count) {
+        return this.availableModelRequests() >= count;
+    }
+    snapshot() {
+        const used = (0, types_1.sumSubtaskUsage)(this.reconciled);
+        const reservedModelRequests = (0, types_1.sumSubtaskUsage)(Array.from(this.reserved.entries()).map(([, n]) => ({ ...types_1.EMPTY_SUBTASK_USAGE, modelRequests: n }))).modelRequests;
+        const availableModelRequests = this.availableModelRequests();
+        return {
+            reservedModelRequests,
+            used,
+            availableModelRequests,
+            exhausted: this.aggregateUsedModelRequests() > this.limits.maxModelRequestsPerTurn,
+            violations: [...this.violations],
+        };
+    }
+    /** Reconciled aggregate usage across all completed children. */
+    aggregateUsage() {
+        return (0, types_1.sumSubtaskUsage)(this.reconciled);
+    }
+    /** Number of tasks that have been reconciled (completed/failed/cancelled). */
+    reconciledTaskCount() {
+        return this.reconciled.length;
+    }
+    /** Recorded overage violations (observed exceeded enforced ceiling). */
+    violationsList() {
+        return [...this.violations];
+    }
+    /** True if no reservations are outstanding and no usage has been recorded. */
+    isClean() {
+        return this.reserved.size === 0 && this.reconciled.length === 0;
+    }
+    aggregateReservedOrUsed() {
+        let total = 0;
+        for (const n of this.reserved.values())
+            total += n;
+        for (const u of this.reconciled)
+            total += u.modelRequests;
+        return total;
+    }
+    aggregateUsedModelRequests() {
+        return this.reconciled.reduce((acc, u) => acc + u.modelRequests, 0);
+    }
+}
+exports.SubagentBudgetLedger = SubagentBudgetLedger;
+/** Build limits from a SubagentConfig. */
+function budgetLimitsFromConfig(config) {
+    return {
+        maxModelRequestsPerTurn: config.maxModelRequestsPerTurn,
+        maxModelRequestsPerTask: config.maxModelRequestsPerTask,
+        maxToolCallsPerTask: config.maxToolCallsPerTask,
+        timeoutMs: config.timeoutMs,
+    };
+}
+//# sourceMappingURL=budget.js.map

package/dist/runtime/subagents/budget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget.js","sourceRoot":"","sources":["../../../src/runtime/subagents/budget.ts"],"names":[],"mappings":"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"}

package/dist/runtime/subagents/child-executor-guard.d.ts

@@ -0,0 +1,60 @@
+/**
+ * ChildToolExecutorGuard: enforces project-root and packet-scope isolation.
+ *
+ * R3 (v0.2.20): the policy only canonicalizes scope.paths into the child
+ * prompt, but the actual tool arguments (read_file path, glob base, grep
+ * path, batch_read nested args) were not validated. A child could read
+ * absolute paths, `../` escapes, outside-scope files, or symlink targets
+ * pointing outside the project.
+ *
+ * This guard wraps the child tool executor and performs a realpath-based
+ * containment check on every path-bearing argument before delegating to
+ * the real executor.
+ *
+ * Two containment boundaries:
+ *   1. Canonical project root (always enforced).
+ *   2. Packet scope paths (enforced when the packet specifies a non-empty
+ *      scope). The path must be inside the root AND inside at least one
+ *      scope realpath.
+ */
+export interface GuardOptions {
+    /** Canonical project root (first containment boundary). */
+    rootCwd: string;
+    /** Canonical scope paths (second, stricter boundary). Empty = root only. */
+    scopePaths?: readonly string[];
+}
+export interface GuardRejection {
+    ok: false;
+    tool: string;
+    reason: string;
+    path?: string;
+}
+export interface GuardApproval {
+    ok: true;
+}
+export type GuardVerdict = GuardApproval | GuardRejection;
+/**
+ * Evaluate whether a tool call is allowed under the guard's boundaries.
+ * Pure (modulo realpath reads) so it can be tested in isolation.
+ */
+export declare function evaluateToolCall(tool: string, args: Record<string, unknown>, options: GuardOptions): GuardVerdict;
+/**
+ * A mutable scope holder: the supervisor sets the current packet's scope
+ * before running it, so the turn-level guard can enforce per-packet scope
+ * containment without rebuilding the executor per packet.
+ */
+export declare class ScopeHolder {
+    private current;
+    setScope(paths: readonly string[]): void;
+    clear(): void;
+    getScope(): readonly string[];
+}
+/**
+ * Wrap a child tool executor with containment enforcement. The returned
+ * executor delegates to `inner` only when all path-bearing args are inside
+ * the project root (and inside the packet scope, if the scope holder is set).
+ */
+export declare function createChildToolExecutorGuard(inner: (name: string, args: Record<string, unknown>, abortSignal?: AbortSignal) => Promise<string>, options: GuardOptions & {
+    scopeHolder?: ScopeHolder;
+}): (name: string, args: Record<string, unknown>, abortSignal?: AbortSignal) => Promise<string>;
+//# sourceMappingURL=child-executor-guard.d.ts.map

package/dist/runtime/subagents/child-executor-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-executor-guard.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/child-executor-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiBH,MAAM,WAAW,YAAY;IAC3B,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,KAAK,CAAC;IACV,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,aAAa;IAC5B,EAAE,EAAE,IAAI,CAAC;CACV;AAED,MAAM,MAAM,YAAY,GAAG,aAAa,GAAG,cAAc,CAAC;AA+I1D;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,YAAY,GACpB,YAAY,CAkBd;AAED;;;;GAIG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,OAAO,CAAyB;IAExC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI;IAIxC,KAAK,IAAI,IAAI;IAIb,QAAQ,IAAI,SAAS,MAAM,EAAE;CAG9B;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,KAAK,EAAE,CACL,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,CAAC,EAAE,WAAW,KACtB,OAAO,CAAC,MAAM,CAAC,EACpB,OAAO,EAAE,YAAY,GAAG;IAAE,WAAW,CAAC,EAAE,WAAW,CAAA;CAAE,GACpD,CACD,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,WAAW,CAAC,EAAE,WAAW,KACtB,OAAO,CAAC,MAAM,CAAC,CAgBnB"}

package/dist/runtime/subagents/child-executor-guard.js

@@ -0,0 +1,219 @@
+"use strict";
+/**
+ * ChildToolExecutorGuard: enforces project-root and packet-scope isolation.
+ *
+ * R3 (v0.2.20): the policy only canonicalizes scope.paths into the child
+ * prompt, but the actual tool arguments (read_file path, glob base, grep
+ * path, batch_read nested args) were not validated. A child could read
+ * absolute paths, `../` escapes, outside-scope files, or symlink targets
+ * pointing outside the project.
+ *
+ * This guard wraps the child tool executor and performs a realpath-based
+ * containment check on every path-bearing argument before delegating to
+ * the real executor.
+ *
+ * Two containment boundaries:
+ *   1. Canonical project root (always enforced).
+ *   2. Packet scope paths (enforced when the packet specifies a non-empty
+ *      scope). The path must be inside the root AND inside at least one
+ *      scope realpath.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ScopeHolder = void 0;
+exports.evaluateToolCall = evaluateToolCall;
+exports.createChildToolExecutorGuard = createChildToolExecutorGuard;
+const path_1 = require("path");
+const fs_1 = require("fs");
+/** Tools whose arguments carry a single primary path under key `path`. */
+const PATH_TOOLS = new Set(['read_file', 'list_files']);
+/** Tools whose arguments carry a base/glob root under `path`. */
+const BASE_PATH_TOOLS = new Set(['glob']);
+/** Tools whose arguments carry a search base under `path`. */
+const SEARCH_PATH_TOOLS = new Set(['grep']);
+/** batch_read nests step args; each step has { tool, args }. */
+const BATCH_TOOL = 'batch_read';
+/**
+ * Return the realpath of the nearest existing ancestor of `p`.
+ *
+ * This handles not-yet-created paths (the target doesn't exist, but its
+ * parent dir does) and symlinked parent directories: we walk up until we
+ * find a path that exists, then resolve its realpath. Symlink escapes in
+ * an existing ancestor are caught because realpath resolves them.
+ */
+function nearestExistingAncestorRealpath(p) {
+    let current = p;
+    for (let i = 0; i < 64; i++) {
+        if ((0, fs_1.existsSync)(current)) {
+            try {
+                return (0, fs_1.realpathSync)(current);
+            }
+            catch (err) {
+                // Distinguish ENOENT (path disappeared between existsSync and realpathSync)
+                // from permission/I/O errors. ENOENT: continue walking up. Others: fail.
+                const code = err?.code;
+                if (code === 'ENOENT') {
+                    // Path vanished between existsSync and realpathSync (TOCTOU).
+                    // Continue walking up to find an existing ancestor.
+                    const parent = (0, path_1.resolve)(current, '..');
+                    if (parent === current)
+                        return undefined;
+                    current = parent;
+                    continue;
+                }
+                // EACCES, EIO, etc: cannot resolve realpath — treat as unresolvable.
+                // Returning undefined signals to the caller that containment cannot be
+                // verified, and the path should be rejected.
+                return undefined;
+            }
+        }
+        const parent = (0, path_1.resolve)(current, '..');
+        if (parent === current)
+            return undefined; // filesystem root, no existing ancestor
+        current = parent;
+    }
+    return undefined; // loop exhausted, no existing ancestor found
+}
+/** True if `candidate` is `ancestor` or inside it (both realpaths). */
+function isInsideOrEqual(candidate, ancestor) {
+    if (candidate === ancestor)
+        return true;
+    const rel = (0, path_1.relative)(ancestor, candidate);
+    return rel !== '' && !rel.startsWith('..') && !(0, path_1.isAbsolute)(rel);
+}
+/**
+ * Check that a path stays inside root (and inside a scope if scopes given).
+ *
+ * Strategy: resolve the path against root, then take the realpath of its
+ * nearest existing ancestor. If that ancestor is outside root, the path
+ * escapes (via `..`, absolute outside root, or symlinked parent). If scopes
+ * are specified, the ancestor must also be inside a scope OR the path must
+ * descend into a scope from the root (ancestor is root itself, remaining
+ * suffix enters a scope).
+ */
+function checkContainment(rawPath, rootReal, scopeReals) {
+    if (typeof rawPath !== 'string' || rawPath.trim() === '') {
+        return { contained: false, reason: 'empty path' };
+    }
+    const resolved = (0, path_1.resolve)(rootReal, rawPath);
+    const ancestorReal = nearestExistingAncestorRealpath(resolved);
+    // If no existing ancestor could be resolved (e.g. EACCES on realpathSync),
+    // containment cannot be verified — reject the path.
+    if (ancestorReal === undefined) {
+        return { contained: false, reason: `cannot verify path containment: ${rawPath}` };
+    }
+    // Boundary 1: must be inside root.
+    if (!isInsideOrEqual(ancestorReal, rootReal)) {
+        return { contained: false, reason: `path escapes project root: ${rawPath}` };
+    }
+    // Boundary 2: if scopes specified, the target must be inside a scope.
+    if (scopeReals.length > 0) {
+        // If the ancestor is already inside a scope, ok.
+        const ancestorInScope = scopeReals.some(s => isInsideOrEqual(ancestorReal, s));
+        if (!ancestorInScope) {
+            // Ancestor is root (or above scope) but target may descend into a
+            // scope. Re-resolve the full target's nearest-existing-ancestor
+            // against each scope: the resolved path relative to root must, when
+            // joined, fall inside a scope realpath.
+            const targetInScope = scopeReals.some(s => {
+                // Compute where the target would resolve to relative to root, then
+                // check containment against the scope realpath.
+                const targetResolved = (0, path_1.resolve)(rootReal, rawPath);
+                const targetAncestor = nearestExistingAncestorRealpath(targetResolved);
+                return targetAncestor !== undefined && isInsideOrEqual(targetAncestor, s);
+            });
+            if (!targetInScope) {
+                return { contained: false, reason: `path outside packet scope: ${rawPath}` };
+            }
+        }
+    }
+    return { contained: true };
+}
+/** Extract path-bearing arguments from a tool call. */
+function extractPathArgs(tool, args) {
+    const paths = [];
+    if (PATH_TOOLS.has(tool) ||
+        BASE_PATH_TOOLS.has(tool) ||
+        SEARCH_PATH_TOOLS.has(tool)) {
+        const p = args.path;
+        if (typeof p === 'string') {
+            paths.push(p);
+        }
+        // glob/grep with no path default to cwd (inside root) - no check needed.
+    }
+    if (tool === BATCH_TOOL) {
+        const steps = args.steps;
+        if (Array.isArray(steps)) {
+            for (const step of steps) {
+                if (step && typeof step === 'object' && typeof step.tool === 'string') {
+                    const stepArgs = step.args && typeof step.args === 'object'
+                        ? step.args
+                        : {};
+                    paths.push(...extractPathArgs(step.tool, stepArgs));
+                }
+            }
+        }
+    }
+    return paths;
+}
+/**
+ * Evaluate whether a tool call is allowed under the guard's boundaries.
+ * Pure (modulo realpath reads) so it can be tested in isolation.
+ */
+function evaluateToolCall(tool, args, options) {
+    const rootReal = nearestExistingAncestorRealpath(options.rootCwd);
+    if (rootReal === undefined) {
+        return { ok: false, tool, reason: 'cannot resolve project root realpath' };
+    }
+    const scopeReals = (options.scopePaths ?? []).map(p => nearestExistingAncestorRealpath((0, path_1.resolve)(rootReal, p))).filter((s) => s !== undefined);
+    const pathArgs = extractPathArgs(tool, args);
+    for (const path of pathArgs) {
+        const verdict = checkContainment(path, rootReal, scopeReals);
+        if (!verdict.contained) {
+            return { ok: false, tool, reason: verdict.reason ?? 'path rejected', path };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * A mutable scope holder: the supervisor sets the current packet's scope
+ * before running it, so the turn-level guard can enforce per-packet scope
+ * containment without rebuilding the executor per packet.
+ */
+class ScopeHolder {
+    constructor() {
+        this.current = [];
+    }
+    setScope(paths) {
+        this.current = paths;
+    }
+    clear() {
+        this.current = [];
+    }
+    getScope() {
+        return this.current;
+    }
+}
+exports.ScopeHolder = ScopeHolder;
+/**
+ * Wrap a child tool executor with containment enforcement. The returned
+ * executor delegates to `inner` only when all path-bearing args are inside
+ * the project root (and inside the packet scope, if the scope holder is set).
+ */
+function createChildToolExecutorGuard(inner, options) {
+    return async (name, args, abortSignal) => {
+        const scopePaths = options.scopeHolder?.getScope() ?? options.scopePaths ?? [];
+        const verdict = evaluateToolCall(name, args, {
+            rootCwd: options.rootCwd,
+            scopePaths,
+        });
+        if (!verdict.ok) {
+            return JSON.stringify({
+                success: false,
+                output: '',
+                error: `Subagent scope guard rejected ${verdict.tool}: ${verdict.reason}`,
+            });
+        }
+        return inner(name, args, abortSignal);
+    };
+}
+//# sourceMappingURL=child-executor-guard.js.map

package/dist/runtime/subagents/child-executor-guard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-executor-guard.js","sourceRoot":"","sources":["../../../src/runtime/subagents/child-executor-guard.ts"],"names":[],"mappings":"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"}

package/dist/runtime/subagents/context-builder.d.ts

@@ -0,0 +1,34 @@
+/**
+ * SubagentContextBuilder: assembles the independent child message context.
+ *
+ * A child does NOT inherit the parent's full transcript. It receives a role
+ * system prompt, a read-only summary of the root objective, and the specific
+ * task packet with canonical scope. Optional capsule/evidence are injected only
+ * when available, kept compact to avoid polluting the child context.
+ */
+import type { Message } from '../../services/llm';
+import type { ContextCapsule } from '../../harness/types';
+import type { SubtaskPacket } from './types';
+export interface ChildContextInputs {
+    /** Canonical project root the child operates in. */
+    cwd: string;
+    /** The task packet (objective, scope, expectedOutput, hints). */
+    packet: SubtaskPacket;
+    /** Canonical scope paths already validated by policy. */
+    canonicalScopePaths?: string[];
+    /** Read-only summary of the root objective; never the full parent transcript. */
+    rootObjectiveSummary?: string;
+    /** Parent harness capsule, compacted to its salient fields. */
+    capsule?: ContextCapsule;
+    /** Model/provider info shown to the child so it understands its limits. */
+    modelLabel?: string;
+    /** Active project instructions / skill guidance (read-only). */
+    projectInstructions?: string;
+}
+/**
+ * Build the child message list. The first message is always the role system
+ * prompt; a single user message frames the task. The child loop appends its
+ * own assistant/tool messages on top of this.
+ */
+export declare function buildChildMessages(inputs: ChildContextInputs): Message[];
+//# sourceMappingURL=context-builder.d.ts.map

package/dist/runtime/subagents/context-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/context-builder.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAE1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAE7C,MAAM,WAAW,kBAAkB;IACjC,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAC;IACZ,iEAAiE;IACjE,MAAM,EAAE,aAAa,CAAC;IACtB,yDAAyD;IACzD,mBAAmB,CAAC,EAAE,MAAM,EAAE,CAAC;IAC/B,iFAAiF;IACjF,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,OAAO,CAAC,EAAE,cAAc,CAAC;IACzB,2EAA2E;IAC3E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gEAAgE;IAChE,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,EAAE,CAwDxE"}

package/dist/runtime/subagents/context-builder.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * SubagentContextBuilder: assembles the independent child message context.
+ *
+ * A child does NOT inherit the parent's full transcript. It receives a role
+ * system prompt, a read-only summary of the root objective, and the specific
+ * task packet with canonical scope. Optional capsule/evidence are injected only
+ * when available, kept compact to avoid polluting the child context.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildChildMessages = buildChildMessages;
+const presets_1 = require("./presets");
+/**
+ * Build the child message list. The first message is always the role system
+ * prompt; a single user message frames the task. The child loop appends its
+ * own assistant/tool messages on top of this.
+ */
+function buildChildMessages(inputs) {
+    const { packet, cwd } = inputs;
+    const systemPrompt = assembleSystemPrompt(inputs);
+    const userPrompt = assembleUserPrompt(inputs);
+    return [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: userPrompt },
+    ];
+    function assembleSystemPrompt(i) {
+        const rolePrompt = (0, presets_1.systemPromptForRole)(packet.role);
+        const lines = [rolePrompt, ''];
+        lines.push(`# Operating context`);
+        lines.push(`- Project root: ${cwd}`);
+        if (i.modelLabel)
+            lines.push(`- Model: ${i.modelLabel}`);
+        lines.push('- You are a child agent at delegation depth 1. You may NOT create further subagents.');
+        lines.push('- You may NOT edit, write, delete, commit, push, publish, install, or run shell commands.');
+        if (i.rootObjectiveSummary) {
+            lines.push('');
+            lines.push(`# Root objective (read-only summary)`);
+            lines.push(truncate(i.rootObjectiveSummary, 800));
+        }
+        if (i.projectInstructions) {
+            lines.push('');
+            lines.push(`# Project instructions (read-only)`);
+            lines.push(truncate(i.projectInstructions, 1200));
+        }
+        if (i.capsule) {
+            lines.push('');
+            lines.push(`# Parent context capsule (read-only)`);
+            lines.push(compactCapsule(i.capsule));
+        }
+        return lines.join('\n');
+    }
+    function assembleUserPrompt(i) {
+        const lines = [];
+        lines.push(`## Task`);
+        lines.push(`role: ${packet.role}`);
+        lines.push(`objective: ${packet.objective}`);
+        if (packet.reason)
+            lines.push(`reason: ${packet.reason}`);
+        if (i.canonicalScopePaths && i.canonicalScopePaths.length > 0) {
+            lines.push(`scope: ${i.canonicalScopePaths.join(', ')}`);
+        }
+        if (packet.contextHints && packet.contextHints.length > 0) {
+            lines.push(`hints:`);
+            for (const hint of packet.contextHints)
+                lines.push(`  - ${hint}`);
+        }
+        if (packet.expectedOutput) {
+            lines.push(`expected output: ${packet.expectedOutput}`);
+        }
+        lines.push('');
+        lines.push('Investigate now using only the read-only tools available to you, then emit the JSON result object as specified in your system prompt.');
+        return lines.join('\n');
+    }
+}
+function compactCapsule(capsule) {
+    const lines = [];
+    if (capsule.contract?.objective)
+        lines.push(`- contract objective: ${truncate(capsule.contract.objective, 200)}`);
+    if (capsule.completed.length > 0)
+        lines.push(`- completed: ${truncate(capsule.completed.join('; '), 300)}`);
+    if (capsule.openTodos.length > 0)
+        lines.push(`- open todos: ${truncate(capsule.openTodos.join('; '), 300)}`);
+    if (capsule.changedFiles.length > 0)
+        lines.push(`- changed files: ${truncate(capsule.changedFiles.join(', '), 300)}`);
+    if (capsule.keyFacts.length > 0) {
+        lines.push(`- key facts:`);
+        for (const fact of capsule.keyFacts.slice(0, 5))
+            lines.push(`  - ${truncate(fact.content, 160)}`);
+    }
+    if (capsule.nextAction)
+        lines.push(`- next action: ${truncate(capsule.nextAction, 200)}`);
+    return lines.length > 0 ? lines.join('\n') : '(no capsule fields)';
+}
+function truncate(text, max) {
+    if (text.length <= max)
+        return text;
+    return `${text.slice(0, max - 1)}…`;
+}
+//# sourceMappingURL=context-builder.js.map

package/dist/runtime/subagents/context-builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-builder.js","sourceRoot":"","sources":["../../../src/runtime/subagents/context-builder.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,21 @@
+/**
+ * Subagent runtime public surface.
+ *
+ * v0.2.20 exposes a read-only subagent runtime. The root Agent may request
+ * 1-3 independent investigation packets; a Supervisor runs them as isolated
+ * child agents under a unified budget, permission boundary and trace.
+ */
+export * from './types';
+export * from './presets';
+export { evaluateSubtaskPolicy, canonicalizeScopePaths, hasExplicitDelegationIntent, clampSubagentConfig, type PolicyContext, type PolicyVerdict, type PolicyRejectReason, } from './policy';
+export { SubagentBudgetLedger, TurnTaskState, budgetLimitsFromConfig, type SubagentBudgetLimits, type ReservedBudget, type BudgetSnapshot, type BudgetViolation, } from './budget';
+export { buildChildMessages, type ChildContextInputs } from './context-builder';
+export { parseSubtaskResult, extractJsonObject, type ParsedSubtaskPayload } from './result-parser';
+export { createChildToolExecutorGuard, evaluateToolCall, ScopeHolder, type GuardOptions, type GuardVerdict, } from './child-executor-guard';
+export { runSubtask, type SubagentRunnerDeps, type ChildToolSet, type ExecuteChildQuery, type RunSubtaskOutcome, } from './runner';
+export { SubagentProviderGate, type ProviderGateOptions, } from './provider-gate';
+export { runSubtaskBatch, type SubagentSupervisorDeps, type RunBatchOutcome, } from './supervisor';
+export { createSubtaskTool, coerceSubtaskRequest, summarizeBatchForModel, } from './tool';
+export { createProductionExecuteQuery, createChildLlmConfig, type SubagentLlmFactoryDeps, } from './production';
+export { createSubagentToolForTurn, createSubagentBundleForTurn, deriveRootLlmConfig, type SubagentTurnInputs, type SubagentTurnBundle, } from './runtime-integration';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/runtime/subagents/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,GACxB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,oBAAoB,EACpB,aAAa,EACb,sBAAsB,EACtB,KAAK,oBAAoB,EACzB,KAAK,cAAc,EACnB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AACnG,OAAO,EACL,4BAA4B,EAC5B,gBAAgB,EAChB,WAAW,EACX,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,UAAU,EACV,KAAK,kBAAkB,EACvB,KAAK,YAAY,EACjB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,GACvB,MAAM,UAAU,CAAC;AAClB,OAAO,EACL,oBAAoB,EACpB,KAAK,mBAAmB,GACzB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EACf,KAAK,sBAAsB,EAC3B,KAAK,eAAe,GACrB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,iBAAiB,EACjB,oBAAoB,EACpB,sBAAsB,GACvB,MAAM,QAAQ,CAAC;AAChB,OAAO,EACL,4BAA4B,EAC5B,oBAAoB,EACpB,KAAK,sBAAsB,GAC5B,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,mBAAmB,EACnB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,GACxB,MAAM,uBAAuB,CAAC"}