@nanhara/hara 0.121.0 → 0.122.0

package/dist/org/projects.js

@@ -0,0 +1,347 @@
+// Global agent index — ~/.hara/projects.json registers canonical project homes. The registry is private,
+// atomically replaced, and guarded across processes because gateway/desktop/CLI may update it concurrently.
+import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { isAbsolute, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { randomUUID } from "node:crypto";
+import { loadRoles, loadGlobalRoles } from "./roles.js";
+const PROJECT_NAME = /^[a-z0-9](?:[a-z0-9._-]{0,62}[a-z0-9])?$/;
+const sleepCell = new Int32Array(new SharedArrayBuffer(4));
+const LOCK_ATTEMPTS = 500;
+const LOCK_WAIT_MS = 10;
+function haraDir() {
+    const dir = join(homedir(), ".hara");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        /* best effort on non-POSIX filesystems */
+    }
+    return dir;
+}
+const projectsFile = () => join(haraDir(), "projects.json");
+/** Handles are case-insensitive and form the left side of `project:agent`; canonical storage is lowercase. */
+export function canonicalProjectName(value) {
+    if (typeof value !== "string")
+        return null;
+    const name = value.trim().toLowerCase();
+    return PROJECT_NAME.test(name) ? name : null;
+}
+/** Existing paths resolve symlinks so one project cannot be registered twice through aliases. */
+export function canonicalProjectPath(value, requireDirectory = false) {
+    if (typeof value !== "string" || !value.trim() || !isAbsolute(value))
+        return null;
+    const absolute = resolve(value);
+    try {
+        if (requireDirectory && !statSync(absolute).isDirectory())
+            return null;
+        return realpathSync.native(absolute);
+    }
+    catch {
+        return requireDirectory ? null : absolute;
+    }
+}
+function readLock(path) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        return Number.isInteger(parsed?.pid) && parsed.pid > 0 && typeof parsed?.token === "string" && parsed.token
+            ? { pid: parsed.pid, token: parsed.token }
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error?.code === "EPERM";
+    }
+}
+function writeExclusive(path, record) {
+    let fd;
+    try {
+        fd = openSync(path, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify(record), "utf8");
+        fsyncSync(fd);
+    }
+    catch (error) {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+                fd = undefined;
+            }
+            finally {
+                rmSync(path, { force: true });
+            }
+        }
+        throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function withProjectsLock(fn) {
+    const file = projectsFile();
+    const lock = `${file}.lock`;
+    const reclaim = `${lock}.reclaim`;
+    let claim;
+    for (let attempt = 0; attempt < LOCK_ATTEMPTS; attempt++) {
+        if (existsSync(reclaim)) {
+            const stale = readLock(reclaim);
+            if (stale && !pidAlive(stale.pid)) {
+                const current = readLock(reclaim);
+                if (current?.pid === stale.pid && current.token === stale.token && !pidAlive(current.pid)) {
+                    rmSync(reclaim, { force: true });
+                    continue;
+                }
+            }
+            Atomics.wait(sleepCell, 0, 0, LOCK_WAIT_MS);
+            continue;
+        }
+        const candidate = { pid: process.pid, token: randomUUID() };
+        try {
+            writeExclusive(lock, candidate);
+            claim = candidate;
+            break;
+        }
+        catch (error) {
+            if (error?.code !== "EEXIST")
+                throw error;
+        }
+        const held = readLock(lock);
+        if (held && !pidAlive(held.pid)) {
+            const guard = { pid: process.pid, token: randomUUID() };
+            try {
+                writeExclusive(reclaim, guard);
+                const current = readLock(lock);
+                if (current?.pid === held.pid && current.token === held.token && !pidAlive(current.pid))
+                    rmSync(lock);
+            }
+            catch {
+                // Another writer is reclaiming, or the evidence is malformed. Never fail open.
+            }
+            finally {
+                const currentGuard = readLock(reclaim);
+                if (currentGuard?.pid === process.pid && currentGuard.token === guard.token)
+                    rmSync(reclaim, { force: true });
+            }
+        }
+        Atomics.wait(sleepCell, 0, 0, LOCK_WAIT_MS);
+    }
+    if (!claim)
+        throw new Error("projects registry is busy; retry the operation");
+    try {
+        return fn();
+    }
+    finally {
+        const current = readLock(lock);
+        if (current?.pid === process.pid && current.token === claim.token)
+            rmSync(lock, { force: true });
+    }
+}
+function parseProjects(raw, strict) {
+    const parsed = JSON.parse(raw);
+    const source = Array.isArray(parsed) ? parsed : parsed?.projects;
+    if (!Array.isArray(source))
+        throw new Error("projects registry must contain a projects array");
+    const out = [];
+    const names = new Set();
+    const paths = new Set();
+    for (const value of source) {
+        const name = canonicalProjectName(value?.name);
+        const path = canonicalProjectPath(value?.path);
+        if (!name || !path || names.has(name) || paths.has(path)) {
+            if (strict)
+                throw new Error("projects registry contains invalid or duplicate entries");
+            continue;
+        }
+        names.add(name);
+        paths.add(path);
+        out.push({ name, path });
+    }
+    return out;
+}
+function loadProjectsUnlocked(strict) {
+    const file = projectsFile();
+    if (!existsSync(file))
+        return [];
+    try {
+        return parseProjects(readFileSync(file, "utf8"), strict);
+    }
+    catch (error) {
+        if (strict)
+            throw error;
+        return [];
+    }
+}
+export function loadProjects() {
+    return loadProjectsUnlocked(false);
+}
+function atomicSave(list) {
+    const file = projectsFile();
+    const tmp = `${file}.${process.pid}.${randomUUID()}.tmp`;
+    let fd;
+    try {
+        fd = openSync(tmp, "wx", 0o600);
+        writeFileSync(fd, JSON.stringify({ projects: list }, null, 2) + "\n", "utf8");
+        fsyncSync(fd);
+        closeSync(fd);
+        fd = undefined;
+        renameSync(tmp, file);
+        try {
+            chmodSync(file, 0o600);
+        }
+        catch {
+            /* best effort on non-POSIX filesystems */
+        }
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+        rmSync(tmp, { force: true });
+    }
+}
+function normalizeProjectList(list) {
+    if (!Array.isArray(list))
+        throw new Error("projects must be an array");
+    const normalized = list.map((value) => {
+        const name = canonicalProjectName(value?.name);
+        const path = canonicalProjectPath(value?.path);
+        if (!name || !path)
+            throw new Error("project entries require a valid name and absolute path");
+        return { name, path };
+    });
+    if (new Set(normalized.map((p) => p.name)).size !== normalized.length || new Set(normalized.map((p) => p.path)).size !== normalized.length) {
+        throw new Error("project names and paths must be unique");
+    }
+    return normalized;
+}
+export function saveProjects(list) {
+    withProjectsLock(() => atomicSave(normalizeProjectList(list)));
+}
+export function addProject(nameInput, pathInput) {
+    const name = canonicalProjectName(nameInput);
+    if (!name)
+        return "invalid project name: use 1-64 lowercase letters, numbers, '.', '_' or '-'";
+    const path = canonicalProjectPath(pathInput, true);
+    if (!path)
+        return `path does not exist or is not a directory: ${pathInput}`;
+    try {
+        return withProjectsLock(() => {
+            const list = loadProjectsUnlocked(true);
+            const alias = list.find((p) => p.path === path && p.name !== name);
+            if (alias)
+                return `path is already registered as '${alias.name}': ${path}`;
+            const next = list.filter((p) => p.name !== name);
+            next.push({ name, path });
+            atomicSave(next);
+            return null;
+        });
+    }
+    catch (error) {
+        return `projects registry: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+export function removeProject(nameInput) {
+    const name = canonicalProjectName(nameInput);
+    if (!name)
+        return false;
+    return withProjectsLock(() => {
+        const list = loadProjectsUnlocked(true);
+        const next = list.filter((p) => p.name !== name);
+        if (next.length === list.length)
+            return false;
+        atomicSave(next);
+        return true;
+    });
+}
+function sameList(a, b) {
+    if (a === undefined || b === undefined)
+        return a === b;
+    if (a.length !== b.length)
+        return false;
+    const left = [...a].sort();
+    const right = [...b].sort();
+    return left.every((value, i) => value === right[i]);
+}
+/** Project roles with the same prompt can still intentionally override model/routing/tool policy. */
+function sameRoleDefinition(a, b) {
+    return (a.id === b.id &&
+        a.description === b.description &&
+        a.system === b.system &&
+        a.model === b.model &&
+        sameList(a.owns, b.owns) &&
+        sameList(a.rejects, b.rejects) &&
+        sameList(a.allowTools, b.allowTools) &&
+        sameList(a.denyTools, b.denyTools) &&
+        a.readOnly === b.readOnly);
+}
+/** Build the global index: inherited globals are listed once; any project override gets its qualified home. */
+export function buildAgentsIndex() {
+    const globals = loadGlobalRoles();
+    const globalById = new Map(globals.map((role) => [role.id, role]));
+    const out = globals.map((role) => ({ name: role.id, description: role.description, home: "" }));
+    for (const project of loadProjects()) {
+        let roles = [];
+        try {
+            roles = loadRoles(project.path);
+        }
+        catch {
+            continue;
+        }
+        for (const role of roles) {
+            const global = globalById.get(role.id);
+            if (global && sameRoleDefinition(global, role))
+                continue;
+            out.push({ name: role.id, description: role.description, home: project.path, project: project.name });
+        }
+    }
+    return out;
+}
+/** Resolve `global:agent`, `project:agent`, or a bare name.
+ *
+ * Bare names normally prefer the global definition, then a unique project match. Callers that already
+ * have a working directory (the chat gateway, for example) may pass it as `preferredHome`; a matching
+ * project override then wins before the global fallback. This makes `/agent reviewer` do the local thing
+ * while keeping registry-wide, context-free lookups deterministic. */
+export function resolveAgent(refInput, preferredHome) {
+    if (typeof refInput !== "string")
+        return null;
+    const ref = refInput.trim();
+    const index = buildAgentsIndex();
+    const separator = ref.indexOf(":");
+    if (separator > 0) {
+        const namespace = ref.slice(0, separator).trim().toLowerCase();
+        const name = ref.slice(separator + 1).trim();
+        if (namespace === "global") {
+            if (!name || name.includes(":"))
+                return null;
+            return index.find((entry) => !entry.project && entry.name === name) ?? null;
+        }
+        const project = canonicalProjectName(namespace);
+        if (!project || !name || name.includes(":"))
+            return null;
+        return index.find((entry) => entry.project === project && entry.name === name) ?? null;
+    }
+    const hits = index.filter((entry) => entry.name === ref);
+    if (!hits.length)
+        return null;
+    if (hits.length === 1)
+        return hits[0];
+    if (preferredHome) {
+        const preferred = canonicalProjectPath(preferredHome);
+        const local = preferred ? hits.find((entry) => !!entry.project && entry.home === preferred) : undefined;
+        if (local)
+            return local;
+    }
+    const global = hits.find((entry) => !entry.project);
+    if (global)
+        return global;
+    return { ambiguous: hits };
+}

package/dist/org/roles.js

@@ -1,5 +1,5 @@
 // Org roles — markdown agent definitions in <project>/.hara/roles/*.md.
-// Frontmatter: name, description, owns[], rejects[], model?, allowTools[], denyTools[]. Body = persona/system.
+// Frontmatter: name, description, owns[], rejects[], model?, allowTools[], denyTools[], readOnly?. Body = persona/system.
 import { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -83,17 +83,38 @@ function parseFrontmatter(text) {
  *  parallel), with a role allowed to narrow further but never to grant write/exec. `isReadonly` is the
  *  read-kind predicate. This is the guard that keeps the `agent` tool from bypassing the approval gate. */
 export function subagentToolFilter(role, isReadonly) {
-    const roleFilter = role?.allowTools
-        ? (n) => role.allowTools.includes(n)
-        : role?.denyTools
-            ? (n) => !role.denyTools.includes(n)
-            : null;
+    // Treat allow + deny as an intersection when both are present. A deny must never disappear merely
+    // because an allow-list was also declared (mixed policies are common in generated role bundles).
+    const roleFilter = role?.allowTools || role?.denyTools
+        ? (n) => (!role.allowTools || role.allowTools.includes(n)) && (!role.denyTools || !role.denyTools.includes(n))
+        : null;
     return (n) => isReadonly(n) && (roleFilter ? roleFilter(n) : true);
 }
+/** Apply a role's declared tool policy to a normal (approval-gated) run. Undefined means unrestricted. */
+export function roleToolFilter(role) {
+    if (!role)
+        return undefined;
+    const declared = (name) => (!role.allowTools || role.allowTools.includes(name)) && (!role.denyTools || !role.denyTools.includes(name));
+    if (role.readOnly) {
+        // Raw bash is intentionally absent: even commands that look read-only can hide redirection, command
+        // substitution, hooks, or an executable with side effects. Reviewers get dedicated read/search tools.
+        const safe = new Set(["read_file", "grep", "glob", "ls", "web_fetch", "web_search", "codebase_search", "todo_write"]);
+        return (name) => safe.has(name) && declared(name);
+    }
+    return role.allowTools || role.denyTools ? declared : undefined;
+}
 export function loadRoles(cwd) {
-    const byId = new Map();
     // lowest→highest precedence: plugins < org(B-end push) < global < .claude/agents < .hara/roles (project wins)
-    for (const dir of [...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]) {
+    return [...rolesFromDirs([...pluginRoleDirs(), orgRolesDir(), globalRolesDir(), claudeAgentsDir(cwd), rolesDir(cwd)]).values()];
+}
+/** The project-independent layers only (plugins + org-pushed + ~/.hara/roles) — what the global agent
+ *  index lists as "runs anywhere". Excludes cwd-derived layers by construction. */
+export function loadGlobalRoles() {
+    return [...rolesFromDirs([...pluginRoleDirs(), orgRolesDir(), globalRolesDir()]).values()];
+}
+function rolesFromDirs(dirs) {
+    const byId = new Map();
+    for (const dir of dirs) {
         if (!existsSync(dir))
             continue;
         for (const f of readdirSync(dir)) {
@@ -102,6 +123,9 @@ export function loadRoles(cwd) {
             try {
                 const { fm, body } = parseFrontmatter(readFileSync(join(dir, f), "utf8"));
                 const id = fm.name || f.replace(/\.md$/, "");
+                const explicitReadOnly = /^(true|false)$/i.test(String(fm.readOnly ?? ""))
+                    ? String(fm.readOnly).toLowerCase() === "true"
+                    : undefined;
                 byId.set(id, {
                     id,
                     description: fm.description || "",
@@ -112,6 +136,7 @@ export function loadRoles(cwd) {
                     model: fm.model && !/^(sonnet|opus|haiku|inherit)$/i.test(String(fm.model)) ? fm.model : undefined,
                     allowTools: Array.isArray(fm.allowTools) ? fm.allowTools : claudeTools(fm.tools),
                     denyTools: Array.isArray(fm.denyTools) ? fm.denyTools : undefined,
+                    readOnly: explicitReadOnly ?? (id.toLowerCase() === "reviewer" ? true : undefined),
                     system: body,
                 });
             }
@@ -120,7 +145,7 @@ export function loadRoles(cwd) {
             }
         }
     }
-    return [...byId.values()];
+    return byId;
 }
 export function hasRoles(cwd) {
     return loadRoles(cwd).length > 0;
@@ -140,10 +165,11 @@ End with a one-line summary of what changed.
 name: reviewer
 description: Reviews code for bugs, correctness, security, and style. Does not modify code.
 owns: [review, audit, check, correctness, security, vulnerability, lint, quality]
-allowTools: [read_file, bash]
+allowTools: [read_file, grep, glob, ls, codebase_search]
+readOnly: true
 ---
 You are the **reviewer**. Read the relevant code and report concrete issues (bug / correctness /
-security / style) with file:line and a suggested fix. Do NOT edit files — you have read-only tools.
+security / style) with file:line and a suggested fix. Do NOT edit files — your tool surface is enforced read-only.
 Be specific; skip nitpicks unless asked.
 `,
     "docs.md": `---
@@ -164,6 +190,7 @@ Each \`*.md\` here is a role-agent. Frontmatter:
 - \`rejects\` — keywords that exclude this role (REJECT)
 - \`model\` — optional model override
 - \`allowTools\` / \`denyTools\` — restrict the role's tools
+- \`readOnly\` — enforce read/search-only tools (defaults on for a role named \`reviewer\`)
 
 Run \`hara org "<task>"\` to dispatch a task to the owning role, or \`hara org --role <id> "<task>"\`.
 `,

package/dist/security/secrets.js

@@ -0,0 +1,150 @@
+/** Shared secret redaction for anything that may leave the live model context (session JSON, public
+ *  feedback, logs). Deliberately conservative: a false positive hides a value in a local transcript;
+ *  a false negative leaves a credential on disk. */
+const CREDENTIAL_NAME = String.raw `(?:[A-Za-z][A-Za-z0-9_.-]*(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*|(?:api[_-]?key|apikey|secret|token|password|passwd)[A-Za-z0-9_.-]*)`;
+const CREDENTIAL_FLAG = String.raw `--?(?:api[-_]?key|token|secret|password|passwd)`;
+const PATTERNS = [
+    {
+        label: "private-key",
+        re: /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+        replace: "<REDACTED:private-key>",
+    },
+    { label: "sk-key", re: /\bsk-[A-Za-z0-9_-]{8,}\b/g, replace: "sk-***" },
+    { label: "github-token", re: /\bgh[pousr]_[A-Za-z0-9]{20,}\b/g, replace: "gh*_***" },
+    { label: "gitlab-token", re: /\bglpat-[A-Za-z0-9_-]{20,}\b/g, replace: "glpat-***" },
+    { label: "slack-token", re: /\bxox[baprs]-[A-Za-z0-9-]{16,}\b/g, replace: "xox*-***" },
+    { label: "npm-token", re: /\bnpm_[A-Za-z0-9]{20,}\b/g, replace: "npm_***" },
+    { label: "google-api-key", re: /\bAIza[A-Za-z0-9_-]{20,}\b/g, replace: "AIza***" },
+    { label: "stripe-live-key", re: /\b(?:sk|rk)_live_[A-Za-z0-9]{12,}\b/g, replace: "stripe-live-***" },
+    { label: "aws-key", re: /\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, replace: "AWS-KEY-***" },
+    { label: "jwt", re: /\beyJ[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, replace: "JWT-***" },
+    {
+        label: "bearer-token",
+        re: /\bBearer\s+[A-Za-z0-9._~+/=-]{12,}/gi,
+        replace: "Bearer ***",
+    },
+    {
+        label: "url-credential",
+        re: /(\bhttps?:\/\/[^\s/:@]+:)([^\s/@]{3,})(@)/gi,
+        replace: (_match, prefix, _value, suffix) => `${prefix}***${suffix}`,
+    },
+    {
+        // Quoted credentials may legitimately contain whitespace. Handle them before the unquoted patterns so
+        // `PASSWORD="correct horse battery staple"` is redacted as one value rather than leaking its tail.
+        label: "environment-credential",
+        re: /(\b[A-Z][A-Z0-9_]*(?:_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD)\b\s*=\s*)(["'])([\s\S]*?)\2/g,
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        label: "credential-assignment",
+        re: new RegExp(`(\\b${CREDENTIAL_NAME}\\b["']?\\s*[:=]\\s*)(["'])([\\s\\S]*?)\\2`, "gi"),
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        label: "authorization",
+        re: /(\bAuthorization\s*[:=]\s*)(["'])([\s\S]*?)\2/gi,
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        label: "credential-flag",
+        re: new RegExp(`(${CREDENTIAL_FLAG}(?:\\s+|=))(["'])([\\s\\S]*?)\\2`, "gi"),
+        replace: (_match, prefix, quote) => `${prefix}${quote}***${quote}`,
+    },
+    {
+        // Generic all-caps environment variables such as OPENAI_KEY / SOME_SERVICE_PRIVATE_KEY. Keep this
+        // case-sensitive so ordinary prose/code identifiers ending in "key" are not over-redacted.
+        label: "environment-credential",
+        re: /(\b[A-Z][A-Z0-9_]*(?:_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD)\b\s*=\s*)(["']?)([^\s"',;}\]]{6,})(["']?)/g,
+        replace: (_match, prefix, open, _value, close) => `${prefix}${open}***${close}`,
+    },
+    {
+        // FEISHU_APP_SECRET=… · apiKey: "…" · "access_token": "…". The optional quote immediately
+        // after the key handles JSON without consuming the opening quote of the value.
+        label: "credential-assignment",
+        re: new RegExp(`(\\b${CREDENTIAL_NAME}\\b["']?\\s*[:=]\\s*)(?!["'])([^\\s"',;}\\]]{6,})`, "gi"),
+        replace: (_match, prefix) => `${prefix}***`,
+    },
+    {
+        label: "authorization",
+        re: /(\bAuthorization\s*[:=]\s*)(?!["']|Bearer\s+)([^\s"',;}\]]{6,})/gi,
+        replace: (_match, prefix) => `${prefix}***`,
+    },
+    {
+        label: "credential-flag",
+        re: new RegExp(`(${CREDENTIAL_FLAG}(?:\\s+|=))(?!["'])([^\\s"']{6,})`, "gi"),
+        replace: (_match, prefix) => `${prefix}***`,
+    },
+];
+export function redactSensitiveText(text) {
+    let out = text;
+    const redactions = [];
+    for (const pattern of PATTERNS) {
+        pattern.re.lastIndex = 0;
+        out = out.replace(pattern.re, (...args) => {
+            redactions.push(pattern.label);
+            return typeof pattern.replace === "string" ? pattern.replace : pattern.replace(...args);
+        });
+    }
+    return { text: out, redactions };
+}
+/** Structured tool/config data often carries an opaque value that has no recognizable token prefix. In that
+ *  case the FIELD name is the evidence (`apiKey`, `access_token`, `FEISHU_APP_SECRET`, …). Keep this narrow
+ *  enough not to erase ordinary fields such as `tokenCount` or `secretary`. */
+function sensitiveFieldName(key) {
+    if (/^[A-Z][A-Z0-9_]*(?:_KEY|_SECRET|_TOKEN|_PASSWORD|_PASSWD)$/.test(key))
+        return true;
+    const compact = key.replace(/[^a-z0-9]/gi, "").toLowerCase();
+    return (compact === "authorization" ||
+        compact.endsWith("apikey") ||
+        compact.endsWith("privatekey") ||
+        compact.endsWith("token") ||
+        compact.endsWith("secret") ||
+        compact.endsWith("password") ||
+        compact.endsWith("passwd"));
+}
+/** Deep-copy a JSON-shaped value while redacting every string. Session history contains secrets not only
+ *  in user text but also in assistant tool inputs and tool results, so a top-level content-only pass is
+ *  insufficient. The live value is never mutated. */
+export function redactSensitiveValue(value) {
+    const hits = [];
+    const seen = new WeakMap();
+    const walk = (v) => {
+        if (typeof v === "string") {
+            const r = redactSensitiveText(v);
+            hits.push(...r.redactions);
+            return r.text;
+        }
+        if (Array.isArray(v)) {
+            const prior = seen.get(v);
+            if (prior)
+                return prior;
+            const out = [];
+            seen.set(v, out);
+            for (const child of v)
+                out.push(walk(child));
+            return out;
+        }
+        if (v && typeof v === "object") {
+            const prior = seen.get(v);
+            if (prior)
+                return prior;
+            const out = {};
+            seen.set(v, out);
+            for (const [key, child] of Object.entries(v)) {
+                let copied;
+                if (typeof child === "string" && child && sensitiveFieldName(key)) {
+                    hits.push("credential-field");
+                    copied = "***";
+                }
+                else {
+                    copied = walk(child);
+                }
+                // defineProperty keeps an own `__proto__` data key from mutating the clone's prototype.
+                Object.defineProperty(out, key, { value: copied, enumerable: true, writable: true, configurable: true });
+            }
+            return out;
+        }
+        return v;
+    };
+    return { value: walk(value), redactions: hits };
+}