aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/selfimprovement/signatureBuilder.js

@@ -0,0 +1,158 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/selfimprovement/signatureBuilder.ts — v4.6 Phase 3b.
+ *
+ * Builds a stable, deterministic signature string for a failed tool
+ * call so equivalent failures collapse into one `failure_signatures`
+ * row. The shape is:
+ *
+ *     <tool_name>:<failure_category>[:<args_hash_prefix>]
+ *
+ * The `args_hash_prefix` field is OPTIONAL. When the caller supplies
+ * `args`, this module normalises them (strips volatile fields like
+ * timestamps, run IDs, UUIDs, monotonic counters), serialises the
+ * result deterministically, and takes the first 6 hex chars of a
+ * SHA-256 digest. When `args` is omitted, the signature collapses to
+ * `<tool>:<category>` only — same logical failure, broader grouping.
+ *
+ * Granularity trade-offs:
+ *
+ *   * Too granular ("every failure unique") → no aggregation; the
+ *     `occurrences` column never increments past 1; operators can't
+ *     see "this tool fails the same way over and over."
+ *   * Too coarse ("only tool+category") → "file_read failed with
+ *     `not_found`" groups EVERY missing file together; the operator
+ *     can't tell which paths are sore points.
+ *
+ * The args-hash compromise: same tool + same category + same
+ * normalized args → same signature (good); same tool + same category
+ * + meaningfully different args → different signatures (also good).
+ * Volatile fields are stripped BEFORE hashing so re-hashing on a
+ * later turn produces the same signature even when only the
+ * timestamp / call id changes.
+ *
+ * Volatile field list (`VOLATILE_KEYS`) — defensive; covers the
+ * fields Aiden's tool layer tends to thread through args. Plugin
+ * authors who emit custom volatile keys should pre-normalise before
+ * calling this module.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildFailureSignature = buildFailureSignature;
+const node_crypto_1 = __importDefault(require("node:crypto"));
+// ── Implementation ───────────────────────────────────────────────────────
+/**
+ * Keys whose values are stripped from the args object before hashing.
+ * These are fields that DO change between otherwise-identical
+ * failures (turn timestamps, run row ids, etc.) so leaving them in
+ * would prevent any signature from ever grouping.
+ *
+ * The list is intentionally narrow — only fields Aiden's tool layer
+ * is known to inject. Plugins emitting custom volatile keys must
+ * pre-normalise their args before calling this module.
+ */
+const VOLATILE_KEYS = new Set([
+    'timestamp',
+    'ts',
+    'requestId',
+    'request_id',
+    'runId',
+    'run_id',
+    'callId',
+    'call_id',
+    'sessionId',
+    'session_id',
+    'turnId',
+    'turn_id',
+    'eventId',
+    'event_id',
+    'createdAt',
+    'created_at',
+    'updatedAt',
+    'updated_at',
+    // Common UUID/idempotency-key names.
+    'uuid',
+    'idempotencyKey',
+    'idempotency_key',
+]);
+/**
+ * Deterministically stringify a value. Sorts object keys so
+ * `{a:1, b:2}` and `{b:2, a:1}` produce identical bytes. Strips
+ * volatile keys from any nested object before stringifying.
+ *
+ * Non-JSON-serialisable values (functions, symbols, circular refs)
+ * collapse to the literal string `'[unserializable]'` so the hash
+ * remains stable. Better-than-throwing is the right trade-off for
+ * a write-through hot path.
+ */
+function deterministicStringify(value) {
+    const seen = new WeakSet();
+    const visit = (v) => {
+        if (v === null || v === undefined)
+            return null;
+        const t = typeof v;
+        if (t === 'string' || t === 'number' || t === 'boolean')
+            return v;
+        if (t === 'function' || t === 'symbol')
+            return '[unserializable]';
+        if (typeof v === 'bigint')
+            return v.toString();
+        if (Array.isArray(v)) {
+            if (seen.has(v))
+                return '[circular]';
+            seen.add(v);
+            return v.map(visit);
+        }
+        if (t === 'object') {
+            const obj = v;
+            if (seen.has(obj))
+                return '[circular]';
+            seen.add(obj);
+            const out = {};
+            const keys = Object.keys(obj).filter((k) => !VOLATILE_KEYS.has(k));
+            keys.sort();
+            for (const k of keys)
+                out[k] = visit(obj[k]);
+            return out;
+        }
+        return '[unserializable]';
+    };
+    try {
+        return JSON.stringify(visit(value));
+    }
+    catch {
+        return '[unserializable]';
+    }
+}
+/**
+ * Build a failure signature. Pure function — no I/O, no side
+ * effects. Safe to call on the hot path of every classified
+ * failure; SHA-256 of a small JSON string is cheap (microseconds).
+ */
+function buildFailureSignature(input) {
+    const base = `${input.toolName}:${input.category}`;
+    if (input.args === undefined) {
+        return { signature: base };
+    }
+    const normalized = deterministicStringify(input.args);
+    // Empty / trivially-null args don't deserve a hash suffix —
+    // collapse to the base signature so "args: {}" and "no args"
+    // group together.
+    if (normalized === 'null' || normalized === '{}' || normalized === '[]') {
+        return { signature: base };
+    }
+    const digest = node_crypto_1.default.createHash('sha256').update(normalized).digest('hex');
+    const argsHash = digest.slice(0, 6);
+    return {
+        signature: `${base}:${argsHash}`,
+        argsHash,
+    };
+}

package/dist/core/v4/subagent/childBuilder.js

@@ -0,0 +1,391 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/childBuilder.ts — v4.6 Phase 1.
+ *
+ * Constructs the child `AidenAgent` for one `spawn_sub_agent` call.
+ * Mirrors the closure-capture shape of `cli/v4/daemonAgentBuilder.ts`
+ * — shared deps captured at REPL bootstrap, fresh per-spawn state
+ * built inline.
+ *
+ * Per the design doc §5 state-isolation matrix:
+ *   - Conversation history, system prompt, TCE, file-op cache:
+ *     ISOLATED (child gets fresh).
+ *   - Toolset: intersection of (parent's enabled toolsets) ∩
+ *     (spec.toolsets or parent's full set) MINUS the hard blocklist.
+ *   - Provider + model + credentials: INHERITED (same adapter).
+ *   - FallbackAdapter rate-limit state: CLONED per child (when the
+ *     adapter exposes `clone()`) so a child's 429 doesn't poison
+ *     the parent's quota tracking.
+ *   - ApprovalEngine: fresh instance with auto-deny callbacks
+ *     (child cannot prompt the user).
+ *   - plannerGuard / honestyEnforcement / skillTeacher / skillMiner:
+ *     OMITTED (focused worker config, matching daemon agent shape).
+ *   - Working directory / sandbox / runtimeToggles: shared via the
+ *     process-level singletons read on each tool dispatch.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProviderNotFoundError = exports.SUBAGENT_BLOCKED_TOOL_NAMES = void 0;
+exports.buildChildAgent = buildChildAgent;
+const approvalEngine_1 = require("../../../moat/approvalEngine");
+const aidenAgent_1 = require("../aidenAgent");
+const providerFallback_1 = require("../providerFallback");
+// ── Hard-coded blocklist (Q5 from design doc §2) ────────────────────────────
+/**
+ * Tools children must NEVER receive, even if the parent's enabled toolsets
+ * cover them and the spec explicitly requests them. Filtered post-intersection.
+ *
+ * Each entry's rationale, in order:
+ *   - `spawn_sub_agent` — no recursive spawning (depth cap = 1 in Phase 1)
+ *   - `clarify`         — child cannot prompt the user
+ *   - `memory`          — no writes to shared MEMORY.md / USER.md
+ *   - `execute_code`    — children reason step-by-step, not write scripts
+ *   - `send_message`    — no cross-platform side effects from a child
+ */
+exports.SUBAGENT_BLOCKED_TOOL_NAMES = new Set([
+    'spawn_sub_agent',
+    'clarify',
+    'memory',
+    'execute_code',
+    'send_message',
+]);
+/**
+ * v4.6 Phase 2P — error thrown by `buildChildAgent` when
+ * `input.providerOverride` doesn't match any provider in the
+ * parent's pool. Caught by `spawnSubAgent` and converted to a
+ * `status: 'failed', exitReason: 'provider_not_found'` envelope
+ * with the failing name + the list of valid alternatives.
+ */
+class ProviderNotFoundError extends Error {
+    constructor(requested, available, hint) {
+        const base = `spawn_sub_agent: provider "${requested}" not in parent's pool.`;
+        const list = available.length > 0
+            ? ` Available: ${available.join(', ')}.`
+            : ' Parent has no FallbackAdapter pool (single-provider configuration).';
+        super(`${base}${list}${hint ? ' ' + hint : ' Omit the provider field to inherit the parent\'s provider.'}`);
+        this.name = 'ProviderNotFoundError';
+        this.requested = requested;
+        this.available = available;
+    }
+}
+exports.ProviderNotFoundError = ProviderNotFoundError;
+// ── Implementation ──────────────────────────────────────────────────────────
+/**
+ * Build the child agent + initial history. Pure factory — no side
+ * effects beyond constructing in-memory objects. The caller is
+ * responsible for running `agent.runConversation(...)` and writing
+ * the `runs` row.
+ */
+function buildChildAgent(deps, input) {
+    // ── 1. ApprovalEngine: fresh, auto-deny callbacks ────────────────────────
+    // 'smart' mode: safe auto-allows, dangerous auto-denies, caution
+    // calls promptUser which we wire to a synchronous deny — children
+    // cannot interact with a TUI.
+    const autoDenyCallbacks = {
+        promptUser: async () => 'deny',
+    };
+    const childApprovalEngine = new approvalEngine_1.ApprovalEngine('smart', autoDenyCallbacks);
+    // ── 2. ToolContext: parent's services + child approval engine + session ──
+    const childToolContext = {
+        ...deps.parentToolContext,
+        sessionId: input.sessionId,
+        approvalEngine: childApprovalEngine,
+    };
+    // ── 3. Build the child's toolExecutor from the parent's registry ─────────
+    // Same registry, different context. The registry stays read-only.
+    const childToolExecutor = deps.toolRegistry.buildExecutor(childToolContext);
+    // ── 4. Tool array: intersection + blocklist filter ───────────────────────
+    // Step 4a — pick the parent's toolsets we care about.
+    // If the spec named toolsets, intersect with the parent's known set.
+    // Otherwise the child gets the parent's full enabled set (which on
+    // REPL means every toolset the registry knows).
+    const allHandlers = deps.toolRegistry.list();
+    const parentToolsetNames = new Set();
+    for (const name of allHandlers) {
+        const handler = deps.toolRegistry.get(name);
+        if (handler?.toolset)
+            parentToolsetNames.add(handler.toolset);
+    }
+    let chosenToolsets = input.requestedToolsets && input.requestedToolsets.length > 0
+        ? input.requestedToolsets.filter((t) => parentToolsetNames.has(t))
+        : [...parentToolsetNames];
+    // v4.6 Phase 1 (Dispatch 2L) — zero-tools-bug fallback. When the
+    // model passes `toolsets: [...]` with values that DON'T match any
+    // real registry toolset (e.g. `["functions"]`, a name fabricated
+    // from the OpenAI tool-use vocabulary, or `["file_operations"]`, a
+    // skill name confused for a toolset), the strict filter strips all
+    // entries → `chosenToolsets` is `[]` → child gets ZERO tools → it
+    // hallucinates an answer rather than admit it can't do the work.
+    //
+    // Recover by inheriting the full parent set when the requested
+    // names ALL miss. Logs a warning so the operator sees what the
+    // model asked for and what real names exist. Partial intersections
+    // (some valid, some invalid) keep the valid subset — that's the
+    // user's explicit narrowing intent, not a bug.
+    if (input.requestedToolsets && input.requestedToolsets.length > 0 &&
+        chosenToolsets.length === 0) {
+        deps.logger?.warn?.('spawn_sub_agent: requested toolsets stripped to empty, falling back to full parent set', {
+            requested: input.requestedToolsets,
+            validParentToolsets: [...parentToolsetNames],
+        });
+        chosenToolsets = [...parentToolsetNames];
+    }
+    // Step 4b — pull the schemas for those toolsets.
+    // v4.6 Phase 1 — pass 'repl' context: in Phase 1 spawn_sub_agent
+    // is REPL-only (Q6), so children always spawn from a REPL parent.
+    // Phase 3+ may extend the child builder to receive the parent's
+    // context dynamically; for now, 'repl' is the only path.
+    const candidateSchemas = chosenToolsets.length > 0
+        ? deps.toolRegistry.getSchemas(chosenToolsets, 'repl')
+        : []; // No matching toolsets means an empty child toolset.
+    // Step 4c — strip the hard blocklist (with v4.6 Phase 2P legacy
+    // env-flag escape hatch per design doc §12.4). Default: full
+    // 5-name blocklist. When AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE=1 is
+    // set in the environment, `execute_code` is removed from the
+    // blocklist for THIS spawn — backward-compat preservation of any
+    // user's existing v4.1.0 .env workflow. The other 4 names
+    // (spawn_sub_agent, clarify, memory, send_message) remain
+    // blocked regardless of the flag.
+    const blocked = resolveBlocklist(deps.logger);
+    const childTools = candidateSchemas.filter((t) => !blocked.has(t.name));
+    // ── 5. Provider: clone FallbackAdapter rate-limit state if supported ─────
+    // Per Q11 (verbatim mirror of providerFallback.ts:578 clone pattern).
+    // Best-effort — if the adapter doesn't expose `clone()`, fall back to
+    // sharing the parent's adapter. Phase 1 accepts that fallback case
+    // means a child's 429 affects the parent's quota tracking; that's
+    // explicit in the design-doc §5 row.
+    //
+    // v4.6 Phase 2P — when `input.providerOverride` is supplied, resolve
+    // it against the parent's FallbackAdapter slot pool. Fail-loud on
+    // unknown names (`ProviderNotFoundError`) so fanout's diversity
+    // invariant is preserved (silent fallback would collapse the
+    // rotation). Single-provider parents (non-FallbackAdapter) reject
+    // any override, since there's no pool to select from.
+    const childProvider = resolveChildProvider(deps.parentProvider, input.providerOverride);
+    // ── 6. Observability — onToolCall → run_events + log ─────────────────────
+    // When deps.runStore + deps.childRunId are present (the production
+    // path from spawnSubAgent.ts), wire an `onToolCall` callback that
+    // mirrors the daemon dispatcher's audit shape (see
+    // `core/v4/daemon/dispatcher/realAgentRunner.ts:367-382`). Per-call
+    // start time is tracked in a Map keyed by tool_call_id so the
+    // `durationMs` on completed events is per-tool, not per-turn.
+    // Pure no-op when runStore is absent (unit tests of buildChildAgent).
+    const onToolCall = buildOnToolCall(deps);
+    // ── 7. Build the child agent ─────────────────────────────────────────────
+    // Focused worker config: omit plannerGuard, honestyEnforcement,
+    // skillTeacher, skillMiner, contextCompressor, promptCaching,
+    // promptBuilder. Match the daemon agent's "act on the task, don't
+    // self-improve" shape.
+    const agent = new aidenAgent_1.AidenAgent({
+        provider: childProvider,
+        tools: childTools,
+        toolExecutor: childToolExecutor,
+        sessionId: input.sessionId,
+        maxTurns: input.maxIterations,
+        providerId: deps.parentProviderId,
+        modelId: deps.parentModelId,
+        resolveVerifiedFlag: deps.resolveVerifiedFlag,
+        resolveToolset: deps.resolveToolset,
+        resolveMutates: deps.resolveMutates,
+        onToolCall,
+        // iterationBudgetInjection inherits the default (true) — child
+        // sees its own remaining-budget hint near the end of the run.
+    });
+    // ── 7. Initial history: fresh system prompt + the user-shaped goal ───────
+    const systemContent = buildChildSystemPrompt(input.goal, input.context);
+    const userContent = composeUserMessage(input.goal, input.context);
+    const history = [
+        { role: 'system', content: systemContent },
+        { role: 'user', content: userContent },
+    ];
+    return { agent, history };
+}
+// ── Helpers ─────────────────────────────────────────────────────────────────
+/**
+ * v4.6 Phase 2P — resolve the child's provider adapter.
+ *
+ * No override (Phase 1 behavior unchanged):
+ *   - FallbackAdapter → clone with fresh mutable state, all slots.
+ *   - Any other adapter shape with `clone()` → clone.
+ *   - Adapter without `clone()` → reuse the parent's instance.
+ *
+ * Override supplied (Phase 2P):
+ *   - Parent must be FallbackAdapter (only adapter type with a
+ *     multi-provider pool). Otherwise throw `ProviderNotFoundError`.
+ *   - Override must match one of `parent.getProviderIds()`. Otherwise
+ *     throw `ProviderNotFoundError` listing the available pool.
+ *   - On match: clone with slot-subset filter restricted to that
+ *     provider's slots. Child rotates only within the chosen
+ *     provider's slots; the diversity invariant fanout depends on
+ *     is preserved.
+ */
+function resolveChildProvider(parent, override) {
+    if (!override) {
+        // ── No override path — Phase 1 clone semantics, unchanged. ────────
+        const maybeClone = parent.clone;
+        if (typeof maybeClone === 'function') {
+            try {
+                return maybeClone.call(parent);
+            }
+            catch {
+                return parent;
+            }
+        }
+        return parent;
+    }
+    // ── Override path — must be FallbackAdapter. ───────────────────────
+    if (!(parent instanceof providerFallback_1.FallbackAdapter)) {
+        throw new ProviderNotFoundError(override, [], 'Parent agent uses a single-provider adapter; provider override is only available when parent is configured with FallbackAdapter (multi-provider pool).');
+    }
+    const available = parent.getProviderIds();
+    if (!available.includes(override)) {
+        throw new ProviderNotFoundError(override, available);
+    }
+    return parent.clone({ providerId: override });
+}
+/**
+ * v4.6 Phase 2P — resolve the effective tool blocklist for THIS
+ * child build. Default is the full 5-name set
+ * (`SUBAGENT_BLOCKED_TOOL_NAMES`). When
+ * `AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE=1` (or any truthy value) is
+ * present in `process.env`, drop `execute_code` — preserves the
+ * v4.1.0 fanout escape hatch for users with that flag in `.env`.
+ * Other 4 names stay blocked regardless.
+ *
+ * Logs a one-line warning when the escape hatch is active so the
+ * relaxation is visible in observability — silently relaxing a
+ * security boundary is exactly the failure mode we want to avoid.
+ */
+function resolveBlocklist(logger) {
+    const raw = process.env.AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE;
+    if (!raw)
+        return exports.SUBAGENT_BLOCKED_TOOL_NAMES;
+    const flag = String(raw).trim().toLowerCase();
+    if (flag === '1' || flag === 'true' || flag === 'on' || flag === 'yes') {
+        logger?.warn?.('spawn_sub_agent: AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE escape hatch active; ' +
+            'execute_code dropped from child blocklist (other 4 names still blocked)', { source: 'env', flag: raw });
+        const relaxed = new Set(exports.SUBAGENT_BLOCKED_TOOL_NAMES);
+        relaxed.delete('execute_code');
+        return relaxed;
+    }
+    return exports.SUBAGENT_BLOCKED_TOOL_NAMES;
+}
+/**
+ * Compose the child's system prompt. Intentionally minimal — no
+ * SOUL.md, no parent identity, no MEMORY.md preamble. Goal-focused.
+ */
+function buildChildSystemPrompt(goal, context) {
+    const lines = [
+        'You are a focused sub-agent dispatched to handle ONE concrete task.',
+        'You have no memory of any prior conversation — only the goal and',
+        'optional context below. You cannot ask the user follow-up questions',
+        '(your `clarify` tool is disabled), you cannot spawn further sub-agents,',
+        'and you cannot write to MEMORY.md.',
+        '',
+        'When the task is done, produce a single final assistant message',
+        'summarising what you did and what you found. That summary is the',
+        'ONLY output the parent agent will see — no tool traces, no',
+        'intermediate reasoning. Make it self-contained, factual, and tight.',
+        '',
+        `## Goal`,
+        goal.trim(),
+    ];
+    if (context && context.trim().length > 0) {
+        lines.push('', '## Background context', context.trim());
+    }
+    return lines.join('\n');
+}
+/**
+ * Compose the initial user message. Currently a stub repeat of the goal
+ * — kept distinct from the system prompt so providers that prefer the
+ * system role for instructions and the user role for the immediate
+ * request both get a sensible payload. Context is included only in
+ * the system prompt so the user message stays compact.
+ */
+function composeUserMessage(goal, _context) {
+    return goal.trim();
+}
+/**
+ * v4.6 Phase 1 — build the child agent's `onToolCall` callback. Emits
+ * `tool_call_started` + `tool_call_completed` events to the child's
+ * `runs` row via the supplied runStore, mirroring the daemon
+ * dispatcher's audit shape. Also logs each call at info level so
+ * users tailing aiden.log see what the child actually did.
+ *
+ * Returns `undefined` when persistence + logger are both absent —
+ * the agent constructor accepts `undefined` for `onToolCall` and
+ * dispatches without notifying.
+ */
+function buildOnToolCall(deps) {
+    const { runStore, childRunId, logger } = deps;
+    if (!runStore && !logger && childRunId === undefined)
+        return undefined;
+    // Per-call start time keyed by tool_call_id so `durationMs` on the
+    // completed event reflects per-tool wall-clock, not per-turn.
+    const callStarts = new Map();
+    return (call, phase, result) => {
+        try {
+            if (phase === 'before') {
+                const startedAt = Date.now();
+                callStarts.set(call.id, startedAt);
+                const argsSummary = safeShortJson(call.arguments, 200);
+                if (runStore && childRunId !== undefined) {
+                    runStore.emitEvent(childRunId, 'tool_call_started', {
+                        toolName: call.name,
+                        args: argsSummary,
+                        ts: startedAt,
+                    });
+                }
+                if (logger) {
+                    logger.info('sub-agent tool call', {
+                        childRunId: childRunId ?? null,
+                        toolName: call.name,
+                        args: argsSummary,
+                    });
+                }
+                return;
+            }
+            // phase === 'after'
+            const startedAt = callStarts.get(call.id) ?? Date.now();
+            callStarts.delete(call.id);
+            const durationMs = Date.now() - startedAt;
+            if (runStore && childRunId !== undefined) {
+                runStore.emitEvent(childRunId, 'tool_call_completed', {
+                    toolName: call.name,
+                    error: result?.error ?? null,
+                    hasResult: result?.result !== undefined && result?.result !== null,
+                    durationMs,
+                });
+            }
+            if (logger) {
+                logger.info('sub-agent tool result', {
+                    childRunId: childRunId ?? null,
+                    toolName: call.name,
+                    ok: !result?.error,
+                    durationMs,
+                });
+            }
+        }
+        catch {
+            // Observability must never crash the agent loop.
+        }
+    };
+}
+/** JSON-stringify with a byte cap; returns the truncated string with an
+ *  ellipsis when the payload exceeds `maxBytes`. */
+function safeShortJson(value, maxBytes) {
+    try {
+        const s = JSON.stringify(value);
+        if (s === undefined)
+            return '';
+        return s.length > maxBytes ? s.slice(0, maxBytes) + '…' : s;
+    }
+    catch {
+        return String(value).slice(0, maxBytes);
+    }
+}