@archmax-ai/harness 0.0.0

package/dist/machine/variables.js

@@ -0,0 +1,415 @@
+/**
+ * Run-variable references — `${{name}}` and `${{name.dotted.path}}` — in guards,
+ * prompts and the arguments the agent writes. One resolver serves the kernel,
+ * disclosure, validation and substitution, so a reference means one thing.
+ *
+ * Three invariants carry the feature's safety: a substituted value is
+ * glob-escaped where the output is a *pattern* and verbatim where it is a
+ * *value*; resolution fails closed (never the literal `${{…}}` text, never `*`);
+ * and traversal reads own properties only (`resolvePath`), so `tags.length` and
+ * `constructor` never resolve.
+ */
+import { guardReferences } from "./allow.js";
+import { SET_VARIABLES_TOOL } from "./tool-names.js";
+import { declaredVariableNames } from "./triggers.js";
+/** The shape a run-variable name must take: a snake_case identifier, never dotted. */
+export const VARIABLE_NAME_PATTERN = /^[a-z][a-z0-9_]*$/;
+/**
+ * The built-in variable holding the run's trigger id. Reserved: it is set by the
+ * harness at run start, locked, and needs no seed — so a guard may reference
+ * `${{trigger}}` without anything supplying it.
+ */
+export const TRIGGER_VARIABLE = "trigger";
+/**
+ * The built-in variable holding a short label for the task the run is doing.
+ * Agent-owned, unlike `trigger`: nothing sets it until the agent does. Two rules
+ * follow it everywhere it is written — it is **never locked** (a seed stores it
+ * unlocked; `set_variables` refuses `lock: true`), and it is **shape-checked on
+ * write** ({@link titleWriteError}). Unrelated to the spec's static `title`
+ * fields.
+ */
+export const TITLE_VARIABLE = "title";
+/**
+ * The longest a title may be. A bound, not a style guide — the system prompt asks
+ * for something short, and this only stops something unusable from being stored.
+ */
+export const TITLE_MAX_LENGTH = 200;
+/**
+ * Check a value destined for {@link TITLE_VARIABLE}, returning the refusal reason
+ * or `undefined` when it passes. Shared by both write routes (a seed throws, the
+ * agent's `set_variables` is refused). Refuses rather than coerces; trimming is
+ * the one coercion allowed.
+ */
+export function titleWriteError(value) {
+    const shape = `'${TITLE_VARIABLE}' is reserved for a short label naming the task this run is doing. ` +
+        `It must be a non-empty single-line string of at most ${TITLE_MAX_LENGTH} characters`;
+    if (typeof value !== "string") {
+        return `${shape}, but a ${value === null ? "null" : typeof value} was given.`;
+    }
+    if (/[\r\n]/.test(value))
+        return `${shape}; this one spans more than one line.`;
+    const trimmed = value.trim();
+    if (trimmed === "")
+        return `${shape}; this one is empty.`;
+    if (trimmed.length > TITLE_MAX_LENGTH) {
+        return `${shape}; this one is ${trimmed.length}. Shorten it and retry.`;
+    }
+    return undefined;
+}
+/**
+ * The value to store for a title that has passed {@link titleWriteError} — the
+ * trimmed string. Separate from the check so a caller cannot store the untrimmed
+ * original by forgetting to.
+ */
+export function normalizeTitle(value) {
+    return value.trim();
+}
+/** Thrown when a seeded (or written) variable name is not a valid identifier. */
+export class InvalidVariableNameError extends Error {
+    variable;
+    source;
+    constructor(variable, 
+    /** Where the name came from, for a message that points at the fix. */
+    source = "seeded") {
+        super(`'${variable}' is not a valid variable name (${source}). Use lowercase letters, digits ` +
+            `and underscores, starting with a letter (e.g. 'from_email').`);
+        this.variable = variable;
+        this.source = source;
+        this.name = "InvalidVariableNameError";
+    }
+}
+/**
+ * Thrown when a seeded `title` is not a usable label — a throw rather than the
+ * agent's string refusal, because a bad seed is a host defect that should
+ * surface at assembly.
+ */
+export class InvalidTitleError extends Error {
+    detail;
+    source;
+    constructor(
+    /** The shape problem, in the same words the agent's refusal uses. */
+    detail, 
+    /** Where the value came from, for a message that points at the fix. */
+    source = "seeded") {
+        super(`${detail} (${source})`);
+        this.detail = detail;
+        this.source = source;
+        this.name = "InvalidTitleError";
+    }
+}
+/**
+ * Turn a caller's seeds into locked variable entries — the one way a run's
+ * opening facts are established, whether by a host's `variables` option, a
+ * delivery's seeds, or the arguments a delegation hands a sub-run. Locked because
+ * a `${{name}}` guard bound to a seed is worthless if the agent can rewrite it.
+ */
+export function buildSeededVariables(seeds, 
+/** Where the names came from, for a message that points at the fix. */
+source = "seeded") {
+    const store = {};
+    for (const [name, value] of Object.entries(seeds ?? {})) {
+        if (!VARIABLE_NAME_PATTERN.test(name))
+            throw new InvalidVariableNameError(name, source);
+        // `title` is the one seed stored unlocked: a seeded title is an *opening*
+        // label the agent may refine (see TITLE_VARIABLE).
+        if (name === TITLE_VARIABLE) {
+            const problem = titleWriteError(value);
+            if (problem)
+                throw new InvalidTitleError(problem, source);
+            store[name] = { value: normalizeTitle(value), locked: false };
+            continue;
+        }
+        store[name] = { value, locked: true };
+    }
+    return store;
+}
+/**
+ * Matches a `${{…}}` reference, or the **escaped** form `$${{…}}` that writes the
+ * braces as text (`$$` rather than a backslash, which would not survive JSON
+ * encoding on the model's side). The inner text is captured loosely and
+ * validated separately so a malformed reference is reported, never ignored.
+ */
+const REFERENCE_RE = /(\$?)\$\{\{([^}]*)\}\}/g;
+/**
+ * Every `${{…}}` and `$${{…}}` span in a string, in order. One scan so a
+ * reference and its escaped twin can never be found by different rules.
+ */
+function scan(glob) {
+    const spans = [];
+    REFERENCE_RE.lastIndex = 0;
+    let match;
+    while ((match = REFERENCE_RE.exec(glob)) !== null) {
+        const inner = (match[2] ?? "").trim();
+        const segments = inner.split(".");
+        spans.push({
+            raw: match[0],
+            name: segments[0] ?? "",
+            path: segments.slice(1),
+            index: match.index,
+            escaped: match[1] === "$",
+        });
+    }
+    return spans;
+}
+/**
+ * Whether a glob contains reference **syntax** — a `${{…}}` reference or an
+ * escaped `$${{…}}` literal. Callers use this to skip resolution entirely for the
+ * common reference-free glob, so an escape has to answer `true` here: it resolves
+ * nothing, but it still needs the pass that turns `$${{x}}` into `${{x}}`.
+ */
+export function hasVariableReference(glob) {
+    return scan(glob).length > 0;
+}
+/**
+ * Every `${{…}}` reference in a glob, in order. A syntactically malformed
+ * reference still appears here (with an empty `name`), so callers can report it
+ * rather than skip it. An escaped `$${{…}}` is omitted — it is literal text, and
+ * reporting it as a reference would make `validate` warn about a variable the
+ * author deliberately spelled out.
+ */
+export function parseReferences(glob) {
+    return scan(glob)
+        .filter((span) => !span.escaped)
+        // Drop `escaped`: it is this module's discriminator, not part of a reference.
+        .map(({ raw, name, path, index }) => ({ raw, name, path, index }));
+}
+/** Whether a reference is structurally usable (name shape, no empty segments). */
+export function referenceError(ref) {
+    if (ref.name === "")
+        return "malformed";
+    if (ref.path.some((segment) => segment === ""))
+        return "malformed";
+    if (!VARIABLE_NAME_PATTERN.test(ref.name))
+        return "invalid-name";
+    return undefined;
+}
+/**
+ * A path segment that addresses an array element from the end (`-1` last, `-2`
+ * second-to-last). Deliberately canonical-only: `-0` and `-01` do not match, so
+ * there is exactly one spelling of each index and any other `-`-prefixed segment
+ * stays an ordinary key.
+ */
+const FROM_END_RE = /^-[1-9][0-9]*$/;
+/** A canonical non-negative index — no leading zeros, so one spelling per index. */
+const INDEX_RE = /^(0|[1-9][0-9]*)$/;
+/**
+ * Descend one level. An **array** is addressed by index only — canonical
+ * non-negative, or negative from the end; `Object.hasOwn` alone would let
+ * `${{tags.length}}` resolve, since `length` is an own property. Any other
+ * object is an own-property lookup, so `constructor`, `toString` and `__proto__`
+ * stay unreachable while a data key of the same name still resolves.
+ */
+function step(container, segment) {
+    if (container === null || typeof container !== "object")
+        return undefined;
+    if (Array.isArray(container)) {
+        if (FROM_END_RE.test(segment)) {
+            const fromEnd = container.length + Number(segment);
+            return fromEnd >= 0 ? container[fromEnd] : undefined;
+        }
+        return INDEX_RE.test(segment) ? container[Number(segment)] : undefined;
+    }
+    return Object.hasOwn(container, segment)
+        ? container[segment]
+        : undefined;
+}
+/**
+ * Resolve a dotted path against a value, reading own properties only. Returns
+ * `undefined` when any segment misses — indistinguishable from a stored
+ * `undefined`, which is fine: both are unresolvable for a guard.
+ */
+export function resolvePath(value, path) {
+    let current = value;
+    for (const segment of path) {
+        current = step(current, segment);
+        if (current === undefined)
+            return undefined;
+    }
+    return current;
+}
+/** Values a guard may substitute: exactly the scalars a glob can match against. */
+function isScalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+/**
+ * Escape every picomatch metacharacter so a substituted value is matched as
+ * literal text; without it a variable holding `*` or `{a,b}` widens the guard.
+ */
+export function escapeGlobLiteral(value) {
+    return value.replace(/[\\*?[\]{}()!+@|^$]/g, (char) => `\\${char}`);
+}
+/** Explain an unresolved reference in the words a block reason should use. */
+function explain(reason, ref) {
+    const target = ref.path.length > 0 ? `'${ref.name}' at path '${ref.path.join(".")}'` : `'${ref.name}'`;
+    switch (reason) {
+        case "malformed":
+            return `${ref.raw} is not a valid reference — use \${{name}} or \${{name.path.to.value}}`;
+        case "invalid-name":
+            return `${ref.raw} names '${ref.name}', which is not a valid variable name (lowercase letters, digits and underscores, starting with a letter)`;
+        case "unset":
+            return `variable '${ref.name}' is not set`;
+        case "path-missing":
+            return `${target} does not resolve — the value has no such path`;
+        case "non-scalar":
+            return `${target} resolves to a non-scalar value; only strings, numbers and booleans can be substituted into a guard`;
+    }
+}
+/**
+ * Substitute every reference in a glob against the run's variables. Returns the
+ * resolved pattern, or the first unresolved reference and why — a glob with an
+ * unresolved reference matches nothing at all, so the caller must not fall back
+ * to the original text.
+ */
+export function resolveGlob(glob, variables) {
+    return substitute(glob, variables, escapeGlobLiteral);
+}
+/**
+ * Shared substitution. `render` decides how a resolved value enters the output:
+ * glob-escaped for enforcement (where the result is a *pattern*), verbatim for
+ * disclosure (where the result is *prose the model reads*) — showing an author's
+ * email as `a\@b.c` would teach the model to pass the backslash.
+ */
+function substitute(glob, variables, render) {
+    const refs = scan(glob);
+    if (refs.length === 0)
+        return { ok: true, pattern: glob };
+    let out = "";
+    let cursor = 0;
+    for (const ref of refs) {
+        // `$${{…}}`: the braces are meant as text. Emit the span with one `$`
+        // dropped and resolve nothing.
+        if (ref.escaped) {
+            out += glob.slice(cursor, ref.index) + ref.raw.slice(1);
+            cursor = ref.index + ref.raw.length;
+            continue;
+        }
+        const structural = referenceError(ref);
+        if (structural) {
+            return { ok: false, reason: structural, reference: ref.raw, detail: explain(structural, ref) };
+        }
+        const entry = variables[ref.name];
+        if (entry === undefined) {
+            return { ok: false, reason: "unset", reference: ref.raw, detail: explain("unset", ref) };
+        }
+        const resolved = resolvePath(entry.value, ref.path);
+        if (resolved === undefined) {
+            const reason = ref.path.length === 0 ? "unset" : "path-missing";
+            return { ok: false, reason, reference: ref.raw, detail: explain(reason, ref) };
+        }
+        if (!isScalar(resolved)) {
+            return {
+                ok: false,
+                reason: "non-scalar",
+                reference: ref.raw,
+                detail: explain("non-scalar", ref),
+            };
+        }
+        out += glob.slice(cursor, ref.index) + render(String(resolved));
+        cursor = ref.index + ref.raw.length;
+    }
+    return { ok: true, pattern: out + glob.slice(cursor) };
+}
+/**
+ * Substitute every reference in a piece of **prose** (a sub-workflow prompt)
+ * verbatim: a prompt is text a model reads, where glob-escaping would teach it
+ * to emit backslashes. Failure is still closed — a literal `${{…}}` reaching a
+ * model is an instruction it cannot follow.
+ */
+export function resolveText(text, variables) {
+    return substitute(text, variables, (value) => value);
+}
+/**
+ * Whether a value is a plain JSON object this walk may rebuild. Anything with its
+ * own prototype (`Date`, `Map`, a class instance) is left alone rather than
+ * flattened into `{}`.
+ */
+function isDataObject(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+/**
+ * Substitute every reference in the **arguments the agent wrote**, verbatim.
+ * Walks deep (non-string leaves pass through), fails first-wins and totally (the
+ * tool never receives a half-resolved structure), and only reports. Objects are
+ * rebuilt with `Object.fromEntries`, which *defines* each key, so a model-emitted
+ * `__proto__` becomes a property rather than a prototype.
+ */
+export function resolveArguments(args, variables) {
+    let failure;
+    const walk = (value) => {
+        if (failure)
+            return value;
+        if (typeof value === "string") {
+            // The same verbatim rendering a prompt gets — an argument is a value too.
+            const result = resolveText(value, variables);
+            if (result.ok)
+                return result.pattern;
+            failure = result;
+            return value;
+        }
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (isDataObject(value)) {
+            const entries = [];
+            for (const [key, member] of Object.entries(value)) {
+                entries.push([key, walk(member)]);
+                if (failure)
+                    break;
+            }
+            return Object.fromEntries(entries);
+        }
+        return value;
+    };
+    const resolved = walk(args);
+    return failure ?? { ok: true, args: resolved };
+}
+/**
+ * Render a guard glob for the model: the resolved pattern when it resolves, or a
+ * short unresolved marker naming the reference. The model is told a constraint
+ * exists and what it is waiting on, rather than being shown a placeholder it
+ * might try to pass literally into a call that would end the run.
+ */
+export function describeGlob(glob, variables) {
+    const result = substitute(glob, variables, (value) => value);
+    return result.ok ? result.pattern : `${glob} (unresolved: ${result.detail})`;
+}
+// --- What the assembly can guarantee a guard reference resolves ----------------
+/**
+ * Warn about every `${{…}}` guard reference the assembly cannot *guarantee* is
+ * set — named by neither the host's seeds, any state's `requires`, nor the
+ * built-in `trigger`. A warning, not a throw: `archmax_set_variables` can create
+ * any name at runtime, so an upstream state may legitimately establish it; the
+ * enforcement is the runtime failure when the guard cannot resolve.
+ */
+export function unguaranteedReferenceWarnings(machine, seededVariables) {
+    const guaranteed = new Set([
+        TRIGGER_VARIABLE,
+        ...Object.keys(seededVariables),
+        ...declaredVariableNames(machine.spec),
+    ]);
+    const messages = [];
+    const seen = new Set();
+    for (const ref of guardReferences(machine.spec)) {
+        const name = ref.reference.name;
+        if (name === "" || guaranteed.has(name))
+            continue;
+        const where = ref.state ? `state '${ref.state}'` : "tools.allow_always";
+        const key = `${where}|${ref.tool}|${ref.arg}|${name}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        messages.push(`${where} guards '${ref.tool ?? "?"}' on '${ref.reference.raw}' (argument ` +
+            `'${ref.arg}'), but nothing guarantees '${name}' is set: it is not seeded ` +
+            `as a seeded variable and no state requires it. The guard then depends on ` +
+            `the agent having called ${SET_VARIABLES_TOOL} first — if it has not, the session fails ` +
+            `at that call. Name '${name}' in the 'requires' of a state that runs first, ` +
+            `or seed it.` +
+            (ref.state
+                ? ""
+                : " An allow_always entry is evaluated in every state, including states reached before anything sets it."));
+    }
+    return messages;
+}
+//# sourceMappingURL=variables.js.map

package/dist/machine/variables.js.map

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

package/dist/public/cli.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@archmax-ai/harness/cli` — the state-flow renderer and its styling.
+ *
+ * A subpath of its own so a third-party frontend of the typed event stream can
+ * render sessions the way `archmax run` does — and suites the way `archmax test`
+ * does — without importing the CLI itself.
+ */
+/** Render one lifecycle event as the CLI's own console line, or `null` for none. */
+export { renderEventLine } from "../core/events.js";
+/** The CLI's colour and glyph vocabulary, honouring `NO_COLOR`. */
+export { createStyle, icons } from "../cli/style.js";
+export type { Style } from "../cli/style.js";
+/** The live state flow `archmax run` builds from the event stream, and the test view `archmax test` builds on it. */
+export { createStateFlowRenderer, createTestView, caseVerdictLine } from "../cli/state-flow.js";
+export type { StateFlowRenderer, StateFlowWriter, TestView } from "../cli/state-flow.js";

package/dist/public/cli.js

@@ -0,0 +1,14 @@
+/**
+ * `@archmax-ai/harness/cli` — the state-flow renderer and its styling.
+ *
+ * A subpath of its own so a third-party frontend of the typed event stream can
+ * render sessions the way `archmax run` does — and suites the way `archmax test`
+ * does — without importing the CLI itself.
+ */
+/** Render one lifecycle event as the CLI's own console line, or `null` for none. */
+export { renderEventLine } from "../core/events.js";
+/** The CLI's colour and glyph vocabulary, honouring `NO_COLOR`. */
+export { createStyle, icons } from "../cli/style.js";
+/** The live state flow `archmax run` builds from the event stream, and the test view `archmax test` builds on it. */
+export { createStateFlowRenderer, createTestView, caseVerdictLine } from "../cli/state-flow.js";
+//# sourceMappingURL=cli.js.map

package/dist/public/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/public/cli.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,oFAAoF;AACpF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,mEAAmE;AACnE,OAAO,EAAE,WAAW,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAGrD,qHAAqH;AACrH,OAAO,EAAE,uBAAuB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/public/messages.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `@archmax-ai/harness/messages` — reading a transcript without the runtime.
+ *
+ * Every reader is duck-typed over the shapes a message takes — a LangChain class
+ * instance, a checkpoint's serialized form, a raw `{ role, content }` — and this
+ * module imports nothing, so an API request path that renders or slices a
+ * transcript loads no LangGraph. A unit test walks the import graph to keep it
+ * that way. The root exports the readers a governed host needs most
+ * (`contentToString`, `isAiMessage`, `isRuntimeNote`, `runtimeNoteKind`); they
+ * are the same bindings here.
+ */
+export { 
+/** A message's text, whatever content-block shape it arrived in. */
+contentToString, 
+/** The LangChain message kind (`ai`, `human`, `tool`, `system`, …). */
+messageTypeOf, 
+/** Whether a message is the assistant's. */
+isAiMessage, 
+/** Whether a message is a person's (or a human-role runtime note — see `isRuntimeNote`). */
+isHumanMessage, 
+/** Whether the runtime wrote this message rather than a person. */
+isRuntimeNote, 
+/** Which kind of runtime note a message is, or `null` if a person wrote it. */
+runtimeNoteKind, 
+/** The last thing the agent said to the person; tool results and runtime notes are skipped. */
+lastAgentText, 
+/** Whether a message opens a turn: something the session was told. */
+opensTurn, 
+/** The messages appended since a count read earlier — what one `invoke` added. */
+messagesSince, 
+/** The trailing turn: from the last thing the session was told to the end. */
+lastTurn, } from "../core/message-readers.js";
+export type { RuntimeNoteKind } from "../core/message-readers.js";

package/dist/public/messages.js

@@ -0,0 +1,33 @@
+/**
+ * `@archmax-ai/harness/messages` — reading a transcript without the runtime.
+ *
+ * Every reader is duck-typed over the shapes a message takes — a LangChain class
+ * instance, a checkpoint's serialized form, a raw `{ role, content }` — and this
+ * module imports nothing, so an API request path that renders or slices a
+ * transcript loads no LangGraph. A unit test walks the import graph to keep it
+ * that way. The root exports the readers a governed host needs most
+ * (`contentToString`, `isAiMessage`, `isRuntimeNote`, `runtimeNoteKind`); they
+ * are the same bindings here.
+ */
+export { 
+/** A message's text, whatever content-block shape it arrived in. */
+contentToString, 
+/** The LangChain message kind (`ai`, `human`, `tool`, `system`, …). */
+messageTypeOf, 
+/** Whether a message is the assistant's. */
+isAiMessage, 
+/** Whether a message is a person's (or a human-role runtime note — see `isRuntimeNote`). */
+isHumanMessage, 
+/** Whether the runtime wrote this message rather than a person. */
+isRuntimeNote, 
+/** Which kind of runtime note a message is, or `null` if a person wrote it. */
+runtimeNoteKind, 
+/** The last thing the agent said to the person; tool results and runtime notes are skipped. */
+lastAgentText, 
+/** Whether a message opens a turn: something the session was told. */
+opensTurn, 
+/** The messages appended since a count read earlier — what one `invoke` added. */
+messagesSince, 
+/** The trailing turn: from the last thing the session was told to the end. */
+lastTurn, } from "../core/message-readers.js";
+//# sourceMappingURL=messages.js.map

package/dist/public/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/public/messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO;AACL,oEAAoE;AACpE,eAAe;AACf,uEAAuE;AACvE,aAAa;AACb,4CAA4C;AAC5C,WAAW;AACX,4FAA4F;AAC5F,cAAc;AACd,mEAAmE;AACnE,aAAa;AACb,+EAA+E;AAC/E,eAAe;AACf,+FAA+F;AAC/F,aAAa;AACb,sEAAsE;AACtE,SAAS;AACT,kFAAkF;AAClF,aAAa;AACb,8EAA8E;AAC9E,QAAQ,GACT,MAAM,4BAA4B,CAAC"}

package/dist/public/sandbox.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `@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).
+ */
+/** What a hook answers with. */
+export interface HookVerdict {
+    verdict: "ok" | "correct" | "veto";
+    reason: string;
+}
+/** One transcript message, as plain data. `role` is `user`, `assistant`, `tool`, `system`, or `runtime`. */
+export interface HookMessage {
+    role: string;
+    text: string;
+    toolCalls?: {
+        name: string;
+        args: unknown;
+    }[];
+    /** Tool results: the tool that produced the text. */
+    tool?: string;
+    /** Runtime notes: which kind of note (an arrival, a decision, an error route). */
+    note?: string;
+}
+/** The machine context a lifecycle hook receives (also the global `args`). */
+export interface HookArgs {
+    state: string;
+    phase: "before" | "after";
+    /** Which trigger started the run — its id. A run's input is in `variables`. */
+    trigger?: string;
+    /** The session's variables as a plain `name → value` map. Read-only: assigning changes nothing. */
+    variables: Record<string, unknown>;
+    /** The recent transcript, newest last. */
+    messages: HookMessage[];
+    /** `after` hooks on an advance: the transition being attempted and the agent's reason. */
+    from?: string;
+    to?: string;
+    reason?: string;
+}
+/**
+ * The privileged tool-call bridge (`tools.*`): the agent's tools as async
+ * functions keyed by camelCase name (`tools.readFile({ file_path })`). A hook
+ * runs on runtime authority, so the state's allow list does not bind it; the
+ * safety rules, the workflow `policy`, and consumer rules do. A refused call
+ * rejects with the governance reason.
+ */
+export type SandboxTools = Record<string, (input?: unknown) => Promise<unknown>>;
+/**
+ * One committed traversal step of a session's audit trail: the state entered,
+ * the kind of edge that committed it, the recorded rationale when one was given
+ * (on `trigger` steps, the trigger id), and — on `sub-workflow` steps — the
+ * child workflow and whether it completed. Each turn begins with a `trigger`
+ * step; the order read back is the order committed.
+ */
+export interface TrailStep {
+    to: string;
+    kind: "trigger" | "agent" | "human" | "sub-workflow" | "reset" | "on_error";
+    reason?: string;
+    workflow?: string;
+    status?: "ok" | "error";
+    /** Epoch milliseconds at commit. */
+    ts: number;
+}
+/** The single object a hook function is called with. */
+export interface HookInput extends HookArgs {
+    tools: SandboxTools;
+}
+/**
+ * A hook's return: a verdict, `false` (veto), or nothing (`ok`).
+ *
+ * Nothing else is read as an opinion. A hook's return value *is* its verdict,
+ * so any other object — a misspelled `verdict`, a retired shape like
+ * `{ ok: false, reason }` — is a verdict the author got wrong and fails closed
+ * with its keys named, rather than being read as `ok` and silently permitting
+ * what the hook meant to block. Non-object values (`true`, a number, a bare
+ * body's incidental completion value) stay `ok`.
+ *
+ * These rules are the whole verdict vocabulary, and every hook kind is read
+ * through them — a custom kind registered via `hookExecutors` included.
+ */
+export type HookResult = HookVerdict | false | void | undefined;
+export type HookFn = (input: HookInput) => HookResult | Promise<HookResult>;
+export declare function ok(reason?: string): HookVerdict;
+export declare function veto(reason: string): HookVerdict;
+export declare function correct(reason: string): HookVerdict;
+/** Alias for `export default`: `export default defineHook(async (input) => …)`. Identity at runtime. */
+export declare function defineHook(fn: HookFn): HookFn;