@archmax-ai/harness 0.0.0

package/dist/behaviour/support.js

@@ -0,0 +1,339 @@
+/**
+ * Shared support for the behaviour-level suite.
+ *
+ * Everything here drives the runtime through the **public API only** — the
+ * `../index.js` barrel and `../public/testing.js` — so that an internal
+ * restructuring can be verified against these tests without touching them. No
+ * test in this directory imports from `src/workflow/*`, `src/machine/*`,
+ * `src/kernel/*` or any other internal module.
+ *
+ * Three pieces:
+ *
+ *  - {@link ScriptedModel}: a fake chat model that replays a queue of turns —
+ *    tool calls (`archmax_advance`, `archmax_wait`, `write_file`, a delegation
+ *    tool, …) and final text replies — and records what it was bound with.
+ *  - {@link makeWorkspace}: writes an authored workspace (workflow.yaml, hooks,
+ *    skills) into a temp directory, cleaned up by {@link cleanupWorkspaces}.
+ *  - {@link assemble} / {@link turn}: assemble a governed agent over a memory
+ *    session store with an event sink, and drive one conversational turn.
+ */
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { stringify as toYaml } from "yaml";
+import { AIMessage } from "@langchain/core/messages";
+import { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { contentToString, createAgent, createMemorySessionStore, isAiMessage, } from "../index.js";
+/**
+ * A model that replays a fixed script of turns. `bindTools` returns the same
+ * instance so the cursor is shared across every binding the agent performs —
+ * the script is the run's plan, not one binding's. When the script runs out the
+ * model replies with a final `done`, so every turn terminates.
+ */
+export class ScriptedModel extends BaseChatModel {
+    turns;
+    cursor = 0;
+    lastBound = [];
+    seq = 0;
+    /** Tool calls the script actually issued, in order. */
+    issued = [];
+    /** Every model invocation, in order. */
+    calls = [];
+    /** What to say when the script is exhausted. */
+    fallbackReply;
+    /**
+     * The id this model was configured to run, as a real client exposes it — what
+     * `modelIdOf` reads and what the runtime prices against when a response names
+     * no model. Left undefined by default so an existing case is unchanged.
+     */
+    model;
+    constructor(turns, opts = {}) {
+        super({});
+        this.turns = turns;
+        this.fallbackReply = opts.fallbackReply ?? "done";
+        if (opts.model !== undefined)
+            this.model = opts.model;
+    }
+    _llmType() {
+        return "archmax-behaviour-scripted";
+    }
+    /** How many scripted turns are still unplayed. */
+    get remaining() {
+        return Math.max(0, this.turns.length - this.cursor);
+    }
+    /** Append turns to the script — for a later conversational turn on the same agent. */
+    enqueue(...turns) {
+        this.turns.push(...turns);
+    }
+    bindTools(tools) {
+        this.lastBound = tools.map((t) => String(t?.name ?? ""));
+        return this;
+    }
+    async _generate(messages) {
+        const system = messages.find((m) => m.getType() === "system");
+        this.calls.push({
+            tools: [...this.lastBound],
+            systemPrompt: system ? contentToString(system.content) : "",
+            messageTypes: messages.map((m) => m.getType()),
+        });
+        // The cursor only moves past a scripted turn: a fallback reply consumes
+        // nothing, so turns enqueued later are still played in order.
+        const scripted = this.turns[this.cursor];
+        if (scripted)
+            this.cursor += 1;
+        const turn = scripted ?? { reply: this.fallbackReply };
+        const usage = turn.usage
+            ? {
+                usage_metadata: {
+                    input_tokens: turn.usage.input,
+                    output_tokens: turn.usage.output,
+                    total_tokens: turn.usage.input + turn.usage.output,
+                },
+                ...(turn.reports ? { response_metadata: { model_name: turn.reports } } : {}),
+            }
+            : {};
+        if ("reply" in turn) {
+            const message = new AIMessage({ content: turn.reply, ...usage });
+            return { generations: [{ text: turn.reply, message }] };
+        }
+        const calls = "batch" in turn ? turn.batch : [{ tool: turn.tool, args: turn.args }];
+        const toolCalls = calls.map((c) => {
+            this.issued.push({ name: c.tool, args: c.args });
+            return { id: `call-${++this.seq}`, name: c.tool, args: c.args };
+        });
+        const message = new AIMessage({ content: "", tool_calls: toolCalls, ...usage });
+        return { generations: [{ text: "", message }] };
+    }
+}
+// --- Temp workspaces ----------------------------------------------------------
+const tmpRoots = [];
+/**
+ * Write an authored workspace into a fresh temp directory. Values are file
+ * contents; a non-string value is serialized as YAML (handy for `workflow.yaml`
+ * declared as an object). Returns the root path.
+ */
+export function makeWorkspace(files) {
+    const root = mkdtempSync(join(tmpdir(), "archmax-behaviour-"));
+    tmpRoots.push(root);
+    for (const [rel, contents] of Object.entries(files)) {
+        const full = resolve(root, rel);
+        mkdirSync(dirname(full), { recursive: true });
+        writeFileSync(full, typeof contents === "string" ? contents : toYaml(contents));
+    }
+    return root;
+}
+/** Remove every workspace {@link makeWorkspace} created. Call from `afterEach`. */
+export function cleanupWorkspaces() {
+    while (tmpRoots.length)
+        rmSync(tmpRoots.pop(), { recursive: true, force: true });
+}
+/** A `SKILL.md` body with the frontmatter the skill loader requires. */
+export function skillMarkdown(name, description = `The ${name} skill.`) {
+    return `---\nname: ${name}\ndescription: ${description}\n---\n\n# ${name}\n`;
+}
+/**
+ * One inline rubric, as the value of a `{ rubric: … }` hook. A rubric is
+ * declared on the hook that applies it, so a fixture builds the declaration and
+ * drops it straight into a state's `before`/`after`.
+ */
+export function rubricDeclaration(opts = {}) {
+    return {
+        instructions: opts.instructions ?? "Judge the reply. Reply with a JSON verdict.",
+        ...(opts.maxIterations !== undefined ? { max_iterations: opts.maxIterations } : {}),
+        ...(opts.model !== undefined ? { model: opts.model } : {}),
+        ...(opts.metadata !== undefined ? { metadata: opts.metadata } : {}),
+    };
+}
+/** The default persona file every workspace here carries. */
+export const AGENTS_MD = "# Agent\n\nDo what the workflow says.\n";
+/** Assemble a governed agent over `root` with an event sink and memory storage. */
+export async function assemble(root, opts = {}) {
+    const model = opts.model ?? new ScriptedModel(opts.turns ?? []);
+    const events = [];
+    const store = opts.store ?? createMemorySessionStore();
+    const rubricModel = opts.rubricModel;
+    const agent = await createAgent({
+        workflow: opts.workflow ?? "w",
+        ...(opts.modelFactory
+            ? { modelFactory: opts.modelFactory }
+            : rubricModel
+                ? {
+                    modelFactory: (role) => (role === "agent" ? model : rubricModel),
+                }
+                : { model: model }),
+        onEvent: (event) => events.push(event),
+        workspace: { rootDir: root, sessionStore: store },
+        ...opts.params,
+    });
+    if (!agent.workflow)
+        throw new Error("expected a governed assembly");
+    return { agent: agent, model, events, store, root };
+}
+/** Drive one conversational turn on `sessionId`. */
+export async function turn(agent, sessionId, text, opts = {}) {
+    const input = {
+        messages: [{ role: "user", content: text }],
+        ...(opts.trigger ? { trigger: opts.trigger } : {}),
+    };
+    const result = (await agent.invoke(input, {
+        configurable: { thread_id: sessionId },
+    }));
+    const messages = result.messages ?? [];
+    return { messages, reply: lastAgentText(messages) };
+}
+/** The final assistant message carrying text, skipping tool results. */
+export function lastAgentText(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const message = messages[i];
+        if (!isAiMessage(message))
+            continue;
+        const text = contentToString(message.content).trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
+/** The type of a message (`ai`, `human`, `tool`, `system`), read across shapes. */
+export function messageType(message) {
+    const msg = message;
+    const t = msg._getType?.call(msg) ??
+        msg.getType?.call(msg) ??
+        msg.type ??
+        msg.role ??
+        "";
+    return String(t);
+}
+/** Tool results in a transcript: `{ name, content, status }`. */
+export function toolResults(messages) {
+    return messages
+        .filter((m) => messageType(m) === "tool")
+        .map((m) => {
+        const msg = m;
+        return {
+            name: String(msg.name ?? ""),
+            content: contentToString(msg.content),
+            ...(msg.status ? { status: msg.status } : {}),
+        };
+    });
+}
+// --- Event selectors ----------------------------------------------------------
+/** Events of one type, narrowed. */
+export function eventsOf(events, type) {
+    return events.filter((e) => e.type === type);
+}
+/** The states entered, in order. */
+export function statesEntered(events) {
+    return eventsOf(events, "state-enter").map((e) => e.state);
+}
+/** The agent-driven transitions (`from -> to`), in order — the opening arrival excluded. */
+export function advances(events) {
+    return eventsOf(events, "advance")
+        .filter((e) => e.from !== "__start__")
+        .map((e) => ({ from: e.from, to: e.to, ...(e.reason ? { reason: e.reason } : {}) }));
+}
+/** Names of the tools governance refused, in order. */
+export function blockedTools(events) {
+    return eventsOf(events, "tool-blocked").map((e) => e.tool);
+}
+/** Events emitted for one session only. */
+export function forSession(events, sessionId) {
+    return events.filter((e) => e.sessionId === sessionId);
+}
+// --- Spec builders ------------------------------------------------------------
+/**
+ * A two-state linear machine: `start` (manual) → `done` (terminal), with the
+ * runtime contract pinned. Extra keys are merged into the spec root.
+ */
+export function linearSpec(extra = {}) {
+    return {
+        runtime: { engine: "archmax-harness", version: "2" },
+        states: {
+            start: { triggers: { manual: null }, transitions: [{ to: "done", description: "Test edge to done." }] },
+            done: {},
+        },
+        ...extra,
+    };
+}
+/** The scripted turn that advances `to` with a reason. */
+export function advanceTo(to, reason = `moving to ${to}`) {
+    return { tool: "archmax_advance", args: { to, reason } };
+}
+/** A workspace with a persona and one workflow spec under `workflows/w/`. */
+export function workspaceWith(spec, extraFiles = {}) {
+    return makeWorkspace({
+        "AGENTS.md": AGENTS_MD,
+        "workflows/w/workflow.yaml": spec,
+        ...extraFiles,
+    });
+}
+/**
+ * A fake model for the `rubric` role that answers each dispatch with the next
+ * scripted verdict. When the framework binds a structured-output tool
+ * (`extract-*`) it is called with the verdict; otherwise the verdict is the reply
+ * text as JSON — both reach the lifecycle runner as a parseable verdict.
+ */
+export class JudgeModel extends BaseChatModel {
+    verdicts;
+    fallback;
+    failWith;
+    cursor = 0;
+    lastBound = [];
+    seq = 0;
+    /** How many times the judge was asked. */
+    get dispatches() {
+        return this.calls;
+    }
+    calls = 0;
+    constructor(verdicts, fallback = { verdict: "ok", reason: "fine" }, 
+    /**
+     * Fail every dispatch instead of answering — how an unusable `model` id
+     * surfaces, since a bad id is refused at invocation, not construction.
+     */
+    failWith) {
+        super({});
+        this.verdicts = verdicts;
+        this.fallback = fallback;
+        this.failWith = failWith;
+    }
+    _llmType() {
+        return "archmax-behaviour-judge";
+    }
+    bindTools(tools) {
+        this.lastBound = tools.map((t) => String(t?.name ?? ""));
+        return this;
+    }
+    async _generate() {
+        this.calls += 1;
+        if (this.failWith)
+            throw new Error(this.failWith);
+        const verdict = this.verdicts[this.cursor++] ?? this.fallback;
+        const extract = this.lastBound.find((name) => name.startsWith("extract-"));
+        if (extract) {
+            const message = new AIMessage({
+                content: "",
+                tool_calls: [{ id: `judge-${++this.seq}`, name: extract, args: { ...verdict } }],
+            });
+            return { generations: [{ text: "", message }] };
+        }
+        const text = JSON.stringify(verdict);
+        return { generations: [{ text, message: new AIMessage(text) }] };
+    }
+}
+// --- Store access -------------------------------------------------------------
+/** Read one file from a session store by store-relative path, or `undefined`. */
+export async function storeFile(store, path) {
+    const result = await store.backend.readRaw(path);
+    const data = result.data;
+    return typeof data?.content === "string" ? data.content : undefined;
+}
+// --- Session ids ---------------------------------------------------------------
+let sessionSeq = 0;
+/**
+ * A session id no other test in this process has used. Sandbox REPL sessions
+ * and other per-session resources are keyed by session id for the life of the
+ * process, so tests that run hooks or scripts must not share one.
+ */
+export function freshSessionId(prefix = "s") {
+    return `${prefix}-${process.pid}-${++sessionSeq}`;
+}
+//# sourceMappingURL=support.js.map

package/dist/behaviour/support.js.map

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

package/dist/cli/banner.d.ts

@@ -0,0 +1,11 @@
+export declare const BANNER_TEXT = "\n               __                     __\n ___ _________/ /  __ _  ___ ___ __  / /  ___ ________  ___ ___ ___\n/ _ `/ __/ __/ _ \\/  ' \\/ _ `/\\ \\ / / _ \\/ _ `/ __/ _ \\/ -_|_-<(_-<\n\\_,_/_/  \\__/_//_/_/_/_/\\_,_//_\\_\\ /_//_/\\_,_/_/ /_//_/\\__/___/___/\n";
+export interface BannerContext {
+    /** Env to check for `ARCHMAX_CLI_NO_BANNER` (defaults to `process.env`). */
+    env?: NodeJS.ProcessEnv;
+    /** Whether `stderr` is a TTY (defaults to `process.stderr.isTTY`). */
+    isTTY?: boolean;
+}
+/** True when the startup banner should be printed for the given context. */
+export declare function shouldShowBanner(ctx?: BannerContext): boolean;
+/** Print the banner to `stderr` when {@link shouldShowBanner} allows it for the live process context. */
+export declare function printBanner(): void;

package/dist/cli/banner.js

@@ -0,0 +1,29 @@
+/**
+ * Startup banner: the archmax harness ASCII wordmark, in the spirit of oh-my-zsh's
+ * startup art. The banner is written to `stderr` only, never `stdout`, so it
+ * can never pollute piped/redirected output.
+ */
+import { createStyle } from "./style.js";
+export const BANNER_TEXT = `
+               __                     __
+ ___ _________/ /  __ _  ___ ___ __  / /  ___ ________  ___ ___ ___
+/ _ \`/ __/ __/ _ \\/  ' \\/ _ \`/\\ \\ / / _ \\/ _ \`/ __/ _ \\/ -_|_-<(_-<
+\\_,_/_/  \\__/_//_/_/_/_/\\_,_//_\\_\\ /_//_/\\_,_/_/ /_//_/\\__/___/___/
+`;
+/** True when the startup banner should be printed for the given context. */
+export function shouldShowBanner(ctx = {}) {
+    const env = ctx.env ?? process.env;
+    const isTTY = ctx.isTTY ?? Boolean(process.stderr.isTTY);
+    if (env.ARCHMAX_CLI_NO_BANNER !== undefined && env.ARCHMAX_CLI_NO_BANNER !== "")
+        return false;
+    if (!isTTY)
+        return false;
+    return true;
+}
+/** Print the banner to `stderr` when {@link shouldShowBanner} allows it for the live process context. */
+export function printBanner() {
+    if (shouldShowBanner()) {
+        console.error(createStyle().cyan(BANNER_TEXT));
+    }
+}
+//# sourceMappingURL=banner.js.map

package/dist/cli/banner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"banner.js","sourceRoot":"","sources":["../../src/cli/banner.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEzC,MAAM,CAAC,MAAM,WAAW,GAAG;;;;;CAK1B,CAAC;AASF,4EAA4E;AAC5E,MAAM,UAAU,gBAAgB,CAAC,MAAqB,EAAE;IACtD,MAAM,GAAG,GAAG,GAAG,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG,CAAC;IACnC,MAAM,KAAK,GAAG,GAAG,CAAC,KAAK,IAAI,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEzD,IAAI,GAAG,CAAC,qBAAqB,KAAK,SAAS,IAAI,GAAG,CAAC,qBAAqB,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC9F,IAAI,CAAC,KAAK;QAAE,OAAO,KAAK,CAAC;IACzB,OAAO,IAAI,CAAC;AACd,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,WAAW;IACzB,IAAI,gBAAgB,EAAE,EAAE,CAAC;QACvB,OAAO,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC;IACjD,CAAC;AACH,CAAC"}

package/dist/cli/bootstrap.d.ts

@@ -0,0 +1,33 @@
+import type { GovernedAgent } from "../agent.js";
+import { type TriggerInput } from "../machine/triggers.js";
+import { type UsageTracker } from "../core/usage.js";
+import { type Style } from "./style.js";
+import { type Invocation } from "./command.js";
+/**
+ * The `<workflow>` slot: given, or inferred when the workspace holds exactly
+ * one workflow — the common single-workflow workspace needs no repetition.
+ */
+export declare function resolveWorkflow(given: string | undefined, rootDir: string | undefined): string;
+/** `--variables` must be a JSON object; anything else is an argument error before any assembly. */
+export declare function parseVariablesJson(raw: string | undefined): Record<string, unknown> | undefined;
+/** The one session header every command prints to stderr. Loads `.env` first so the model line is the effective one. */
+export declare function printSessionHeader(style: Style, workflow: string, rootDir: string | undefined, showModel?: boolean): void;
+/** Wire the state flow (and `--verbose` raw lines) behind a usage tracker whose handler the agent receives. */
+export declare function createEventSink(style: Style, verbose: boolean, view?: import("./state-flow.js").StateFlowRenderer): UsageTracker;
+export declare const isKnown: (e: unknown) => e is Error;
+/** Assemble the governed agent for a CLI command; a known load failure becomes a one-line `CliError`. */
+export declare function bootstrap(workflow: string, rootDir: string | undefined, usage: UsageTracker, extra?: {
+    trigger?: TriggerInput;
+    variables?: Record<string, unknown>;
+}): Promise<GovernedAgent>;
+/**
+ * Everything a session command shares: the id is validated before anything is
+ * assembled, the agent is bootstrapped under the (given or inferred) workflow,
+ * the body runs, known runtime refusals become one-line errors, and the
+ * session is disposed however the body ended.
+ */
+export declare function withSession(inv: Invocation, sessionId: string | undefined, body: (ctx: {
+    agent: GovernedAgent;
+    style: Style;
+    usage: UsageTracker;
+}) => Promise<number>): Promise<number>;

package/dist/cli/bootstrap.js

@@ -0,0 +1,153 @@
+/**
+ * Assembling an agent for a CLI command: which workflow (given, or inferred
+ * from a single-workflow workspace), the `.env`-backed session header, the
+ * event sink behind the state flow and the usage tracker, and the one
+ * `withSession` wrapper every session command runs its body inside.
+ */
+import { existsSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { createAgent } from "../assembly/index.js";
+import { UnknownTriggerError } from "../machine/triggers.js";
+import { WorkflowDisabledError, WorkflowLoadError } from "../machine/load-spec.js";
+import { EmptyMessageError, InvalidDecisionTargetError, MissingDeliveryTriggerError, SessionNotAwaitingInputError, SessionNotParkedError, } from "../sessions/resume.js";
+import { SessionNotResumableError, UnknownSessionTriggerError } from "../sessions/resolve.js";
+import { sessionIdRejection } from "../core/session-store.js";
+import { UnsupportedRuntimeContractError } from "../runtime/contract.js";
+import { loadDotenv, resolveWorkspaceRoot } from "../env.js";
+import { createUsageTracker } from "../core/usage.js";
+import { originLabel, renderEventLine } from "../core/events.js";
+import { createStyle, icons } from "./style.js";
+import { createStateFlowRenderer } from "./state-flow.js";
+import { CliError, UsageError, err } from "./command.js";
+/**
+ * The `<workflow>` slot: given, or inferred when the workspace holds exactly
+ * one workflow — the common single-workflow workspace needs no repetition.
+ */
+export function resolveWorkflow(given, rootDir) {
+    if (given)
+        return given;
+    const dir = resolve(resolveWorkspaceRoot(rootDir), "workflows");
+    const slugs = existsSync(dir)
+        ? readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && existsSync(resolve(dir, e.name, "workflow.yaml")))
+            .map((e) => e.name)
+        : [];
+    if (slugs.length === 1)
+        return slugs[0];
+    if (slugs.length === 0)
+        throw new UsageError(`a workflow is required and none was found under ${dir}`);
+    throw new UsageError(`a workflow is required; this workspace has several: ${slugs.sort().join(", ")}`);
+}
+/** `--variables` must be a JSON object; anything else is an argument error before any assembly. */
+export function parseVariablesJson(raw) {
+    if (raw === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(raw);
+    }
+    catch {
+        throw new UsageError("--variables is not valid JSON");
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new UsageError('--variables must encode a JSON object (e.g. \'{"from_email":"a@b.com"}\')');
+    }
+    return value;
+}
+/** The raw event line for `--verbose`, including the two events the default console output skips. */
+function rawEventLine(event) {
+    switch (event.type) {
+        case "agent-text":
+            return `[agent:${event.state}] ${event.text}`;
+        case "tool-called":
+            return (`[workflow:${event.state}] tool ${event.tool}${event.detail ? ` ${event.detail}` : ""}` +
+                `${event.origin ? ` (from a ${originLabel(event.origin)})` : ""}`);
+        default:
+            return renderEventLine(event) ?? "";
+    }
+}
+/** The one session header every command prints to stderr. Loads `.env` first so the model line is the effective one. */
+export function printSessionHeader(style, workflow, rootDir, showModel = false) {
+    loadDotenv(rootDir);
+    err(style.cyan(style.bold(`${icons.diamond} ${workflow}`)));
+    err(`  ${style.dim("directory")}  ${resolveWorkspaceRoot(rootDir)}`);
+    if (showModel)
+        err(`  ${style.dim("model")}      ${process.env.ARCHMAX_MODEL ?? "(unset — see .env)"}`);
+    err("");
+}
+/** Wire the state flow (and `--verbose` raw lines) behind a usage tracker whose handler the agent receives. */
+export function createEventSink(style, verbose, view = createStateFlowRenderer(process.stderr, style)) {
+    return createUsageTracker({
+        onEvent: (event) => {
+            if (verbose) {
+                const line = rawEventLine(event);
+                if (line)
+                    err(line);
+            }
+            view.onEvent(event);
+        },
+    });
+}
+const KNOWN_ERRORS = [
+    UnsupportedRuntimeContractError,
+    WorkflowLoadError,
+    UnknownTriggerError,
+    WorkflowDisabledError,
+    SessionNotParkedError,
+    InvalidDecisionTargetError,
+    EmptyMessageError,
+    SessionNotAwaitingInputError,
+    MissingDeliveryTriggerError,
+    SessionNotResumableError,
+    UnknownSessionTriggerError,
+];
+export const isKnown = (e) => KNOWN_ERRORS.some((cls) => e instanceof cls);
+/** Assemble the governed agent for a CLI command; a known load failure becomes a one-line `CliError`. */
+export async function bootstrap(workflow, rootDir, usage, extra = {}) {
+    try {
+        const agent = await createAgent({
+            workflow,
+            ...(rootDir !== undefined ? { workspace: { rootDir } } : {}),
+            onEvent: usage.handler,
+            ...(extra.trigger ? { trigger: extra.trigger } : {}),
+            ...(extra.variables ? { variables: extra.variables } : {}),
+        });
+        if (!agent.workflow)
+            throw new CliError(`workflow '${workflow}' assembled without a machine.`);
+        return agent;
+    }
+    catch (e) {
+        if (isKnown(e))
+            throw new CliError(e.message);
+        throw e;
+    }
+}
+/**
+ * Everything a session command shares: the id is validated before anything is
+ * assembled, the agent is bootstrapped under the (given or inferred) workflow,
+ * the body runs, known runtime refusals become one-line errors, and the
+ * session is disposed however the body ended.
+ */
+export async function withSession(inv, sessionId, body) {
+    const rejection = sessionId === undefined ? null : sessionIdRejection(sessionId);
+    if (rejection)
+        throw new UsageError(`invalid session id '${sessionId}' - ${rejection}. Use one from 'archmax sessions'.`);
+    const workflow = resolveWorkflow(inv.values.workflow, inv.root);
+    const style = createStyle();
+    printSessionHeader(style, workflow, inv.root);
+    const usage = createEventSink(style, inv.values.verbose === true);
+    const agent = await bootstrap(workflow, inv.root, usage);
+    try {
+        return await body({ agent, style, usage });
+    }
+    catch (e) {
+        if (isKnown(e))
+            throw new CliError(e.message);
+        throw e;
+    }
+    finally {
+        if (sessionId !== undefined)
+            agent.dispose(sessionId);
+    }
+}
+//# sourceMappingURL=bootstrap.js.map

package/dist/cli/bootstrap.js.map

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

package/dist/cli/command.d.ts

@@ -0,0 +1,39 @@
+export interface Positional {
+    name: string;
+    required: boolean;
+    description: string;
+    /** Joins every remaining positional with spaces (a prompt or message needs no quoting). */
+    rest?: boolean;
+}
+export interface OptionSpec {
+    type: "string" | "boolean";
+    description: string;
+    placeholder?: string;
+    short?: string;
+}
+export type Values = Record<string, string | boolean | undefined>;
+export interface Invocation {
+    positionals: string[];
+    values: Values;
+    root: string | undefined;
+}
+export interface Command {
+    name: string;
+    summary: string;
+    description?: string;
+    positionals: Positional[];
+    options: Record<string, OptionSpec>;
+    run(inv: Invocation): Promise<number>;
+}
+/** A failure of the invocation itself: exit 2, one line, a `--help` hint — never a usage dump. */
+export declare class UsageError extends Error {
+}
+/** A failure the command established after parsing: exit 1, one line. */
+export declare class CliError extends Error {
+}
+export declare const GLOBAL_OPTIONS: Record<string, OptionSpec>;
+export declare const out: (line: string) => void;
+export declare const err: (line: string) => void;
+export declare function parseInvocation(cmd: Command, args: string[]): Invocation;
+export declare function commandHelp(cmd: Command): string;
+export declare function topLevelHelp(commands: Command[]): string;