@alisio/core 0.1.0-alpha.8 → 0.1.0

package/dist/runtime/access.d.ts

@@ -0,0 +1,62 @@
+import type { ApprovalDecision } from "../core/contracts.ts";
+export type ExternalDirectoryDecision = ApprovalDecision;
+export interface ExternalDirectoryRequest {
+    /** Canonical directory the call needs; approval is scoped to this directory and its subtree. */
+    directory: string;
+    /** Concrete path that triggered the request (named in the prompt and the error). */
+    path: string;
+    session?: string;
+    label?: string;
+    signal: AbortSignal;
+}
+/**
+ * Interactive approval for a directory outside the workspace and every declared extra root.
+ * The three decisions match the existing tool-ask flow: allow once, allow for the session, deny.
+ */
+export type ExternalDirectoryHandler = (request: ExternalDirectoryRequest) => Promise<ExternalDirectoryDecision>;
+export interface PathAccessOptions {
+    /** Canonical workspace root (the fallback boundary for every relative tool path). */
+    workspace: string;
+    /** Declared extra roots (config `additionalDirectories` plus per-run `--add-dir`). */
+    extraRoots?: readonly string[];
+    /** Interactive approval for directories outside every allowed root. */
+    approve?: ExternalDirectoryHandler;
+    /** Fully locked: declared roots are ignored and no external directory is ever approvable. */
+    readOnly?: boolean;
+}
+export interface ResolvePathOptions {
+    /** Workspace to resolve a relative path against (child sessions may use a worktree). */
+    workspace?: string;
+    session?: string;
+    label?: string;
+    signal?: AbortSignal;
+    /**
+     * When false, an unapproved external directory is denied without prompting. Used by nested
+     * `execute` calls, which must never trigger a new interactive approval.
+     */
+    interactive?: boolean;
+}
+export declare class PathAccess {
+    readonly workspace: string;
+    private readonly roots;
+    private readonly approve?;
+    private readonly readOnly;
+    /** Session-approved directory subtrees (allow for the session). */
+    private readonly approved;
+    /** Canonicalized roots, memoized; a nonexistent declared root never matches. */
+    private readonly canonical;
+    constructor(options: PathAccessOptions);
+    /** Extra roots actually in force (always empty under `--read-only`). */
+    get extraRoots(): readonly string[];
+    /** Directory subtrees approved for the session (diagnostics and tests). */
+    approvedDirectories(): string[];
+    private canonicalize;
+    /** The allowed root that contains `target`, if any. */
+    private rootFor;
+    /**
+     * Resolves one tool path under the mediated policy. Inside the workspace or a declared extra
+     * root it behaves exactly like `safePath`; outside every root it asks for directory approval (or
+     * denies with the actionable message when no approval is possible).
+     */
+    resolve(path: string, options?: ResolvePathOptions): Promise<string>;
+}

package/dist/runtime/access.js

@@ -0,0 +1,115 @@
+/**
+ * Mediated path access: the workspace plus explicitly declared extra directories.
+ *
+ * A tool path is resolved against the workspace first. Paths that fall outside every allowed root
+ * are NOT rejected outright anymore: they trigger an interactive approval scoped to the containing
+ * directory (mirroring OpenCode's `external_directory` model), and the approved directory is
+ * remembered for the session. In non-interactive runs the same check denies with an actionable
+ * error that names the resolved path and the exact remedy instead of hanging.
+ *
+ * This reuses `safePath`'s symlink hardening for the final resolution, so the symlink and
+ * per-segment `lstat` guarantees are preserved. Like the rest of Alisio, this is mediation, not an
+ * OS sandbox and not race-proof against hostile concurrent processes.
+ */
+import { lstat, realpath } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { inside, outsideRootsMessage, safePath } from "./paths.js";
+/** Nearest existing ancestor directory of `target`, canonicalized; used as the approval boundary. */
+async function nearestExistingDirectory(target) {
+    let current = target;
+    for (;;) {
+        try {
+            if ((await lstat(current)).isDirectory())
+                return await realpath(current);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw e;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+}
+export class PathAccess {
+    workspace;
+    roots;
+    approve;
+    readOnly;
+    /** Session-approved directory subtrees (allow for the session). */
+    approved = new Set();
+    /** Canonicalized roots, memoized; a nonexistent declared root never matches. */
+    canonical = new Map();
+    constructor(options) {
+        this.workspace = options.workspace;
+        this.roots = options.readOnly ? [] : [...(options.extraRoots ?? [])];
+        this.readOnly = !!options.readOnly;
+        if (options.approve && !options.readOnly)
+            this.approve = options.approve;
+    }
+    /** Extra roots actually in force (always empty under `--read-only`). */
+    get extraRoots() {
+        return this.roots;
+    }
+    /** Directory subtrees approved for the session (diagnostics and tests). */
+    approvedDirectories() {
+        return [...this.approved];
+    }
+    canonicalize(path) {
+        let cached = this.canonical.get(path);
+        if (!cached) {
+            cached = realpath(path).catch(() => undefined);
+            this.canonical.set(path, cached);
+        }
+        return cached;
+    }
+    /** The allowed root that contains `target`, if any. */
+    async rootFor(target, workspace) {
+        const canonicalWorkspace = (await this.canonicalize(workspace)) ?? workspace;
+        if (inside(canonicalWorkspace, target))
+            return canonicalWorkspace;
+        for (const root of this.roots) {
+            const canonical = await this.canonicalize(root);
+            if (canonical && inside(canonical, target))
+                return canonical;
+        }
+        return undefined;
+    }
+    /**
+     * Resolves one tool path under the mediated policy. Inside the workspace or a declared extra
+     * root it behaves exactly like `safePath`; outside every root it asks for directory approval (or
+     * denies with the actionable message when no approval is possible).
+     */
+    async resolve(path, options = {}) {
+        const workspace = options.workspace ?? this.workspace;
+        const target = resolve(workspace, path);
+        const root = await this.rootFor(target, workspace);
+        if (root)
+            return safePath(root, target);
+        if (this.readOnly)
+            throw new Error(outsideRootsMessage(target, "--read-only disables access outside the workspace; run without it to allow it"));
+        const boundary = await nearestExistingDirectory(target);
+        for (const approved of this.approved)
+            if (inside(approved, target))
+                return safePath(approved, target);
+        const approve = this.approve;
+        if (options.interactive === false || !approve)
+            throw new Error(outsideRootsMessage(target, approve
+                ? "this call cannot request a new interactive approval"
+                : "no interactive approval is available in this run"));
+        const decision = await approve({
+            directory: boundary,
+            path: target,
+            ...(options.session ? { session: options.session } : {}),
+            ...(options.label ? { label: options.label } : {}),
+            signal: options.signal ?? new AbortController().signal,
+        });
+        if (decision === "session")
+            this.approved.add(boundary);
+        if (decision === "session" || decision === "once")
+            return safePath(boundary, target);
+        throw new Error(outsideRootsMessage(target, `access to directory "${boundary}" was denied by the user`));
+    }
+}

package/dist/runtime/blobs.d.ts

@@ -0,0 +1,51 @@
+import type { Attachment, BlobRef, SqlDatabase } from "@alisio/sdk";
+/** A streamed blob exceeded its size limit. */
+export declare class BlobTooLarge extends Error {
+    readonly limit: number;
+    constructor(limit: number);
+}
+export interface BlobStoreOptions {
+    /** Directory that holds `sha256/…` (by default `<state home>/blobs`). */
+    root: string;
+    /** Session database with the v4 `blobs` table (e.g. `SQLiteStore.db`). */
+    db: SqlDatabase;
+}
+export declare class BlobStore {
+    private readonly options;
+    constructor(options: BlobStoreOptions);
+    /** Absolute file path of a blob. Throws for anything that is not a lowercase sha256 hex. */
+    path(hash: string): string;
+    has(hash: string): boolean;
+    private row;
+    /** Stores bytes once per content hash and returns their reference. */
+    put(bytes: Uint8Array, mimeType: string, dims?: {
+        width?: number;
+        height?: number;
+    }): BlobRef;
+    /**
+     * Stores a byte stream (an upload too large to hold in memory, e.g. a dataset) once per content
+     * hash, hashing while it writes. Fails with `BlobTooLarge` as soon as `maxBytes` is exceeded and
+     * leaves nothing behind. The stored type is the declared one; images stay the only blobs that
+     * `attachment()` and the blob route serve.
+     */
+    putStream(stream: AsyncIterable<Uint8Array>, mimeType: string, options: {
+        maxBytes: number;
+    }): Promise<BlobRef>;
+    /**
+     * Retention: deletes the bytes and the row of a blob that is not an image (an uploaded dataset
+     * original). Images are referenced by messages and are never removed here. Returns the freed
+     * bytes (0 when the blob is unknown, an image or already gone).
+     */
+    removeUpload(hash: string): number;
+    /** Hashes of non-image blobs created before `cutoff` (epoch ms): uploaded dataset originals. */
+    uploadsBefore(cutoff: number): string[];
+    get(hash: string): {
+        bytes: Buffer;
+        mimeType: string;
+    } | undefined;
+    /**
+     * Resolves a reference into a provider-ready image `Attachment` (base64 `data`), verifying
+     * that the stored bytes still match the hash.
+     */
+    attachment(ref: BlobRef): Attachment;
+}

package/dist/runtime/blobs.js

@@ -0,0 +1,177 @@
+/**
+ * Content-addressed attachment bytes (v4). Files live at `<root>/sha256/<hash[0..2]>/<hash>`
+ * (directories 0700, files 0600, atomic temp-file + rename); metadata lives in the `blobs` table
+ * of the session database. Portable `node:fs`/`node:crypto` only (Node and Bun).
+ *
+ * `Attachment.data` stays required in the SDK, so blobs never reach the runner by reference: the
+ * host resolves a `BlobRef` into a base64 `Attachment` with `attachment()` before `runner.run`.
+ * Persisted messages therefore still carry base64 (as legacy inline attachments do).
+ */
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { pipeline } from "node:stream/promises";
+const HASH = /^[0-9a-f]{64}$/;
+/** A streamed blob exceeded its size limit. */
+export class BlobTooLarge extends Error {
+    limit;
+    constructor(limit) {
+        super(`The upload exceeds ${limit} bytes`);
+        this.limit = limit;
+    }
+}
+export class BlobStore {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    /** Absolute file path of a blob. Throws for anything that is not a lowercase sha256 hex. */
+    path(hash) {
+        if (!HASH.test(hash))
+            throw new Error(`Invalid blob hash: ${hash.slice(0, 80)}`);
+        return join(this.options.root, "sha256", hash.slice(0, 2), hash);
+    }
+    has(hash) {
+        return HASH.test(hash) && existsSync(this.path(hash)) && !!this.row(hash);
+    }
+    row(hash) {
+        return this.options.db.prepare("SELECT * FROM blobs WHERE hash=?").get(hash);
+    }
+    /** Stores bytes once per content hash and returns their reference. */
+    put(bytes, mimeType, dims = {}) {
+        const mime = mimeType.trim();
+        if (!mime || mime.length > 255)
+            throw new Error("A blob needs a MIME type");
+        const hash = createHash("sha256").update(bytes).digest("hex");
+        const file = this.path(hash);
+        if (!existsSync(file)) {
+            const dir = join(this.options.root, "sha256", hash.slice(0, 2));
+            mkdirSync(dir, { recursive: true, mode: 0o700 });
+            chmodSync(dir, 0o700);
+            const temp = join(dir, `.tmp-${randomUUID()}`);
+            try {
+                writeFileSync(temp, bytes, { mode: 0o600, flag: "wx" });
+                renameSync(temp, file);
+            }
+            catch (error) {
+                rmSync(temp, { force: true });
+                throw error;
+            }
+        }
+        this.options.db
+            .prepare("INSERT OR IGNORE INTO blobs(hash,mime,size,width,height,created_at) VALUES(?,?,?,?,?,?)")
+            .run(hash, mime, bytes.byteLength, dims.width ?? null, dims.height ?? null, Date.now());
+        const row = this.row(hash);
+        return {
+            hash,
+            mimeType: row?.mime ?? mime,
+            bytes: bytes.byteLength,
+            ...(row?.width != null ? { width: Number(row.width) } : {}),
+            ...(row?.height != null ? { height: Number(row.height) } : {}),
+        };
+    }
+    /**
+     * Stores a byte stream (an upload too large to hold in memory, e.g. a dataset) once per content
+     * hash, hashing while it writes. Fails with `BlobTooLarge` as soon as `maxBytes` is exceeded and
+     * leaves nothing behind. The stored type is the declared one; images stay the only blobs that
+     * `attachment()` and the blob route serve.
+     */
+    async putStream(stream, mimeType, options) {
+        const mime = mimeType.trim();
+        if (!mime || mime.length > 255)
+            throw new Error("A blob needs a MIME type");
+        const dir = join(this.options.root, "sha256");
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        const temp = join(dir, `.tmp-${randomUUID()}`);
+        const hash = createHash("sha256");
+        let size = 0;
+        try {
+            await pipeline(stream, async function* (source) {
+                for await (const chunk of source) {
+                    size += chunk.byteLength;
+                    if (size > options.maxBytes)
+                        throw new BlobTooLarge(options.maxBytes);
+                    hash.update(chunk);
+                    yield chunk;
+                }
+            }, createWriteStream(temp, { mode: 0o600, flags: "wx" }));
+            const digest = hash.digest("hex");
+            const file = this.path(digest);
+            const fileDir = join(dir, digest.slice(0, 2));
+            mkdirSync(fileDir, { recursive: true, mode: 0o700 });
+            chmodSync(fileDir, 0o700);
+            if (existsSync(file))
+                rmSync(temp, { force: true });
+            else
+                renameSync(temp, file);
+            this.options.db
+                .prepare("INSERT OR IGNORE INTO blobs(hash,mime,size,width,height,created_at) VALUES(?,?,?,?,?,?)")
+                .run(digest, mime, statSync(file).size, null, null, Date.now());
+            const row = this.row(digest);
+            return { hash: digest, mimeType: row?.mime ?? mime, bytes: statSync(file).size };
+        }
+        catch (error) {
+            rmSync(temp, { force: true });
+            throw error;
+        }
+    }
+    /**
+     * Retention: deletes the bytes and the row of a blob that is not an image (an uploaded dataset
+     * original). Images are referenced by messages and are never removed here. Returns the freed
+     * bytes (0 when the blob is unknown, an image or already gone).
+     */
+    removeUpload(hash) {
+        if (!HASH.test(hash))
+            return 0;
+        const row = this.row(hash);
+        if (row?.mime.startsWith("image/"))
+            return 0;
+        const file = this.path(hash);
+        let size = 0;
+        try {
+            size = statSync(file).size;
+            rmSync(file, { force: true });
+        }
+        catch {
+            /* Already gone. */
+        }
+        this.options.db.prepare("DELETE FROM blobs WHERE hash=?").run(hash);
+        return size;
+    }
+    /** Hashes of non-image blobs created before `cutoff` (epoch ms): uploaded dataset originals. */
+    uploadsBefore(cutoff) {
+        return this.options.db
+            .prepare("SELECT hash FROM blobs WHERE mime NOT LIKE 'image/%' AND created_at<?")
+            .all(cutoff).map((r) => r.hash);
+    }
+    get(hash) {
+        if (!HASH.test(hash))
+            return undefined;
+        const row = this.row(hash);
+        const file = this.path(hash);
+        if (!row || !existsSync(file))
+            return undefined;
+        return { bytes: readFileSync(file), mimeType: row.mime };
+    }
+    /**
+     * Resolves a reference into a provider-ready image `Attachment` (base64 `data`), verifying
+     * that the stored bytes still match the hash.
+     */
+    attachment(ref) {
+        const found = this.get(ref.hash);
+        if (!found)
+            throw new Error(`Blob not found: ${ref.hash}`);
+        if (createHash("sha256").update(found.bytes).digest("hex") !== ref.hash)
+            throw new Error(`Blob content does not match its hash: ${ref.hash}`);
+        if (!found.mimeType.startsWith("image/"))
+            throw new Error(`Only image blobs can be attached (got ${found.mimeType})`);
+        return {
+            kind: "image",
+            mimeType: found.mimeType,
+            data: found.bytes.toString("base64"),
+            bytes: found.bytes.byteLength,
+            ...(ref.width !== undefined ? { width: ref.width } : {}),
+            ...(ref.height !== undefined ? { height: ref.height } : {}),
+        };
+    }
+}

package/dist/runtime/diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Unified line diffs for the `diff` UiBlock that `write_file`/`edit_file` attach for rich
+ * clients (spec §8.6, RF-13). Myers O((N+M)·D) on lines after trimming the common prefix and
+ * suffix; when the edit distance exceeds `maxD` the middle becomes a full replacement. Pure and
+ * portable (no dependency). The web UI ships its own copy of the algorithm for third-party blocks
+ * that only carry `before`/`after` (packages cannot share code with the browser bundle).
+ */
+type Op = 0 | 1 | 2;
+/** Line edit script (0 equal, 1 delete, 2 insert). */
+export declare function lineEdits(a: string[], b: string[], maxD?: number): Op[];
+/**
+ * A unified patch (`--- a/path`, `+++ b/path`, hunks with `context` lines) from `before` to
+ * `after`; `undefined` means the file did not exist. Identical texts give `""`.
+ */
+export declare function unifiedPatch(path: string, before: string | undefined, after: string | undefined, options?: {
+    context?: number;
+}): string;
+/** Cuts `text` at a line boundary so it fits in `maxBytes` (UTF-8). */
+export declare function clipLines(text: string, maxBytes: number): {
+    text: string;
+    clipped: boolean;
+};
+export {};

package/dist/runtime/diff.js

@@ -0,0 +1,154 @@
+/**
+ * Unified line diffs for the `diff` UiBlock that `write_file`/`edit_file` attach for rich
+ * clients (spec §8.6, RF-13). Myers O((N+M)·D) on lines after trimming the common prefix and
+ * suffix; when the edit distance exceeds `maxD` the middle becomes a full replacement. Pure and
+ * portable (no dependency). The web UI ships its own copy of the algorithm for third-party blocks
+ * that only carry `before`/`after` (packages cannot share code with the browser bundle).
+ */
+function myers(a, b, maxD) {
+    const n = a.length;
+    const m = b.length;
+    if (!n)
+        return b.map(() => 2);
+    if (!m)
+        return a.map(() => 1);
+    const max = n + m;
+    const offset = max + 1;
+    const v = new Int32Array(2 * max + 3);
+    const trace = [];
+    for (let d = 0; d <= Math.min(max, maxD); d++) {
+        trace.push(v.slice(offset - d - 1, offset + d + 2));
+        for (let k = -d; k <= d; k += 2) {
+            let x = k === -d || (k !== d && v[offset + k - 1] < v[offset + k + 1])
+                ? v[offset + k + 1]
+                : v[offset + k - 1] + 1;
+            let y = x - k;
+            while (x < n && y < m && a[x] === b[y]) {
+                x++;
+                y++;
+            }
+            v[offset + k] = x;
+            if (x >= n && y >= m)
+                return backtrack(trace, n, m);
+        }
+    }
+    return undefined;
+}
+function backtrack(trace, n, m) {
+    const ops = [];
+    let x = n;
+    let y = m;
+    for (let d = trace.length - 1; d > 0; d--) {
+        const snap = trace[d];
+        const at = (k) => snap[k + d + 1];
+        const k = x - y;
+        const prevK = k === -d || (k !== d && at(k - 1) < at(k + 1)) ? k + 1 : k - 1;
+        const prevX = at(prevK);
+        const prevY = prevX - prevK;
+        while (x > prevX && y > prevY) {
+            ops.push(0);
+            x--;
+            y--;
+        }
+        ops.push(x === prevX ? 2 : 1);
+        x = prevX;
+        y = prevY;
+    }
+    while (x > 0 && y > 0) {
+        ops.push(0);
+        x--;
+        y--;
+    }
+    return ops.reverse();
+}
+/** Line edit script (0 equal, 1 delete, 2 insert). */
+export function lineEdits(a, b, maxD = 2000) {
+    let start = 0;
+    while (start < a.length && start < b.length && a[start] === b[start])
+        start++;
+    let endA = a.length;
+    let endB = b.length;
+    while (endA > start && endB > start && a[endA - 1] === b[endB - 1]) {
+        endA--;
+        endB--;
+    }
+    const midA = a.slice(start, endA);
+    const midB = b.slice(start, endB);
+    const middle = myers(midA, midB, maxD) ?? [...midA.map(() => 1), ...midB.map(() => 2)];
+    return [...new Array(start).fill(0), ...middle, ...new Array(a.length - endA).fill(0)];
+}
+const NO_EOL = "\u0000no-eol";
+/** Lines of a text; a last line without `\n` carries a marker so a newline change is a change. */
+function linesOf(text) {
+    if (!text)
+        return [];
+    const lines = text.split("\n");
+    if (lines.at(-1) === "")
+        lines.pop();
+    else
+        lines[lines.length - 1] = `${lines.at(-1)}${NO_EOL}`;
+    return lines;
+}
+/**
+ * A unified patch (`--- a/path`, `+++ b/path`, hunks with `context` lines) from `before` to
+ * `after`; `undefined` means the file did not exist. Identical texts give `""`.
+ */
+export function unifiedPatch(path, before, after, options = {}) {
+    const context = options.context ?? 3;
+    const a = linesOf(before);
+    const b = linesOf(after);
+    const rows = [];
+    let i = 0;
+    let j = 0;
+    for (const op of lineEdits(a, b)) {
+        if (op === 0)
+            rows.push({ op, text: a[i], old: i++, new: j++ });
+        else if (op === 1)
+            rows.push({ op, text: a[i], old: i++, new: j });
+        else
+            rows.push({ op, text: b[j], old: i, new: j++ });
+    }
+    const hunks = [];
+    for (let k = 0; k < rows.length; k++) {
+        if (rows[k].op === 0)
+            continue;
+        const from = Math.max(0, k - context);
+        const last = hunks.at(-1);
+        if (last && from <= last[1] + 1)
+            last[1] = Math.min(rows.length - 1, k + context);
+        else
+            hunks.push([from, Math.min(rows.length - 1, k + context)]);
+    }
+    if (!hunks.length)
+        return "";
+    const out = [
+        `--- ${before === undefined ? "/dev/null" : `a/${path}`}`,
+        `+++ ${after === undefined ? "/dev/null" : `b/${path}`}`,
+    ];
+    const range = (start, count) => count === 1 ? `${start + 1}` : `${count === 0 ? start : start + 1},${count}`;
+    for (const [from, to] of hunks) {
+        const slice = rows.slice(from, to + 1);
+        const first = slice[0];
+        const oldCount = slice.filter((r) => r.op !== 2).length;
+        const newCount = slice.filter((r) => r.op !== 1).length;
+        out.push(`@@ -${range(first.old, oldCount)} +${range(first.new, newCount)} @@`);
+        for (const row of slice) {
+            const noEol = row.text.endsWith(NO_EOL);
+            const text = noEol ? row.text.slice(0, -NO_EOL.length) : row.text;
+            out.push(`${row.op === 0 ? " " : row.op === 1 ? "-" : "+"}${text}`);
+            if (noEol)
+                out.push("\");
+        }
+    }
+    return out.join("\n");
+}
+/** Cuts `text` at a line boundary so it fits in `maxBytes` (UTF-8). */
+export function clipLines(text, maxBytes) {
+    if (Buffer.byteLength(text) <= maxBytes)
+        return { text, clipped: false };
+    let cut = Buffer.from(text).subarray(0, maxBytes).toString("utf8");
+    // A split multi-byte character decodes to U+FFFD; drop the partial last line either way.
+    const newline = cut.lastIndexOf("\n");
+    cut = newline > 0 ? cut.slice(0, newline) : cut.replace(/�$/, "");
+    return { text: cut, clipped: true };
+}

package/dist/runtime/ids.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A ULID (26 characters, lexicographically sortable by creation time): 48 bits of milliseconds
+ * and 80 random bits. No dependency and no monotonic counter; two ids created in the same
+ * millisecond sort arbitrarily, which is fine for row ids and folder names.
+ */
+export declare function ulid(now?: number): string;
+/** A prefixed id such as `art_01J…` or `exec_01J…`. */
+export declare const newId: (prefix: string, now?: number) => string;

package/dist/runtime/ids.js

@@ -0,0 +1,32 @@
+import { randomBytes } from "node:crypto";
+/** Crockford base32 (no I, L, O, U), the ULID alphabet. */
+const ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
+/**
+ * A ULID (26 characters, lexicographically sortable by creation time): 48 bits of milliseconds
+ * and 80 random bits. No dependency and no monotonic counter; two ids created in the same
+ * millisecond sort arbitrarily, which is fine for row ids and folder names.
+ */
+export function ulid(now = Date.now()) {
+    let time = "";
+    let t = Math.max(0, Math.floor(now));
+    for (let i = 0; i < 10; i++) {
+        time = ALPHABET[t % 32] + time;
+        t = Math.floor(t / 32);
+    }
+    const bytes = randomBytes(10);
+    let random = "";
+    // 80 bits → 16 characters of 5 bits each.
+    let buffer = 0, bits = 0;
+    for (const byte of bytes) {
+        buffer = (buffer << 8) | byte;
+        bits += 8;
+        while (bits >= 5) {
+            bits -= 5;
+            random += ALPHABET[(buffer >> bits) & 31];
+        }
+        buffer &= (1 << bits) - 1;
+    }
+    return time + random;
+}
+/** A prefixed id such as `art_01J…` or `exec_01J…`. */
+export const newId = (prefix, now) => `${prefix}_${ulid(now)}`;

package/dist/runtime/paths.d.ts

@@ -1,4 +1,15 @@
 export declare function inside(root: string, path: string): boolean;
+/**
+ * Actionable message for a path that no allowed root covers. It always names the resolved target
+ * and both remedies (the one-run flag and the persistent configuration key) instead of the old
+ * opaque "Path outside workspace".
+ */
+export declare function outsideRootsMessage(target: string, reason?: string): string;
 /** Mediated path policy; not an OS sandbox and not race-proof against hostile concurrent processes. */
 export declare function safePath(root: string, path: string): Promise<string>;
 export declare function findWorkspace(cwd: string): Promise<string>;
+/**
+ * Opaque, stable key of a workspace path: the first 16 hex characters of its sha256. Core names
+ * per-workspace folders with it and the server exposes it as the web `workspaceId`.
+ */
+export declare const workspaceKey: (path: string) => string;

package/dist/runtime/paths.js

@@ -1,14 +1,25 @@
+import { createHash } from "node:crypto";
 import { lstat, realpath } from "node:fs/promises";
 import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 export function inside(root, path) {
     const r = relative(root, path);
     return r === "" || (!r.startsWith(`..${sep}`) && r !== ".." && !isAbsolute(r));
 }
+/**
+ * Actionable message for a path that no allowed root covers. It always names the resolved target
+ * and both remedies (the one-run flag and the persistent configuration key) instead of the old
+ * opaque "Path outside workspace".
+ */
+export function outsideRootsMessage(target, reason) {
+    return (`Path outside the workspace: ${target}${reason ? ` (${reason})` : ""}. ` +
+        "Allow its directory for one run with `--add-dir <directory>`, add it to the " +
+        "`additionalDirectories` configuration key, or approve it interactively in the TUI.");
+}
 /** Mediated path policy; not an OS sandbox and not race-proof against hostile concurrent processes. */
 export async function safePath(root, path) {
     const canonical = await realpath(root), target = resolve(canonical, path);
     if (!inside(canonical, target))
-        throw new Error("Path outside workspace");
+        throw new Error(outsideRootsMessage(target));
     let cursor = canonical;
     for (const part of relative(canonical, target).split(sep).filter(Boolean)) {
         cursor = resolve(cursor, part);
@@ -40,3 +51,8 @@ export async function findWorkspace(cwd) {
         path = dirname(path);
     }
 }
+/**
+ * Opaque, stable key of a workspace path: the first 16 hex characters of its sha256. Core names
+ * per-workspace folders with it and the server exposes it as the web `workspaceId`.
+ */
+export const workspaceKey = (path) => createHash("sha256").update(path).digest("hex").slice(0, 16);