narai-primitives 2.0.0-rc.1

package/dist/hub/dispatch.js

@@ -0,0 +1,297 @@
+/** Subprocess fan-out — run plan steps in parallel, returning per-step
+ *  envelopes or structured errors.
+ *
+ *  Memory & cancellation safeguards (added during the narai-primitives
+ *  consolidation):
+ *    - per-spawn timeout (default 60s; SIGTERM then SIGKILL after grace)
+ *    - stdout buffer cap (default 50 MB; runaway connectors can't OOM the parent)
+ *    - concurrency limit on plan dispatch (default 8; widely-fanned plans
+ *      don't spawn 50+ children at once)
+ *    - AbortSignal propagation: caller can cancel mid-`gather()`
+ *    - parent-exit child cleanup: SIGTERM all in-flight children when the
+ *      parent receives SIGINT/SIGTERM/exit
+ *
+ *  Every safeguard surfaces a structured error envelope on the affected step
+ *  rather than throwing, matching the `DispatchResult.error` contract that
+ *  callers like doc-wiki's `applyMermaid` already handle. */
+import { spawn as nodeSpawn } from "node:child_process";
+const STDOUT_PREVIEW_CHARS = 200;
+/** Default per-spawn timeout. Overridable per call via `dispatchPlan({ timeoutMs })`. */
+const DEFAULT_TIMEOUT_MS = 60_000;
+/** Default stdout cap (50 MB). Overridable per call via `dispatchPlan({ maxStdoutBytes })`. */
+const DEFAULT_MAX_STDOUT_BYTES = 50 * 1024 * 1024;
+/** Default concurrent-spawn cap. Overridable per call via `dispatchPlan({ concurrency })`. */
+const DEFAULT_CONCURRENCY = 8;
+/** Grace period between SIGTERM and SIGKILL when killing a hung child. */
+const SIGKILL_GRACE_MS = 2_000;
+const defaultSpawn = (cmd, args, opts) => {
+    const env = { ...process.env, ...(opts.env ?? {}) };
+    return nodeSpawn(cmd, args, { env, stdio: ["ignore", "pipe", "pipe"] });
+};
+const liveChildren = new Set();
+let exitHandlersWired = false;
+function ensureExitHandlers() {
+    if (exitHandlersWired)
+        return;
+    exitHandlersWired = true;
+    const teardown = () => {
+        for (const c of liveChildren) {
+            try {
+                if (!c.killed)
+                    c.kill("SIGTERM");
+            }
+            catch {
+                // best-effort
+            }
+        }
+        liveChildren.clear();
+    };
+    process.on("exit", teardown);
+    process.on("SIGINT", () => {
+        teardown();
+        // Re-raise so the user's terminal exits with the conventional code.
+        process.exit(130);
+    });
+    process.on("SIGTERM", () => {
+        teardown();
+        process.exit(143);
+    });
+}
+// ── Public API ────────────────────────────────────────────────────────
+/** Dispatch a validated plan in parallel (bounded by `concurrency`). Each step
+ *  gets its own DispatchResult. `runStep` never rejects — every error path
+ *  resolves to a structured result. */
+export async function dispatchPlan(plan, preparedByName, opts = {}) {
+    ensureExitHandlers();
+    const spawnFn = opts.spawnProcess ?? defaultSpawn;
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const maxStdoutBytes = opts.maxStdoutBytes ?? DEFAULT_MAX_STDOUT_BYTES;
+    const concurrency = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
+    const signal = opts.signal;
+    // Pre-allocate result slots so the order matches the input plan even when
+    // steps complete out of order.
+    const results = new Array(plan.length);
+    // Simple bounded-concurrency runner: index marches through `plan` while
+    // up to `concurrency` workers pick the next index in turn.
+    let next = 0;
+    const worker = async () => {
+        while (next < plan.length) {
+            const idx = next++;
+            const step = plan[idx];
+            // Honor cancellation before starting any new step.
+            if (signal?.aborted) {
+                results[idx] = abortedResult(idx + 1, step);
+                continue;
+            }
+            results[idx] = await runStep(idx + 1, step, preparedByName, spawnFn, timeoutMs, maxStdoutBytes, signal);
+        }
+    };
+    const workers = [];
+    for (let i = 0; i < Math.min(concurrency, plan.length); i++) {
+        workers.push(worker());
+    }
+    await Promise.all(workers);
+    return results;
+}
+// ── Step runner ───────────────────────────────────────────────────────
+function abortedResult(stepIdx, step) {
+    return {
+        step: stepIdx,
+        connector: step.connector,
+        action: step.action,
+        params: step.params,
+        error: { code: "ABORTED", message: "dispatch aborted via AbortSignal" },
+    };
+}
+function runStep(stepIdx, step, preparedByName, spawnFn, timeoutMs, maxStdoutBytes, signal) {
+    const prepared = preparedByName.get(step.connector);
+    if (prepared === undefined) {
+        return Promise.resolve({
+            step: stepIdx,
+            connector: step.connector,
+            action: step.action,
+            params: step.params,
+            error: {
+                code: "DISPATCH_FAILED",
+                message: `connector '${step.connector}' not prepared`,
+            },
+        });
+    }
+    const cliArgs = [
+        ...prepared.binArgs,
+        "--action",
+        step.action,
+        "--params",
+        JSON.stringify(step.params),
+    ];
+    const blob = JSON.stringify(prepared.slice);
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawnFn(prepared.binCommand, cliArgs, {
+                env: { NARAI_CONFIG_BLOB: blob },
+            });
+        }
+        catch (err) {
+            resolve({
+                step: stepIdx,
+                connector: step.connector,
+                action: step.action,
+                params: step.params,
+                error: {
+                    code: "DISPATCH_FAILED",
+                    message: `spawn failed: ${err.message}`,
+                },
+            });
+            return;
+        }
+        let stdoutBuf = "";
+        let stdoutBytes = 0;
+        let settled = false;
+        let timeoutHandle;
+        let killGraceHandle;
+        const childLike = child;
+        liveChildren.add(childLike);
+        const cleanup = () => {
+            if (timeoutHandle !== undefined)
+                clearTimeout(timeoutHandle);
+            if (killGraceHandle !== undefined)
+                clearTimeout(killGraceHandle);
+            liveChildren.delete(childLike);
+            if (signal !== undefined)
+                signal.removeEventListener("abort", onAbort);
+        };
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(result);
+        };
+        /** Kill the child gracefully, with SIGKILL fallback after a short grace. */
+        const killChild = () => {
+            try {
+                if (!childLike.killed)
+                    childLike.kill("SIGTERM");
+            }
+            catch {
+                // best-effort
+            }
+            killGraceHandle = setTimeout(() => {
+                try {
+                    if (!childLike.killed)
+                        childLike.kill("SIGKILL");
+                }
+                catch {
+                    // best-effort
+                }
+            }, SIGKILL_GRACE_MS);
+        };
+        // Timeout — finish with structured TIMEOUT error.
+        timeoutHandle = setTimeout(() => {
+            killChild();
+            finish({
+                step: stepIdx,
+                connector: step.connector,
+                action: step.action,
+                params: step.params,
+                error: {
+                    code: "TIMEOUT",
+                    message: `connector did not exit within ${timeoutMs}ms`,
+                },
+            });
+        }, timeoutMs);
+        // AbortSignal — finish with structured ABORTED error.
+        const onAbort = () => {
+            killChild();
+            finish({
+                step: stepIdx,
+                connector: step.connector,
+                action: step.action,
+                params: step.params,
+                error: { code: "ABORTED", message: "dispatch aborted via AbortSignal" },
+            });
+        };
+        if (signal !== undefined) {
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener("abort", onAbort);
+        }
+        child.stdout.on("data", (chunk) => {
+            const text = chunk.toString();
+            stdoutBytes += Buffer.byteLength(text, "utf-8");
+            if (stdoutBytes > maxStdoutBytes) {
+                killChild();
+                finish({
+                    step: stepIdx,
+                    connector: step.connector,
+                    action: step.action,
+                    params: step.params,
+                    error: {
+                        code: "STDOUT_CAP_EXCEEDED",
+                        message: `connector stdout exceeded ${maxStdoutBytes} bytes; aborted`,
+                    },
+                });
+                return;
+            }
+            stdoutBuf += text;
+        });
+        // Pass stderr through verbatim so callers see connector diagnostics.
+        child.stderr.on("data", (chunk) => {
+            process.stderr.write(chunk);
+        });
+        child.on("error", (err) => {
+            finish({
+                step: stepIdx,
+                connector: step.connector,
+                action: step.action,
+                params: step.params,
+                error: {
+                    code: "DISPATCH_FAILED",
+                    message: `spawn error: ${err.message}`,
+                },
+            });
+        });
+        child.on("exit", (code) => {
+            const trimmed = stdoutBuf.trim();
+            if (trimmed === "") {
+                finish({
+                    step: stepIdx,
+                    connector: step.connector,
+                    action: step.action,
+                    params: step.params,
+                    error: {
+                        code: "DISPATCH_FAILED",
+                        message: `connector exited with code ${String(code)} and no stdout`,
+                    },
+                });
+                return;
+            }
+            try {
+                const envelope = JSON.parse(trimmed);
+                finish({
+                    step: stepIdx,
+                    connector: step.connector,
+                    action: step.action,
+                    params: step.params,
+                    envelope,
+                });
+            }
+            catch {
+                finish({
+                    step: stepIdx,
+                    connector: step.connector,
+                    action: step.action,
+                    params: step.params,
+                    error: {
+                        code: "ENVELOPE_PARSE_ERROR",
+                        message: `non-JSON stdout (preview): ${trimmed.slice(0, STDOUT_PREVIEW_CHARS)}`,
+                    },
+                });
+            }
+        });
+    });
+}
+//# sourceMappingURL=dispatch.js.map

package/dist/hub/dispatch.js.map

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

package/dist/hub/index.d.ts

@@ -0,0 +1,9 @@
+/** Public API: `gather()` — plans connector calls from a prompt and dispatches
+ *  them in parallel as subprocesses. */
+import type { GatherDeps, GatherInput, GatherOutput } from "./types.js";
+export type { CliResolver, DispatchResult, GatherDeps, GatherInput, GatherOutput, Planner, PlanStep, PreparedConnector, SpawnFn, } from "./types.js";
+export { AgentSdkPlanner, buildSystemPrompt, buildUserPrompt, extractJsonArray, validatePlan } from "./plan.js";
+export { dispatchPlan } from "./dispatch.js";
+/** Plan + dispatch connector calls from a natural-language prompt. */
+export declare function gather(input: GatherInput, deps?: GatherDeps): Promise<GatherOutput>;
+//# sourceMappingURL=index.d.ts.map

package/dist/hub/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/hub/index.ts"],"names":[],"mappings":"AAAA;wCACwC;AAiBxC,OAAO,KAAK,EAGV,UAAU,EACV,WAAW,EACX,YAAY,EAEb,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,WAAW,EACX,cAAc,EACd,UAAU,EACV,WAAW,EACX,YAAY,EACZ,OAAO,EACP,QAAQ,EACR,iBAAiB,EACjB,OAAO,GACR,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,eAAe,EAAE,iBAAiB,EAAE,eAAe,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAChH,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAmG7C,sEAAsE;AACtE,wBAAsB,MAAM,CAAC,KAAK,EAAE,WAAW,EAAE,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,YAAY,CAAC,CAqH7F"}

package/dist/hub/index.js

@@ -0,0 +1,215 @@
+/** Public API: `gather()` — plans connector calls from a prompt and dispatches
+ *  them in parallel as subprocesses. */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { loadResolvedConfig } from "narai-primitives/config";
+import { resolveAgentCli } from "narai-primitives/toolkit";
+import { dispatchPlan } from "./dispatch.js";
+import { AgentSdkPlanner, buildSystemPrompt, buildUserPrompt, extractJsonArray, validatePlan, } from "./plan.js";
+export { AgentSdkPlanner, buildSystemPrompt, buildUserPrompt, extractJsonArray, validatePlan } from "./plan.js";
+export { dispatchPlan } from "./dispatch.js";
+/** Strip `-agent-connector` suffix to get the short name expected by `resolveAgentCli`. */
+function shortName(skill) {
+    return skill.replace(/-agent-connector$/, "");
+}
+/** Walk up from a `dist/cli.js` path to the package root. */
+function packageRootFromCli(cliPath) {
+    // <root>/dist/cli.js → <root>
+    return path.dirname(path.dirname(cliPath));
+}
+/** Read a file synchronously, returning null on failure. */
+function tryRead(p) {
+    try {
+        return fs.readFileSync(p, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Default CLI resolver — wraps `resolveAgentCli` with a one-arg signature. */
+const defaultCliResolver = (name) => resolveAgentCli({ name });
+/** Resolve one connector's bin + SKILL.md content. */
+function prepareConnector(slice, cliResolver) {
+    const skill = slice.skill;
+    // Path-style skill: SKILL.md from the path; bin from `options.bin`.
+    if (skill.startsWith("~") || skill.startsWith("/") || skill.startsWith(".")) {
+        const expanded = skill.startsWith("~")
+            ? path.join(os.homedir(), skill.slice(1))
+            : skill;
+        const skillFile = path.join(expanded, "SKILL.md");
+        const skillContent = tryRead(skillFile);
+        if (skillContent === null) {
+            return {
+                error: {
+                    code: "SKILL_NOT_FOUND",
+                    message: `SKILL.md not found at ${skillFile}`,
+                },
+            };
+        }
+        const binOpt = slice.options["bin"];
+        if (typeof binOpt !== "string" || binOpt === "") {
+            return {
+                error: {
+                    code: "CONFIG_ERROR",
+                    message: `connector '${slice.name}' uses path-style skill but has no 'bin' option`,
+                },
+            };
+        }
+        return {
+            prepared: {
+                name: slice.name,
+                binCommand: "node",
+                binArgs: [binOpt],
+                skillContent,
+                slice,
+            },
+        };
+    }
+    // Built-in skill: resolve bin via the injected resolver + read SKILL.md from package root.
+    const name = shortName(skill);
+    const resolved = cliResolver(name);
+    if (resolved === null) {
+        return {
+            error: {
+                code: "CLI_NOT_FOUND",
+                message: `could not resolve CLI for connector '${slice.name}' (short name: ${name})`,
+            },
+        };
+    }
+    const root = packageRootFromCli(resolved.resolvedPath);
+    const skillFile = path.join(root, "plugin", "skills", `${name}-agent`, "SKILL.md");
+    const skillContent = tryRead(skillFile);
+    if (skillContent === null) {
+        return {
+            error: {
+                code: "SKILL_NOT_FOUND",
+                message: `SKILL.md not found at ${skillFile}`,
+            },
+        };
+    }
+    return {
+        prepared: {
+            name: slice.name,
+            binCommand: resolved.command,
+            binArgs: resolved.args,
+            skillContent,
+            slice,
+        },
+    };
+}
+/** Plan + dispatch connector calls from a natural-language prompt. */
+export async function gather(input, deps = {}) {
+    const configLoader = deps.configLoader ?? loadResolvedConfig;
+    const planner = deps.planner ?? new AgentSdkPlanner();
+    const cliResolver = deps.cliResolver ?? defaultCliResolver;
+    // Step 1 — load config.
+    const loadOpts = {};
+    if (input.consumer !== undefined)
+        loadOpts.consumer = input.consumer;
+    if (input.environment !== undefined)
+        loadOpts.environment = input.environment;
+    const resolved = await configLoader(loadOpts);
+    // Step 2 — prepare each enabled connector.
+    const prepared = [];
+    const prepErrors = [];
+    let syntheticIdx = 0;
+    for (const [name, slice] of Object.entries(resolved.connectors)) {
+        if (!slice.enabled)
+            continue;
+        const result = prepareConnector(slice, cliResolver);
+        if ("error" in result) {
+            syntheticIdx++;
+            prepErrors.push({
+                step: syntheticIdx,
+                connector: name,
+                action: "<prepare>",
+                params: {},
+                error: result.error,
+            });
+            continue;
+        }
+        prepared.push(result.prepared);
+    }
+    if (prepared.length === 0) {
+        return { plan: [], results: prepErrors };
+    }
+    // Step 3 — plan.
+    const systemPrompt = buildSystemPrompt(prepared);
+    const userPrompt = buildUserPrompt(input.prompt, input.extraContext);
+    let raw;
+    try {
+        raw = await planner.plan(systemPrompt, userPrompt);
+    }
+    catch (err) {
+        const msg = err.message;
+        const code = msg.includes("authentic") || msg.includes("session") || msg.includes("OAuth")
+            ? "NO_CLAUDE_CODE_SESSION"
+            : "PLANNER_FAILED";
+        return {
+            plan: [],
+            results: [
+                ...prepErrors,
+                {
+                    step: prepErrors.length + 1,
+                    connector: "<planner>",
+                    action: "<plan>",
+                    params: {},
+                    error: { code, message: msg },
+                },
+            ],
+        };
+    }
+    let parsed;
+    try {
+        parsed = extractJsonArray(raw);
+    }
+    catch (err) {
+        return {
+            plan: [],
+            results: [
+                ...prepErrors,
+                {
+                    step: prepErrors.length + 1,
+                    connector: "<planner>",
+                    action: "<plan>",
+                    params: {},
+                    error: {
+                        code: "PLANNER_INVALID",
+                        message: `could not parse planner JSON: ${err.message}`,
+                    },
+                },
+            ],
+        };
+    }
+    const enabledNames = new Set(prepared.map((p) => p.name));
+    const validation = validatePlan(parsed, enabledNames);
+    // Synthesize an error per dropped entry (offset after prep errors).
+    const planEntryErrors = validation.invalid.map((bad, i) => ({
+        step: prepErrors.length + i + 1,
+        connector: isPlainObject(bad.entry) && typeof bad.entry["connector"] === "string"
+            ? bad.entry["connector"]
+            : "<unknown>",
+        action: isPlainObject(bad.entry) && typeof bad.entry["action"] === "string"
+            ? bad.entry["action"]
+            : "<unknown>",
+        params: {},
+        error: { code: "PLAN_ENTRY_INVALID", message: bad.reason },
+    }));
+    // Step 4 — dispatch.
+    const preparedByName = new Map(prepared.map((p) => [p.name, p]));
+    const dispatchResults = await dispatchPlan(validation.valid, preparedByName, {
+        ...(deps.spawnProcess !== undefined ? { spawnProcess: deps.spawnProcess } : {}),
+    });
+    // Renumber dispatch results so `step` is contiguous in the final output.
+    const offset = prepErrors.length + planEntryErrors.length;
+    const renumbered = dispatchResults.map((r, i) => ({ ...r, step: offset + i + 1 }));
+    return {
+        plan: validation.valid,
+        results: [...prepErrors, ...planEntryErrors, ...renumbered],
+    };
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+//# sourceMappingURL=index.js.map

package/dist/hub/index.js.map

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

package/dist/hub/plan.d.ts

@@ -0,0 +1,24 @@
+/** Planner-prompt builder, response JSON extraction, plan validation, and the
+ *  default Agent SDK planner. */
+import type { PlanStep, Planner, PreparedConnector } from "./types.js";
+/** Build the system prompt by concatenating each connector's SKILL.md verbatim. */
+export declare function buildSystemPrompt(connectors: readonly PreparedConnector[]): string;
+/** Build the user-facing prompt portion. */
+export declare function buildUserPrompt(prompt: string, extraContext?: string): string;
+/** Extract a JSON array from a possibly-prose-wrapped LLM response.
+ *  Returns the parsed value (typed `unknown`), or throws on failure. */
+export declare function extractJsonArray(raw: string): unknown;
+export interface PlanValidation {
+    valid: PlanStep[];
+    invalid: {
+        entry: unknown;
+        reason: string;
+    }[];
+}
+/** Validate raw plan entries; drop malformed ones with a recorded reason. */
+export declare function validatePlan(raw: unknown, enabledConnectors: ReadonlySet<string>): PlanValidation;
+/** Default planner: invokes `@anthropic-ai/claude-agent-sdk` `query()`. */
+export declare class AgentSdkPlanner implements Planner {
+    plan(systemPrompt: string, userPrompt: string): Promise<string>;
+}
+//# sourceMappingURL=plan.d.ts.map

package/dist/hub/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/hub/plan.ts"],"names":[],"mappings":"AAAA;iCACiC;AAEjC,OAAO,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEvE,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,SAAS,iBAAiB,EAAE,GAAG,MAAM,CAUlF;AAED,4CAA4C;AAC5C,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAG7E;AAED;wEACwE;AACxE,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAcrD;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAC1B,GAAG,EAAE,OAAO,EACZ,iBAAiB,EAAE,WAAW,CAAC,MAAM,CAAC,GACrC,cAAc,CA2BhB;AAMD,2EAA2E;AAC3E,qBAAa,eAAgB,YAAW,OAAO;IACvC,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAiCtE"}