@chances-ai/engine 24.0.0

package/dist/session/index.js

@@ -0,0 +1,202 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { createId } from "@chances-ai/runtime";
+/** Persists sessions as JSON under <workspaceRoot>/.chances/sessions. */
+export class SessionStore {
+    dir;
+    constructor(workspaceRoot) {
+        this.dir = join(workspaceRoot, ".chances", "sessions");
+        mkdirSync(this.dir, { recursive: true });
+    }
+    save(state) {
+        writeFileSync(join(this.dir, `${state.id}.json`), JSON.stringify(state, null, 2));
+    }
+    load(id) {
+        const path = join(this.dir, `${id}.json`);
+        if (!existsSync(path))
+            return undefined;
+        try {
+            return JSON.parse(readFileSync(path, "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    list() {
+        return readdirSync(this.dir)
+            .filter((f) => f.endsWith(".json"))
+            .flatMap((f) => {
+            try {
+                return [JSON.parse(readFileSync(join(this.dir, f), "utf8"))];
+            }
+            catch {
+                return [];
+            }
+        })
+            .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    }
+}
+/**
+ * Owns the session lifecycle (state machine): create/resume, append turns,
+ * flatten to a provider message list, checkpoint and restore.
+ */
+export class SessionManager {
+    store;
+    state;
+    constructor(state, store) {
+        this.store = store;
+        this.state = state;
+    }
+    static create(title = "session", store) {
+        const now = new Date().toISOString();
+        return new SessionManager({ id: createId("ses"), title, createdAt: now, updatedAt: now, turns: [] }, store);
+    }
+    static resume(id, store) {
+        const state = store.load(id);
+        return state ? new SessionManager(state, store) : undefined;
+    }
+    /**
+     * (5.5) Creates a NEW session pre-seeded with a deep clone of `parent`'s
+     * completed turns — the seam behind the `task` tool's `context: "fork"` mode.
+     *
+     * Three invariants make this safe:
+     *  - **New id, no `SessionStore`.** The child is a distinct session that can
+     *    never `save()` over the parent's `<id>.json` on disk (mirrors
+     *    `create("subagent")`, which also omits the store). All mutation stays in
+     *    the child's own in-memory state.
+     *  - **Whole turns, never a mid-turn slice.** chances-cli persists an
+     *    assistant message carrying `tool-call` parts and its `tool` results in
+     *    one atomic turn (see `engine.ts` end-of-turn `appendTurn`), so copying at
+     *    turn granularity keeps every `tool-call` paired with its result — the
+     *    provider's no-orphan-`tool_use` invariant holds for free.
+     *  - **The session `model` field is NOT carried.** The forked child's model is
+     *    chosen by the caller (persona override or inherited parent selection),
+     *    not by the parent session's last `/model` choice. `snapshot()` deep-clones
+     *    the whole state; we keep only `turns`.
+     */
+    static forkFrom(parent, title = "subagent") {
+        const now = new Date().toISOString();
+        return new SessionManager({ id: createId("ses"), title, createdAt: now, updatedAt: now, turns: parent.snapshot().turns }, undefined);
+    }
+    get id() {
+        return this.state.id;
+    }
+    /** All messages across turns, ready to send to a provider. */
+    messages() {
+        return this.state.turns.flatMap((t) => t.messages);
+    }
+    appendTurn(messages) {
+        const turn = { turnId: createId("turn"), at: new Date().toISOString(), messages };
+        this.state.turns.push(turn);
+        this.state.updatedAt = turn.at;
+        this.store?.save(this.state);
+        return turn;
+    }
+    /** Records the user's current model choice so `/resume` can restore it.
+     * Persisted immediately; not gated behind the next `appendTurn`. */
+    setModel(model) {
+        this.state.model = model;
+        this.state.updatedAt = new Date().toISOString();
+        this.store?.save(this.state);
+    }
+    /** Returns the persisted model choice for this session, if any. */
+    modelChoice() {
+        return this.state.model ? { ...this.state.model } : undefined;
+    }
+    /**
+     * Empties this session's turn list. Used by `/clear` when the user wants a
+     * fresh conversation without losing the session metadata (id/title). The
+     * underlying file is rewritten so a `/resume` of this id will land on an
+     * empty conversation.
+     */
+    clearTurns() {
+        this.state.turns = [];
+        this.state.updatedAt = new Date().toISOString();
+        this.store?.save(this.state);
+    }
+    /**
+     * (3.5) Applies a pure transform to every turn in the prefix
+     * (all but the last `keepRecentTurns` turns). Used by the Stage 1
+     * pruner — the transform receives one turn's messages, returns
+     * the rewritten messages. The turn's `turnId` / `at` are
+     * unchanged so persistence keeps its identity; the synthetic
+     * `compact-*` turn (from `compactTurns`) is treated like any
+     * other turn for indexing purposes.
+     *
+     * `keepRecentTurns` is clamped to `[0, turns.length]`. When
+     * `keepRecentTurns >= turns.length`, this is a no-op (nothing to
+     * prune). When 0, every turn including the most recent is fed to
+     * the transform.
+     *
+     * Idempotent if the transform is idempotent (the pruner's marker
+     * replacement is — second pass sees the marker, fails the
+     * delta>0 check, leaves it alone).
+     */
+    pruneTurns(keepRecentTurns, transform) {
+        const total = this.state.turns.length;
+        const cutoff = Math.max(0, total - Math.max(0, keepRecentTurns));
+        if (cutoff === 0)
+            return;
+        let mutated = false;
+        for (let i = 0; i < cutoff; i++) {
+            const t = this.state.turns[i];
+            const newMessages = transform(t.messages);
+            if (newMessages !== t.messages) {
+                this.state.turns[i] = { ...t, messages: newMessages };
+                mutated = true;
+            }
+        }
+        if (mutated) {
+            this.state.updatedAt = new Date().toISOString();
+            this.store?.save(this.state);
+        }
+    }
+    /**
+     * Replaces all but the last `keepLastN` turns with a single synthetic
+     * "system context" turn carrying `summary` as a user-role message. Why
+     * user-role rather than system-role: providers vary in how they handle
+     * mid-conversation system messages, but every provider accepts a long-form
+     * user message as historical context. The synthetic turn's `turnId` is
+     * tagged `compact-*` so debuggers can spot it.
+     *
+     * `keepLastN` is clamped to `[0, turns.length]` — passing a larger N keeps
+     * everything (compaction is a no-op), passing 0 collapses the whole
+     * conversation into the summary. The summary itself must be non-empty;
+     * callers should bail before invoking this when the summarizer returned
+     * nothing.
+     */
+    compactTurns(summary, keepLastN) {
+        if (!summary)
+            throw new Error("compactTurns: summary must be a non-empty string");
+        if (keepLastN < 0)
+            throw new Error("compactTurns: keepLastN must be >= 0");
+        const total = this.state.turns.length;
+        if (keepLastN >= total)
+            return; // nothing to compact
+        const recent = this.state.turns.slice(total - keepLastN);
+        const synthetic = {
+            turnId: `compact-${createId("turn")}`,
+            at: new Date().toISOString(),
+            messages: [
+                {
+                    role: "user",
+                    content: [{ type: "text", text: `PREVIOUS_CONVERSATION_SUMMARY:\n${summary}` }],
+                },
+            ],
+        };
+        this.state.turns = [synthetic, ...recent];
+        this.state.updatedAt = synthetic.at;
+        this.store?.save(this.state);
+    }
+    checkpoint() {
+        return { turnIndex: this.state.turns.length, state: structuredClone(this.state) };
+    }
+    restore(checkpoint) {
+        this.state = structuredClone(checkpoint.state);
+        this.store?.save(this.state);
+    }
+    snapshot() {
+        return structuredClone(this.state);
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/session/index.js.map

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

package/dist/tools/approval.d.ts

@@ -0,0 +1,33 @@
+import type { ToolCategory } from "@chances-ai/runtime/config";
+import type { ApprovalMode, ToolTier } from "@chances-ai/runtime";
+/**
+ * (5.3) Pure tier logic backing the session approval modes. Lives in
+ * `@chances-ai/tools` (next to the gate, its only consumer) rather than in
+ * config/runtime so the tables sit beside the code that reads them; the bare
+ * `ApprovalMode`/`ToolTier` type unions live in `@chances-ai/runtime` to avoid
+ * a config↔runtime import cycle (codex 5.3 Round-1 MUST-FIX #3). See
+ * docs/5.3-design.md § 3 (D1/D2/D3).
+ */
+/**
+ * Each tool category's capability tier. `network-read` (web_fetch) and
+ * `integration` (MCP-bridged tools) are **exec**: the first is per-URL-sensitive
+ * egress (see `defaultPolicy` rationale in config/types.ts), the second can do
+ * anything the server implements. So `auto-edit` prompts both, and `plan`
+ * blocks both.
+ */
+export declare const CATEGORY_TIER: Record<ToolCategory, ToolTier>;
+/**
+ * True when `mode` blocks the entire `category` outright (plan's read-only
+ * floor). The single source of truth shared by `PermissionGate.evaluate()` AND
+ * the engine's pre-hook `blockByMode` check — so a `Tool.permission()` that
+ * returns `null` to bypass the gate (e.g. `pty.read`) can't sneak past plan
+ * mode (codex 5.3 Round-1 MUST-FIX #1).
+ */
+export declare function isBlockedByMode(category: ToolCategory, mode: ApprovalMode): boolean;
+/** True when `mode` auto-approves the entire `category` (yolo / auto-edit),
+ *  i.e. the interactive prompt is skipped and the call runs. */
+export declare function isAutoApprovedByMode(category: ToolCategory, mode: ApprovalMode): boolean;
+/** Human-readable reason for a mode-driven block, surfaced in the tool result
+ *  so the model (and user) sees why a call was refused. */
+export declare function modeBlockReason(mode: ApprovalMode): string;
+//# sourceMappingURL=approval.d.ts.map

package/dist/tools/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../../src/tools/approval.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAC/D,OAAO,KAAK,EAAE,YAAY,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAElE;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,YAAY,EAAE,QAAQ,CASxD,CAAC;AAmBF;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAEnF;AAED;gEACgE;AAChE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,YAAY,EAAE,IAAI,EAAE,YAAY,GAAG,OAAO,CAExF;AAED;2DAC2D;AAC3D,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAE1D"}

package/dist/tools/approval.js

@@ -0,0 +1,53 @@
+/**
+ * (5.3) Pure tier logic backing the session approval modes. Lives in
+ * `@chances-ai/tools` (next to the gate, its only consumer) rather than in
+ * config/runtime so the tables sit beside the code that reads them; the bare
+ * `ApprovalMode`/`ToolTier` type unions live in `@chances-ai/runtime` to avoid
+ * a config↔runtime import cycle (codex 5.3 Round-1 MUST-FIX #3). See
+ * docs/5.3-design.md § 3 (D1/D2/D3).
+ */
+/**
+ * Each tool category's capability tier. `network-read` (web_fetch) and
+ * `integration` (MCP-bridged tools) are **exec**: the first is per-URL-sensitive
+ * egress (see `defaultPolicy` rationale in config/types.ts), the second can do
+ * anything the server implements. So `auto-edit` prompts both, and `plan`
+ * blocks both.
+ */
+export const CATEGORY_TIER = {
+    "file-read": "read",
+    search: "read",
+    "memory-read": "read",
+    "file-write": "write",
+    "memory-write": "write",
+    shell: "exec",
+    integration: "exec",
+    "network-read": "exec",
+};
+const TIER_RANK = { read: 0, write: 1, exec: 2 };
+const MODE_PROFILE = {
+    default: { autoApproveMaxTier: -1, blockAboveTier: 2 }, // pure passthrough to policy
+    "auto-edit": { autoApproveMaxTier: 1, blockAboveTier: 2 }, // auto read+write, prompt exec
+    plan: { autoApproveMaxTier: -1, blockAboveTier: 0 }, // read-only: block write+exec
+    yolo: { autoApproveMaxTier: 2, blockAboveTier: 2 }, // auto-approve every tier
+};
+/**
+ * True when `mode` blocks the entire `category` outright (plan's read-only
+ * floor). The single source of truth shared by `PermissionGate.evaluate()` AND
+ * the engine's pre-hook `blockByMode` check — so a `Tool.permission()` that
+ * returns `null` to bypass the gate (e.g. `pty.read`) can't sneak past plan
+ * mode (codex 5.3 Round-1 MUST-FIX #1).
+ */
+export function isBlockedByMode(category, mode) {
+    return TIER_RANK[CATEGORY_TIER[category]] > MODE_PROFILE[mode].blockAboveTier;
+}
+/** True when `mode` auto-approves the entire `category` (yolo / auto-edit),
+ *  i.e. the interactive prompt is skipped and the call runs. */
+export function isAutoApprovedByMode(category, mode) {
+    return TIER_RANK[CATEGORY_TIER[category]] <= MODE_PROFILE[mode].autoApproveMaxTier;
+}
+/** Human-readable reason for a mode-driven block, surfaced in the tool result
+ *  so the model (and user) sees why a call was refused. */
+export function modeBlockReason(mode) {
+    return `Blocked: '${mode}' approval mode is read-only — exit ${mode} mode (shift+tab) to run mutating tools.`;
+}
+//# sourceMappingURL=approval.js.map

package/dist/tools/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../../src/tools/approval.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,aAAa,GAAmC;IAC3D,WAAW,EAAE,MAAM;IACnB,MAAM,EAAE,MAAM;IACd,aAAa,EAAE,MAAM;IACrB,YAAY,EAAE,OAAO;IACrB,cAAc,EAAE,OAAO;IACvB,KAAK,EAAE,MAAM;IACb,WAAW,EAAE,MAAM;IACnB,cAAc,EAAE,MAAM;CACvB,CAAC;AAEF,MAAM,SAAS,GAA6B,EAAE,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;AAU3E,MAAM,YAAY,GAAsC;IACtD,OAAO,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,6BAA6B;IACrF,WAAW,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,+BAA+B;IAC1F,IAAI,EAAE,EAAE,kBAAkB,EAAE,CAAC,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,8BAA8B;IACnF,IAAI,EAAE,EAAE,kBAAkB,EAAE,CAAC,EAAE,cAAc,EAAE,CAAC,EAAE,EAAE,0BAA0B;CAC/E,CAAC;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,QAAsB,EAAE,IAAkB;IACxE,OAAO,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,cAAc,CAAC;AAChF,CAAC;AAED;gEACgE;AAChE,MAAM,UAAU,oBAAoB,CAAC,QAAsB,EAAE,IAAkB;IAC7E,OAAO,SAAS,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,CAAC,kBAAkB,CAAC;AACrF,CAAC;AAED;2DAC2D;AAC3D,MAAM,UAAU,eAAe,CAAC,IAAkB;IAChD,OAAO,aAAa,IAAI,uCAAuC,IAAI,0CAA0C,CAAC;AAChH,CAAC"}

package/dist/tools/builtins/_shared.d.ts

@@ -0,0 +1,94 @@
+import type { JSONValue } from "@chances-ai/runtime";
+import type { ToolContext } from "../types.js";
+/** Diff/write-preview cap: refuses to read either side of a comparison when it
+ * exceeds this many bytes, so a `write` against a generated 50 MB file doesn't
+ * stall the approval prompt on a synchronous read. */
+export declare const PREVIEW_BYTE_CAP: number;
+export declare function str(args: JSONValue, key: string): string;
+export declare function optStr(args: JSONValue, key: string): string | undefined;
+export declare function optNum(args: JSONValue, key: string): number | undefined;
+export declare function optBool(args: JSONValue, key: string): boolean | undefined;
+/** Resolves a path and refuses to escape the workspace root.
+ *
+ * Symlinks are resolved through `realpathSync` *before* the containment
+ * check whenever EITHER condition holds:
+ *
+ *  - **Isolated context** (`runWithCwd` active — i.e. an
+ *    `isolation: 'worktree'` subagent): always, so a tracked symlink
+ *    inside the worktree that points outside it is rejected
+ *    (4.1 codex Round-1 MUST-FIX #5).
+ *  - **`opts.resolveSymlinks`** set by the caller: the file-write tools
+ *    (`write`/`edit`) pass it so that, even in the non-isolated parent
+ *    context, a workspace-internal symlink pointing OUTSIDE can't be
+ *    *written through* to plant/modify a file outside the workspace
+ *    (e.g. a git hook, build script, or dotfile). This closes the
+ *    write-escape hole that lexical-only containment leaves open — for the
+ *    full symlink chain (`realpathExtant` walks every hop and fails closed
+ *    past its depth cap), and `write`/`edit` write to the *resolved* path so
+ *    the symlink isn't re-traversed after the check.
+ *
+ *    **Residual (out of the single-agent threat model, not closed here):** a
+ *    classic TOCTOU still exists if a *concurrent* actor swaps a parent dir
+ *    for an outbound symlink in the window between this check and the
+ *    `writeFileSync`. Fully closing it needs an `openat`/`O_NOFOLLOW` path
+ *    walk (no clean Node API); documented as a future-hardening pointer.
+ *
+ * In the resolving branch, both `workspaceRoot` and the target are
+ * realpath'd so the comparison is between fully-resolved trees; for
+ * non-existent leaves (the standard `write` case) and dangling symlinks,
+ * `realpathExtant` walks the symlink chain up to the nearest existing
+ * ancestor and re-joins the missing tail.
+ *
+ * **Windows junctions.** An NTFS junction (a directory reparse point) is
+ * NOT reported as a symlink by `lstat().isSymbolicLink()`, so it skips the
+ * manual `readlink` branch in `realpathExtant` — but `realpathSync` DOES
+ * traverse it, so a write target under a junction that points outside the
+ * workspace still resolves outside and is rejected by the containment check.
+ * Covered by the win32-only junction tests in `_shared.symlink.test.ts` (D-C).
+ *
+ * **Read-class tools** (`read`/`grep`/`glob`/`diff`/`lsp`) deliberately
+ * stay lexical in the non-isolated context: reading *through* an inbound
+ * symlink (a config/fixture symlinked into a repo) is a common, legitimate
+ * pattern, and the high-severity risk is *writing* outside the workspace,
+ * not reading a file the caller's own UID can already read. (claude-code
+ * resolves reads too; we intentionally keep them lexical here to avoid
+ * breaking legit symlinked-file reads — revisit if a read-escape threat
+ * emerges.)
+ */
+export declare function safePath(ctx: ToolContext, p: string, opts?: {
+    resolveSymlinks?: boolean;
+}): string;
+/** Render a string as a short JSON-quoted preview for permission prompts. */
+export declare function preview(s: string): string;
+export { cleanOutput, normaliseLineEndings, stripAnsi } from "@chances-ai/runtime";
+/** Map an engine call id to a filesystem-safe artifact-dir name (5.7 / codex
+ * R1 M2). A clean id (`toolu_…`, `call_…`) is used **verbatim** — that branch is
+ * injective and the dir name stays human-readable, joining 1:1 to the
+ * `tool_result` the client saw. Anything else — a hostile/unusual provider id
+ * containing `/`, `..`, or other bytes, OR an empty string — is replaced
+ * WHOLESALE by `id-<sha256[:16]>` rather than lossily mapped (`a/b` and `a_b`
+ * must NOT collide into one dir and overwrite each other). That hash branch is
+ * **collision-resistant, not strictly injective** (a 64-bit truncation), but
+ * for the volume of tool calls in a session the collision probability is
+ * negligible and a collision is never a security issue (worst case: two
+ * unrelated calls share a dir — never a traversal). Traversal is impossible in
+ * both branches: verbatim only admits `[A-Za-z0-9_-]`, the hash only emits hex. */
+export declare function safeArtifactId(raw: string): string;
+/** Best-effort persistence under `<root>/.chances/tool-results/<id>/<file>`
+ * with restrictive POSIX permissions (0o700 dir, 0o600 file). Returns the
+ * absolute path on success, `null` on filesystem failure (the caller's
+ * banner still renders an inline preview either way, so persistence
+ * failure degrades to "model only sees the head"; not a fatal tool
+ * error).
+ *
+ * `id` is the engine's `ctx.callId` (5.7) when available — the artifact dir is
+ * then named for the real call so a client correlates the saved file with the
+ * `tool_result`. Falls back to a fresh `createId(prefix)` for non-engine
+ * callers (tests/plugins) — fully backward compatible.
+ *
+ * **Windows caveat.** Node's `fs` `mode` flag only affects the read-only
+ * bit on Windows; ACL-based access control is not enforced via this
+ * argument. POSIX-first audience; explicit DACL hardening is a follow-up.
+ */
+export declare function persistFullOutput(workspaceRoot: string, body: string, prefix?: string, filename?: string, id?: string): string | null;
+//# sourceMappingURL=_shared.d.ts.map

package/dist/tools/builtins/_shared.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"_shared.d.ts","sourceRoot":"","sources":["../../../src/tools/builtins/_shared.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;sDAEsD;AACtD,eAAO,MAAM,gBAAgB,QAAa,CAAC;AAE3C,wBAAgB,GAAG,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAKvE;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAOvE;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAKzE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,wBAAgB,QAAQ,CACtB,GAAG,EAAE,WAAW,EAChB,CAAC,EAAE,MAAM,EACT,IAAI,CAAC,EAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAA;CAAE,GACnC,MAAM,CAqBR;AA0ED,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGzC;AAaD,OAAO,EAAE,WAAW,EAAE,oBAAoB,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAEnF;;;;;;;;;;;mFAWmF;AACnF,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,iBAAiB,CAC/B,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,MAAM,SAAS,EACf,QAAQ,SAAe,EACvB,EAAE,CAAC,EAAE,MAAM,GACV,MAAM,GAAG,IAAI,CAef"}

package/dist/tools/builtins/_shared.js

@@ -0,0 +1,246 @@
+import { createHash } from "node:crypto";
+import { lstatSync, mkdirSync, readlinkSync, realpathSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { AppError, ErrorCode, createId, currentCwdOverride } from "@chances-ai/runtime";
+/** Diff/write-preview cap: refuses to read either side of a comparison when it
+ * exceeds this many bytes, so a `write` against a generated 50 MB file doesn't
+ * stall the approval prompt on a synchronous read. */
+export const PREVIEW_BYTE_CAP = 256 * 1024;
+export function str(args, key) {
+    const v = args[key];
+    if (typeof v !== "string")
+        throw new AppError(ErrorCode.Tool, `Expected string arg "${key}"`);
+    return v;
+}
+export function optStr(args, key) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "string")
+        throw new AppError(ErrorCode.Tool, `Expected string arg "${key}"`);
+    return v;
+}
+export function optNum(args, key) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "number" || !Number.isFinite(v)) {
+        throw new AppError(ErrorCode.Tool, `Expected number arg "${key}"`);
+    }
+    return v;
+}
+export function optBool(args, key) {
+    const v = args[key];
+    if (v === undefined || v === null)
+        return undefined;
+    if (typeof v !== "boolean")
+        throw new AppError(ErrorCode.Tool, `Expected boolean arg "${key}"`);
+    return v;
+}
+/** Resolves a path and refuses to escape the workspace root.
+ *
+ * Symlinks are resolved through `realpathSync` *before* the containment
+ * check whenever EITHER condition holds:
+ *
+ *  - **Isolated context** (`runWithCwd` active — i.e. an
+ *    `isolation: 'worktree'` subagent): always, so a tracked symlink
+ *    inside the worktree that points outside it is rejected
+ *    (4.1 codex Round-1 MUST-FIX #5).
+ *  - **`opts.resolveSymlinks`** set by the caller: the file-write tools
+ *    (`write`/`edit`) pass it so that, even in the non-isolated parent
+ *    context, a workspace-internal symlink pointing OUTSIDE can't be
+ *    *written through* to plant/modify a file outside the workspace
+ *    (e.g. a git hook, build script, or dotfile). This closes the
+ *    write-escape hole that lexical-only containment leaves open — for the
+ *    full symlink chain (`realpathExtant` walks every hop and fails closed
+ *    past its depth cap), and `write`/`edit` write to the *resolved* path so
+ *    the symlink isn't re-traversed after the check.
+ *
+ *    **Residual (out of the single-agent threat model, not closed here):** a
+ *    classic TOCTOU still exists if a *concurrent* actor swaps a parent dir
+ *    for an outbound symlink in the window between this check and the
+ *    `writeFileSync`. Fully closing it needs an `openat`/`O_NOFOLLOW` path
+ *    walk (no clean Node API); documented as a future-hardening pointer.
+ *
+ * In the resolving branch, both `workspaceRoot` and the target are
+ * realpath'd so the comparison is between fully-resolved trees; for
+ * non-existent leaves (the standard `write` case) and dangling symlinks,
+ * `realpathExtant` walks the symlink chain up to the nearest existing
+ * ancestor and re-joins the missing tail.
+ *
+ * **Windows junctions.** An NTFS junction (a directory reparse point) is
+ * NOT reported as a symlink by `lstat().isSymbolicLink()`, so it skips the
+ * manual `readlink` branch in `realpathExtant` — but `realpathSync` DOES
+ * traverse it, so a write target under a junction that points outside the
+ * workspace still resolves outside and is rejected by the containment check.
+ * Covered by the win32-only junction tests in `_shared.symlink.test.ts` (D-C).
+ *
+ * **Read-class tools** (`read`/`grep`/`glob`/`diff`/`lsp`) deliberately
+ * stay lexical in the non-isolated context: reading *through* an inbound
+ * symlink (a config/fixture symlinked into a repo) is a common, legitimate
+ * pattern, and the high-severity risk is *writing* outside the workspace,
+ * not reading a file the caller's own UID can already read. (claude-code
+ * resolves reads too; we intentionally keep them lexical here to avoid
+ * breaking legit symlinked-file reads — revisit if a read-escape threat
+ * emerges.)
+ */
+export function safePath(ctx, p, opts) {
+    const abs = isAbsolute(p) ? p : resolve(ctx.cwd, p);
+    const isolated = currentCwdOverride() !== undefined;
+    if (isolated || opts?.resolveSymlinks) {
+        // Realpath both sides, then re-check against the fully-resolved trees.
+        const rootReal = realpathSafe(ctx.workspaceRoot);
+        const absReal = realpathExtant(abs);
+        const rel = relative(rootReal, absReal);
+        if (rel.startsWith("..") || isAbsolute(rel)) {
+            throw new AppError(ErrorCode.Permission, `Path escapes workspace: ${p}`);
+        }
+        return absReal;
+    }
+    // Non-isolated read-class path: lexical containment only, unchanged since 1.x.
+    const rel = relative(ctx.workspaceRoot, abs);
+    if (rel.startsWith("..") || isAbsolute(rel)) {
+        throw new AppError(ErrorCode.Permission, `Path escapes workspace: ${p}`);
+    }
+    return abs;
+}
+/** Realpath an existing path. We always expect `workspaceRoot` to exist
+ * when invoked through the engine; if it doesn't we fall back to the
+ * original (lexical containment is then a no-op safety net). */
+function realpathSafe(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return p;
+    }
+}
+/** Realpath a path that may or may not exist, resolving any symlinks
+ * at the leaf — including DANGLING symlinks (Round-2 MUST-FIX #3). A
+ * symlink whose target doesn't exist would otherwise be accepted by the
+ * lexical containment check; a subsequent `write` would then follow the
+ * symlink and create the target OUTSIDE the worktree. We catch this by
+ * `lstat`-ing the leaf first; if it's a symlink, we resolve the link
+ * target manually (relative-to-link-dir if not absolute) and recurse.
+ * Bounded by `SYMLINK_RESOLVE_MAX_DEPTH` to defeat link cycles.
+ *
+ * On depth exhaustion we **fail closed** (throw) rather than returning the
+ * unresolved path: returning the lexically-in-workspace symlink would let a
+ * `write` follow a >8-hop chain OUTSIDE the workspace — the very escape this
+ * resolution prevents (5.6-era symlink-hardening codex MUST-FIX). A legit
+ * path practically never chains >8 symlinks, so rejecting is the safe choice. */
+const SYMLINK_RESOLVE_MAX_DEPTH = 8;
+function realpathExtant(p, depth = 0) {
+    // Detect symlinks (live OR dangling) at the leaf BEFORE the
+    // `realpathSync` happy path — dangling symlinks make `realpathSync`
+    // throw ENOENT, which we previously swallowed and rejoined the leaf
+    // verbatim (the bug).
+    try {
+        const lst = lstatSync(p);
+        if (lst.isSymbolicLink()) {
+            if (depth >= SYMLINK_RESOLVE_MAX_DEPTH) {
+                throw new AppError(ErrorCode.Permission, `Symlink chain too deep (possible workspace escape): ${p}`);
+            }
+            const target = readlinkSync(p);
+            const resolved = isAbsolute(target) ? target : resolve(dirname(p), target);
+            return realpathExtant(resolved, depth + 1);
+        }
+    }
+    catch (e) {
+        // Propagate our own fail-closed throw (and any deeper one from the
+        // recursion); only swallow the expected fs errors (lstat ENOENT on a
+        // non-existent leaf), which fall through to the ancestor walk below.
+        if (e instanceof AppError)
+            throw e;
+    }
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        /* fall through */
+    }
+    let current = dirname(p);
+    let tail = p.slice(current.length);
+    while (current !== dirname(current)) {
+        try {
+            const real = realpathSync(current);
+            return join(real, tail);
+        }
+        catch {
+            tail = current.slice(dirname(current).length) + tail;
+            current = dirname(current);
+        }
+    }
+    // Reached the root without finding an existing ancestor; return the
+    // path lexically resolved (this is the standard cwd-relative form, so
+    // containment falls through to the lexical check above).
+    return p;
+}
+/** Render a string as a short JSON-quoted preview for permission prompts. */
+export function preview(s) {
+    const one = s.replace(/\s+/g, " ").trim();
+    return JSON.stringify(one.length > 40 ? one.slice(0, 40) + "…" : one);
+}
+// ---------------------------------------------------------------------------
+// (5.1) Shared output-cleaning + persistence helpers used by `bash` and
+// the new `pty` interactive tool. Both tools strip ANSI before showing
+// the model the body, and persist oversized bodies to
+// `.chances/tool-results/<id>/<file>` under restrictive POSIX perms.
+//
+// (5.7) The ANSI / control-char strippers moved to `@chances-ai/runtime`
+// (`text-sanitize.ts`) so the bash tool, the pty registry, and the MCP /
+// compaction / agents sanitizers all share ONE audited implementation
+// instead of byte-copied regexes. Re-exported here so existing
+// `./_shared.js` importers (bash, pty) are unchanged.
+export { cleanOutput, normaliseLineEndings, stripAnsi } from "@chances-ai/runtime";
+/** Map an engine call id to a filesystem-safe artifact-dir name (5.7 / codex
+ * R1 M2). A clean id (`toolu_…`, `call_…`) is used **verbatim** — that branch is
+ * injective and the dir name stays human-readable, joining 1:1 to the
+ * `tool_result` the client saw. Anything else — a hostile/unusual provider id
+ * containing `/`, `..`, or other bytes, OR an empty string — is replaced
+ * WHOLESALE by `id-<sha256[:16]>` rather than lossily mapped (`a/b` and `a_b`
+ * must NOT collide into one dir and overwrite each other). That hash branch is
+ * **collision-resistant, not strictly injective** (a 64-bit truncation), but
+ * for the volume of tool calls in a session the collision probability is
+ * negligible and a collision is never a security issue (worst case: two
+ * unrelated calls share a dir — never a traversal). Traversal is impossible in
+ * both branches: verbatim only admits `[A-Za-z0-9_-]`, the hash only emits hex. */
+export function safeArtifactId(raw) {
+    if (/^[A-Za-z0-9_-]{1,128}$/.test(raw))
+        return raw;
+    return `id-${createHash("sha256").update(raw).digest("hex").slice(0, 16)}`;
+}
+/** Best-effort persistence under `<root>/.chances/tool-results/<id>/<file>`
+ * with restrictive POSIX permissions (0o700 dir, 0o600 file). Returns the
+ * absolute path on success, `null` on filesystem failure (the caller's
+ * banner still renders an inline preview either way, so persistence
+ * failure degrades to "model only sees the head"; not a fatal tool
+ * error).
+ *
+ * `id` is the engine's `ctx.callId` (5.7) when available — the artifact dir is
+ * then named for the real call so a client correlates the saved file with the
+ * `tool_result`. Falls back to a fresh `createId(prefix)` for non-engine
+ * callers (tests/plugins) — fully backward compatible.
+ *
+ * **Windows caveat.** Node's `fs` `mode` flag only affects the read-only
+ * bit on Windows; ACL-based access control is not enforced via this
+ * argument. POSIX-first audience; explicit DACL hardening is a follow-up.
+ */
+export function persistFullOutput(workspaceRoot, body, prefix = "tool", filename = "output.txt", id) {
+    try {
+        // `id !== undefined` (not truthiness) so an empty-string call id still
+        // routes through `safeArtifactId` (→ a hash dir) instead of silently
+        // falling back to a random `createId`, which would break correlation
+        // with `tool_result.callId === ""` (codex R2 Q2).
+        const dirName = id !== undefined ? safeArtifactId(id) : createId(prefix);
+        const dir = join(workspaceRoot, ".chances", "tool-results", dirName);
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const path = join(dir, filename);
+        writeFileSync(path, body, { mode: 0o600 });
+        return path;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=_shared.js.map