specrails-core 6.0.0 → 6.1.0

package/dist/agent-runtime/engine/implementation-compiler.js

@@ -0,0 +1,91 @@
+import { Annotation, END, interrupt, isGraphInterrupt, START, StateGraph } from '@langchain/langgraph';
+import { EphemeralValue } from '@langchain/langgraph/channels';
+import { CORE_NODE_ORDER, CoreState } from '../graph/state.js';
+import { EngineError } from './contracts.js';
+import { boundPieceOutput } from './output.js';
+import { json } from './pieces/shared.js';
+function implementationSchema() {
+    return Annotation.Root({ ...CoreState.spec,
+        $scope: Annotation({ reducer: (_old, value) => value }),
+        $outer: Annotation({ reducer: (_old, value) => value }),
+        $next: Annotation({ reducer: (_old, value) => value, default: () => 'architect' }),
+        $nodeResult: Annotation({ reducer: (_old, value) => value, default: () => null }),
+        $commit: new EphemeralValue(false),
+    });
+}
+export function implementationInput(parent, frame) {
+    return { $outer: structuredClone(parent), $scope: { id: frame.scope.id + '/' + frame.visitId, nodePathPrefix: frame.nodePath,
+            ...(frame.scope.branchId ? { branchId: frame.scope.branchId } : {}), ...(frame.scope.limits ? { limits: frame.scope.limits } : {}) } };
+}
+export function implementationContext(state, frame, signal, execution) {
+    return { state: structuredClone(state), frame, signal,
+        interrupt: request => interrupt(request),
+        progress: event => execution.progress({ ...event, payload: {
+                ...(event.payload !== null && typeof event.payload === 'object' && !Array.isArray(event.payload) ? event.payload : { payload: event.payload }),
+                runId: frame.runId, nodePath: frame.nodePath, scopeId: frame.scope.id,
+                ...(frame.scope.branchId ? { branch: frame.scope.branchId } : {}), attemptId: frame.attemptId, attempt: frame.attempt, visit: frame.visit,
+            } }), };
+}
+/** Six actual Core nodes use the parent's saver; every state update shares its terminal commit. */
+export function compileImplementationGraph(adapter, execution) {
+    const schema = implementationSchema(), graph = new StateGraph(schema);
+    for (const id of CORE_NODE_ORDER) {
+        const node = adapter.nodes[id], effect = node.effect ?? 'write';
+        graph.addNode(id, async (state, config) => {
+            const info = config.executionInfo;
+            if (!info?.threadId)
+                throw new EngineError('execution_identity_missing', 'Implementation child requires a public checkpoint identity');
+            const frame = await execution.enter({ nodePath: state.$scope.nodePathPrefix + '/' + id, scope: state.$scope,
+                kind: id === 'verify' ? 'verify' : id === 'archive' ? 'openspec-archive' : 'role-turn', effect,
+                requiresAI: !['verify', 'archive'].includes(id), acceptsSteering: !['verify', 'archive'].includes(id),
+                task: { checkpointThreadId: info.threadId, checkpointId: info.checkpointId, taskCheckpointNs: info.checkpointNs, taskId: info.taskId },
+                retry: { maxAttempts: node.maxAttempts ?? 1, retrySafe: node.retrySafe === true },
+            });
+            let result;
+            try {
+                result = await execution.execute(frame, effect, async (signal) => {
+                    const context = implementationContext(state.$outer, frame, signal, execution);
+                    const response = await adapter.runNode(id, state, context);
+                    const next = response.status === 'succeeded' ? response.next === undefined ? node.ends[0] ?? null : response.next : null;
+                    if (next !== null && !CORE_NODE_ORDER.includes(next))
+                        throw new EngineError('invalid_piece_outcome', `Implementation ${id} returned an unknown successor`);
+                    const update = response.update === undefined ? {} : json(response.update);
+                    const childUpdate = { update, next, response: json({ ...response, update: undefined }), journal: json(adapter.snapshot(context)) };
+                    if (Buffer.byteLength(JSON.stringify(childUpdate)) > 1_750_000)
+                        throw new EngineError('implementation_snapshot_invalid', 'Implementation child checkpoint exceeds its bounded state budget');
+                    return { outcome: next ?? (response.status === 'succeeded' ? 'next' : response.status), status: response.status,
+                        childUpdate,
+                        ...(response.output === undefined ? {} : { output: boundPieceOutput(json(response.output)) }),
+                        ...(response.error ? { error: { code: response.status === 'blocked' ? 'implementation_blocked' : 'implementation_failed', message: response.error } } : {}),
+                        completesRun: false };
+                });
+            }
+            catch (error) {
+                if (isGraphInterrupt(error)) {
+                    await execution.interrupted(frame, error);
+                    throw error;
+                }
+                const code = error instanceof EngineError || (error && typeof error === 'object' && 'code' in error) ? String(error.code) : 'implementation_failed';
+                if (effect === 'write' && ['aborted', 'timeout', 'idle_timeout', 'lease_lost'].includes(code)) {
+                    await execution.interrupted(frame, error);
+                    throw error;
+                }
+                await execution.failed(frame, error, { retry: false });
+                result = { outcome: 'failed', status: 'failed', error: { code, message: error instanceof Error ? error.message : String(error) },
+                    childUpdate: { update: {}, next: null, response: { status: 'failed', error: error instanceof Error ? error.message : String(error) } }, completesRun: false };
+            }
+            const marker = execution.terminal(frame, result);
+            const saved = marker.result.childUpdate;
+            if (!saved)
+                throw new EngineError('terminal_mismatch', 'Implementation terminal is missing its child state update');
+            return { ...saved.update, $next: saved.next, $nodeResult: saved.response, $commit: marker };
+        });
+    }
+    const edges = graph;
+    edges.addEdge(START, adapter.entry);
+    const destinations = Object.fromEntries(CORE_NODE_ORDER.map(id => [id, id]));
+    destinations.__end__ = END;
+    for (const id of CORE_NODE_ORDER)
+        edges.addConditionalEdges(id, state => state.$next ?? '__end__', destinations);
+    return edges.compile();
+}

package/dist/agent-runtime/engine/index.d.ts

@@ -0,0 +1,14 @@
+/** Published definitions and run lifecycle. Infrastructure remains per execution. */
+export { createRun, resumeRun, signalRun, cancelRun, definitionRunDirectory, type RunObservers, type ResumeDefinitionOptions } from './runs.js';
+export { forkRun, type ForkRunOptions } from './fork.js';
+export { statusRun } from './run-status.js';
+export { preflightDefinition, configuredRoles, type DefinitionRunInput, type DefinitionRunRequest } from './preflight.js';
+export { validateWorkflowDefinition } from './definition-validator.js';
+export { workflowDefinitionSchema } from './definition-schema.js';
+export { definitionVersion, canonicalJson } from './canonical-json.js';
+export { validationPieceRegistry } from './pieces/index.js';
+export { PieceRegistry } from './piece-registry.js';
+export { compileWorkflowDefinition } from './compiler.js';
+export { describeDefinition } from './graph-description.js';
+export * from './definition-types.js';
+export * from './contracts.js';

package/dist/agent-runtime/engine/index.js

@@ -0,0 +1,14 @@
+/** Published definitions and run lifecycle. Infrastructure remains per execution. */
+export { createRun, resumeRun, signalRun, cancelRun, definitionRunDirectory } from './runs.js';
+export { forkRun } from './fork.js';
+export { statusRun } from './run-status.js';
+export { preflightDefinition, configuredRoles } from './preflight.js';
+export { validateWorkflowDefinition } from './definition-validator.js';
+export { workflowDefinitionSchema } from './definition-schema.js';
+export { definitionVersion, canonicalJson } from './canonical-json.js';
+export { validationPieceRegistry } from './pieces/index.js';
+export { PieceRegistry } from './piece-registry.js';
+export { compileWorkflowDefinition } from './compiler.js';
+export { describeDefinition } from './graph-description.js';
+export * from './definition-types.js';
+export * from './contracts.js';

package/dist/agent-runtime/engine/invocation-context.d.ts

@@ -0,0 +1,11 @@
+import type { WorkflowState, WorkflowStepContext } from '../workflow-types.js';
+import { type JsonValue, type PieceExecutionContext, type WorkflowBudget } from './contracts.js';
+import type { RunLedger } from './checkpoint/ledger.js';
+import type { WorkflowDefinition, DefinitionNode } from './definition-types.js';
+/** Resolve declared paths without interpreting LangGraph's opaque namespaces. */
+export declare function definitionNodeAt(definition: WorkflowDefinition, nodePath: string): DefinitionNode | undefined;
+export declare function roleAt(definition: WorkflowDefinition, nodePath: string): string;
+export declare function ledgerBudget(ledger: RunLedger): WorkflowBudget;
+export declare function ledgerWorkflowState(ledger: RunLedger, definition: WorkflowDefinition, scopeId?: string): WorkflowState;
+/** Adapter to the existing efficient role invoker; SQLite remains the sole journal. */
+export declare function invocationStepContext(ledger: RunLedger, definition: WorkflowDefinition, context: PieceExecutionContext, input?: JsonValue): WorkflowStepContext;

package/dist/agent-runtime/engine/invocation-context.js

@@ -0,0 +1,128 @@
+import { randomUUID } from 'node:crypto';
+import { EngineError } from './contracts.js';
+import { remainingBudget } from './budget.js';
+import { projectDurableEvent, traceIdFor } from './events.js';
+import { contentDigest } from './canonical-json.js';
+import { ControlInbox, renderOperatorSteering } from './steering/inbox.js';
+/** Resolve declared paths without interpreting LangGraph's opaque namespaces. */
+export function definitionNodeAt(definition, nodePath) {
+    let nodes = definition.nodes, node;
+    for (const segment of nodePath.split('/')) {
+        node = nodes[segment];
+        if (!node)
+            return undefined;
+        const reference = node.kind === 'component' ? node.params.ref : node.kind === 'map' ? node.params.body : undefined;
+        nodes = typeof reference === 'string' ? definition.components?.[reference]?.nodes ?? {} : {};
+    }
+    return node;
+}
+export function roleAt(definition, nodePath) {
+    const node = definitionNodeAt(definition, nodePath);
+    if (node?.kind === 'role-turn' || node?.kind === 'decider')
+        return String(node.params.roleId);
+    return node?.kind === 'prompt' ? 'prompt' : nodePath.split('/').at(-1);
+}
+export function ledgerBudget(ledger) {
+    const row = ledger.db.get('budget', { run_id: ledger.runId });
+    return { ...(row.max_cost_usd === null ? {} : { maxCostUsd: Number(row.max_cost_usd) }),
+        ...(row.max_tokens === null ? {} : { maxTokens: Number(row.max_tokens) }),
+        ...(row.max_duration_ms === null ? {} : { maxDurationMs: Number(row.max_duration_ms) }) };
+}
+export function ledgerWorkflowState(ledger, definition, scopeId = 'root') {
+    const row = ledger.run(), snapshot = ledger.scopeSnapshot(scopeId), usage = snapshot.usage;
+    const attempts = new Map(ledger.db.sqlite.prepare("SELECT a.*,v.effect FROM attempts a JOIN visits v ON a.visit_id=v.visit_id WHERE a.run_id=? AND (?='*' OR a.scope_id=?)").all(ledger.runId, scopeId, scopeId).map(item => [String(item.attempt_id), item]));
+    const invocations = new Map();
+    for (const item of ledger.db.sqlite.prepare('SELECT * FROM invocations WHERE run_id=? ORDER BY started_at,ordinal').all(ledger.runId)) {
+        const key = String(item.attempt_id), entries = invocations.get(key) ?? [];
+        entries.push(item);
+        invocations.set(key, entries);
+    }
+    const history = snapshot.attempts.map(attempt => {
+        const details = attempts.get(attempt.frame.attemptId), rows = invocations.get(attempt.frame.attemptId) ?? [];
+        const completed = rows.filter(item => item.result_json).map(item => JSON.parse(String(item.result_json)));
+        const sum = (key) => rows.some(item => !item.result_json) || completed.some(item => item.usage[key] == null) ? null : completed.reduce((total, item) => total + (item.usage[key] ?? 0), 0);
+        return { id: attempt.frame.attemptId, stepId: roleAt(definition, attempt.frame.nodePath), attempt: attempt.frame.attempt, visit: attempt.frame.visit,
+            status: attempt.status, startedAt: String(details.started_at),
+            ...(details.ended_at ? { completedAt: String(details.ended_at) } : {}),
+            ...(attempt.result?.output === undefined ? {} : { output: attempt.result.output }),
+            ...(attempt.error ? { error: attempt.error.message } : {}),
+            ...(rows.length ? { usage: { costUsd: sum('costUsd'), inputTokens: sum('inputTokens'), outputTokens: sum('outputTokens') } } : {}),
+            invocations: completed, pendingInvocations: rows.filter(item => !item.result_json).map(item => ({
+                invocationId: String(item.invocation_id), ordinal: Number(item.ordinal), provider: String(item.provider), ...(item.model ? { model: String(item.model) } : {}),
+            })), };
+    });
+    const steps = {};
+    for (const attempt of snapshot.attempts) {
+        const details = attempts.get(attempt.frame.attemptId);
+        steps[attempt.frame.nodePath] = { id: attempt.frame.nodePath, status: attempt.status,
+            effect: details.effect, visits: attempt.frame.visit, attempt: attempt.frame.attempt, attemptId: attempt.frame.attemptId,
+            startedAt: String(details.started_at), ...(details.ended_at ? { completedAt: String(details.ended_at) } : {}),
+            ...(attempt.result?.output === undefined ? {} : { output: attempt.result.output }),
+            ...(attempt.result?.childUpdate ? { update: attempt.result.childUpdate } : {}), ...(attempt.error ? { error: attempt.error.message } : {}) };
+    }
+    const interruptions = ledger.db.sqlite.prepare("SELECT * FROM interrupts WHERE run_id=? AND (?='*' OR scope_id=?) ORDER BY requested_at DESC,interrupt_id DESC").all(ledger.runId, scopeId, scopeId);
+    const pending = interruptions.find(item => !item.answered_at) ?? interruptions[0];
+    const request = pending ? JSON.parse(String(pending.payload_json)) : undefined;
+    const answer = pending?.answer_json ? JSON.parse(String(pending.answer_json)) : undefined;
+    const events = ledger.events().filter(event => scopeId === '*' || !event.scopeId || event.scopeId === scopeId).flatMap(event => {
+        const projected = projectDurableEvent(event);
+        return projected.type === 'workflow-event' ? [projected.event] : [];
+    });
+    return { schemaVersion: 2, runId: ledger.runId, traceId: traceIdFor(ledger.runId), workflowId: definition.id,
+        workflowVersion: definition.version, workflowFingerprint: definition.version, inputFingerprint: contentDigest(JSON.parse(String(row.request_json))),
+        status: String(row.status), createdAt: String(row.created_at), updatedAt: String(row.updated_at),
+        nextStep: pending && !pending.answered_at ? String(pending.node_path) : [...snapshot.attempts].reverse().find(attempt => ['running', 'interrupted', 'failed'].includes(attempt.status))?.frame.nodePath ?? null,
+        nextAttempt: history.length + 1, transitions: snapshot.transitions, executionCount: history.length, steps, history, events, budget: ledgerBudget(ledger),
+        ...(pending && request?.kind === 'question' ? { pendingQuestion: { stepId: String(pending.node_path), requestedAt: String(pending.requested_at), question: request.prompt,
+                ...(pending.answered_at ? { answeredAt: String(pending.answered_at), answer: typeof answer === 'string' ? answer : answer?.answer } : {}) } } : {}),
+        ...(pending && ['approval', 'gate'].includes(request?.kind ?? '') ? { pendingApproval: { stepId: String(pending.node_path), requestedAt: String(pending.requested_at), reason: request.prompt,
+                ...(pending.answered_at ? { grantedAt: String(pending.answered_at) } : {}) } } : {}),
+        usage: { costUsd: usage.costUsd, inputTokens: usage.inputTokens, outputTokens: usage.outputTokens, knownCostUsd: usage.knownCostUsd,
+            knownTokens: usage.knownInputTokens + usage.knownOutputTokens, durationMs: ledger.activeDurationMs() }, };
+}
+/** Adapter to the existing efficient role invoker; SQLite remains the sole journal. */
+export function invocationStepContext(ledger, definition, context, input = null) {
+    const budget = ledgerBudget(ledger);
+    const messages = new ControlInbox(ledger.db, ledger.runId).assigned(context.frame);
+    const pendingRow = ledger.db.sqlite.prepare('SELECT payload_json FROM interrupts WHERE run_id=? AND attempt_id=? ORDER BY requested_at DESC,interrupt_id DESC LIMIT 1').get(ledger.runId, context.frame.attemptId);
+    const pending = pendingRow ? JSON.parse(String(pendingRow.payload_json)) : undefined;
+    let offered;
+    const headroom = () => {
+        const live = ledger.db.sqlite.prepare('SELECT COUNT(*) count,COALESCE(SUM(max_tokens),0) tokens,COALESCE(SUM(max_cost_usd),0) cost FROM reservations WHERE run_id=?').get(ledger.runId);
+        const remaining = remainingBudget(ledger.usage(), budget, ledger.activeDurationMs(), { costUsd: Number(live.cost), tokens: Number(live.tokens) });
+        // Each concurrent caller receives a bounded share of unreserved capacity.
+        // Actual usage returns the unused share immediately at invocation settlement.
+        const parallelism = Math.min(definition.policies?.concurrency ?? 1, context.frame.scope.limits?.[0]?.concurrency ?? definition.policies?.concurrency ?? 1);
+        const slots = Math.max(1, parallelism - Number(live.count));
+        offered = { ...remaining,
+            ...(remaining.maxTokens === undefined ? {} : { maxTokens: Math.floor(remaining.maxTokens / slots) }),
+            ...(remaining.maxCostUsd === undefined ? {} : { maxCostUsd: remaining.maxCostUsd / slots }),
+        };
+        return offered;
+    };
+    return {
+        runId: ledger.runId, stepId: context.frame.nodePath, attemptId: context.frame.attemptId, attempt: context.frame.attempt,
+        input, ...(messages.length ? { operatorSteering: renderOperatorSteering(messages) } : {}),
+        ...(pending?.kind === 'question' ? { pending: { kind: 'question', question: pending.prompt } } : pending && ['approval', 'gate'].includes(pending.kind) ? { pending: { kind: 'approval', reason: pending.prompt } } : {}),
+        signal: context.signal, checkpoint: ledgerWorkflowState(ledger, definition, context.frame.scope.id), remainingBudget: headroom,
+        interrupt: request => context.interrupt({ kind: request.kind, prompt: request.kind === 'approval' ? request.reason : request.question,
+            nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId }),
+        // The existing invoker calls this immediately before its finally settlement.
+        // Never charge twice: ProviderInvocation is the durable source of usage.
+        reportUsage: () => { },
+        reportInvocationStarted: async (measurement) => {
+            const invocationId = randomUUID(), limits = offered ?? headroom();
+            if (limits.maxTokens === 0 || limits.maxCostUsd === 0)
+                throw new EngineError('budget_exhausted', 'No unreserved budget remains for a provider invocation');
+            const ordinal = ledger.startInvocation(context.frame, { ...measurement, invocationId, role: roleAt(definition, context.frame.nodePath) }, limits);
+            offered = undefined;
+            return { invocationId, ordinal };
+        },
+        reportInvocation: async (invocation) => {
+            if (!invocation.invocationId)
+                throw new EngineError('invocation_mismatch', 'Provider settlement requires its durable invocation ID');
+            ledger.settleInvocation(context.frame, { ...invocation, invocationId: invocation.invocationId });
+        },
+        reportEfficiencyActivity: async (kind, payload) => context.progress({ type: 'runtime-efficiency-event', payload: { kind, ...payload } }),
+    };
+}

package/dist/agent-runtime/engine/otel.d.ts

@@ -0,0 +1,15 @@
+import { type DurableEngineEvent } from './contracts.js';
+export interface EngineTelemetry {
+    observe(event: DurableEngineEvent): void;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+interface TelemetryOptions {
+    endpoint?: string;
+    onError?: (error: unknown) => void;
+    timeoutMs?: number;
+    maxQueue?: number;
+}
+/** Explicitly enabled OTLP/HTTP observer. Lifecycle metadata only; never a source of execution truth. */
+export declare function createEngineTelemetry(options?: TelemetryOptions): EngineTelemetry | undefined;
+export {};

package/dist/agent-runtime/engine/otel.js

@@ -0,0 +1,132 @@
+import { EngineError } from './contracts.js';
+import { spanIdFor, traceIdFor } from './events.js';
+/** Explicitly enabled OTLP/HTTP observer. Lifecycle metadata only; never a source of execution truth. */
+export function createEngineTelemetry(options = {}) {
+    const configured = options.endpoint ?? process.env.SPECRAILS_OTEL_ENDPOINT;
+    if (!configured)
+        return undefined;
+    const report = (error) => { try {
+        options.onError?.(error);
+    }
+    catch { /* Optional diagnostics cannot fail a run. */ } };
+    let endpoint;
+    try {
+        endpoint = new URL(configured);
+        if (!['http:', 'https:'].includes(endpoint.protocol) || endpoint.username || endpoint.password || endpoint.search || endpoint.hash)
+            throw new Error('Telemetry endpoint must be an HTTP(S) URL without credentials, query or fragment');
+        endpoint.pathname = endpoint.pathname.replace(/\/$/, '').endsWith('/v1/traces') ? endpoint.pathname.replace(/\/$/, '') : endpoint.pathname.replace(/\/$/, '') + '/v1/traces';
+    }
+    catch (error) {
+        report(error);
+        return undefined;
+    }
+    const maximum = options.maxQueue ?? 512, timeoutMs = options.timeoutMs ?? 3000;
+    if (!Number.isSafeInteger(maximum) || maximum < 1 || maximum > 4096 || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000) {
+        report(new EngineError('invalid_arguments', 'Telemetry queue or timeout exceeds its bound'));
+        return undefined;
+    }
+    const queue = [];
+    // Every observer belongs to one running stream. Cursor storage stays bounded across long executions.
+    const cursors = new Map();
+    let closed = false, draining, timer, dropped = 0;
+    async function send(spans) {
+        const response = await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, redirect: 'error', signal: AbortSignal.timeout(timeoutMs),
+            body: JSON.stringify({ resourceSpans: [{ resource: { attributes: [{ key: 'service.name', value: { stringValue: 'specrails-core' } }] }, scopeSpans: [{ scope: { name: 'specrails.agent-engine', version: '2' }, spans }] }] }) });
+        if (!response.ok) {
+            await response.body?.cancel();
+            throw new Error(`Telemetry collector returned HTTP ${response.status}`);
+        }
+        const reader = response.body?.getReader();
+        if (!reader)
+            return;
+        let bytes = 0;
+        const chunks = [];
+        try {
+            for (;;) {
+                const chunk = await reader.read();
+                if (chunk.done)
+                    break;
+                bytes += chunk.value.byteLength;
+                if (bytes > 64 * 1024)
+                    throw new Error('Telemetry collector response exceeds 64 KiB');
+                chunks.push(chunk.value);
+            }
+        }
+        finally {
+            await reader.cancel().catch(() => { });
+            reader.releaseLock();
+        }
+        if (bytes) {
+            const result = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            if (Number(result.partialSuccess?.rejectedSpans ?? 0) > 0)
+                throw new Error('Telemetry collector rejected spans');
+        }
+    }
+    const flush = () => {
+        if (timer) {
+            clearTimeout(timer);
+            timer = undefined;
+        }
+        if (draining)
+            return draining;
+        const work = async () => {
+            while (queue.length) {
+                const batch = queue.splice(0, 64);
+                try {
+                    await send(batch);
+                }
+                catch (error) {
+                    report(error);
+                }
+            }
+            if (dropped) {
+                report(new Error(`Telemetry queue discarded ${dropped} events`));
+                dropped = 0;
+            }
+        };
+        draining = work().finally(() => { draining = undefined; });
+        return draining;
+    };
+    return {
+        observe(event) {
+            if (closed)
+                return;
+            try {
+                if (!Number.isSafeInteger(event.sequence) || event.sequence < 1)
+                    throw new Error('Telemetry event sequence is invalid');
+                if ((cursors.get(event.runId) ?? 0) >= event.sequence)
+                    return;
+                if (!cursors.has(event.runId) && cursors.size >= 16)
+                    throw new Error('Telemetry observer exceeds its run bound');
+                cursors.set(event.runId, event.sequence);
+                if (queue.length >= maximum) {
+                    dropped++;
+                    return;
+                }
+                const millis = Date.parse(event.timestamp);
+                if (!Number.isFinite(millis) || millis < 0)
+                    throw new Error('Telemetry event timestamp is invalid');
+                const nano = (BigInt(millis) * 1000000n).toString();
+                const attributes = Object.entries({ 'specrails.run.id': event.runId, 'specrails.event.type': event.type,
+                    ...(event.nodePath ? { 'specrails.node.path': event.nodePath } : {}), ...(event.scopeId ? { 'specrails.scope.id': event.scopeId } : {}),
+                    ...(event.attemptId ? { 'specrails.attempt.id': event.attemptId } : {}), ...(event.branchId ? { 'specrails.branch.id': event.branchId } : {}),
+                }).map(([key, value]) => ({ key, value: { stringValue: value.slice(0, 512) } }));
+                // Event spans are points in durable history, so no provider duration is inferred from them.
+                queue.push({ traceId: traceIdFor(event.runId), spanId: spanIdFor(event.runId, event.sequence), name: event.type.slice(0, 128), kind: 1,
+                    startTimeUnixNano: nano, endTimeUnixNano: nano, attributes: [...attributes, { key: 'specrails.event.sequence', value: { intValue: String(event.sequence) } }],
+                    status: { code: /_(failed|interrupted|blocked)$/.test(event.type) ? 2 : 0 },
+                });
+                if (queue.length >= 64)
+                    void flush();
+                else if (!timer && !draining) {
+                    timer = setTimeout(() => { void flush(); }, 1000);
+                    timer.unref();
+                }
+            }
+            catch (error) {
+                report(error);
+            }
+        }, flush,
+        async close() { closed = true; await flush(); },
+    };
+}

package/dist/agent-runtime/engine/output.d.ts

@@ -0,0 +1,4 @@
+import { type JsonValue } from './contracts.js';
+export declare const MAX_PIECE_OUTPUT_BYTES = 262144;
+/** Preserve JSON shape while bounding untrusted provider/command output before checkpointing. */
+export declare function boundPieceOutput(value: JsonValue, maxBytes?: number): JsonValue;

package/dist/agent-runtime/engine/output.js

@@ -0,0 +1,73 @@
+import { EngineError } from './contracts.js';
+export const MAX_PIECE_OUTPUT_BYTES = 262_144;
+const truncation = '[truncated]';
+/** Preserve JSON shape while bounding untrusted provider/command output before checkpointing. */
+export function boundPieceOutput(value, maxBytes = MAX_PIECE_OUTPUT_BYTES) {
+    let remaining = maxBytes;
+    const active = new Set();
+    function string(input) {
+        const budget = Math.max(16, remaining - 64);
+        const cap = Math.max(0, Math.min(32_000, budget - 16));
+        const prefix = (text, length) => text.slice(0, length).replace(/[\uD800-\uDBFF]$/, '');
+        let candidate = input.length > cap ? prefix(input, cap) + truncation : input;
+        while (Buffer.byteLength(JSON.stringify(candidate)) > budget && candidate.length > truncation.length)
+            candidate = prefix(candidate, Math.floor(candidate.length / 2)) + truncation;
+        remaining -= Buffer.byteLength(JSON.stringify(candidate));
+        return candidate;
+    }
+    function visit(input, depth) {
+        if (depth > 32 || remaining < 40) {
+            remaining -= truncation.length + 2;
+            return truncation;
+        }
+        if (typeof input === 'string')
+            return string(input);
+        if (input === null || typeof input === 'boolean' || typeof input === 'number') {
+            if (typeof input === 'number' && !Number.isFinite(input))
+                throw new EngineError('invalid_piece_output', 'Piece output must be finite JSON');
+            remaining -= String(input).length;
+            return input;
+        }
+        if (typeof input !== 'object' || active.has(input))
+            throw new EngineError('invalid_piece_output', 'Piece output must be acyclic JSON');
+        active.add(input);
+        remaining -= 2;
+        let result;
+        if (Array.isArray(input)) {
+            const entries = [];
+            for (const entry of input) {
+                if (remaining < 80) {
+                    entries.push(truncation);
+                    remaining -= truncation.length + 3;
+                    break;
+                }
+                remaining -= 1;
+                entries.push(visit(entry, depth + 1));
+            }
+            result = entries;
+        }
+        else {
+            const entries = Object.create(null);
+            for (const key of Object.keys(input)) {
+                const overhead = Buffer.byteLength(JSON.stringify(key)) + 2;
+                if (remaining < overhead + 80) {
+                    entries._coreTruncated = true;
+                    remaining -= 22;
+                    break;
+                }
+                const descriptor = Object.getOwnPropertyDescriptor(input, key);
+                if (!('value' in descriptor))
+                    throw new EngineError('invalid_piece_output', 'Piece output cannot contain accessors');
+                remaining -= overhead;
+                entries[key] = visit(descriptor.value, depth + 1);
+            }
+            result = entries;
+        }
+        active.delete(input);
+        return result;
+    }
+    const bounded = visit(value, 0);
+    if (Buffer.byteLength(JSON.stringify(bounded)) > maxBytes)
+        throw new EngineError('invalid_piece_output', 'Piece output exceeds the bounded JSON budget');
+    return bounded;
+}

package/dist/agent-runtime/engine/piece-dependencies.d.ts

@@ -0,0 +1,50 @@
+import { type PipelineContext, type VerificationEvidencePort } from '../../pipeline/pipeline-state.js';
+import type { RuntimeConfig } from '../executor-types.js';
+import type { ExecutorRegistry } from '../executors.js';
+import { type OpenSpecRoleContext } from '../openspec.js';
+import type { ProviderInvocation } from '../efficiency-types.js';
+import type { RoleStatePort } from '../role-state.js';
+import { type AttemptFrame, type CandidateState, type EngineEffect, type JsonValue, type PieceExecutionContext, type PieceResult } from './contracts.js';
+import type { RunLedger } from './checkpoint/ledger.js';
+import type { WorkflowDefinition } from './definition-types.js';
+import type { PieceDependencies, PieceStatePort } from './pieces/ports.js';
+import type { ProjectMemory, SqliteProjectStore } from './store/sqlite-store.js';
+import { type ImplementationBinding } from './pieces/implementation-binding.js';
+/** Adapters are bound to one frozen project, definition and execution lease. */
+export declare class RunPieceDependencies implements PieceDependencies {
+    readonly context: PipelineContext;
+    readonly config: RuntimeConfig;
+    readonly registry: ExecutorRegistry;
+    private readonly definition;
+    private readonly ledger;
+    private readonly directory;
+    private readonly change?;
+    private readonly projectMemory?;
+    readonly policies: PieceDependencies['policies'];
+    constructor(context: PipelineContext, config: RuntimeConfig, registry: ExecutorRegistry, definition: WorkflowDefinition, ledger: RunLedger, directory: string, change?: string | undefined, projectMemory?: SqliteProjectStore | undefined);
+    memory(context: PieceExecutionContext): ProjectMemory;
+    private implementationBindings;
+    bindImplementation(context: PieceExecutionContext, change: string): ImplementationBinding;
+    private candidateScope;
+    private inheritedCandidateScope;
+    private candidate;
+    implementationExclusions(_context: PieceExecutionContext): {
+        runtimeExclusions: string[];
+        repositoryExclusions: Readonly<Record<string, readonly string[]>>;
+    };
+    fingerprint(): string;
+    initializeCandidate(): void;
+    executionSnapshot(context: PieceExecutionContext): {
+        candidate: CandidateState;
+        verified: import("./contracts.js").VerifiedState | null;
+    };
+    /** Only the execution owner proposes protected candidate/receipt channels. */
+    finalize(frame: AttemptFrame, result: PieceResult, effect: EngineEffect): PieceResult;
+    memo(context: PieceExecutionContext): PieceStatePort;
+    roleState(context: PieceExecutionContext): RoleStatePort;
+    stepContext(context: PieceExecutionContext): import("../workflow-types.js").WorkflowStepContext;
+    settleResult(context: PieceExecutionContext, key: string, value: JsonValue, invocation: ProviderInvocation): void;
+    artifactDirectory(context: PieceExecutionContext): string;
+    openspec(context: PieceExecutionContext): Record<string, OpenSpecRoleContext>;
+    verification(context: PieceExecutionContext): VerificationEvidencePort;
+}