@cleocode/adapters 2026.4.47 → 2026.4.49

package/src/providers/openai-sdk/manifest.json

@@ -0,0 +1,45 @@
+{
+  "id": "openai-sdk",
+  "name": "OpenAI Agents SDK Adapter",
+  "version": "1.0.0",
+  "description": "CLEO adapter for the OpenAI Agents SDK with first-class handoffs and multi-model support",
+  "provider": "openai-sdk",
+  "entryPoint": "src/providers/openai-sdk/index.ts",
+  "capabilities": {
+    "supportsHooks": false,
+    "supportedHookEvents": [],
+    "supportsSpawn": true,
+    "supportsInstall": true,
+    "supportsMcp": false,
+    "supportsInstructionFiles": true,
+    "instructionFilePattern": "AGENTS.md",
+    "supportsContextMonitor": false,
+    "supportsStatusline": false,
+    "supportsProviderPaths": false,
+    "supportsTransport": false,
+    "supportsHandoffs": true,
+    "supportsMultiModel": true,
+    "supportsTracing": true
+  },
+  "config": {
+    "provider.openai.model": {
+      "type": "string",
+      "default": "gpt-4.1",
+      "description": "Default model for lead/orchestrator agents"
+    },
+    "provider.openai.workerModel": {
+      "type": "string",
+      "default": "gpt-4.1-mini",
+      "description": "Default model for worker agents"
+    },
+    "provider.openai.tracingEnabled": {
+      "type": "boolean",
+      "default": true,
+      "description": "Whether to write SDK span events to conduit.db"
+    }
+  },
+  "detectionPatterns": [
+    { "type": "env", "pattern": "OPENAI_API_KEY", "description": "OpenAI API key must be set" }
+  ],
+  "workerArchetypes": ["worker-read", "worker-write", "worker-bash"]
+}

package/src/providers/openai-sdk/spawn.ts

@@ -0,0 +1,300 @@
+/**
+ * OpenAI Agents SDK spawn provider.
+ *
+ * Implements `AdapterSpawnProvider` using the `@openai/agents` SDK runner.
+ * Unlike the Claude Code provider (detached fire-and-forget), this provider
+ * awaits the run and returns `status: 'completed'` or `status: 'failed'`
+ * so the orchestrator receives rich output immediately.
+ *
+ * Key features:
+ * - Tier-based model selection (lead → gpt-4.1, worker → gpt-4.1-mini)
+ * - Handoff topology built from `SpawnContext.options.handoffs`
+ * - CLEO path ACL guardrails applied at input stage
+ * - Default-on tracing via `CleoConduitTraceProcessor`
+ * - CANT prompt enrichment (best-effort, same as Claude Code provider)
+ *
+ * @task T582
+ */
+
+import type { AdapterSpawnProvider, SpawnContext, SpawnResult } from '@cleocode/contracts';
+import { getErrorMessage } from '@cleocode/contracts';
+import { addTraceProcessor, OpenAIProvider, Runner, setTracingDisabled } from '@openai/agents';
+import { mapSdkRunOutcome } from '../shared/sdk-result-mapper.js';
+import { buildDefaultGuardrails } from './guardrails.js';
+import { buildAgentTopology } from './handoff.js';
+import { CleoConduitTraceProcessor } from './tracing.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * OpenAI SDK-specific spawn options carried in `SpawnContext.options`.
+ *
+ * @remarks
+ * All fields are optional. Unknown fields are ignored.
+ */
+export interface OpenAiSdkSpawnOptions {
+  /**
+   * OpenAI model to use.
+   *
+   * @defaultValue Derived from `tier`:
+   *   - `'lead'` / `'orchestrator'` → `'gpt-4.1'`
+   *   - `'worker'` → `'gpt-4.1-mini'`
+   */
+  model?: string;
+
+  /**
+   * Agent archetype tier. Controls model selection and topology shape.
+   *
+   * @defaultValue `'worker'`
+   */
+  tier?: 'lead' | 'worker' | 'orchestrator';
+
+  /**
+   * Worker archetype names this agent may hand off to.
+   * References keys in `WORKER_ARCHETYPES` from `handoff.ts`.
+   *
+   * @defaultValue `[]`
+   */
+  handoffs?: string[];
+
+  /**
+   * File-path glob ACL allowlist. Paths outside this list trip the path guardrail.
+   *
+   * @defaultValue `[]` (all paths allowed)
+   */
+  allowedGlobs?: string[];
+
+  /**
+   * Tool name allowlist. Tools not in this list are documented but not enforced
+   * (enforcement is structural via the `tools` array on the Agent).
+   *
+   * @defaultValue `[]` (all tools allowed)
+   */
+  allowedTools?: string[];
+
+  /**
+   * Disable tracing to conduit.db.
+   *
+   * @defaultValue `false`
+   */
+  tracingDisabled?: boolean;
+
+  /**
+   * Agent display name used as the CANT persona.
+   */
+  agentName?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const MODEL_LEAD = 'gpt-4.1';
+const MODEL_WORKER = 'gpt-4.1-mini';
+
+// ---------------------------------------------------------------------------
+// Provider
+// ---------------------------------------------------------------------------
+
+/**
+ * Spawn provider for the OpenAI Agents SDK.
+ *
+ * Spawns SDK-backed agent runs for a given `SpawnContext`. The run is
+ * awaited synchronously and the result mapped to a `SpawnResult` with
+ * `status: 'completed'` or `status: 'failed'`. In-flight runs are tracked
+ * by instance ID so `listRunning()` and `terminate()` work correctly.
+ *
+ * @remarks
+ * The provider creates a fresh `Runner` per spawn so that `RunConfig`
+ * settings do not bleed across parallel spawns. Trace processors are
+ * registered globally via `addTraceProcessor` and removed by disabling
+ * tracing when the option is set.
+ *
+ * @example
+ * ```typescript
+ * const provider = new OpenAiSdkSpawnProvider();
+ * const result = await provider.spawn({
+ *   taskId: 'T582',
+ *   prompt: 'Implement feature X',
+ *   options: { tier: 'lead', handoffs: ['worker-read', 'worker-write'] },
+ * });
+ * console.log(result.status); // 'completed'
+ * ```
+ */
+export class OpenAiSdkSpawnProvider implements AdapterSpawnProvider {
+  /** Currently running instance IDs (completed runs are removed). */
+  private readonly runningInstances = new Set<string>();
+
+  /**
+   * Check whether the OpenAI SDK can spawn in the current environment.
+   *
+   * Requires `OPENAI_API_KEY` to be set. Does not make a network call.
+   *
+   * @returns `true` when `OPENAI_API_KEY` is present in the environment.
+   */
+  async canSpawn(): Promise<boolean> {
+    return typeof process.env.OPENAI_API_KEY === 'string' && process.env.OPENAI_API_KEY.length > 0;
+  }
+
+  /**
+   * Spawn a subagent via the OpenAI Agents SDK runner.
+   *
+   * Awaits the run to completion and returns a fully-resolved `SpawnResult`.
+   *
+   * @param context - Spawn context with task ID, prompt, and options.
+   * @returns Resolved spawn result with `status: 'completed'` or `'failed'`.
+   */
+  async spawn(context: SpawnContext): Promise<SpawnResult> {
+    const instanceId = `openai-sdk-${Date.now()}-${Math.random().toString(36).substring(2, 9)}`;
+    const startTime = new Date().toISOString();
+
+    this.runningInstances.add(instanceId);
+
+    try {
+      const opts = this.parseOptions(context.options);
+
+      // Enrich prompt with CANT bundle (best-effort, same pattern as Claude Code provider).
+      let finalPrompt = context.prompt;
+      try {
+        const { buildCantEnrichedPrompt } = await import('../../cant-context.js');
+        finalPrompt = await buildCantEnrichedPrompt({
+          projectDir: context.workingDirectory ?? process.cwd(),
+          basePrompt: context.prompt,
+          agentName: opts.agentName,
+        });
+      } catch {
+        // CANT enrichment unavailable — use raw prompt.
+      }
+
+      // Build guardrails from ACL options.
+      const guardrails = buildDefaultGuardrails(opts.allowedGlobs ?? [], opts.allowedTools ?? []);
+
+      // Derive model from tier when not explicitly set.
+      const model = opts.model ?? this.modelForTier(opts.tier ?? 'worker');
+
+      // Build agent topology (lead + workers, or standalone worker).
+      const agent = buildAgentTopology({
+        instructions: finalPrompt,
+        model,
+        tier: opts.tier ?? 'worker',
+        handoffNames: opts.handoffs ?? [],
+        guardrails,
+      });
+
+      // Register trace processor globally (default-on).
+      // The SDK uses global processor registration via addTraceProcessor().
+      let traceProcessor: CleoConduitTraceProcessor | undefined;
+      if (!opts.tracingDisabled) {
+        traceProcessor = new CleoConduitTraceProcessor(context.taskId);
+        addTraceProcessor(traceProcessor);
+      } else {
+        setTracingDisabled(true);
+      }
+
+      // Build OpenAI model provider and runner.
+      const modelProvider = new OpenAIProvider();
+      const runner = new Runner({ modelProvider });
+
+      // Run the agent — no extra options needed beyond what is set on the runner.
+      const runResult = await runner.run(agent, finalPrompt);
+
+      // Restore tracing state if we disabled it for this spawn.
+      if (opts.tracingDisabled) {
+        setTracingDisabled(false);
+      }
+
+      const finalOutput =
+        typeof runResult.finalOutput === 'string'
+          ? runResult.finalOutput
+          : JSON.stringify(runResult.finalOutput);
+
+      this.runningInstances.delete(instanceId);
+
+      return mapSdkRunOutcome(instanceId, context.taskId, 'openai-sdk', startTime, {
+        finalOutput,
+        succeeded: true,
+      });
+    } catch (error: unknown) {
+      this.runningInstances.delete(instanceId);
+
+      return mapSdkRunOutcome(instanceId, context.taskId, 'openai-sdk', startTime, {
+        finalOutput: '',
+        succeeded: false,
+        errorMessage: getErrorMessage(error),
+      });
+    }
+  }
+
+  /**
+   * List currently running OpenAI SDK agent instances.
+   *
+   * @returns Array of in-progress spawn results.
+   */
+  async listRunning(): Promise<SpawnResult[]> {
+    return [...this.runningInstances].map((instanceId) => ({
+      instanceId,
+      taskId: 'unknown',
+      providerId: 'openai-sdk',
+      status: 'running' as const,
+      startTime: new Date().toISOString(),
+    }));
+  }
+
+  /**
+   * Terminate a running spawn by instance ID.
+   *
+   * The OpenAI SDK runner does not support external termination of in-flight
+   * runs; this method removes the instance from the tracking set so it will
+   * no longer appear in `listRunning()`.
+   *
+   * @param instanceId - ID of the spawn instance to terminate.
+   */
+  async terminate(instanceId: string): Promise<void> {
+    this.runningInstances.delete(instanceId);
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Parse and validate `SpawnContext.options` into typed `OpenAiSdkSpawnOptions`.
+   *
+   * Unknown fields are silently ignored.
+   */
+  private parseOptions(raw?: Record<string, unknown>): OpenAiSdkSpawnOptions {
+    if (!raw) return {};
+
+    const opts: OpenAiSdkSpawnOptions = {};
+
+    if (typeof raw.model === 'string') opts.model = raw.model;
+    if (raw.tier === 'lead' || raw.tier === 'worker' || raw.tier === 'orchestrator') {
+      opts.tier = raw.tier;
+    }
+    if (Array.isArray(raw.handoffs) && raw.handoffs.every((h) => typeof h === 'string')) {
+      opts.handoffs = raw.handoffs as string[];
+    }
+    if (Array.isArray(raw.allowedGlobs) && raw.allowedGlobs.every((g) => typeof g === 'string')) {
+      opts.allowedGlobs = raw.allowedGlobs as string[];
+    }
+    if (Array.isArray(raw.allowedTools) && raw.allowedTools.every((t) => typeof t === 'string')) {
+      opts.allowedTools = raw.allowedTools as string[];
+    }
+    if (typeof raw.tracingDisabled === 'boolean') opts.tracingDisabled = raw.tracingDisabled;
+    if (typeof raw.agentName === 'string') opts.agentName = raw.agentName;
+
+    return opts;
+  }
+
+  /**
+   * Derive the default model for a given tier.
+   *
+   * @param tier - Agent tier.
+   * @returns Model identifier string.
+   */
+  private modelForTier(tier: 'lead' | 'worker' | 'orchestrator'): string {
+    return tier === 'worker' ? MODEL_WORKER : MODEL_LEAD;
+  }
+}

package/src/providers/openai-sdk/tracing.ts

@@ -0,0 +1,175 @@
+/**
+ * OpenAI Agents SDK trace processor that writes spans to conduit.db.
+ *
+ * `CleoConduitTraceProcessor` implements the SDK `TracingProcessor` interface.
+ * On every span end it serialises the span and writes a structured event to
+ * conduit.db via the shared `conduit-trace-writer` transport layer.
+ *
+ * Tracing is on by default for all OpenAI SDK spawns. Set
+ * `options.tracingDisabled = true` in `SpawnContext.options` to opt out when
+ * conduit is unavailable.
+ *
+ * @task T582
+ */
+
+import type { Span, SpanData, Trace, TracingProcessor } from '@openai/agents';
+import type { ConduitSpanEvent } from '../shared/conduit-trace-writer.js';
+import { writeSpanBatchToConduit } from '../shared/conduit-trace-writer.js';
+
+// ---------------------------------------------------------------------------
+// Processor
+// ---------------------------------------------------------------------------
+
+/**
+ * CLEO trace processor that persists OpenAI Agents SDK spans to conduit.db.
+ *
+ * Implements the `TracingProcessor` interface from `@openai/agents-core`.
+ * Each `onSpanEnd` call extracts span metadata and enqueues a write to
+ * conduit via the shared `conduit-trace-writer` module. Writes are
+ * fire-and-forget — failures are logged but never propagated to the caller.
+ *
+ * @remarks
+ * `onTraceEnd` performs a batch flush of any buffered spans. Individual
+ * `onSpanEnd` calls also write immediately so spans are not lost if the run
+ * is interrupted.
+ *
+ * @example
+ * ```typescript
+ * import { addTraceProcessor } from '@openai/agents';
+ * import { CleoConduitTraceProcessor } from './tracing.js';
+ *
+ * const processor = new CleoConduitTraceProcessor('T582');
+ * addTraceProcessor(processor);
+ * ```
+ */
+export class CleoConduitTraceProcessor implements TracingProcessor {
+  /** CLEO task ID included in every span event for correlation. */
+  private readonly taskId: string;
+
+  /** Pending span events buffered within the current trace. */
+  private pendingEvents: ConduitSpanEvent[] = [];
+
+  /**
+   * @param taskId - CLEO task ID to attach to every written span.
+   */
+  constructor(taskId: string) {
+    this.taskId = taskId;
+  }
+
+  /**
+   * Called when a new trace starts. Resets the pending event buffer.
+   *
+   * @param _trace - The trace that just started (unused).
+   */
+  async onTraceStart(_trace: Trace): Promise<void> {
+    this.pendingEvents = [];
+  }
+
+  /**
+   * Called when a trace ends. Flushes all pending span events to conduit.
+   *
+   * @param _trace - The trace that just ended (unused — spans were captured via `onSpanEnd`).
+   */
+  async onTraceEnd(_trace: Trace): Promise<void> {
+    if (this.pendingEvents.length > 0) {
+      await writeSpanBatchToConduit(this.pendingEvents);
+      this.pendingEvents = [];
+    }
+  }
+
+  /**
+   * Called when a new span starts. No-op — we capture on end to have full timing.
+   *
+   * @param _span - The span that just started (unused).
+   */
+  async onSpanStart(_span: Span<SpanData>): Promise<void> {
+    // Capture on end so startedAt / endedAt are both populated.
+  }
+
+  /**
+   * Called when a span ends. Serialises and writes the span to conduit.
+   *
+   * @param span - The completed span from the SDK.
+   */
+  async onSpanEnd(span: Span<SpanData>): Promise<void> {
+    const event = this.extractSpanEvent(span);
+    if (event) {
+      this.pendingEvents.push(event);
+      // Also write immediately to survive partial run interruptions.
+      await writeSpanBatchToConduit([event]);
+    }
+  }
+
+  /**
+   * Called during graceful shutdown. Flushes any remaining pending events.
+   *
+   * @param _timeout - Shutdown timeout in milliseconds (unused).
+   */
+  async shutdown(_timeout?: number): Promise<void> {
+    if (this.pendingEvents.length > 0) {
+      await writeSpanBatchToConduit(this.pendingEvents);
+      this.pendingEvents = [];
+    }
+  }
+
+  /**
+   * Force-flush all pending span events to conduit immediately.
+   */
+  async forceFlush(): Promise<void> {
+    if (this.pendingEvents.length > 0) {
+      await writeSpanBatchToConduit(this.pendingEvents);
+      this.pendingEvents = [];
+    }
+  }
+
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+
+  /**
+   * Extract a {@link ConduitSpanEvent} from an SDK span, or `null` if the
+   * span cannot be meaningfully serialised.
+   *
+   * @param span - The SDK span to serialise.
+   * @returns A conduit span event or `null`.
+   */
+  private extractSpanEvent(span: Span<SpanData>): ConduitSpanEvent | null {
+    const spanId =
+      span.spanId ?? `span-${Date.now()}-${Math.random().toString(36).substring(2, 7)}`;
+
+    // Guard against malformed/empty spans (e.g. in unit tests with minimal mocks).
+    if (!span.spanData) return null;
+
+    const data = span.spanData;
+    const spanType = data.type;
+
+    // Extract agent name from span data shape based on type.
+    let agentName = 'unknown';
+    let handoffTarget: string | undefined;
+
+    if (data.type === 'agent') {
+      agentName = data.name;
+    } else if (data.type === 'handoff') {
+      agentName = data.from_agent ?? 'unknown';
+      handoffTarget = data.to_agent ?? undefined;
+    } else if (data.type === 'function') {
+      agentName = data.name;
+    }
+
+    const startTime = span.startedAt ?? new Date().toISOString();
+    const endTime = span.endedAt ?? new Date().toISOString();
+
+    return {
+      spanId,
+      taskId: this.taskId,
+      agentName,
+      spanType,
+      startTime,
+      endTime,
+      handoffTarget,
+      metadata: {
+        rawSpanData: data,
+      },
+    };
+  }
+}

package/src/providers/shared/conduit-trace-writer.ts

@@ -0,0 +1,101 @@
+/**
+ * Shared conduit trace writer for SDK-backed providers.
+ *
+ * Writes structured span events to conduit.db via the CLEO transport layer.
+ * Both T581 (Claude SDK) and T582 (OpenAI SDK) use this module so the
+ * conduit write path stays DRY.
+ *
+ * The writer is fire-and-forget: if conduit is unavailable, write failures are
+ * silently swallowed so that missing tracing never breaks agent execution.
+ *
+ * @task T582
+ */
+
+/**
+ * A single normalised span event written to conduit.
+ *
+ * @remarks
+ * This shape is intentionally minimal — only fields that both SDK providers
+ * can populate consistently are required. Provider-specific fields go into
+ * the `metadata` bag.
+ */
+export interface ConduitSpanEvent {
+  /** Unique identifier for this span (from the SDK). */
+  spanId: string;
+  /** The task ID this span belongs to. */
+  taskId: string;
+  /** The name of the agent that produced this span. */
+  agentName: string;
+  /** Type of span: `'agent'`, `'function'`, `'handoff'`, `'generation'`, etc. */
+  spanType: string;
+  /** ISO timestamp when the span started. */
+  startTime: string;
+  /** ISO timestamp when the span ended. */
+  endTime: string;
+  /** Optional tool name for function/tool spans. */
+  toolName?: string;
+  /** Optional handoff target agent name. */
+  handoffTarget?: string;
+  /** Extra provider-specific metadata. */
+  metadata?: Record<string, unknown>;
+}
+
+/** Conduit write result — only used internally for error handling. */
+interface WriteResult {
+  written: boolean;
+  error?: string;
+}
+
+/**
+ * Write a single span event to conduit via `cleo` CLI transport.
+ *
+ * Falls back gracefully when conduit is unavailable. All errors are caught
+ * and returned in the result rather than thrown.
+ *
+ * @param event - The span event to persist.
+ * @returns Result indicating whether the write succeeded.
+ *
+ * @remarks
+ * The current implementation writes to conduit using the `cleo conduit send`
+ * CLI command. This keeps the trace writer free of direct DB dependencies and
+ * consistent with the no-direct-SQLite rule (ADR).
+ *
+ * When conduit grows a native TS API this writer can be updated without
+ * changing caller code.
+ */
+export async function writeSpanToConduit(event: ConduitSpanEvent): Promise<WriteResult> {
+  try {
+    const { exec } = await import('node:child_process');
+    const { promisify } = await import('node:util');
+    const execAsync = promisify(exec);
+
+    const payload = JSON.stringify({
+      type: 'agent_span',
+      version: '1',
+      ...event,
+    });
+
+    // Use the CLEO conduit send command which handles DB access via the
+    // business logic layer (no direct SQLite per ADR-013 §9).
+    await execAsync(`cleo conduit send --type agent_span --payload ${JSON.stringify(payload)}`);
+    return { written: true };
+  } catch (err: unknown) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { written: false, error: message };
+  }
+}
+
+/**
+ * Write multiple span events to conduit, swallowing individual write failures.
+ *
+ * @param events - Array of span events to persist.
+ * @returns Number of events successfully written.
+ */
+export async function writeSpanBatchToConduit(events: ConduitSpanEvent[]): Promise<number> {
+  let written = 0;
+  for (const event of events) {
+    const result = await writeSpanToConduit(event);
+    if (result.written) written++;
+  }
+  return written;
+}

package/src/providers/shared/sdk-result-mapper.ts

@@ -0,0 +1,83 @@
+/**
+ * Shared SDK result mapper for CLEO spawn providers.
+ *
+ * Normalises provider-specific run results (OpenAI Agents SDK, Claude Agent SDK)
+ * into the canonical {@link SpawnResult} contract used by CLEO orchestration.
+ *
+ * Both T581 (Claude SDK) and T582 (OpenAI SDK) import from this module so the
+ * mapping logic stays DRY.
+ *
+ * @task T582
+ */
+
+import type { SpawnResult } from '@cleocode/contracts';
+
+/**
+ * Raw run outcome from any SDK provider, normalised before mapping.
+ *
+ * @remarks
+ * Both `@anthropic-ai/claude-agent-sdk` and `@openai/agents` surface a
+ * `finalOutput` string plus an optional error. This interface captures the
+ * minimal shared shape so the mapper stays provider-agnostic.
+ */
+export interface RawSdkRunOutcome {
+  /** Final text produced by the agent run. Empty string when the run failed. */
+  finalOutput: string;
+  /** True when the run completed without error. */
+  succeeded: boolean;
+  /** Human-readable error message when `succeeded` is false. */
+  errorMessage?: string;
+  /** Exit / stop reason surfaced by the SDK (optional). */
+  stopReason?: string;
+}
+
+/**
+ * Map a raw SDK run outcome to the canonical CLEO {@link SpawnResult}.
+ *
+ * @param instanceId - Unique identifier for this spawn instance.
+ * @param taskId - CLEO task ID associated with the run.
+ * @param providerId - Identifier of the provider that performed the run (e.g. `'openai-sdk'`).
+ * @param startTime - ISO timestamp captured just before the run was started.
+ * @param outcome - Normalised run outcome from the SDK provider.
+ * @returns A fully-populated {@link SpawnResult} ready for return from `spawn()`.
+ *
+ * @example
+ * ```typescript
+ * const result = mapSdkRunOutcome('openai-sdk-123', 'T582', 'openai-sdk', start, {
+ *   finalOutput: 'Done',
+ *   succeeded: true,
+ * });
+ * // result.status === 'completed'
+ * ```
+ */
+export function mapSdkRunOutcome(
+  instanceId: string,
+  taskId: string,
+  providerId: string,
+  startTime: string,
+  outcome: RawSdkRunOutcome,
+): SpawnResult {
+  const endTime = new Date().toISOString();
+
+  if (outcome.succeeded) {
+    return {
+      instanceId,
+      taskId,
+      providerId,
+      status: 'completed',
+      output: outcome.finalOutput,
+      startTime,
+      endTime,
+    };
+  }
+
+  return {
+    instanceId,
+    taskId,
+    providerId,
+    status: 'failed',
+    startTime,
+    endTime,
+    error: outcome.errorMessage ?? 'SDK run failed without a message',
+  };
+}