@xrkseek/harness 0.4.8 → 0.4.10

package/node_modules/@xrkseek/xrk-workflow/lib/types/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * Service Definition for the workflow capability seam. Service Providers execute orchestration scripts;
+ * observe-only lifecycle events never expose run control.
+ * @module @xrkseek/xrk-workflow
+ */
+import { Context, Service } from '@xrkseek/cordis';
+import { HarnessError } from '@xrkseek/xrk-llm';
+import { type WorkflowAgentEndInfo, type WorkflowAgentInfo, type WorkflowResultInfo, type WorkflowRunInfo } from './types.ts';
+import type { WorkflowRun, WorkflowStartRequest } from './runtime-types.ts';
+export { WorkflowRunId } from './types.ts';
+export type { WorkflowAgentEndInfo, WorkflowAgentInfo, WorkflowAgentOutcome, WorkflowMeta, WorkflowPhase, WorkflowResult, WorkflowResultInfo, WorkflowRunInfo, WorkflowStopReason, } from './types.ts';
+export type { WorkflowRun, WorkflowStartRequest } from './runtime-types.ts';
+/**
+ * Nested `await tools.name(args)` bridge (Code Mode shape). Host mounts a
+ * registry-backed bridge; Isolating posts RPC across the worker boundary.
+ */
+export interface WorkflowToolCallResult {
+    readonly content: string;
+    readonly isError?: boolean;
+}
+export interface WorkflowToolBridge {
+    /** Names exposed on the `tools` Proxy (exclude recursive orchestrators). */
+    readonly listNames: () => readonly string[];
+    readonly call: (name: string, args: unknown, signal?: AbortSignal) => Promise<WorkflowToolCallResult>;
+}
+/** Build the script-facing `tools` Proxy (same contract as Code Mode). */
+export declare function buildWorkflowToolsProxy(bridge: WorkflowToolBridge | undefined, signal?: AbortSignal): Record<string, (args?: unknown) => Promise<string>>;
+declare module '@xrkseek/cordis' {
+    interface Context {
+        workflowEngine: WorkflowEngine;
+    }
+    interface Events {
+        /**
+         * A workflow run started — the script's meta block validated, the body
+         * about to execute. Paired with {@link Events['workflow/end']}.
+         * @param info - the run's identity snapshot (id + meta).
+         * @mode emit
+         */
+        'workflow/start'(info: WorkflowRunInfo): void;
+        /**
+         * The script entered a phase (a `phase(title)` call) — progress grouping
+         * for observers; no execution semantics.
+         * @param info - the run's identity snapshot.
+         * @param title - the phase title, verbatim.
+         * @mode emit
+         */
+        'workflow/phase'(info: WorkflowRunInfo, title: string): void;
+        /**
+         * The script emitted a narration line (a `log(message)` call).
+         * @param info - the run's identity snapshot.
+         * @param message - the logged message, verbatim.
+         * @mode emit
+         */
+        'workflow/log'(info: WorkflowRunInfo, message: string): void;
+        /**
+         * One `agent()` call established a published child run. Paired with
+         * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+         * receives a published run from the provider emits neither
+         * event in this pair.
+         * @param info - the run's identity snapshot.
+         * @param agent - the call's sequence number, label, phase, and child id.
+         * @mode emit
+         */
+        'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void;
+        /**
+         * One `agent()` call settled (clean result, child failure, or run
+         * cancellation). Paired with {@link Events['workflow/agent-start']} by
+         * `agent.seq`, exactly once per started call on every stop path — on an
+         * engine termination path (a worker killed past its grace) the end is
+         * engine-synthesized with outcome `'cancelled'`.
+         * @param info - the run's identity snapshot.
+         * @param agent - the call identity plus its outcome.
+         * @mode emit
+         */
+        'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void;
+        /**
+         * A workflow run settled (any stop reason). Fired when
+         * {@link WorkflowRun.result} resolves. Paired with
+         * {@link Events['workflow/start']}.
+         * @param info - the run's identity snapshot.
+         * @param result - the outcome data (stop reason, error, agent count) —
+         *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+         * @mode emit
+         */
+        'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void;
+    }
+}
+/** The full set of `workflow/*` event names {@link WorkflowEngine.emitWorkflowEvent} dispatches. */
+export type WorkflowEventName = 'workflow/start' | 'workflow/phase' | 'workflow/log' | 'workflow/agent-start' | 'workflow/agent-end' | 'workflow/end';
+/**
+ * Machine-routable fatal workflow failures: parse/meta/argument/schema errors,
+ * resource caps, subagent infrastructure failures, unserializable boundary
+ * values, and cancellation. An ordinary child failure resolves its item to
+ * `null` and is not one of these fatal codes.
+ */
+export type WorkflowErrorCode = 'SCRIPT_PARSE' | 'META_INVALID' | 'INVALID_ARGUMENT' | 'UNSUPPORTED_OPTION' | 'UNSUPPORTED_SCHEMA' | 'AGENT_CAP' | 'ITEM_CAP' | 'AGENT_START' | 'AGENT_RESULT' | 'RESULT_UNSERIALIZABLE' | 'CANCELLED' | 'WORKER_EXIT';
+/**
+ * Typed error for workflow-seam failures. Extends {@link HarnessError}, so the
+ * `code` is machine-routable taxonomy. `fatal` drives the combinator
+ * discipline: `parallel()`/`pipeline()` re-throw a fatal error (a typo'd
+ * option or a tripped cap must kill the script loudly), and reserve the
+ * per-item `null` for child-run failures and ordinary in-stage script errors.
+ * Every {@link WorkflowErrorCode} is fatal; the flag exists so the
+ * distinction is explicit at every catch site rather than implied.
+ */
+export declare class WorkflowError extends HarnessError {
+    /** Whether combinators must propagate this error instead of nulling the item. */
+    readonly fatal: boolean;
+    constructor(message: string, code: WorkflowErrorCode, options?: ErrorOptions & {
+        fatal?: boolean;
+    });
+}
+/**
+ * Whether combinators must re-throw `error` instead of mapping the item to `null`.
+ * @param error - any thrown value; fatality is host `instanceof` (unforgeable from a script realm).
+ * @returns true iff `error` is a {@link WorkflowError} whose `fatal` flag is set.
+ */
+export declare function isFatalWorkflowError(error: unknown): boolean;
+/**
+ * Workflow Service Definition contract. Invalid requests throw before publication; a live
+ * run is holder-owned, its result never rejects, cancellation and disposal are
+ * bounded, and disposal waits for child cleanup within that bound. Lifecycle
+ * listener failures are contained, and `workflow/end` fires exactly once as the
+ * result settles.
+ */
+export declare abstract class WorkflowEngine extends Service {
+    constructor(ctx: Context);
+    /**
+     * Parse and execute a workflow script.
+     * @param request - the script, its `args`, the parent agent, and an
+     *   optional cancel signal.
+     * @returns the live run; its `result` resolves when the script settles.
+     */
+    abstract start(request: WorkflowStartRequest): WorkflowRun;
+    /**
+     * Emit a lifecycle event while containing and logging each listener failure.
+     * @param name - the `workflow/*` event to dispatch.
+     * @param args - the event's payload, matching its declared signature.
+     */
+    protected emitWorkflowEvent(name: WorkflowEventName, ...args: unknown[]): void;
+}
+/**
+ * In-process Provider: AsyncFunction body with `phase` / `log` / `agent`.
+ * `agent()` returns `null` unless `createAgent` is supplied (Cordis compositions
+ * that wire subagents). Product Face boot uses the Face-native `ralph` tool;
+ * this Provider fills the abstract `ctx.workflowEngine` hole for Cordis mounts.
+ */
+export declare class InProcessWorkflowEngine extends WorkflowEngine {
+    private readonly createAgent;
+    private readonly toolBridge;
+    constructor(ctx: Context, options?: {
+        readonly createAgent?: InProcessWorkflowEngine['createAgent'];
+        readonly toolBridge?: WorkflowToolBridge;
+    });
+    start(request: WorkflowStartRequest): WorkflowRun;
+}
+/**
+ * Worker-thread Provider: script body runs in an isolated `worker_threads`
+ * Worker (eval). `agent()` posts an RPC to the parent thread, which may run
+ * an optional {@link IsolatingWorkflowEngine} `createAgent` bridge (same
+ * contract as {@link InProcessWorkflowEngine}) and return a structured-cloneable
+ * value. Without `createAgent`, `agent()` still settles `null`.
+ * `await tools.name(args)` uses an optional {@link WorkflowToolBridge}
+ * (Code Mode subset — nested Host tools via parentPort RPC). Full sandboxed
+ * Node PTC process confinement is not claimed.
+ */
+export declare class IsolatingWorkflowEngine extends WorkflowEngine {
+    private readonly createAgent;
+    private readonly toolBridge;
+    constructor(ctx: Context, options?: {
+        readonly createAgent?: IsolatingWorkflowEngine['createAgent'];
+        readonly toolBridge?: WorkflowToolBridge;
+    });
+    start(request: WorkflowStartRequest): WorkflowRun;
+}
+export default WorkflowEngine;
+//# sourceMappingURL=index.d.ts.map