@archmax-ai/harness 0.0.0

package/dist/core/zones.d.ts

@@ -0,0 +1,181 @@
+/**
+ * The workspace root namespace — and the one thing in it the framework owns.
+ *
+ * The root **is the current run**: the executing session's folder in the
+ * configured session store, served as the default route of the workspace
+ * `CompositeBackend`. The framework's path vocabulary stops at the run areas
+ * below; **which directories are authored is workspace shape, not framework
+ * knowledge**, resolved per assembly into an {@link AuthoredMounts} table by
+ * discovery or consumer declaration (see {@link resolveAuthoredMounts}).
+ *
+ * Every consumer that needs to know "which zone is this path in?" — the decision
+ * kernel, the workspace router's routing and root shaping, and static
+ * validation — classifies through {@link classifyWorkspacePath} with that one
+ * resolved table, so runtime enforcement and validation cannot disagree.
+ */
+/**
+ * The mount keys of one workspace, split by shape and write posture — the input
+ * every path classification takes. Produced by `resolveMounts` (`core/mounts.ts`)
+ * from the very keys the composite routes on, so routing and classification cannot
+ * drift. Declared here, with the classifier that consumes it, so this namespace
+ * module stays a leaf: composition depends on classification, never the reverse.
+ */
+export interface MountPrefixes {
+    /** Directory mount names (no slashes), e.g. `["skills", "workflows"]`. */
+    readonly dirs: readonly string[];
+    /** Exact-path file mount names, e.g. `["AGENTS.md"]`. */
+    readonly files: readonly string[];
+    /** Names of mounts declared writable; excluded from the read-only rules. */
+    readonly writable: readonly string[];
+    /**
+     * Names of mounts the host declared `governed`: closed by default, reachable
+     * only from the states a `mounts` list enables (see
+     * `WorkflowMachine.enabledMounts`). A name absent from this list is visible
+     * in every state, which is what every table without the flag resolves to.
+     */
+    readonly governed: readonly string[];
+    /**
+     * Names of directory mounts the host declared `searchable: false`: the
+     * runtime never searches them on its own initiative (a root-wide `grep` or
+     * `glob` skips them), while a search addressed at one still reaches its
+     * backend so the backend can answer with its own refusal. A file mount is
+     * never listed here — a file is not searched as a tree. Not a governance
+     * concern: the kernel and `validate` do not read it.
+     */
+    readonly unsearchable: readonly string[];
+}
+/** No mounts: every path resolves in the run root. */
+export declare const NO_MOUNTS: MountPrefixes;
+/**
+ * Runtime-internal run areas: checkpoint records, observability artifacts, and
+ * the cross-session content-addressed spec snapshots. Written by the runtime
+ * through the workspace, never addressable by agent tools.
+ */
+export declare const SESSION_INTERNAL_DIRS: readonly ["checkpoints", "artifacts", "_specs"];
+/**
+ * Context-offload areas. Deep Agents' filesystem and summarization middleware
+ * write to these fixed root paths when a tool result or human message exceeds
+ * its eviction threshold, and hand the model a pointer to read back. Because
+ * the session store serves the root, they land in `<sessionId>/…` with no upstream
+ * patching. Agent-readable (it must follow the pointer), never agent-writable.
+ */
+export declare const SESSION_OFFLOAD_DIRS: readonly ["large_tool_results", "conversation_history"];
+/**
+ * The run's working area: intermediate files *and* the results a state produces.
+ * Always agent-readable/writable, independent of state policy — one area, so an
+ * author never has to decide which of two working directories a file belongs in.
+ *
+ * Being always-open is the trade: a state cannot narrow *where inside it* a write
+ * may land. A workflow that needs the write itself governed names an ordinary run
+ * path instead (anything else in the root classifies as `run`, matched against the
+ * state's `tools.allow` like any other argument).
+ */
+export declare const SESSION_OPEN_DIR = "scratchpad";
+/**
+ * Cross-session reserved prefix inside the session store, resolved at the store
+ * root whether or not a session is bound (see `SessionZoneRouter`).
+ */
+export declare const SESSION_AGNOSTIC_PREFIX = "_specs";
+/**
+ * Store prefixes that resolve to the root whether or not a session is bound:
+ * data shared across sessions, like a spec snapshot. One list, so a second such
+ * prefix is a one-line change.
+ */
+export declare const SESSION_AGNOSTIC_PREFIXES: readonly string[];
+/** Whether a run-store-relative path addresses a session-agnostic prefix. */
+export declare function isSessionAgnosticPath(rel: string): boolean;
+/**
+ * Zone of a canonical workspace path:
+ *
+ * - `authored` — read-only authored mount or authored root file
+ * - `run-internal` — runtime-only run area (no agent access)
+ * - `run-offload` — runtime-managed offload area (agent read-only)
+ * - `run-open` — `scratchpad/…` (always agent read/write)
+ * - `run` — anything else in the run root; governed by the active state's
+ *   `tools.allow`
+ * - `escapes` — climbs above the workspace root
+ * - `root` — the workspace root itself
+ */
+export type WorkspaceZone = "authored" | "run-internal" | "run-offload" | "run-open" | "run" | "escapes" | "root";
+/**
+ * Session-area names the framework owns at the workspace root. An authored
+ * directory may not shadow one of these, and a session id may not be one of them.
+ */
+export declare function sessionAreaNames(): string[];
+/** @deprecated Older spelling of {@link sessionAreaNames}; kept for one release. */
+export declare const runAreaNames: typeof sessionAreaNames;
+/**
+ * The authoring prefixes: the workspace-root names holding what the **runtime**
+ * reads. `workflows/` carries the machine specs — grading rubrics included — the
+ * prose addenda, the lifecycle hook scripts, and the offline test cases a session
+ * is enforced with. It is served by the *authoring* backend and is not routed into
+ * the agent's workspace composite.
+ *
+ * It is reserved rather than merely omitted: a workspace that mounted it would hand
+ * a session its own spec, its sibling workflows' specs, the tests grading it, and
+ * the criteria (with the iteration budget) of the rubric that vetoes it. Refusing
+ * the key makes the isolation a property of composition instead of a rule
+ * something downstream could relax.
+ *
+ * Still a **set**, though it holds one member: the classification is the contract
+ * and its cardinality is incidental. One list, three consumers — mount resolution,
+ * the decision kernel's script diagnostic, and static validation — so a further
+ * prefix is a one-line change and the three can never disagree about what the
+ * authoring backend serves. Declared here, with the rest of the root namespace
+ * vocabulary, so a browser-safe consumer can read it without the mount composition.
+ */
+export declare const AUTHORING_PREFIXES: readonly ["workflows"];
+/** A root name on the authoring backend. */
+export type AuthoringPrefix = (typeof AUTHORING_PREFIXES)[number];
+/** Whether a bare root name is an authoring prefix. */
+export declare function isAuthoringPrefix(name: string): name is AuthoringPrefix;
+/**
+ * The authoring prefix a **canonicalized** relative path addresses, or `null`
+ * when it addresses none. The matched prefix is returned rather than a boolean so
+ * a caller can name it — and describe its content with
+ * {@link describeAuthoringPrefix} — in the diagnostic it produces.
+ */
+export declare function authoringPlanePrefix(rel: string): AuthoringPrefix | null;
+/** The noun phrase naming what an authoring prefix holds. */
+export declare function describeAuthoringPrefix(prefix: AuthoringPrefix): string;
+/**
+ * The mount name a **canonicalized** relative path addresses, or `null` when it
+ * addresses none — the longest matching name, so a nested key (`catalogs/eu`)
+ * wins over a single-segment one (`catalogs`) mounted beside it, and a sibling
+ * under the same first segment (`catalogs/uk`) matches neither.
+ *
+ * Longest prefix rather than first segment because a mount key of several
+ * segments is an ordinary mount: the composite already routes the longer prefix
+ * first, so classification has to agree or a nested mount would be governed as
+ * a run path.
+ */
+export declare function mountNameOf(rel: string, mounts?: MountPrefixes): string | null;
+/**
+ * Whether a glob or path pattern can only ever match inside one mount — the
+ * shape `validate` needs to spot a `tools.allow` entry that contradicts the
+ * state's enabled mounts. Returns the mount name when the pattern's literal
+ * prefix (everything before its first wildcard) is already inside a mount, else
+ * `null`: a broader pattern is left to the runtime rule, which refuses the
+ * unreachable paths call by call.
+ */
+export declare function mountNameOfPattern(pattern: string, mounts?: MountPrefixes): string | null;
+/**
+ * Classify a workspace path against the workspace's resolved authored mounts.
+ * Canonicalizes first (leading slashes stripped, `.`/`//` segments dropped, `..`
+ * applied) so equivalent spellings — `./data/x`, `//data/x`, `data/./x` — land in
+ * the same zone and none can be dodged with a prefix.
+ *
+ * With no table supplied, nothing classifies as `authored` — a caller probing the
+ * kernel in isolation gets run-state classification. That is safe because authored
+ * mounts refuse writes themselves (see `mountSubtree({ readOnly })`), so the
+ * kernel's read-only rule is the diagnostic layer rather than the only enforcement.
+ */
+export declare function classifyWorkspacePath(path: string, mounts?: MountPrefixes): WorkspaceZone;
+/**
+ * Whether `name` is reserved at the workspace root. Used to refuse a session id
+ * that would route its own run folder (`<sessionId>/checkpoints/…`) into a run
+ * area or a declared mount. Without a mount table only the framework-owned run
+ * areas are reserved — a colliding mount name then fails loudly at the read-only
+ * mount instead of silently corrupting authored content.
+ */
+export declare function isReservedRootName(name: string, mounts?: MountPrefixes): boolean;

package/dist/core/zones.js

@@ -0,0 +1,202 @@
+import { canonicalizeRelPath } from "./workspace.js";
+/** No mounts: every path resolves in the run root. */
+export const NO_MOUNTS = {
+    dirs: [],
+    files: [],
+    writable: [],
+    governed: [],
+    unsearchable: [],
+};
+/**
+ * Runtime-internal run areas: checkpoint records, observability artifacts, and
+ * the cross-session content-addressed spec snapshots. Written by the runtime
+ * through the workspace, never addressable by agent tools.
+ */
+export const SESSION_INTERNAL_DIRS = ["checkpoints", "artifacts", "_specs"];
+/**
+ * Context-offload areas. Deep Agents' filesystem and summarization middleware
+ * write to these fixed root paths when a tool result or human message exceeds
+ * its eviction threshold, and hand the model a pointer to read back. Because
+ * the session store serves the root, they land in `<sessionId>/…` with no upstream
+ * patching. Agent-readable (it must follow the pointer), never agent-writable.
+ */
+export const SESSION_OFFLOAD_DIRS = ["large_tool_results", "conversation_history"];
+/**
+ * The run's working area: intermediate files *and* the results a state produces.
+ * Always agent-readable/writable, independent of state policy — one area, so an
+ * author never has to decide which of two working directories a file belongs in.
+ *
+ * Being always-open is the trade: a state cannot narrow *where inside it* a write
+ * may land. A workflow that needs the write itself governed names an ordinary run
+ * path instead (anything else in the root classifies as `run`, matched against the
+ * state's `tools.allow` like any other argument).
+ */
+export const SESSION_OPEN_DIR = "scratchpad";
+/**
+ * Cross-session reserved prefix inside the session store, resolved at the store
+ * root whether or not a session is bound (see `SessionZoneRouter`).
+ */
+export const SESSION_AGNOSTIC_PREFIX = "_specs";
+/**
+ * Store prefixes that resolve to the root whether or not a session is bound:
+ * data shared across sessions, like a spec snapshot. One list, so a second such
+ * prefix is a one-line change.
+ */
+export const SESSION_AGNOSTIC_PREFIXES = [SESSION_AGNOSTIC_PREFIX];
+/** Whether a run-store-relative path addresses a session-agnostic prefix. */
+export function isSessionAgnosticPath(rel) {
+    return SESSION_AGNOSTIC_PREFIXES.some((prefix) => rel === prefix || rel.startsWith(`${prefix}/`));
+}
+const INTERNAL_DIR_SET = new Set(SESSION_INTERNAL_DIRS);
+const OFFLOAD_DIR_SET = new Set(SESSION_OFFLOAD_DIRS);
+/**
+ * Session-area names the framework owns at the workspace root. An authored
+ * directory may not shadow one of these, and a session id may not be one of them.
+ */
+export function sessionAreaNames() {
+    return [
+        ...SESSION_INTERNAL_DIRS,
+        ...SESSION_OFFLOAD_DIRS,
+        SESSION_OPEN_DIR,
+    ];
+}
+/** @deprecated Older spelling of {@link sessionAreaNames}; kept for one release. */
+export const runAreaNames = sessionAreaNames;
+const SESSION_AREA_SET = new Set(sessionAreaNames());
+// --- The authoring prefixes ------------------------------------------------------
+/**
+ * The authoring prefixes: the workspace-root names holding what the **runtime**
+ * reads. `workflows/` carries the machine specs — grading rubrics included — the
+ * prose addenda, the lifecycle hook scripts, and the offline test cases a session
+ * is enforced with. It is served by the *authoring* backend and is not routed into
+ * the agent's workspace composite.
+ *
+ * It is reserved rather than merely omitted: a workspace that mounted it would hand
+ * a session its own spec, its sibling workflows' specs, the tests grading it, and
+ * the criteria (with the iteration budget) of the rubric that vetoes it. Refusing
+ * the key makes the isolation a property of composition instead of a rule
+ * something downstream could relax.
+ *
+ * Still a **set**, though it holds one member: the classification is the contract
+ * and its cardinality is incidental. One list, three consumers — mount resolution,
+ * the decision kernel's script diagnostic, and static validation — so a further
+ * prefix is a one-line change and the three can never disagree about what the
+ * authoring backend serves. Declared here, with the rest of the root namespace
+ * vocabulary, so a browser-safe consumer can read it without the mount composition.
+ */
+export const AUTHORING_PREFIXES = ["workflows"];
+/**
+ * What each prefix holds, as a noun phrase a diagnostic can drop into a sentence.
+ * Kept per-prefix rather than collapsed into "the authoring backend" so a
+ * diagnostic describes the prefix the consumer actually named.
+ */
+const AUTHORING_CONTENT = {
+    workflows: "machine specs, grading rubrics, hook scripts, and test cases",
+};
+/** Whether a bare root name is an authoring prefix. */
+export function isAuthoringPrefix(name) {
+    return AUTHORING_PREFIXES.includes(name);
+}
+/**
+ * The authoring prefix a **canonicalized** relative path addresses, or `null`
+ * when it addresses none. The matched prefix is returned rather than a boolean so
+ * a caller can name it — and describe its content with
+ * {@link describeAuthoringPrefix} — in the diagnostic it produces.
+ */
+export function authoringPlanePrefix(rel) {
+    for (const prefix of AUTHORING_PREFIXES) {
+        if (rel === prefix || rel.startsWith(`${prefix}/`))
+            return prefix;
+    }
+    return null;
+}
+/** The noun phrase naming what an authoring prefix holds. */
+export function describeAuthoringPrefix(prefix) {
+    return AUTHORING_CONTENT[prefix];
+}
+/**
+ * The mount name a **canonicalized** relative path addresses, or `null` when it
+ * addresses none — the longest matching name, so a nested key (`catalogs/eu`)
+ * wins over a single-segment one (`catalogs`) mounted beside it, and a sibling
+ * under the same first segment (`catalogs/uk`) matches neither.
+ *
+ * Longest prefix rather than first segment because a mount key of several
+ * segments is an ordinary mount: the composite already routes the longer prefix
+ * first, so classification has to agree or a nested mount would be governed as
+ * a run path.
+ */
+export function mountNameOf(rel, mounts = NO_MOUNTS) {
+    let match = null;
+    for (const name of mounts.dirs) {
+        if ((rel === name || rel.startsWith(`${name}/`)) && name.length > (match?.length ?? -1)) {
+            match = name;
+        }
+    }
+    for (const name of mounts.files) {
+        // A file mount is an exact path: `AGENTS.md.bak` is not captured.
+        if (rel === name && name.length > (match?.length ?? -1))
+            match = name;
+    }
+    return match;
+}
+/**
+ * Whether a glob or path pattern can only ever match inside one mount — the
+ * shape `validate` needs to spot a `tools.allow` entry that contradicts the
+ * state's enabled mounts. Returns the mount name when the pattern's literal
+ * prefix (everything before its first wildcard) is already inside a mount, else
+ * `null`: a broader pattern is left to the runtime rule, which refuses the
+ * unreachable paths call by call.
+ */
+export function mountNameOfPattern(pattern, mounts = NO_MOUNTS) {
+    const literal = canonicalizeRelPath(pattern).path.split(/[*?[{]/, 1)[0] ?? "";
+    const upToSegment = literal.slice(0, literal.lastIndexOf("/") + 1).replace(/\/+$/, "");
+    if (upToSegment === "")
+        return null;
+    return mountNameOf(upToSegment, mounts);
+}
+/**
+ * Classify a workspace path against the workspace's resolved authored mounts.
+ * Canonicalizes first (leading slashes stripped, `.`/`//` segments dropped, `..`
+ * applied) so equivalent spellings — `./data/x`, `//data/x`, `data/./x` — land in
+ * the same zone and none can be dodged with a prefix.
+ *
+ * With no table supplied, nothing classifies as `authored` — a caller probing the
+ * kernel in isolation gets run-state classification. That is safe because authored
+ * mounts refuse writes themselves (see `mountSubtree({ readOnly })`), so the
+ * kernel's read-only rule is the diagnostic layer rather than the only enforcement.
+ */
+export function classifyWorkspacePath(path, mounts = NO_MOUNTS) {
+    const { path: rel, escapes } = canonicalizeRelPath(path);
+    if (escapes)
+        return "escapes";
+    if (rel === "")
+        return "root";
+    const [top] = rel.split("/");
+    const mount = mountNameOf(rel, mounts);
+    // A writable mount is not authored: its paths are governed like run paths.
+    if (mount != null && !mounts.writable.includes(mount))
+        return "authored";
+    if (INTERNAL_DIR_SET.has(top))
+        return "run-internal";
+    if (OFFLOAD_DIR_SET.has(top))
+        return "run-offload";
+    if (top === SESSION_OPEN_DIR)
+        return "run-open";
+    return "run";
+}
+/**
+ * Whether `name` is reserved at the workspace root. Used to refuse a session id
+ * that would route its own run folder (`<sessionId>/checkpoints/…`) into a run
+ * area or a declared mount. Without a mount table only the framework-owned run
+ * areas are reserved — a colliding mount name then fails loudly at the read-only
+ * mount instead of silently corrupting authored content.
+ */
+export function isReservedRootName(name, mounts = NO_MOUNTS) {
+    if (SESSION_AREA_SET.has(name))
+        return true;
+    // A nested mount name reserves its own first segment too: a session folder
+    // called `catalogs` would route `catalogs/eu/…` into the mount.
+    const firstSegments = [...mounts.dirs, ...mounts.files].map((mount) => mount.split("/")[0]);
+    return firstSegments.includes(name);
+}
+//# sourceMappingURL=zones.js.map

package/dist/core/zones.js.map

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

package/dist/env.d.ts

@@ -0,0 +1,99 @@
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { ChatOpenAI } from "@langchain/openai";
+import { type PricingTable } from "./core/usage.js";
+/**
+ * Package install root — the directory containing this file's parent (`dist/`
+ * when published/built, `src/` in development). Used only to locate assets
+ * bundled with the package, never the consumer's workspace or configuration.
+ */
+export declare const PACKAGE_ROOT: string;
+/** Installed package implementation version, read from the package's `package.json`. */
+export declare const PACKAGE_VERSION: string;
+/**
+ * The authoring skill bundled with the package — the parent directory holding
+ * `archmax-harness/` (`SKILL.md` + `references/*.md`), which teaches a coding agent how
+ * to author a workspace. Resolved to `dist/authoring-skill` when built or
+ * installed, with a repo-checkout fallback to the top-level `skills/` when
+ * running from `src/`. Consumers mount it directly so the skill always matches
+ * the installed SDK version instead of a synced copy.
+ */
+export declare const BUNDLED_AUTHORING_SKILL_DIR: string;
+/** @deprecated Use {@link BUNDLED_AUTHORING_SKILL_DIR}; same value, kept for one release. */
+export declare const BUNDLED_SKILLS_DIR: string;
+/** Resolve the agent workspace root: an explicit path, else the consumer's cwd. */
+export declare function resolveWorkspaceRoot(rootDir?: string): string;
+/**
+ * Load `.env` from the resolved workspace root (or cwd) if present.
+ *
+ * Two rules, in this order: the real process environment always wins, and a
+ * later `.env` wins over an earlier one. The second is why this does not just
+ * call `dotenv.config` — dotenv never overrides an already-set variable, and it
+ * cannot tell its own earlier assignment from a real environment variable. The
+ * import-time cwd load below is an earlier one, so without the distinction a
+ * stray `.env` in whatever directory the process happened to start in would
+ * silently outrank the workspace root that owns the configuration (issue #23).
+ */
+export declare function loadDotenv(rootDir?: string): void;
+export interface AgentEnv {
+    apiBaseUrl: string;
+    apiKey: string;
+    model: string;
+    temperature?: number;
+    maxTokens?: number;
+    /**
+     * Whether the model streams responses (default true). Streaming is what
+     * makes `agent-text-delta` lifecycle events flow; invoke results are
+     * unchanged. Set `ARCHMAX_STREAMING=0` for OpenAI-compatible endpoints that
+     * misbehave under SSE.
+     */
+    streaming?: boolean;
+}
+/** Read the OpenAI-compatible model configuration from the `ARCHMAX_*` environment keys. */
+export declare function loadEnv(): AgentEnv;
+/** Build a `ChatOpenAI` model pointed at any OpenAI-compatible endpoint. */
+export declare function createChatModel(env?: AgentEnv): ChatOpenAI;
+/**
+ * Prompt-cache configuration from the environment: `ARCHMAX_PROMPT_CACHE`
+ * (default on) and `ARCHMAX_PROMPT_CACHE_TTL` (`5m` | `1h`).
+ */
+export declare function loadPromptCacheEnv(): {
+    enabled?: boolean;
+    ttl?: string;
+};
+/**
+ * Token prices from the environment, in USD per 1M tokens, applying to whatever
+ * model is configured: `ARCHMAX_PRICE_INPUT`, `ARCHMAX_PRICE_OUTPUT`,
+ * `ARCHMAX_PRICE_CACHE_READ`, `ARCHMAX_PRICE_CACHE_WRITE`. Returns `undefined`
+ * when none are set, so cost is omitted rather than reported as zero.
+ */
+export declare function loadPricingEnv(): PricingTable | undefined;
+/**
+ * The role a model plays in the runtime: the workflow `agent` (turns), a `judge`
+ * (the offline case grader), or a `rubric` (a grading rubric dispatched by a
+ * lifecycle hook). A {@link ModelFactory} may return a different model per role.
+ */
+export type ModelRole = "agent" | "judge" | "rubric";
+/**
+ * Supplies the chat model for a given role, so library users can run the runtime
+ * against any LangChain `BaseChatModel` (e.g. Amazon Bedrock via
+ * `ChatBedrockConverse`) without forking. The default
+ * ({@link defaultModelFactory}) is role-independent and returns the
+ * env-configured OpenAI-compatible model, so existing `.env` setups and the
+ * bundled offline test cases are unchanged.
+ *
+ * `env` is a thunk, not a value: a factory that brings its own credentials (a
+ * host resolving the model from its own configuration) never calls it, and
+ * {@link loadEnv} — which throws on a missing `ARCHMAX_API_BASE_URL` — is then
+ * never reached. Calling it more than once is cheap; the assembly memoizes.
+ */
+export type ModelFactory = (role: ModelRole, env: () => AgentEnv, 
+/**
+ * The model id the caller asked for — today, the `model` a grading rubric
+ * declares. Additive: a factory that ignores it behaves exactly as one written
+ * before rubrics could name a model, and no error is raised for an unhonoured
+ * request. The default factory applies it over `ARCHMAX_MODEL`, keeping the
+ * configured endpoint and credentials.
+ */
+requested?: string) => BaseChatModel;
+/** The default, role-independent model factory: the env-configured `ChatOpenAI`. */
+export declare const defaultModelFactory: ModelFactory;