narai-primitives 2.0.0-rc.1

package/dist/hub/plan.js

@@ -0,0 +1,103 @@
+/** Planner-prompt builder, response JSON extraction, plan validation, and the
+ *  default Agent SDK planner. */
+/** Build the system prompt by concatenating each connector's SKILL.md verbatim. */
+export function buildSystemPrompt(connectors) {
+    const sorted = [...connectors].sort((a, b) => a.name.localeCompare(b.name));
+    const intro = "You are a planner for a set of read-only data connectors. Below is the documentation for each connector you may call, copied verbatim from its plugin skill.";
+    const sections = sorted.map((c) => `## Connector: \`${c.name}\`\n\n${c.skillContent.trim()}\n`);
+    const tail = 'Given the user\'s prompt, return JSON: an array of objects with shape `{"connector": "<name>", "action": "<action>", "params": { ... }}`. Do not include any call whose required params you cannot fill from the prompt. Return `[]` if no connector is relevant. Return JSON only, no prose.';
+    return [intro, ...sections, tail].join("\n\n");
+}
+/** Build the user-facing prompt portion. */
+export function buildUserPrompt(prompt, extraContext) {
+    if (extraContext === undefined || extraContext.trim() === "")
+        return prompt;
+    return `${prompt}\n\n--- extra context ---\n${extraContext}`;
+}
+/** Extract a JSON array from a possibly-prose-wrapped LLM response.
+ *  Returns the parsed value (typed `unknown`), or throws on failure. */
+export function extractJsonArray(raw) {
+    // First try a clean parse — best case, the model returned only JSON.
+    const trimmed = raw.trim();
+    try {
+        return JSON.parse(trimmed);
+    }
+    catch {
+        // fall through
+    }
+    // Greedy match the first `[ ... ]` block. Defensive but acceptable for V1.
+    const match = trimmed.match(/\[[\s\S]*\]/);
+    if (match === null) {
+        throw new Error("no JSON array found in planner response");
+    }
+    return JSON.parse(match[0]);
+}
+/** Validate raw plan entries; drop malformed ones with a recorded reason. */
+export function validatePlan(raw, enabledConnectors) {
+    if (!Array.isArray(raw)) {
+        return { valid: [], invalid: [{ entry: raw, reason: "plan is not an array" }] };
+    }
+    const valid = [];
+    const invalid = [];
+    for (const entry of raw) {
+        if (!isPlainObject(entry)) {
+            invalid.push({ entry, reason: "entry is not a plain object" });
+            continue;
+        }
+        const { connector, action, params } = entry;
+        if (typeof connector !== "string" || !enabledConnectors.has(connector)) {
+            invalid.push({ entry, reason: `unknown connector '${String(connector)}'` });
+            continue;
+        }
+        if (typeof action !== "string" || action === "") {
+            invalid.push({ entry, reason: "missing or empty action" });
+            continue;
+        }
+        if (!isPlainObject(params)) {
+            invalid.push({ entry, reason: "params must be a plain object" });
+            continue;
+        }
+        valid.push({ connector, action, params });
+    }
+    return { valid, invalid };
+}
+function isPlainObject(v) {
+    return v !== null && typeof v === "object" && !Array.isArray(v);
+}
+/** Default planner: invokes `@anthropic-ai/claude-agent-sdk` `query()`. */
+export class AgentSdkPlanner {
+    async plan(systemPrompt, userPrompt) {
+        let query;
+        try {
+            ({ query } = await import("@anthropic-ai/claude-agent-sdk"));
+        }
+        catch (err) {
+            throw new Error(`failed to load @anthropic-ai/claude-agent-sdk: ${err.message}`);
+        }
+        const iter = query({
+            prompt: userPrompt,
+            options: {
+                systemPrompt,
+                maxTurns: 1,
+                // The planner does not need any tools; it returns JSON via assistant text.
+                tools: [],
+            },
+        });
+        let final = "";
+        for await (const msg of iter) {
+            if (msg.type === "result") {
+                if (msg.subtype === "success") {
+                    final = msg.result;
+                }
+                else {
+                    throw new Error(`planner failed: ${msg.subtype}`);
+                }
+            }
+        }
+        if (final === "") {
+            throw new Error("planner returned no result");
+        }
+        return final;
+    }
+}
+//# sourceMappingURL=plan.js.map

package/dist/hub/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/hub/plan.ts"],"names":[],"mappings":"AAAA;iCACiC;AAIjC,mFAAmF;AACnF,MAAM,UAAU,iBAAiB,CAAC,UAAwC;IACxE,MAAM,MAAM,GAAG,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;IAC5E,MAAM,KAAK,GACT,8JAA8J,CAAC;IACjK,MAAM,QAAQ,GAAG,MAAM,CAAC,GAAG,CACzB,CAAC,CAAC,EAAE,EAAE,CAAC,mBAAmB,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,IAAI,CACnE,CAAC;IACF,MAAM,IAAI,GACR,+RAA+R,CAAC;IAClS,OAAO,CAAC,KAAK,EAAE,GAAG,QAAQ,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AACjD,CAAC;AAED,4CAA4C;AAC5C,MAAM,UAAU,eAAe,CAAC,MAAc,EAAE,YAAqB;IACnE,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,MAAM,CAAC;IAC5E,OAAO,GAAG,MAAM,8BAA8B,YAAY,EAAE,CAAC;AAC/D,CAAC;AAED;wEACwE;AACxE,MAAM,UAAU,gBAAgB,CAAC,GAAW;IAC1C,qEAAqE;IACrE,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACP,eAAe;IACjB,CAAC;IACD,2EAA2E;IAC3E,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACnB,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;IAC7D,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;AAC9B,CAAC;AAOD,6EAA6E;AAC7E,MAAM,UAAU,YAAY,CAC1B,GAAY,EACZ,iBAAsC;IAEtC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QACxB,OAAO,EAAE,KAAK,EAAE,EAAE,EAAE,OAAO,EAAE,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC,EAAE,CAAC;IAClF,CAAC;IACD,MAAM,KAAK,GAAe,EAAE,CAAC;IAC7B,MAAM,OAAO,GAAyC,EAAE,CAAC;IACzD,KAAK,MAAM,KAAK,IAAI,GAAG,EAAE,CAAC;QACxB,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,6BAA6B,EAAE,CAAC,CAAC;YAC/D,SAAS;QACX,CAAC;QACD,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;QAC5C,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,CAAC,iBAAiB,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,CAAC;YACvE,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC,CAAC;YAC5E,SAAS;QACX,CAAC;QACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,EAAE,EAAE,CAAC;YAChD,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAC;YAC3D,SAAS;QACX,CAAC;QACD,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,+BAA+B,EAAE,CAAC,CAAC;YACjE,SAAS;QACX,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;AAC5B,CAAC;AAED,SAAS,aAAa,CAAC,CAAU;IAC/B,OAAO,CAAC,KAAK,IAAI,IAAI,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;AAClE,CAAC;AAED,2EAA2E;AAC3E,MAAM,OAAO,eAAe;IAC1B,KAAK,CAAC,IAAI,CAAC,YAAoB,EAAE,UAAkB;QACjD,IAAI,KAA4D,CAAC;QACjE,IAAI,CAAC;YACH,CAAC,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,gCAAgC,CAAC,CAAC,CAAC;QAC/D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,MAAM,IAAI,KAAK,CACb,kDAAmD,GAAa,CAAC,OAAO,EAAE,CAC3E,CAAC;QACJ,CAAC;QACD,MAAM,IAAI,GAAG,KAAK,CAAC;YACjB,MAAM,EAAE,UAAU;YAClB,OAAO,EAAE;gBACP,YAAY;gBACZ,QAAQ,EAAE,CAAC;gBACX,2EAA2E;gBAC3E,KAAK,EAAE,EAAE;aACV;SACF,CAAC,CAAC;QACH,IAAI,KAAK,GAAG,EAAE,CAAC;QACf,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;YAC7B,IAAI,GAAG,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBAC1B,IAAI,GAAG,CAAC,OAAO,KAAK,SAAS,EAAE,CAAC;oBAC9B,KAAK,GAAG,GAAG,CAAC,MAAM,CAAC;gBACrB,CAAC;qBAAM,CAAC;oBACN,MAAM,IAAI,KAAK,CAAC,mBAAmB,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;gBACpD,CAAC;YACH,CAAC;QACH,CAAC;QACD,IAAI,KAAK,KAAK,EAAE,EAAE,CAAC;YACjB,MAAM,IAAI,KAAK,CAAC,4BAA4B,CAAC,CAAC;QAChD,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;CACF"}

package/dist/hub/types.d.ts

@@ -0,0 +1,65 @@
+/** Public types for `@narai/connector-hub`. */
+import type { ResolvedConnector, LoadOptions, ResolvedConfig } from "narai-primitives/config";
+import type { ResolvedAgentCli } from "narai-primitives/toolkit";
+export interface GatherInput {
+    prompt: string;
+    consumer?: string;
+    environment?: string;
+    extraContext?: string;
+}
+export interface PlanStep {
+    connector: string;
+    action: string;
+    params: Record<string, unknown>;
+}
+export interface DispatchError {
+    code: string;
+    message: string;
+}
+export interface DispatchResult {
+    step: number;
+    connector: string;
+    action: string;
+    params: Record<string, unknown>;
+    envelope?: unknown;
+    error?: DispatchError;
+}
+export interface GatherOutput {
+    plan: PlanStep[];
+    results: DispatchResult[];
+}
+/** Pluggable planner — an implementation that returns a raw LLM response string. */
+export interface Planner {
+    plan(systemPrompt: string, userPrompt: string): Promise<string>;
+}
+/** A resolved connector + the bin needed to invoke it + its SKILL.md content. */
+export interface PreparedConnector {
+    name: string;
+    binCommand: string;
+    binArgs: string[];
+    skillContent: string;
+    slice: ResolvedConnector;
+}
+/** Options for `child_process.spawn`-style injection. */
+export interface SpawnOpts {
+    env?: NodeJS.ProcessEnv;
+}
+/** Minimal handle returned by an injected spawn fn. */
+export interface SpawnedHandle {
+    stdout: NodeJS.ReadableStream;
+    stderr: NodeJS.ReadableStream;
+    on(event: "exit", listener: (code: number | null) => void): void;
+    on(event: "error", listener: (err: Error) => void): void;
+}
+export type SpawnFn = (cmd: string, args: string[], opts: SpawnOpts) => SpawnedHandle;
+export type ConfigLoader = (opts: LoadOptions) => Promise<ResolvedConfig>;
+/** Resolves a connector's CLI bin from its short name. Defaults to `resolveAgentCli`. */
+export type CliResolver = (name: string) => ResolvedAgentCli | null;
+export interface GatherDeps {
+    planner?: Planner;
+    spawnProcess?: SpawnFn;
+    configLoader?: ConfigLoader;
+    /** Override the default `resolveAgentCli` (used by tests). */
+    cliResolver?: CliResolver;
+}
+//# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/hub/types.ts"],"names":[],"mappings":"AAAA,+CAA+C;AAE/C,OAAO,KAAK,EAAE,iBAAiB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAC9F,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,EAAE,CAAC;IACjB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,oFAAoF;AACpF,MAAM,WAAW,OAAO;IACtB,IAAI,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE;AAED,iFAAiF;AACjF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,iBAAiB,CAAC;CAC1B;AAED,yDAAyD;AACzD,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,uDAAuD;AACvD,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;IACjE,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;CAC1D;AAED,MAAM,MAAM,OAAO,GAAG,CACpB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,EAAE,SAAS,KACZ,aAAa,CAAC;AAEnB,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;AAE1E,yFAAyF;AACzF,MAAM,MAAM,WAAW,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,gBAAgB,GAAG,IAAI,CAAC;AAEpE,MAAM,WAAW,UAAU;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,8DAA8D;IAC9D,WAAW,CAAC,EAAE,WAAW,CAAC;CAC3B"}

package/dist/hub/types.js

@@ -0,0 +1,3 @@
+/** Public types for `@narai/connector-hub`. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/hub/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/hub/types.ts"],"names":[],"mappings":"AAAA,+CAA+C"}

package/dist/toolkit/_optional.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Wrap a dynamic `import(modName)` so that `ERR_MODULE_NOT_FOUND` (and the
+ * older CommonJS `MODULE_NOT_FOUND`) becomes a friendly error matching the
+ * Python `ImportError` style: the user sees the package name and the exact
+ * `npm install` command needed.
+ *
+ * Anything other than a not-found error is rethrown unchanged — we don't
+ * want to swallow real import failures (syntax errors, etc.).
+ */
+export declare function importOptional<T>(modName: string, installName?: string): Promise<T>;
+export declare function isBinaryOnPath(binaryName: string): boolean;
+/** Test helper — wipe the PATH probe cache between tests. */
+export declare function _resetBinaryProbeCache(): void;
+//# sourceMappingURL=_optional.d.ts.map

package/dist/toolkit/_optional.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_optional.d.ts","sourceRoot":"","sources":["../../src/toolkit/_optional.ts"],"names":[],"mappings":"AAqBA;;;;;;;;GAQG;AACH,wBAAsB,cAAc,CAAC,CAAC,EACpC,OAAO,EAAE,MAAM,EACf,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,CAAC,CAAC,CA8BZ;AAsBD,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAiB1D;AAED,6DAA6D;AAC7D,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/toolkit/_optional.js

@@ -0,0 +1,96 @@
+/**
+ * _optional.ts — shared helpers for graceful degradation when an optional
+ * dependency is missing.
+ *
+ * Two primitives:
+ *   - `importOptional(modName, installName?)`: wrap a dynamic `import(x)` so
+ *     an unresolvable module raises a user-friendly `Error` naming the
+ *     npm package and the exact install command, matching the Python
+ *     reference's `ImportError` style. Promoted from `extract_binary.ts`
+ *     so `extract_multimodal.ts` can reuse it.
+ *   - `isBinaryOnPath(binaryName)`: probe `PATH` for an external CLI tool
+ *     (e.g. `faster-whisper`, `yt-dlp`) by running `<bin> --version` via
+ *     `spawnSync` and returning whether the exit code was 0. Suppresses
+ *     stdio, safe to call in hot paths. Backbone of the multimodal
+ *     feature flag (`multimodal.enabled: optional`) — callers surface a
+ *     warning when this returns false instead of erroring out.
+ */
+import { spawnSync } from "node:child_process";
+// ── Optional-dep loader ────────────────────────────────────────────
+/**
+ * Wrap a dynamic `import(modName)` so that `ERR_MODULE_NOT_FOUND` (and the
+ * older CommonJS `MODULE_NOT_FOUND`) becomes a friendly error matching the
+ * Python `ImportError` style: the user sees the package name and the exact
+ * `npm install` command needed.
+ *
+ * Anything other than a not-found error is rethrown unchanged — we don't
+ * want to swallow real import failures (syntax errors, etc.).
+ */
+export async function importOptional(modName, installName) {
+    try {
+        return (await import(modName));
+    }
+    catch (e) {
+        const err = e;
+        const msg = typeof err.message === "string" ? err.message : "";
+        // Match both Node's native loader (`ERR_MODULE_NOT_FOUND`) and
+        // Vitest/Vite's loader (message-shaped errors). Real syntax errors
+        // from inside a resolved module produce `SyntaxError` (name), which
+        // we intentionally do NOT rewrite — rewriting would hide user bugs.
+        const notFound = err.code === "ERR_MODULE_NOT_FOUND" ||
+            err.code === "MODULE_NOT_FOUND" ||
+            (err.name !== "SyntaxError" &&
+                (msg.includes("Failed to load url") ||
+                    msg.includes("Cannot find module") ||
+                    msg.includes("Cannot find package") ||
+                    msg.includes("does not provide an export")));
+        if (notFound) {
+            const pkgName = installName ??
+                (modName.startsWith("@")
+                    ? modName.split("/").slice(0, 2).join("/")
+                    : (modName.split("/")[0] ?? modName));
+            throw new Error(`Missing optional dependency '${pkgName}'. Install with: npm install ${pkgName}`);
+        }
+        throw e;
+    }
+}
+// ── PATH probing ────────────────────────────────────────────────────
+/**
+ * Return true when `binaryName` is resolvable on `PATH` (i.e. the user's
+ * shell could run it). Implementation: invoke `<binaryName> --version`
+ * via `spawnSync` with stdio suppressed.
+ *
+ * `spawnSync` returns an object with:
+ *   - `error` populated when the binary isn't found (ENOENT).
+ *   - `status` set when the binary ran (even if `--version` isn't a real
+ *     flag — we only care that the process launched, not its exit code).
+ *
+ * So presence = no error AND status is a number. Non-zero statuses still
+ * count as "present" because some legacy tools use `--version` for help.
+ *
+ * Never throws. Caches the result per binary name for the lifetime of
+ * the Node process (PATH doesn't change mid-run).
+ */
+const _probeCache = new Map();
+export function isBinaryOnPath(binaryName) {
+    const cached = _probeCache.get(binaryName);
+    if (cached !== undefined)
+        return cached;
+    const result = spawnSync(binaryName, ["--version"], {
+        stdio: "ignore",
+        // Guard against a binary that hangs on --version: cap at 5s.
+        timeout: 5_000,
+    });
+    // spawnSync returns `error` set when the binary isn't found (ENOENT),
+    // or a non-null `status` / `signal` when it ran.
+    const present = result.error === undefined || result.error === null
+        ? result.status !== null || result.signal !== null
+        : false;
+    _probeCache.set(binaryName, present);
+    return present;
+}
+/** Test helper — wipe the PATH probe cache between tests. */
+export function _resetBinaryProbeCache() {
+    _probeCache.clear();
+}
+//# sourceMappingURL=_optional.js.map

package/dist/toolkit/_optional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"_optional.js","sourceRoot":"","sources":["../../src/toolkit/_optional.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAE/C,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,OAAe,EACf,WAAoB;IAEpB,IAAI,CAAC;QACH,OAAO,CAAC,MAAM,MAAM,CAAC,OAAO,CAAC,CAAM,CAAC;IACtC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,MAAM,GAAG,GAAG,CAA0B,CAAC;QACvC,MAAM,GAAG,GAAG,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/D,+DAA+D;QAC/D,mEAAmE;QACnE,oEAAoE;QACpE,oEAAoE;QACpE,MAAM,QAAQ,GACZ,GAAG,CAAC,IAAI,KAAK,sBAAsB;YACnC,GAAG,CAAC,IAAI,KAAK,kBAAkB;YAC/B,CAAC,GAAG,CAAC,IAAI,KAAK,aAAa;gBACzB,CAAC,GAAG,CAAC,QAAQ,CAAC,oBAAoB,CAAC;oBACjC,GAAG,CAAC,QAAQ,CAAC,oBAAoB,CAAC;oBAClC,GAAG,CAAC,QAAQ,CAAC,qBAAqB,CAAC;oBACnC,GAAG,CAAC,QAAQ,CAAC,4BAA4B,CAAC,CAAC,CAAC,CAAC;QACnD,IAAI,QAAQ,EAAE,CAAC;YACb,MAAM,OAAO,GACX,WAAW;gBACX,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;oBACtB,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;oBAC1C,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,OAAO,CAAC,CAAC,CAAC;YAC1C,MAAM,IAAI,KAAK,CACb,gCAAgC,OAAO,gCAAgC,OAAO,EAAE,CACjF,CAAC;QACJ,CAAC;QACD,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED,uEAAuE;AAEvE;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,GAAG,IAAI,GAAG,EAAmB,CAAC;AAE/C,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C,MAAM,MAAM,GAAG,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;IAC3C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,MAAM,CAAC;IAExC,MAAM,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,CAAC,WAAW,CAAC,EAAE;QAClD,KAAK,EAAE,QAAQ;QACf,6DAA6D;QAC7D,OAAO,EAAE,KAAK;KACf,CAAC,CAAC;IACH,sEAAsE;IACtE,iDAAiD;IACjD,MAAM,OAAO,GACX,MAAM,CAAC,KAAK,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,KAAK,IAAI;QACjD,CAAC,CAAC,MAAM,CAAC,MAAM,KAAK,IAAI,IAAI,MAAM,CAAC,MAAM,KAAK,IAAI;QAClD,CAAC,CAAC,KAAK,CAAC;IACZ,WAAW,CAAC,GAAG,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;IACrC,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,6DAA6D;AAC7D,MAAM,UAAU,sBAAsB;IACpC,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC"}

package/dist/toolkit/agent_cli.d.ts

@@ -0,0 +1,33 @@
+/**
+ * agent_cli — shared CLI argument parser for connector packages.
+ *
+ * Connectors all accept the same `--action <name> --params <json>` shape.
+ * This helper centralises the parser, keyed by an explicit set of valid
+ * flag names so unknown flags still throw. Each caller keeps its own
+ * help text and post-parse validation (e.g. JSON-shaped `--params`).
+ */
+/** Parsed result. Keys match the lowercase flag names. */
+export interface ParsedAgentArgs {
+    /** The `<name>` portion of `--action <name>` or `--action=<name>`. */
+    action?: string;
+    /** The `<json>` portion of `--params <json>` or `--params=<json>`. */
+    params?: string;
+    /** `true` when `-h` / `--help` was passed. */
+    help?: boolean;
+}
+/** Closed set of valid flag names (without the leading `--`). */
+export interface FlagSpec {
+    readonly flags: readonly string[];
+}
+/**
+ * Parse `argv` against a closed set of valid flag names.
+ *
+ * Accepted shapes:
+ *   --flag value
+ *   --flag=value
+ *   -h / --help
+ *
+ * Throws on any positional, bare `-x`, or unrecognised `--name`.
+ */
+export declare function parseAgentArgs(argv: readonly string[], spec: FlagSpec): ParsedAgentArgs;
+//# sourceMappingURL=agent_cli.d.ts.map

package/dist/toolkit/agent_cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_cli.d.ts","sourceRoot":"","sources":["../../src/toolkit/agent_cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,eAAe;IAC9B,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sEAAsE;IACtE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8CAA8C;IAC9C,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,iEAAiE;AACjE,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,IAAI,EAAE,QAAQ,GACb,eAAe,CAwCjB"}

package/dist/toolkit/agent_cli.js

@@ -0,0 +1,62 @@
+/**
+ * agent_cli — shared CLI argument parser for connector packages.
+ *
+ * Connectors all accept the same `--action <name> --params <json>` shape.
+ * This helper centralises the parser, keyed by an explicit set of valid
+ * flag names so unknown flags still throw. Each caller keeps its own
+ * help text and post-parse validation (e.g. JSON-shaped `--params`).
+ */
+/**
+ * Parse `argv` against a closed set of valid flag names.
+ *
+ * Accepted shapes:
+ *   --flag value
+ *   --flag=value
+ *   -h / --help
+ *
+ * Throws on any positional, bare `-x`, or unrecognised `--name`.
+ */
+export function parseAgentArgs(argv, spec) {
+    const valid = new Set(spec.flags);
+    const out = {};
+    let i = 0;
+    while (i < argv.length) {
+        const a = argv[i];
+        if (a === undefined) {
+            i++;
+            continue;
+        }
+        if (a === "-h" || a === "--help") {
+            out.help = true;
+            i++;
+            continue;
+        }
+        if (!a.startsWith("--")) {
+            throw new Error(`unrecognized argument: ${a}`);
+        }
+        let name;
+        let value;
+        const eq = a.indexOf("=");
+        if (eq >= 0) {
+            name = a.slice(2, eq);
+            value = a.slice(eq + 1);
+            i++;
+        }
+        else {
+            name = a.slice(2);
+            value = argv[i + 1];
+            i += 2;
+        }
+        if (!valid.has(name)) {
+            throw new Error(`unrecognized argument: --${name}`);
+        }
+        if (name === "action") {
+            out.action = value ?? "";
+        }
+        else if (name === "params") {
+            out.params = value ?? "";
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=agent_cli.js.map

package/dist/toolkit/agent_cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_cli.js","sourceRoot":"","sources":["../../src/toolkit/agent_cli.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAiBH;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAuB,EACvB,IAAc;IAEd,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAClC,MAAM,GAAG,GAAoB,EAAE,CAAC;IAChC,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,QAAQ,EAAE,CAAC;YACjC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;YAChB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;YACxB,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,EAAE,CAAC,CAAC;QACjD,CAAC;QACD,IAAI,IAAY,CAAC;QACjB,IAAI,KAAyB,CAAC;QAC9B,MAAM,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;QAC1B,IAAI,EAAE,IAAI,CAAC,EAAE,CAAC;YACZ,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACtB,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC;YACxB,CAAC,EAAE,CAAC;QACN,CAAC;aAAM,CAAC;YACN,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAClB,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACpB,CAAC,IAAI,CAAC,CAAC;QACT,CAAC;QACD,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACrB,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC;QACtD,CAAC;QACD,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YACtB,GAAG,CAAC,MAAM,GAAG,KAAK,IAAI,EAAE,CAAC;QAC3B,CAAC;aAAM,IAAI,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,GAAG,CAAC,MAAM,GAAG,KAAK,IAAI,EAAE,CAAC;QAC3B,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/toolkit/agent_resolver.d.ts

@@ -0,0 +1,46 @@
+/**
+ * agent_resolver — locate a connector's CLI on disk via the canonical
+ * 4-step fallback every consumer (the hub, doc-wiki's wrappers, etc.) needs:
+ *
+ *   1. `<NAME>_AGENT_CLI` env var (operator escape hatch).
+ *   2. `~/.claude/plugins/cache/<name>-agent-plugin*` — populated by Claude
+ *      Code's plugin manager.
+ *   3. `${CLAUDE_PLUGIN_DATA}/node_modules/<package>/<cliRelativePath>` —
+ *      where the connector's `SessionStart` hook installs it.
+ *   4. `~/src/connectors/<name>-agent-connector/<cliRelativePath>` — the
+ *      developer-machine fallback.
+ *
+ * Returns null if no candidate exists, so callers can fail with a clear
+ * message instead of crashing on `spawn`.
+ */
+export interface ResolveAgentCliOptions {
+    /** Connector short name (e.g. `"confluence"`, `"db"`, `"aws"`). */
+    name: string;
+    /** Override env-var name. Default: `<NAME>_AGENT_CLI` (uppercased + underscores for hyphens). */
+    envVar?: string;
+    /** Substring matched against entries in `~/.claude/plugins/cache/`. Default: `<name>-agent-plugin`. */
+    pluginNameContains?: string;
+    /** npm package the connector is published as. Default: `@narai/<name>-agent-connector`. */
+    packageName?: string;
+    /** CLI path within the package. Default: `dist/cli.js`. */
+    cliRelativePath?: string;
+    /** Dev-fallback root. Default: `~/src/connectors/`. */
+    devRoot?: string;
+    /** Override for `process.env`. Used by tests; production callers leave it alone. */
+    envOverride?: NodeJS.ProcessEnv;
+    /** Override for `os.homedir()`. Used by tests. */
+    homeOverride?: string;
+}
+export type ResolutionSource = "env" | "plugin-cache" | "claude-plugin-data" | "dev-fallback";
+export interface ResolvedAgentCli {
+    /** Always `"node"` — connector CLIs are always invoked through node. */
+    command: string;
+    /** `[absoluteCliPath]`; pass to `child_process.spawn(command, [...args, ...callerArgs])`. */
+    args: string[];
+    /** Which fallback path produced the resolution. Useful for diagnostics. */
+    source: ResolutionSource;
+    /** Absolute path that was found on disk. */
+    resolvedPath: string;
+}
+export declare function resolveAgentCli(opts: ResolveAgentCliOptions): ResolvedAgentCli | null;
+//# sourceMappingURL=agent_resolver.d.ts.map

package/dist/toolkit/agent_resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent_resolver.d.ts","sourceRoot":"","sources":["../../src/toolkit/agent_resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAMH,MAAM,WAAW,sBAAsB;IACrC,mEAAmE;IACnE,IAAI,EAAE,MAAM,CAAC;IACb,iGAAiG;IACjG,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,uGAAuG;IACvG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,uDAAuD;IACvD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,WAAW,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,kDAAkD;IAClD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,GACxB,KAAK,GACL,cAAc,GACd,oBAAoB,GACpB,cAAc,CAAC;AAEnB,MAAM,WAAW,gBAAgB;IAC/B,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,6FAA6F;IAC7F,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,2EAA2E;IAC3E,MAAM,EAAE,gBAAgB,CAAC;IACzB,4CAA4C;IAC5C,YAAY,EAAE,MAAM,CAAC;CACtB;AAkBD,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,gBAAgB,GAAG,IAAI,CAiDrF"}

package/dist/toolkit/agent_resolver.js

@@ -0,0 +1,78 @@
+/**
+ * agent_resolver — locate a connector's CLI on disk via the canonical
+ * 4-step fallback every consumer (the hub, doc-wiki's wrappers, etc.) needs:
+ *
+ *   1. `<NAME>_AGENT_CLI` env var (operator escape hatch).
+ *   2. `~/.claude/plugins/cache/<name>-agent-plugin*` — populated by Claude
+ *      Code's plugin manager.
+ *   3. `${CLAUDE_PLUGIN_DATA}/node_modules/<package>/<cliRelativePath>` —
+ *      where the connector's `SessionStart` hook installs it.
+ *   4. `~/src/connectors/<name>-agent-connector/<cliRelativePath>` — the
+ *      developer-machine fallback.
+ *
+ * Returns null if no candidate exists, so callers can fail with a clear
+ * message instead of crashing on `spawn`.
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+function defaultEnvVar(name) {
+    return `${name.toUpperCase().replace(/-/g, "_")}_AGENT_CLI`;
+}
+function defaultPluginNameContains(name) {
+    return `${name}-agent-plugin`;
+}
+function defaultPackageName(name) {
+    return `@narai/${name}-agent-connector`;
+}
+function defaultDevRoot(home) {
+    return path.join(home, "src", "connectors");
+}
+export function resolveAgentCli(opts) {
+    const env = opts.envOverride ?? process.env;
+    const home = opts.homeOverride ?? os.homedir();
+    const envVar = opts.envVar ?? defaultEnvVar(opts.name);
+    const pluginContains = opts.pluginNameContains ?? defaultPluginNameContains(opts.name);
+    const packageName = opts.packageName ?? defaultPackageName(opts.name);
+    const cliRelative = opts.cliRelativePath ?? "dist/cli.js";
+    const devRoot = opts.devRoot ?? defaultDevRoot(home);
+    // 1. Explicit env-var override.
+    const envPath = env[envVar];
+    if (typeof envPath === "string" && envPath !== "" && fs.existsSync(envPath)) {
+        return { command: "node", args: [envPath], source: "env", resolvedPath: envPath };
+    }
+    // 2. Plugin cache lookup.
+    const pluginCache = path.join(home, ".claude", "plugins", "cache");
+    if (fs.existsSync(pluginCache)) {
+        let entries;
+        try {
+            entries = fs.readdirSync(pluginCache);
+        }
+        catch {
+            entries = [];
+        }
+        for (const entry of entries) {
+            if (!entry.includes(pluginContains))
+                continue;
+            const candidate = path.join(pluginCache, entry, "node_modules", packageName, cliRelative);
+            if (fs.existsSync(candidate)) {
+                return { command: "node", args: [candidate], source: "plugin-cache", resolvedPath: candidate };
+            }
+        }
+    }
+    // 3. CLAUDE_PLUGIN_DATA install location.
+    const pluginData = env["CLAUDE_PLUGIN_DATA"];
+    if (typeof pluginData === "string" && pluginData !== "") {
+        const candidate = path.join(pluginData, "node_modules", packageName, cliRelative);
+        if (fs.existsSync(candidate)) {
+            return { command: "node", args: [candidate], source: "claude-plugin-data", resolvedPath: candidate };
+        }
+    }
+    // 4. Dev fallback.
+    const devCandidate = path.join(devRoot, `${opts.name}-agent-connector`, cliRelative);
+    if (fs.existsSync(devCandidate)) {
+        return { command: "node", args: [devCandidate], source: "dev-fallback", resolvedPath: devCandidate };
+    }
+    return null;
+}
+//# sourceMappingURL=agent_resolver.js.map

package/dist/toolkit/agent_resolver.js.map

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

package/dist/toolkit/audit/events.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Audit event shapes. Every event becomes one line in a JSONL file.
+ *
+ * `event_type` is the discriminant; the union is open (extensible) because
+ * connectors may emit their own event types via `AuditWriter.logEvent`.
+ */
+export interface BaseEvent {
+    event_type: string;
+    timestamp: string;
+    session_id: string;
+    details?: Record<string, unknown>;
+}
+/** Emitted on every action invocation (after policy gate). */
+export interface ActionEvent extends BaseEvent {
+    event_type: "action";
+    connector: string;
+    action: string;
+    status: string;
+    execution_time_ms: number;
+}
+/** Policy-gate decision events. */
+export interface PolicyEvent extends BaseEvent {
+    event_type: "policy_success" | "policy_denied" | "policy_escalate";
+    connector: string;
+    action: string;
+    reason: string;
+    kind: string;
+    aspects?: readonly string[];
+}
+/** Grant lifecycle. */
+export interface GrantEvent extends BaseEvent {
+    event_type: "grant_added" | "grant_expired" | "grant_revoked";
+    grant_type: string;
+    ttl_seconds?: number;
+}
+/** Hardship — also written to JSONL via the hardship module, but audited too. */
+export interface HardshipEvent extends BaseEvent {
+    event_type: "hardship_recorded";
+    connector: string;
+    action: string;
+    kind: string;
+    context: string;
+}
+export type AuditEvent = BaseEvent | ActionEvent | PolicyEvent | GrantEvent | HardshipEvent;
+//# sourceMappingURL=events.d.ts.map

package/dist/toolkit/audit/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../../src/toolkit/audit/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,SAAS;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,8DAA8D;AAC9D,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,UAAU,EAAE,QAAQ,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,mCAAmC;AACnC,MAAM,WAAW,WAAY,SAAQ,SAAS;IAC5C,UAAU,EACN,gBAAgB,GAChB,eAAe,GACf,iBAAiB,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,uBAAuB;AACvB,MAAM,WAAW,UAAW,SAAQ,SAAS;IAC3C,UAAU,EAAE,aAAa,GAAG,eAAe,GAAG,eAAe,CAAC;IAC9D,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,iFAAiF;AACjF,MAAM,WAAW,aAAc,SAAQ,SAAS;IAC9C,UAAU,EAAE,mBAAmB,CAAC;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,UAAU,GAClB,SAAS,GACT,WAAW,GACX,WAAW,GACX,UAAU,GACV,aAAa,CAAC"}

package/dist/toolkit/audit/events.js

@@ -0,0 +1,8 @@
+/**
+ * Audit event shapes. Every event becomes one line in a JSONL file.
+ *
+ * `event_type` is the discriminant; the union is open (extensible) because
+ * connectors may emit their own event types via `AuditWriter.logEvent`.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/toolkit/audit/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../../src/toolkit/audit/events.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/toolkit/audit/writer.d.ts

@@ -0,0 +1,16 @@
+import type { AuditEvent } from "./events.js";
+export interface AuditWriterOptions {
+    enabled: boolean;
+    /** Absolute path to the JSONL file. Required when `enabled` is true. */
+    path?: string;
+    /** Fixed session id (tests). If omitted, a random 12-char hex is generated. */
+    sessionId?: string;
+}
+export declare function scrubSecrets(text: string): string;
+export interface AuditWriter {
+    readonly enabled: boolean;
+    readonly sessionId: string;
+    logEvent(event: Omit<AuditEvent, "timestamp" | "session_id"> & Record<string, unknown>): void;
+}
+export declare function createAuditWriter(opts: AuditWriterOptions): AuditWriter;
+//# sourceMappingURL=writer.d.ts.map

package/dist/toolkit/audit/writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer.d.ts","sourceRoot":"","sources":["../../../src/toolkit/audit/writer.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,OAAO,CAAC;IACjB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAQD,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIjD;AAOD,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CACN,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,WAAW,GAAG,YAAY,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5E,IAAI,CAAC;CACT;AA+CD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,kBAAkB,GAAG,WAAW,CAQvE"}