@archmax-ai/harness 0.8.0 → 1.0.0

package/dist/workflow/grader-state.d.ts

@@ -0,0 +1,55 @@
+/**
+ * A grader state's run: an isolated grader subagent — its own model, its own
+ * prompt, its own messages — that judges the session and decides where it goes.
+ *
+ * Isolated in three ways. It reads the session only through its tools
+ * (`archmax_get_history` above all), and nothing it says enters the session's
+ * transcript. Its tokens are tagged `nostream`, so they never stream as the
+ * session's text. And it compiles with no checkpointer, so it writes nothing into
+ * the session's thread. What it decided reaches the session as the step
+ * recorder's decision, which the orchestrator (`automated.ts`) commits.
+ *
+ * Its tools are its state's surface, already governed by the PTC gateway on the
+ * `agent` origin; this module adds what a model's calls get on the agent's own
+ * path — `${{…}}` argument substitution, and a refused or failed call answered
+ * as an error the model can read rather than thrown — and ends the loop the
+ * moment a decision is recorded.
+ */
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import type { StructuredTool } from "@langchain/core/tools";
+import type { WorkflowEventEmitter } from "../core/events.js";
+import { type PricingTable, type UsageSummary } from "../core/usage.js";
+import type { WorkflowMachine } from "../machine/machine.js";
+import type { StepRecorder } from "./automated-controls.js";
+/**
+ * What every grader is told before its state's criteria: what it is, how it reads
+ * the session, and the two calls it decides with. Compiled in, like the platform
+ * prompt: a grader's contract is the runtime's, its criteria are the author's.
+ */
+export declare const GRADER_PREAMBLE = "# Grader\n\nYou are the grader of one state of a workflow session. You do not talk to anyone:\nyou judge the session's work against the criteria below and decide where the\nsession goes next.\n\n1. Read the session with `archmax_get_history`: every message so far, and the trail of\n   states it moved through and why. Read files or variables when the criteria need them.\n2. Decide by calling `archmax_advance({ \"to\": \"<slug>\", \"reason\": \"<what you found>\" })` with\n   one of the transitions listed in your task. The reason is what the next state reads:\n   when you send work back, say exactly what has to change.\n3. When the work cannot be accepted and must not be retried \u2014 your criteria say when \u2014\n   call `archmax_raise({ \"code\": \"<short-token>\", \"reason\": \"<why>\" })` instead: it ends the\n   session as failed.\n\nMake exactly one of those two calls, then stop. Text you write is read by no one.\n\n## Criteria";
+/** The task a grader is handed: where it stands, and the transitions it chooses from. */
+export declare function graderTask(machine: WorkflowMachine, state: string): string;
+export interface GraderStateRun {
+    machine: WorkflowMachine;
+    emit: WorkflowEventEmitter;
+    pricing?: PricingTable;
+    state: string;
+    model: BaseChatModel;
+    /** The model's id, for usage events, when the instance exposes one. */
+    modelId?: string;
+    /** The grader state's tools, governed (controls included). */
+    tools: StructuredTool[];
+    recorder: StepRecorder;
+    /** The turn's abort signal: a cancelled turn cancels the grader. */
+    signal?: AbortSignal;
+}
+/**
+ * Run a grader state's subagent. Settles with the error that stopped it, if one
+ * did — an exhausted `budget.maxTurns`, an expired `budget.timeoutMs`, a model
+ * or runtime failure — and with its usage across every model call. A cancelled
+ * turn is not the grader's failure: its abort propagates.
+ */
+export declare function runGraderState(run: GraderStateRun): Promise<{
+    error?: string;
+    usage?: UsageSummary;
+}>;

package/dist/workflow/grader-state.js

@@ -0,0 +1,182 @@
+import { HumanMessage, ToolMessage } from "@langchain/core/messages";
+import { isCommand, isGraphBubbleUp } from "@langchain/langgraph";
+import { createAgent, createMiddleware, tool } from "langchain";
+import { DEFAULT_RECURSION_LIMIT } from "../core/deepagents.js";
+import { contentToString, isAiMessage } from "../core/messages.js";
+import { addSummaries, extractUsage, summarizeUsage } from "../core/usage.js";
+import { ADVANCE_TOOL, GET_HISTORY_TOOL, RAISE_TOOL, isWorkflowToolName } from "../machine/tool-names.js";
+import { resolveArguments } from "../machine/variables.js";
+import { PtcGovernanceError } from "../sandbox/ptc-gateway.js";
+import { unresolvedArgumentMessage } from "./control-tools.js";
+import { renderTransitions } from "./render-prompt.js";
+import { blockedMessage } from "./tool-service.js";
+/**
+ * What every grader is told before its state's criteria: what it is, how it reads
+ * the session, and the two calls it decides with. Compiled in, like the platform
+ * prompt: a grader's contract is the runtime's, its criteria are the author's.
+ */
+export const GRADER_PREAMBLE = `# Grader
+
+You are the grader of one state of a workflow session. You do not talk to anyone:
+you judge the session's work against the criteria below and decide where the
+session goes next.
+
+1. Read the session with \`${GET_HISTORY_TOOL}\`: every message so far, and the trail of
+   states it moved through and why. Read files or variables when the criteria need them.
+2. Decide by calling \`${ADVANCE_TOOL}({ "to": "<slug>", "reason": "<what you found>" })\` with
+   one of the transitions listed in your task. The reason is what the next state reads:
+   when you send work back, say exactly what has to change.
+3. When the work cannot be accepted and must not be retried — your criteria say when —
+   call \`${RAISE_TOOL}({ "code": "<short-token>", "reason": "<why>" })\` instead: it ends the
+   session as failed.
+
+Make exactly one of those two calls, then stop. Text you write is read by no one.
+
+## Criteria`;
+/** The task a grader is handed: where it stands, and the transitions it chooses from. */
+export function graderTask(machine, state) {
+    return [
+        `You are grading the session in the grader state \`${state}\`.`,
+        `Transitions — choose one with \`${ADVANCE_TOOL}\`:`,
+        ...renderTransitions(machine, state),
+    ].join("\n\n");
+}
+/** The tag LangGraph's message stream skips: a grader's tokens are not the session's text. */
+const NO_STREAM_TAG = "langsmith:nostream";
+/** The text a tool's settled value reads as, for the grader's tool answer. */
+function answerText(value) {
+    if (typeof value === "string")
+        return value;
+    if (value instanceof ToolMessage)
+        return contentToString(value.content);
+    if (isCommand(value)) {
+        const messages = value.update?.messages ?? [];
+        const answer = [...messages].reverse().find((m) => m instanceof ToolMessage);
+        if (answer)
+            return contentToString(answer.content);
+    }
+    try {
+        return JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+/**
+ * The grader's own instance of a governed tool: same name, description and
+ * schema, invoked with plain arguments. The grader's tool node hands a tool a
+ * tool call and its own config; the governed tool takes arguments and runs on
+ * the session's turn config, which the gateway supplies.
+ */
+function graderTool(governed) {
+    return tool(async (args) => answerText(await governed.invoke(args)), {
+        name: governed.name,
+        description: governed.description,
+        schema: governed.schema,
+    });
+}
+/**
+ * Run a grader state's subagent. Settles with the error that stopped it, if one
+ * did — an exhausted `budget.maxTurns`, an expired `budget.timeoutMs`, a model
+ * or runtime failure — and with its usage across every model call. A cancelled
+ * turn is not the grader's failure: its abort propagates.
+ */
+export async function runGraderState(run) {
+    const { machine, emit, recorder, state } = run;
+    const declared = machine.spec.states[state];
+    const maxTurns = declared?.budget?.maxTurns;
+    const timeoutMs = declared?.budget?.timeoutMs;
+    let usage;
+    let modelCalls = 0;
+    let exhausted;
+    const middleware = createMiddleware({
+        name: "GraderMiddleware",
+        beforeModel: {
+            canJumpTo: ["end"],
+            hook: () => {
+                // Decided: the run is over, with no further model call.
+                if (recorder.decision)
+                    return { jumpTo: "end" };
+                if (maxTurns != null && modelCalls + 1 > maxTurns) {
+                    exhausted = `grader state '${state}' exhausted its turn budget (maxTurns: ${maxTurns})`;
+                    return { jumpTo: "end" };
+                }
+                modelCalls += 1;
+                return undefined;
+            },
+        },
+        afterModel: (stateView) => {
+            const last = stateView.messages?.at(-1);
+            if (!last || !isAiMessage(last))
+                return undefined;
+            const extracted = extractUsage(last);
+            if (!extracted)
+                return undefined;
+            const model = extracted.model ?? run.modelId;
+            const summary = summarizeUsage(extracted.usage, run.pricing, model);
+            emit({ type: "model-usage", state, ...summary, ...(model ? { model } : {}) });
+            usage = usage ? addSummaries(usage, summary) : summary;
+            return undefined;
+        },
+        wrapToolCall: async (request, handler) => {
+            const name = request.toolCall.name;
+            const callId = request.toolCall.id ?? "";
+            let call = request;
+            // `${{…}}` resolves against the session's variables as this run sees them,
+            // exactly as the agent's own arguments do; a delegation's are its params.
+            if (!isWorkflowToolName(name)) {
+                const substituted = resolveArguments((request.toolCall.args ?? {}), recorder.store());
+                if (!substituted.ok)
+                    return blockedMessage(name, callId, unresolvedArgumentMessage(substituted));
+                call = { ...request, toolCall: { ...request.toolCall, args: substituted.args } };
+            }
+            try {
+                return await handler(call);
+            }
+            catch (err) {
+                if (isGraphBubbleUp(err) || run.signal?.aborted)
+                    throw err;
+                const cause = err?.cause ?? err;
+                const message = String(cause?.message ?? cause);
+                if (cause instanceof PtcGovernanceError)
+                    return blockedMessage(name, callId, message);
+                return new ToolMessage({ content: message, tool_call_id: callId, name, status: "error" });
+            }
+        },
+    });
+    const grader = createAgent({
+        model: run.model,
+        tools: run.tools.map(graderTool),
+        systemPrompt: `${GRADER_PREAMBLE}\n\n${declared?.instructions?.trim() ?? ""}`,
+        middleware: [middleware],
+        checkpointer: false,
+        name: `grader:${state}`,
+    });
+    const signals = [run.signal, timeoutMs != null ? AbortSignal.timeout(timeoutMs) : undefined].filter((signal) => signal !== undefined);
+    const signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
+    try {
+        await grader.invoke({ messages: [new HumanMessage(graderTask(machine, state))] }, {
+            ...(signal ? { signal } : {}),
+            tags: [NO_STREAM_TAG],
+            // A model call is up to four graph steps (before it, the call, after it,
+            // its tools): room for every call the budget allows, which the
+            // middleware enforces first; unbounded, a session's own limit.
+            recursionLimit: maxTurns != null ? 4 * maxTurns + 8 : DEFAULT_RECURSION_LIMIT,
+        });
+    }
+    catch (err) {
+        if (run.signal?.aborted)
+            throw err;
+        if (recorder.decision)
+            return { ...(usage ? { usage } : {}) };
+        const expired = timeoutMs != null && signal?.aborted;
+        return {
+            error: expired
+                ? `grader state '${state}' exceeded its time budget (timeoutMs: ${timeoutMs})`
+                : `grader state '${state}' failed: ${err?.message ?? String(err)}`,
+            ...(usage ? { usage } : {}),
+        };
+    }
+    return { ...(exhausted && !recorder.decision ? { error: exhausted } : {}), ...(usage ? { usage } : {}) };
+}
+//# sourceMappingURL=grader-state.js.map

package/dist/workflow/grader-state.js.map

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

package/dist/workflow/history.d.ts

@@ -0,0 +1,11 @@
+import type { HistoryMessage, SessionHistory } from "../public/sandbox.js";
+export type { HistoryMessage, SessionHistory };
+/**
+ * The transcript as plain messages, oldest first. A runtime note is carried in
+ * the transcript as a tool-call pair; only the half holding the text is kept,
+ * as one `runtime` entry. A tool result carries its text, the tool that
+ * produced it, and the id of the call it answers.
+ */
+export declare function historyMessages(messages: unknown[]): HistoryMessage[];
+/** The history of the session whose checkpointed state this is. */
+export declare function sessionHistory(state: unknown): SessionHistory;

package/dist/workflow/history.js

@@ -0,0 +1,64 @@
+/**
+ * A session's **history**: its whole transcript as plain messages and its whole
+ * trail — what an automated state reads with `archmax_get_history`, a grader
+ * and a code state's script alike, so both counting the same rounds read the
+ * same thing. Built from the checkpointed session, never from the request a
+ * summary shortened for the model.
+ *
+ * Nothing is windowed: a grader asked to give up after N send-backs has to see
+ * all N. What bounds it is the sandbox's result and memory quotas, and the
+ * grader model's context.
+ */
+import { contentToString, messageTypeOf, runtimeNoteKind } from "../core/messages.js";
+import { readAuditTrail } from "./state.js";
+const ROLE_BY_TYPE = {
+    human: "user",
+    ai: "assistant",
+    system: "system",
+    tool: "tool",
+    function: "tool",
+};
+/**
+ * The transcript as plain messages, oldest first. A runtime note is carried in
+ * the transcript as a tool-call pair; only the half holding the text is kept,
+ * as one `runtime` entry. A tool result carries its text, the tool that
+ * produced it, and the id of the call it answers.
+ */
+export function historyMessages(messages) {
+    const out = [];
+    for (const raw of Array.isArray(messages) ? messages : []) {
+        const msg = raw;
+        const type = messageTypeOf(raw);
+        const text = contentToString(msg.content);
+        const note = runtimeNoteKind(raw);
+        if (note !== null) {
+            if (text.trim() === "")
+                continue;
+            out.push({ role: "runtime", text, note });
+            continue;
+        }
+        const role = ROLE_BY_TYPE[type] ?? (type || "unknown");
+        const entry = { role, text };
+        const calls = msg.tool_calls;
+        if ((type === "ai" || type === "assistant") && Array.isArray(calls) && calls.length > 0) {
+            entry.toolCalls = calls.map((c) => {
+                const call = c;
+                return { ...(call.id == null ? {} : { id: String(call.id) }), name: String(call.name ?? ""), args: call.args ?? {} };
+            });
+        }
+        if (role === "tool") {
+            if (typeof msg.name === "string")
+                entry.tool = msg.name;
+            if (msg.tool_call_id != null)
+                entry.id = String(msg.tool_call_id);
+        }
+        out.push(entry);
+    }
+    return out;
+}
+/** The history of the session whose checkpointed state this is. */
+export function sessionHistory(state) {
+    const messages = state?.messages;
+    return { messages: historyMessages(Array.isArray(messages) ? messages : []), trail: readAuditTrail(state) };
+}
+//# sourceMappingURL=history.js.map

package/dist/workflow/history.js.map

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

package/dist/workflow/middleware.d.ts

@@ -1,13 +1,13 @@
 import type { StructuredTool } from "@langchain/core/tools";
 import type { AgentMiddleware } from "langchain";
-import type { ScriptExecutor } from "../sandbox/executor.js";
+import type { BaseChatModel } from "@langchain/core/language_models/chat_models";
+import { type ScriptExecutor } from "../sandbox/executor.js";
 import type { PtcToolGateway } from "../sandbox/ptc-gateway.js";
-import { LifecycleRunner, type HookExecutor, type HookScriptResolver } from "../lifecycle/runner.js";
 import type { WorkflowMachine } from "../machine/machine.js";
-import type { Rubric } from "../rubrics/rubrics.js";
 import type { Workspace } from "../core/workspace.js";
 import { type WorkflowEventHandler } from "../core/events.js";
 import type { VariableStore } from "../machine/variables.js";
+import type { CodeScriptResolver } from "./code-state.js";
 import type { SubWorkflowDispatcher } from "./sub-workflow.js";
 import type { GovernanceRule } from "../kernel/kernel.js";
 import { type MountPrefixes } from "../core/mounts.js";
@@ -29,30 +29,27 @@ export interface WorkflowInstrumentation {
     /** The governance middleware proper; assembled after {@link parkMiddleware}. */
     middleware: AgentMiddleware;
     tools: StructuredTool[];
-    lifecycle: LifecycleRunner;
     /** Release every per-session resource (idempotent; safe for sessions that never ran). */
     dispose(sessionId: string): void;
 }
 export interface WorkflowMiddlewareOptions {
     machine: WorkflowMachine;
-    /** Serves the agent's own `archmax_eval`/`archmax_run` over the agent workspace. */
-    executor: ScriptExecutor;
-    /** The workflow's grading rubrics, dispatched by a `{ rubric: … }` hook. */
-    rubrics?: Map<string, Rubric>;
-    ptcNames: string[];
+    /** Runs a code state's script, reading it from the authoring backend. */
+    codeExecutor: ScriptExecutor;
+    /** Resolves a code state's declared `script:` to its authoring-backend path. */
+    resolveCodeScript: CodeScriptResolver;
+    /** The model a grader state runs on, and its id when the instance exposes one. */
+    graderModel(state: string): {
+        model: BaseChatModel;
+        id?: string;
+    };
     /** Consumer rules, evaluated after the safety and `policy` rules, before per-state defaults. */
     policyRules?: GovernanceRule[];
     /** The workspace's resolved mount keys, so the kernel's read-only rule can classify authored paths. */
     mountPrefixes?: MountPrefixes;
     /** The workspace's skills: one table for what the kernel refuses, the prompt names, a listing returns. */
     skills?: SkillRegistry;
-    /** Custom hook-kind executors registered alongside the built-in `script`/`rubric`. */
-    hookExecutors?: Record<string, HookExecutor>;
-    /** Script executor for lifecycle hooks, reading from the authoring backend. Defaults to {@link executor}. */
-    hookExecutor?: ScriptExecutor;
-    /** Resolves a hook's declared `script:` to its authoring-backend path. */
-    resolveHookScript?: HookScriptResolver;
-    /** Governs the `tools.*` calls hook scripts make and carries the live per-session context. */
+    /** Governs every call made outside the tool node — scripts', automated states' — and carries the live per-session context. */
     ptcGateway?: PtcToolGateway;
     /** Runs delegated machines. Omitted, a delegation call falls through to the tool's own body. */
     subWorkflows?: SubWorkflowDispatcher;
@@ -85,7 +82,7 @@ export interface WorkflowMiddlewareOptions {
 }
 /**
  * In-graph governance for the Deep Agent: the turn boundary, per-state tool
- * disclosure and the kernel's verdict on every call, lifecycle hooks, the
+ * disclosure and the kernel's verdict on every call, the automated states, the
  * control tools, budgets, `on_error` routing, and every park's commit, closing
  * turn and suspension.
  */