agent-nuvira 3.3.3 → 3.3.5

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"}