@personaxis/core 0.11.0

package/dist/skill-review.js

@@ -0,0 +1,67 @@
+/**
+ * Skill security review (F6 — plan/06-skills).
+ *
+ * We don't maintain skills; we USE them from external sources (Anthropic, GitHub,
+ * ClawHub). But ~26% of community skills carry vulnerabilities (Xu & Yan, 2026)
+ * and the ClawHavoc campaign shipped 1,200+ malicious skills. So every skill is
+ * scanned BEFORE use: risky shell/network/eval/secret patterns are flagged, a
+ * verdict is produced, and a content hash is returned for allowlisting. Never
+ * auto-update; pin by hash.
+ */
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+const RULES = [
+    { re: /\brm\s+-rf\b/, severity: "danger", rule: "destructive-rm" },
+    { re: /curl[^\n|]*\|\s*(ba)?sh/i, severity: "danger", rule: "curl-pipe-shell" },
+    { re: /wget[^\n|]*\|\s*(ba)?sh/i, severity: "danger", rule: "wget-pipe-shell" },
+    { re: /base64\s+-+d/i, severity: "danger", rule: "base64-decode-exec" },
+    { re: /\beval\s*\(/, severity: "danger", rule: "eval" },
+    { re: /child_process|subprocess\.|os\.system|exec\(/i, severity: "warn", rule: "process-spawn" },
+    { re: /process\.env\.|os\.environ|\$\{?[A-Z_]*(KEY|TOKEN|SECRET|PASSWORD)/, severity: "warn", rule: "secret-access" },
+    { re: /\bsudo\b/, severity: "warn", rule: "privilege-escalation" },
+    { re: /https?:\/\/(?!github\.com|raw\.githubusercontent\.com|anthropic\.com)[^\s'")]+/i, severity: "info", rule: "external-network" },
+    { re: /~\/\.ssh|id_rsa|\.aws\/credentials|\.npmrc/, severity: "danger", rule: "credential-file-access" },
+];
+const SCANNABLE = new Set([".md", ".sh", ".bash", ".py", ".js", ".ts", ".mjs", ".cjs", ".yaml", ".yml", ".json"]);
+function collectFiles(dir) {
+    const out = [];
+    const walk = (d) => {
+        for (const name of readdirSync(d)) {
+            const p = join(d, name);
+            const st = statSync(p);
+            if (st.isDirectory())
+                walk(p);
+            else if (SCANNABLE.has(extname(name)))
+                out.push(p);
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+export function reviewSkill(skillPath) {
+    if (!existsSync(skillPath)) {
+        throw new Error(`skill path not found: ${skillPath}`);
+    }
+    const isDir = statSync(skillPath).isDirectory();
+    const files = isDir ? collectFiles(skillPath) : [skillPath];
+    const findings = [];
+    const hasher = createHash("sha256");
+    for (const file of files) {
+        const content = readFileSync(file, "utf-8");
+        hasher.update(file).update(content);
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            for (const r of RULES) {
+                const m = lines[i].match(r.re);
+                if (m) {
+                    findings.push({ severity: r.severity, rule: r.rule, file, match: m[0].slice(0, 80) });
+                }
+            }
+        }
+    }
+    const hasDanger = findings.some((f) => f.severity === "danger");
+    const hasWarn = findings.some((f) => f.severity === "warn");
+    const verdict = hasDanger ? "danger" : hasWarn ? "review" : "ok";
+    return { skillPath, files, hash: hasher.digest("hex"), findings, verdict };
+}

package/dist/spec-edit.d.ts

@@ -0,0 +1,30 @@
+/**
+ * F3.7 — surgical, comment-preserving dot-path edits of a persona spec.
+ *
+ * The persona spec (`personaxis.md` frontmatter) is authored YAML with dense
+ * tier/consumer-tag comments. Editing it must NEVER parse→re-serialize (that
+ * strips every author comment) — so, like the migrate codemods, this edits the
+ * raw text: it locates the dot-path's leaf line by indentation and replaces only
+ * the scalar value, keeping indentation and any trailing `# comment`.
+ *
+ * Supported leaves:
+ *   - block scalars at any depth        (a.b.c: value)
+ *   - one-level flow-map leaves          (parent: { key: value, … } → edit key)
+ * A path that resolves to a block/array (not a scalar) is rejected — those are
+ * structural edits the author makes in the file (or via a codemod), not surgical
+ * value changes.
+ */
+/** Read the value at a dot-path from a parsed object (undefined if absent). */
+export declare function getAtPath(root: unknown, dotPath: string): unknown;
+/** Coerce a raw CLI string to the type of an existing sample value (num/bool/string). */
+export declare function coerceLike(raw: string, sample: unknown): unknown;
+export interface SpecEditResult {
+    text: string;
+    previous: unknown;
+}
+/**
+ * Set a scalar at `dotPath` in the raw frontmatter YAML, preserving comments.
+ * `parsed` is the same YAML already parsed (for the current value + type). Throws
+ * with a clear message when the path is missing or is not a scalar leaf.
+ */
+export declare function setScalarAtPath(frontmatterYaml: string, parsed: Record<string, unknown>, dotPath: string, newValue: unknown): SpecEditResult;

package/dist/spec-edit.js

@@ -0,0 +1,137 @@
+/**
+ * F3.7 — surgical, comment-preserving dot-path edits of a persona spec.
+ *
+ * The persona spec (`personaxis.md` frontmatter) is authored YAML with dense
+ * tier/consumer-tag comments. Editing it must NEVER parse→re-serialize (that
+ * strips every author comment) — so, like the migrate codemods, this edits the
+ * raw text: it locates the dot-path's leaf line by indentation and replaces only
+ * the scalar value, keeping indentation and any trailing `# comment`.
+ *
+ * Supported leaves:
+ *   - block scalars at any depth        (a.b.c: value)
+ *   - one-level flow-map leaves          (parent: { key: value, … } → edit key)
+ * A path that resolves to a block/array (not a scalar) is rejected — those are
+ * structural edits the author makes in the file (or via a codemod), not surgical
+ * value changes.
+ */
+const INDENT = "  ";
+/** Read the value at a dot-path from a parsed object (undefined if absent). */
+export function getAtPath(root, dotPath) {
+    let node = root;
+    for (const seg of dotPath.split(".")) {
+        if (node == null || typeof node !== "object")
+            return undefined;
+        node = node[seg];
+    }
+    return node;
+}
+/** Coerce a raw CLI string to the type of an existing sample value (num/bool/string). */
+export function coerceLike(raw, sample) {
+    if (typeof sample === "number") {
+        const n = Number(raw);
+        if (!Number.isFinite(n))
+            throw new Error(`"${raw}" is not a number (the current value is numeric)`);
+        return n;
+    }
+    if (typeof sample === "boolean") {
+        if (raw === "true")
+            return true;
+        if (raw === "false")
+            return false;
+        throw new Error(`"${raw}" is not a boolean (use true/false)`);
+    }
+    return raw; // string (or unknown sample) → verbatim
+}
+/** Serialize a scalar for YAML: quote a string only when needed; numbers/bools bare. */
+function scalarToYaml(v) {
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    const s = String(v);
+    // Quote when the string could be misread as another YAML type or has special chars.
+    if (s === "" || /^[\s]|[\s]$|[:#{}[\],&*!|>'"%@`]|^(true|false|null|~|-?\d)/.test(s)) {
+        return JSON.stringify(s); // JSON string is valid YAML double-quoted
+    }
+    return s;
+}
+/** The line index of `indent + key:` within [from, to); -1 if absent. */
+function findKeyLine(lines, key, indent, from, to) {
+    const prefix = indent + key + ":";
+    for (let i = from; i < to; i++)
+        if (lines[i].startsWith(prefix))
+            return i;
+    return -1;
+}
+/** End (exclusive) of the block owned by the key at `start` (indent-based). */
+function blockEnd(lines, start, indent, to) {
+    let end = start + 1;
+    while (end < to) {
+        const l = lines[end];
+        if (l.trim() !== "" && !l.startsWith(indent + " ") && !l.startsWith(indent + "\t"))
+            break;
+        end++;
+    }
+    return end;
+}
+/** Split a `key: value  # comment` line into value + trailing comment (comment kept verbatim). */
+function splitValueComment(afterColon) {
+    // A '#' starts a comment only when preceded by whitespace (or at col 0 of the value).
+    const m = afterColon.match(/^(.*?)(\s+#.*)?$/s);
+    return { value: (m?.[1] ?? afterColon).trimEnd(), comment: m?.[2] ?? "" };
+}
+/**
+ * Set a scalar at `dotPath` in the raw frontmatter YAML, preserving comments.
+ * `parsed` is the same YAML already parsed (for the current value + type). Throws
+ * with a clear message when the path is missing or is not a scalar leaf.
+ */
+export function setScalarAtPath(frontmatterYaml, parsed, dotPath, newValue) {
+    const previous = getAtPath(parsed, dotPath);
+    if (previous === undefined)
+        throw new Error(`path not found: ${dotPath}`);
+    if (previous !== null && typeof previous === "object") {
+        throw new Error(`${dotPath} is a ${Array.isArray(previous) ? "list" : "block"}, not a scalar — edit it in the file directly`);
+    }
+    const lines = frontmatterYaml.split("\n");
+    const segs = dotPath.split(".");
+    let from = 0;
+    let to = lines.length;
+    let indent = "";
+    // Descend the block structure for every segment but the last.
+    for (let s = 0; s < segs.length - 1; s++) {
+        const idx = findKeyLine(lines, segs[s], indent, from, to);
+        if (idx === -1)
+            throw new Error(`path not found: ${dotPath} (missing "${segs[s]}")`);
+        // Flow-map fallback: the value is inline `{ … }` and the rest of the path is inside it.
+        const afterColon = lines[idx].slice((indent + segs[s] + ":").length);
+        if (afterColon.trim().startsWith("{")) {
+            return editFlowMapLeaf(lines, idx, indent + segs[s] + ":", segs.slice(s + 1), newValue, previous);
+        }
+        from = idx + 1;
+        to = blockEnd(lines, idx, indent, to);
+        indent += INDENT;
+    }
+    // The leaf: a block scalar `indent + key: value`.
+    const leaf = segs[segs.length - 1];
+    const li = findKeyLine(lines, leaf, indent, from, to);
+    if (li === -1)
+        throw new Error(`path not found: ${dotPath} (missing "${leaf}")`);
+    const afterColon = lines[li].slice((indent + leaf + ":").length);
+    if (afterColon.trim() === "" || afterColon.trim().startsWith("{") || afterColon.trim().startsWith("[")) {
+        throw new Error(`${dotPath} is not a block scalar — edit it in the file directly`);
+    }
+    const { comment } = splitValueComment(afterColon);
+    lines[li] = `${indent}${leaf}: ${scalarToYaml(newValue)}${comment}`;
+    return { text: lines.join("\n"), previous };
+}
+/** Replace `key: value` for one key inside a single-line flow map `parent: { … }`. */
+function editFlowMapLeaf(lines, lineIdx, keyPrefix, remaining, newValue, previous) {
+    if (remaining.length !== 1) {
+        throw new Error(`nested flow-map path too deep — edit "${keyPrefix.replace(/:$/, "")}" in the file directly`);
+    }
+    const nested = remaining[0];
+    const line = lines[lineIdx];
+    const re = new RegExp(`(\\{[^}]*?\\b${nested}\\s*:\\s*)([^,}]*?)(\\s*[,}])`);
+    if (!re.test(line))
+        throw new Error(`key "${nested}" not found in the flow map`);
+    lines[lineIdx] = line.replace(re, (_m, pre, _old, post) => `${pre}${scalarToYaml(newValue)}${post}`);
+    return { text: lines.join("\n"), previous };
+}

package/dist/state-engine.d.ts

@@ -0,0 +1,40 @@
+/**
+ * State engine — the canonical, programmatic mutation primitive.
+ *
+ * This is the same clamp + audit logic the CLI's `state mutate` command applies,
+ * lifted to a pure function so the Living Loop (and the managed runtime) can call
+ * it directly. Mirrors the runtime tool `adjust_persona_state(field, delta, reason)`.
+ *
+ * Guarantees (spec-faithful, non-negotiable):
+ *  - every delta is clamped to the declared envelope [min, max];
+ *  - every mutation appends an immutable, timestamped entry to mutation_log;
+ *  - clamping is recorded (`clamped: true`) for full auditability.
+ */
+import type { Envelope } from "./envelopes.js";
+import type { MutationLogEntry, StateFile } from "./persona.js";
+export interface MutationRequest {
+    field: string;
+    delta: number;
+    reason: string;
+    actor?: MutationLogEntry["actor"];
+    toolCallId?: string;
+    /** Set by the governance gate when a mutation is refused. */
+    governanceBlocked?: boolean;
+    /** v0.8: machine/instance origin (cross-OS reconciliation). */
+    originNode?: string;
+    /** v0.8: runtime session id. */
+    sessionId?: string;
+}
+export interface MutationResult {
+    entry: MutationLogEntry;
+    from: number;
+    to: number;
+    clamped: boolean;
+    blocked: boolean;
+}
+/**
+ * Apply one mutation to `state` in place. Returns the audit result.
+ * If `req.governanceBlocked` is true the value is NOT changed; only an audit
+ * entry recording the blocked attempt is appended.
+ */
+export declare function applyMutation(state: StateFile, envelopes: Record<string, Envelope>, req: MutationRequest): MutationResult;

package/dist/state-engine.js

@@ -0,0 +1,50 @@
+/**
+ * State engine — the canonical, programmatic mutation primitive.
+ *
+ * This is the same clamp + audit logic the CLI's `state mutate` command applies,
+ * lifted to a pure function so the Living Loop (and the managed runtime) can call
+ * it directly. Mirrors the runtime tool `adjust_persona_state(field, delta, reason)`.
+ *
+ * Guarantees (spec-faithful, non-negotiable):
+ *  - every delta is clamped to the declared envelope [min, max];
+ *  - every mutation appends an immutable, timestamped entry to mutation_log;
+ *  - clamping is recorded (`clamped: true`) for full auditability.
+ */
+/**
+ * Apply one mutation to `state` in place. Returns the audit result.
+ * If `req.governanceBlocked` is true the value is NOT changed; only an audit
+ * entry recording the blocked attempt is appended.
+ */
+export function applyMutation(state, envelopes, req) {
+    const envelope = envelopes[req.field];
+    if (!envelope) {
+        throw new Error(`No envelope declared for '${req.field}'. Mutable fields: ${Object.keys(envelopes).join(", ")}`);
+    }
+    if (!Number.isFinite(req.delta)) {
+        throw new Error(`Invalid delta for '${req.field}': ${req.delta}`);
+    }
+    const current = state.values[req.field] ?? envelope.mean;
+    const blocked = req.governanceBlocked === true;
+    const requested = current + req.delta;
+    const clampedTo = Math.max(envelope.min, Math.min(envelope.max, requested));
+    const next = blocked ? current : clampedTo;
+    const clamped = !blocked && clampedTo !== requested;
+    const entry = {
+        ts: new Date().toISOString(),
+        field: req.field,
+        from: current,
+        to: next,
+        delta_requested: req.delta,
+        clamped,
+        reason: req.reason,
+        actor: req.actor ?? "human-operator",
+        tool_call_id: req.toolCallId,
+        governance_blocked: blocked,
+        origin_node: req.originNode,
+        session_id: req.sessionId,
+    };
+    state.values[req.field] = next;
+    state.mutation_log = state.mutation_log ?? [];
+    state.mutation_log.push(entry);
+    return { entry, from: current, to: next, clamped, blocked };
+}

package/dist/state-rebuild.d.ts

@@ -0,0 +1,48 @@
+/**
+ * F3.4 — state.json as a REBUILDABLE CHECKPOINT of the mutation_log.
+ *
+ * The mutation_log is the append-only source of truth: every value change is an
+ * audited entry recording its resulting value (`to`). So `state.values` is a
+ * derived checkpoint — reconstructable by replaying the log from the envelope
+ * means. This makes state.json recoverable (a corrupt/torn values block can be
+ * rebuilt from the log) and tamper-evident (a hand-edited value that the log
+ * does not justify shows up as drift).
+ *
+ * Replay is exact and deterministic: each entry already stores the post-clamp,
+ * post-governance result, so folding the log — `values[field] = entry.to` —
+ * reproduces the canonical values for every MUTATED field. A governance-blocked
+ * entry has `to === from`, so it correctly leaves the value unchanged.
+ *
+ * SAFETY: the log is authoritative ONLY over fields it has touched. A field with
+ * no log history is preserved from the stored value as-is (falling back to the
+ * envelope mean only when it is absent from both) — a `rebuild --write` never
+ * resets an un-mutated field, so it is safe even when state keys and log field
+ * keys are spelled inconsistently (the pre-v1.0 short-key vs full dot-path gap).
+ */
+import type { Envelope } from "./envelopes.js";
+import type { MutationLogEntry, StateFile } from "./persona.js";
+export interface RebuildDrift {
+    field: string;
+    stored: number | undefined;
+    rebuilt: number;
+}
+export interface RebuildResult {
+    /** The values reconstructed purely from envelope means + the mutation_log. */
+    values: Record<string, number>;
+    /** Fields where the STORED value disagrees with the rebuilt one (tamper/corruption). */
+    drift: RebuildDrift[];
+}
+/**
+ * Reconstruct `values` from envelope means + the mutation_log, and report any
+ * field whose stored value disagrees with the replay.
+ */
+export declare function rebuildStateValues(envelopes: Record<string, Envelope>, mutationLog: MutationLogEntry[], storedValues?: Record<string, number>): RebuildResult;
+/**
+ * Return a copy of `state` with `values` rebuilt from its mutation_log (+ the
+ * envelope means). The mutation_log itself is preserved verbatim — this is a
+ * checkpoint refresh, never a history rewrite.
+ */
+export declare function rebuildState(state: StateFile, envelopes: Record<string, Envelope>): {
+    state: StateFile;
+    drift: RebuildDrift[];
+};

package/dist/state-rebuild.js

@@ -0,0 +1,60 @@
+/**
+ * F3.4 — state.json as a REBUILDABLE CHECKPOINT of the mutation_log.
+ *
+ * The mutation_log is the append-only source of truth: every value change is an
+ * audited entry recording its resulting value (`to`). So `state.values` is a
+ * derived checkpoint — reconstructable by replaying the log from the envelope
+ * means. This makes state.json recoverable (a corrupt/torn values block can be
+ * rebuilt from the log) and tamper-evident (a hand-edited value that the log
+ * does not justify shows up as drift).
+ *
+ * Replay is exact and deterministic: each entry already stores the post-clamp,
+ * post-governance result, so folding the log — `values[field] = entry.to` —
+ * reproduces the canonical values for every MUTATED field. A governance-blocked
+ * entry has `to === from`, so it correctly leaves the value unchanged.
+ *
+ * SAFETY: the log is authoritative ONLY over fields it has touched. A field with
+ * no log history is preserved from the stored value as-is (falling back to the
+ * envelope mean only when it is absent from both) — a `rebuild --write` never
+ * resets an un-mutated field, so it is safe even when state keys and log field
+ * keys are spelled inconsistently (the pre-v1.0 short-key vs full dot-path gap).
+ */
+/**
+ * Reconstruct `values` from envelope means + the mutation_log, and report any
+ * field whose stored value disagrees with the replay.
+ */
+export function rebuildStateValues(envelopes, mutationLog, storedValues = {}) {
+    // 1. preserve the stored values (un-mutated fields are never reset).
+    const values = { ...storedValues };
+    // 2. seed declared-but-absent envelope fields from their mean.
+    for (const [field, env] of Object.entries(envelopes)) {
+        if (values[field] === undefined)
+            values[field] = env.mean;
+    }
+    // 3. replay the log; each entry's `to` is authoritative for the fields it touched.
+    const mutated = new Set();
+    for (const entry of mutationLog) {
+        values[entry.field] = entry.to;
+        mutated.add(entry.field);
+    }
+    // 4. drift = a MUTATED field whose stored value disagrees with the replay
+    //    (the log is the source of truth; the stored value was tampered/torn).
+    const drift = [];
+    for (const field of mutated) {
+        const rebuilt = values[field];
+        const stored = storedValues[field];
+        if (stored === undefined || Math.abs(stored - rebuilt) > 1e-9) {
+            drift.push({ field, stored, rebuilt });
+        }
+    }
+    return { values, drift };
+}
+/**
+ * Return a copy of `state` with `values` rebuilt from its mutation_log (+ the
+ * envelope means). The mutation_log itself is preserved verbatim — this is a
+ * checkpoint refresh, never a history rewrite.
+ */
+export function rebuildState(state, envelopes) {
+    const { values, drift } = rebuildStateValues(envelopes, state.mutation_log ?? [], state.values ?? {});
+    return { state: { ...state, values }, drift };
+}

package/dist/sync.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Cross-OS state reconciliation (F7 — plan/08-persona-model).
+ *
+ * The portable user-clone persona can live on Windows, Linux and macOS at once,
+ * versioned via git. Identity (personaxis.md) is immutable and shared; only
+ * state.json (envelope values + mutation_log) and memory diverge per machine.
+ * This module merges two states WITHOUT clobbering either:
+ *   - mutation_log: union, de-duplicated, time-ordered (the full audit survives);
+ *   - values: last-writer-wins PER FIELD by the latest mutation timestamp across
+ *     both logs, clamped to the envelope; ties/absent history are reported as
+ *     conflicts rather than silently overwritten;
+ *   - a merge marker is appended so the reconciliation itself is auditable.
+ *
+ * Deterministic, governed, reversible — never a blind overwrite.
+ */
+import type { Envelope } from "./envelopes.js";
+import type { StateFile } from "./persona.js";
+export interface MergeConflict {
+    field: string;
+    a: number;
+    b: number;
+    chosen: number;
+    reason: string;
+}
+export interface MergeResult {
+    merged: StateFile;
+    conflicts: MergeConflict[];
+}
+/**
+ * Merge state `b` into `a` (a = local/base). Returns the merged state + conflicts.
+ */
+export declare function mergeState(a: StateFile, b: StateFile, envelopes?: Record<string, Envelope>): MergeResult;

package/dist/sync.js

@@ -0,0 +1,95 @@
+/**
+ * Cross-OS state reconciliation (F7 — plan/08-persona-model).
+ *
+ * The portable user-clone persona can live on Windows, Linux and macOS at once,
+ * versioned via git. Identity (personaxis.md) is immutable and shared; only
+ * state.json (envelope values + mutation_log) and memory diverge per machine.
+ * This module merges two states WITHOUT clobbering either:
+ *   - mutation_log: union, de-duplicated, time-ordered (the full audit survives);
+ *   - values: last-writer-wins PER FIELD by the latest mutation timestamp across
+ *     both logs, clamped to the envelope; ties/absent history are reported as
+ *     conflicts rather than silently overwritten;
+ *   - a merge marker is appended so the reconciliation itself is auditable.
+ *
+ * Deterministic, governed, reversible — never a blind overwrite.
+ */
+function clamp(v, e) {
+    if (!e)
+        return v;
+    return Math.max(e.min, Math.min(e.max, v));
+}
+function dedupeLog(entries) {
+    const seen = new Set();
+    const out = [];
+    for (const e of entries) {
+        // v0.8: origin_node distinguishes same-ts mutations made on different machines,
+        // so a genuine concurrent edit is not collapsed during reconciliation.
+        const key = `${e.ts}|${e.field}|${e.to}|${e.actor}|${e.origin_node ?? ""}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(e);
+    }
+    return out.sort((x, y) => x.ts.localeCompare(y.ts));
+}
+function latestForField(log, field) {
+    let best;
+    for (const e of log) {
+        if (e.field === field && (!best || e.ts > best.ts))
+            best = e;
+    }
+    return best;
+}
+/**
+ * Merge state `b` into `a` (a = local/base). Returns the merged state + conflicts.
+ */
+export function mergeState(a, b, envelopes = {}) {
+    const mergedLog = dedupeLog([...(a.mutation_log ?? []), ...(b.mutation_log ?? [])]);
+    const conflicts = [];
+    const fields = new Set([...Object.keys(a.values), ...Object.keys(b.values)]);
+    const values = {};
+    for (const f of fields) {
+        const av = a.values[f];
+        const bv = b.values[f];
+        const latest = latestForField(mergedLog, f);
+        let chosen;
+        let reason;
+        if (latest) {
+            chosen = latest.to;
+            reason = `latest mutation @ ${latest.ts} (${latest.actor})`;
+        }
+        else if (av === bv || bv === undefined) {
+            chosen = av ?? bv;
+            reason = "agreement / base-only";
+        }
+        else if (av === undefined) {
+            chosen = bv;
+            reason = "incoming-only";
+        }
+        else {
+            chosen = av;
+            reason = "no history, kept base (conflict)";
+            conflicts.push({ field: f, a: av, b: bv, chosen, reason });
+        }
+        values[f] = clamp(chosen, envelopes[f]);
+        if (latest && av !== undefined && bv !== undefined && av !== bv) {
+            conflicts.push({ field: f, a: av, b: bv, chosen: values[f], reason });
+        }
+    }
+    const marker = {
+        ts: new Date().toISOString(),
+        field: "__merge__",
+        from: 0,
+        to: 0,
+        delta_requested: 0,
+        clamped: false,
+        reason: `cross-machine reconciliation (${conflicts.length} conflict(s))`,
+        actor: "runtime-context",
+    };
+    const merged = {
+        ...a,
+        values,
+        mutation_log: [...mergedLog, marker],
+    };
+    return { merged, conflicts };
+}

package/dist/tool-calling.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 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 type { ToolSpec } from "./tools/registry.js";
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string;
+    /** For assistant turns that issued tool calls (echoed back to the model). */
+    tool_calls?: RawToolCall[];
+    /** For role:"tool" results. */
+    tool_call_id?: string;
+    name?: string;
+}
+interface RawToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    args: Record<string, unknown>;
+}
+export interface TokenUsage {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+}
+export interface ToolCallResponse {
+    /** Assistant free text accompanying the call (may be empty). */
+    text: string;
+    toolCalls: ToolCall[];
+    usedFallback: boolean;
+    /** Token accounting from the provider (for budget enforcement), when reported. */
+    usage?: TokenUsage;
+}
+export interface ToolCallConfig {
+    endpoint: string;
+    model: string;
+    apiKey?: string;
+    maxTokens?: number;
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Request the next action. `preferFallback` lets the caller skip the native
+ * attempt once it has learned the endpoint doesn't support `tools`.
+ */
+export declare function requestToolCall(cfg: ToolCallConfig, messages: ChatMessage[], tools: ToolSpec[], preferFallback?: boolean): Promise<ToolCallResponse>;
+export {};