@archmax-ai/harness 0.0.0

package/dist/machine/machine.d.ts

@@ -0,0 +1,273 @@
+import { type WorkflowEventHandler } from "../core/events.js";
+import type { Workspace } from "../core/workspace.js";
+import type { MountPrefixes } from "../core/zones.js";
+import { type GuardResolutionFailure } from "./allow.js";
+import { type VariableStore } from "./variables.js";
+import { type WorkflowSpecPaths } from "./load-spec.js";
+import { type SessionPath, type TriggerBinding } from "./triggers.js";
+import { ALWAYS_ALLOWED_TOOLS, UNGRANTABLE_TOOLS, ESSENTIAL_TOOLS } from "./tool-names.js";
+import { type ForbidEntry, type HarnessSettings, type LifecycleHook, type MachineSpec, type MachineTransition } from "./types.js";
+export { ALWAYS_ALLOWED_TOOLS, ESSENTIAL_TOOLS, UNGRANTABLE_TOOLS };
+/**
+ * Read-only context a guard check consults: the run's variables (for `${{…}}`
+ * substitution) and a sink for the first unresolvable reference, which the
+ * kernel escalates to a terminal run failure rather than a retryable block.
+ */
+export interface GuardContext {
+    variables?: VariableStore;
+    onUnresolved?: (failure: GuardResolutionFailure) => void;
+}
+/**
+ * The compiled workflow: what the runtime consults for transitions, tool
+ * surfaces, enabled skills and trigger wiring. A pure view over the parsed
+ * `spec` — no workspace, no file access. Declarations are read off `spec`
+ * directly (`machine.spec.states[slug].instructions`); the methods here are the
+ * derived answers.
+ */
+export declare class WorkflowMachine {
+    readonly spec: MachineSpec;
+    /**
+     * Host-declared tool names treated as essential — always disclosed and
+     * permitted in every state, exactly like the built-in {@link ESSENTIAL_TOOLS}.
+     */
+    private readonly extraEssential;
+    /**
+     * The entry state: the `manual` start state, else the first declared start
+     * state, else the first declared state — so a machine always has one.
+     */
+    readonly entry: string;
+    private bindingsCache?;
+    private constructor();
+    /**
+     * Load the machine from its two files, or `null` when nothing loads to a
+     * usable machine. Load problems other than a missing file are emitted as
+     * `warning` events.
+     */
+    static load(workspace: Workspace, paths: WorkflowSpecPaths, onEvent?: WorkflowEventHandler): Promise<WorkflowMachine | null>;
+    /** Construct a machine from an already-parsed spec. */
+    static fromSpec(spec: MachineSpec, extraEssentialTools?: Iterable<string>): WorkflowMachine;
+    /**
+     * Stable content hash of the spec, written into a session's first checkpoint
+     * and compared on resume.
+     */
+    get specHash(): string;
+    /** Whether this machine is out of service (see {@link specDisabled}). */
+    get disabled(): boolean;
+    /** Runtime knobs from `settings`, defaults applied. */
+    get harnessSettings(): HarnessSettings;
+    /**
+     * The model id `state`'s turns run on, or `undefined` when the workflow leaves
+     * the choice to the assembly. The one place the chain is derived — the state's
+     * `model`, else the root's `settings.model` — so nothing re-implements the
+     * precedence. An unknown slug reads as the workflow's own declaration, which is
+     * what the runtime wants for a position it cannot resolve.
+     */
+    modelFor(state: string): string | undefined;
+    /**
+     * Every distinct model id this spec declares, in a stable order (the root's
+     * first, then each state's in declaration order). What assembly builds a model
+     * for, and what it names when an explicit `model` instance makes them inert.
+     */
+    declaredModels(): string[];
+    /**
+     * The skills the workflow grants in **every** state: the root's
+     * `allow_always`, resolved against the registry. A state's `skills.allow`
+     * adds to this list, exactly as `tools.allow` adds to `tools.allow_always`.
+     * An absent key grants nothing, the same as `allow_always: []`. A declared
+     * slug the registry does not provide is dropped (and reported by `validate`).
+     */
+    workflowAlwaysSkills(available: readonly string[]): string[];
+    /** The slugs `skills.forbid_always` denies in every state of this workflow. */
+    workflowForbiddenSkills(): string[];
+    /**
+     * The slugs denied while `state` is active, from either level. Declaration
+     * order, workflow-wide first, so a caller rendering them is byte-stable.
+     */
+    forbiddenSkills(state: string): string[];
+    /**
+     * Which level denies `slug` in `state`, or `undefined` if neither does — so a
+     * refusal can say whether a list forbade the bundle or nothing granted it.
+     */
+    skillDenial(state: string, slug: string): "workflow" | "state" | undefined;
+    /**
+     * The skills enabled while `state` is active — the one answer the kernel's
+     * skill rule, prompt disclosure, the PTC listing redaction and `validate` all
+     * consult.
+     *
+     * The grant is additive: the state's own `skills.allow` followed by the root's
+     * `allow_always`, each in declaration order, deduplicated by slug. The denial
+     * beats it: anything `skills.forbid_always` or the state's `skills.forbid`
+     * names is removed, so **deny beats allow and no narrower level widens a
+     * denial**. Order is declaration order from the frozen spec, so everything
+     * rendered from this — the prompt's skills section above all — is byte-stable
+     * across the model calls of a turn.
+     */
+    enabledSkills(state: string, available: readonly string[]): string[];
+    /**
+     * The governed mounts the workflow enables in **every** state: the root's
+     * `mounts.allow_always`, filtered to the names the host declared governed. A
+     * state's `mounts.allow` adds to this list, exactly as `skills.allow` adds to
+     * `skills.allow_always`. An absent key grants nothing, the same as
+     * `allow_always: []`. A name the table does not govern is dropped (and
+     * reported by `validate`) — an ungoverned mount needs no grant.
+     */
+    workflowAlwaysMounts(governed: readonly string[]): string[];
+    /**
+     * The names `mounts.forbid_always` denies in every state of this workflow —
+     * governed or not, since a denial subtracts an ungoverned mount's standing
+     * visibility too.
+     */
+    workflowForbiddenMounts(): string[];
+    /**
+     * The mount names denied while `state` is active, from either level.
+     * Declaration order, workflow-wide first, so a caller rendering them is
+     * byte-stable.
+     */
+    forbiddenMounts(state: string): string[];
+    /**
+     * Which level denies `name` in `state`, or `undefined` if neither does — so a
+     * refusal can say whether a list forbade the mount or nothing enabled it.
+     */
+    mountDenial(state: string, name: string): "workflow" | "state" | undefined;
+    /**
+     * The **governed** mounts enabled while `state` is active — the one answer the
+     * kernel's mount rule, prompt disclosure, the listing redaction and `validate`
+     * all consult. Ungoverned mounts are not in it: they are visible in every
+     * state without a grant, and `forbiddenMounts` is what takes one away.
+     *
+     * The grant is additive: the state's own `mounts.allow` followed by the root's
+     * `allow_always`, each in declaration order, deduplicated by name. The denial
+     * beats it: anything `mounts.forbid_always` or the state's `mounts.forbid`
+     * names is removed, so **deny beats allow and no narrower level widens a
+     * denial**. Order is declaration order from the frozen spec, so everything
+     * rendered from this is byte-stable across the model calls of a turn.
+     */
+    enabledMounts(state: string, governed: readonly string[]): string[];
+    /**
+     * Whether writes to `name` are permitted while `state` is active — the second
+     * half of a mount grant, beside which states may see it at all.
+     *
+     * A mount is writable here only when the host declared it writable **and** no
+     * applicable grant narrowed it to `read`. Read-only is a restriction, so it
+     * behaves like every other restriction in this schema: whichever level asks
+     * for it gets it, and no narrower level widens it back. `read_write` on a
+     * mount the host serves read-only is therefore inert (reported by `validate`)
+     * — the host's posture is the ceiling, not a default to argue with.
+     *
+     * An ungoverned mount takes the host's posture in every state: it carries no
+     * grant to qualify.
+     */
+    mountWritable(state: string, name: string, mounts: MountPrefixes): boolean;
+    transitionTargets(from: string): string[];
+    getTransition(from: string, to: string): MachineTransition | undefined;
+    /** The state a failed turn routes to (`on_error`), if declared and present. */
+    onError(state: string): string | undefined;
+    /** A state with no declared outgoing transitions is terminal (ends the run). */
+    isTerminal(state: string): boolean;
+    /** Whether a state is a human decision state (a person picks the edge). */
+    isHumanState(state: string): boolean;
+    /**
+     * States a run can reach: the start states plus everything transitively
+     * reachable through transitions and `on_error` routes. A state no start state
+     * reaches is dead in the definition, so nothing it declares widens the surface.
+     */
+    reachableStates(): Set<string>;
+    /** Each state's normalized `before`/`after` hook lists, for states declaring any. */
+    lifecycleHooks(): Record<string, LifecycleHook>;
+    /**
+     * The sibling workflows this machine may delegate to: every
+     * `archmax_workflow_<slug>` named in `tools.allow_always` and in the given
+     * state's `tools.allow` — or, with no state, in any **reachable** state's.
+     * Naming a target in governance *is* declaring the delegation.
+     */
+    delegationTargets(state?: string): string[];
+    /** Run variables this state must have set before it may be left. */
+    requiredVariables(state: string): string[];
+    private allowEntries;
+    private allowAlwaysEntries;
+    /**
+     * The effective essential set: the built-ins plus the host's `essentialTools`.
+     * Unconditional — no property of a workspace or a spec adds to it, and `task`
+     * is in it under no circumstances (see {@link UNGRANTABLE_TOOLS}).
+     */
+    private essentialTools;
+    /**
+     * Every denial entry that applies in `state`: the workflow's `forbid_always`
+     * followed by the state's own `forbid`. Order is presentational only — both
+     * block, and a denial is evaluated ahead of every grant.
+     */
+    forbidEntries(state: string): ForbidEntry[];
+    /**
+     * The entries that govern `state`, in precedence order — the one derivation
+     * enforcement and disclosure both read. A tool is decided by exactly one tier:
+     * the state's own entries when they name it (the narrower constraint, even for
+     * an essential tool); else the essential grant; else `allow_always`. An
+     * `allow_always` entry for a tool the state mentions or that is essential is
+     * therefore inert.
+     */
+    private effectiveEntries;
+    /**
+     * Whether a tool call is statically permitted in `state`. Closed by default:
+     * the always-allowed controls pass; otherwise some effective entry must name
+     * the tool and match its arguments.
+     */
+    checkAllowed(state: string, tool: string, args: Record<string, unknown>, ctx?: GuardContext): boolean;
+    /**
+     * The tool names disclosed to the model while `state` is active: every tool
+     * an effective entry names plus the controls (`archmax_advance` omitted for a
+     * terminal state, where every call to it would be rejected), minus the tools
+     * denied here by name. Name-level only — argument enforcement stays with the
+     * kernel at call time.
+     */
+    disclosedTools(state: string): Set<string>;
+    private renderEntry;
+    /**
+     * Model-facing description of what `checkAllowed` enforces in a state: the
+     * effective entries in precedence order, minus any tool denied here by name,
+     * then the always-allowed controls the state discloses. A denial that leaves
+     * the tool usable for other arguments (a guarded entry) leaves it listed —
+     * the same line disclosure draws — so the model's picture matches enforcement
+     * either way.
+     */
+    describeAllowed(state: string): string;
+    /**
+     * Model-facing lines describing the argument constraints that bind in a
+     * state, rendered through the same resolver the kernel enforces with so an
+     * unresolved reference is shown as unresolved-and-named rather than as a
+     * placeholder the model might pass literally. Empty when none bind.
+     */
+    describeArgConstraints(state: string, variables?: VariableStore): string[];
+    /**
+     * Every trigger the spec declares, read from the states that declare them —
+     * computed once per machine.
+     */
+    triggerBindings(): Map<string, TriggerBinding>;
+    /** The declared start states as `{ trigger, state }` pairs, in declaration order. */
+    startStates(): {
+        trigger: string;
+        state: string;
+    }[];
+    /**
+     * The state a trigger enters, or `undefined` for an id no state declares.
+     * `manual` is the one entry for every ingress — the CLI, an SDK invocation
+     * naming no trigger, a host firing that names it, and a delegation.
+     */
+    startStateForTrigger(id: string): string | undefined;
+    /** The session path declared for a trigger, if it declares one. */
+    sessionPathForTrigger(id: string): SessionPath | undefined;
+    /**
+     * The host-resolved `message:` declaration for a trigger: the parsed path,
+     * `false` for "firings carry no message", or `undefined` when undeclared.
+     */
+    messagePathForTrigger(id: string): SessionPath | false | undefined;
+    /** The host-resolved `connection:` slug declared for a trigger, if any. */
+    connectionForTrigger(id: string): string | undefined;
+    /** The run variables a firing of this trigger must supply, if declared. */
+    requiresForTrigger(id: string): string[] | undefined;
+    /**
+     * The run variables a run started through this trigger guarantees are set when
+     * it completes, if declared — the only variables that cross a sub-run boundary
+     * upward.
+     */
+    returnsForTrigger(id: string): string[] | undefined;
+}