@xrkseek/harness 0.4.8 → 0.4.9

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

@@ -0,0 +1,13 @@
+/** Package-owned workflow lifecycle invariants. @module @xrkseek/xrk-workflow/invariant */
+import type { Context } from '@xrkseek/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "workflow-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register the workflow invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/node_modules/@xrkseek/xrk-workflow/lib/types/invariant.js

@@ -0,0 +1,118 @@
+/** Package-owned workflow lifecycle invariants. @module @xrkseek/xrk-workflow/invariant */
+const PACKAGE_NAME = '@xrkseek/xrk-workflow';
+/** Cordis companion plugin name. */
+export const name = 'workflow-invariant';
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants'];
+/** Require every event for a run to retain its validated identity snapshot. */
+function traceFor(traces, info, fail) {
+    const trace = traces.get(info.id);
+    if (trace === undefined)
+        fail(`workflow event has no matching workflow/start for run ${JSON.stringify(info.id)}`);
+    if (trace.meta !== JSON.stringify(info.meta)) {
+        fail(`workflow event meta diverges from workflow/start for run ${JSON.stringify(info.id)}`);
+    }
+    return trace;
+}
+/** Assert the immutable identity fields shared by an agent pair. */
+function validateAgentEnd(start, end, fail) {
+    if (start.label !== end.label || start.phase !== end.phase || start.childId !== end.childId) {
+        fail(`workflow/agent-end identity diverges from workflow/agent-start for seq ${end.seq}`);
+    }
+    const outcome = end.outcome;
+    if (outcome !== 'completed' && outcome !== 'failed' && outcome !== 'cancelled') {
+        fail(`workflow/agent-end carries unknown outcome ${JSON.stringify(outcome)}`);
+    }
+}
+/** Validate a terminal result against the accumulated run trace. */
+function validateWorkflowEnd(trace, result, fail) {
+    if (trace.agents.size > 0)
+        fail(`workflow/end has ${trace.agents.size} agent call(s) without workflow/agent-end`);
+    if (!Number.isSafeInteger(result.agentsStarted) || result.agentsStarted < trace.starts) {
+        fail('workflow/end agentsStarted must be a safe integer covering every observed agent start');
+    }
+    if (result.stopReason === 'completed' ? result.error !== undefined : typeof result.error !== 'string') {
+        fail('workflow/end error must be absent exactly for completed runs');
+    }
+}
+/** Install workflow start/end and child-call pairing checks. */
+const install = (ctx, fail) => {
+    const traces = new Map();
+    const stagedStarts = new WeakSet();
+    const stagedAgentStarts = new WeakSet();
+    const stagedAgentEnds = new WeakSet();
+    const stagedEnds = new WeakSet();
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName === 'workflow/start') {
+            const info = args[0];
+            if (String(info.id).length === 0 || info.meta.name.length === 0 || info.meta.description.length === 0) {
+                fail('workflow/start id, meta.name, and meta.description must be non-empty');
+            }
+            if (traces.has(info.id))
+                fail(`workflow/start repeated run id ${JSON.stringify(info.id)}`);
+            stagedStarts.add(info);
+            return;
+        }
+        if (!eventName.startsWith('workflow/'))
+            return;
+        const info = args[0];
+        const trace = traceFor(traces, info, fail);
+        if (eventName === 'workflow/agent-start') {
+            const agent = args[1];
+            if (!Number.isSafeInteger(agent.seq) || agent.seq < 1 || String(agent.childId).length === 0) {
+                fail('workflow/agent-start seq must be positive and childId must be non-empty');
+            }
+            if (trace.agents.has(agent.seq))
+                fail(`workflow/agent-start repeated seq ${agent.seq}`);
+            stagedAgentStarts.add(agent);
+            return;
+        }
+        if (eventName === 'workflow/agent-end') {
+            const agent = args[1];
+            const start = trace.agents.get(agent.seq);
+            if (start === undefined)
+                return fail(`workflow/agent-end has no matching start for seq ${agent.seq}`);
+            validateAgentEnd(start, agent, fail);
+            stagedAgentEnds.add(agent);
+            return;
+        }
+        if (eventName === 'workflow/end') {
+            const result = args[1];
+            validateWorkflowEnd(trace, result, fail);
+            stagedEnds.add(result);
+        }
+    }, { global: true });
+    ctx.on('workflow/start', (info) => {
+        /* v8 ignore next -- internal/dispatch stages the same run-info object */
+        if (!stagedStarts.delete(info))
+            return;
+        traces.set(info.id, { meta: JSON.stringify(info.meta), agents: new Map(), starts: 0 });
+    }, { global: true });
+    ctx.on('workflow/agent-start', (info, agent) => {
+        /* v8 ignore next -- internal/dispatch stages the same agent object */
+        if (!stagedAgentStarts.delete(agent))
+            return;
+        const trace = traceFor(traces, info, fail);
+        trace.agents.set(agent.seq, agent);
+        trace.starts += 1;
+    }, { global: true });
+    ctx.on('workflow/agent-end', (info, agent) => {
+        /* v8 ignore next -- internal/dispatch stages the same agent object */
+        if (!stagedAgentEnds.delete(agent))
+            return;
+        traceFor(traces, info, fail).agents.delete(agent.seq);
+    }, { global: true });
+    ctx.on('workflow/end', (info, result) => {
+        /* v8 ignore next -- internal/dispatch stages the same result object */
+        if (!stagedEnds.delete(result))
+            return;
+        traces.delete(info.id);
+    }, { global: true });
+};
+/**
+ * Register the workflow invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//# sourceMappingURL=invariant.js.map

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

@@ -0,0 +1,45 @@
+/**
+ * Host-only workflow request and live-run handles. The browser-safe durable
+ * vocabulary remains in `./types` so Client programs never import Agent or
+ * host Cordis context declarations.
+ *
+ * @module @xrkseek/xrk-workflow
+ */
+import type { Agent } from '@xrkseek/xrk-agent';
+import type { WorkflowMeta, WorkflowResult, WorkflowRunId } from './types.ts';
+/**
+ * What a caller asks for when starting a workflow run. `meta` and `args` are
+ * plain JSON data by the seam contract. `parent` is required because every
+ * `agent()` spawned by the script is attributed to that live Agent.
+ */
+export interface WorkflowStartRequest {
+    /** The plain-JS script body (top-level await allowed; ends with `return <json-value>`). */
+    script: string;
+    /** The workflow's identity block, as plain JSON data (shape-validated by the engine). */
+    meta: WorkflowMeta;
+    /** Optional input exposed verbatim to the script as the `args` global. */
+    args?: unknown;
+    /** Optional engine-wide child-provider override for this run. */
+    subagentProvider?: string;
+    /** Optional per-run total-child ceiling. */
+    maxTotalAgents?: number;
+    /** The agent on whose behalf the run executes (parent of every child). */
+    parent: Agent;
+    /** Cancels the run when aborted. */
+    signal?: AbortSignal;
+}
+/**
+ * Holder-owned live workflow. `result` never rejects; consumers may cancel
+ * and must call idempotent `dispose()` to await script and child quiescence.
+ */
+export interface WorkflowRun {
+    readonly id: WorkflowRunId;
+    /** The validated meta block available before the script body runs. */
+    readonly meta: WorkflowMeta;
+    readonly result: Promise<WorkflowResult>;
+    /** Cancel the run and its children. */
+    cancel(reason?: string): void;
+    /** Cancel if needed and await bounded settlement and cleanup. */
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=runtime-types.d.ts.map

package/node_modules/@xrkseek/xrk-workflow/lib/types/runtime-types.js

@@ -0,0 +1,9 @@
+/**
+ * Host-only workflow request and live-run handles. The browser-safe durable
+ * vocabulary remains in `./types` so Client programs never import Agent or
+ * host Cordis context declarations.
+ *
+ * @module @xrkseek/xrk-workflow
+ */
+export {};
+//# sourceMappingURL=runtime-types.js.map

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

@@ -0,0 +1,118 @@
+/**
+ * Workflow seam vocabulary: the request/run/result types a workflow engine
+ * consumes and produces, plus the fields in the `workflow/*` event payloads.
+ * Types only (plus the id-brand factory), per the package convention.
+ *
+ * @module @xrkseek/xrk-workflow/types
+ */
+import type { Branded } from '@xrkseek/xrk-brand';
+import type { SessionId } from '@xrkseek/xrk-session/types';
+/** Identifies one workflow run. */
+export type WorkflowRunId = Branded<'WorkflowRunId'>;
+/**
+ * Brand a string as a {@link WorkflowRunId}.
+ * @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures).
+ * @returns the same string, branded.
+ */
+export declare function WorkflowRunId(id: string): WorkflowRunId;
+/**
+ * One phase declared in a script's `meta.phases` (progress vocabulary only —
+ * phases group agents in observers/UIs; they impose no execution structure).
+ */
+export interface WorkflowPhase {
+    /** The phase title; `phase()` calls match against it by exact string. */
+    title: string;
+    /** Optional one-line description of what the phase does. */
+    detail?: string;
+    /** Optional provider override this phase is expected to use (informational). */
+    provider?: string;
+    /** Optional model override this phase is expected to use (informational). */
+    model?: string;
+}
+/**
+ * The script's identity block, provided as plain JSON data alongside the
+ * script body (the model-facing tool carries it as its `meta` parameter) and
+ * validated by the engine before the body runs. `name`/`description` are
+ * required; the rest is optional annotation. The field vocabulary matches the
+ * Claude Code dynamic-workflows meta block.
+ */
+export interface WorkflowMeta {
+    /** Short kebab-case workflow name (display + persistence key). */
+    name: string;
+    /** One-line description of what the workflow does. */
+    description: string;
+    /** Optional guidance on when this workflow applies (shown in listings). */
+    whenToUse?: string;
+    /** Optional phase declarations matched by `phase()` calls. */
+    phases?: WorkflowPhase[];
+}
+/**
+ * Why a run settled. CLOSED union (engine-owned, consumers may exhaust):
+ * `completed` = the script ran to its final `return`; `cancelled` = the run
+ * was cancelled (caller `cancel()`/signal); `error` = the script threw, a
+ * fatal `WorkflowError` propagated, or the result failed materialization.
+ */
+export type WorkflowStopReason = 'completed' | 'cancelled' | 'error';
+/**
+ * The outcome resolved by a live workflow run. `value` is
+ * the script's materialized return value (plain host-realm JSON data; `null`
+ * when the script returned `undefined`) — meaningful only for `completed`.
+ * A non-`completed` reason carries the failure in `error`; the consumer maps
+ * it to an `isError` tool result rather than reporting partial output.
+ */
+export interface WorkflowResult {
+    /** The script's return value (host JSON data; `null` for no return). */
+    value: unknown;
+    /** Why the run settled. */
+    stopReason: WorkflowStopReason;
+    /** The failure message (present iff `stopReason` is not `completed`). */
+    error?: string;
+    /**
+     * How many `agent()` calls the run accepted over its whole lifetime. On a
+     * graceful settlement this is the script-side count (calls still queued for
+     * a concurrency slot included); on a termination path (grace force-settle,
+     * worker death) it degrades to the host-observed count — calls queued
+     * inside a terminated script are unknowable then.
+     */
+    agentsStarted: number;
+}
+/** Identifying detail for a run, carried by every `workflow/*` event as borrowed immutable data, never the live run. */
+export interface WorkflowRunInfo {
+    /** The run's id. */
+    id: WorkflowRunId;
+    /** The run's validated meta block. */
+    meta: WorkflowMeta;
+}
+/** One `agent()` call's identity within a run (the `workflow/agent-start` payload). */
+export interface WorkflowAgentInfo {
+    /** 1-based sequence number of this `agent()` call within the run. */
+    seq: number;
+    /** The display label (the `label` option, or a prompt snippet). */
+    label: string;
+    /** The phase this agent belongs to (the `phase` option, else the current `phase()` title). */
+    phase?: string;
+    /** The child agent's id on the subagent seam. */
+    childId: SessionId;
+}
+/** How one `agent()` call settled: clean result, child failure (script sees `null`), or run cancellation. */
+export type WorkflowAgentOutcome = 'completed' | 'failed' | 'cancelled';
+/** One `agent()` call's settlement (the `workflow/agent-end` payload). */
+export interface WorkflowAgentEndInfo extends WorkflowAgentInfo {
+    /** How the call settled. */
+    outcome: WorkflowAgentOutcome;
+}
+/**
+ * A settled run's outcome as event data (the `workflow/end` payload): the
+ * {@link WorkflowResult} minus `value` (a listener observing outcomes must not
+ * receive a mutable alias of the caller's result value; a consumer that needs
+ * the value holds the run and awaits `result`).
+ */
+export interface WorkflowResultInfo {
+    /** Why the run settled. */
+    stopReason: WorkflowStopReason;
+    /** The failure message (present iff `stopReason` is not `completed`). */
+    error?: string;
+    /** How many `agent()` calls the run accepted (see {@link WorkflowResult.agentsStarted}). */
+    agentsStarted: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/node_modules/@xrkseek/xrk-workflow/lib/types/types.js

@@ -0,0 +1,16 @@
+/**
+ * Workflow seam vocabulary: the request/run/result types a workflow engine
+ * consumes and produces, plus the fields in the `workflow/*` event payloads.
+ * Types only (plus the id-brand factory), per the package convention.
+ *
+ * @module @xrkseek/xrk-workflow/types
+ */
+/**
+ * Brand a string as a {@link WorkflowRunId}.
+ * @param id - the raw id string (the engine mints UUIDs; tests may pass fixtures).
+ * @returns the same string, branded.
+ */
+export function WorkflowRunId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/node_modules/@xrkseek/xrk-workflow/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@xrkseek/xrk-workflow",
+  "description": "Workflow capability seam: ctx.workflowEngine service, run vocabulary, and workflow/* events",
+  "version": "0.1.0-rc.8",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xrkseek/XRK-harness.git",
+    "directory": "packages/workflow/workflow"
+  },
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./src/index.ts"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/types/invariant.js"
+    },
+    "./types": {
+      "types": "./lib/types/types.d.ts",
+      "default": "./lib/types/types.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@xrkseek/xrk-agent": "workspace:^",
+    "@xrkseek/xrk-brand": "workspace:^",
+    "@xrkseek/xrk-invariants": "workspace:^",
+    "@xrkseek/xrk-llm": "workspace:^",
+    "@xrkseek/xrk-session": "workspace:^",
+    "@xrkseek/cordis": "workspace:^"
+  },
+  "devDependencies": {
+    "@xrkseek/xrk-agent": "workspace:^",
+    "@xrkseek/xrk-brand": "workspace:^",
+    "@xrkseek/xrk-invariants": "workspace:^",
+    "@xrkseek/xrk-llm": "workspace:^",
+    "@xrkseek/xrk-session": "workspace:^",
+    "@xrkseek/cordis": "workspace:^"
+  },
+  "private": true
+}