@archmax-ai/harness 0.0.0

package/dist/core/workspace-context.js.map

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

package/dist/core/workspace-prompt.d.ts

@@ -0,0 +1,7 @@
+import { type MountPrefixes } from "./zones.js";
+/**
+ * Render the "Workspace zones" section of the system prompt for one assembly's
+ * resolved mounts. Every name it prints is a route the workspace actually
+ * serves; a workspace with no mounts simply gets no mount bullets.
+ */
+export declare function renderWorkspaceZones(mounts?: MountPrefixes): string;

package/dist/core/workspace-prompt.js

@@ -0,0 +1,102 @@
+import { NO_MOUNTS, SESSION_OFFLOAD_DIRS, SESSION_OPEN_DIR, } from "./zones.js";
+/**
+ * The system prompt's account of the workspace, **rendered from the assembly's
+ * resolved mount table** rather than written by hand.
+ *
+ * The same reason the graph section is rendered from the loaded spec: prose about
+ * enforcement drifts from enforcement. A hand-maintained list of mounts in the
+ * platform prompt has to be edited every time a consumer's mount table changes,
+ * and when it is not, the agent is told it has directories that do not exist —
+ * it then reads a missing path while faithfully quoting its own instructions.
+ * Deriving the list from {@link MountPrefixes} (the very keys the composite
+ * routes on and the kernel classifies against) makes that unrepresentable.
+ *
+ * Consumer-declared mounts are the workspace's shape, so a custom platform prompt
+ * inherits an accurate description without restating one.
+ */
+/**
+ * Mount names as the agent addresses them: directories with a trailing slash,
+ * file mounts by their exact path, each in backticks and alphabetically ordered
+ * so the rendered prompt is stable across assemblies of the same table.
+ *
+ * Dot-prefixed mounts are omitted: `.platform/` and its kind carry the runtime's
+ * own inputs (the platform prompt the agent is already reading), not authored
+ * content it should go looking through.
+ *
+ * **Governed** mounts are omitted too, and for a load-bearing reason: which of
+ * them a state reaches varies, and this section is part of the cacheable prefix,
+ * which does not. They are disclosed where they apply, in the volatile "Current
+ * state" block (see `renderMountsSection`).
+ */
+function mountNames(mounts, writable) {
+    const isWritable = (name) => mounts.writable.includes(name);
+    const pick = (names) => names.filter((name) => !name.startsWith(".") &&
+        !mounts.governed.includes(name) &&
+        isWritable(name) === writable).sort();
+    const entry = (name, label) => ({
+        label,
+        // Only a directory mount is ever unsearchable (`resolveMounts` lists no file).
+        browseOnly: mounts.unsearchable.includes(name),
+    });
+    return [
+        ...pick(mounts.dirs).map((name) => entry(name, `\`${name}/\``)),
+        ...pick(mounts.files).map((name) => entry(name, `\`${name}\``)),
+    ];
+}
+/**
+ * Render the "Workspace zones" section of the system prompt for one assembly's
+ * resolved mounts. Every name it prints is a route the workspace actually
+ * serves; a workspace with no mounts simply gets no mount bullets.
+ */
+export function renderWorkspaceZones(mounts = NO_MOUNTS) {
+    const offload = SESSION_OFFLOAD_DIRS.map((dir) => `\`${dir}/\``).join(", ");
+    const readOnly = mountNames(mounts, false);
+    const writable = mountNames(mounts, true);
+    const bullets = [
+        `- **\`${SESSION_OPEN_DIR}/\`** — your working area: intermediate files and the ` +
+            `artifacts you produce. Always readable and writable, whatever state you are in.`,
+        `- **${offload}** — where the runtime parks oversized tool results and ` +
+            `history. Read them when handed a path (paginate with \`read_file\` offset/limit); ` +
+            `you cannot write there.`,
+    ];
+    if (readOnly.length + writable.length > 0) {
+        // One bullet per mount, each with its posture, rather than two prose groups:
+        // the agent addresses a mount by name, so the name is what must carry whether
+        // it can be written. Same vocabulary as the volatile per-state listing.
+        const notes = [];
+        if (readOnly.length > 0) {
+            notes.push("A `read-only` mount refuses writes; read it freely.");
+        }
+        if (writable.length > 0) {
+            notes.push(`A \`read/write\` mount is as open to you as \`${SESSION_OPEN_DIR}/\`: write there when ` +
+                `the work belongs outside this run, and the write is checked against the active ` +
+                `state's tool rules like any other. It outlives the run, so keep scratch files out.`);
+        }
+        if ([...readOnly, ...writable].some((m) => m.browseOnly)) {
+            notes.push("A `browse only` mount is listed and read, never searched: a search from the root " +
+                "leaves it out, and a search addressed at it is answered by the mount itself.");
+        }
+        const line = (posture) => (m) => `  - **${m.label}** — ${posture}${m.browseOnly ? ", browse only" : ""}`;
+        bullets.push(`- **Mounts** — authored content beside the run, each marked with what you may do there:`, ...readOnly.map(line("read-only")), ...writable.map(line("read/write")), 
+        // Indented, so it reads as the rest of the bullet rather than a new one.
+        `  ${notes.join(" ")}`);
+    }
+    bullets.push(`- **Any other path in the root** belongs to this run and is governed by the ` +
+        `active state's tool rules: write one only where the state's spec allows it.`);
+    if (mounts.governed.length > 0) {
+        // Named nowhere here on purpose: which of them this state reaches is in the
+        // volatile block, so this prefix stays byte-identical across states.
+        bullets.push(`- **Some mounts are given per state.** The ones available where you are now are ` +
+            `listed under "Mounts available in this state" in the "Current state" block; a path ` +
+            `under any other is blocked here.`);
+    }
+    return [
+        "## Workspace zones",
+        "",
+        "Your workspace root **is this run** — writable and private to it. Authored",
+        "content is mounted beside it, read-only unless a mount below says otherwise.",
+        "",
+        ...bullets,
+    ].join("\n");
+}
+//# sourceMappingURL=workspace-prompt.js.map

package/dist/core/workspace-prompt.js.map

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

package/dist/core/workspace-router.d.ts

@@ -0,0 +1,61 @@
+import type { BackendProtocolV2, CompositeBackend } from "deepagents";
+import { classifyWorkspacePath } from "./zones.js";
+import type { MountPrefixes } from "./mounts.js";
+/**
+ * The workspace's single entry point, wrapping the mount-routing
+ * {@link CompositeBackend}. It owns the three things prefix routing cannot do
+ * on its own:
+ *
+ *  1. **Canonicalization.** `CompositeBackend` routes by literal prefix, but
+ *     the workspace convention — agent tool calls, generated lifecycle scripts,
+ *     the runtime's own `./skills/` discovery glob, documented authoring style —
+ *     uses relative and dot-prefixed paths. Without canonicalizing first,
+ *     `./skills/x` misses the `/skills/` mount and silently falls through to
+ *     the run root: reads report the file missing and writes land in run state.
+ *  2. **File mounts.** A mount key without a trailing slash (`/AGENTS.md`) names
+ *     one file, which a route prefix cannot express: prefix matching is
+ *     `startsWith`, so `/AGENTS.md` would also capture `/AGENTS.md.bak`, and the
+ *     stripped key would collapse to `/`.
+ *  3. **Agent-visible root shaping.** While a session is bound, a listing of `/`
+ *     shows exactly the namespace the agent may address: authored mounts and
+ *     authored root files plus the agent-addressable run areas, with the
+ *     runtime-internal areas omitted. Listings outside a bound session (e.g.
+ *     enumerating session folders for `runs.list()`) are returned untouched.
+ *  4. **Search posture.** A root-wide `grep`/`glob` fans out to every route and
+ *     one route's `{ error }` is fatal to it, and the composite hands a route
+ *     `/` whether the search was addressed at the mount or fanned out. A mount
+ *     declared `searchable: false` is therefore absent from the composite that
+ *     serves searches, and a search addressed at it (the mount or a path inside
+ *     it) is delegated to its route directly, so the backend's own answer —
+ *     matches or refusal — reaches the caller verbatim.
+ */
+export interface WorkspaceRouterOptions {
+    /** Mount-routing backend: session zone as default route, authored zone mounted. */
+    composite: CompositeBackend;
+    /**
+     * The composite `grep`/`glob` fan out through: the same default route and the
+     * searchable directory routes only. Defaults to `composite`, which is exact
+     * when no mount is unsearchable.
+     */
+    searchComposite?: CompositeBackend;
+    /**
+     * Unsearchable directory mounts by mount name → the very route object the
+     * composite would have called, so an addressed search keeps the route's
+     * read-only wrapping and prefix-aware refusals. Default: none.
+     */
+    unsearchableRoutes?: ReadonlyMap<string, BackendProtocolV2>;
+    /** Exact-path file mounts, by mount name (e.g. `AGENTS.md` → its backend). */
+    fileMounts: Map<string, BackendProtocolV2>;
+    /** This workspace's resolved mount keys, for root-listing shaping. */
+    mountPrefixes: MountPrefixes;
+    /** The session id bound to the current async context, if any. */
+    boundSessionId: () => string | undefined;
+}
+/** Thrown when a workspace path resolves above the workspace root. */
+export declare class WorkspacePathEscapeError extends Error {
+    readonly path: string;
+    constructor(path: string);
+}
+export declare function createWorkspaceRouter(options: WorkspaceRouterOptions): BackendProtocolV2;
+/** Re-exported so callers can classify a path with the router's own rules. */
+export { classifyWorkspacePath };

package/dist/core/workspace-router.js

@@ -0,0 +1,145 @@
+import { canonicalizeRelPath } from "./workspace.js";
+import { SESSION_INTERNAL_DIRS, classifyWorkspacePath, mountNameOf } from "./zones.js";
+/** Thrown when a workspace path resolves above the workspace root. */
+export class WorkspacePathEscapeError extends Error {
+    path;
+    constructor(path) {
+        super(`Path ${JSON.stringify(path)} resolves outside the workspace root; ` +
+            `workspace paths may not traverse above it.`);
+        this.path = path;
+        this.name = "WorkspacePathEscapeError";
+    }
+}
+const INTERNAL_DIR_SET = new Set(SESSION_INTERNAL_DIRS);
+/** Canonical, leading-slash form of a workspace path. Throws on escapes. */
+function canonical(path) {
+    const { path: rel, escapes } = canonicalizeRelPath(path);
+    if (escapes)
+        throw new WorkspacePathEscapeError(path);
+    return `/${rel}`;
+}
+/** Directory-entry name of a `FileInfo` path (trailing slash tolerated). */
+function entryName(path) {
+    return canonicalizeRelPath(path).path.split("/")[0] ?? "";
+}
+export function createWorkspaceRouter(options) {
+    const { composite, fileMounts, mountPrefixes, boundSessionId } = options;
+    const searchComposite = options.searchComposite ?? composite;
+    const unsearchableRoutes = options.unsearchableRoutes ?? new Map();
+    /** The file mount serving `path` exactly, or `null` for normal routing. */
+    const fileMount = (path) => {
+        const rel = canonical(path).slice(1);
+        const backend = fileMounts.get(rel);
+        return backend ? { backend, key: `/${rel}` } : null;
+    };
+    /**
+     * The unsearchable mount a search at `target` is addressed at, with the
+     * route-relative path the composite would have handed its route, or `null`
+     * when the search belongs to the fan-out composite. The routing mount is the
+     * longest-prefix match across every mount, so a searchable mount nested in an
+     * unsearchable one (or the reverse) is still routed to its own backend.
+     */
+    const addressedUnsearchable = (target) => {
+        const name = mountNameOf(target.slice(1), mountPrefixes);
+        const backend = name === null ? undefined : unsearchableRoutes.get(name);
+        if (!name || !backend)
+            return null;
+        // The composite's own formula: strip the route prefix, keep the leading
+        // slash, and the mount itself becomes `/`.
+        return { backend, name, routePath: target.slice(name.length + 1) || "/" };
+    };
+    /** Hide runtime-internal areas and surface file mounts at `/`. */
+    const shapeRoot = async (path, files) => {
+        if (path !== "/" || !boundSessionId())
+            return files;
+        const visible = files.filter((file) => !INTERNAL_DIR_SET.has(entryName(file.path)));
+        const present = new Set(visible.map((file) => canonicalizeRelPath(file.path).path));
+        for (const name of mountPrefixes.files) {
+            if (present.has(name))
+                continue;
+            const mounted = fileMounts.get(name);
+            if (!mounted)
+                continue;
+            const res = await mounted.readRaw(`/${name}`);
+            if (!res.error && res.data)
+                visible.push({ path: `/${name}`, is_dir: false });
+        }
+        return visible.sort((a, b) => a.path.localeCompare(b.path));
+    };
+    const router = {
+        // Preserve the CompositeBackend duck-type (`routePrefixes`) so Deep Agents
+        // components that detect mount-routing backends still recognize this one.
+        get routePrefixes() {
+            return composite.routePrefixes;
+        },
+        async ls(path) {
+            const target = canonical(path);
+            const file = fileMount(target);
+            const res = file ? await file.backend.ls(file.key) : await composite.ls(target);
+            if (res.error || !res.files)
+                return res;
+            return { ...res, files: await shapeRoot(target, res.files) };
+        },
+        read(filePath, offset, limit) {
+            const target = canonical(filePath);
+            const file = fileMount(target);
+            return file
+                ? file.backend.read(file.key, offset, limit)
+                : composite.read(target, offset, limit);
+        },
+        readRaw(filePath) {
+            const target = canonical(filePath);
+            const file = fileMount(target);
+            return file ? file.backend.readRaw(file.key) : composite.readRaw(target);
+        },
+        async grep(pattern, path, glob) {
+            if (path == null)
+                return searchComposite.grep(pattern, path, glob);
+            const target = canonical(path);
+            const direct = addressedUnsearchable(target);
+            if (!direct)
+                return searchComposite.grep(pattern, target, glob);
+            const res = await direct.backend.grep(pattern, direct.routePath, glob);
+            if (res.error)
+                return res;
+            // Re-apply the route prefix as the composite does for its own routes.
+            return {
+                ...res,
+                matches: (res.matches ?? []).map((m) => ({ ...m, path: `/${direct.name}${m.path}` })),
+            };
+        },
+        async glob(pattern, path) {
+            if (path === undefined)
+                return searchComposite.glob(pattern, path);
+            const target = canonical(path);
+            const direct = addressedUnsearchable(target);
+            if (!direct)
+                return searchComposite.glob(pattern, target);
+            const res = await direct.backend.glob(pattern, direct.routePath);
+            if (res.error)
+                return res;
+            return {
+                ...res,
+                files: (res.files ?? []).map((f) => ({ ...f, path: `/${direct.name}${f.path}` })),
+            };
+        },
+        write(filePath, content) {
+            const target = canonical(filePath);
+            // Route the write to the file mount so its own read-only semantics answer,
+            // rather than creating a run-state shadow copy at the same path.
+            const file = fileMount(target);
+            return file ? file.backend.write(file.key, content) : composite.write(target, content);
+        },
+        edit(filePath, oldString, newString, replaceAll) {
+            const target = canonical(filePath);
+            const file = fileMount(target);
+            return file
+                ? file.backend.edit(file.key, oldString, newString, replaceAll)
+                : composite.edit(target, oldString, newString, replaceAll);
+        },
+    };
+    return router;
+}
+/** Re-exported so callers can classify a path with the router's own rules. */
+export { classifyWorkspacePath };
+//# sourceMappingURL=workspace-router.js.map

package/dist/core/workspace-router.js.map

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

package/dist/core/workspace.d.ts

@@ -0,0 +1,85 @@
+import type { BackendProtocolV2, FileData, FileInfo } from "deepagents";
+/**
+ * Single file-access layer for the runtime.
+ *
+ * Every read of a file in the agent workspace — machine config, system prompt,
+ * hook scripts, `archmax_run` sources, lifecycle artifacts — flows
+ * through here so it is served by the configured LangChain Deep Agents
+ * {@link BackendProtocolV2}. Swap the backend (filesystem, store, sandbox,
+ * remote) and the whole runtime follows, with no direct `fs` coupling.
+ * Deletion — the one operation the backend protocol does not model — is owned
+ * by the session store (`SessionStore.deleteSession`), not this layer.
+ */
+export declare class Workspace {
+    private readonly backend;
+    constructor(backend: BackendProtocolV2);
+    readText(path: string): Promise<string | null>;
+    /**
+     * Write text to a workspace file through the backend. Parent directories are
+     * created by the backend. Throws if the backend reports a write error.
+     */
+    writeText(path: string, contents: string): Promise<void>;
+    /** Write a value as pretty-printed JSON through {@link writeText}. */
+    writeJson(path: string, value: unknown): Promise<void>;
+    /**
+     * Replace `oldString` with `newString` in an existing workspace file through
+     * the backend's `edit` operation. Used to update an already-written file (e.g.
+     * an approval request's frontmatter on decision) on a create-only backend, which
+     * refuses to overwrite. Throws if the backend reports an error.
+     */
+    editText(path: string, oldString: string, newString: string, replaceAll?: boolean): Promise<void>;
+    /** Backends throw on e.g. path traversal; treat any failure as "absent". */
+    private tryReadRaw;
+    readJson<T = unknown>(path: string): Promise<T | null>;
+    exists(path: string): Promise<boolean>;
+    /**
+     * Immediate children of a directory as {@link FileInfo} entries. A missing
+     * directory and an unreadable one both read as empty — which is what most
+     * callers want, and is wrong for anything replaying durable state: see
+     * {@link listDirStrict}.
+     */
+    listDir(path: string): Promise<FileInfo[]>;
+    /**
+     * {@link listDir}, but a backend that failed to answer throws instead of
+     * reading as an empty directory. For a caller that replays durable state, the
+     * difference is everything: a transient read error must not be indistinguishable
+     * from a session with no checkpoints, or the session silently forks (issue #27).
+     *
+     * A directory the backend reports as absent is still empty, not an error — a
+     * session's first turn has no `checkpoints/` folder yet.
+     */
+    listDirStrict(path: string): Promise<FileInfo[]>;
+    /**
+     * {@link readJson}, but distinguishes the three outcomes a durable replay has
+     * to tell apart: the file is absent (`null`), or it is there and unreadable —
+     * an unparseable or unfetchable checkpoint throws rather than being skipped.
+     */
+    readJsonStrict<T = unknown>(path: string): Promise<T | null>;
+}
+/** Strip leading slashes to get a workspace-relative path. */
+export declare function normalizeRelPath(p: string): string;
+/** A canonicalized workspace-relative path plus whether it escapes the root. */
+export interface CanonicalRelPath {
+    /** The resolved relative path: `//` and `.` collapsed, `..` applied. */
+    path: string;
+    /** True when a `..` segment climbs above the workspace root. */
+    escapes: boolean;
+}
+/**
+ * Canonicalize a workspace-relative path to the single form the backend will
+ * resolve to: strip leading slashes, drop `.` and empty (`//`) segments, and
+ * apply `..` against the accumulated path. A `..` that would climb above the
+ * root is preserved as a leading `..` and flags `escapes`.
+ *
+ * Every path-governance decision (read-only zone, `forbid_paths`, scratchpad,
+ * `scratchpad/`) canonicalizes through here so none can be dodged with a
+ * `./`, `.//`, or `..` prefix: all three mechanisms see the same path the
+ * backend will act on.
+ */
+export declare function canonicalizeRelPath(p: string): CanonicalRelPath;
+/** Convert a relative or virtual path to the leading-slash form backends expect. */
+export declare function toBackendPath(p: string): string;
+/** Workspace-relative basename of a (possibly trailing-slash) directory path. */
+export declare function dirName(path: string): string;
+/** Decode {@link FileData} (v1 line array, v2 string, or binary) to text. */
+export declare function fileDataToText(data: FileData): string | null;

package/dist/core/workspace.js

@@ -0,0 +1,193 @@
+/**
+ * Single file-access layer for the runtime.
+ *
+ * Every read of a file in the agent workspace — machine config, system prompt,
+ * hook scripts, `archmax_run` sources, lifecycle artifacts — flows
+ * through here so it is served by the configured LangChain Deep Agents
+ * {@link BackendProtocolV2}. Swap the backend (filesystem, store, sandbox,
+ * remote) and the whole runtime follows, with no direct `fs` coupling.
+ * Deletion — the one operation the backend protocol does not model — is owned
+ * by the session store (`SessionStore.deleteSession`), not this layer.
+ */
+export class Workspace {
+    backend;
+    constructor(backend) {
+        this.backend = backend;
+    }
+    async readText(path) {
+        const res = await this.tryReadRaw(path);
+        if (!res || res.error || !res.data)
+            return null;
+        return fileDataToText(res.data);
+    }
+    /**
+     * Write text to a workspace file through the backend. Parent directories are
+     * created by the backend. Throws if the backend reports a write error.
+     */
+    async writeText(path, contents) {
+        const res = await this.backend.write(toBackendPath(path), contents);
+        const error = res?.error;
+        if (error)
+            throw new Error(error);
+    }
+    /** Write a value as pretty-printed JSON through {@link writeText}. */
+    async writeJson(path, value) {
+        await this.writeText(path, `${JSON.stringify(value, null, 2)}\n`);
+    }
+    /**
+     * Replace `oldString` with `newString` in an existing workspace file through
+     * the backend's `edit` operation. Used to update an already-written file (e.g.
+     * an approval request's frontmatter on decision) on a create-only backend, which
+     * refuses to overwrite. Throws if the backend reports an error.
+     */
+    async editText(path, oldString, newString, replaceAll = false) {
+        const res = await this.backend.edit(toBackendPath(path), oldString, newString, replaceAll);
+        const error = res?.error;
+        if (error)
+            throw new Error(error);
+    }
+    /** Backends throw on e.g. path traversal; treat any failure as "absent". */
+    async tryReadRaw(path) {
+        try {
+            return await this.backend.readRaw(toBackendPath(path));
+        }
+        catch {
+            return null;
+        }
+    }
+    async readJson(path) {
+        const text = await this.readText(path);
+        if (text == null)
+            return null;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            return null;
+        }
+    }
+    async exists(path) {
+        const res = await this.tryReadRaw(path);
+        return res != null && !res.error && res.data != null;
+    }
+    /**
+     * Immediate children of a directory as {@link FileInfo} entries. A missing
+     * directory and an unreadable one both read as empty — which is what most
+     * callers want, and is wrong for anything replaying durable state: see
+     * {@link listDirStrict}.
+     */
+    async listDir(path) {
+        try {
+            const res = await this.backend.ls(toBackendPath(path));
+            return res.error || !res.files ? [] : res.files;
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * {@link listDir}, but a backend that failed to answer throws instead of
+     * reading as an empty directory. For a caller that replays durable state, the
+     * difference is everything: a transient read error must not be indistinguishable
+     * from a session with no checkpoints, or the session silently forks (issue #27).
+     *
+     * A directory the backend reports as absent is still empty, not an error — a
+     * session's first turn has no `checkpoints/` folder yet.
+     */
+    async listDirStrict(path) {
+        const res = await this.backend.ls(toBackendPath(path));
+        if (res.error) {
+            if (isAbsentError(res.error))
+                return [];
+            throw new Error(`cannot list '${path}': ${res.error}`);
+        }
+        return res.files ?? [];
+    }
+    /**
+     * {@link readJson}, but distinguishes the three outcomes a durable replay has
+     * to tell apart: the file is absent (`null`), or it is there and unreadable —
+     * an unparseable or unfetchable checkpoint throws rather than being skipped.
+     */
+    async readJsonStrict(path) {
+        const res = await this.backend.readRaw(toBackendPath(path));
+        if (res.error) {
+            if (isAbsentError(res.error))
+                return null;
+            throw new Error(`cannot read '${path}': ${res.error}`);
+        }
+        if (!res.data)
+            return null;
+        const text = fileDataToText(res.data);
+        if (text == null)
+            throw new Error(`cannot read '${path}': its content is not decodable text`);
+        try {
+            return JSON.parse(text);
+        }
+        catch (err) {
+            throw new Error(`cannot parse '${path}' as JSON: ${err.message}`, { cause: err });
+        }
+    }
+}
+/**
+ * Whether a backend error says the path does not exist, as opposed to saying it
+ * could not be read. Backends phrase this themselves, so the test is on the
+ * wording every one of them uses.
+ */
+function isAbsentError(error) {
+    return /not found|no such file|does not exist|missing|enoent/i.test(error);
+}
+/** Strip leading slashes to get a workspace-relative path. */
+export function normalizeRelPath(p) {
+    return String(p).replace(/^\/+/, "");
+}
+/**
+ * Canonicalize a workspace-relative path to the single form the backend will
+ * resolve to: strip leading slashes, drop `.` and empty (`//`) segments, and
+ * apply `..` against the accumulated path. A `..` that would climb above the
+ * root is preserved as a leading `..` and flags `escapes`.
+ *
+ * Every path-governance decision (read-only zone, `forbid_paths`, scratchpad,
+ * `scratchpad/`) canonicalizes through here so none can be dodged with a
+ * `./`, `.//`, or `..` prefix: all three mechanisms see the same path the
+ * backend will act on.
+ */
+export function canonicalizeRelPath(p) {
+    const out = [];
+    let escapes = false;
+    for (const seg of normalizeRelPath(String(p)).split("/")) {
+        if (seg === "" || seg === ".")
+            continue;
+        if (seg === "..") {
+            if (out.length > 0 && out[out.length - 1] !== "..") {
+                out.pop();
+            }
+            else {
+                out.push("..");
+                escapes = true;
+            }
+            continue;
+        }
+        out.push(seg);
+    }
+    return { path: out.join("/"), escapes };
+}
+/** Convert a relative or virtual path to the leading-slash form backends expect. */
+export function toBackendPath(p) {
+    return `/${normalizeRelPath(p)}`;
+}
+/** Workspace-relative basename of a (possibly trailing-slash) directory path. */
+export function dirName(path) {
+    return normalizeRelPath(path).replace(/\/+$/, "").split("/").pop() ?? "";
+}
+/** Decode {@link FileData} (v1 line array, v2 string, or binary) to text. */
+export function fileDataToText(data) {
+    const content = data.content;
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content))
+        return content.join("\n");
+    if (content instanceof Uint8Array)
+        return new TextDecoder().decode(content);
+    return null;
+}
+//# sourceMappingURL=workspace.js.map

package/dist/core/workspace.js.map

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