@purista/harness 1.5.0 → 1.5.1

package/dist/agents/index.js

@@ -129,8 +129,7 @@ async function runDefaultAgentInner(args) {
     const outputSchema = args.agent.output ?? z.string();
     const parsedInput = parseAgentSchema(inputSchema, args.input, 'agent_input');
     const selectedModelAlias = args.modelAlias ?? args.agent.model;
-    const model = args.models[selectedModelAlias];
-    if (!model)
+    if (!args.models[selectedModelAlias])
         throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: selectedModelAlias } });
     const skillIds = args.agent.skills ?? [];
     await mountSkillsOnce(args.session, args.mountedSkills, args.skills, skillIds);
@@ -175,6 +174,7 @@ async function runDefaultAgentInner(args) {
     });
     const mcpSpecs = args.mcpRegistry ? await getMcpToolSpecs(args.customTools, enabledCustomTools, { registry: args.mcpRegistry, signal: args.signal, toolTimeoutMs: args.toolTimeoutMs, sandbox: args.session, sandboxKey: args.sessionId }) : [];
     const customSpecs = [...tsCustomSpecs, ...mcpSpecs];
+    const allToolSpecs = [...builtinSpecs, ...customSpecs];
     const nonSystem = args.history.filter((m) => m.role !== 'system');
     const system = args.history.filter((m) => m.role === 'system');
     const cappedNonSystem = args.historyWindow === undefined ? nonSystem : args.historyWindow === 0 ? [] : nonSystem.slice(-args.historyWindow);
@@ -201,19 +201,42 @@ async function runDefaultAgentInner(args) {
                 throw abortError(args.signal, 'run', 'Run was cancelled.');
             if (steps >= maxSteps)
                 throw new AgentLoopBudgetError('Agent loop budget exceeded.', { agent_id: args.agentId, reason: 'iterations_exceeded', limit: maxSteps });
+            const prepared = await args.agent.prepareStep?.({
+                input: parsedInput,
+                runId: args.runId,
+                sessionId: args.sessionId,
+                history: { list: async () => args.history },
+                memory: args.memory,
+                checkpoints: args.checkpoints,
+                metadata: args.metadata ?? {},
+                metrics: args.metrics,
+                step: steps,
+                model: selectedModelAlias,
+                messages: modelMessages,
+                tools: allToolSpecs
+            });
+            const stepModelAlias = prepared?.model ?? selectedModelAlias;
+            const model = args.models[stepModelAlias];
+            if (!model)
+                throw new ValidationError('Unknown model alias', { where: 'agent_input', issues: { model: stepModelAlias } });
+            const stepTools = filterActiveTools(allToolSpecs, prepared?.activeTools, args.agentId);
+            const stepMessages = prepared?.messages ? [...prepared.messages] : modelMessages;
+            const stepInstructions = prepared?.instructions ?? instructions;
             const response = await model.object({
                 messages: [
-                    { role: 'system', content: instructions },
-                    ...modelMessages
+                    { role: 'system', content: stepInstructions },
+                    ...stepMessages
                 ],
-                tools: [...builtinSpecs, ...customSpecs],
-                schema: z.toJSONSchema(outputSchema)
+                tools: stepTools,
+                schema: z.toJSONSchema(outputSchema),
+                ...(prepared?.call ? { call: prepared.call } : {})
             }, args.signal, {
                 harnessName: args.harnessName,
                 sessionId: args.sessionId,
                 runId: args.runId,
                 ...(args.workflowId ? { workflowId: args.workflowId } : {}),
-                agentId: args.agentId
+                agentId: args.agentId,
+                modelAlias: stepModelAlias
             });
             // Emit one usage-bearing model event per model round-trip (including
             // tool-call steps) so run-summary modelCalls and tokenTotals are accurate
@@ -223,11 +246,17 @@ async function runDefaultAgentInner(args) {
                 runId: args.runId,
                 agentId: args.agentId,
                 ...(args.workflowId ? { workflowId: args.workflowId } : {}),
-                modelAlias: selectedModelAlias,
+                modelAlias: stepModelAlias,
                 object: (response.object ?? null),
                 usage: response.usage
             });
             const toolCalls = (response.toolCalls ?? []);
+            if (await shouldStopAgentLoop(args, parsedInput, stepModelAlias, steps, modelMessages, allToolSpecs, response, toolCalls)) {
+                const validated = parseAgentSchema(outputSchema, response.object, 'agent_output');
+                emitted.push({ id: `msg_${ulid()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() });
+                await args.emitEvent?.({ type: 'agent.finished', runId: args.runId, agentId: args.agentId, at: new Date().toISOString(), output: validated, ...agentEventMeta });
+                return { output: validated, emitted };
+            }
             if (toolCalls.length === 0) {
                 const validated = parseAgentSchema(outputSchema, response.object, 'agent_output');
                 emitted.push({ id: `msg_${ulid()}_a`, sessionId: args.sessionId, runId: args.runId, role: 'assistant', content: JSON.stringify(validated), timestamp: new Date().toISOString() });
@@ -262,6 +291,41 @@ async function runDefaultAgentInner(args) {
         throw error;
     }
 }
+function filterActiveTools(tools, activeTools, agentId) {
+    if (!activeTools)
+        return [...tools];
+    const requested = new Set(activeTools);
+    const filtered = tools.filter((tool) => requested.has(tool.name));
+    if (filtered.length !== requested.size) {
+        const available = new Set(tools.map((tool) => tool.name));
+        const unknown = [...requested].filter((name) => !available.has(name));
+        throw new ValidationError('prepareStep referenced an unknown active tool.', {
+            where: 'agent_input',
+            issues: { agentId, activeTools: unknown }
+        });
+    }
+    return filtered;
+}
+async function shouldStopAgentLoop(args, input, selectedModelAlias, step, messages, tools, response, toolCalls) {
+    if (!args.agent.stopWhen)
+        return false;
+    return args.agent.stopWhen({
+        input,
+        runId: args.runId,
+        sessionId: args.sessionId,
+        history: { list: async () => args.history },
+        memory: args.memory,
+        checkpoints: args.checkpoints,
+        metadata: args.metadata ?? {},
+        metrics: args.metrics,
+        step,
+        model: selectedModelAlias,
+        messages,
+        tools,
+        response,
+        toolCalls
+    });
+}
 /** Runs `fn` over `items` with bounded concurrency, preserving input order. */
 export async function runLimited(items, limit, fn) {
     const concurrency = Math.max(1, Math.min(limit, items.length));

package/dist/harness/defineHarness.d.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { type Logger } from '../logger/index.js';
-import type { ModelAlias, ModelCapability, TokenUsage } from '../ports/model-provider.js';
+import type { ModelAlias, ModelCapability, ObjectResponse, ToolCallSpec, ModelMessage, ModelToolSpec, TokenUsage, ModelCallOptions } from '../ports/model-provider.js';
 import type { StateStore } from '../ports/state.js';
 import type { Metrics, TelemetryShim } from '../telemetry/index.js';
 import type { HarnessAdapterContext } from '../ports/harness-context.js';
@@ -15,6 +15,7 @@ import type { HarnessError } from '../errors/harness-error.js';
 import { type Sandbox } from '../sandbox/index.js';
 import type { ModelHandle } from '../models/registry.js';
 import { type AdapterCapability, type DurableRuntimeAdapter, type HarnessInspection } from '../ports/capabilities.js';
+import type { DurableStepOptions } from '../runtime/steps.js';
 /** Stable harness version string for diagnostics and generated documentation. */
 export { HARNESS_VERSION } from '../version.js';
 /** OpenTelemetry capture controls used by the harness. */
@@ -365,6 +366,41 @@ export interface AgentContextMinimal<S extends BuilderState, I> {
     metadata: Readonly<Record<string, JsonValue>>;
     metrics: Metrics;
 }
+/** Context passed before each default agent loop model call. */
+export interface AgentPrepareStepContext<S extends BuilderState, I> extends AgentContextMinimal<S, I> {
+    /** Zero-based model-call step in the default loop. */
+    step: number;
+    /** Model alias selected for this step before overrides are applied. */
+    model: keyof NonNullable<S['models']> & string;
+    /** Messages that would be sent to the model for this step. */
+    messages: readonly ModelMessage[];
+    /** Model-facing tools that would be available for this step. */
+    tools: readonly ModelToolSpec[];
+}
+/** Per-step overrides returned from `AgentDefinition.prepareStep`. */
+export interface AgentPrepareStepResult<S extends BuilderState> {
+    /** Optional model alias override for this model call. */
+    model?: keyof NonNullable<S['models']> & string;
+    /** Optional instruction override for this model call only. */
+    instructions?: string;
+    /** Optional model-facing tool names to keep active for this model call. */
+    activeTools?: readonly string[];
+    /** Optional message override for this model call only. */
+    messages?: readonly ModelMessage[];
+    /** Optional generation settings for this model call only. */
+    call?: ModelCallOptions;
+}
+/** Context passed after a default agent loop model call to decide whether to stop. */
+export interface AgentStopWhenContext<S extends BuilderState, I> extends AgentPrepareStepContext<S, I> {
+    /** Raw provider-normalized object response from the current model call. */
+    response: ObjectResponse<JsonValue>;
+    /** Tool calls requested by the current model response. */
+    toolCalls: readonly ToolCallSpec[];
+}
+/** Hook used to prepare each model call in the default agent loop. */
+export type AgentPrepareStep<S extends BuilderState, I> = (ctx: AgentPrepareStepContext<S, I>) => AgentPrepareStepResult<S> | Promise<AgentPrepareStepResult<S> | void> | void;
+/** Hook used to stop the default loop after a model call. */
+export type AgentStopWhen<S extends BuilderState, I> = (ctx: AgentStopWhenContext<S, I>) => boolean | Promise<boolean>;
 /** Run-bound facade for explicit long-horizon context checkpoints. */
 export interface ContextCheckpoints {
     write(input: {
@@ -404,7 +440,7 @@ export interface WorkflowContext<S extends BuilderState, I, O> {
      * checkpointed and replayed on resume without re-running `fn`; otherwise it is
      * a transparent pass-through. See spec 10 "Durable steps".
      */
-    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>): Promise<T>;
+    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>, options?: DurableStepOptions): Promise<T>;
     output?: O;
 }
 /** Invoke options accepted by workflow-local child-agent calls. */
@@ -434,6 +470,24 @@ export interface AgentDefinition<S extends BuilderState, I extends z.ZodTypeAny
     permissions?: AgentPermissions;
     onPermission?: OnPermission;
     maxSteps?: number;
+    /**
+     * Optional hook for per-round loop control in the default agent loop.
+     *
+     * @example
+     * ```ts
+     * prepareStep: ({ step }) => step === 0 ? { activeTools: ['lookup'] } : {}
+     * ```
+     */
+    prepareStep?: AgentPrepareStep<S, z.infer<I>>;
+    /**
+     * Optional hook that can stop the default loop after a model call.
+     *
+     * @example
+     * ```ts
+     * stopWhen: ({ step }) => step >= 2
+     * ```
+     */
+    stopWhen?: AgentStopWhen<S, z.infer<I>>;
     handler?: (ctx: AgentContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 }
 /** Workflow definition registered inline within `.workflows(...)`. */
@@ -458,6 +512,8 @@ type AgentDefinitionResolved<S extends BuilderState, I extends z.ZodTypeAny, O e
     permissions?: AgentPermissions;
     onPermission?: OnPermission;
     maxSteps?: number;
+    prepareStep?: AgentPrepareStep<S, z.infer<I>>;
+    stopWhen?: AgentStopWhen<S, z.infer<I>>;
     handler?: (ctx: AgentContext<S, z.infer<I>, z.infer<O>>) => Promise<z.infer<O>>;
 };
 type AgentDefinitionFor<S extends BuilderState, D> = D extends {

package/dist/index.d.ts

@@ -25,7 +25,7 @@ export type { DurableReplayCheckpoint, DurableWorkspacePolicy, DurableWorkspaceS
 export { InMemoryDurableWorkspaceStore, inMemoryDurableWorkspaceStore } from './workspace/index.js';
 export type { ContextCheckpoint, ContextCheckpointQuery, ContextCheckpointRef, ContextCheckpointStore, ContextCheckpointStoreInfo } from './ports/context-checkpoints.js';
 export { createDurableWorkflowContext, DurableStepError, DurableRunLeaseError, DurableTerminalRunError, inMemoryDurableRuntime, isResumeBlockingRunStatus, isTerminalRunStatus } from './runtime/index.js';
-export type { DurableActiveRunStatus, DurableWorkflowContext, DurableWorkflowContextOptions, DurableStepCommit, DurableRunLease, DurableRunStart, DurableRunStatus, DurableRuntime, DurableTerminalRunStatus, FinishRunPatch, InMemoryDurableRuntimeOptions, RunCheckpoint } from './runtime/index.js';
+export type { DurableActiveRunStatus, DurableWorkflowContext, DurableWorkflowContextOptions, DurableStepCommit, DurableStepOptions, DurableStepRetryPolicy, DurableStepRetrySetting, DurableRunLease, DurableRunStart, DurableRunStatus, DurableRuntime, DurableTerminalRunStatus, FinishRunPatch, InMemoryDurableRuntimeOptions, RunCheckpoint } from './runtime/index.js';
 export { bashSandbox, inMemorySandbox } from './sandbox/index.js';
 export type { ExecCapableSandboxSession, HibernateCapableSandbox, ResumeCapableSandbox, Sandbox, SandboxProcess, SandboxResumeOptions, SandboxSession, SandboxSessionBase, SandboxSessionFor, SnapshotCapableSandbox, SnapshotResult, SpawnCapableSandboxSession, SpawnOptions } from './sandbox/index.js';
 export type { DirEntry, ExecOptions, ExecResult, FileStat } from './harness/types.js';
@@ -35,4 +35,4 @@ export { discoverSkills } from './skills/index.js';
 export { evaluateDeterministicScorer, evaluatePromptCandidates } from './eval/index.js';
 export type { CandidateScore, DeterministicScorerDefinition, EvaluatePromptCandidatesInput, EvaluationItem, PromptCandidate, ScorerResult, ScorerTarget } from './eval/index.js';
 export { defineHarness } from './harness/defineHarness.js';
-export type { AgentContext, AgentContextMinimal, AgentDefinition, AgentDefinitionHelpers, AgentInput, AgentInvoker, AgentOutput, AgentPermissions, AgentsConfig, BuilderState, BuiltinToolName, ContentCaptureMode, ContextCheckpoints, ConversationHistory, DelegationDefaults, DiscoveredSkills, DiscoverSkillsOptions, DurableInvokeOptions, Harness, HarnessBuilder, HarnessDefaults, HarnessOptions, InferTypes, InvokeOptions, McpAuth, McpHttpToolDefinition, McpStdioToolDefinition, ModelHandles, ModelsConfig, OnPermission, PermissionContext, PermissionDecision, PermissionMode, PermissionPolicy, ResolvedSkill, RunEvent, RunSummary, SerializedError, Session, SkillDefinition, SkillDiagnostic, SkillFrontmatter, SkillsConfig, SkillValidationMode, TelemetryFlavor, TelemetryOptions, ToolDefinition, ToolHandlerContext, ToolsConfig, TsToolDefinition, WorkflowAgentInvokeOptions, WorkflowContext, WorkflowDefinition, WorkflowDefinitionHelpers, WorkflowDelegationPolicy, WorkflowInput, WorkflowInvoker, WorkflowOutput, WorkflowsConfig } from './harness/defineHarness.js';
+export type { AgentContext, AgentContextMinimal, AgentDefinition, AgentDefinitionHelpers, AgentInput, AgentInvoker, AgentOutput, AgentPermissions, AgentPrepareStep, AgentPrepareStepContext, AgentPrepareStepResult, AgentStopWhen, AgentStopWhenContext, AgentsConfig, BuilderState, BuiltinToolName, ContentCaptureMode, ContextCheckpoints, ConversationHistory, DelegationDefaults, DiscoveredSkills, DiscoverSkillsOptions, DurableInvokeOptions, Harness, HarnessBuilder, HarnessDefaults, HarnessOptions, InferTypes, InvokeOptions, McpAuth, McpHttpToolDefinition, McpStdioToolDefinition, ModelHandles, ModelsConfig, OnPermission, PermissionContext, PermissionDecision, PermissionMode, PermissionPolicy, ResolvedSkill, RunEvent, RunSummary, SerializedError, Session, SkillDefinition, SkillDiagnostic, SkillFrontmatter, SkillsConfig, SkillValidationMode, TelemetryFlavor, TelemetryOptions, ToolDefinition, ToolHandlerContext, ToolsConfig, TsToolDefinition, WorkflowAgentInvokeOptions, WorkflowContext, WorkflowDefinition, WorkflowDefinitionHelpers, WorkflowDelegationPolicy, WorkflowInput, WorkflowInvoker, WorkflowOutput, WorkflowsConfig } from './harness/defineHarness.js';

package/dist/runtime/steps.d.ts

@@ -18,6 +18,26 @@ export interface DurableWorkflowContextOptions {
      */
     readonly onStepCommit?: (commit: DurableStepCommit) => Promise<DurableReplayCheckpoint | undefined>;
 }
+/** Retry policy for a single explicit workflow step. */
+export type DurableStepRetrySetting = boolean | DurableStepRetryPolicy;
+/** Provider-neutral retry policy for `ctx.step(...)` boundaries. */
+export interface DurableStepRetryPolicy {
+    /** Total attempts including the first call. Default: `3`. */
+    readonly maxAttempts?: number;
+    /** Base delay before retrying in milliseconds. Default: `100`. */
+    readonly minDelayMs?: number;
+    /** Maximum delay before retrying in milliseconds. Default: `1_000`. */
+    readonly maxDelayMs?: number;
+    /** Delay strategy. Default: `exponential`. */
+    readonly backoff?: 'fixed' | 'exponential';
+    /** Optional predicate to suppress retries for non-transient failures. */
+    readonly shouldRetry?: (error: unknown, attempt: number) => boolean | Promise<boolean>;
+}
+/** Per-call options for an explicit workflow step. */
+export interface DurableStepOptions {
+    /** Retry failed step functions before a checkpoint is committed. Default: no retry. */
+    readonly retry?: DurableStepRetrySetting;
+}
 /** Durable workflow context that exposes explicit checkpoint boundaries. */
 export interface DurableWorkflowContext {
     /** Current durable run lease. */
@@ -30,7 +50,7 @@ export interface DurableWorkflowContext {
      * const prepared = await ctx.step('prepare-inputs', async () => ({ ok: true }))
      * ```
      */
-    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>): Promise<T>;
+    step<T extends JsonValue>(stepId: string, fn: () => Promise<T>, options?: DurableStepOptions): Promise<T>;
 }
 /** Error thrown when a durable step id is invalid or duplicated. */
 export declare class DurableStepError extends Error {
@@ -38,3 +58,4 @@ export declare class DurableStepError extends Error {
 }
 /** Creates a durable workflow context bound to an acquired runtime lease. */
 export declare function createDurableWorkflowContext(runtime: DurableRuntime, lease: DurableRunLease, options?: DurableWorkflowContextOptions): DurableWorkflowContext;
+export declare function runStepWithRetry<T>(fn: () => Promise<T>, retry: DurableStepRetrySetting | undefined): Promise<T>;

package/dist/runtime/steps.js

@@ -18,7 +18,7 @@ export function createDurableWorkflowContext(runtime, lease, options = {}) {
     let sequence = (lease.checkpoints ?? []).reduce((max, checkpoint) => Math.max(max, checkpoint.sequence), 0);
     return {
         lease,
-        async step(stepId, fn) {
+        async step(stepId, fn, stepOptions = {}) {
             validateStepId(stepId);
             if (completed.has(stepId)) {
                 throw new DurableStepError(`Duplicate durable step id "${stepId}".`);
@@ -29,7 +29,7 @@ export function createDurableWorkflowContext(runtime, lease, options = {}) {
             if (replay.has(stepId)) {
                 return replay.get(stepId);
             }
-            const output = await fn();
+            const output = await runStepWithRetry(fn, stepOptions.retry);
             assertJsonSerializable(output, stepId);
             sequence += 1;
             // Workspace state is written before the runtime checkpoint (spec 21 §10),
@@ -54,6 +54,57 @@ export function createDurableWorkflowContext(runtime, lease, options = {}) {
         }
     };
 }
+export async function runStepWithRetry(fn, retry) {
+    const policy = normalizeRetryPolicy(retry);
+    let attempt = 0;
+    let lastError;
+    while (attempt < policy.maxAttempts) {
+        attempt += 1;
+        try {
+            return await fn();
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= policy.maxAttempts)
+                break;
+            if (policy.shouldRetry && !await policy.shouldRetry(error, attempt))
+                break;
+            await sleep(retryDelayMs(policy, attempt));
+        }
+    }
+    throw lastError;
+}
+function normalizeRetryPolicy(retry) {
+    if (!retry) {
+        return { maxAttempts: 1, minDelayMs: 0, maxDelayMs: 0, backoff: 'fixed' };
+    }
+    if (retry === true) {
+        return { maxAttempts: 3, minDelayMs: 100, maxDelayMs: 1_000, backoff: 'exponential' };
+    }
+    return {
+        maxAttempts: clampPositiveInteger(retry.maxAttempts ?? 3),
+        minDelayMs: Math.max(0, retry.minDelayMs ?? 100),
+        maxDelayMs: Math.max(0, retry.maxDelayMs ?? 1_000),
+        backoff: retry.backoff ?? 'exponential',
+        ...(retry.shouldRetry ? { shouldRetry: retry.shouldRetry } : {})
+    };
+}
+function clampPositiveInteger(value) {
+    return Number.isFinite(value) && value > 0 ? Math.floor(value) : 1;
+}
+function retryDelayMs(policy, attempt) {
+    if (policy.maxDelayMs === 0)
+        return 0;
+    const base = policy.backoff === 'fixed'
+        ? policy.minDelayMs
+        : policy.minDelayMs * 2 ** Math.max(0, attempt - 1);
+    return Math.min(policy.maxDelayMs, base);
+}
+function sleep(ms) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
 function validateStepId(stepId) {
     if (!STEP_ID_PATTERN.test(stepId)) {
         throw new DurableStepError(`Invalid durable step id "${stepId}".`);

package/dist/sessions/index.d.ts

@@ -40,9 +40,9 @@ type HarnessDefinition<S extends BuilderState> = {
  * promise-notified rather than time-polled, so there is no fixed per-event
  * latency or periodic timer.
  *
- * Abandoning the stream (`break` / `iterator.return()`) aborts `relaySignal`,
- * so a run wired to it is cancelled promptly instead of blocking the consumer
- * until the run finishes on its own.
+ * Abandoning the stream (`break` / `iterator.return()`) only detaches that
+ * consumer. It does not abort `relaySignal`; callers must pass `opts.signal`
+ * when they intend to cancel the underlying run.
  */
 export declare function relayRunEvents(run: (onEvent: (event: RunEvent) => Promise<void>, relaySignal: AbortSignal) => Promise<unknown>): AsyncIterable<RunEvent>;
 export declare function createSessionHarness<S extends BuilderState>(definition: HarnessDefinition<S>): Harness<S>;

package/dist/sessions/index.js

@@ -4,6 +4,7 @@ import { runDefaultAgent } from '../agents/index.js';
 import { runWorkflow } from '../workflows/index.js';
 import { createMemoryFacade, createSessionMemory } from '../ports/memory.js';
 import { beginDurableWorkflow, DURABLE_RUN_ID_PATTERN, isExecutableDurableRuntime } from '../runtime/sessionDurable.js';
+import { runStepWithRetry } from '../runtime/steps.js';
 import { HarnessConfigError } from '../errors/catalog.js';
 import { loadSkillsSync } from '../skills/index.js';
 import { createModelRegistry } from '../models/registry.js';
@@ -49,9 +50,9 @@ const STREAM_UNDROPPABLE_EVENT_TYPES = new Set(['run.finished']);
  * promise-notified rather than time-polled, so there is no fixed per-event
  * latency or periodic timer.
  *
- * Abandoning the stream (`break` / `iterator.return()`) aborts `relaySignal`,
- * so a run wired to it is cancelled promptly instead of blocking the consumer
- * until the run finishes on its own.
+ * Abandoning the stream (`break` / `iterator.return()`) only detaches that
+ * consumer. It does not abort `relaySignal`; callers must pass `opts.signal`
+ * when they intend to cancel the underlying run.
  */
 export async function* relayRunEvents(run) {
     const queue = [];
@@ -61,6 +62,7 @@ export async function* relayRunEvents(run) {
     let failure;
     let wake;
     const relayController = new AbortController();
+    let completedNormally = false;
     const notify = () => {
         const resolve = wake;
         wake = undefined;
@@ -110,6 +112,7 @@ export async function* relayRunEvents(run) {
             }
             if (queue.length === 0 && dropped === 0) {
                 if (done) {
+                    completedNormally = true;
                     break;
                 }
                 // No await between the empty check and installing `wake`, so a producer
@@ -121,10 +124,12 @@ export async function* relayRunEvents(run) {
         }
     }
     finally {
-        // Cancel the run before awaiting it so an abandoned stream does not block
-        // `iterator.return()` until the run finishes or times out.
-        relayController.abort(new OperationCancelledError('Run event stream was abandoned by the consumer.', { scope: 'run' }));
-        await result.catch(() => undefined);
+        if (completedNormally) {
+            await result.catch(() => undefined);
+        }
+        else {
+            void result.catch(() => undefined);
+        }
     }
     if (failure)
         throw failure;
@@ -922,8 +927,8 @@ export function createSessionHarness(definition) {
         }
     }
     /** Pass-through step used when a workflow runs without durable execution. */
-    function passthroughStep(_stepId, fn) {
-        return fn();
+    function passthroughStep(_stepId, fn, options = {}) {
+        return runStepWithRetry(fn, options.retry);
     }
     function resolveDelegationPolicy(workflow) {
         const configured = workflow.delegation;

package/dist/version.d.ts

@@ -1,2 +1,2 @@
 /** Harness package version, used as the OpenTelemetry instrumentation scope version. */
-export declare const HARNESS_VERSION = "1.5.0";
+export declare const HARNESS_VERSION = "1.5.1";

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Harness package version, used as the OpenTelemetry instrumentation scope version. */
-export const HARNESS_VERSION = '1.5.0';
+export const HARNESS_VERSION = '1.5.1';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@purista/harness",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "description": "Self-hosted enterprise agent harness for typed tools, agents, workflows, state, sandboxing, and telemetry.",
   "type": "module",
   "main": "dist/index.js",
@@ -69,12 +69,12 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opentelemetry/context-async-hooks": "^2.7.1",
-    "@types/node": "^25.9.1",
-    "@vitest/coverage-v8": "^4.1.8",
+    "@opentelemetry/context-async-hooks": "^2.8.0",
+    "@types/node": "^25.9.3",
+    "@vitest/coverage-v8": "^4.1.9",
     "just-bash": "^3.0.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vitest": "^4.1.9"
   },
   "engines": {
     "node": ">=24.15.0"