agent-nuvira 3.3.1 → 3.3.4

package/dist/tools/child-agent-entry.js

@@ -0,0 +1,129 @@
+/**
+ * Child-agent entry point (`src/tools/child-agent-entry.ts`) — the file the
+ * spawner forks.
+ *
+ * It exists as TypeScript for two reasons that were both live defects:
+ *
+ *   1. **It is shipped.** `tsc` emits `dist/tools/child-agent-entry.js`, so the
+ *      compiled layout forks a file that exists. The previous entry was a
+ *      hand-written `child-agent-entry.js` under `src/`, which nothing copied to
+ *      `dist/` (`allowJs` is false) — a compiled install forked a path that was
+ *      never there, and `spawn()` threw ENOENT.
+ *   2. **It runs in this package's module system.** `package.json` is
+ *      `"type": "module"`, so that same `.js` file was parsed as ESM while being
+ *      written in CommonJS (`require`, `__dirname`, a `parentPort` import from a
+ *      worker-thread API that a `fork()`ed process does not have). It died on
+ *      `require is not defined` before it read a single environment variable.
+ *
+ * The child reports over the IPC channel `fork()` establishes: `progress` while
+ * it works, then exactly one `result` or `error`. The parent treats "exited
+ * without a result" as a failure, so this file must never exit 0 silently.
+ */
+import { runSubagent } from './child-agent-runtime.js';
+import { SubagentRefusalError } from './subagent-refusal.js';
+// WS6 (#28) — the declared fault seam, read in the CHILD's own process (the
+// declaration reaches it through the environment it inherited).
+import { faultAt } from '../runtime/fault-injection.js';
+function num(raw, fallback) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : fallback;
+}
+/** Env vars the spawner sets; anything malformed falls back rather than throwing. */
+function readConfig() {
+    const parseList = (raw) => {
+        try {
+            const parsed = JSON.parse(raw ?? '[]');
+            return Array.isArray(parsed) ? parsed.filter((t) => typeof t === 'string') : [];
+        }
+        catch {
+            return [];
+        }
+    };
+    return {
+        goal: process.env.SUBAGENT_GOAL ?? '',
+        provider: process.env.SUBAGENT_PROVIDER || 'auto',
+        model: process.env.SUBAGENT_MODEL || undefined,
+        tools: parseList(process.env.SUBAGENT_TOOLS),
+        blockedTools: parseList(process.env.SUBAGENT_BLOCKED_TOOLS),
+        maxLlmCalls: num(process.env.SUBAGENT_MAX_LLM_CALLS, 25),
+        maxIterations: num(process.env.SUBAGENT_MAX_ITERATIONS, 12),
+        cwd: process.cwd(),
+    };
+}
+/**
+ * The run's identity, as the runtime announced it: which provider, which model it
+ * pinned, and which transport carries tool calls.
+ *
+ * Remembered on the way OUT so the failure frame can carry it too. A child that
+ * died before producing a result used to reach the parent as a bare message, so a
+ * failed subagent could not be attributed to a backend — the one moment you most
+ * want to know which provider/model was serving the run.
+ */
+const identity = {};
+function send(msg) {
+    if (typeof msg.provider === 'string')
+        identity.provider = msg.provider;
+    if (typeof msg.model === 'string')
+        identity.model = msg.model;
+    if (typeof msg.transport === 'string')
+        identity.transport = msg.transport;
+    try {
+        process.send?.(msg);
+    }
+    catch {
+        // A closed IPC channel must not turn a finished task into a crash.
+    }
+}
+async function main() {
+    // WS6 (#28) — a DECLARED ipc fault: this process dies before it does any work,
+    // and deliberately WITHOUT a frame, because a crash is the failure the parent
+    // cannot observe from inside its own process. The assertion it exists for is
+    // that the parent reports the run as failed rather than hanging on a child that
+    // will never speak, or inventing a result for it.
+    if (faultAt('ipc', 'child'))
+        process.exit(3);
+    const config = readConfig();
+    if (!config.goal) {
+        send({ type: 'error', error: 'SUBAGENT_GOAL is empty — nothing to do.' });
+        process.exit(1);
+        return;
+    }
+    try {
+        const outcome = await runSubagent(config, { send });
+        send({
+            type: 'result',
+            result: outcome.result,
+            llmCalls: outcome.llmCalls,
+            toolCalls: outcome.toolCalls,
+            provider: outcome.provider,
+            // Which model and which tool transport actually served the run — recorded
+            // so a finished subagent can be inspected after the fact rather than guessed
+            // at from its output.
+            ...(outcome.model ? { model: outcome.model } : {}),
+            transport: outcome.transport,
+            truncated: outcome.truncated,
+            // G1 — the child's OWN verification verdict, on the frame like every other
+            // fact the parent can only learn across the fork. Without it a delegated run
+            // that wrote and verified nothing looked exactly like one that checked its
+            // work: the honesty flags live in this process and nowhere else.
+            ...(outcome.unverifiedEdit ? { unverifiedEdit: true } : {}),
+            ...(outcome.unverifiedEditClaim ? { unverifiedEditClaim: true } : {}),
+        });
+        process.exit(0);
+    }
+    catch (err) {
+        // The refusal's code crosses the boundary with the message: the parent logs
+        // WHY, instead of inferring it from an exit code. The identity rides along so
+        // the parent can record which provider/model/transport failed.
+        const code = err instanceof SubagentRefusalError ? err.code : 'unavailable';
+        send({
+            type: 'error',
+            code,
+            error: err instanceof Error ? err.message : String(err),
+            ...identity,
+        });
+        process.exit(1);
+    }
+}
+void main();
+//# sourceMappingURL=child-agent-entry.js.map

package/dist/tools/child-agent-entry.js.map

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

package/dist/tools/child-agent-runtime.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Child-agent runtime (`src/tools/child-agent-runtime.ts`).
+ *
+ * The work a forked subagent process actually does: resolve a REAL inference
+ * provider from the user's own configuration, run a bounded think → act →
+ * observe loop, execute any tool the model asks for through the REAL registry,
+ * and return the model's own output.
+ *
+ * ── What this replaces ──────────────────────────────────────────────────────
+ * `child-agent-worker.ts` was a simulation wearing the shape of an agent loop:
+ * its `LLMClient.call()` switched on keywords in the goal and returned canned
+ * strings ("I've analyzed the task: …"), and its `ToolExecutor.execute()`
+ * returned `Executed <tool>` without running anything. A subagent built on it
+ * reported work that never happened — the finding-#4 defect in the same
+ * workstream, which is why the tool was marked NOT CONNECTED in the registry.
+ *
+ * ── The rule this module follows ────────────────────────────────────────────
+ * Nothing is synthesised. If no provider can be constructed, or the backend is
+ * not reachable, or the provider cannot do tool-calling while tools were
+ * requested, this THROWS a typed refusal instead of returning a plausible
+ * answer. `SubagentRefusalError.code` carries the reason so the parent records
+ * it as the failure it is.
+ *
+ * The provider factory and the tool runner are injectable so the loop is
+ * testable without a network; production passes neither and gets the real ones.
+ */
+import type { InferenceProvider } from '../inference/interface.js';
+import { type ResumeOutcome } from '../learning/step-checkpoint.js';
+export interface SubagentRuntimeConfig {
+    /** The task the subagent must complete. */
+    goal: string;
+    /** Provider id, or 'auto' to let the config resolve the best available one. */
+    provider?: string;
+    /** Model id; 'auto'/absent lets the provider's configured model stand. */
+    model?: string;
+    /** Allow-list of tool names. Empty = a plain completion with no tools. */
+    tools?: string[];
+    /** Never offered to the model, and refused if it calls one anyway. */
+    blockedTools?: string[];
+    /** Hard ceiling on model calls (default 25). */
+    maxLlmCalls?: number;
+    /** Hard ceiling on loop iterations (default 12). */
+    maxIterations?: number;
+    /** Working directory for tool execution. */
+    cwd?: string;
+    /**
+     * WS5 (#27) — replay this child's recorded steps whose input is unchanged
+     * instead of paying for them again. `undefined` defers to the inherited
+     * `NUVIRA_RESUME`, so a resumed parent run resumes its children too.
+     */
+    resume?: string | boolean;
+}
+export interface SubagentRuntimeHooks {
+    /** Receives `progress` records (forwarded to the parent over IPC). */
+    send?: (msg: Record<string, unknown>) => void;
+    /** Override provider construction (tests inject a scripted provider). */
+    createProvider?: (requested: string | undefined, model: string | undefined) => Promise<{
+        provider: InferenceProvider;
+        type: string;
+    }>;
+    /** Override tool execution (tests assert the real registry is used). */
+    runTool?: (name: string, args: Record<string, unknown>) => Promise<string>;
+}
+export interface SubagentRuntimeResult {
+    /** The model's final text. Never a template this module composed. */
+    result: string;
+    llmCalls: number;
+    toolCalls: number;
+    /** Provider that actually served the calls. */
+    provider: string;
+    /**
+     * The model sent on the wire, when one could be resolved. Reported because a
+     * run is otherwise only attributable to a provider — "groq failed" does not
+     * say WHICH model the account rejected (see {@link effectiveModel}).
+     */
+    model?: string;
+    /**
+     * How tool calls were carried. `native` = the provider's own tool protocol;
+     * `json` = the shared JSON-fallback transport (the same prompt builder and
+     * parser the chat and execute loops use). `none` = no tools were requested.
+     */
+    transport: 'native' | 'json' | 'none';
+    /** True when the run hit an iteration/call ceiling before the model stopped. */
+    truncated: boolean;
+    /**
+     * WS5 (#27) — what this run's resume replayed, and what it saved. Present only
+     * when a resume was asked for; reported to the parent on its own frame, because
+     * the child is a separate process and that frame is its only channel.
+     */
+    resume?: ResumeOutcome;
+    /**
+     * G1 — this run MUTATED the workspace and nothing observed the result (the
+     * bounded nudge was spent and the model still answered without verifying, or
+     * the run hit its ceiling first). Set whether or not the nudge fired, exactly
+     * as `ToolLoopResult.unverifiedEdit` is: honesty is not a function of
+     * configuration, so a caller can never read an unverified edit as a checked one.
+     */
+    unverifiedEdit?: boolean;
+    /**
+     * G1/G2 — the answer ASSERTS a completed code change that no verification
+     * backed (`detectUnverifiedEditClaim`). The child's own flag, carried across the
+     * fork, so a delegated run whose summary claims "I fixed it" is recorded as
+     * unverified rather than read as an observed result.
+     */
+    unverifiedEditClaim?: boolean;
+}
+/**
+ * Resolve the tool allow-list: the request, minus anything always blocked, minus
+ * anything the caller listed as blocked, keeping only names the registry knows.
+ * A name that does not exist is dropped loudly (returned) rather than silently.
+ */
+export declare function resolveToolAllowList(config: SubagentRuntimeConfig): {
+    allowed: string[];
+    unknown: string[];
+};
+/**
+ * Run the subagent to completion.
+ *
+ * @throws SubagentRefusalError when nothing real can be run — no constructible
+ *   provider, an unreachable backend, or tools requested on a provider that
+ *   cannot call them.
+ */
+export declare function runSubagent(config: SubagentRuntimeConfig, hooks?: SubagentRuntimeHooks): Promise<SubagentRuntimeResult>;
+//# sourceMappingURL=child-agent-runtime.d.ts.map

package/dist/tools/child-agent-runtime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"child-agent-runtime.d.ts","sourceRoot":"","sources":["../../src/tools/child-agent-runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,KAAK,EAAE,iBAAiB,EAA6C,MAAM,2BAA2B,CAAC;AAmC9G,OAAO,EAML,KAAK,aAAa,EAEnB,MAAM,gCAAgC,CAAC;AAmBxC,MAAM,WAAW,qBAAqB;IACpC,2CAA2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAED,MAAM,WAAW,oBAAoB;IACnC,sEAAsE;IACtE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IAC9C,yEAAyE;IACzE,cAAc,CAAC,EAAE,CACf,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,EAAE,MAAM,GAAG,SAAS,KACtB,OAAO,CAAC;QAAE,QAAQ,EAAE,iBAAiB,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC5D,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5E;AAED,MAAM,WAAW,qBAAqB;IACpC,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,SAAS,EAAE,QAAQ,GAAG,MAAM,GAAG,MAAM,CAAC;IACtC,gFAAgF;IAChF,SAAS,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB;;;;;;OAMG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,OAAO,CAAC;CAC/B;AA+CD;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,qBAAqB,GAAG;IAAE,OAAO,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,MAAM,EAAE,CAAA;CAAE,CAa5G;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,qBAAqB,EAC7B,KAAK,GAAE,oBAAyB,GAC/B,OAAO,CAAC,qBAAqB,CAAC,CAwMhC"}