@agentproto/workflow-runtime 0.9.0 → 0.11.0

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { DriverHandle, ResolverContext } from '@agentproto/driver';
 import { ToolContext, ToolHandle } from '@agentproto/tool';
 import { ZodType } from 'zod';
 import { WorkflowHandle } from '@agentproto/workflow';
+import { FsPort, FsStat, FsLockHandle } from '@agentproto/corpus';
 
 /**
  * Typed step algebra for AIP-15 WORKFLOW execution.
@@ -155,6 +156,11 @@ interface ApprovalStep {
     id: string;
     prompt: Selector<string>;
     approvers?: readonly string[];
+    /** Artifacts attached to the approval request (e.g. paths to review). */
+    artifacts?: readonly string[];
+    /** Give up waiting after this long — the step resolves as REJECTED with
+     *  `who: "timeout"` (the host decides; the runtime enforces it). */
+    timeoutMs?: number;
     onApprove?: readonly RunStep[];
     onReject?: readonly RunStep[];
 }
@@ -184,6 +190,73 @@ interface SubworkflowStep {
     /** Input for the child (default: the parent's workflow input). */
     input?: Selector<unknown>;
 }
+/**
+ * Harness pinning for an {@link AgentStep}'s spawn (AIP-15 P2) — mirrors
+ * `@agentproto/workflow`'s manifest `Harness` block, compiled onto the
+ * runtime step. Precedence when a field is also set elsewhere: this block
+ * (highest) > the resolved AGENT.md's own frontmatter > `app_run` caller
+ * args > the adapter's own default (lowest).
+ */
+interface AgentHarness {
+    /** Model id override for this spawn. */
+    model?: string;
+    /** Reasoning-effort override for this spawn (adapter-defined vocabulary). */
+    effort?: string;
+    /** Spawn-time role — governs the child's tool-policy disposition. */
+    role?: string;
+    /** Per-spawn tool allowlist. Applied where the resolved adapter supports a
+     *  generic per-spawn allowlist mechanism; where it doesn't, the host MUST
+     *  record `toolsApplied: false` on the step's output and emit a warning
+     *  rather than silently ignoring the field. */
+    tools?: readonly string[];
+    /** Skill ids auto-mounted into the spawn. */
+    skills?: readonly string[];
+    /** Working directory override for this step's spawn — takes precedence
+     *  over {@link AgentStep.cwd} and the run-level `ctx.cwd`. */
+    cwd?: string;
+    /** sha256 (hex) of the `harness.promptFile` this step's prompt was read
+     *  from, computed by `@agentproto/workflow-loader` at load time. Absent
+     *  when the step's prompt was authored inline. */
+    promptSha?: string;
+    /** AIP-10 corpus knowledge materialized into the step's cwd (under
+     *  `.knowledge/`) before the session runs. See
+     *  {@link HarnessKnowledgeSelector}. */
+    knowledge?: readonly HarnessKnowledgeSelector[];
+}
+/**
+ * One AIP-10 corpus workspace attachment on an {@link AgentStep}'s
+ * `harness.knowledge[]` — mirrors `@agentproto/workflow`'s manifest
+ * `KnowledgeSelector`, with the `workspace` path already resolved to an
+ * absolute path by `@agentproto/workflow-loader` (or authored absolute).
+ */
+interface HarnessKnowledgeSelector {
+    /** Absolute path to an AIP-10 corpus workspace root. */
+    workspace: string;
+    /** Tags with OR semantics (maps to `resolveKnowledge`'s `query.tags`). */
+    anyOf?: readonly string[];
+    /** Tags that must ALL be present (post-filter after `anyOf`). */
+    allOf?: readonly string[];
+    /** Refined-kind filter. */
+    kinds?: readonly string[];
+    /** Cap on materialized entries after slug-ascending sort. Default 50. */
+    maxEntries?: number;
+    /** Materialization mode — v1 supports only `"files"`. */
+    mode?: "files";
+    /** Internal — set by `@agentproto/workflow-loader` when a selector string
+     *  carries `$…` run-time references that must be resolved against the run
+     *  bindings before materialization. Not user-authored; the loader rejects
+     *  an authored `deferred`, and resolution strips the flag. */
+    deferred?: boolean;
+}
+/** Per-selector materialization record on an agent step's run output. */
+interface KnowledgeAppliedRecord {
+    /** The (absolute) corpus workspace root the selector resolved against. */
+    workspace: string;
+    /** Entries matching the selector after allOf + kind filtering. */
+    matched: number;
+    /** Entries actually written (≤ matched, after the `maxEntries` cap). */
+    written: number;
+}
 /**
  * Where an {@link AgentStep}'s session runs when not on the host: a sandbox
  * provider slug (e.g. `"local"`, `"e2b"`) or an inline AIP-36 SandboxSpec-like
@@ -207,6 +280,13 @@ interface AgentStep {
     adapter?: Selector<string> | string;
     /** Reuse an earlier AgentStep's spawned session, by that step's id. */
     sessionRef?: string;
+    /** Model id override for this spawn — same semantics as `agent_start.model`
+     *  (a literal string or a per-run selector resolving to one; `undefined` ⇒
+     *  unchanged behaviour, the adapter keeps its default). Forwarded to the
+     *  spawn through the harness slot; an explicit `harness.model` pinning
+     *  (AIP-15 P2) still wins. Only meaningful with `adapter`; ignored on a
+     *  `sessionRef` reuse. */
+    model?: Selector<string> | string;
     /** Working directory for this spawn. Omit to fall back to the run-level `ctx.cwd`. */
     cwd?: Selector<string>;
     /** Run this step's session inside a sandbox instead of on the host — a
@@ -233,7 +313,7 @@ interface AgentStep {
     /** Re-prompt-and-retry attempts on schema mismatch before failing. Default 2. */
     maxRetries?: number;
     /** Cache this step's output under the run's cacheKey; the resolved prompt +
-     *  adapter + sessionRef are hashed. Default false — most agent steps have
+     *  adapter + model + sessionRef are hashed. Default false — most agent steps have
      *  side effects. */
     cacheable?: boolean;
     /** Manifest-declared adapter option id → value, forwarded to a NEW spawn's
@@ -242,6 +322,81 @@ interface AgentStep {
      *  declarative `agent.ref` names an app-scoped agent. Only meaningful with
      *  `adapter`; ignored on a `sessionRef` reuse. */
     options?: Record<string, boolean | number | string>;
+    /** Harness pinning for this step's spawn. See {@link AgentHarness}. */
+    harness?: AgentHarness;
+}
+/**
+ * `kind: "gate"` — run a shell command through the host's subprocess runner
+ * as a deterministic pass/fail check (AIP-15 P3 / AIP-17). Exit code 0 is a
+ * pass; any other code is a failure. Bound output is `{ ok, exitCode, report
+ * }`; `report` is the process' stdout (if it parses as JSON) or the file at
+ * `reportPath` (relative to `cwd`), parsed as JSON.
+ */
+interface GateStep {
+    kind: "gate";
+    id: string;
+    command: string;
+    /** Command arguments. Each element (selector or string) resolves per-run
+     *  against the bindings: a LEADING `$input|$item|$steps.<id>|$index` token
+     *  (AIP-16 prefix grammar) resolves and any trailing text is appended
+     *  verbatim (`"$input.bookDir/knowledge"` → `"<resolved>/knowledge"`); a
+     *  string that is exactly a ref resolves to that value's string form;
+     *  `$$…` stays a literal `$`; a ref that resolves to nothing (or a `$…`
+     *  string that opens no known ref token) throws naming the step and the
+     *  arg index. */
+    args?: readonly (Selector<string> | string)[];
+    /** Working directory. Selector form resolves per-run. A string may carry
+     *  the same leading-`$…` ref rule as `args` (leading token + trailing
+     *  text, `$$` escape, unresolvable ref throws). The RESOLVED cwd is made
+     *  absolute: absolute stays absolute; relative (incl. `.`) resolves
+     *  against the run's own `ctx.cwd` — never the daemon process cwd.
+     *  Omit for the run's `ctx.cwd`. */
+    cwd?: Selector<string> | string;
+    /** Path (relative to `cwd`), of a JSON report file, consulted when stdout
+     *  doesn't itself parse as JSON. */
+    reportPath?: string;
+    /** Hard wall-clock cap for a single command invocation, in ms. */
+    timeoutMs?: number;
+    /** Re-run on a failing exit code, up to `maxAttempts` (default 1 = no
+     *  retry — a single attempt, fail immediately on a non-zero exit). */
+    retry?: {
+        maxAttempts: number;
+        backoff: "fixed" | "exponential";
+        initialMs?: number;
+    };
+    /** Re-prompt-and-rerun on a failing attempt, BEFORE each retry after the
+     *  first: send the named prior {@link AgentStep}'s session (resolved via
+     *  {@link AgentSessionHost.resolveByLabel}, the same lookup a `sessionRef`
+     *  reuse uses) a prompt with this gate's last report injected, wait for
+     *  its turn, then re-run the gate command. */
+    onFail?: {
+        reprompt: string;
+        with?: Record<string, unknown>;
+    };
+}
+/** One gate command invocation's raw result — before report resolution. */
+interface GateCommandResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut?: boolean;
+}
+/** Host-injectable subprocess runner for {@link GateStep}. Undefined ⇒ the
+ *  runtime's own `node:child_process`-backed default. */
+type GateCommandRunner = (spec: {
+    command: string;
+    args: readonly string[];
+    cwd: string;
+    timeoutMs?: number;
+}) => Promise<GateCommandResult>;
+/** One `kind: "gate"` command attempt's outcome, reported as it happens
+ *  (every attempt, not just the last) — the `gate-report` lifecycle event. */
+interface GateReportEvent {
+    stepId: string;
+    ok: boolean;
+    exitCode: number;
+    report: unknown;
+    attempt: number;
 }
 /** What a declarative agent-step's `agent.ref` resolves to — the adapter to
  *  spawn under plus any adapter options that pick which concrete agent runs
@@ -262,7 +417,7 @@ interface AgentRefResolution {
  * issue #21534); tightening the union to `ToolStep<unknown, …>` rejects a
  * concrete `ToolStep<MarketSearchInput, …>` on the zod `ZodType<T>` variance.
  */
-type RunStep = ToolStep<any, any, any> | TransformStep | MapStep | PipelineStep | BranchStep | LoopStep | ParallelStep | ApprovalStep | SuspendStep | GroupStep | SubworkflowStep | AgentStep;
+type RunStep = ToolStep<any, any, any> | TransformStep | MapStep | PipelineStep | BranchStep | LoopStep | ParallelStep | ApprovalStep | SuspendStep | GroupStep | SubworkflowStep | AgentStep | GateStep;
 interface RuntimeWorkflow {
     id: string;
     description?: string;
@@ -270,10 +425,21 @@ interface RuntimeWorkflow {
     /** Pick the run's final output (default: the last top-level step's output). */
     output?: Selector<unknown>;
 }
+/** A human/host decision on one approval request. `who` records WHO decided
+ *  ("human", "timeout", "cancelled", …); `note` is optional free text. */
+interface ApprovalDecision {
+    approved: boolean;
+    who: string;
+    note?: string;
+}
 interface ApprovalRequest {
     stepId: string;
     prompt: string;
     approvers: readonly string[];
+    artifacts?: readonly string[];
+    /** The step's `timeoutMs` when set — the host may enforce it itself; the
+     *  runtime's default when the host doesn't is to wait forever. */
+    timeoutMs?: number;
 }
 interface ResumeRequest {
     stepId: string;
@@ -291,6 +457,8 @@ interface AgentSessionHost {
         sandbox?: AgentSandboxRef;
         /** Adapter option id → value for this spawn (see {@link AgentStep.options}). */
         options?: Record<string, boolean | number | string>;
+        /** Harness pinning for this spawn (see {@link AgentStep.harness}). */
+        harness?: AgentHarness;
     }): Promise<string>;
     /** Send a prompt to an existing session and wait for its turn to end. */
     sendPromptAndWait(sessionId: string, prompt: string): Promise<void>;
@@ -302,6 +470,16 @@ interface AgentSessionHost {
     readFinalMessage?(sessionId: string): Promise<string>;
     /** Current cumulative cost (USD) of a session, for run-level budgeting. */
     readCostUsd?(sessionId: string): Promise<number>;
+    /** Emit a harness-warning for a session — the pass-through channel behind
+     *  the AIP-15 "never silently ignore" `session:harness-warning` event (used
+     *  by the runtime for `harness.knowledge` empty matches, reason
+     *  `knowledge-empty`). Optional: hosts without an event bus omit it and
+     *  the runtime degrades to the run-record entry alone. */
+    emitHarnessWarning?(input: {
+        sessionId: string;
+        warnings: readonly string[];
+        label?: string;
+    }): void;
 }
 /** One journal entry: a cached step output plus the hash of the inputs that produced it. */
 interface StepCacheEntry {
@@ -319,8 +497,10 @@ interface RunWorkflowArgs {
     workflow: RuntimeWorkflow;
     input?: unknown;
     signal?: AbortSignal;
-    /** Decide an {@link ApprovalStep}. Default: auto-approve. */
-    approve?: (req: ApprovalRequest) => boolean | Promise<boolean>;
+    /** Decide an {@link ApprovalStep}. Default: auto-approve. May return a bare
+     *  boolean (equivalent to `{approved, who: "host"}`) or a full
+     *  {@link ApprovalDecision} recording who decided. */
+    approve?: (req: ApprovalRequest) => boolean | ApprovalDecision | Promise<boolean | ApprovalDecision>;
     /** Supply a {@link SuspendStep}'s resume payload. Default: throw + suspend. */
     resume?: (req: ResumeRequest) => unknown | Promise<unknown>;
     /** Host-injected agent session runtime. Undefined ⇒ {@link AgentStep} throws. */
@@ -341,6 +521,12 @@ interface RunWorkflowArgs {
     onStepStart?: (stepId: string) => void;
     /** Called when a step completes execution, with its output. */
     onStepComplete?: (stepId: string, output: unknown) => void;
+    /** Host-injectable subprocess runner for `kind: "gate"` steps. Undefined ⇒
+     *  the runtime's own `node:child_process`-backed default. */
+    runGateCommand?: GateCommandRunner;
+    /** Called once per `kind: "gate"` command attempt (every attempt, not just
+     *  the last) — the `gate-report` lifecycle event. */
+    onGateReport?: (ev: GateReportEvent) => void;
 }
 interface WorkflowRunResult {
     output: unknown;
@@ -414,6 +600,16 @@ declare class WorkflowCompileError extends Error {
 }
 /** Resolve a single `$…` reference string against the run bindings. */
 declare function resolveRef(ref: string, b: Bindings): unknown;
+/** Resolve the leading ref token of a string (see {@link REF_PREFIX_RE}):
+ *  if `value` starts with a `$input`/`$item`/`$steps`/`$index` reference
+ *  token, resolve it against the bindings and return the resolved value plus
+ *  the literal remainder (`rest`). Throws exactly like {@link resolveRef} for
+ *  a matched-but-malformed token; returns `undefined` when the string does
+ *  not START with a ref token at all (caller decides pass-through vs error). */
+declare function resolveRefPrefixed(value: string, b: Bindings): {
+    resolved: unknown;
+    rest: string;
+} | undefined;
 /** Recursively resolve a value node: refs in strings, into arrays/objects. */
 declare function resolveValue(node: unknown, b: Bindings): unknown;
 /** Evaluate a `while`/`when` predicate string against the bindings. */
@@ -461,6 +657,7 @@ interface AgentStepFields {
      *  steps resolve `$steps.*` refs into one before calling this). */
     prompt: string | Selector<string>;
     adapter?: string;
+    model?: Selector<string> | string;
     sessionRef?: string;
     sandbox?: AgentSandboxRef;
     cacheable?: boolean;
@@ -468,9 +665,62 @@ interface AgentStepFields {
     outputSchema?: AgentStep["outputSchema"];
     maxRetries?: number;
     options?: Record<string, boolean | number | string>;
+    harness?: AgentHarness;
 }
 /** Build a runtime {@link AgentStep} from field values, applying the same
  *  defaults everywhere: `policy` defaults to `{ awaiting: "fail" }`. */
 declare function buildAgentStep(id: string, fields: AgentStepFields): AgentStep;
 
-export { type AgentRefResolution, type AgentSandboxRef, type AgentSessionHost, type AgentStep, type AgentStepFields, type ApprovalRequest, type ApprovalStep, type Bindings, type BranchStep, type CompileWorkflowOptions, type FanOutOutcome, type GroupStep, type LoopStep, type MapStep, type ParallelStep, type PipelineStep, type ResumeRequest, type RunStep, type RunWorkflowArgs, type RuntimeWorkflow, type Selector, type StepCache, type StepCacheEntry, type SubworkflowStep, type SuspendStep, type TolerantFanOutResult, type ToolStep, type TransformStep, WorkflowCompileError, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, resolveRef, resolveValue, runWorkflow };
+/**
+ * `harness.knowledge` materialization (AIP-15 P2) — resolve each selector
+ * against its AIP-10 corpus workspace with the same `resolveKnowledge` the
+ * corpus CLI previews with, then write the matched raw entries (frontmatter +
+ * body) into the step's cwd under `.knowledge/` BEFORE the step's session
+ * runs. Idempotent: every run rewrites the same deterministic file set.
+ */
+
+/**
+ * Resolve every `$…`-bearing string of each `harness.knowledge[]` selector
+ * (`workspace`, `anyOf[]`, `allOf[]`, `kinds[]`) against the run bindings,
+ * producing selectors whose strings are run-resolved and stripped of the
+ * loader's internal `deferred` flag. Selectors without refs pass through
+ * unchanged (a copy). See {@link resolveRefString} for the ref rule.
+ */
+declare function resolveKnowledgeSelectors(stepId: string, selectors: readonly HarnessKnowledgeSelector[], b: Bindings): HarnessKnowledgeSelector[];
+interface MaterializedKnowledge {
+    records: KnowledgeAppliedRecord[];
+    /** Total entries written across all selectors — drives the prompt note. */
+    written: number;
+    /** human-readable warnings for empty matches (`knowledge-empty`). */
+    warnings: string[];
+}
+/**
+ * Materialize every selector in `selectors` under `<stepCwd>/.knowledge/`.
+ * Throws on a non-"files" `mode` or an unreadable workspace — the loader
+ * rejects both earlier; this is the direct-TS-authoring path's backstop.
+ */
+declare function materializeKnowledge(stepId: string, selectors: readonly HarnessKnowledgeSelector[], stepCwd: string): Promise<MaterializedKnowledge>;
+
+/**
+ * NodeFsPort — a read-mostly `FsPort` over the host filesystem, rooted at an
+ * AIP-10 corpus workspace. The local-FS twin of the adapter `corpus-cli`'s
+ * knowledge preview uses, so `harness.knowledge` materialization resolves a
+ * workspace with exactly the same port (and therefore the same hidden-segment
+ * skipping and path confinement) the CLI does.
+ */
+
+declare class NodeFsPort implements FsPort {
+    private readonly root;
+    constructor(root: string);
+    private resolve;
+    exists(p: string): Promise<boolean>;
+    readFile(p: string): Promise<string>;
+    writeFile(p: string, content: string): Promise<void>;
+    appendFile(p: string, content: string): Promise<void>;
+    readdir(p: string): Promise<readonly string[]>;
+    walk(p: string): Promise<readonly string[]>;
+    stat(p: string): Promise<FsStat | null>;
+    lock(): Promise<FsLockHandle>;
+}
+
+export { type AgentHarness, type AgentRefResolution, type AgentSandboxRef, type AgentSessionHost, type AgentStep, type AgentStepFields, type ApprovalDecision, type ApprovalRequest, type ApprovalStep, type Bindings, type BranchStep, type CompileWorkflowOptions, type FanOutOutcome, type GateCommandResult, type GateCommandRunner, type GateReportEvent, type GateStep, type GroupStep, type HarnessKnowledgeSelector, type KnowledgeAppliedRecord, type LoopStep, type MapStep, type MaterializedKnowledge, NodeFsPort, type ParallelStep, type PipelineStep, type ResumeRequest, type RunStep, type RunWorkflowArgs, type RuntimeWorkflow, type Selector, type StepCache, type StepCacheEntry, type SubworkflowStep, type SuspendStep, type TolerantFanOutResult, type ToolStep, type TransformStep, WorkflowCompileError, type WorkflowRunResult, WorkflowSuspendedError, buildAgentStep, compileWorkflow, compileWorkflowManifest, evalPredicate, materializeKnowledge, resolveKnowledgeSelectors, resolveRef, resolveRefPrefixed, resolveValue, runWorkflow };