@archmax-ai/harness 0.0.0

package/dist/public/sandbox.js

@@ -0,0 +1,32 @@
+/**
+ * `@archmax-ai/harness/sandbox` — the typed authoring surface for lifecycle hook
+ * scripts. Inside the QuickJS sandbox these names are provided by the prelude
+ * and the import line is stripped before evaluation; importing from here buys
+ * IDE completion for the hook input, nothing at runtime.
+ *
+ * ```js
+ * import { veto, ok } from "@archmax-ai/harness/sandbox";
+ * /** Vetoes a refund the policy forbids. *\/
+ * export default async function hook({ state, phase, variables, messages, tools }) {
+ *   const refund = JSON.parse(await tools.readFile({ file_path: "scratchpad/refund.json" }));
+ *   if (refund.decision !== "denied") return veto(`order ${refund.orderId} is not eligible`);
+ *   return ok();
+ * }
+ * ```
+ *
+ * Returning nothing is `ok`; throwing is a veto (hooks are fail-closed).
+ */
+export function ok(reason = "ok") {
+    return { verdict: "ok", reason };
+}
+export function veto(reason) {
+    return { verdict: "veto", reason };
+}
+export function correct(reason) {
+    return { verdict: "correct", reason };
+}
+/** Alias for `export default`: `export default defineHook(async (input) => …)`. Identity at runtime. */
+export function defineHook(fn) {
+    return fn;
+}
+//# sourceMappingURL=sandbox.js.map

package/dist/public/sandbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sandbox.js","sourceRoot":"","sources":["../../src/public/sandbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAmFH,MAAM,UAAU,EAAE,CAAC,MAAM,GAAG,IAAI;IAC9B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AACnC,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,MAAc;IACjC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC;AACrC,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,MAAc;IACpC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC;AACxC,CAAC;AAED,wGAAwG;AACxG,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,EAAE,CAAC;AACZ,CAAC"}

package/dist/public/spec.d.ts

@@ -0,0 +1,147 @@
+/**
+ * `@archmax-ai/harness/spec` — the workflow vocabulary with **no runtime behind it**:
+ * the `workflow.yaml` schema, the pure validator, the slug, variable and
+ * session-path grammars, the reserved names and the path conventions.
+ *
+ * Browser-safe by construction: nothing reachable from here imports `node:*`,
+ * LangGraph, Deep Agents, the sandbox or a filesystem library, and a unit test
+ * walks this module's import graph to keep it that way. An editor bundles it
+ * into a page; an API request path that only has to parse or validate a spec
+ * imports it without loading the runtime.
+ *
+ * What is **not** here, because it cannot be pure: loading a spec from a
+ * backend (`loadMachineSpec`), compiling one (`WorkflowMachine`), the full
+ * validator (`validateWorkflow`, which also probes the kernel and reads hook
+ * scripts), resolving a trigger against a machine, and every store and mount.
+ * Those stay on the package root.
+ *
+ * Several names here are also on the root. That is deliberate: this subpath
+ * exists for the weight of the import, not to move the names — and a test pins
+ * that a shared name is the same binding on both.
+ */
+export { 
+/** The whole `workflow.yaml` document. Parse with it and pass the **output** on; never compose it into another schema. */
+machineSpecSchema, 
+/** One state. */
+machineStateSchema, 
+/** A trigger's declaration under a state's `triggers:`. Loose: host keys pass through. */
+triggerDeclarationSchema, 
+/** A state's `triggers:` mapping — trigger id to declaration (or `null`). */
+stateTriggersSchema, 
+/** One transition. */
+machineTransitionSchema, transitionTypeSchema, stateTypeSchema, stateBudgetSchema, allowEntrySchema, forbidEntrySchema, 
+/** The `*` entry a `forbid` list uses to refuse every tool. */
+FORBID_ANY_TOOL, toolsBlockSchema, skillsBlockSchema, mountAccessSchema, mountGrantEntrySchema, mountsBlockSchema, workflowMountsConfigSchema, hookSchema, hookSpecSchema, rubricDeclarationSchema, workflowToolsConfigSchema, workflowSkillsConfigSchema, machineSettingsSchema, machinePromptCacheSettingsSchema, workflowTestsConfigSchema, runtimeMetadataSchema, specExtensionsSchema, 
+/** The loose slot for host metadata at the root, on a state and on a rubric. */
+specMetadataSchema, 
+/** Shape plus document-level cross-references, as one total function. */
+parseMachineSpec, 
+/** The document-level rules alone, over a spec the shape has accepted. */
+refineSpec, } from "../machine/spec-schema.js";
+export type { SpecSchemaIssue } from "../machine/spec-schema.js";
+export type { MachineSpec, MachineState, MachineTransition, TransitionType, Hook, HookSpec, StateBudget, AllowEntry, ForbidEntry, ToolsBlock, SkillsBlock, MountAccess, MountGrantEntry, MountsBlock, WorkflowMountsConfig, StateType, WorkflowToolsConfig, WorkflowSkillsConfig, MachineSettings, MachinePromptCacheSettings, WorkflowTestsConfig, RuntimeMetadata, TriggerDeclaration, SpecExtensions, SpecMetadata, RubricDeclaration, } from "../machine/types.js";
+/** Whether a spec declares itself out of service (`disabled: true`). */
+export { specDisabled } from "../machine/types.js";
+export { 
+/** Everything the document alone can say: shape, cross-references and lint, as diagnostics. */
+validateSpec, 
+/** One structural issue as an error-severity diagnostic. */
+schemaIssueDiagnostic, } from "../machine/validate-spec.js";
+export type { SpecValidation } from "../machine/validate-spec.js";
+/** The advisories alone, over a spec the schema has accepted. */
+export { lintSpec } from "../machine/lint-spec.js";
+export type { Diagnostic, DiagnosticSeverity } from "../machine/diagnostic.js";
+export { normalizeMountGrants } from "../machine/mount-grants.js";
+export type { NormalizedMountGrant } from "../machine/mount-grants.js";
+export { 
+/** The mount a canonical relative path addresses, longest key first. */
+mountNameOf, 
+/** The mount a glob can only ever match inside, or `null` when it is broader. */
+mountNameOfPattern, } from "../core/zones.js";
+export { 
+/** A `before:`/`after:` declaration as a flat list of hooks. */
+normalizeHooks, 
+/** A hook's kind (`script`, `subagent`, a custom one). */
+hookKind, 
+/** A hook's value: the script path, the rubric name. */
+hookValue, 
+/** The keys that ride beside a hook's kind (`max_iterations`) rather than naming one. */
+HOOK_SIDECAR_KEYS, } from "../lifecycle/hook-shape.js";
+export { SLUG_PATTERN, isSlug } from "../machine/slug.js";
+export { MANUAL_TRIGGER, DEFAULT_TRIGGER_ID, 
+/** Parse a dotted session path (`triggers.-1.conversationId`). */
+parseSessionPath, 
+/** Resolve a parsed session path against a firing's variables. */
+resolveSessionId, 
+/** The session id a firing of a trigger resolves to under a spec, or `undefined` when the runtime would mint one. */
+sessionIdForTrigger, 
+/** Every trigger a spec declares, keyed by id, with the state each enters. */
+triggerBindings, 
+/** The trigger ids one state declares. */
+stateTriggerIds, 
+/** Every variable a spec's `requires` declarations guarantee. */
+declaredVariableNames, } from "../machine/triggers.js";
+export type { SessionPath, SessionPathParse, TriggerBinding, TriggerInput, ResolvedTrigger, } from "../machine/triggers.js";
+export { VARIABLE_NAME_PATTERN, 
+/** The reserved variable holding the session's current trigger id. */
+TRIGGER_VARIABLE, 
+/** The reserved variable naming the session's task for a listing. */
+TITLE_VARIABLE, TITLE_MAX_LENGTH, 
+/** Whether a glob or text carries a `${{…}}` reference. */
+hasVariableReference, 
+/** Every `${{…}}` reference in a glob or text. */
+parseReferences, 
+/** Why a reference cannot be written, or `undefined` when it can. */
+referenceError, 
+/** Step into a structured value along a dotted path. */
+resolvePath, 
+/** Substitute every reference in a text against a variable store. */
+resolveText, } from "../machine/variables.js";
+export type { VariableReference, VariableStore, VariableEntry } from "../machine/variables.js";
+export { ARCHMAX_TOOL_PREFIX, ADVANCE_TOOL, RESET_TOOL, WAIT_TOOL, EVAL_TOOL, RUN_TOOL, GET_VARIABLES_TOOL, SET_VARIABLES_TOOL, 
+/** The tool name a runtime note's call pair wears; registered nowhere. */
+NOTE_TOOL, WORKFLOW_TOOL_PREFIX, workflowToolName, workflowSlugFromToolName, isWorkflowToolName, 
+/** Whether a name is one the runtime owns (`archmax_*`). */
+isReservedToolName, 
+/** The control tools: advance, reset, wait, get/set variables. */
+HARNESS_CONTROL_TOOLS, 
+/** Tools permitted in every state regardless of `allow`. */
+ALWAYS_ALLOWED_TOOLS, 
+/** The always-on built-ins a state's own entry may narrow but `allow_always` cannot add to. */
+ESSENTIAL_TOOLS, 
+/** Tools no list may grant (`task`). */
+UNGRANTABLE_TOOLS, ReservedToolNameError, } from "../machine/tool-names.js";
+export { DEFAULT_SUB_WORKFLOW_DEPTH, DEFAULT_SUB_WORKFLOW_CONCURRENCY } from "../machine/delegation.js";
+export { SESSION_INTERNAL_DIRS, SESSION_OFFLOAD_DIRS, SESSION_OPEN_DIR, SESSION_AGNOSTIC_PREFIX, SESSION_AGNOSTIC_PREFIXES, NO_MOUNTS, 
+/** Every session-area name the runtime owns at the workspace root. */
+sessionAreaNames, classifyWorkspacePath, isReservedRootName, isSessionAgnosticPath, 
+/** The prefixes the authoring backend serves (`workflows`), reserved at the root. */
+AUTHORING_PREFIXES, isAuthoringPrefix, 
+/** The authoring prefix a canonical path addresses, or `null`. */
+authoringPlanePrefix, describeAuthoringPrefix, } from "../core/zones.js";
+export type { MountPrefixes, WorkspaceZone, AuthoringPrefix } from "../core/zones.js";
+export { 
+/** Why a session id cannot own a session folder, or `null` when it can. */
+sessionIdRejection, SessionStoreIdError, 
+/** Directory of the zero-config filesystem session store (`sessions`). */
+DEFAULT_SESSIONS_DIR, } from "../core/session-id.js";
+export { 
+/** Whether one session was dispatched by another, at any depth. */
+isChildSessionOf, 
+/** The session that dispatched this one, or `undefined` at the top level. */
+parentSessionIdOf, 
+/** The id a child session gets: `<parent>~<identity>`. */
+childSessionId, 
+/** A dispatch identity: `<state>:<workflow>:<ordinal>`. */
+subRunIdentity, } from "../sessions/scope.js";
+export { DEFAULT_WORKFLOW, 
+/** Where a hook script lives, relative to its workflow directory. */
+HOOKS_DIR, PLATFORM_PROMPT_PATH, PLATFORM_BACKEND_PROMPT_PATH, 
+/** The authored paths of one workflow (`workflow.yaml`, `WORKFLOW.md`, `tests/`, `hooks/`). */
+workflowPaths, 
+/** The runtime-internal layout of one session's folder. */
+sessionPaths, 
+/** Resolve a hook's declared `script:` to an authoring-backend path, or refuse it with a reason. */
+resolveHookScript, } from "../workflow/paths.js";
+export { parseCodeDescription } from "../core/code-description.js";
+export type { CodeDescription } from "../core/code-description.js";

package/dist/public/spec.js

@@ -0,0 +1,149 @@
+/**
+ * `@archmax-ai/harness/spec` — the workflow vocabulary with **no runtime behind it**:
+ * the `workflow.yaml` schema, the pure validator, the slug, variable and
+ * session-path grammars, the reserved names and the path conventions.
+ *
+ * Browser-safe by construction: nothing reachable from here imports `node:*`,
+ * LangGraph, Deep Agents, the sandbox or a filesystem library, and a unit test
+ * walks this module's import graph to keep it that way. An editor bundles it
+ * into a page; an API request path that only has to parse or validate a spec
+ * imports it without loading the runtime.
+ *
+ * What is **not** here, because it cannot be pure: loading a spec from a
+ * backend (`loadMachineSpec`), compiling one (`WorkflowMachine`), the full
+ * validator (`validateWorkflow`, which also probes the kernel and reads hook
+ * scripts), resolving a trigger against a machine, and every store and mount.
+ * Those stay on the package root.
+ *
+ * Several names here are also on the root. That is deliberate: this subpath
+ * exists for the weight of the import, not to move the names — and a test pins
+ * that a shared name is the same binding on both.
+ */
+// --- The schema --------------------------------------------------------------
+export { 
+/** The whole `workflow.yaml` document. Parse with it and pass the **output** on; never compose it into another schema. */
+machineSpecSchema, 
+/** One state. */
+machineStateSchema, 
+/** A trigger's declaration under a state's `triggers:`. Loose: host keys pass through. */
+triggerDeclarationSchema, 
+/** A state's `triggers:` mapping — trigger id to declaration (or `null`). */
+stateTriggersSchema, 
+/** One transition. */
+machineTransitionSchema, transitionTypeSchema, stateTypeSchema, stateBudgetSchema, allowEntrySchema, forbidEntrySchema, 
+/** The `*` entry a `forbid` list uses to refuse every tool. */
+FORBID_ANY_TOOL, toolsBlockSchema, skillsBlockSchema, mountAccessSchema, mountGrantEntrySchema, mountsBlockSchema, workflowMountsConfigSchema, hookSchema, hookSpecSchema, rubricDeclarationSchema, workflowToolsConfigSchema, workflowSkillsConfigSchema, machineSettingsSchema, machinePromptCacheSettingsSchema, workflowTestsConfigSchema, runtimeMetadataSchema, specExtensionsSchema, 
+/** The loose slot for host metadata at the root, on a state and on a rubric. */
+specMetadataSchema, 
+/** Shape plus document-level cross-references, as one total function. */
+parseMachineSpec, 
+/** The document-level rules alone, over a spec the shape has accepted. */
+refineSpec, } from "../machine/spec-schema.js";
+/** Whether a spec declares itself out of service (`disabled: true`). */
+export { specDisabled } from "../machine/types.js";
+// --- Validation and advisories --------------------------------------------------
+export { 
+/** Everything the document alone can say: shape, cross-references and lint, as diagnostics. */
+validateSpec, 
+/** One structural issue as an error-severity diagnostic. */
+schemaIssueDiagnostic, } from "../machine/validate-spec.js";
+/** The advisories alone, over a spec the schema has accepted. */
+export { lintSpec } from "../machine/lint-spec.js";
+// --- Mount grants -----------------------------------------------------------------
+export { normalizeMountGrants } from "../machine/mount-grants.js";
+export { 
+/** The mount a canonical relative path addresses, longest key first. */
+mountNameOf, 
+/** The mount a glob can only ever match inside, or `null` when it is broader. */
+mountNameOfPattern, } from "../core/zones.js";
+// --- Hooks ------------------------------------------------------------------------
+export { 
+/** A `before:`/`after:` declaration as a flat list of hooks. */
+normalizeHooks, 
+/** A hook's kind (`script`, `subagent`, a custom one). */
+hookKind, 
+/** A hook's value: the script path, the rubric name. */
+hookValue, 
+/** The keys that ride beside a hook's kind (`max_iterations`) rather than naming one. */
+HOOK_SIDECAR_KEYS, } from "../lifecycle/hook-shape.js";
+// --- Slugs, triggers, variables --------------------------------------------------
+export { SLUG_PATTERN, isSlug } from "../machine/slug.js";
+export { MANUAL_TRIGGER, DEFAULT_TRIGGER_ID, 
+/** Parse a dotted session path (`triggers.-1.conversationId`). */
+parseSessionPath, 
+/** Resolve a parsed session path against a firing's variables. */
+resolveSessionId, 
+/** The session id a firing of a trigger resolves to under a spec, or `undefined` when the runtime would mint one. */
+sessionIdForTrigger, 
+/** Every trigger a spec declares, keyed by id, with the state each enters. */
+triggerBindings, 
+/** The trigger ids one state declares. */
+stateTriggerIds, 
+/** Every variable a spec's `requires` declarations guarantee. */
+declaredVariableNames, } from "../machine/triggers.js";
+export { VARIABLE_NAME_PATTERN, 
+/** The reserved variable holding the session's current trigger id. */
+TRIGGER_VARIABLE, 
+/** The reserved variable naming the session's task for a listing. */
+TITLE_VARIABLE, TITLE_MAX_LENGTH, 
+/** Whether a glob or text carries a `${{…}}` reference. */
+hasVariableReference, 
+/** Every `${{…}}` reference in a glob or text. */
+parseReferences, 
+/** Why a reference cannot be written, or `undefined` when it can. */
+referenceError, 
+/** Step into a structured value along a dotted path. */
+resolvePath, 
+/** Substitute every reference in a text against a variable store. */
+resolveText, } from "../machine/variables.js";
+// --- Tool names ---------------------------------------------------------------------
+export { ARCHMAX_TOOL_PREFIX, ADVANCE_TOOL, RESET_TOOL, WAIT_TOOL, EVAL_TOOL, RUN_TOOL, GET_VARIABLES_TOOL, SET_VARIABLES_TOOL, 
+/** The tool name a runtime note's call pair wears; registered nowhere. */
+NOTE_TOOL, WORKFLOW_TOOL_PREFIX, workflowToolName, workflowSlugFromToolName, isWorkflowToolName, 
+/** Whether a name is one the runtime owns (`archmax_*`). */
+isReservedToolName, 
+/** The control tools: advance, reset, wait, get/set variables. */
+HARNESS_CONTROL_TOOLS, 
+/** Tools permitted in every state regardless of `allow`. */
+ALWAYS_ALLOWED_TOOLS, 
+/** The always-on built-ins a state's own entry may narrow but `allow_always` cannot add to. */
+ESSENTIAL_TOOLS, 
+/** Tools no list may grant (`task`). */
+UNGRANTABLE_TOOLS, ReservedToolNameError, } from "../machine/tool-names.js";
+export { DEFAULT_SUB_WORKFLOW_DEPTH, DEFAULT_SUB_WORKFLOW_CONCURRENCY } from "../machine/delegation.js";
+// --- The root namespace ---------------------------------------------------------------
+export { SESSION_INTERNAL_DIRS, SESSION_OFFLOAD_DIRS, SESSION_OPEN_DIR, SESSION_AGNOSTIC_PREFIX, SESSION_AGNOSTIC_PREFIXES, NO_MOUNTS, 
+/** Every session-area name the runtime owns at the workspace root. */
+sessionAreaNames, classifyWorkspacePath, isReservedRootName, isSessionAgnosticPath, 
+/** The prefixes the authoring backend serves (`workflows`), reserved at the root. */
+AUTHORING_PREFIXES, isAuthoringPrefix, 
+/** The authoring prefix a canonical path addresses, or `null`. */
+authoringPlanePrefix, describeAuthoringPrefix, } from "../core/zones.js";
+// --- Session ids -----------------------------------------------------------------------
+export { 
+/** Why a session id cannot own a session folder, or `null` when it can. */
+sessionIdRejection, SessionStoreIdError, 
+/** Directory of the zero-config filesystem session store (`sessions`). */
+DEFAULT_SESSIONS_DIR, } from "../core/session-id.js";
+export { 
+/** Whether one session was dispatched by another, at any depth. */
+isChildSessionOf, 
+/** The session that dispatched this one, or `undefined` at the top level. */
+parentSessionIdOf, 
+/** The id a child session gets: `<parent>~<identity>`. */
+childSessionId, 
+/** A dispatch identity: `<state>:<workflow>:<ordinal>`. */
+subRunIdentity, } from "../sessions/scope.js";
+// --- Paths -------------------------------------------------------------------------------
+export { DEFAULT_WORKFLOW, 
+/** Where a hook script lives, relative to its workflow directory. */
+HOOKS_DIR, PLATFORM_PROMPT_PATH, PLATFORM_BACKEND_PROMPT_PATH, 
+/** The authored paths of one workflow (`workflow.yaml`, `WORKFLOW.md`, `tests/`, `hooks/`). */
+workflowPaths, 
+/** The runtime-internal layout of one session's folder. */
+sessionPaths, 
+/** Resolve a hook's declared `script:` to an authoring-backend path, or refuse it with a reason. */
+resolveHookScript, } from "../workflow/paths.js";
+// --- Scripts -------------------------------------------------------------------------------
+export { parseCodeDescription } from "../core/code-description.js";
+//# sourceMappingURL=spec.js.map

package/dist/public/spec.js.map

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

package/dist/public/testing.d.ts

@@ -0,0 +1,71 @@
+/**
+ * `@archmax-ai/harness/testing` — the case engine behind `archmax test`.
+ *
+ * A subpath of its own so a production import never pulls in test machinery: a
+ * host that builds cases programmatically, drives a suite in CI, or mocks tools
+ * imports here, and everything else imports the root.
+ *
+ * Cases are declarative YAML documents interpreted **host-side** — no sandbox
+ * is involved. See the testing guide.
+ */
+export { 
+/** Discover and run a workflow's cases. */
+runTests, 
+/** Find and parse a suite's case files. */
+discoverCases, 
+/** Drive one discovered case against an agent under test. */
+runCase, 
+/** Reduce a case's assertion records to a verdict. */
+reduceVerdict, 
+/** The process exit code a verdict implies. */
+exitCodeForVerdict, 
+/** Refuse a target that is not workflow-governed, on the runner's own terms. */
+assertWorkflowGovernedTarget, } from "../testing/runner.js";
+export type { 
+/** One case's outcome. */
+CaseResult, 
+/** A single assertion's record. */
+AssertionRecord, 
+/** Whether an assertion passed, failed, or never ran. */
+AssertionStatus, 
+/** A case's settled verdict. */
+CaseVerdict, 
+/** A verdict's status: passed, failed, or skipped. */
+CaseStatus, 
+/** Options for {@link runTests}. */
+RunTestsOptions, 
+/** What {@link runTests} returns. */
+RunTestsResult, 
+/** Why a whole suite ran no cases. */
+SuiteSkip, 
+/** A parsed (or unparseable) case file, as {@link discoverCases} reports it. */
+DiscoveredCase, 
+/** Options for {@link runCase}. */
+RunCaseOptions, } from "../testing/runner.js";
+/** Build the agent under test. Replaceable via `runTests({ createTarget })`. */
+export { createCaseTarget } from "../testing/target.js";
+export type { CaseTargetOptions } from "../testing/target.js";
+export { 
+/** Parse one case document, for a host that builds or validates cases itself. */
+parseCaseDocument, 
+/** The inverse: a case document back to YAML, in the grammar's key order. */
+serializeCaseDocument, 
+/** The prose-length bounds a case's `title` and `description` are held to. */
+CASE_TITLE_MAX_LENGTH, CASE_DESCRIPTION_MAX_LENGTH, 
+/** A structural problem in a case document. */
+CaseSchemaError, } from "../testing/case-schema.js";
+export type { 
+/** A parsed case. */
+CaseDocument, 
+/** One entry of a case's flat `steps` list. */
+CaseStep, 
+/** A declarative assertion. */
+CaseExpectation, 
+/** A declared trigger start condition. */
+CaseTriggerDecl, 
+/** One seeded workspace file. */
+CaseWorkspaceEntry, } from "../testing/case-schema.js";
+/** Middleware that intercepts declared tool mocks, for a caller-built target. */
+export { createToolMockMiddleware } from "../testing/mock-middleware.js";
+/** The partial-match vocabulary shared by `calledTool.input` assertions and `whenInput` mocks. */
+export { partialMatch } from "../core/match.js";

package/dist/public/testing.js

@@ -0,0 +1,39 @@
+/**
+ * `@archmax-ai/harness/testing` — the case engine behind `archmax test`.
+ *
+ * A subpath of its own so a production import never pulls in test machinery: a
+ * host that builds cases programmatically, drives a suite in CI, or mocks tools
+ * imports here, and everything else imports the root.
+ *
+ * Cases are declarative YAML documents interpreted **host-side** — no sandbox
+ * is involved. See the testing guide.
+ */
+export { 
+/** Discover and run a workflow's cases. */
+runTests, 
+/** Find and parse a suite's case files. */
+discoverCases, 
+/** Drive one discovered case against an agent under test. */
+runCase, 
+/** Reduce a case's assertion records to a verdict. */
+reduceVerdict, 
+/** The process exit code a verdict implies. */
+exitCodeForVerdict, 
+/** Refuse a target that is not workflow-governed, on the runner's own terms. */
+assertWorkflowGovernedTarget, } from "../testing/runner.js";
+/** Build the agent under test. Replaceable via `runTests({ createTarget })`. */
+export { createCaseTarget } from "../testing/target.js";
+export { 
+/** Parse one case document, for a host that builds or validates cases itself. */
+parseCaseDocument, 
+/** The inverse: a case document back to YAML, in the grammar's key order. */
+serializeCaseDocument, 
+/** The prose-length bounds a case's `title` and `description` are held to. */
+CASE_TITLE_MAX_LENGTH, CASE_DESCRIPTION_MAX_LENGTH, 
+/** A structural problem in a case document. */
+CaseSchemaError, } from "../testing/case-schema.js";
+/** Middleware that intercepts declared tool mocks, for a caller-built target. */
+export { createToolMockMiddleware } from "../testing/mock-middleware.js";
+/** The partial-match vocabulary shared by `calledTool.input` assertions and `whenInput` mocks. */
+export { partialMatch } from "../core/match.js";
+//# sourceMappingURL=testing.js.map

package/dist/public/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../../src/public/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO;AACL,2CAA2C;AAC3C,QAAQ;AACR,2CAA2C;AAC3C,aAAa;AACb,6DAA6D;AAC7D,OAAO;AACP,sDAAsD;AACtD,aAAa;AACb,+CAA+C;AAC/C,kBAAkB;AAClB,gFAAgF;AAChF,4BAA4B,GAC7B,MAAM,sBAAsB,CAAC;AAyB9B,gFAAgF;AAChF,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAGxD,OAAO;AACL,iFAAiF;AACjF,iBAAiB;AACjB,6EAA6E;AAC7E,qBAAqB;AACrB,8EAA8E;AAC9E,qBAAqB,EACrB,2BAA2B;AAC3B,+CAA+C;AAC/C,eAAe,GAChB,MAAM,2BAA2B,CAAC;AAenC,iFAAiF;AACjF,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,kGAAkG;AAClG,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/rubrics/rubrics.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Grading rubrics: the standards a state's exit is measured against, declared
+ * inline on the hook that applies them and dispatched by the runtime alone.
+ *
+ * This module is only the *vocabulary* — the verdict contract, the payload a
+ * grader receives, the rejection wording, and the projection from a loaded spec
+ * into a registry. There is deliberately no loader, no file format and no merge
+ * path: a rubric is spec content, so the spec's own schema is the one thing that
+ * has to accept it, and nothing outside assembly builds a registry.
+ *
+ * A rubric has no author-given name. Its identity is its **position** — the
+ * state, the phase, and its index in that phase's hook list — which is also how
+ * its retry budget is keyed, so two graders on one state can never share a
+ * budget or be confused for one another in an event.
+ */
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { CreateDeepAgentParams } from "deepagents";
+import type { MachineSpec, RubricDeclaration } from "../machine/types.js";
+/** A grader in the Deep Agents shape, registered for the runtime's own `task` dispatch. */
+export type LoadedRubric = NonNullable<CreateDeepAgentParams["subagents"]>[number];
+/** The verdict vocabulary. `correct` asks for another iteration; `veto` blocks outright. */
+export type RubricVerdict = "ok" | "correct" | "veto";
+export interface RubricVerdictResult {
+    verdict: RubricVerdict;
+    reason: string;
+    /** The rubric that produced this verdict; absent for a script hook's own verdict. */
+    rubric?: string;
+}
+/**
+ * The structured output a rubric with an iteration budget must return. Applied
+ * automatically, so a grader's output is a contract rather than a prompt
+ * convention.
+ */
+export declare const RUBRIC_VERDICT_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly verdict: {
+            readonly type: "string";
+            readonly enum: readonly ["ok", "correct", "veto"];
+        };
+        readonly reason: {
+            readonly type: "string";
+        };
+    };
+    readonly required: readonly ["verdict", "reason"];
+};
+/**
+ * One registry entry: the declaration plus the positional id the runtime
+ * dispatches it under. The id is internal — it appears in operator-facing events
+ * and never in a prompt — so it is built for uniqueness, not for authoring.
+ */
+export interface Rubric extends RubricDeclaration {
+    id: string;
+    state: string;
+    phase: "before" | "after";
+    index: number;
+}
+/**
+ * The id one inline rubric is registered and dispatched under. Positional
+ * because an inline rubric has no name: reordering a phase's hooks re-keys them,
+ * which is the same class of change as editing the spec at all (it moves the
+ * spec hash).
+ */
+export declare function rubricId(state: string, phase: "before" | "after", index: number): string;
+/** Whether a value is a usable verdict. Anything else has graded nothing. */
+export declare function isRubricVerdict(value: unknown): value is RubricVerdictResult;
+/**
+ * The structured-output schema every dispatch requests: the verdict schema,
+ * unconditionally.
+ *
+ * Not conditional on `max_iterations`, as it was when a grader was a subagent
+ * that might also be a general-purpose helper. A rubric only ever grades, so a
+ * grader that needs no retries still has to answer in the verdict vocabulary —
+ * and without the schema its answer arrives as prose, parses to no verdict, and
+ * fails closed on a transition the author expected it to wave through.
+ */
+export declare function resolveRubricResponseFormat(_rubric: RubricDeclaration): Record<string, unknown> | undefined;
+/** The compact task payload a grader is handed: the request, the transcript, and where it happened. */
+export declare function buildRubricTaskDescription(args: Record<string, unknown>): string;
+/**
+ * What an `after`-hook verdict does to an `archmax_advance` attempt.
+ *
+ * `reason` is `null` when the transition may proceed. The other two are decided
+ * here, together, because they are mutually exclusive and were not: a `correct`
+ * whose budget is already spent is `budgetExhausted` and bills nothing, while
+ * only a `correct` that actually got its retry is `consumesIteration`. Billing
+ * an attempt that was never granted costs the state its budget for good on
+ * re-entry (issue #62).
+ */
+export interface RubricTransitionOutcome {
+    reason: string | null;
+    /** A `correct` refused because the hook's `max_iterations` are already spent. */
+    budgetExhausted: boolean;
+    /** This block granted a retry, so it spends one of the hook's iterations. */
+    consumesIteration: boolean;
+}
+/**
+ * Map an `after`-hook verdict to an `archmax_advance` rejection outcome. One
+ * implementation for every hook kind: the retry flow (bounded iterations with
+ * remaining-attempt guidance) is identical whether the verdict came from a
+ * rubric or a script — only the label differs (`rubric` vs `hook`).
+ */
+export declare function rubricTransitionOutcome(verdict: RubricVerdictResult, opts: {
+    maxIterations: number;
+    iterationsUsed: number;
+    to?: string;
+}): RubricTransitionOutcome;
+/**
+ * The rejection reason alone, for callers that do not decide the retry budget.
+ */
+export declare function rubricTransitionReason(verdict: RubricVerdictResult, opts: {
+    maxIterations: number;
+    iterationsUsed: number;
+    to?: string;
+}): string | null;
+/**
+ * The rubric registry for one machine: every inline rubric its states declare,
+ * keyed by {@link rubricId}. Walks the spec rather than reading a root block,
+ * because a grader lives on the hook that applies it.
+ *
+ * Scoped to this spec, so a delegated child is graded by its own standards; two
+ * states declaring the same criteria produce two entries, which is the accepted
+ * cost of a state being legible on its own.
+ */
+export declare function rubricsFromSpec(spec: Pick<MachineSpec, "states">): Map<string, Rubric>;
+/**
+ * Project the registry into the Deep Agents subagent shape so the framework
+ * registers the `task` tool the runtime dispatches through. These are never
+ * disclosed to the agent: `task` is withheld in every state and grantable by
+ * nothing, so registering a grader here gives the graded agent no reach.
+ *
+ * `model` resolves the grader's own model when it declared one, else the
+ * assembly's `rubric`-role model.
+ */
+export declare function rubricsAsSubagents(registry: Map<string, Rubric>, modelFor?: (rubric: Rubric) => BaseChatModel | undefined): LoadedRubric[];