@archmax-ai/harness 0.0.0

package/dist/core/prompt.js

@@ -0,0 +1,75 @@
+/**
+ * The system prompt, layered. Every layer below is either read through the
+ * backend or rendered from something the runtime enforces, so what the model is
+ * told cannot drift from what the workspace serves or the machine permits.
+ *
+ * The full order the model sees, first to last:
+ *
+ *  1. `AGENTS.md` — the workspace's persona, read through the composite.
+ *  2. The consumer's `systemPrompt` option — appended after the persona.
+ *  3. The platform prompt — how to move and which tools are the runtime's own.
+ *     It ships inside the code (`platform-prompt.md`, generated into
+ *     `platform-prompt.generated.ts`); a workspace may override it at
+ *     `.platform/system/GRAPH_STATE.md`. A plain agent has no machine for it to
+ *     explain, so it gets no platform layer.
+ *  4. Workspace zones — rendered from the assembly's resolved mount table.
+ *  5. The workflow header — the spec's `title` and root `instructions`, and no
+ *     state of the graph: the graph is disclosed only from where the agent
+ *     stands, so it lives in layer 8 (see `workflow/render-prompt.ts`). This
+ *     layer is therefore a function of the header alone and does not grow with
+ *     the state count.
+ *  6. `WORKFLOW.md` — the optional prose addendum, HTML comments stripped.
+ *  7. Deep Agents' tool guidance — the file tools' and `write_todos`' sections,
+ *     appended by their middleware.
+ *  8. The volatile "Current state" block — the current date and time, then the
+ *     active state's instructions, skills, mounts, variables, argument
+ *     constraints and its own outgoing transitions, appended per model call by
+ *     the workflow middleware and never part of the cacheable prefix. The clock
+ *     is here for the same reason everything else in this block is — it does not
+ *     hold still — and is rounded to a ten-minute bucket so that it holds still
+ *     for the calls of one turn (see `renderNow` in `workflow/governance.ts`).
+ *
+ * Layers 1–6 are what `resolveSystemPrompt` returns and the assembly hands to
+ * Deep Agents as `systemPrompt: { prefix, base: null }`. Deep Agents' own base
+ * prompt ("You are a Deep Agent…") is deliberately dropped: it is generic
+ * assistant guidance that contradicts layer 3 (it says to ask before acting and
+ * to yield only when the task is done; a governed session parks, waits and
+ * stops at human states). Layers 7–8 come from middleware.
+ */
+import { PLATFORM_PROMPT } from "./platform-prompt.generated.js";
+import { renderWorkspaceZones } from "./workspace-prompt.js";
+import { NO_MOUNTS } from "./zones.js";
+/** Join the prompt layers, skipping absent ones. */
+export function buildSystemPrompt(parts) {
+    return [
+        parts.agents?.trim(),
+        parts.extra?.trim(),
+        parts.platform?.trim(),
+        parts.workspace?.trim(),
+        parts.workflow?.trim(),
+    ]
+        .filter(Boolean)
+        .join("\n\n");
+}
+/** The workspace's override when it serves one, else the bundled prompt. */
+async function readPlatformPrompt(workspace, backendPath) {
+    if (backendPath === null)
+        return null;
+    return (await workspace.readText(backendPath)) || PLATFORM_PROMPT;
+}
+/** Load the prompt layers from the backend and merge them. */
+export async function resolveSystemPrompt(workspace, opts) {
+    const agentsPath = opts.agentsPath ?? "AGENTS.md";
+    const [platform, agents] = await Promise.all([
+        readPlatformPrompt(workspace, opts.platformBackendPath),
+        workspace.readText(agentsPath),
+    ]);
+    return buildSystemPrompt({
+        agents,
+        extra: opts.extra,
+        platform,
+        workspace: renderWorkspaceZones(opts.mountPrefixes ?? NO_MOUNTS),
+        workflow: opts.workflowPrompt ?? null,
+    });
+}
+//# sourceMappingURL=prompt.js.map

package/dist/core/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,OAAO,EAAE,eAAe,EAAE,MAAM,gCAAgC,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAC7D,OAAO,EAAE,SAAS,EAAsB,MAAM,YAAY,CAAC;AAwC3D,oDAAoD;AACpD,MAAM,UAAU,iBAAiB,CAAC,KAAwB;IACxD,OAAO;QACL,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE;QACpB,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE;QACnB,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE;QACtB,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE;QACvB,KAAK,CAAC,QAAQ,EAAE,IAAI,EAAE;KACvB;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,MAAM,CAAC,CAAC;AAClB,CAAC;AAED,4EAA4E;AAC5E,KAAK,UAAU,kBAAkB,CAC/B,SAAoB,EACpB,WAA0B;IAE1B,IAAI,WAAW,KAAK,IAAI;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,CAAC,MAAM,SAAS,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC,IAAI,eAAe,CAAC;AACpE,CAAC;AAED,8DAA8D;AAC9D,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,SAAoB,EACpB,IAAgC;IAEhC,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,WAAW,CAAC;IAClD,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC3C,kBAAkB,CAAC,SAAS,EAAE,IAAI,CAAC,mBAAmB,CAAC;QACvD,SAAS,CAAC,QAAQ,CAAC,UAAU,CAAC;KAC/B,CAAC,CAAC;IAEH,OAAO,iBAAiB,CAAC;QACvB,MAAM;QACN,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,QAAQ;QACR,SAAS,EAAE,oBAAoB,CAAC,IAAI,CAAC,aAAa,IAAI,SAAS,CAAC;QAChE,QAAQ,EAAE,IAAI,CAAC,cAAc,IAAI,IAAI;KACtC,CAAC,CAAC;AACL,CAAC"}

package/dist/core/session-id.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The session-id vocabulary: what makes an id able to own a session folder, and
+ * the error an id that cannot is refused with. Pure — it depends on nothing but
+ * the root-namespace classifier — so a browser-side host can refuse a bad id
+ * with the same words the runtime uses, before it reaches a store. The stores
+ * themselves live in `session-store.ts`.
+ */
+import { type MountPrefixes } from "./zones.js";
+/**
+ * Directory name of the zero-config filesystem session store
+ * (`<workspace>/sessions`, one folder per session inside it). Physical detail
+ * only: it appears in no SDK-visible or agent-visible path.
+ */
+export declare const DEFAULT_SESSIONS_DIR = "sessions";
+/**
+ * Thrown when a `sessionId` cannot own a session folder: it would address storage
+ * outside the session zone (absolute or `..` traversal), or it collides with a name
+ * reserved at the workspace root. The latter matters because session state is
+ * addressed as `<sessionId>/…` at the root — a session called `skills` would route
+ * its own checkpoints into the authored `skills/` mount. Deletion is also the
+ * one session operation that touches real `node:fs` directly (bypassing the
+ * backend's virtual mode), so it must contain its target itself.
+ */
+export declare class SessionStoreIdError extends Error {
+    readonly sessionId: string;
+    constructor(sessionId: string, reason?: string);
+}
+/** Strip leading slashes to the store-relative form. */
+export declare function storeRelativeSessionId(sessionId: string): string;
+/**
+ * Why a session id cannot own a session folder, or `null` when it can: non-empty
+ * once leading slashes are stripped, free of `..` traversal segments, and with a
+ * first segment that is not reserved at the workspace root. Exposed so
+ * untrusted-id ingress points (the CLI, `invoke`, session handles, a host's own
+ * API) can reject a bad id up front with their own message, rather than relying
+ * on a store throwing deep inside a delete.
+ */
+export declare function sessionIdRejection(sessionId: string, mountPrefixes?: MountPrefixes): string | null;

package/dist/core/session-id.js

@@ -0,0 +1,61 @@
+/**
+ * The session-id vocabulary: what makes an id able to own a session folder, and
+ * the error an id that cannot is refused with. Pure — it depends on nothing but
+ * the root-namespace classifier — so a browser-side host can refuse a bad id
+ * with the same words the runtime uses, before it reaches a store. The stores
+ * themselves live in `session-store.ts`.
+ */
+import { isReservedRootName } from "./zones.js";
+/**
+ * Directory name of the zero-config filesystem session store
+ * (`<workspace>/sessions`, one folder per session inside it). Physical detail
+ * only: it appears in no SDK-visible or agent-visible path.
+ */
+export const DEFAULT_SESSIONS_DIR = "sessions";
+/**
+ * Thrown when a `sessionId` cannot own a session folder: it would address storage
+ * outside the session zone (absolute or `..` traversal), or it collides with a name
+ * reserved at the workspace root. The latter matters because session state is
+ * addressed as `<sessionId>/…` at the root — a session called `skills` would route
+ * its own checkpoints into the authored `skills/` mount. Deletion is also the
+ * one session operation that touches real `node:fs` directly (bypassing the
+ * backend's virtual mode), so it must contain its target itself.
+ */
+export class SessionStoreIdError extends Error {
+    sessionId;
+    constructor(sessionId, reason = "it must stay within the session zone (no absolute paths or '..' traversal)") {
+        super(`Invalid session id ${JSON.stringify(sessionId)}: ${reason}.`);
+        this.sessionId = sessionId;
+        this.name = "SessionStoreIdError";
+    }
+}
+/** Strip leading slashes to the store-relative form. */
+export function storeRelativeSessionId(sessionId) {
+    return String(sessionId).replace(/^\/+/, "");
+}
+/**
+ * Why a session id cannot own a session folder, or `null` when it can: non-empty
+ * once leading slashes are stripped, free of `..` traversal segments, and with a
+ * first segment that is not reserved at the workspace root. Exposed so
+ * untrusted-id ingress points (the CLI, `invoke`, session handles, a host's own
+ * API) can reject a bad id up front with their own message, rather than relying
+ * on a store throwing deep inside a delete.
+ */
+export function sessionIdRejection(sessionId, mountPrefixes) {
+    const relative = storeRelativeSessionId(sessionId);
+    const segments = relative.split(/[\\/]+/);
+    if (relative === "")
+        return "it must not be empty";
+    if (segments.some((segment) => segment === "..")) {
+        return "it must stay within the session zone (no absolute paths or '..' traversal)";
+    }
+    // Session areas are the framework's own namespace, so they are always reserved.
+    // Mount names are workspace shape: reserved once the caller supplies the
+    // resolved mount keys (assembly does). Without it a colliding authored name
+    // still fails safely — the read-only mount refuses the write.
+    if (isReservedRootName(segments[0], mountPrefixes)) {
+        return `'${segments[0]}' is reserved at the workspace root (a session area or an authored mount)`;
+    }
+    return null;
+}
+//# sourceMappingURL=session-id.js.map

package/dist/core/session-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-id.js","sourceRoot":"","sources":["../../src/core/session-id.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,kBAAkB,EAAsB,MAAM,YAAY,CAAC;AAEpE;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,UAAU,CAAC;AAE/C;;;;;;;;GAQG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAEjC;IADX,YACW,SAAiB,EAC1B,MAAM,GAAG,4EAA4E;QAErF,KAAK,CAAC,sBAAsB,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC;QAH5D,cAAS,GAAT,SAAS,CAAQ;QAI1B,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED,wDAAwD;AACxD,MAAM,UAAU,sBAAsB,CAAC,SAAiB;IACtD,OAAO,MAAM,CAAC,SAAS,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAC/C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,SAAiB,EACjB,aAA6B;IAE7B,MAAM,QAAQ,GAAG,sBAAsB,CAAC,SAAS,CAAC,CAAC;IACnD,MAAM,QAAQ,GAAG,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,CAAC;IAC1C,IAAI,QAAQ,KAAK,EAAE;QAAE,OAAO,sBAAsB,CAAC;IACnD,IAAI,QAAQ,CAAC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,KAAK,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,4EAA4E,CAAC;IACtF,CAAC;IACD,gFAAgF;IAChF,yEAAyE;IACzE,4EAA4E;IAC5E,8DAA8D;IAC9D,IAAI,kBAAkB,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,aAAa,CAAC,EAAE,CAAC;QACnD,OAAO,IAAI,QAAQ,CAAC,CAAC,CAAC,2EAA2E,CAAC;IACpG,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/core/session-store.d.ts

@@ -0,0 +1,85 @@
+import { type BackendProtocolV2 } from "deepagents";
+import { DEFAULT_SESSIONS_DIR, SessionStoreIdError, sessionIdRejection } from "./session-id.js";
+/**
+ * Consumer-owned physical storage for the session zone — the agent's workspace root.
+ *
+ * The ownership boundary: the SDK owns the *logical* session namespace — the
+ * per-session `<sessionId>/…` layout, reserved areas (`checkpoints/`,
+ * `artifacts/`, `scratchpad/`, `large_tool_results/`,
+ * `conversation_history/`), the session-agnostic `_specs/` prefix, session-scoped
+ * path routing, and lazy creation — while the consumer owns the *physical*
+ * storage: which backend, under what prefix/tenancy, how durable, and for how
+ * long. A `SessionStore` is that consumer-side choice, made explicitly (or by the
+ * documented zero-config default) and mounted exactly once.
+ */
+export { DEFAULT_SESSIONS_DIR, SessionStoreIdError, sessionIdRejection };
+export interface SessionStoreCapabilities {
+    /** Whether the store can enumerate session folders (`sessions.list()`). */
+    list: boolean;
+    /** Whether the store can remove a session's content (`sessions.delete()`). */
+    delete: boolean;
+}
+export interface SessionStore {
+    /** Store flavor for diagnostics and error messages. */
+    kind: "filesystem" | "backend" | "memory";
+    /**
+     * Backend serving the session zone. The SDK wraps it in a `SessionZoneRouter`
+     * (session-scoped, id-free addressing) and mounts it on the workspace
+     * `CompositeBackend`; consumers never address it directly.
+     */
+    backend: BackendProtocolV2;
+    capabilities: SessionStoreCapabilities;
+    /**
+     * Remove everything stored under a session's namespace. Returns whether
+     * anything was removed. Throws {@link SessionStoreCapabilityError} when the
+     * store cannot delete (see {@link SessionStoreCapabilities.delete}).
+     */
+    deleteSession(sessionId: string): Promise<boolean>;
+}
+/**
+ * Thrown at assembly when a custom authored `backend` is supplied without an
+ * explicit `sessionStore`. The runtime never silently runs without session-scoped
+ * routing and never silently writes session state to local disk beside a
+ * virtual workspace — the consumer must name the storage.
+ */
+export declare class SessionStoreRequiredError extends Error {
+    constructor();
+}
+/** Thrown when a session operation needs a capability the configured store lacks. */
+export declare class SessionStoreCapabilityError extends Error {
+    readonly storeKind: string;
+    readonly capability: keyof SessionStoreCapabilities;
+    constructor(storeKind: string, capability: keyof SessionStoreCapabilities);
+}
+/**
+ * Local-directory session store: a filesystem backend rooted at `dir`, with full
+ * listing and deletion capabilities. The zero-config default is this store at
+ * `<workspaceRoot>/sessions`.
+ */
+export declare function createFilesystemSessionStore(options: {
+    dir: string;
+}): SessionStore;
+/**
+ * Session store over any {@link BackendProtocolV2} (object storage, database,
+ * remote). The `prefix` is the consumer's tenancy/layout concern: it is
+ * applied inside the store and never appears in SDK-visible or agent-visible
+ * paths. Deletion is available only when the consumer supplies a
+ * `deleteSession` implementation (the backend protocol models no delete);
+ * listing can be disabled for backends whose `ls` cannot enumerate folders.
+ */
+export declare function createBackendSessionStore(options: {
+    backend: BackendProtocolV2;
+    prefix?: string;
+    /** Remove `<prefix>/<sessionId>/…` from the underlying storage. */
+    deleteSession?: (sessionId: string) => Promise<boolean>;
+    /** Whether the backend's `ls` can enumerate session folders (default true). */
+    list?: boolean;
+}): SessionStore;
+/**
+ * Ephemeral in-memory session store for tests and throwaway sessions: Deep
+ * Agents' own `StoreBackend` over a LangGraph `InMemoryStore`, so nothing
+ * touches the filesystem or any external service, and everything vanishes with
+ * the process. Overwrites in place like every Deep Agents backend from
+ * deepagents 1.12.0 on; fully listable and deletable.
+ */
+export declare function createMemorySessionStore(): SessionStore;

package/dist/core/session-store.js

@@ -0,0 +1,149 @@
+import { existsSync, rmSync } from "node:fs";
+import { resolve, sep } from "node:path";
+import { InMemoryStore } from "@langchain/langgraph-checkpoint";
+import { FilesystemBackend, StoreBackend } from "deepagents";
+import { mountSubtree } from "./path-mapping.js";
+import { DEFAULT_SESSIONS_DIR, SessionStoreIdError, sessionIdRejection, storeRelativeSessionId as rel, } from "./session-id.js";
+/**
+ * Consumer-owned physical storage for the session zone — the agent's workspace root.
+ *
+ * The ownership boundary: the SDK owns the *logical* session namespace — the
+ * per-session `<sessionId>/…` layout, reserved areas (`checkpoints/`,
+ * `artifacts/`, `scratchpad/`, `large_tool_results/`,
+ * `conversation_history/`), the session-agnostic `_specs/` prefix, session-scoped
+ * path routing, and lazy creation — while the consumer owns the *physical*
+ * storage: which backend, under what prefix/tenancy, how durable, and for how
+ * long. A `SessionStore` is that consumer-side choice, made explicitly (or by the
+ * documented zero-config default) and mounted exactly once.
+ */
+// The id vocabulary is pure and lives in `session-id.ts`; re-exported so the
+// stores and the rule they enforce are reached from one module.
+export { DEFAULT_SESSIONS_DIR, SessionStoreIdError, sessionIdRejection };
+/**
+ * Thrown at assembly when a custom authored `backend` is supplied without an
+ * explicit `sessionStore`. The runtime never silently runs without session-scoped
+ * routing and never silently writes session state to local disk beside a
+ * virtual workspace — the consumer must name the storage.
+ */
+export class SessionStoreRequiredError extends Error {
+    constructor() {
+        super("A custom `backend` requires an explicit `sessionStore` for session state " +
+            "(checkpoints, artifacts, output, scratch). Pass one of: " +
+            "createFilesystemSessionStore({ dir }), createBackendSessionStore({ backend, prefix? }), " +
+            "or createMemorySessionStore().");
+        this.name = "SessionStoreRequiredError";
+    }
+}
+/** Thrown when a session operation needs a capability the configured store lacks. */
+export class SessionStoreCapabilityError extends Error {
+    storeKind;
+    capability;
+    constructor(storeKind, capability) {
+        super(`The configured ${storeKind} session store does not support '${capability}'. ` +
+            `Provide a store with that capability (e.g. createFilesystemSessionStore) to use it.`);
+        this.storeKind = storeKind;
+        this.capability = capability;
+        this.name = "SessionStoreCapabilityError";
+    }
+}
+/**
+ * Store-relative session id with traversal and reserved names contained: strips
+ * leading slashes, then rejects any id that would resolve outside its zone or
+ * shadow a reserved root name. Callers pass the id straight to `rmSync`/subtree
+ * deletion and to root-relative run paths, so this is the single point that keeps
+ * both inside the session zone.
+ */
+function containedSessionId(sessionId) {
+    const rejection = sessionIdRejection(sessionId);
+    if (rejection)
+        throw new SessionStoreIdError(sessionId, rejection);
+    return rel(sessionId);
+}
+/**
+ * Local-directory session store: a filesystem backend rooted at `dir`, with full
+ * listing and deletion capabilities. The zero-config default is this store at
+ * `<workspaceRoot>/sessions`.
+ */
+export function createFilesystemSessionStore(options) {
+    const dir = resolve(options.dir);
+    return {
+        kind: "filesystem",
+        backend: new FilesystemBackend({ rootDir: dir, virtualMode: true }),
+        capabilities: { list: true, delete: true },
+        async deleteSession(sessionId) {
+            const target = resolve(dir, containedSessionId(sessionId));
+            // Belt-and-suspenders: even with `..` rejected, assert the resolved path
+            // stays strictly under `dir` before touching real `fs`.
+            if (target !== dir && !target.startsWith(dir + sep)) {
+                throw new SessionStoreIdError(sessionId);
+            }
+            if (target === dir || !existsSync(target))
+                return false;
+            rmSync(target, { recursive: true, force: true });
+            return true;
+        },
+    };
+}
+/**
+ * Session store over any {@link BackendProtocolV2} (object storage, database,
+ * remote). The `prefix` is the consumer's tenancy/layout concern: it is
+ * applied inside the store and never appears in SDK-visible or agent-visible
+ * paths. Deletion is available only when the consumer supplies a
+ * `deleteSession` implementation (the backend protocol models no delete);
+ * listing can be disabled for backends whose `ls` cannot enumerate folders.
+ */
+export function createBackendSessionStore(options) {
+    const prefix = options.prefix ? rel(options.prefix).replace(/\/+$/, "") : "";
+    const backend = prefix ? mountSubtree(options.backend, prefix) : options.backend;
+    const capabilities = {
+        list: options.list ?? true,
+        delete: options.deleteSession !== undefined,
+    };
+    return {
+        kind: "backend",
+        backend,
+        capabilities,
+        async deleteSession(sessionId) {
+            if (!options.deleteSession)
+                throw new SessionStoreCapabilityError("backend", "delete");
+            return options.deleteSession(sessionId);
+        },
+    };
+}
+/**
+ * Ephemeral in-memory session store for tests and throwaway sessions: Deep
+ * Agents' own `StoreBackend` over a LangGraph `InMemoryStore`, so nothing
+ * touches the filesystem or any external service, and everything vanishes with
+ * the process. Overwrites in place like every Deep Agents backend from
+ * deepagents 1.12.0 on; fully listable and deletable.
+ */
+export function createMemorySessionStore() {
+    const store = new InMemoryStore();
+    const namespace = ["sessions"];
+    const backend = new StoreBackend({ store, namespace });
+    return {
+        kind: "memory",
+        backend,
+        capabilities: { list: true, delete: true },
+        async deleteSession(sessionId) {
+            const id = containedSessionId(sessionId);
+            // Collect first, then delete: the store's pagination is by offset.
+            const keys = [];
+            const limit = 500;
+            for (let offset = 0;; offset += limit) {
+                const page = await store.search(namespace, { limit, offset });
+                for (const item of page) {
+                    const key = String(item.key);
+                    if (key === `/${id}` || key.startsWith(`/${id}/`) || key === id || key.startsWith(`${id}/`)) {
+                        keys.push(key);
+                    }
+                }
+                if (page.length < limit)
+                    break;
+            }
+            await Promise.all(keys.map((key) => store.delete(namespace, key)));
+            return keys.length > 0;
+        },
+    };
+}
+//# sourceMappingURL=session-store.js.map

package/dist/core/session-store.js.map

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

package/dist/core/session-zone.d.ts

@@ -0,0 +1,54 @@
+import type { BackendProtocolV2 } from "deepagents";
+/**
+ * The session zone — the agent's workspace **root**: durable per-session
+ * checkpoints, observability artifacts, the agent's `scratchpad/…` working area, the
+ * always-writable `scratchpad/…`, and the runtime's context-offload areas, all
+ * served by the configured session store as the default route of the workspace
+ * `CompositeBackend`.
+ *
+ * Three calling conventions share this one root, disambiguated by path shape
+ * rather than by whether a session happens to be bound:
+ *
+ *  - **Runtime-internal, already-qualified paths** (e.g.
+ *    `<sessionId>/checkpoints/cp-1.json`, built by `sessionPaths`) — the
+ *    checkpoint saver and run-artifact writers address their own session's
+ *    folder explicitly. These pass through unmodified, whether or not a session
+ *    happens to be bound at the time (some, like the inner Deep Agent's own
+ *    checkpoint writes, run *during* a bound turn; others, like
+ *    `listSessions()`, run outside any turn).
+ *  - **Session-agnostic reserved paths** (`_specs/<hash>.json`) — content
+ *    addressed and shared by every session on the same spec version, so they
+ *    resolve at the store root even while a session is bound.
+ *  - **Agent-visible, id-free paths** (e.g. `scratchpad/notes.txt`) — issued by
+ *    tool calls while a session's turn is executing. The currently bound
+ *    session id (see {@link sessionScoped}) is prefixed on before delegating, and
+ *    stripped back off the paths results carry, so the id never appears in an
+ *    agent-visible listing.
+ *
+ * A path is treated as "already qualified" when it (ignoring a leading `/`)
+ * equals or starts with the bound session id — safe because internal callers
+ * only ever address their own currently-bound session's folder, and a session id
+ * may not collide with a reserved root name.
+ */
+export declare class SessionZoneRouter implements BackendProtocolV2 {
+    private readonly binding;
+    private readonly routed;
+    constructor(backend: BackendProtocolV2);
+    /**
+     * Bind id-free run-root addressing to `sessionId` for everything `fn` does
+     * (the binding propagates through async continuations, so a whole agent
+     * turn — including lifecycle hooks, sandboxed scripts, and the inner
+     * agent's own checkpoint writes — is covered by wrapping its `invoke`).
+     * Concurrent sessions each carry their own binding.
+     */
+    sessionScoped<T>(sessionId: string, fn: () => Promise<T>): Promise<T>;
+    /** The session id bound to the current async context, if any. */
+    boundSessionId(): string | undefined;
+    ls(path: string): import("deepagents").MaybePromise<import("deepagents").LsResult>;
+    read(filePath: string, offset?: number, limit?: number): import("deepagents").MaybePromise<import("deepagents").ReadResult>;
+    readRaw(filePath: string): import("deepagents").MaybePromise<import("deepagents").ReadRawResult>;
+    grep(pattern: string, path?: string | null, glob?: string | null): import("deepagents").MaybePromise<import("deepagents").GrepResult>;
+    glob(pattern: string, path?: string): import("deepagents").MaybePromise<import("deepagents").GlobResult>;
+    write(filePath: string, content: string): import("deepagents").MaybePromise<import("deepagents").WriteResult>;
+    edit(filePath: string, oldString: string, newString: string, replaceAll?: boolean): import("deepagents").MaybePromise<import("deepagents").EditResult>;
+}

package/dist/core/session-zone.js

@@ -0,0 +1,82 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { mountSubtree } from "./path-mapping.js";
+import { isSessionAgnosticPath } from "./zones.js";
+/**
+ * The session zone — the agent's workspace **root**: durable per-session
+ * checkpoints, observability artifacts, the agent's `scratchpad/…` working area, the
+ * always-writable `scratchpad/…`, and the runtime's context-offload areas, all
+ * served by the configured session store as the default route of the workspace
+ * `CompositeBackend`.
+ *
+ * Three calling conventions share this one root, disambiguated by path shape
+ * rather than by whether a session happens to be bound:
+ *
+ *  - **Runtime-internal, already-qualified paths** (e.g.
+ *    `<sessionId>/checkpoints/cp-1.json`, built by `sessionPaths`) — the
+ *    checkpoint saver and run-artifact writers address their own session's
+ *    folder explicitly. These pass through unmodified, whether or not a session
+ *    happens to be bound at the time (some, like the inner Deep Agent's own
+ *    checkpoint writes, run *during* a bound turn; others, like
+ *    `listSessions()`, run outside any turn).
+ *  - **Session-agnostic reserved paths** (`_specs/<hash>.json`) — content
+ *    addressed and shared by every session on the same spec version, so they
+ *    resolve at the store root even while a session is bound.
+ *  - **Agent-visible, id-free paths** (e.g. `scratchpad/notes.txt`) — issued by
+ *    tool calls while a session's turn is executing. The currently bound
+ *    session id (see {@link sessionScoped}) is prefixed on before delegating, and
+ *    stripped back off the paths results carry, so the id never appears in an
+ *    agent-visible listing.
+ *
+ * A path is treated as "already qualified" when it (ignoring a leading `/`)
+ * equals or starts with the bound session id — safe because internal callers
+ * only ever address their own currently-bound session's folder, and a session id
+ * may not collide with a reserved root name.
+ */
+export class SessionZoneRouter {
+    binding = new AsyncLocalStorage();
+    routed;
+    constructor(backend) {
+        this.routed = mountSubtree(backend, () => this.binding.getStore(), {
+            // Session-agnostic prefixes resolve to the run-store root whether or not a
+            // session is bound: a spec snapshot is shared across sessions, and the
+            // session index has to be readable before a session is chosen at all.
+            passthrough: (rel, prefix) => rel === prefix || rel.startsWith(`${prefix}/`) || isSessionAgnosticPath(rel),
+        });
+    }
+    /**
+     * Bind id-free run-root addressing to `sessionId` for everything `fn` does
+     * (the binding propagates through async continuations, so a whole agent
+     * turn — including lifecycle hooks, sandboxed scripts, and the inner
+     * agent's own checkpoint writes — is covered by wrapping its `invoke`).
+     * Concurrent sessions each carry their own binding.
+     */
+    sessionScoped(sessionId, fn) {
+        return this.binding.run(sessionId, fn);
+    }
+    /** The session id bound to the current async context, if any. */
+    boundSessionId() {
+        return this.binding.getStore();
+    }
+    ls(path) {
+        return this.routed.ls(path);
+    }
+    read(filePath, offset, limit) {
+        return this.routed.read(filePath, offset, limit);
+    }
+    readRaw(filePath) {
+        return this.routed.readRaw(filePath);
+    }
+    grep(pattern, path, glob) {
+        return this.routed.grep(pattern, path, glob);
+    }
+    glob(pattern, path) {
+        return this.routed.glob(pattern, path);
+    }
+    write(filePath, content) {
+        return this.routed.write(filePath, content);
+    }
+    edit(filePath, oldString, newString, replaceAll) {
+        return this.routed.edit(filePath, oldString, newString, replaceAll);
+    }
+}
+//# sourceMappingURL=session-zone.js.map

package/dist/core/session-zone.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-zone.js","sourceRoot":"","sources":["../../src/core/session-zone.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,MAAM,OAAO,iBAAiB;IACX,OAAO,GAAG,IAAI,iBAAiB,EAAU,CAAC;IAC1C,MAAM,CAAoB;IAE3C,YAAY,OAA0B;QACpC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE;YACjE,2EAA2E;YAC3E,uEAAuE;YACvE,sEAAsE;YACtE,WAAW,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAC3B,GAAG,KAAK,MAAM,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,MAAM,GAAG,CAAC,IAAI,qBAAqB,CAAC,GAAG,CAAC;SAC/E,CAAC,CAAC;IACL,CAAC;IAED;;;;;;OAMG;IACH,aAAa,CAAI,SAAiB,EAAE,EAAoB;QACtD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IACzC,CAAC;IAED,iEAAiE;IACjE,cAAc;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC;IACjC,CAAC;IAED,EAAE,CAAC,IAAY;QACb,OAAO,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;IAED,IAAI,CAAC,QAAgB,EAAE,MAAe,EAAE,KAAc;QACpD,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;IAED,OAAO,CAAC,QAAgB;QACtB,OAAO,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IACvC,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAoB,EAAE,IAAoB;QAC9D,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAC/C,CAAC;IAED,IAAI,CAAC,OAAe,EAAE,IAAa;QACjC,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IACzC,CAAC;IAED,KAAK,CAAC,QAAgB,EAAE,OAAe;QACrC,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC9C,CAAC;IAED,IAAI,CAAC,QAAgB,EAAE,SAAiB,EAAE,SAAiB,EAAE,UAAoB;QAC/E,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,UAAU,CAAC,CAAC;IACtE,CAAC;CACF"}

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

@@ -0,0 +1,31 @@
+import type { SkillRegistry } from "./skills.js";
+/**
+ * The model-facing account of the skills a state may use — rendered by the
+ * runtime rather than delegated to the upstream skills middleware.
+ *
+ * Upstream renders one section, once, from a whole source directory: its
+ * `sources` are fixed at construction and its result is cached in a closure, so
+ * nothing about it can vary per state. Under a governed workflow that is exactly
+ * the wrong shape — a state that may use one capability would be told about
+ * three, two of which the kernel refuses. So the runtime renders this instead,
+ * from the same resolved set the kernel enforces, into the **volatile** system
+ * block (see `workflow/middleware.ts`), which is where anything that changes
+ * with the state belongs.
+ *
+ * What it says is the Agent Skills progressive-disclosure contract itself and
+ * nothing more: the slug, what the skill is for, and where to read the rest.
+ */
+/** Heading of the rendered section, also the marker tests assert on. */
+export declare const SKILLS_SECTION_HEADING = "Skills available in this state";
+/**
+ * Render the section for one state's enabled skills, or `null` when the set is
+ * empty — a state that may use no skill gets no heading rather than an empty
+ * one, and therefore no invitation to go looking.
+ *
+ * `enabled` is the resolved slug order (see `WorkflowMachine.enabledSkills`), so
+ * the text is byte-identical on every model call of a turn and on every
+ * re-entry: a prompt section that reordered itself would churn the transcript
+ * for no reason. A slug with no registry entry is skipped rather than rendered
+ * as a bare name — the description is the whole value of disclosing it.
+ */
+export declare function renderSkillsSection(enabled: readonly string[], registry: SkillRegistry): string | null;