@personaxis/core 0.11.0

package/dist/tool-calling.js

@@ -0,0 +1,168 @@
+/**
+ * Tool-calling client (G1) — provider-agnostic action proposals.
+ *
+ * Primary path: OpenAI-style native function-calling (`tools` + `tool_choice`),
+ * which Cohere/OpenAI/together/etc. expose on /chat/completions. Fallback path
+ * (when an endpoint rejects `tools` with a 400): a ReAct-style single-action JSON
+ * (`{thought, tool, args}`) under the same constrained-decoding strategy chain the
+ * appraiser uses (json_schema → json_object → plain). Either way the model only
+ * *proposes* a tool call; the agent loop gates + executes.
+ */
+import { repairToolArgs } from "./tool-repair.js";
+function extractUsage(json) {
+    const u = json.usage;
+    if (!u)
+        return undefined;
+    const total = u.total_tokens ?? (u.prompt_tokens ?? 0) + (u.completion_tokens ?? 0);
+    return { prompt_tokens: u.prompt_tokens ?? 0, completion_tokens: u.completion_tokens ?? 0, total_tokens: total };
+}
+function url(cfg) {
+    return `${cfg.endpoint.replace(/\/$/, "")}/chat/completions`;
+}
+function headers(cfg) {
+    return { "content-type": "application/json", ...(cfg.apiKey ? { authorization: `Bearer ${cfg.apiKey}` } : {}) };
+}
+async function safeText(res) {
+    try {
+        return (await res.text()).slice(0, 300);
+    }
+    catch {
+        return "";
+    }
+}
+function parseArgs(raw) {
+    try {
+        const v = JSON.parse(raw || "{}");
+        return v && typeof v === "object" ? v : {};
+    }
+    catch {
+        // FR.10 (OpenClaw port): salvage almost-JSON before giving up — a repaired
+        // call saves a full model round-trip on weaker tool-callers.
+        const r = repairToolArgs(raw);
+        return r.ok && r.value ? r.value : {};
+    }
+}
+/**
+ * Request the next action. `preferFallback` lets the caller skip the native
+ * attempt once it has learned the endpoint doesn't support `tools`.
+ */
+export async function requestToolCall(cfg, messages, tools, preferFallback = false) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    if (!preferFallback) {
+        const body = {
+            model: cfg.model,
+            messages,
+            tools: tools.map((t) => ({
+                type: "function",
+                function: { name: t.name, description: t.description, parameters: t.parameters },
+            })),
+            tool_choice: "auto",
+            temperature: 0.3,
+            max_tokens: cfg.maxTokens ?? 1024,
+        };
+        const res = await fetchImpl(url(cfg), { method: "POST", headers: headers(cfg), body: JSON.stringify(body) });
+        if (res.ok) {
+            const json = (await res.json());
+            const msg = json.choices?.[0]?.message ?? {};
+            const toolCalls = (msg.tool_calls ?? []).map((tc) => ({
+                id: tc.id,
+                name: tc.function.name,
+                args: parseArgs(tc.function.arguments),
+            }));
+            return { text: (msg.content ?? "").trim(), toolCalls, usedFallback: false, usage: extractUsage(json) };
+        }
+        // Auth/rate/server errors won't be fixed by the fallback — surface them.
+        if (res.status === 401 || res.status === 403 || res.status === 429 || res.status >= 500) {
+            throw new Error(`tool-calling HTTP ${res.status}: ${await safeText(res)}`);
+        }
+        // 400/422 → endpoint likely doesn't support `tools`; degrade to ReAct.
+    }
+    return reactFallback(cfg, messages, tools);
+}
+const REACT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    required: ["tool", "args"],
+    properties: {
+        thought: { type: "string" },
+        tool: { type: "string" },
+        args: { type: "object" },
+    },
+};
+/** ReAct fallback: render the transcript to text, ask for ONE JSON action. */
+async function reactFallback(cfg, messages, tools) {
+    const fetchImpl = cfg.fetchImpl ?? fetch;
+    const toolDocs = tools
+        .map((t) => `- ${t.name}(${Object.keys(t.parameters.properties ?? {}).join(", ")}): ${t.description}`)
+        .join("\n");
+    const transcript = messages
+        .map((m) => {
+        if (m.role === "tool")
+            return `TOOL_RESULT[${m.name ?? ""}]: ${m.content}`;
+        if (m.role === "assistant" && m.tool_calls?.length)
+            return `ASSISTANT called: ${m.tool_calls.map((tc) => `${tc.function.name}(${tc.function.arguments})`).join(", ")}`;
+        return `${m.role.toUpperCase()}: ${m.content}`;
+    })
+        .join("\n");
+    const system = [
+        messages.find((m) => m.role === "system")?.content ?? "",
+        "",
+        "You are an agent that acts ONLY by emitting a single JSON action.",
+        "Available tools:",
+        toolDocs,
+        "",
+        'Respond with exactly one JSON object: {"thought": string, "tool": string, "args": object}.',
+        'When the task is complete, use {"tool":"finish","args":{"summary":"..."}}.',
+    ].join("\n");
+    const strategies = [
+        { type: "json_schema", json_schema: { name: "agent_action", strict: true, schema: REACT_SCHEMA } },
+        { type: "json_object" },
+        undefined,
+    ];
+    let lastErr = "no response";
+    for (const responseFormat of strategies) {
+        const body = {
+            model: cfg.model,
+            messages: [
+                { role: "system", content: system },
+                { role: "user", content: `Transcript so far:\n${transcript}\n\nEmit the next action as JSON.` },
+            ],
+            ...(responseFormat ? { response_format: responseFormat } : {}),
+            temperature: 0.3,
+            max_tokens: cfg.maxTokens ?? 1024,
+        };
+        const res = await fetchImpl(url(cfg), { method: "POST", headers: headers(cfg), body: JSON.stringify(body) });
+        if (res.ok) {
+            const json = (await res.json());
+            const usage = extractUsage(json);
+            const content = json.choices?.[0]?.message?.content ?? "{}";
+            let parsed;
+            try {
+                parsed = JSON.parse(content);
+            }
+            catch {
+                const m = content.match(/\{[\s\S]*\}/);
+                try {
+                    parsed = m ? JSON.parse(m[0]) : {};
+                }
+                catch {
+                    const r = repairToolArgs(m ? m[0] : content); // FR.10 repair pass
+                    parsed = r.ok && r.value ? r.value : {};
+                }
+            }
+            if (!parsed.tool) {
+                return { text: parsed.thought ?? content.slice(0, 200), toolCalls: [], usedFallback: true, usage };
+            }
+            return {
+                text: parsed.thought ?? "",
+                toolCalls: [{ id: `react_${Date.now()}`, name: parsed.tool, args: parsed.args ?? {} }],
+                usedFallback: true,
+                usage,
+            };
+        }
+        lastErr = `HTTP ${res.status}: ${await safeText(res)}`;
+        if (res.status === 401 || res.status === 403 || res.status === 429 || res.status >= 500)
+            break;
+    }
+    throw new Error(`tool-calling fallback ${lastErr}`);
+}

package/dist/tool-repair.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool-call repair (FR.10 — ported from OpenClaw's self-contained module):
+ * salvage malformed / truncated LLM tool-call argument JSON before rejecting
+ * it. Weaker models routinely emit almost-JSON — a code fence around it,
+ * single quotes, a trailing comma, or a truncation mid-object. Rejecting those
+ * costs a full round-trip; a deterministic repair pass recovers most of them.
+ *
+ * Repairs are CONSERVATIVE and layered; the result reports `repaired: true`
+ * so callers can log/trace that the model needed help (a quality signal).
+ */
+export interface RepairResult {
+    ok: boolean;
+    value?: Record<string, unknown>;
+    repaired: boolean;
+    /** Which repairs were applied, in order (for tracing). */
+    applied: string[];
+    error?: string;
+}
+/** Parse tool-call args, repairing common LLM malformations when needed. */
+export declare function repairToolArgs(raw: string): RepairResult;

package/dist/tool-repair.js

@@ -0,0 +1,119 @@
+/**
+ * Tool-call repair (FR.10 — ported from OpenClaw's self-contained module):
+ * salvage malformed / truncated LLM tool-call argument JSON before rejecting
+ * it. Weaker models routinely emit almost-JSON — a code fence around it,
+ * single quotes, a trailing comma, or a truncation mid-object. Rejecting those
+ * costs a full round-trip; a deterministic repair pass recovers most of them.
+ *
+ * Repairs are CONSERVATIVE and layered; the result reports `repaired: true`
+ * so callers can log/trace that the model needed help (a quality signal).
+ */
+/** Parse tool-call args, repairing common LLM malformations when needed. */
+export function repairToolArgs(raw) {
+    const applied = [];
+    let text = raw.trim();
+    const attempt = () => {
+        try {
+            const v = JSON.parse(text);
+            return v && typeof v === "object" && !Array.isArray(v) ? v : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // 0. Already valid.
+    let v = attempt();
+    if (v)
+        return { ok: true, value: v, repaired: false, applied };
+    // 1. Strip a markdown code fence (```json ... ```).
+    const fence = text.match(/^```[a-zA-Z]*\s*\n?([\s\S]*?)\n?```\s*$/);
+    if (fence) {
+        text = fence[1].trim();
+        applied.push("strip-code-fence");
+        if ((v = attempt()))
+            return { ok: true, value: v, repaired: true, applied };
+    }
+    // 2. Extract the outermost {...} from surrounding prose.
+    const first = text.indexOf("{");
+    const last = text.lastIndexOf("}");
+    if (first > 0 || (first === 0 && last !== text.length - 1)) {
+        if (first !== -1 && last > first) {
+            text = text.slice(first, last + 1);
+            applied.push("extract-object");
+            if ((v = attempt()))
+                return { ok: true, value: v, repaired: true, applied };
+        }
+    }
+    // 3. Normalize single-quoted strings/keys → double quotes (when no double
+    //    quotes are present at all — avoids corrupting embedded apostrophes).
+    if (!text.includes('"') && text.includes("'")) {
+        text = text.replace(/'/g, '"');
+        applied.push("single-to-double-quotes");
+        if ((v = attempt()))
+            return { ok: true, value: v, repaired: true, applied };
+    }
+    // 4. Quote unquoted keys ({key: → {"key":).
+    const quotedKeys = text.replace(/([{,]\s*)([A-Za-z_][A-Za-z0-9_]*)(\s*:)/g, '$1"$2"$3');
+    if (quotedKeys !== text) {
+        text = quotedKeys;
+        applied.push("quote-keys");
+        if ((v = attempt()))
+            return { ok: true, value: v, repaired: true, applied };
+    }
+    // 5. Remove trailing commas before } or ].
+    const noTrailing = text.replace(/,\s*([}\]])/g, "$1");
+    if (noTrailing !== text) {
+        text = noTrailing;
+        applied.push("strip-trailing-commas");
+        if ((v = attempt()))
+            return { ok: true, value: v, repaired: true, applied };
+    }
+    // 6. Truncation: close an unterminated string, then balance braces/brackets.
+    const closed = closeTruncated(text);
+    if (closed !== text) {
+        text = closed;
+        applied.push("close-truncated");
+        if ((v = attempt()))
+            return { ok: true, value: v, repaired: true, applied };
+    }
+    return { ok: false, repaired: applied.length > 0, applied, error: "unrecoverable tool-call JSON" };
+}
+/** Close an unterminated trailing string and balance {} / []. */
+function closeTruncated(text) {
+    let inString = false;
+    let escaped = false;
+    const stack = [];
+    for (const ch of text) {
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (ch === '"') {
+            inString = !inString;
+            continue;
+        }
+        if (inString)
+            continue;
+        if (ch === "{")
+            stack.push("}");
+        else if (ch === "[")
+            stack.push("]");
+        else if (ch === "}" || ch === "]") {
+            if (stack[stack.length - 1] === ch)
+                stack.pop();
+        }
+    }
+    let out = text;
+    // A truncated value like `{"a": "unfinish` → close the string first.
+    if (inString)
+        out += '"';
+    // Drop a dangling comma/colon before closing (`{"a": 1,` / `{"a":`).
+    out = out.replace(/[,:]\s*$/, (m) => (m.trim() === ":" ? ': null' : ""));
+    while (stack.length > 0)
+        out += stack.pop();
+    return out;
+}

package/dist/tools/exec.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Real action executors (G1) — the surface the governed agent loop acts through.
+ *
+ * Gating happens BEFORE this module (the agent calls evaluateCommand /
+ * evaluateFileWrite and only reaches here on an `allow`). These functions perform
+ * the actual side effect, bounded: commands run with a timeout and truncated
+ * output; file writes resolve against the workspace root. Output is returned, not
+ * printed — the engine stays UI-agnostic.
+ */
+import { spawn } from "node:child_process";
+import { type Policy } from "../sandbox.js";
+/** Hard cap on captured stdout/stderr so a runaway command can't blow up context. */
+export declare const MAX_OUTPUT = 16000;
+export interface ExecResult {
+    ok: boolean;
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    truncated: boolean;
+    timedOut: boolean;
+}
+/**
+ * Run an ALLOWED shell command. When a native sandbox wrapper is available
+ * (macOS Seatbelt / Linux bubblewrap) we spawn that binary directly with explicit
+ * args (no shell). Otherwise we run through the OS shell (cmd.exe on Windows,
+ * /bin/sh on Unix) so the command is portable.
+ */
+export declare function executeCommand(cmd: string, policy: Policy, opts?: {
+    timeoutMs?: number;
+    spawnImpl?: typeof spawn;
+}): Promise<ExecResult>;
+export interface FileResult {
+    ok: boolean;
+    path: string;
+    bytes?: number;
+    content?: string;
+    error?: string;
+}
+/** Overwrite/create a file with content (parent dirs created). */
+export declare function executeFileWrite(path: string, content: string, policy: Policy): FileResult;
+/** Replace the first occurrence of `find` with `replace` in an existing file. */
+export declare function executeFileEdit(path: string, find: string, replace: string, policy: Policy): FileResult;
+/** Read a file's contents (truncated to MAX_OUTPUT). */
+export declare function readFileSafe(path: string, policy: Policy): FileResult;
+/** List a directory (names + type marker). */
+export declare function listDirSafe(path: string, policy: Policy): FileResult;

package/dist/tools/exec.js

@@ -0,0 +1,132 @@
+/**
+ * Real action executors (G1) — the surface the governed agent loop acts through.
+ *
+ * Gating happens BEFORE this module (the agent calls evaluateCommand /
+ * evaluateFileWrite and only reaches here on an `allow`). These functions perform
+ * the actual side effect, bounded: commands run with a timeout and truncated
+ * output; file writes resolve against the workspace root. Output is returned, not
+ * printed — the engine stays UI-agnostic.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync, } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { wrapCommand } from "../sandbox.js";
+/** Hard cap on captured stdout/stderr so a runaway command can't blow up context. */
+export const MAX_OUTPUT = 16_000;
+const DEFAULT_TIMEOUT_MS = 30_000;
+/**
+ * Run an ALLOWED shell command. When a native sandbox wrapper is available
+ * (macOS Seatbelt / Linux bubblewrap) we spawn that binary directly with explicit
+ * args (no shell). Otherwise we run through the OS shell (cmd.exe on Windows,
+ * /bin/sh on Unix) so the command is portable.
+ */
+export function executeCommand(cmd, policy, opts = {}) {
+    const wrapped = wrapCommand(cmd, policy);
+    const useShell = wrapped.sandbox === "none";
+    const spawnFn = opts.spawnImpl ?? spawn;
+    return new Promise((resolveExec) => {
+        const child = useShell
+            ? spawnFn(cmd, { cwd: policy.workspaceRoot, shell: true })
+            : spawnFn(wrapped.command, wrapped.args, { cwd: policy.workspaceRoot, shell: false });
+        let stdout = "";
+        let stderr = "";
+        let truncated = false;
+        let timedOut = false;
+        let settled = false;
+        const finish = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolveExec(r);
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGKILL");
+        }, opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+        child.stdout?.on("data", (d) => {
+            if (stdout.length < MAX_OUTPUT)
+                stdout += d.toString();
+            if (stdout.length >= MAX_OUTPUT) {
+                stdout = stdout.slice(0, MAX_OUTPUT);
+                truncated = true;
+            }
+        });
+        child.stderr?.on("data", (d) => {
+            if (stderr.length < MAX_OUTPUT)
+                stderr += d.toString();
+            if (stderr.length >= MAX_OUTPUT) {
+                stderr = stderr.slice(0, MAX_OUTPUT);
+                truncated = true;
+            }
+        });
+        child.on("error", (err) => {
+            finish({ ok: false, code: null, stdout, stderr: `${stderr}\n[spawn error: ${err.message}]`, truncated, timedOut });
+        });
+        child.on("close", (code) => {
+            finish({ ok: !timedOut && code === 0, code, stdout, stderr, truncated, timedOut });
+        });
+    });
+}
+function abs(path, policy) {
+    return resolve(policy.workspaceRoot, path);
+}
+/** Overwrite/create a file with content (parent dirs created). */
+export function executeFileWrite(path, content, policy) {
+    try {
+        const p = abs(path, policy);
+        mkdirSync(dirname(p), { recursive: true });
+        writeFileSync(p, content, "utf-8");
+        return { ok: true, path: p, bytes: Buffer.byteLength(content) };
+    }
+    catch (e) {
+        return { ok: false, path, error: e.message };
+    }
+}
+/** Replace the first occurrence of `find` with `replace` in an existing file. */
+export function executeFileEdit(path, find, replace, policy) {
+    try {
+        const p = abs(path, policy);
+        if (!existsSync(p))
+            return { ok: false, path: p, error: "file not found" };
+        const orig = readFileSync(p, "utf-8");
+        if (!orig.includes(find))
+            return { ok: false, path: p, error: "find text not present (no change made)" };
+        writeFileSync(p, orig.replace(find, replace), "utf-8");
+        return { ok: true, path: p };
+    }
+    catch (e) {
+        return { ok: false, path, error: e.message };
+    }
+}
+/** Read a file's contents (truncated to MAX_OUTPUT). */
+export function readFileSafe(path, policy) {
+    try {
+        const p = abs(path, policy);
+        if (!existsSync(p))
+            return { ok: false, path: p, error: "file not found" };
+        let content = readFileSync(p, "utf-8");
+        if (content.length > MAX_OUTPUT)
+            content = content.slice(0, MAX_OUTPUT) + "\n…[truncated]";
+        return { ok: true, path: p, content };
+    }
+    catch (e) {
+        return { ok: false, path, error: e.message };
+    }
+}
+/** List a directory (names + type marker). */
+export function listDirSafe(path, policy) {
+    try {
+        const p = abs(path, policy);
+        if (!existsSync(p))
+            return { ok: false, path: p, error: "directory not found" };
+        const entries = readdirSync(p).map((name) => {
+            const isDir = statSync(resolve(p, name)).isDirectory();
+            return isDir ? `${name}/` : name;
+        });
+        return { ok: true, path: p, content: entries.join("\n") };
+    }
+    catch (e) {
+        return { ok: false, path, error: e.message };
+    }
+}

package/dist/tools/registry.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Tool registry (G1) — the governed agent's action vocabulary.
+ *
+ * Each tool declares: a JSON-Schema for its args (used both for native
+ * function-calling and the constrained-JSON fallback), a `gate` that returns a
+ * sandbox verdict (allow | ask | deny) WITHOUT side effects, and an `execute`
+ * that performs the action and returns a text observation to feed back to the
+ * model. The agent loop owns the policy and only calls `execute` after the gate
+ * (and, for `ask`, the human) approves.
+ */
+import { type CommandVerdict, type Policy } from "../sandbox.js";
+export interface ToolSpec {
+    name: string;
+    description: string;
+    /** JSON Schema for the tool's arguments object — the SINGLE schema source
+     * (native function-calling, constrained-JSON fallback, and validateToolArgs
+     * all read it; FR.7 decision: no parallel Zod declaration). */
+    parameters: Record<string, unknown>;
+    /** FR.7: true when the tool cannot change any state — read-only tools may run
+     * in PARALLEL; writers run serially (Claude Code's scheduling rule). */
+    isReadOnly: boolean;
+    /** FR.7: true when concurrent invocations of THIS tool cannot interfere. */
+    isConcurrencySafe: boolean;
+    /** Decide allow | ask | deny for these args under the policy. Pure. */
+    gate(args: Record<string, unknown>, policy: Policy): CommandVerdict;
+    /** Perform the action; returns a text observation for the model. */
+    execute(args: Record<string, unknown>, policy: Policy): Promise<string>;
+}
+/**
+ * FR.7: validate args against the tool's declared JSON Schema (required keys +
+ * primitive types — the registry's schemas are flat by design). Returns the
+ * problems found; empty = valid. Runs BEFORE the gate, so a malformed call is
+ * an input error, never a policy question.
+ */
+export declare function validateToolArgs(spec: ToolSpec, args: Record<string, unknown>): string[];
+export declare const TOOLS: ToolSpec[];
+export declare const FINISH_TOOL = "finish";
+export declare function toolByName(name: string): ToolSpec | undefined;