@archmax-ai/harness 0.0.0

package/dist/env.js

@@ -0,0 +1,271 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { ChatOpenAI, ChatOpenAICompletions } from "@langchain/openai";
+import dotenv from "dotenv";
+import { DEFAULT_PRICING_KEY } from "./core/usage.js";
+const here = dirname(fileURLToPath(import.meta.url));
+/**
+ * Package install root — the directory containing this file's parent (`dist/`
+ * when published/built, `src/` in development). Used only to locate assets
+ * bundled with the package, never the consumer's workspace or configuration.
+ */
+export const PACKAGE_ROOT = resolve(here, "..");
+/** Installed package implementation version, read from the package's `package.json`. */
+export const PACKAGE_VERSION = (() => {
+    try {
+        const pkg = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, "package.json"), "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : "0.0.0";
+    }
+    catch {
+        return "0.0.0";
+    }
+})();
+/** Return the first existing directory among the candidates, else the first. */
+function firstExistingDir(candidates) {
+    for (const candidate of candidates) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    return candidates[0];
+}
+/**
+ * The authoring skill bundled with the package — the parent directory holding
+ * `archmax-harness/` (`SKILL.md` + `references/*.md`), which teaches a coding agent how
+ * to author a workspace. Resolved to `dist/authoring-skill` when built or
+ * installed, with a repo-checkout fallback to the top-level `skills/` when
+ * running from `src/`. Consumers mount it directly so the skill always matches
+ * the installed SDK version instead of a synced copy.
+ */
+export const BUNDLED_AUTHORING_SKILL_DIR = firstExistingDir([
+    resolve(here, "authoring-skill"),
+    resolve(here, "..", "skills"),
+]);
+/** @deprecated Use {@link BUNDLED_AUTHORING_SKILL_DIR}; same value, kept for one release. */
+export const BUNDLED_SKILLS_DIR = BUNDLED_AUTHORING_SKILL_DIR;
+/** Resolve the agent workspace root: an explicit path, else the consumer's cwd. */
+export function resolveWorkspaceRoot(rootDir) {
+    return rootDir ? resolve(rootDir) : process.cwd();
+}
+let lastEnvFileLoaded = null;
+/**
+ * Variables whose current value came from a `.env` file rather than from the
+ * real process environment. Only these may be replaced by a later `.env`.
+ */
+const fromEnvFile = new Set();
+/**
+ * Load `.env` from the resolved workspace root (or cwd) if present.
+ *
+ * Two rules, in this order: the real process environment always wins, and a
+ * later `.env` wins over an earlier one. The second is why this does not just
+ * call `dotenv.config` — dotenv never overrides an already-set variable, and it
+ * cannot tell its own earlier assignment from a real environment variable. The
+ * import-time cwd load below is an earlier one, so without the distinction a
+ * stray `.env` in whatever directory the process happened to start in would
+ * silently outrank the workspace root that owns the configuration (issue #23).
+ */
+export function loadDotenv(rootDir) {
+    const envFile = resolve(resolveWorkspaceRoot(rootDir), ".env");
+    if (envFile === lastEnvFileLoaded)
+        return;
+    if (!existsSync(envFile))
+        return;
+    // Parsed rather than applied by dotenv, so assignment follows the rules above.
+    // Parsing also emits nothing on stdout, which the CLI reserves for its answer.
+    let parsed;
+    try {
+        parsed = dotenv.parse(readFileSync(envFile));
+    }
+    catch {
+        return;
+    }
+    for (const [name, value] of Object.entries(parsed)) {
+        if (process.env[name] !== undefined && !fromEnvFile.has(name))
+            continue;
+        process.env[name] = value;
+        fromEnvFile.add(name);
+    }
+    lastEnvFileLoaded = envFile;
+}
+// Eagerly load `.env` from the consumer's working directory for the common case.
+// A workspace-root load later in startup overrides whatever this set.
+loadDotenv();
+/** Resolve a config key from its canonical `ARCHMAX_*` environment name. */
+function envValue(suffix) {
+    const name = `ARCHMAX_${suffix}`;
+    return { name, raw: process.env[name] };
+}
+function required(suffix) {
+    const { name, raw } = envValue(suffix);
+    if (!raw || raw.trim() === "") {
+        throw new Error(`Missing required environment variable: ${name}. Copy .env.example to .env and fill it in.`);
+    }
+    return raw.trim();
+}
+function optionalNumber(suffix) {
+    const { name, raw } = envValue(suffix);
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const parsed = Number(raw);
+    if (Number.isNaN(parsed)) {
+        throw new Error(`Environment variable ${name} must be a number, got: ${raw}`);
+    }
+    return parsed;
+}
+function optionalBoolean(suffix) {
+    const { name, raw } = envValue(suffix);
+    if (raw === undefined || raw.trim() === "")
+        return undefined;
+    const normalized = raw.trim().toLowerCase();
+    if (["1", "true", "yes", "on"].includes(normalized))
+        return true;
+    if (["0", "false", "no", "off"].includes(normalized))
+        return false;
+    throw new Error(`Environment variable ${name} must be a boolean, got: ${raw}`);
+}
+/** Read the OpenAI-compatible model configuration from the `ARCHMAX_*` environment keys. */
+export function loadEnv() {
+    return {
+        apiBaseUrl: required("API_BASE_URL"),
+        apiKey: required("API_KEY"),
+        model: required("MODEL"),
+        temperature: optionalNumber("TEMPERATURE"),
+        maxTokens: optionalNumber("MAX_TOKENS"),
+        streaming: optionalBoolean("STREAMING"),
+    };
+}
+/**
+ * Pin an unnamed response role to `assistant` on both of the provider's
+ * message-conversion seams.
+ *
+ * An OpenAI-compatible endpoint is not required to name the role in what it
+ * sends back, and many do not: proxies (LiteLLM and friends) drop or null it,
+ * and providers legitimately send it only on the first streaming delta.
+ * `@langchain/openai` maps a response with no role to a *generic* `ChatMessage`
+ * / `ChatMessageChunk` instead of an `AIMessage` — and a generic **first**
+ * chunk poisons the whole reply, because every later `AIMessageChunk` merges
+ * into the receiver's class. The agent loop then gets a message that is not the
+ * assistant's turn: tool calls are invisible to it, and the framework refuses
+ * the model result outright (see `asModelCallResult` in `core/framework.ts`,
+ * which repairs what still reaches it — e.g. from a model a library user
+ * supplies rather than this factory).
+ *
+ * What comes back from a chat completion *is* the assistant's turn, so a
+ * response that names no role is read as one.
+ */
+function withAssistantRoleDefault(completions) {
+    // Both converters are `protected` on the provider class, so they are replaced
+    // through an index signature rather than a subclass override — that keeps this
+    // module free of the provider SDK's request/response types. Each is patched
+    // only if present: a provider release that drops the seam (both are marked
+    // deprecated upstream) leaves the model untouched rather than failing here,
+    // and the framework-level repair still covers it.
+    const seam = completions;
+    const deltaConverter = seam._convertCompletionsDeltaToBaseMessageChunk;
+    if (typeof deltaConverter === "function") {
+        const original = deltaConverter;
+        seam._convertCompletionsDeltaToBaseMessageChunk = (delta, rawResponse, defaultRole) => {
+            // `role` on a delta is sticky: the provider sends it once and the caller
+            // carries it forward as `defaultRole`. A role the provider did name as one
+            // of the protocol's own keeps deciding the class, so this changes nothing
+            // for a conforming endpoint.
+            const role = responseRole(stringRole(delta)) ?? defaultRole ?? "assistant";
+            return original.call(completions, { ...delta, role }, rawResponse, role);
+        };
+    }
+    const messageConverter = seam._convertCompletionsMessageToBaseMessage;
+    if (typeof messageConverter === "function") {
+        const original = messageConverter;
+        seam._convertCompletionsMessageToBaseMessage = (message, rawResponse) => {
+            const role = responseRole(stringRole(message)) ?? "assistant";
+            return original.call(completions, { ...message, role }, rawResponse);
+        };
+    }
+    return completions;
+}
+/** The `role` a provider named on a delta/message, if it named a non-empty one. */
+function stringRole(payload) {
+    const role = payload?.role;
+    return typeof role === "string" && role !== "" ? role : undefined;
+}
+/**
+ * The roles the chat-completions protocol defines for a turn that is *not* the
+ * assistant's. A response naming one of these is left as it is — the endpoint
+ * meant it, and the provider integration maps it faithfully.
+ */
+const NON_ASSISTANT_ROLES = new Set(["user", "system", "developer", "tool", "function"]);
+/**
+ * Which role a *response* should be read as. Anything the protocol does not
+ * define for another turn is the assistant's — including a role borrowed from a
+ * different API's vocabulary (`model`), which is what a proxy fronting a
+ * non-OpenAI provider tends to pass through.
+ */
+function responseRole(named) {
+    if (named === undefined)
+        return undefined;
+    return NON_ASSISTANT_ROLES.has(named) ? named : "assistant";
+}
+/** Build a `ChatOpenAI` model pointed at any OpenAI-compatible endpoint. */
+export function createChatModel(env = loadEnv()) {
+    const fields = {
+        model: env.model,
+        apiKey: env.apiKey,
+        temperature: env.temperature,
+        maxTokens: env.maxTokens,
+        // Streaming feeds `agent-text-delta` events; `invoke` results are the
+        // same either way. `ARCHMAX_STREAMING=0` opts out.
+        streaming: env.streaming ?? true,
+        // Ask for usage in the stream: without it a streaming run (the default)
+        // reports no tokens at all, and token/cost accounting would silently be zero.
+        streamUsage: true,
+        configuration: { baseURL: env.apiBaseUrl },
+    };
+    // The chat-completions sub-model is constructed here rather than left to
+    // `ChatOpenAI` so the role normalization is part of the fields the wrapper
+    // rebuilds itself from: `withConfig()` (which the agent loop uses) makes a new
+    // wrapper out of exactly this object, and a sub-model patched afterwards would
+    // be dropped by it.
+    return new ChatOpenAI({
+        ...fields,
+        completions: withAssistantRoleDefault(new ChatOpenAICompletions(fields)),
+    });
+}
+/**
+ * Prompt-cache configuration from the environment: `ARCHMAX_PROMPT_CACHE`
+ * (default on) and `ARCHMAX_PROMPT_CACHE_TTL` (`5m` | `1h`).
+ */
+export function loadPromptCacheEnv() {
+    const enabled = optionalBoolean("PROMPT_CACHE");
+    const { raw: ttl } = envValue("PROMPT_CACHE_TTL");
+    return {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(ttl?.trim() ? { ttl: ttl.trim() } : {}),
+    };
+}
+/**
+ * Token prices from the environment, in USD per 1M tokens, applying to whatever
+ * model is configured: `ARCHMAX_PRICE_INPUT`, `ARCHMAX_PRICE_OUTPUT`,
+ * `ARCHMAX_PRICE_CACHE_READ`, `ARCHMAX_PRICE_CACHE_WRITE`. Returns `undefined`
+ * when none are set, so cost is omitted rather than reported as zero.
+ */
+export function loadPricingEnv() {
+    const entry = {};
+    const input = optionalNumber("PRICE_INPUT");
+    const output = optionalNumber("PRICE_OUTPUT");
+    const cacheRead = optionalNumber("PRICE_CACHE_READ");
+    const cacheWrite = optionalNumber("PRICE_CACHE_WRITE");
+    if (input !== undefined)
+        entry.input = input;
+    if (output !== undefined)
+        entry.output = output;
+    if (cacheRead !== undefined)
+        entry.cacheRead = cacheRead;
+    if (cacheWrite !== undefined)
+        entry.cacheWrite = cacheWrite;
+    if (Object.keys(entry).length === 0)
+        return undefined;
+    return { [DEFAULT_PRICING_KEY]: entry };
+}
+/** The default, role-independent model factory: the env-configured `ChatOpenAI`. */
+export const defaultModelFactory = (_role, env, requested) => createChatModel(requested === undefined ? env() : { ...env(), model: requested });
+//# sourceMappingURL=env.js.map

package/dist/env.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,265 @@
+/**
+ * `@archmax-ai/harness` — a generic, backend-driven agent runtime built on LangChain Deep
+ * Agents. Assemble a governed agent with {@link createAgent}, point it at a
+ * workspace of authored workflows, and drive it like any Deep Agent.
+ *
+ * The runtime reads its entire agent definition (machine spec, system prompt,
+ * skills, scripts) and session state through a single Deep Agents
+ * backend, so the same code runs over a local filesystem, a store, a sandbox, or
+ * a remote backend without modification.
+ *
+ * **What is public.** This barrel is the supported surface, and every export
+ * carries a docstring saying what it is for. It is deliberately small: an export
+ * is here because a real consumer needs it, not because a module happened to
+ * expose it. Adjacent surfaces live on their own subpaths — `@archmax-ai/harness/testing`
+ * (the case engine), `@archmax-ai/harness/cli` (the state-flow renderer), and
+ * `@archmax-ai/harness/sandbox` (hook and script authoring) — so a production import never
+ * pulls in test machinery.
+ *
+ * Two **light** subpaths mirror part of this surface without the runtime behind
+ * it: `@archmax-ai/harness/spec` (the schema, the pure validator and the grammars —
+ * browser-safe) and `@archmax-ai/harness/messages` (transcript readers). A name on
+ * both is the same binding.
+ *
+ * Anything not exported here is internal and may change without a major version.
+ */
+/**
+ * Assemble an agent: Deep Agents' own parameters plus `workflow`. Omit `workflow`
+ * for a plain Deep Agent; supply it and the same agent is governed by that
+ * machine. Returns a wrapper over the compiled graph — `invoke` / `stream` /
+ * `graph` — with governance under `.workflow`.
+ */
+export { createAgent } from "./assembly/index.js";
+/** The wrapper class {@link createAgent} returns. */
+export { ArchmaxAgent } from "./agent.js";
+export type { 
+/** Parameters for {@link createAgent}. */
+CreateAgentParams, 
+/** Where files come from and where sessions go (the `workspace` group). */
+AgentWorkspaceParams, } from "./assembly/index.js";
+export type { 
+/** What {@link createAgent} returns. */
+Agent, 
+/** @deprecated Narrow on `agent.workflow` instead. An {@link Agent} known to be governed. */
+GovernedAgent, 
+/** @deprecated The members live on {@link Agent} directly. */
+AgentRunSurface, 
+/** The governance surface at `agent.workflow`, `undefined` when ungoverned. */
+WorkflowSurface, 
+/** A turn's input to `agent.workflow.send`. */
+TurnInput, 
+/** What `agent.workflow.send` takes: a turn or a resume. */
+SendInput, } from "./agent.js";
+/** Session handles over the configured session store (`agent.sessions`). */
+export type { SessionOperations } from "./sessions/operations.js";
+export type { 
+/** How a session is started: a trigger id. */
+TriggerInput, 
+/** A resolved trigger: its id plus the start state it enters. */
+ResolvedTrigger, } from "./machine/triggers.js";
+export type { 
+/** What one `send` produced, whichever way it entered the session. */
+Outcome, 
+/** One of the three resumes: a decision, a reply, or a delivery. */
+ResumePayload, 
+/** The person's answer, as `agent.workflow.decide()` takes it. */
+DecisionResolution, 
+/** A firing delivered into a parked session, as `agent.workflow.deliver()` takes it. */
+TriggerDelivery, 
+/** The outcome of deciding a parked human state. */
+DecideOutcome, 
+/** The outcome of replying to a session parked at a human state. */
+ReplyOutcome, 
+/** @deprecated Older spelling of {@link ReplyOutcome}; kept for one release. */
+RespondOutcome, 
+/** The outcome of delivering into a session parked with `archmax_wait`. */
+DeliverOutcome, 
+/** The child a parked session's pending decision belongs to (`Outcome.delegation`). */
+DelegatedPark, } from "./sessions/resume.js";
+/**
+ * Read a session that must be parked in `status` — the checkpointed status **and**
+ * a live suspension — or `null`. What every resume asks before touching the graph.
+ */
+export { readParkedSession } from "./sessions/resume.js";
+export { 
+/** The park record a session's checkpointed values hold, on either channel, or `null`. */
+pendingParkOf, 
+/** The state a park record names, across the current and the deprecated spelling. */
+parkedStateOf, } from "./workflow/state.js";
+export type { 
+/** What `agent.workflow.resolveSession()` takes: one firing. */
+ResolveSessionInput, 
+/** Where a firing lands: the session and its disposition. */
+ResolvedSession, } from "./sessions/resolve.js";
+export type { 
+/** The checkpointed record a session parked at a human state presents. */
+PendingDecision, 
+/** The checkpointed record a session parked with `archmax_wait` presents. */
+PendingInput, } from "./workflow/state.js";
+/**
+ * The checkpoint-facing half of a compiled graph, for a host that drives
+ * LangGraph directly (`getState`, `updateState`) against `agent.graph`.
+ */
+export type { IntrospectableStateGraph } from "./core/deepagents.js";
+/** One session's projection: status, position, variables, usage, parent. */
+export type { SessionSummary } from "./sessions/summary.js";
+export { 
+/** A named workflow has no loadable machine spec — assembly fails closed. */
+WorkflowLoadError, 
+/** A turn would start a session on a workflow that declares `disabled: true`. */
+WorkflowDisabledError, } from "./machine/load-spec.js";
+/** A trigger id the machine does not declare. */
+export { UnknownTriggerError } from "./machine/triggers.js";
+/** A host tool wearing a reserved `archmax_` name. */
+export { ReservedToolNameError } from "./machine/tool-names.js";
+/** A seeded variable name that is not a legal identifier. */
+export { InvalidVariableNameError } from "./machine/variables.js";
+/** A mount key shadows a session area. */
+export { MountCollisionError } from "./core/mounts.js";
+export { 
+/** A custom `backend` was supplied without a `sessionStore`. */
+SessionStoreRequiredError, 
+/** A session id that would escape its zone or shadow a reserved name. */
+SessionStoreIdError, 
+/** A session operation the configured store cannot perform (delete, list). */
+SessionStoreCapabilityError, } from "./core/session-store.js";
+export { 
+/** The authoring backend was also served by a writable mount. */
+AuthoringBackendExposedError, 
+/** @deprecated Older spelling of {@link AuthoringBackendExposedError}; kept for one release. */
+AuthoringPlaneExposedError, 
+/** A partly composed workspace needed a filesystem default and no `rootDir` was given. */
+WorkspaceRootRequiredError, } from "./core/workspace-context.js";
+/** A workspace declared a `runtime.version` this build does not implement. */
+export { UnsupportedRuntimeContractError } from "./runtime/contract.js";
+export { 
+/** A decision or reply for a session not parked at a human state. */
+SessionNotParkedError, 
+/** A decision naming a target the parked state does not declare. */
+InvalidDecisionTargetError, 
+/** A reply with nothing to answer. */
+EmptyMessageError, 
+/** A delivery to a session not parked with `archmax_wait`. */
+SessionNotAwaitingInputError, 
+/** A delivery naming no trigger id. */
+MissingDeliveryTriggerError, } from "./sessions/resume.js";
+/** A firing for a session whose turn is still in progress. */
+export { SessionNotResumableError } from "./sessions/resolve.js";
+/** The conventional mount table for a filesystem workspace. */
+export { defaultMounts } from "./core/mounts.js";
+/** Rebase one backend so it can serve several mounts. */
+export { mountSubtree } from "./core/path-mapping.js";
+/** One mount: a backend, or `{ backend, readOnly }`. */
+export type { MountSpec } from "./core/mounts.js";
+export { 
+/** Filesystem session store (the zero-config default). */
+createFilesystemSessionStore, 
+/** Session store over any Deep Agents backend (e.g. S3). */
+createBackendSessionStore, 
+/** Ephemeral session store, for tests and one-shot sessions. */
+createMemorySessionStore, } from "./core/session-store.js";
+/** Physical storage for sessions. */
+export type { SessionStore } from "./core/session-store.js";
+/** Whether a name is reserved at the workspace root (a session area or a mount). */
+export { isReservedRootName } from "./core/zones.js";
+/** Why a session id cannot own a session folder, or `null` when it can — the rule every ingress applies. */
+export { sessionIdRejection } from "./core/session-id.js";
+/** Whether one session was dispatched by another (`<parent>~<state>:<workflow>:<n>`), at any depth. */
+export { isChildSessionOf } from "./sessions/scope.js";
+/** Which zone a workspace path belongs to — the kernel's own classifier (a host maps evidence paths with it). */
+export { classifyWorkspacePath } from "./core/zones.js";
+export type { WorkspaceZone } from "./core/zones.js";
+/** The resolved mount keys a workspace classifies paths against. */
+export type { MountPrefixes } from "./core/zones.js";
+/**
+ * Build the workspace composite the assembly uses. Public because a consumer
+ * serving authored content from its own backend needs the same composition.
+ */
+export { createWorkspaceContext } from "./core/workspace-context.js";
+/** What {@link createWorkspaceContext} returns: the composed backends and mounts. */
+export type { WorkspaceContext } from "./core/workspace-context.js";
+/** Where a workspace may override the bundled platform prompt (`.platform/system/GRAPH_STATE.md`). */
+export { PLATFORM_BACKEND_PROMPT_PATH } from "./workflow/paths.js";
+/** Compose the system prompt from persona, platform, zones and workflow layers. */
+export { resolveSystemPrompt } from "./core/prompt.js";
+/** Bind a `name → tool` map in the shape the `tools` option takes. */
+export { toolsFromMap } from "./workflow/agent-tools.js";
+/** A message's text, whatever content-block shape it arrived in. */
+export { contentToString } from "./core/messages.js";
+/** Whether a message is the assistant's turn. */
+export { isAiMessage } from "./core/messages.js";
+/** The last thing the agent said to the person; tool results and runtime notes are skipped. */
+export { lastAgentText } from "./core/messages.js";
+/**
+ * Whether the runtime wrote a transcript message rather than a person — a
+ * decision, an arrival, an error route, a completion check, a child's result.
+ * A host slicing a turn out of a session's messages, or rendering a transcript,
+ * asks this instead of inferring authorship from role.
+ */
+export { isRuntimeNote } from "./core/messages.js";
+/** Which kind of runtime note a message is, or `null` if a person wrote it. */
+export { runtimeNoteKind } from "./core/messages.js";
+export type { RuntimeNoteKind } from "./core/messages.js";
+/** One grading rubric, as declared inline on the hook that applies it. */
+export type { RubricDeclaration } from "./machine/types.js";
+/** Host data the runtime never reads, at the spec root, on a state, or on a rubric. */
+export type { SpecMetadata } from "./machine/types.js";
+/** Parse a sandbox script's leading description block. */
+export { parseCodeDescription } from "./core/code-description.js";
+/** Load and shape-check a `workflow.yaml` without assembling an agent. */
+export { loadMachineSpec } from "./machine/load-spec.js";
+/** A `before:`/`after:` declaration as a flat list of hooks. */
+export { normalizeHooks } from "./lifecycle/hook-shape.js";
+export type { MachineSpec, MachineState } from "./machine/types.js";
+/** The compiled machine, as `agent.workflow.machine` exposes it. */
+export { WorkflowMachine } from "./machine/machine.js";
+/** Statically validate a workflow scaffold — no model calls. */
+export { validateWorkflow } from "./validate/validate.js";
+export type { ValidationResult, Diagnostic } from "./validate/validate.js";
+/** A custom governance rule, inserted after the safety and policy rules. */
+export type { GovernanceRule } from "./kernel/kernel.js";
+/**
+ * The dispatcher's default delegation bounds. Public because a host configuring
+ * `bounds` needs to know what it is overriding.
+ */
+export { DEFAULT_SUB_WORKFLOW_DEPTH, DEFAULT_SUB_WORKFLOW_CONCURRENCY, } from "./machine/delegation.js";
+export { 
+/** The entry trigger id (`manual`). */
+MANUAL_TRIGGER, 
+/** The trigger applied when none is supplied (same value as `MANUAL_TRIGGER`). */
+DEFAULT_TRIGGER_ID, 
+/** The session id a firing of a trigger resolves to under a spec, or `undefined` when the runtime mints one. */
+sessionIdForTrigger, } from "./machine/triggers.js";
+/** Default workflow slug when none is named. */
+export { DEFAULT_WORKFLOW } from "./workflow/paths.js";
+export { 
+/** Prefix of every delegation tool name. */
+WORKFLOW_TOOL_PREFIX, 
+/** The delegation tool name for a workflow slug. */
+workflowToolName, 
+/** The workflow slug a delegation tool name refers to. */
+workflowSlugFromToolName, } from "./machine/tool-names.js";
+export type { 
+/** Every runtime diagnostic, as one typed union. */
+WorkflowLifecycleEvent, 
+/** The `onEvent` subscriber. */
+WorkflowEventHandler, } from "./core/events.js";
+/** Fold `model-usage` events into per-session totals and cost. */
+export { createUsageTracker } from "./core/usage.js";
+/** Render a usage summary for a footer or a log line. */
+export { formatUsage } from "./core/usage.js";
+export type { UsageSummary, PricingTable } from "./core/usage.js";
+/** Build the env-configured chat model to pass as `model`. */
+export { createChatModel } from "./env.js";
+export { 
+/**
+ * The bundled authoring skill's parent directory (holding `archmax-harness/`), so an
+ * authoring agent's reference always matches the installed SDK.
+ */
+BUNDLED_AUTHORING_SKILL_DIR, 
+/** @deprecated Use `BUNDLED_AUTHORING_SKILL_DIR`; same value. */
+BUNDLED_SKILLS_DIR, } from "./env.js";
+/** This package's version, as session metadata records it. */
+export { PACKAGE_VERSION } from "./env.js";
+/** The resolved `runtime.version` and the surfaces it implies. */
+export type { RuntimeContract, ResolvedRuntimeContract } from "./runtime/contract.js";