@archmax-ai/harness 0.0.0

package/dist/core/mount-prompt.js

@@ -0,0 +1,55 @@
+/**
+ * The model-facing account of the governed mounts a state may reach — the mount
+ * twin of `renderSkillsSection`, and in the **volatile** system block for the
+ * same reason: what varies with the state cannot live in the cacheable prefix.
+ *
+ * The static "Workspace zones" section therefore names ungoverned mounts only
+ * (see {@link renderWorkspaceZones}), and this names what this state was given.
+ * A state that reaches none gets no heading rather than an empty one, and
+ * therefore no invitation to go looking.
+ */
+/** Heading of the rendered section, also the marker tests assert on. */
+export const MOUNTS_SECTION_HEADING = "Mounts available in this state";
+/**
+ * Render the section for one state's enabled governed mounts, or `null` when the
+ * set is empty.
+ *
+ * `enabled` is the resolved name order (see `WorkflowMachine.enabledMounts`),
+ * sorted here so the text is stable under a spec edit that only reorders a
+ * list — a prompt section that reordered itself would churn the transcript for
+ * no reason. Each name is printed as the agent addresses it: a directory mount
+ * with a trailing slash, a file mount by its exact path, read-only or read/write
+ * per `writable` — the state's own posture (`WorkflowMachine.mountWritable`),
+ * which a grant's `access: read` may have narrowed below the host's. A mount the
+ * host declared unsearchable gets a browse-only note, so the model lists and
+ * reads it rather than searching it; every other line is unchanged.
+ */
+export function renderMountsSection(enabled, mounts, writable) {
+    const files = new Set(mounts.files);
+    const bullets = [...enabled].sort().map((name) => {
+        const address = files.has(name) ? name : `${name}/`;
+        // The state's own posture, not the table's: a grant may narrow a writable
+        // mount to reads here, and the prompt has to say what this state can do.
+        const posture = writable(name)
+            ? "read/write — write there directly when the work belongs there, no less " +
+                "freely than in your own working area; the write is checked against this " +
+                "state's tool rules like any other"
+            : "read-only — read it freely, writes there are blocked";
+        const browse = mounts.unsearchable.includes(name)
+            ? " Browse only: list and read it directly. Searches from the root leave it out, " +
+                "and a search addressed at it is answered by the mount itself."
+            : "";
+        return `- **\`${address}\`** — ${posture}.${browse}`;
+    });
+    if (bullets.length === 0)
+        return null;
+    return [
+        `## ${MOUNTS_SECTION_HEADING}`,
+        "",
+        ...bullets,
+        "",
+        `Only these mounts are reachable from this state: every other mount's files are blocked ` +
+            `here, whatever an earlier state could read.`,
+    ].join("\n");
+}
+//# sourceMappingURL=mount-prompt.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"mount-prompt.js","sourceRoot":"","sources":["../../src/core/mount-prompt.ts"],"names":[],"mappings":"AAEA;;;;;;;;;GASG;AAEH,wEAAwE;AACxE,MAAM,CAAC,MAAM,sBAAsB,GAAG,gCAAgC,CAAC;AAEvE;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,mBAAmB,CACjC,OAA0B,EAC1B,MAAqB,EACrB,QAAmC;IAEnC,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC/C,MAAM,OAAO,GAAG,KAAK,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,GAAG,CAAC;QACpD,0EAA0E;QAC1E,yEAAyE;QACzE,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC;YAC5B,CAAC,CAAC,yEAAyE;gBACzE,0EAA0E;gBAC1E,mCAAmC;YACrC,CAAC,CAAC,sDAAsD,CAAC;QAC3D,MAAM,MAAM,GAAG,MAAM,CAAC,YAAY,CAAC,QAAQ,CAAC,IAAI,CAAC;YAC/C,CAAC,CAAC,gFAAgF;gBAChF,+DAA+D;YACjE,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,SAAS,OAAO,UAAU,OAAO,IAAI,MAAM,EAAE,CAAC;IACvD,CAAC,CAAC,CAAC;IACH,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO;QACL,MAAM,sBAAsB,EAAE;QAC9B,EAAE;QACF,GAAG,OAAO;QACV,EAAE;QACF,yFAAyF;YACvF,6CAA6C;KAChD,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC"}

package/dist/core/mount-redact.d.ts

@@ -0,0 +1,28 @@
+import { type MountPrefixes } from "./zones.js";
+/**
+ * Keep a mount the state cannot reach out of a *listing* — the mounts half of
+ * the shared listing filter (`core/listing-redact.ts`, which carries the
+ * reasoning and the line shapes), and the twin of `redactDisabledSkills`.
+ *
+ * The workspace root listing is the case that matters most: a governed mount the
+ * state does not have would otherwise appear at the root as a directory the
+ * agent then cannot read, which reads to a model as a broken workspace rather
+ * than as a capability it was not given.
+ */
+/** What a state may see of the mount table: the kernel's decision, as data. */
+export interface MountVisibility {
+    /** The **governed** mounts this state enables (`WorkflowMachine.enabledMounts`). */
+    readonly enabled: readonly string[];
+    /** Every mount name denied here, governed or not (`forbiddenMounts`). */
+    readonly forbidden: readonly string[];
+}
+/**
+ * Drop from `text` every line under a mount this state cannot see: a governed
+ * mount no list enabled, or any mount a `forbid` names. A path under no mount,
+ * and a path under an ungoverned mount nothing denies, is kept — that mount is
+ * visible in every state.
+ *
+ * Returns the text unchanged when nothing was hidden, so a result the filter has
+ * no opinion about is passed through by identity rather than rebuilt.
+ */
+export declare function redactHiddenMounts(text: string, visibility: MountVisibility, mounts: MountPrefixes): string;

package/dist/core/mount-redact.js

@@ -0,0 +1,32 @@
+import { redactListing } from "./listing-redact.js";
+import { mountNameOf } from "./zones.js";
+/**
+ * Drop from `text` every line under a mount this state cannot see: a governed
+ * mount no list enabled, or any mount a `forbid` names. A path under no mount,
+ * and a path under an ungoverned mount nothing denies, is kept — that mount is
+ * visible in every state.
+ *
+ * Returns the text unchanged when nothing was hidden, so a result the filter has
+ * no opinion about is passed through by identity rather than rebuilt.
+ */
+export function redactHiddenMounts(text, visibility, mounts) {
+    if (!text)
+        return text;
+    const enabled = new Set(visibility.enabled);
+    const forbidden = new Set(visibility.forbidden);
+    const hidden = (name) => forbidden.has(name) || (mounts.governed.includes(name) && !enabled.has(name));
+    // Nothing to hide: every mount the table serves is reachable from here.
+    const names = [...mounts.dirs, ...mounts.files];
+    if (!names.some(hidden))
+        return text;
+    return redactListing(text, (path) => mountNameOf(canonical(path), mounts), hidden);
+}
+/**
+ * A result line's path in the form `mountNameOf` classifies: leading slashes
+ * stripped, the shape the tools print (`/catalogs/eu/skus.csv`) reduced to the
+ * shape the mount table holds.
+ */
+function canonical(path) {
+    return path.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+//# sourceMappingURL=mount-redact.js.map

package/dist/core/mount-redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mount-redact.js","sourceRoot":"","sources":["../../src/core/mount-redact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,WAAW,EAAsB,MAAM,YAAY,CAAC;AAqB7D;;;;;;;;GAQG;AACH,MAAM,UAAU,kBAAkB,CAChC,IAAY,EACZ,UAA2B,EAC3B,MAAqB;IAErB,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IAChD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAC9B,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;IAChF,wEAAwE;IACxE,MAAM,KAAK,GAAG,CAAC,GAAG,MAAM,CAAC,IAAI,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;IAChD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACrC,OAAO,aAAa,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;AACrF,CAAC;AAED;;;;GAIG;AACH,SAAS,SAAS,CAAC,IAAY;IAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AACtD,CAAC"}

package/dist/core/mounts.d.ts

@@ -0,0 +1,88 @@
+import { type BackendProtocolV2 } from "deepagents";
+import { AUTHORING_PREFIXES, authoringPlanePrefix, describeAuthoringPrefix, isAuthoringPrefix, NO_MOUNTS, type AuthoringPrefix, type MountPrefixes } from "./zones.js";
+/**
+ * Authored mounts, expressed in the framework's own vocabulary: a
+ * {@link CompositeBackend}-style route table of ordinary backends the consumer
+ * composes. The runtime owns only the **default route** — the session store, which
+ * must catch the runtime's fixed offload paths — and mounts this table beside it.
+ *
+ * A backend rooted *at* the mounted directory needs no path adaptation: the
+ * composite strips the route prefix before delegating and re-applies it to result
+ * paths. A consumer serving several mounts from one backend rebases with
+ * `mountSubtree` (exported from `core/path-mapping.ts`).
+ */
+/**
+ * A mount: a backend (read-only), or a backend with its write posture and its
+ * governance declared.
+ *
+ * `governed: true` says the spec decides which **states** may see this mount:
+ * it is closed by default and reachable only where a `mounts` list enables it,
+ * exactly as a skill bundle is. An ungoverned mount (the default, and every
+ * existing table) is visible in every state, and only a `mounts.forbid` takes
+ * it away. The consumer owns which backend serves a mount, its write posture
+ * and whether it is governed; the spec owns which states enable it, and neither
+ * is inferred from the other.
+ *
+ * `searchable: false` says the runtime must never search this mount on its own
+ * initiative: a root-wide `grep` or `glob` leaves it out, so a backend that
+ * refuses searches (a remote folder a search would download) cannot fail every
+ * root-wide search. A search the agent addresses at the mount still reaches the
+ * backend, whose own answer — matches or refusal — is returned verbatim. The
+ * flag is inert on a file mount, which is never searched as a tree.
+ */
+export type MountSpec = BackendProtocolV2 | {
+    backend: BackendProtocolV2;
+    readOnly?: boolean;
+    governed?: boolean;
+    searchable?: boolean;
+};
+/** One resolved mount: its normalized key, backend, write posture and governance. */
+export interface ResolvedMount {
+    /** Directory mounts keep their trailing slash; file mounts have none. */
+    key: string;
+    /** Key without leading slash or trailing slash — the reserved root name. */
+    name: string;
+    backend: BackendProtocolV2;
+    readOnly: boolean;
+    isDir: boolean;
+    /** Whether the spec's `mounts` lists decide which states may reach it. */
+    governed: boolean;
+    /** Whether a root-wide search may fan out into it (`true` unless declared otherwise). */
+    searchable: boolean;
+}
+export { NO_MOUNTS, type MountPrefixes };
+/**
+ * Thrown when a declared mount key would shadow a run area or serve an
+ * authoring-plane prefix to the agent. A declared route is the consumer's wiring
+ * rather than incidental noise, so it fails loudly instead of being skipped.
+ */
+export declare class MountCollisionError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+export { AUTHORING_PREFIXES, authoringPlanePrefix, describeAuthoringPrefix, isAuthoringPrefix, type AuthoringPrefix, };
+/**
+ * Canonical mount key: one leading slash, collapsed separators, trailing slash
+ * preserved (it is what distinguishes a directory mount from a file mount).
+ */
+export declare function normalizeMountKey(key: string): string;
+/**
+ * Resolve a consumer's mount table into the composite routes and the prefixes
+ * governance classifies against. Throws {@link MountCollisionError} when a key
+ * would shadow a run area or name an {@link AUTHORING_PREFIXES} prefix.
+ */
+export declare function resolveMounts(table?: Record<string, MountSpec>): {
+    mounts: ResolvedMount[];
+    prefixes: MountPrefixes;
+};
+/**
+ * The conventional mount table for a filesystem workspace: each authored
+ * directory as a {@link FilesystemBackend} rooted at itself, plus `AGENTS.md`
+ * served from the workspace root by exact path.
+ *
+ * This is a **default value**, applied only when the consumer supplies no table
+ * on the default backend — not framework law. Nothing in the framework
+ * classifies, validates, or enforces against these names; spread it to extend
+ * (`{ ...defaultMounts(root), "/templates/": … }`) or ignore it entirely.
+ */
+export declare function defaultMounts(rootDir: string): Record<string, MountSpec>;

package/dist/core/mounts.js

@@ -0,0 +1,147 @@
+import { join } from "node:path";
+import { FilesystemBackend } from "deepagents";
+import { normalizeRelPath } from "./workspace.js";
+import { PLATFORM_PROMPT_PATH } from "../workflow/paths.js";
+import { AUTHORING_PREFIXES, authoringPlanePrefix, describeAuthoringPrefix, isAuthoringPrefix, NO_MOUNTS, sessionAreaNames, } from "./zones.js";
+// The classification input type lives with the classifier (`core/zones.ts`);
+// re-exported here so consumers reach the whole mount vocabulary from one module.
+export { NO_MOUNTS };
+/**
+ * Thrown when a declared mount key would shadow a run area or serve an
+ * authoring-plane prefix to the agent. A declared route is the consumer's wiring
+ * rather than incidental noise, so it fails loudly instead of being skipped.
+ */
+export class MountCollisionError extends Error {
+    key;
+    constructor(key) {
+        const name = key.replace(/^\/+|\/+$/g, "");
+        // The collision is with the key's *first* segment, so a nested key
+        // (`/workflows/order-lookup/`) is named for the prefix it reaches into.
+        const top = name.split("/")[0] ?? "";
+        const plane = isAuthoringPrefix(top) ? top : null;
+        super(plane
+            ? `Mount '${key}' would serve the authoring plane to the agent. ` +
+                `'${plane}/' holds ${describeAuthoringPrefix(plane)}; the runtime ` +
+                `reads them through the authoring backend, and no agent tool may address them. ` +
+                `Configure them with the 'authoring' option instead of mounting them.`
+            : `Mount '${key}' collides with the run area '${top}/', which the ` +
+                `session store owns at the workspace root. Mount it under a different key.`);
+        this.key = key;
+        this.name = "MountCollisionError";
+    }
+}
+const SESSION_AREA_SET = new Set(sessionAreaNames());
+// The authoring prefixes are root-namespace vocabulary and live with the rest of
+// it in `core/zones.ts`; re-exported here so consumers reach the whole mount
+// vocabulary from one module.
+export { AUTHORING_PREFIXES, authoringPlanePrefix, describeAuthoringPrefix, isAuthoringPrefix, };
+/**
+ * Canonical mount key: one leading slash, collapsed separators, trailing slash
+ * preserved (it is what distinguishes a directory mount from a file mount).
+ */
+export function normalizeMountKey(key) {
+    const isDir = /\/\s*$/.test(key);
+    const rel = normalizeRelPath(key).replace(/\/+$/, "");
+    return `/${rel}${isDir ? "/" : ""}`;
+}
+function specParts(spec) {
+    if (typeof spec === "object" && spec !== null && "backend" in spec) {
+        return {
+            backend: spec.backend,
+            readOnly: spec.readOnly ?? true,
+            governed: spec.governed ?? false,
+            searchable: spec.searchable ?? true,
+        };
+    }
+    return { backend: spec, readOnly: true, governed: false, searchable: true };
+}
+/**
+ * Resolve a consumer's mount table into the composite routes and the prefixes
+ * governance classifies against. Throws {@link MountCollisionError} when a key
+ * would shadow a run area or name an {@link AUTHORING_PREFIXES} prefix.
+ */
+export function resolveMounts(table = {}) {
+    const mounts = [];
+    for (const [rawKey, spec] of Object.entries(table)) {
+        const key = normalizeMountKey(rawKey);
+        const name = key.replace(/^\/+|\/+$/g, "");
+        if (name === "")
+            continue;
+        // The *first* segment decides: a key several levels down the reserved
+        // prefix is the same exposure as the prefix itself, so `/workflows/x/`
+        // fails exactly as `/workflows/` does.
+        const [top = ""] = name.split("/");
+        if (SESSION_AREA_SET.has(top) || isAuthoringPrefix(top)) {
+            throw new MountCollisionError(key);
+        }
+        const { backend, readOnly, governed, searchable } = specParts(spec);
+        mounts.push({
+            key,
+            name,
+            backend,
+            readOnly,
+            isDir: key.endsWith("/"),
+            governed,
+            searchable,
+        });
+    }
+    return {
+        mounts,
+        prefixes: {
+            dirs: mounts.filter((m) => m.isDir).map((m) => m.name),
+            files: mounts.filter((m) => !m.isDir).map((m) => m.name),
+            writable: mounts.filter((m) => !m.readOnly).map((m) => m.name),
+            governed: mounts.filter((m) => m.governed).map((m) => m.name),
+            // Only a directory is ever searched as a tree, so the flag on a file
+            // mount is recorded on the resolved mount but classifies nothing.
+            unsearchable: mounts.filter((m) => m.isDir && !m.searchable).map((m) => m.name),
+        },
+    };
+}
+/**
+ * Conventional authored directories — a default value, never a constraint.
+ *
+ * Deliberately short, and deliberately missing every {@link AUTHORING_PREFIXES}
+ * prefix. That plane is not workspace furniture the agent browses: it is what the
+ * runtime enforces the run *with*, served by the authoring backend and reachable by
+ * no tool call. `workflows/` holds the spec — its grading rubrics included, so a run
+ * cannot read the criteria it is judged against — plus the prose addendum, the hook
+ * scripts, and the cases grading the run.
+ *
+ * What ships in a skill bundle is the other kind of script — the ones the *agent*
+ * runs with `archmax_run` — together with the data a state reads
+ * (`skills/<name>/scripts/…`, `skills/<name>/assets/…`), reaching the agent through
+ * the `skills/` mount, which also lets a state scope execution to one capability
+ * (`skills/triage/scripts/**`).
+ *
+ * None of the conventional mounts is `governed`: a zero-config workspace's
+ * content is visible in every state, exactly as it was before the `mounts`
+ * block existed.
+ */
+const CONVENTIONAL_DIRS = [
+    "skills",
+    PLATFORM_PROMPT_PATH.split("/")[0], // `.platform` — the runtime reads its prompt from here
+];
+/** Conventional authored root files, mounted by exact path. */
+const CONVENTIONAL_FILES = ["AGENTS.md"];
+/**
+ * The conventional mount table for a filesystem workspace: each authored
+ * directory as a {@link FilesystemBackend} rooted at itself, plus `AGENTS.md`
+ * served from the workspace root by exact path.
+ *
+ * This is a **default value**, applied only when the consumer supplies no table
+ * on the default backend — not framework law. Nothing in the framework
+ * classifies, validates, or enforces against these names; spread it to extend
+ * (`{ ...defaultMounts(root), "/templates/": … }`) or ignore it entirely.
+ */
+export function defaultMounts(rootDir) {
+    const fs = (dir) => new FilesystemBackend({ rootDir: dir, virtualMode: true });
+    const table = {};
+    for (const dir of CONVENTIONAL_DIRS)
+        table[`/${dir}/`] = fs(join(rootDir, dir));
+    // Root files live in the workspace root itself, addressed by their exact key.
+    for (const file of CONVENTIONAL_FILES)
+        table[`/${file}`] = fs(rootDir);
+    return table;
+}
+//# sourceMappingURL=mounts.js.map

package/dist/core/mounts.js.map

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

package/dist/core/path-mapping.d.ts

@@ -0,0 +1,52 @@
+import type { BackendProtocolV2 } from "deepagents";
+/**
+ * Bidirectional path mapping for a backend served under a prefix.
+ *
+ * Three places in the runtime delegate to a backend whose paths are shifted by
+ * a prefix, and all three need the *same* two-way mapping:
+ *
+ *  - **Authored mounts** — `CompositeBackend` strips the route prefix before
+ *    delegating (`/skills/x` → `/x`) and re-prepends it to the paths it returns.
+ *    A one-way prepending wrapper therefore double-prefixes every listed path
+ *    (`/skills/skills/x`); the outbound half is what keeps the round trip honest.
+ *  - **The session store's tenancy prefix** — consumer-owned layout that must never
+ *    appear in an SDK-visible or agent-visible path, including result paths.
+ *  - **The session zone's session binding** — the bound session id must not appear in
+ *    agent-visible listings, so it is stripped on the way out.
+ *
+ * Inbound: `/x` → `/<prefix>/x`. Outbound: every `path` a result carries
+ * (`ls`/`glob` entries, `grep` matches, `write`/`edit` results) is mapped back.
+ * A result path that does not start with the prefix is left untouched — the
+ * inner backend is free to report paths we did not ask about.
+ */
+/** The prefix in effect for a call: a fixed string, or resolved per call. */
+export type PrefixResolver = () => string | undefined;
+/**
+ * Wrap `backend` so it is addressed under `prefix` from the outside, mapping
+ * paths in both directions. `prefix` may be a resolver, returning `undefined`
+ * when no prefix applies for this call (the session zone outside a bound session) —
+ * in which case paths pass through unchanged.
+ *
+ * `passthrough` marks inbound paths that are already expressed in the inner
+ * backend's terms and must not be prefixed (e.g. runtime-internal
+ * session-qualified paths, cross-session `_specs/…`). Their result paths are left
+ * unmapped as well, since they were never shifted.
+ */
+export declare function mountSubtree(backend: BackendProtocolV2, prefix: string | PrefixResolver, options?: {
+    passthrough?: (relPath: string, prefix: string) => boolean;
+    /**
+     * Refuse `write`/`edit` at the mount instead of delegating. Read-only is a
+     * property of the mount, so an authored mount cannot be written through even
+     * by a caller that bypasses governance — the kernel's `zone.read-only` rule
+     * remains the agent-facing diagnostic, not the only enforcement.
+     */
+    readOnly?: boolean;
+    /**
+     * Route prefix a composite stripped before delegating, re-applied when a
+     * read-only refusal names the rejected path. Without it the refusal reports
+     * the stripped key (`/orders.json`) rather than the path the caller sent
+     * (`data/orders.json`) — pointing an agent at a path it never asked about,
+     * which is exactly the confusion that makes it retry with invented paths.
+     */
+    displayPrefix?: string;
+}): BackendProtocolV2;

package/dist/core/path-mapping.js

@@ -0,0 +1,113 @@
+import { normalizeRelPath } from "./workspace.js";
+function relPrefix(prefix) {
+    return normalizeRelPath(prefix).replace(/\/+$/, "");
+}
+/**
+ * Wrap `backend` so it is addressed under `prefix` from the outside, mapping
+ * paths in both directions. `prefix` may be a resolver, returning `undefined`
+ * when no prefix applies for this call (the session zone outside a bound session) —
+ * in which case paths pass through unchanged.
+ *
+ * `passthrough` marks inbound paths that are already expressed in the inner
+ * backend's terms and must not be prefixed (e.g. runtime-internal
+ * session-qualified paths, cross-session `_specs/…`). Their result paths are left
+ * unmapped as well, since they were never shifted.
+ */
+export function mountSubtree(backend, prefix, options = {}) {
+    const resolvePrefix = typeof prefix === "function" ? () => optionalRel(prefix()) : () => relPrefix(prefix);
+    const passthrough = options.passthrough;
+    /**
+     * The refused path in workspace terms — the spelling the caller would use to
+     * address it — so the diagnostic names the path that was actually rejected.
+     */
+    const displayPath = (path) => {
+        const rel = normalizeRelPath(path);
+        const prefix = relPrefix(options.displayPrefix ?? "");
+        if (!prefix)
+            return rel === "" ? path : rel;
+        return rel === "" ? prefix : `${prefix}/${rel}`;
+    };
+    const readOnlyError = (op, path) => ({
+        error: `Cannot ${op} '${displayPath(path)}': it is served by a read-only mount. ` +
+            `Only run state is writable in this workspace.`,
+    });
+    /** The prefix to apply to `path`, or `undefined` when it passes through. */
+    const prefixFor = (path) => {
+        const active = resolvePrefix();
+        if (!active)
+            return undefined;
+        if (passthrough?.(normalizeRelPath(path), active))
+            return undefined;
+        return active;
+    };
+    const mapIn = (path, active) => {
+        if (!active)
+            return path;
+        const hadSlash = path.startsWith("/");
+        const rel = normalizeRelPath(path);
+        const joined = rel === "" ? active : `${active}/${rel}`;
+        return hadSlash || path === "" ? `/${joined}` : joined;
+    };
+    const mapOut = (path, active) => {
+        if (!active)
+            return path;
+        const hadSlash = path.startsWith("/");
+        const rel = normalizeRelPath(path);
+        if (rel !== active && !rel.startsWith(`${active}/`))
+            return path;
+        const stripped = rel === active ? "" : rel.slice(active.length + 1);
+        return hadSlash ? `/${stripped}` : stripped;
+    };
+    const mapFiles = (files, active) => files?.map((file) => ({ ...file, path: mapOut(file.path, active) }));
+    return {
+        async ls(path) {
+            const active = prefixFor(path);
+            const res = await backend.ls(mapIn(path, active));
+            const files = mapFiles(res.files, active);
+            return files ? { ...res, files } : res;
+        },
+        read(filePath, offset, limit) {
+            return backend.read(mapIn(filePath, prefixFor(filePath)), offset, limit);
+        },
+        readRaw(filePath) {
+            return backend.readRaw(mapIn(filePath, prefixFor(filePath)));
+        },
+        async grep(pattern, path, glob) {
+            const target = path ?? "";
+            const active = prefixFor(target);
+            const searchPath = path == null && !active ? path : mapIn(target, active);
+            const res = await backend.grep(pattern, searchPath, glob);
+            const matches = res.matches?.map((match) => ({ ...match, path: mapOut(match.path, active) }));
+            return matches ? { ...res, matches } : res;
+        },
+        async glob(pattern, path) {
+            const target = path ?? "";
+            const active = prefixFor(target);
+            const searchPath = path === undefined && !active ? undefined : mapIn(target, active);
+            const res = await backend.glob(pattern, searchPath);
+            const files = mapFiles(res.files, active);
+            return files ? { ...res, files } : res;
+        },
+        async write(filePath, content) {
+            if (options.readOnly)
+                return readOnlyError("write", filePath);
+            const active = prefixFor(filePath);
+            const res = await backend.write(mapIn(filePath, active), content);
+            return res.path === undefined ? res : { ...res, path: mapOut(res.path, active) };
+        },
+        async edit(filePath, oldString, newString, replaceAll) {
+            if (options.readOnly)
+                return readOnlyError("edit", filePath);
+            const active = prefixFor(filePath);
+            const res = await backend.edit(mapIn(filePath, active), oldString, newString, replaceAll);
+            return res.path === undefined ? res : { ...res, path: mapOut(res.path, active) };
+        },
+    };
+}
+function optionalRel(prefix) {
+    if (prefix == null)
+        return undefined;
+    const rel = relPrefix(prefix);
+    return rel === "" ? undefined : rel;
+}
+//# sourceMappingURL=path-mapping.js.map

package/dist/core/path-mapping.js.map

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

package/dist/core/platform-prompt.generated.d.ts

@@ -0,0 +1,2 @@
+/** The bundled platform prompt: how to move through the graph and which tools are the runtime's. */
+export declare const PLATFORM_PROMPT: string;

package/dist/core/platform-prompt.generated.js

@@ -0,0 +1,4 @@
+// Generated from platform-prompt.md by scripts/generate-platform-prompt.mjs. Do not edit.
+/** The bundled platform prompt: how to move through the graph and which tools are the runtime's. */
+export const PLATFORM_PROMPT = "# Graph state execution\n\nYou run inside a **declarative workflow graph**: you occupy one **state** at a\ntime, and that state's spec governs which tools you may call and which files you\nmay read or write.\n\n## How you move\n\n1. **Name the run first.** Before anything else in your first turn, call\n   **`archmax_set_variables({ \"variables\": { \"title\": \"<a few words>\" } })`** — see\n   \"Naming the run\" below.\n2. Do the current state's work. `scratchpad/` is always open, so it is where a\n   file goes when nothing else was named — but it is a default, not a limit: when\n   the state's instructions or its listed mounts name a writable place, write\n   there instead of copying into `scratchpad/`.\n3. Call **`archmax_advance({ \"to\": \"<next>\", \"reason\": \"<one sentence>\" })`**,\n   choosing `to` from the transitions listed under \"Current state\" and using\n   their descriptions to decide. `to` takes the target's **slug** — the\n   backticked token on the transition line. A parenthesized note carries the\n   edge's declared type (`approve`, `reject`, `refine`), whether the target is a\n   **human decision node**, and whether it is **terminal**. A state with no\n   transitions says so: that is where the run ends, so finish its work and stop.\n4. The runtime validates the edge, runs this state's `after` hook and then the\n   target's `before` hook — either may send you back to correct or veto the\n   move — and only then unlocks the next state's tools.\n\n**One transition per message.** A second `archmax_advance` alongside the first is\nrefused. Chain states over successive turns, never in a single message.\n\n**A conversation keeps its position.** A message arriving after your last turn\nleaves you in the state that turn ended in, not at the beginning. When that state\ncannot serve what was asked — no transition from here reaches it, or an earlier\nturn took a wrong path — call **`archmax_reset({ \"reason\": \"<one sentence>\" })`**\nto return to the state the conversation began in. It is available in every state\nand moves the state machine, not the history: the conversation and everything\nwritten so far are kept.\n\n**A terminal state never serves a follow-up.** A reply, a correction or a new\nrequest landing on a run that was *already sitting* in a terminal state is work\nthis run has no path to do: reset **before** answering it, or you skip every state\nthe answer depends on. Two things are not follow-ups — a run you parked with\n`archmax_wait`, which resumes where it was on purpose, and a terminal state you\nwere routed into *this turn*, by your own `archmax_advance` or by a person's\ndecision, which is the work you were sent there to do: do it, then stop. Never\nreset out of a state you just arrived in, and never `archmax_wait` for the runtime\nto move you — it already has.\n\n### Waiting for something to arrive\n\nIf this state cannot continue without something from **outside the run** — an\nevent, a callback, a webhook, a reply someone sends in their own time — call\n**`archmax_wait({ \"reason\": \"<what you are waiting for>\" })`** and stop, instead of\nending your turn. You resume in **this same state**, with what arrived in your\ntranscript and any values it carried in the variables. Waiting for a *time*\nrather than an event? Add `\"until\": \"1d\"` (a duration or an ISO-8601 instant) so\nwhoever wakes you knows when; an earlier event still resumes you.\n\n`archmax_wait` holds you where you are and moves nothing, so it is never how you\nget a person to decide, approve, sign off, review, or choose between options.\nThat belongs to a **human decision node** — a state the author declared for it,\nwhich you reach the ordinary way with `archmax_advance`. The runtime parks the run\nthere and presents the options by itself: do the work that state's transitions\nrequire, advance into the node, and stop. Never advance out of one yourself, and\nnever `archmax_wait` in front of one to ask for the decision the node exists to\ncollect.\n\nSo: something has to **come to this state** → `archmax_wait`. Someone has to\n**decide** → `archmax_advance` into the human node.\n\n### The state you are in\n\nThe active state's **`instructions`** arrive under a \"Current state\" heading —\nfollow them; the transitions listed there are for choosing where to go next. You\nare shown the edges leading out of the state you are in and nothing else of the\ngraph: there is no map of the workflow to consult, and a state you cannot advance\nto is one you cannot name. Do not guess at slugs, and do not treat a state named\nanywhere else — in a message, a file, or your own earlier turns — as somewhere you\ncan move to. When the state may use skills, they are listed under \"Skills\navailable in this state\", each naming the `SKILL.md` to read first.\n\n**`before`/`after` hooks** run on their own, without you calling them. They may\napprove, ask you to correct your answer, or block the run: fix the work rather\nthan arguing with it.\n\n## Tools\n\nTool access is **closed by default**: you see exactly the active state's surface,\nand a state's entry may also narrow a tool's permitted *arguments* (e.g.\n`write_file` to one path). Tools whose names start with `archmax_` are the\nruntime's own controls — movement, reset, waiting, the sandbox, and the run's\nvariables (`archmax_get_variables` / `archmax_set_variables`); everything else acts\non the workspace or on the systems this workspace integrates. A blocked call names\nthe tool, the state, and the policy — fix the call, or advance if you are done.\n\n**Write code instead of many calls.** **`archmax_eval({ \"code\": \"…\" })`** —\navailable in every state — evaluates JavaScript in a sandbox where `tools.*`\ncalls the same tools you have, governed exactly as your own calls are. Reach for\nit by default whenever the work is a loop, a filter, arithmetic, or more than\nabout two calls whose results feed each other: it is one round trip instead of\nmany, and **only your last expression and whatever you `console.log` come back to\nyou**, so the bulk of what those tools returned never enters the conversation and\nis never re-sent on later calls. The REPL keeps its state between calls, so a\nvalue or helper from one is still in scope in the next. Your code cannot read the\nrun's variables: interpolate a scalar one into it with `${{name}}` (below), and\nuse **`archmax_run({ \"file_path\": \"…\" })`** — also in every state — when the code\nneeds whole structured values, which an authored script receives as\n`args.variables`. It runs the same way, subject to any path constraint the state\nplaces on it.\n\n**Naming the run.** `title` is a reserved run variable holding a short label for\nthe task you are doing — one line, a handful of words, enough that someone\nscanning a list of runs knows which one this is:\n\n```\narchmax_set_variables({ \"variables\": { \"title\": \"Refund for order A-1042\" } })\n```\n\nThis is step 1 above, and it is not optional. Write it from whatever the request\nalready tells you, **before** the current state's own work and before any other\ntool call — it is a label, not a plan, so never investigate or read anything to\nproduce one, and it still goes first when the state's instructions tell you to do\nsomething else first. Update it with the same call whenever the task turns into\nsomething the old title no longer describes; a small refinement of the same task\ndoes not need one. Never pass `lock` with it: the title has to stay correctable\nfor the whole run, so that call is refused.\n\n**Reference a run variable instead of retyping it.** Anywhere a tool argument is\ntext, `${{name}}` (or `${{name.path.to.value}}`) is replaced with that variable's\nvalue before the call runs. A reference may sit **inside** a longer string and\nrepeat:\n\n```\n\"Thanks — your refund is on its way.\n\n--- Original message ---\n\n${{inbound.text}}\"\n```\n\nPrefer the reference to writing the value out. It is what you spend tokens on and\nwhat stays in the transcript — the full value goes to the tool and no further —\nand unlike a retyped copy it cannot paraphrase, truncate or mistype.\n`archmax_get_variables` shows what is set; a reference that does not resolve\nrefuses the call and tells you why, so fix it and retry. To write the characters\n`${{…}}` literally, double the dollar: `$${{name}}`.\n";
+//# sourceMappingURL=platform-prompt.generated.js.map

package/dist/core/platform-prompt.generated.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform-prompt.generated.js","sourceRoot":"","sources":["../../src/core/platform-prompt.generated.ts"],"names":[],"mappings":"AAAA,0FAA0F;AAE1F,oGAAoG;AACpG,MAAM,CAAC,MAAM,eAAe,GAAW,qsQAAqsQ,CAAC"}

package/dist/core/prompt.d.ts

@@ -0,0 +1,42 @@
+import type { Workspace } from "./workspace.js";
+import { type MountPrefixes } from "./zones.js";
+export interface ResolveSystemPromptOptions {
+    /** Workspace-relative path to AGENTS.md (default: `AGENTS.md`). */
+    agentsPath?: string;
+    /**
+     * Where a workspace may override the platform prompt (normally
+     * `PLATFORM_PROMPT_PATH`); the bundled prompt applies when nothing is served
+     * there. `null` leaves the platform layer out — a plain agent has no machine
+     * for it to explain.
+     */
+    platformBackendPath: string | null;
+    /**
+     * Pre-assembled workflow prompt text: the spec-rendered workflow header
+     * followed by any `WORKFLOW.md` prose addendum (the caller composes both —
+     * see `renderWorkflowPrompt` — because it already holds the loaded spec and
+     * body; this module never re-reads the workflow files). Carries no state of
+     * the graph; `renderStateGraph` renders that per model call.
+     */
+    workflowPrompt?: string | null;
+    /**
+     * The assembly's resolved mount keys. The workspace-zones section is rendered
+     * from these, so what the prompt says the agent has cannot drift from what the
+     * workspace serves. Omitted: no mounts are described.
+     */
+    mountPrefixes?: MountPrefixes;
+    /** Extra text appended after AGENTS.md. */
+    extra?: string;
+}
+/** The layers `buildSystemPrompt` joins, in the order listed at the top of this module. */
+export interface SystemPromptParts {
+    agents?: string | null;
+    extra?: string;
+    platform?: string | null;
+    /** The workspace-zones section, rendered from the resolved mount table. */
+    workspace?: string | null;
+    workflow?: string | null;
+}
+/** Join the prompt layers, skipping absent ones. */
+export declare function buildSystemPrompt(parts: SystemPromptParts): string;
+/** Load the prompt layers from the backend and merge them. */
+export declare function resolveSystemPrompt(workspace: Workspace, opts: ResolveSystemPromptOptions): Promise<string>;