@principles/core 1.73.0

package/dist/runtime-v2/adapter/pi-ai-runtime-adapter.js

@@ -0,0 +1,1109 @@
+/**
+ * PiAiRuntimeAdapter — PDRuntimeAdapter implementation for direct LLM completion.
+ *
+ * Uses @mariozechner/pi-ai to call LLM providers directly, bypassing the OpenClaw CLI.
+ * Solves the m8-03 UAT blocker where the main agent takes >300s.
+ *
+ * One-shot run: startRun() calls pi-ai complete(), blocks until LLM responds,
+ * stores output in memory. pollRun()/fetchOutput() operate on stored state.
+ *
+ * Error mapping:
+ *   AbortError (signal.timeout) → timeout
+ *   JSON extraction failure → output_invalid
+ *   DiagnosticianOutputV1Schema validation failure → output_invalid
+ *   Missing apiKeyEnv → runtime_unavailable
+ *   Retries exhausted → execution_failed
+ */
+import { getModel, getProviders, completeSimple } from '@mariozechner/pi-ai';
+import { Value } from '@sinclair/typebox/value';
+import { PDRuntimeError } from '../error-categories.js';
+import { extractJsonObject } from './json-extractor.js';
+import { DiagnosticianOutputV1Schema } from '../diagnostician-output.js';
+import { DreamerOutputV1Schema } from '../internalization/dreamer-output.js';
+import { PhilosopherOutputV1Schema } from '../internalization/philosopher-output.js';
+import { ScribeOutputV1Schema } from '../internalization/scribe-output.js';
+import { ArtificerOutputV1Schema } from '../internalization/artificer-output.js';
+import { EvaluatorOutputV1Schema } from '../internalization/evaluator-output.js';
+import { RolloutReviewerOutputV1Schema } from '../internalization/rollout-reviewer-output.js';
+import { TrainerOutputV1Schema } from '../internalization/trainer-output.js';
+import { EmpathyObserverOutputV1Schema } from '../observer/empathy-observer.js';
+import { CorrectionObserverOutputV1Schema } from '../observer/correction-observer.js';
+import { storeEmitter } from '../store/event-emitter.js';
+import { attemptStructuredOutputRepair, deriveSchemaSummary } from './structured-output-repair.js';
+import { formatValidationErrorEntry, safeStringifyPreview, stripLineageFields } from './output-repair-contract.js';
+import { RECORD_DIAGNOSIS_V1_TOOL } from './tools/diagnostician-tool.js';
+/**
+ * Resolve a pi-ai Model from dynamic config values.
+ *
+ * For built-in providers (openrouter, anthropic, etc.), uses getModel().
+ * For custom providers (e.g., xiaomi-coding with custom baseUrl), creates
+ * a Model<Api> object directly. This enables pi-ai to call OpenAI-compatible
+ * endpoints that aren't in pi-ai's built-in provider registry.
+ */
+function resolveModel(provider, modelId, baseUrl) {
+    const knownProviders = getProviders();
+    if (knownProviders.includes(provider) && !baseUrl) {
+        // Built-in provider — use getModel()
+        // @ts-expect-error — getModel requires literal model ID types; runtime strings from config are acceptable
+        return getModel(provider, modelId);
+    }
+    // Custom provider — baseUrl is required
+    if (!baseUrl) {
+        throw new PDRuntimeError('runtime_unavailable', `Provider '${provider}' is not a built-in pi-ai provider and requires a custom baseUrl. ` +
+            `Pass --baseUrl <url> or add 'baseUrl' to your workflows.yaml policy.`);
+    }
+    // Custom provider with baseUrl — construct Model object directly
+    // Default to openai-completions API for custom OpenAI-compatible endpoints
+    const model = {
+        id: modelId,
+        name: modelId,
+        api: 'openai-completions',
+        provider,
+        baseUrl,
+        reasoning: false,
+        input: ['text'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 32000,
+        compat: {
+            supportsStore: false,
+            supportsDeveloperRole: false,
+            supportsReasoningEffort: false,
+            supportsUsageInStreaming: true,
+            maxTokensField: 'max_tokens',
+            requiresToolResultName: false,
+            requiresAssistantAfterToolResult: false,
+            requiresThinkingAsText: false,
+            requiresReasoningContentOnAssistantMessages: false,
+            thinkingFormat: 'deepseek',
+            supportsStrictMode: false,
+        },
+    };
+    return model;
+}
+/**
+ * Detection for abort/timeout errors from provider SDKs.
+ *
+ * Checks:
+ *   1. AbortSignal already aborted
+ *   2. DOMException AbortError (native fetch/Node abort)
+ *   3. Error objects with name === 'AbortError' (some SDKs)
+ *   4. Non-PDRuntimeError Error with "timeout" or "abort" in message
+ *      (provider SDKs that throw plain Error on timeout)
+ *
+ * Excludes PDRuntimeError to avoid false positives from our own wrapped
+ * error messages that may contain "timed out".
+ */
+function isObjectWithKey(obj, key) {
+    return typeof obj === 'object' && obj !== null && Object.hasOwn(obj, key);
+}
+function isAbortError(err, signal) {
+    if (signal?.aborted)
+        return true;
+    if (err instanceof DOMException && err.name === 'AbortError')
+        return true;
+    if (isObjectWithKey(err, 'name')) {
+        const rawName = err.name;
+        if (typeof rawName === 'string' && rawName === 'AbortError') {
+            return true;
+        }
+    }
+    if (err instanceof Error && !(err instanceof PDRuntimeError) && (/abort/i.test(err.message) || /timeout/i.test(err.message)))
+        return true;
+    return false;
+}
+function classifyFailure(err, signal) {
+    if (signal?.aborted) {
+        return {
+            category: 'timeout',
+            classification: 'client_timeout_budget_exhausted',
+        };
+    }
+    let errorMsg = '';
+    let name = '';
+    if (err instanceof Error) {
+        const { message, name: errName } = err;
+        errorMsg = message;
+        name = errName;
+    }
+    else if (typeof err === 'object' && err !== null) {
+        if (isObjectWithKey(err, 'message')) {
+            const rawMessage = err.message;
+            if (typeof rawMessage === 'string') {
+                errorMsg = rawMessage;
+            }
+        }
+        if (isObjectWithKey(err, 'name')) {
+            const rawName = err.name;
+            if (typeof rawName === 'string') {
+                name = rawName;
+            }
+        }
+    }
+    else {
+        errorMsg = String(err);
+    }
+    const isAbort = name === 'AbortError' || (err instanceof DOMException && err.name === 'AbortError');
+    const hasTimeoutKeywords = /timeout|timed\s*out/i.test(errorMsg) || /abort/i.test(errorMsg);
+    if (isAbort || hasTimeoutKeywords) {
+        return {
+            category: 'timeout',
+            classification: 'provider_transient_timeout',
+        };
+    }
+    return {
+        category: 'execution_failed',
+        classification: 'not_applicable',
+    };
+}
+/**
+ * Extract text content from an AssistantMessage, or throw PDRuntimeError.
+ *
+ * pi-ai complete() may RESOLVE (not reject) with stopReason:'error' when
+ * the provider returns an error response (e.g., 401, rate limit).
+ * This helper normalizes those resolved-error responses into PDRuntimeError
+ * so downstream code never sees a "successful" response that is actually broken.
+ *
+ * Error classification:
+ *   stopReason:'aborted'                              → timeout
+ *   stopReason:'error' + timeout/abort in errorMessage → timeout
+ *   stopReason:'error' + other                        → execution_failed
+ *   no text content block                              → output_invalid
+ */
+function extractAssistantTextOrThrow(response, signal) {
+    // Handle resolved-error responses from pi-ai
+    if (response.stopReason === 'error' || response.stopReason === 'aborted') {
+        const rawMessage = response.errorMessage ?? 'unknown provider error';
+        // Truncate to 300 chars to avoid leaking huge payloads into logs/telemetry
+        const boundedMessage = rawMessage.length > 300 ? rawMessage.substring(0, 300) + '...' : rawMessage;
+        const isTimeout = response.stopReason === 'aborted'
+            || signal?.aborted
+            || /timeout|timed\s*out/i.test(rawMessage)
+            || /abort/i.test(rawMessage);
+        throw new PDRuntimeError(isTimeout ? 'timeout' : 'execution_failed', isTimeout
+            ? `LLM request timed out: ${boundedMessage}`
+            : `LLM execution failed: ${boundedMessage}`);
+    }
+    // Find text content (may be mixed with thinking content from reasoning-enabled models)
+    const textContent = response.content.find(c => c.type === 'text' && c.text && c.text.trim().length > 0);
+    if (!textContent || textContent.type !== 'text' || !textContent.text) {
+        throw new PDRuntimeError('output_invalid', `No text content in LLM response. Content types: ${response.content.map(c => c.type).join(', ')}`);
+    }
+    return textContent.text;
+}
+const OUTPUT_SCHEMA_REGISTRY = new Map([
+    ['diagnostician-output-v1', DiagnosticianOutputV1Schema],
+    ['dreamer-output-v1', DreamerOutputV1Schema],
+    ['philosopher-output-v1', PhilosopherOutputV1Schema],
+    ['scribe-output-v1', ScribeOutputV1Schema],
+    ['artificer-output-v1', ArtificerOutputV1Schema],
+    ['evaluator-output-v1', EvaluatorOutputV1Schema],
+    ['rollout-reviewer-output-v1', RolloutReviewerOutputV1Schema],
+    ['trainer-output-v1', TrainerOutputV1Schema],
+    ['empathy-observer-output-v1', EmpathyObserverOutputV1Schema],
+    ['correction-observer-output-v1', CorrectionObserverOutputV1Schema],
+]);
+export class PiAiRuntimeAdapter {
+    config;
+    runs = new Map();
+    eventEmitter;
+    runtimeKind = 'pi-ai';
+    defaultCapabilities = {
+        supportsStructuredJsonOutput: true,
+        supportsToolUse: false,
+        supportsWorkingDirectory: false,
+        supportsModelSelection: true,
+        supportsLongRunningSessions: false,
+        supportsCancellation: true,
+        supportsArtifactWriteBack: false,
+        supportsConcurrentRuns: false,
+        supportsStreaming: false,
+    };
+    constructor(config) {
+        this.config = config;
+        this.eventEmitter = config.eventEmitter ?? storeEmitter;
+    }
+    kind() {
+        return this.runtimeKind;
+    }
+    async getCapabilities() {
+        return this.defaultCapabilities;
+    }
+    /**
+     * Three-stage health probe (per M6 lesson: binary/list-only checks are fake probes).
+     *
+     * 1. apiKey exists in environment
+     * 2. getModel validates without throwing
+     * 3. Minimal complete probe with {"ok":true} verification
+     */
+    async healthCheck() {
+        const lastCheckedAt = new Date().toISOString();
+        // Stage 1: apiKey exists
+        const apiKey = process.env[this.config.apiKeyEnv];
+        if (!apiKey) {
+            return {
+                healthy: false,
+                degraded: false,
+                warnings: [`API key not found in env: ${this.config.apiKeyEnv}`],
+                lastCheckedAt,
+            };
+        }
+        // Stage 2+3: getModel valid + minimal complete probe
+        try {
+            const model = resolveModel(this.config.provider, this.config.model, this.config.baseUrl);
+            const timeoutMs = this.config.timeoutMs ?? 120_000;
+            const signal = AbortSignal.timeout(timeoutMs);
+            const probeContext = {
+                messages: [{
+                        role: 'user',
+                        content: 'Reply with {"ok":true} only.',
+                        timestamp: Date.now(),
+                    }],
+            };
+            const response = await completeSimple(model, probeContext, {
+                signal,
+                apiKey,
+                timeoutMs,
+                maxRetries: 0,
+            });
+            // extractAssistantTextOrThrow normalizes resolved-error responses
+            const text = extractAssistantTextOrThrow(response, signal);
+            const parsed = extractJsonObject(text);
+            if (typeof parsed !== 'object' ||
+                parsed === null ||
+                !('ok' in parsed) ||
+                parsed.ok !== true) {
+                return {
+                    healthy: false,
+                    degraded: true,
+                    warnings: [`probe returned unexpected result: ${text.substring(0, 200)}`],
+                    lastCheckedAt,
+                };
+            }
+        }
+        catch (err) {
+            // PDRuntimeError from extractAssistantTextOrThrow (timeout/execution_failed)
+            // or thrown errors from complete() (AbortError, network, etc.)
+            if (err instanceof PDRuntimeError && err.category === 'timeout') {
+                return {
+                    healthy: false,
+                    degraded: true,
+                    warnings: [`probe timed out: ${err.message}`],
+                    lastCheckedAt,
+                };
+            }
+            if (err instanceof PDRuntimeError) {
+                return {
+                    healthy: false,
+                    degraded: err.category === 'output_invalid',
+                    warnings: [`probe failed: ${err.message}`],
+                    lastCheckedAt,
+                };
+            }
+            if (isAbortError(err)) {
+                return {
+                    healthy: false,
+                    degraded: true,
+                    warnings: ['probe timed out'],
+                    lastCheckedAt,
+                };
+            }
+            return {
+                healthy: false,
+                degraded: false,
+                warnings: [`probe failed: ${err instanceof Error ? err.message : String(err)}`],
+                lastCheckedAt,
+            };
+        }
+        return { healthy: true, degraded: false, warnings: [], lastCheckedAt };
+    }
+    /**
+     * One-shot run: call LLM via pi-ai complete(), parse and validate output.
+     * Blocks until LLM responds (or times out). Run is terminal on return.
+     *
+     * Timeout priority: input.timeoutMs (from runner) > this.config.timeoutMs (from workflows.yaml) > 300_000 (default)
+     * The resolved effectiveTimeoutMs is passed through to completeWithRetry and pi-ai complete()
+     * so that the provider request timeout always matches the runner's intent.
+     */
+    async startRun(input) {
+        const runId = crypto.randomUUID();
+        const startedAt = new Date().toISOString();
+        // Read API key
+        const apiKey = process.env[this.config.apiKeyEnv];
+        if (!apiKey) {
+            throw new PDRuntimeError('runtime_unavailable', `API key not found in env: ${this.config.apiKeyEnv}`);
+        }
+        // Create run state immediately — failed runs are always trackable
+        const runState = {
+            runId,
+            startedAt,
+            endedAt: startedAt, // will be updated on completion
+            status: 'failed', // default until succeeded
+        };
+        this.runs.set(runId, runState);
+        // AbortSignal.timeout for clean timeout control
+        // Priority: input.timeoutMs (runner) > config.timeoutMs (workflows.yaml) > 300_000 (default)
+        const effectiveTimeoutMs = input.timeoutMs ?? this.config.timeoutMs ?? 300_000;
+        const timeoutSource = input.timeoutMs !== undefined ? 'runner_input'
+            : this.config.timeoutMs !== undefined ? 'adapter_config'
+                : 'default';
+        const signal = AbortSignal.timeout(effectiveTimeoutMs);
+        // Build pi-ai Context from inputPayload
+        const messageContent = typeof input.inputPayload === 'string'
+            ? input.inputPayload
+            : JSON.stringify(input.inputPayload);
+        const userMessage = {
+            role: 'user',
+            content: messageContent,
+            timestamp: Date.now(),
+        };
+        const context = { messages: [userMessage] };
+        // Get model
+        const model = resolveModel(this.config.provider, this.config.model, this.config.baseUrl);
+        // Emit runtime_invocation_started telemetry
+        this.eventEmitter.emitTelemetry({
+            eventType: 'runtime_invocation_started',
+            traceId: input.taskRef?.taskId ?? runId,
+            timestamp: startedAt,
+            sessionId: 'pi-ai-adapter',
+            agentId: 'pi-ai-adapter',
+            payload: {
+                runId,
+                runtimeKind: 'pi-ai',
+                runnerKind: input.agentSpec.agentId,
+                provider: this.config.provider,
+                model: this.config.model,
+                timeoutMs: effectiveTimeoutMs,
+                timeoutSource,
+                outputSchemaRef: input.outputSchemaRef ?? 'unknown',
+            },
+        });
+        try {
+            // PRI-271 B3: Three-path fallback chain for structured output
+            const schemaRef = input.outputSchemaRef;
+            const schema = schemaRef ? OUTPUT_SCHEMA_REGISTRY.get(schemaRef) : undefined;
+            const strategy = this.config.outputPathStrategy ?? 'tool_call_first';
+            let validatedOutput = undefined;
+            const schemaSummary = (schema && schemaRef) ? deriveSchemaSummary(schema) : undefined;
+            // ── Path 1: Tool calling (PRI-271 B2) ──
+            if (strategy === 'tool_call_first' && schema && schemaRef) {
+                const toolResult = await this.tryToolCallPath({ model, baseContext: context, schemaRef, schema, signal, apiKey, effectiveTimeoutMs, input, runId });
+                if (toolResult.success && toolResult.output !== undefined) {
+                    validatedOutput = toolResult.output;
+                    this.emitOutputPathTelemetry({ runId, input, path: 'tool_call', fallbackReason: null });
+                }
+                else {
+                    this.emitOutputPathTelemetry({ runId, input, path: null, fallbackReason: toolResult.fallbackReason ?? 'provider_no_tool_use' });
+                }
+            }
+            // ── Path 2: JSON mode (PRI-271 B1) ──
+            if (!validatedOutput && (strategy === 'tool_call_first' || strategy === 'json_mode_first') && schema && schemaRef) {
+                const jsonResult = await this.tryJsonModePath({ model, baseContext: context, schemaRef, schema, signal, apiKey, effectiveTimeoutMs, input, runId });
+                if (jsonResult.success && jsonResult.output !== undefined) {
+                    validatedOutput = jsonResult.output;
+                    this.emitOutputPathTelemetry({ runId, input, path: 'json_object_mode', fallbackReason: null });
+                }
+                else {
+                    this.emitOutputPathTelemetry({ runId, input, path: null, fallbackReason: jsonResult.fallbackReason ?? 'json_parse_failed' });
+                }
+            }
+            // ── Path 3: Free-form + repair (current behavior, enhanced) ──
+            if (!validatedOutput) {
+                const response = await this.completeWithRetry(model, context, { signal, apiKey, effectiveTimeoutMs, timeoutSource, input, runId });
+                const text = extractAssistantTextOrThrow(response, signal);
+                let parsedOutput = extractJsonObject(text);
+                if (!parsedOutput) {
+                    this.eventEmitter.emitTelemetry({
+                        eventType: 'output_extraction_failed',
+                        traceId: input.taskRef?.taskId ?? runId,
+                        timestamp: new Date().toISOString(),
+                        sessionId: 'pi-ai-adapter',
+                        agentId: 'pi-ai-adapter',
+                        payload: {
+                            runId,
+                            runtimeKind: 'pi-ai',
+                            provider: this.config.provider,
+                            model: this.config.model,
+                            outputSchemaRef: input.outputSchemaRef ?? 'unknown',
+                            rawOutputPreview: text.slice(0, 500),
+                        },
+                    });
+                    throw new PDRuntimeError('output_invalid', 'No valid JSON found in LLM response');
+                }
+                if (schema && !Value.Check(schema, parsedOutput)) {
+                    // Schema validation failed — attempt repair with enhanced config (PRI-271 A1/A2/A3)
+                    const schemaErrors = [...Value.Errors(schema, parsedOutput)]
+                        .map(e => ({ path: e.path, message: e.message, value: e.value }));
+                    const validationErrorEntries = schemaErrors
+                        .slice(0, 10)
+                        .map(e => formatValidationErrorEntry(e.path, e.message, e.value));
+                    const rawOutputPreview = safeStringifyPreview(parsedOutput);
+                    this.eventEmitter.emitTelemetry({
+                        eventType: 'output_schema_invalid',
+                        traceId: input.taskRef?.taskId ?? runId,
+                        timestamp: new Date().toISOString(),
+                        sessionId: 'pi-ai-adapter',
+                        agentId: 'pi-ai-adapter',
+                        payload: {
+                            runId,
+                            runtimeKind: 'pi-ai',
+                            outputSchemaRef: schemaRef ?? 'unknown',
+                            provider: this.config.provider,
+                            model: this.config.model,
+                            rawOutputPreview,
+                            validationErrors: validationErrorEntries,
+                        },
+                    });
+                    const originalOutput = typeof parsedOutput === 'object' && parsedOutput !== null
+                        ? parsedOutput
+                        : undefined;
+                    const repairResult = await attemptStructuredOutputRepair(parsedOutput, schemaErrors, {
+                        llmCaller: (prompt) => this.repairLLMCall(model, prompt, { signal, apiKey }),
+                        schemaCheck: (value) => Value.Check(schema, value),
+                        schemaErrors: (value) => [...Value.Errors(schema, value)].map(e => ({ path: e.path, message: e.message, value: e.value })),
+                    }, {
+                        schemaRef: schemaRef ?? 'unknown',
+                        originalOutput,
+                        schemaSummary,
+                        maxRepairAttempts: this.config.maxRepairAttempts,
+                    });
+                    this.eventEmitter.emitTelemetry({
+                        eventType: 'output_repair_attempted',
+                        traceId: input.taskRef?.taskId ?? runId,
+                        timestamp: new Date().toISOString(),
+                        sessionId: 'pi-ai-adapter',
+                        agentId: 'pi-ai-adapter',
+                        payload: {
+                            runId,
+                            runtimeKind: 'pi-ai',
+                            outputSchemaRef: schemaRef ?? 'unknown',
+                            repaired: repairResult.repaired,
+                            attemptsUsed: repairResult.attemptsUsed,
+                            repairSummary: repairResult.repairSummary,
+                            repairAttempts: repairResult.repairAttempts,
+                            outputPath: 'free_form_with_repair',
+                        },
+                    });
+                    if (repairResult.repaired && repairResult.output) {
+                        parsedOutput = repairResult.output;
+                    }
+                    else {
+                        const evidencePack = {
+                            schemaRef: schemaRef ?? 'unknown',
+                            provider: this.config.provider,
+                            model: this.config.model,
+                            rawOutputPreview,
+                            validationErrors: validationErrorEntries,
+                            repairAttempts: repairResult.repairAttempts,
+                            finalFailureReason: 'repair_exhausted',
+                        };
+                        this.eventEmitter.emitTelemetry({
+                            eventType: 'output_repair_exhausted',
+                            traceId: input.taskRef?.taskId ?? runId,
+                            timestamp: new Date().toISOString(),
+                            sessionId: 'pi-ai-adapter',
+                            agentId: 'pi-ai-adapter',
+                            payload: {
+                                runId,
+                                runtimeKind: 'pi-ai',
+                                outputSchemaRef: schemaRef ?? 'unknown',
+                                provider: this.config.provider,
+                                model: this.config.model,
+                                rawOutputPreview,
+                                validationErrors: validationErrorEntries,
+                                repairAttempts: evidencePack.repairAttempts,
+                                finalFailureReason: evidencePack.finalFailureReason,
+                            },
+                        });
+                        throw new PDRuntimeError('output_invalid', `LLM output does not match ${schemaRef ?? 'unknown'} schema`, { evidencePack });
+                    }
+                }
+                // Lineage fields (taskId/sourcePainId/sourceTaskId/etc.) are
+                // intentionally stripped from LLM output. Downstream consumers
+                // (DiagnosticianRunner, committer) MUST get these values from
+                // RunnerContext / TaskRecord, never from validated output.
+                // This prevents LLM-supplied lineage from poisoning downstream
+                // commits (ERR-008 family). See PRI-272.
+                const protectedFreeForm = typeof parsedOutput === 'object' && parsedOutput !== null
+                    ? stripLineageFields(parsedOutput)
+                    : parsedOutput;
+                validatedOutput = protectedFreeForm;
+                this.emitOutputPathTelemetry({ runId, input, path: 'free_form_with_repair', fallbackReason: null });
+            }
+            // Update run state to succeeded
+            const endedAt = new Date().toISOString();
+            runState.status = 'succeeded';
+            runState.endedAt = endedAt;
+            runState.output = { runId, payload: validatedOutput };
+            // Emit runtime_invocation_succeeded telemetry
+            this.eventEmitter.emitTelemetry({
+                eventType: 'runtime_invocation_succeeded',
+                traceId: input.taskRef?.taskId ?? runId,
+                timestamp: endedAt,
+                sessionId: 'pi-ai-adapter',
+                agentId: 'pi-ai-adapter',
+                payload: {
+                    runId,
+                    runtimeKind: 'pi-ai',
+                },
+            });
+        }
+        catch (err) {
+            // Update run state to failed
+            const endedAt = new Date().toISOString();
+            runState.endedAt = endedAt;
+            const elapsedMs = Date.now() - Date.parse(startedAt);
+            const maxRetries = this.config.maxRetries ?? 2;
+            let timeoutClassification = 'not_applicable';
+            let providerEvidence = '';
+            let retryAttempt = 0;
+            if (err instanceof PDRuntimeError && err.details) {
+                const { details } = err;
+                if (isObjectWithKey(details, 'timeoutClassification')) {
+                    const { timeoutClassification: tc } = details;
+                    if (typeof tc === 'string')
+                        timeoutClassification = tc;
+                }
+                if (isObjectWithKey(details, 'providerEvidence')) {
+                    const { providerEvidence: pe } = details;
+                    if (typeof pe === 'string')
+                        providerEvidence = pe;
+                }
+                if (isObjectWithKey(details, 'retryAttempt')) {
+                    const { retryAttempt: ra } = details;
+                    if (typeof ra === 'number')
+                        retryAttempt = ra;
+                }
+            }
+            if (isAbortError(err, signal)) {
+                runState.status = 'timed_out';
+                runState.reason = `[timeout] LLM request timed out after ${effectiveTimeoutMs}ms (timeoutSource=${timeoutSource})`;
+                if (timeoutClassification === 'not_applicable') {
+                    timeoutClassification = signal?.aborted ? 'client_timeout_budget_exhausted' : 'provider_transient_timeout';
+                }
+                if (!providerEvidence) {
+                    providerEvidence = safeStringifyPreview(err, 300);
+                }
+            }
+            else if (err instanceof PDRuntimeError) {
+                runState.status = 'failed';
+                runState.reason = err.message;
+                if (err.category === 'timeout') {
+                    runState.status = 'timed_out';
+                    if (timeoutClassification === 'not_applicable') {
+                        timeoutClassification = 'provider_transient_timeout';
+                    }
+                }
+                if (!providerEvidence) {
+                    providerEvidence = safeStringifyPreview(err, 300);
+                }
+            }
+            else {
+                runState.status = 'failed';
+                runState.reason = err instanceof Error ? err.message : String(err);
+                providerEvidence = safeStringifyPreview(err, 300);
+            }
+            // Emit runtime_invocation_failed telemetry
+            const errorCategory = err instanceof PDRuntimeError ? err.category : 'execution_failed';
+            this.eventEmitter.emitTelemetry({
+                eventType: 'runtime_invocation_failed',
+                traceId: input.taskRef?.taskId ?? runId,
+                timestamp: endedAt,
+                sessionId: 'pi-ai-adapter',
+                agentId: 'pi-ai-adapter',
+                payload: {
+                    runId,
+                    runtimeKind: 'pi-ai',
+                    runnerKind: input.agentSpec.agentId,
+                    provider: this.config.provider,
+                    model: this.config.model,
+                    effectiveTimeoutMs,
+                    timeoutSource,
+                    elapsedMs,
+                    timeoutClassification,
+                    retryAttempt,
+                    maxRetries,
+                    providerEvidence,
+                    errorMessage: runState.reason,
+                    errorCategory,
+                    finalFailure: true,
+                },
+            });
+            // Re-throw PDRuntimeError as-is, wrap others
+            if (err instanceof PDRuntimeError) {
+                throw err;
+            }
+            throw new PDRuntimeError('execution_failed', `LLM completion failed: ${err instanceof Error ? err.message : String(err)}`, {
+                elapsedMs,
+                providerEvidence,
+            });
+        }
+        return { runId, runtimeKind: 'pi-ai', startedAt };
+    }
+    async pollRun(runId) {
+        const state = this.runs.get(runId);
+        if (!state) {
+            throw new PDRuntimeError('input_invalid', `Run ${runId} not found`);
+        }
+        return {
+            runId,
+            status: state.status,
+            startedAt: state.startedAt,
+            endedAt: state.endedAt,
+            reason: state.reason,
+        };
+    }
+    async cancelRun(runId) {
+        // One-shot mode: startRun() blocks until LLM responds, so cancel is always a no-op.
+        // The run is already terminal by the time cancelRun could be called.
+        const state = this.runs.get(runId);
+        if (state && state.status === 'succeeded') {
+            return;
+        }
+    }
+    async fetchOutput(runId) {
+        const state = this.runs.get(runId);
+        if (!state || !state.output) {
+            return null;
+        }
+        return state.output;
+    }
+    async fetchArtifacts(runId) {
+        // Artifact refs are not yet exposed by the pi-ai adapter.
+        // The DiagnosticianRunner stores artifacts via committer.writeArtifact() directly.
+        // Validate runId exists for API consistency with other methods.
+        if (!this.runs.has(runId)) {
+            throw new PDRuntimeError('input_invalid', `Run '${runId}' not found`);
+        }
+        return [];
+    }
+    // ── Private helpers ──
+    // ── PRI-271: Three-path output extraction ──
+    /**
+     * Path 1: Tool calling (PRI-271 B2).
+     *
+     * Passes `RECORD_DIAGNOSIS_V1_TOOL` via context.tools and injects
+     * `tool_choice: 'required'` via onPayload. If the provider supports tool
+     * calling, the response contains ToolCall content blocks with pre-parsed
+     * arguments that we validate against the schema.
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- stateless helper; kept as private method for cohesion
+    async tryToolCallPath(params) {
+        try {
+            const toolContext = {
+                ...params.baseContext,
+                tools: [RECORD_DIAGNOSIS_V1_TOOL],
+            };
+            const completeOptions = {
+                signal: params.signal,
+                apiKey: params.apiKey,
+                timeoutMs: params.effectiveTimeoutMs,
+                maxRetries: 0,
+                onPayload: (payload) => {
+                    if (typeof payload === 'object' && payload !== null) {
+                        const p = payload;
+                        p.tool_choice = 'required';
+                    }
+                    return payload;
+                },
+            };
+            const response = await completeSimple(params.model, toolContext, completeOptions);
+            if (response.stopReason !== 'toolUse') {
+                return { success: false, fallbackReason: 'provider_no_tool_use' };
+            }
+            const toolCallBlock = response.content.find((block) => typeof block === 'object' && block !== null && 'type' in block && block.type === 'toolCall');
+            if (!toolCallBlock) {
+                return { success: false, fallbackReason: 'tool_call_extraction_failed' };
+            }
+            const toolArgs = toolCallBlock.arguments;
+            if (!Value.Check(params.schema, toolArgs)) {
+                return { success: false, fallbackReason: 'tool_call_schema_invalid' };
+            }
+            // Lineage fields (taskId/sourcePainId/sourceTaskId/etc.) are
+            // intentionally stripped from LLM output. Downstream consumers
+            // (DiagnosticianRunner, committer) MUST get these values from
+            // RunnerContext / TaskRecord, never from validated output.
+            // This prevents LLM-supplied lineage from poisoning downstream
+            // commits (ERR-008 family). See PRI-271 D4 in PR description.
+            const protectedArgs = typeof toolArgs === 'object' && toolArgs !== null
+                ? stripLineageFields(toolArgs)
+                : toolArgs;
+            return { success: true, output: protectedArgs };
+        }
+        catch (err) {
+            if (err instanceof PDRuntimeError && (err.category === 'timeout' || err.category === 'runtime_unavailable')) {
+                throw err;
+            }
+            const reason = err instanceof PDRuntimeError && err.category === 'output_invalid'
+                ? 'tool_call_extraction_failed'
+                : 'provider_no_tool_use';
+            return { success: false, fallbackReason: reason };
+        }
+    }
+    /**
+     * Path 2: JSON mode (PRI-271 B1).
+     *
+     * Injects `response_format: { type: 'json_object' }` via onPayload
+     * to force the provider to output valid JSON. Then parses and validates.
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- stateless helper; kept as private method for cohesion
+    async tryJsonModePath(params) {
+        try {
+            const completeOptions = {
+                signal: params.signal,
+                apiKey: params.apiKey,
+                timeoutMs: params.effectiveTimeoutMs,
+                maxRetries: 0,
+                onPayload: (payload) => {
+                    if (typeof payload === 'object' && payload !== null) {
+                        const p = payload;
+                        p.response_format = { type: 'json_object' };
+                    }
+                    return payload;
+                },
+            };
+            const response = await completeSimple(params.model, params.baseContext, completeOptions);
+            const text = extractAssistantTextOrThrow(response, params.signal);
+            const parsed = extractJsonObject(text);
+            if (!parsed) {
+                return { success: false, fallbackReason: 'json_parse_failed' };
+            }
+            if (!Value.Check(params.schema, parsed)) {
+                return { success: false, fallbackReason: 'json_schema_invalid' };
+            }
+            // Lineage fields (taskId/sourcePainId/sourceTaskId/etc.) are
+            // intentionally stripped from LLM output. Downstream consumers
+            // (DiagnosticianRunner, committer) MUST get these values from
+            // RunnerContext / TaskRecord, never from validated output.
+            // This prevents LLM-supplied lineage from poisoning downstream
+            // commits (ERR-008 family). See PRI-271 D4 in PR description.
+            const protectedParsed = typeof parsed === 'object' && parsed !== null
+                ? stripLineageFields(parsed)
+                : parsed;
+            return { success: true, output: protectedParsed };
+        }
+        catch (err) {
+            if (err instanceof PDRuntimeError && (err.category === 'timeout' || err.category === 'runtime_unavailable')) {
+                throw err;
+            }
+            if (err instanceof PDRuntimeError && err.category === 'output_invalid') {
+                return { success: false, fallbackReason: 'json_parse_failed' };
+            }
+            return { success: false, fallbackReason: 'provider_no_json_mode' };
+        }
+    }
+    /**
+     * Emit output_path_chosen telemetry (PRI-271 B3).
+     *
+     * Every path selection and fallback emits structured telemetry.
+     * `path` is set when a path succeeds; null when recording a fallback reason.
+     */
+    emitOutputPathTelemetry(params) {
+        this.eventEmitter.emitTelemetry({
+            eventType: params.path ? 'output_path_chosen' : 'output_path_fallback',
+            traceId: params.input.taskRef?.taskId ?? params.runId,
+            timestamp: new Date().toISOString(),
+            sessionId: 'pi-ai-adapter',
+            agentId: 'pi-ai-adapter',
+            payload: {
+                runId: params.runId,
+                runtimeKind: 'pi-ai',
+                provider: this.config.provider,
+                model: this.config.model,
+                outputSchemaRef: params.input.outputSchemaRef ?? 'unknown',
+                outputPath: params.path,
+                fallbackReason: params.fallbackReason,
+            },
+        });
+    }
+    /**
+     * Make a single LLM call for output repair (PRI-71).
+     * Returns extracted text response or null if no content.
+     * Reuses same provider/model/apiKey as the original call.
+     *
+     * Uses an independent AbortSignal (fixed 60s timeout) to avoid the repair
+     * call immediately timing out when the original call consumed most of the
+     * original timeout budget (e.g., 5min original → 4m50s elapsed → 10s left).
+     */
+    // eslint-disable-next-line @typescript-eslint/class-methods-use-this -- REPAIR_TIMEOUT_MS is a constant; this method is intentionally stateless
+    async repairLLMCall(model, prompt, options) {
+        const REPAIR_TIMEOUT_MS = 60_000;
+        const repairSignal = AbortSignal.timeout(REPAIR_TIMEOUT_MS);
+        const repairMessage = {
+            role: 'user',
+            content: prompt,
+            timestamp: Date.now(),
+        };
+        const repairContext = { messages: [repairMessage] };
+        const response = await completeSimple(model, repairContext, {
+            signal: repairSignal,
+            apiKey: options.apiKey,
+            timeoutMs: REPAIR_TIMEOUT_MS,
+            maxRetries: 0,
+        });
+        // extractAssistantTextOrThrow throws:
+        //   - output_invalid: no text content in response
+        //   - timeout: aborted/timed out (caller's signal or pi-ai internal)
+        //   - execution_failed: provider error (non-timeout)
+        // We only swallow output_invalid, letting timeout/execution_failed propagate.
+        try {
+            return extractAssistantTextOrThrow(response, options.signal);
+        }
+        catch (err) {
+            if (err instanceof PDRuntimeError && err.category === 'output_invalid') {
+                return null;
+            }
+            throw err;
+        }
+    }
+    /**
+     * Call pi-ai complete() with retry and exponential backoff.
+     * Disables pi-ai built-in retry (maxRetries: 0) to avoid double-retry.
+     */
+    async completeWithRetry(model, context, options) {
+        const maxRetries = this.config.maxRetries ?? 2;
+        const { effectiveTimeoutMs = this.config.timeoutMs ?? 300_000, timeoutSource = 'default', input, runId = crypto.randomUUID(), } = options;
+        let lastError = undefined;
+        const overallStartTime = Date.now();
+        const getDelay = (attemptIndex) => {
+            return this.config._testBackoffDelayMs !== undefined
+                ? this.config._testBackoffDelayMs
+                : Math.min(1000 * Math.pow(2, attemptIndex), 30_000);
+        };
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            const elapsedMs = Date.now() - overallStartTime;
+            const remainingMs = effectiveTimeoutMs - elapsedMs;
+            // Fail fast if overall budget signal is aborted, or if we have already run out of budget time
+            if (options.signal?.aborted || remainingMs <= 0) {
+                const errorDetails = {
+                    timeoutClassification: 'client_timeout_budget_exhausted',
+                    effectiveTimeoutMs,
+                    timeoutSource,
+                    elapsedMs,
+                    retryAttempt: attempt,
+                    maxRetries,
+                    providerEvidence: options.signal?.aborted
+                        ? 'Client budget signal aborted'
+                        : `Overall timeout budget exhausted (elapsed ${elapsedMs}ms of ${effectiveTimeoutMs}ms)`,
+                };
+                throw new PDRuntimeError('timeout', `LLM request timed out after ${effectiveTimeoutMs}ms (timeoutSource=client_budget_exhausted)`, errorDetails);
+            }
+            // Cap the individual attempt timeout to the remaining budget to honor the timeout budget contract
+            const currentTimeoutMs = Math.min(effectiveTimeoutMs, remainingMs);
+            try {
+                const completeOptions = {
+                    signal: options.signal,
+                    apiKey: options.apiKey,
+                    timeoutMs: currentTimeoutMs,
+                    maxRetries: 0, // disable pi-ai built-in retry to avoid double-retry
+                };
+                if (this.config.reasoning !== undefined && this.config.reasoning !== false) {
+                    completeOptions.reasoning = this.config.reasoning;
+                }
+                const response = await completeSimple(model, context, completeOptions);
+                // If provider resolved with an error response, classify and potentially retry.
+                if (response.stopReason === 'error' || response.stopReason === 'aborted') {
+                    const rawMessage = response.errorMessage ?? 'unknown provider error';
+                    const elapsedMsAfter = Date.now() - overallStartTime;
+                    const isTimeout = response.stopReason === 'aborted'
+                        || options.signal?.aborted
+                        || /timeout|timed\s*out/i.test(rawMessage)
+                        || /abort/i.test(rawMessage);
+                    const classification = (options.signal?.aborted || elapsedMsAfter >= effectiveTimeoutMs)
+                        ? 'client_timeout_budget_exhausted'
+                        : isTimeout
+                            ? 'provider_transient_timeout'
+                            : 'not_applicable';
+                    if (isTimeout) {
+                        const errorDetails = {
+                            timeoutClassification: classification,
+                            effectiveTimeoutMs,
+                            timeoutSource,
+                            elapsedMs: elapsedMsAfter,
+                            retryAttempt: attempt,
+                            maxRetries,
+                            providerEvidence: safeStringifyPreview(rawMessage, 300),
+                        };
+                        const pdErr = new PDRuntimeError('timeout', `[timeout] LLM request timed out after ${effectiveTimeoutMs}ms (timeoutSource=provider_request)`, errorDetails);
+                        lastError = pdErr;
+                        if (classification === 'provider_transient_timeout' && attempt < maxRetries) {
+                            if (input) {
+                                this.emitAttemptTelemetry({
+                                    input,
+                                    runId,
+                                    attempt,
+                                    maxRetries,
+                                    err: pdErr,
+                                    elapsedMs: elapsedMsAfter,
+                                    timeoutSource,
+                                    effectiveTimeoutMs,
+                                });
+                            }
+                            const delay = getDelay(attempt);
+                            await new Promise(r => setTimeout(r, delay));
+                            continue;
+                        }
+                        throw pdErr;
+                    }
+                    // execution_failed — retryable if attempts remain
+                    const pdErr = new PDRuntimeError('execution_failed', `LLM execution failed: ${rawMessage.substring(0, 300)}`, {
+                        retryAttempt: attempt,
+                        maxRetries,
+                        elapsedMs: elapsedMsAfter,
+                        providerEvidence: safeStringifyPreview(rawMessage, 300),
+                    });
+                    lastError = pdErr;
+                    if (attempt < maxRetries) {
+                        if (input) {
+                            this.emitAttemptTelemetry({
+                                input,
+                                runId,
+                                attempt,
+                                maxRetries,
+                                err: pdErr,
+                                elapsedMs: elapsedMsAfter,
+                                timeoutSource,
+                                effectiveTimeoutMs,
+                            });
+                        }
+                        const delay = getDelay(attempt);
+                        await new Promise(r => setTimeout(r, delay));
+                        continue;
+                    }
+                    throw pdErr;
+                }
+                return response;
+            }
+            catch (err) {
+                const elapsedMsAfter = Date.now() - overallStartTime;
+                let classificationResult = classifyFailure(err, options.signal);
+                if (options.signal?.aborted || elapsedMsAfter >= effectiveTimeoutMs) {
+                    classificationResult = {
+                        category: 'timeout',
+                        classification: 'client_timeout_budget_exhausted',
+                    };
+                }
+                // If it's a client budget exhaustion, throw immediately (no retry)
+                if (classificationResult.classification === 'client_timeout_budget_exhausted') {
+                    const errorDetails = {
+                        timeoutClassification: 'client_timeout_budget_exhausted',
+                        effectiveTimeoutMs,
+                        timeoutSource,
+                        elapsedMs: elapsedMsAfter,
+                        retryAttempt: attempt,
+                        maxRetries,
+                        providerEvidence: safeStringifyPreview(err, 300),
+                    };
+                    throw new PDRuntimeError('timeout', `LLM request timed out after ${effectiveTimeoutMs}ms`, errorDetails);
+                }
+                if (classificationResult.category === 'timeout') {
+                    const errorDetails = {
+                        timeoutClassification: 'provider_transient_timeout',
+                        effectiveTimeoutMs,
+                        timeoutSource,
+                        elapsedMs: elapsedMsAfter,
+                        retryAttempt: attempt,
+                        maxRetries,
+                        providerEvidence: safeStringifyPreview(err, 300),
+                    };
+                    const pdErr = new PDRuntimeError('timeout', `LLM request timed out after ${effectiveTimeoutMs}ms`, errorDetails);
+                    lastError = pdErr;
+                    if (attempt < maxRetries) {
+                        if (input) {
+                            this.emitAttemptTelemetry({
+                                input,
+                                runId,
+                                attempt,
+                                maxRetries,
+                                err: pdErr,
+                                elapsedMs: elapsedMsAfter,
+                                timeoutSource,
+                                effectiveTimeoutMs,
+                            });
+                        }
+                        const delay = getDelay(attempt);
+                        await new Promise(r => setTimeout(r, delay));
+                        continue;
+                    }
+                    throw pdErr;
+                }
+                if (err instanceof PDRuntimeError) {
+                    throw err; // don't retry standard PDRuntimeError if it is permanent or already handled
+                }
+                // It is an execution_failed (network, etc.)
+                const errorDetails = {
+                    retryAttempt: attempt,
+                    maxRetries,
+                    elapsedMs: elapsedMsAfter,
+                    providerEvidence: safeStringifyPreview(err, 300),
+                };
+                const pdErr = new PDRuntimeError('execution_failed', `LLM completion failed: ${err instanceof Error ? err.message : String(err)}`, errorDetails);
+                lastError = pdErr;
+                if (attempt < maxRetries) {
+                    if (input) {
+                        this.emitAttemptTelemetry({
+                            input,
+                            runId,
+                            attempt,
+                            maxRetries,
+                            err: pdErr,
+                            elapsedMs: elapsedMsAfter,
+                            timeoutSource,
+                            effectiveTimeoutMs,
+                        });
+                    }
+                    const delay = getDelay(attempt);
+                    await new Promise(r => setTimeout(r, delay));
+                }
+            }
+        }
+        // If lastError is already a PDRuntimeError, re-throw it; otherwise wrap it
+        if (lastError instanceof PDRuntimeError) {
+            throw lastError;
+        }
+        throw new PDRuntimeError('execution_failed', `LLM completion failed after ${maxRetries + 1} attempts: ${lastError instanceof Error ? lastError.message : String(lastError)}`);
+    }
+    emitAttemptTelemetry(params) {
+        const { input, runId, attempt, maxRetries, err, elapsedMs, timeoutSource, effectiveTimeoutMs, } = params;
+        const endedAt = new Date().toISOString();
+        const { details } = err;
+        let timeoutClassification = 'not_applicable';
+        let providerEvidence = '';
+        if (details && typeof details === 'object') {
+            if (isObjectWithKey(details, 'timeoutClassification')) {
+                const { timeoutClassification: tc } = details;
+                if (typeof tc === 'string')
+                    timeoutClassification = tc;
+            }
+            if (isObjectWithKey(details, 'providerEvidence')) {
+                const { providerEvidence: pe } = details;
+                if (typeof pe === 'string')
+                    providerEvidence = pe;
+            }
+        }
+        this.eventEmitter.emitTelemetry({
+            eventType: 'runtime_invocation_failed',
+            traceId: input.taskRef?.taskId ?? runId,
+            timestamp: endedAt,
+            sessionId: 'pi-ai-adapter',
+            agentId: 'pi-ai-adapter',
+            payload: {
+                runId,
+                runtimeKind: 'pi-ai',
+                runnerKind: input.agentSpec.agentId,
+                provider: this.config.provider,
+                model: this.config.model,
+                effectiveTimeoutMs,
+                timeoutSource,
+                elapsedMs,
+                timeoutClassification,
+                retryAttempt: attempt,
+                maxRetries,
+                providerEvidence,
+                errorMessage: err.message,
+                isRetryAttempt: true,
+            },
+        });
+    }
+}
+//# sourceMappingURL=pi-ai-runtime-adapter.js.map