specrails-core 6.0.1 → 6.2.0

package/dist/agent-runtime/engine/pieces/openspec.js

@@ -0,0 +1,75 @@
+import { archivedOpenSpecChange, archiveOpenSpecChange } from '../../graph/artifacts.js';
+import { OpenSpecCommandError, resolveOpenSpecCli, runOpenSpec } from '../../openspec.js';
+import { EngineError } from '../contracts.js';
+import { boundedText, json, paramsSchema, text } from './shared.js';
+const schema = paramsSchema({ change: { type: 'string', minLength: 1, maxLength: 128 }, allowArchived: { type: 'boolean' }, repositoryId: { type: 'string', minLength: 1, maxLength: 128 } }, ['change']);
+function changeId(value) {
+    if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value) || value.length > 64)
+        throw new EngineError('invalid_arguments', 'Invalid OpenSpec change identifier');
+    return value;
+}
+export function openSpecPieces(bindings) {
+    return [{
+            descriptor: { kind: 'openspec-validate', paramsSchema: schema, outcomes: ['pass', 'fail', 'failed'], effect: 'read', requiresAI: false },
+            async execute(params, context) {
+                const deps = bindings();
+                if (params.repositoryId !== undefined && params.repositoryId !== deps.context.artifactRepositoryId)
+                    throw new EngineError('artifact_scope_mismatch', 'OpenSpec repository must match the frozen artifact repository');
+                const change = changeId(text(params.change));
+                const archived = params.allowArchived === true ? archivedOpenSpecChange(deps.context, change) : undefined;
+                if (archived)
+                    return { outcome: 'pass', output: { change, archived, skipped: true } };
+                let stdout, exited = true;
+                try {
+                    stdout = await runOpenSpec(resolveOpenSpecCli(), deps.context.artifactRoot, ['validate', change, '--strict', '--json'], context.signal);
+                }
+                catch (error) {
+                    if (!(error instanceof OpenSpecCommandError) || error.exitCode === undefined || error.exitCode < 1)
+                        throw error;
+                    stdout = error.stdout;
+                    exited = false;
+                }
+                let report;
+                try {
+                    report = JSON.parse(stdout);
+                }
+                catch {
+                    throw new EngineError('openspec_invalid_output', 'OpenSpec did not return its validation report');
+                }
+                const item = report.items?.find(entry => entry.id === change && entry.type === 'change');
+                if (!item || typeof item.valid !== 'boolean')
+                    throw new EngineError('openspec_invalid_output', 'OpenSpec validation did not report the requested change');
+                return { outcome: exited && item.valid ? 'pass' : 'fail', output: json(report) };
+            },
+        }, {
+            descriptor: { kind: 'openspec-archive', paramsSchema: { ...schema, properties: { ...schema.properties, requiresVerified: { type: 'boolean' }, reviewedCandidate: { type: 'string' }, approvedCandidate: { type: 'string' } } }, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },
+            async execute(params, context) {
+                const deps = bindings();
+                if (params.repositoryId !== undefined && params.repositoryId !== deps.context.artifactRepositoryId)
+                    throw new EngineError('artifact_scope_mismatch', 'OpenSpec repository must match the frozen artifact repository');
+                const snapshot = deps.executionSnapshot(context);
+                const verified = snapshot.verified ?? deps.verifiedBeforeWrite?.(context);
+                if (params.requiresVerified && (!snapshot.candidate || !verified || verified.candidateHash !== snapshot.candidate.hash))
+                    return { outcome: 'failed', output: { reason: 'unverified' } };
+                if ([params.reviewedCandidate, params.approvedCandidate].some(hash => hash !== undefined && hash !== snapshot.candidate?.hash))
+                    return { outcome: 'failed', output: { reason: 'candidate_changed' } };
+                const change = changeId(text(params.change)), initial = snapshot.candidate?.hash;
+                const archived = params.allowArchived === true ? archivedOpenSpecChange(deps.context, change) : undefined;
+                if (archived)
+                    return { outcome: 'next', output: { change, archived, skipped: true } };
+                try {
+                    await archiveOpenSpecChange(deps.context, change, { directory: deps.artifactDirectory(context), beforePublish: () => {
+                            if (initial !== deps.executionSnapshot(context).candidate?.hash)
+                                throw new EngineError('candidate_changed', 'Candidate changed while preparing the OpenSpec archive');
+                        } }, context.signal);
+                }
+                catch (error) {
+                    if (!(error instanceof OpenSpecCommandError) || error.exitCode === undefined || error.exitCode < 1)
+                        throw error;
+                    return { outcome: 'failed', status: 'failed', error: { code: 'openspec_command_failed', message: boundedText(error.message, 4000) },
+                        output: { change, exitCode: error.exitCode, stdout: boundedText(error.stdout) } };
+                }
+                return { outcome: 'next', output: { change, archived: true }, history: [{ id: context.frame.attemptId + ':archive', transition: context.frame.transition, attempt: context.frame.attempt, ordinal: 0, nodePath: context.frame.nodePath, text: boundedText('Archived OpenSpec change ' + change) }] };
+            },
+        }];
+}

package/dist/agent-runtime/engine/pieces/ports.d.ts

@@ -0,0 +1,53 @@
+import type { PipelineContext, VerificationEvidencePort } from '../../../pipeline/pipeline-state.js';
+import type { RuntimeConfig } from '../../executor-types.js';
+import type { ExecutorRegistry } from '../../executors.js';
+import type { ProviderInvocation } from '../../efficiency-types.js';
+import type { OpenSpecRoleContext } from '../../openspec.js';
+import type { RoleStatePort } from '../../role-state.js';
+import type { WorkflowStepContext } from '../../workflow-types.js';
+import type { CandidateState, JsonValue, PieceExecutionContext, VerifiedState } from '../contracts.js';
+import type { ProjectMemory } from '../store/sqlite-store.js';
+import type { ImplementationBinding } from './implementation-binding.js';
+/** One physical attempt's durable notes; never a cache shared between providers or runs. */
+export interface PieceStatePort {
+    get(key: string): JsonValue | undefined;
+    set(key: string, value: JsonValue): void;
+}
+export interface PieceDependencies {
+    context: PipelineContext;
+    readonly change?: string;
+    config: RuntimeConfig;
+    registry: ExecutorRegistry;
+    stepContext(context: PieceExecutionContext): WorkflowStepContext;
+    roleState(context: PieceExecutionContext): RoleStatePort;
+    artifactContracts?(context: PieceExecutionContext): PieceStatePort;
+    memo(context: PieceExecutionContext): PieceStatePort;
+    /** Narrow project memory is restricted by the declared piece and namespace capability. */
+    memory(context: PieceExecutionContext): ProjectMemory;
+    /** Provider settlement and the response needed for interrupt replay share one transaction. */
+    settleResult(context: PieceExecutionContext, key: string, value: JsonValue, invocation: ProviderInvocation): void;
+    verifiedBeforeWrite?(context: PieceExecutionContext): VerifiedState | null;
+    executionSnapshot(context: PieceExecutionContext): {
+        candidate: CandidateState | null;
+        verified: VerifiedState | null;
+    };
+    verification(context: PieceExecutionContext): VerificationEvidencePort;
+    /** A scoped adapter directory for recoverable OpenSpec write sets, never state.json. */
+    artifactDirectory(context: PieceExecutionContext): string;
+    /** Registers parent-owned scoped journals for candidate inspection, recovery and fork. */
+    bindImplementation(context: PieceExecutionContext, change: string, shared?: boolean): ImplementationBinding;
+    /** Current union of declared implementation artifacts and journals, including the parent run. */
+    implementationExclusions?(context: PieceExecutionContext): {
+        runtimeExclusions: readonly string[];
+        repositoryExclusions: Readonly<Record<string, readonly string[]>>;
+    };
+    openspec?(context: PieceExecutionContext): Record<string, OpenSpecRoleContext>;
+    /** Committed private operation state, inaccessible to workflow variables or fork patches. */
+    operationState?(context: PieceExecutionContext): JsonValue | undefined;
+    policies?: {
+        historyMaxChars?: number;
+        noProgress?: number;
+    };
+}
+/** Evaluated only at execution; catalog listing and validation are effect-free. */
+export type PieceDependencyProvider = () => PieceDependencies;

package/dist/agent-runtime/engine/pieces/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/agent-runtime/engine/pieces/project-memory.d.ts

@@ -0,0 +1,3 @@
+import type { PieceExecutionContext } from '../contracts.js';
+/** Project notes are advisory: failure must never replay an already billed provider response. */
+export declare function advisoryMemory<T>(context: PieceExecutionContext, operation: () => Promise<T>): Promise<T | undefined>;

package/dist/agent-runtime/engine/pieces/project-memory.js

@@ -0,0 +1,13 @@
+/** Project notes are advisory: failure must never replay an already billed provider response. */
+export async function advisoryMemory(context, operation) {
+    try {
+        return await operation();
+    }
+    catch {
+        try {
+            context.progress({ type: 'span', payload: { name: 'project-memory', status: 'unavailable', nodePath: context.frame.nodePath } });
+        }
+        catch { /* Diagnostics cannot fail the node. */ }
+        return undefined;
+    }
+}

package/dist/agent-runtime/engine/pieces/prompt.d.ts

@@ -0,0 +1,5 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+export declare function verificationSentinel(output: string): 'pass' | 'fail' | undefined;
+/** Free turns share accounting and executor protections, without adding role instructions. */
+export declare function promptPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/prompt.js

@@ -0,0 +1,130 @@
+import { performance } from 'node:perf_hooks';
+import { AgentExecutionError, unknownUsage } from '../../executor-types.js';
+import { ROLE_INSTRUCTIONS_VERSION } from '../../prompts.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { answerEntry, boundedText, captures, captureSchema, historyEntry, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
+const sessionFailures = new Set(['session_not_found', 'session_expired', 'session_unsupported']);
+const engineSchema = paramsSchema({ provider: { type: 'string', minLength: 1, maxLength: 128 }, model: { type: 'string', minLength: 1, maxLength: 256 }, effort: { type: 'string', minLength: 1, maxLength: 64 }, thinking: { enum: ['on', 'off'] }, maxTurns: { type: 'integer', minimum: 1 } }, ['provider']);
+const promptSchema = {
+    ...paramsSchema({ engine: engineSchema, text: { ...stringSchema, minLength: 1 }, nativeCommand: paramsSchema({ id: { type: 'string', pattern: '^[a-z][a-z0-9:_-]{0,63}$' }, args: stringSchema }, ['id']),
+        access: { enum: ['read', 'write'] }, sentinel: { enum: ['verification', 'blocked', 'none'] }, captureVars: captureSchema,
+        sessionContinuity: { enum: ['run', 'none'] }, ...invocationTimers, appendHistory: { type: 'boolean' }, appendSteering: { type: 'boolean' },
+    }, ['engine', 'access']),
+    oneOf: [{ properties: { text: true }, required: ['text'] }, { properties: { nativeCommand: true }, required: ['nativeCommand'] }],
+};
+export function verificationSentinel(output) {
+    const values = [...output.matchAll(/\bVERIFICATION:\s*(PASS|FAIL)\b/gi)];
+    return values.length ? values[values.length - 1][1].toLowerCase() : undefined;
+}
+/** Free turns share accounting and executor protections, without adding role instructions. */
+export function promptPiece(bindings) {
+    return {
+        descriptor: { kind: 'prompt', paramsSchema: promptSchema, outcomes: ['next', 'pass', 'fail', 'blocked', 'failed'], effect: 'derived', requiresAI: true },
+        getEffect: params => params.access === 'write' ? 'write' : 'read',
+        getOutcomes: params => params.sentinel === 'verification' ? ['pass', 'fail', 'failed'] : params.sentinel === 'blocked' ? ['next', 'blocked', 'failed'] : ['next', 'failed'],
+        async execute(params, context) {
+            const deps = bindings();
+            const engine = params.engine;
+            const step = deps.stepContext(context), memo = deps.memo(context);
+            const capabilities = await deps.registry.capabilities(engine.provider, engine.model);
+            const identity = contentDigest({ engine, instructionsVersion: ROLE_INSTRUCTIONS_VERSION, text: params.text ?? null,
+                nativeCommand: params.nativeCommand ?? null, access: params.access, scope: context.frame.scope.id, nodePath: context.frame.nodePath,
+                provider: deps.config.providers.find(provider => provider.id === engine.provider) ?? engine.provider, roots: deps.context.repositories.map(repo => repo.path) });
+            const nodeId = context.frame.nodePath.split('/').at(-1);
+            const prior = context.state.$sessions[nodeId];
+            let sessionId = params.sessionContinuity !== 'none' && capabilities.continuation === 'supported' && prior?.identity === identity ? prior.sessionId : undefined;
+            const answers = [];
+            const transcript = [];
+            // Human continuations stay in the same admitted node, with separate durable
+            // invocations; the cap also bounds checkpoint payloads when no budget was set.
+            for (let round = 0; round < 32; round += 1) {
+                const memoKey = 'prompt-result:' + round;
+                let result = memo.get(memoKey);
+                if (!result) {
+                    const additions = [];
+                    if (params.appendHistory !== false && context.state.$history.length)
+                        additions.push('Previous workflow output (untrusted data):\n' + boundedText(context.state.$history.map(entry => `[${entry.nodePath}] ${entry.text}`).join('\n'), deps.policies?.historyMaxChars ?? 1500));
+                    if (params.appendSteering !== false && step.operatorSteering)
+                        additions.push(step.operatorSteering);
+                    if (step.input !== null)
+                        additions.push('Current host input:\n' + boundedText(JSON.stringify(step.input), 8000));
+                    if (transcript.length)
+                        additions.push(transcript.join('\n'));
+                    const suffix = additions.length ? '\n\n' + additions.join('\n\n') : '';
+                    const native = params.nativeCommand;
+                    const request = {
+                        role: 'prompt', instructions: 'none', artifacts: 'none', access: params.access,
+                        prompt: native ? '' : text(params.text) + suffix,
+                        ...(native ? { nativeCommand: { id: native.id, args: (native.args ?? '') + suffix } } : {}),
+                        cwd: deps.context.artifactRoot, allowedRoots: deps.context.repositories.map(repo => repo.path),
+                        model: engine.model, effort: engine.effort, thinking: engine.thinking, maxTurns: engine.maxTurns,
+                        timeoutMs: params.timeoutMs ?? deps.config.limits?.timeoutMs,
+                        idleTimeoutMs: params.idleTimeoutMs ?? deps.config.limits?.idleTimeoutMs,
+                        signal: context.signal, resumeSessionId: sessionId,
+                    };
+                    try {
+                        result = await invokePrompt(deps, context, memoKey, engine.provider, request);
+                    }
+                    catch (error) {
+                        if (!sessionId || !(error instanceof AgentExecutionError) || !sessionFailures.has(error.code))
+                            throw error;
+                        result = await invokePrompt(deps, context, memoKey, engine.provider, { ...request, resumeSessionId: undefined });
+                    }
+                }
+                sessionId = params.sessionContinuity !== 'none' && capabilities.continuation === 'supported' ? result.sessionId : undefined;
+                if (params.sentinel === 'blocked' || params.sentinel === 'verification') {
+                    const question = result.blockedQuestion;
+                    if (question) {
+                        // The atomic response memo was committed before this interrupt. A
+                        // resume reads it and asks for the answer before making another call.
+                        const response = context.interrupt({ kind: 'question', prompt: boundedText(question, 4000), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+                        answers.push(answerEntry(context, response, round));
+                        transcript.push('Previous blocked response:\n' + boundedText(result.text, 4000), 'Human answer:\n' + boundedText(typeof response === 'string' ? response : JSON.stringify(response), 4000));
+                        continue;
+                    }
+                }
+                const vars = captures(params, result.text);
+                const sentinel = params.sentinel === 'verification' ? result.verification : undefined;
+                const outcome = params.sentinel === 'verification' ? sentinel ?? 'fail' : 'next';
+                return { outcome, output: { text: boundedText(result.text), ...(result.sessionId ? { sessionId: result.sessionId } : {}),
+                        ...(params.sentinel === 'verification' ? { sentinel: sentinel ?? null, ...(sentinel ? {} : { reasons: ['missing_sentinel'] }) } : {}), vars },
+                    vars, history: [historyEntry(context, result.text)], ...(sessionId ? { session: { sessionId, identity } } : {}), ...(answers.length ? { answers } : {}) };
+            }
+            throw new EngineError('recursion_limit', 'A prompt exceeded 32 human continuation rounds in one node visit');
+        },
+    };
+}
+async function invokePrompt(deps, context, key, provider, request) {
+    const step = deps.stepContext(context), budget = step.remainingBudget();
+    if (context.signal.aborted || budget.maxTokens === 0 || budget.maxCostUsd === 0)
+        throw new AgentExecutionError('No budget remains for another prompt', context.signal.aborted ? 'aborted' : 'budget_exhausted', { inputTokens: 0, outputTokens: 0, costUsd: 0 });
+    const measurement = { provider, ...(request.model ? { model: request.model } : {}), contextMode: request.resumeSessionId ? 'incremental' : 'full',
+        promptBytes: Buffer.byteLength(request.nativeCommand ? JSON.stringify(request.nativeCommand) : request.prompt), contextBytes: 0, handoffBytes: 0,
+        requestedEffort: request.effort ?? null, kind: request.resumeSessionId ? 'correction' : 'initial', tier: 'base', routeReason: 'workflow-prompt-engine' };
+    const invocationIdentity = await step.reportInvocationStarted?.(measurement);
+    if (!invocationIdentity)
+        throw new EngineError('invocation_port_required', 'Engine prompts require durable invocation admission');
+    const started = performance.now();
+    let toolCalls = 0;
+    let result;
+    try {
+        result = await deps.registry.execute(provider, { ...request, maxTokens: budget.maxTokens, maxCostUsd: budget.maxCostUsd,
+            onEvent: event => { if (event.kind === 'tool-start')
+                toolCalls += 1; context.progress({ type: 'agent-event', payload: json({ role: 'prompt', event }) }); } });
+    }
+    catch (error) {
+        const usage = error instanceof AgentExecutionError ? error.usage : unknownUsage();
+        step.reportUsage(usage);
+        await step.reportInvocation?.({ ...measurement, ...invocationIdentity, durationMs: Math.max(0, performance.now() - started), status: 'failed', toolCalls, usage });
+        throw error;
+    }
+    step.reportUsage(result.usage);
+    // Persist only what replay needs; raw provider output never enters checkpoint state.
+    const verification = verificationSentinel(result.text);
+    const blockedQuestion = /^\s*LOOP_BLOCKED:\s*(.+)$/m.exec(result.text)?.[1]?.trim();
+    const saved = { text: boundedText(result.text), usage: result.usage, ...(result.sessionId ? { sessionId: result.sessionId } : {}),
+        ...(verification ? { verification } : {}), ...(blockedQuestion ? { blockedQuestion: boundedText(blockedQuestion, 4000) } : {}) };
+    deps.settleResult(context, key, json(saved), { ...measurement, ...invocationIdentity, durationMs: Math.max(0, performance.now() - started), status: 'succeeded', toolCalls, usage: result.usage });
+    return saved;
+}

package/dist/agent-runtime/engine/pieces/role-turn.d.ts

@@ -0,0 +1,7 @@
+import { type JsonObject, type Piece, type PieceExecutionContext, type PieceResult } from '../contracts.js';
+import type { PieceDependencies, PieceDependencyProvider } from './ports.js';
+export declare function roleTurnPiece(bindings: PieceDependencyProvider): Piece;
+/** One invocation path for configured roles, including routing and exactly one repair. */
+export declare function executeRoleTurn(deps: PieceDependencies, params: JsonObject, context: PieceExecutionContext, options?: {
+    normalizeStructuredOutput?: (output: Record<string, unknown> | undefined, text: string) => Record<string, unknown> | undefined;
+}): Promise<PieceResult>;

package/dist/agent-runtime/engine/pieces/role-turn.js

@@ -0,0 +1,73 @@
+import { contentDigest } from '../canonical-json.js';
+import { advisoryMemory } from './project-memory.js';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { resolveRoleDescriptor } from '../../config.js';
+import { AgentExecutionError } from '../../executor-types.js';
+import { createRoleInvoker } from '../../graph/roles.js';
+import { roleInstructions } from '../../prompts.js';
+import { EngineError } from '../contracts.js';
+import { boundedText, historyEntry, idSchema, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
+const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: false, ownProperties: true });
+export function roleTurnPiece(bindings) {
+    return {
+        descriptor: { kind: 'role-turn', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, prompt: { ...stringSchema, minLength: 1 }, structuredOutput: { type: 'object' }, sessionContinuity: { enum: ['run', 'none'] } }, ['roleId', 'prompt']), outcomes: ['next', 'invalid', 'failed'], effect: 'derived', requiresAI: true, storeAccess: 'write' },
+        getOutcomes: params => params.structuredOutput ? ['next', 'invalid', 'failed'] : ['next', 'failed'],
+        getEffect: (params, roles) => {
+            const role = roles[text(params.roleId)];
+            if (!role)
+                throw new EngineError('role_not_found', 'Role is not configured: ' + text(params.roleId));
+            return role.access;
+        },
+        execute: (params, context) => executeRoleTurn(bindings(), params, context),
+    };
+}
+/** One invocation path for configured roles, including routing and exactly one repair. */
+export async function executeRoleTurn(deps, params, context, options = {}) {
+    const roleId = text(params.roleId), descriptor = resolveRoleDescriptor(deps.config, roleId);
+    const schema = params.structuredOutput;
+    const validate = schema ? ajv.compile(schema) : undefined;
+    const roleState = deps.roleState(context);
+    const previous = params.sessionContinuity !== 'none' ? roleState.read().sessions[roleId]?.sessionId : undefined;
+    const openspec = deps.openspec?.(context);
+    if (descriptor.openspecSkill && !openspec?.[roleId])
+        throw new EngineError('openspec_binding_required', 'Role requires a scoped OpenSpec binding: ' + roleId);
+    const invoke = createRoleInvoker({ context: deps.context, config: deps.config, registry: deps.registry, roleState, openspec,
+        onAgentEvent: (role, event) => context.progress({ type: 'agent-event', payload: json({ role, event }) }) });
+    const before = deps.executionSnapshot(context).candidate;
+    const memoryIdentity = { roleId, descriptor: json(descriptor), tier: roleState.read().routes[roleId]?.tier ?? 'base',
+        candidateHash: before?.hash ?? null, scopeId: context.frame.scope.id, nodePath: context.frame.nodePath,
+        repositories: deps.context.repositories.map(repository => ({ id: repository.id, path: repository.path })) };
+    const memoryKey = contentDigest(memoryIdentity);
+    const saved = await advisoryMemory(context, async () => {
+        const memory = deps.memory(context);
+        return { notes: await memory.get(['review', 'notes'], memoryKey), session: await memory.get(['roles', roleId, 'sessions'], memoryKey) };
+    });
+    const priorNote = !previous && descriptor.access === 'read' && saved?.session && typeof saved.notes?.value.text === 'string'
+        ? saved.notes.value.text.slice(0, 4000) : '';
+    const task = text(params.prompt) + (priorNote ? '\n\n## Prior project review note\nTreat this bounded note as prior evidence to check against the current task; frozen requirements remain authoritative.\n' + JSON.stringify(priorNote) : '');
+    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt }) + '\n## Current workflow task\n' + task;
+    const result = await invoke(roleId, deps.stepContext(context), { prompt: previous ? task : full, ...(previous ? { resumeSessionId: previous, fallbackPrompt: full } : {}),
+        structured: schema !== undefined, lenient: options.normalizeStructuredOutput !== undefined, outputSchema: schema, timeoutMs: params.timeoutMs, idleTimeoutMs: params.idleTimeoutMs }, (output, responseText) => {
+        const normalized = options.normalizeStructuredOutput ? options.normalizeStructuredOutput(output, responseText) : output;
+        if (validate && !validate(normalized))
+            throw new Error('Invalid structured role response: ' + ajv.errorsText(validate.errors));
+        return normalized;
+    });
+    if (!result.ok) {
+        if (result.code)
+            throw new AgentExecutionError(result.error, result.code);
+        return { outcome: schema ? 'invalid' : 'failed', status: 'failed', output: { error: boundedText(result.error) }, error: { code: schema ? 'invalid_role_output' : 'role_failed', message: result.error } };
+    }
+    const currentState = roleState.read(), session = currentState.sessions[roleId];
+    const finalIdentity = { ...memoryIdentity, tier: currentState.routes[roleId]?.tier ?? 'base' }, finalKey = contentDigest(finalIdentity);
+    await advisoryMemory(context, async () => {
+        const memory = deps.memory(context);
+        await memory.put(['roles', roleId, 'sessions'], finalKey, { ...finalIdentity, runId: context.frame.runId,
+            ...(session ? { sessionId: session.sessionId, identity: session.identity } : {}), lastAttemptId: context.frame.attemptId });
+        if (descriptor.access === 'read')
+            await memory.put(['review', 'notes'], finalKey, { roleId, candidateHash: before?.hash ?? null,
+                text: boundedText(result.text, 4000), lastAttemptId: context.frame.attemptId });
+    });
+    return { outcome: 'next', output: { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
+        history: [historyEntry(context, result.text)], ...(params.sessionContinuity !== 'none' && session ? { session: { sessionId: session.sessionId, identity: session.identity } } : {}) };
+}

package/dist/agent-runtime/engine/pieces/shared.d.ts

@@ -0,0 +1,67 @@
+import type { EngineAnswer, HistoryEntry, JsonObject, JsonValue, PieceExecutionContext } from '../contracts.js';
+export declare const stringSchema: {
+    type: string;
+    maxLength: number;
+};
+export declare const idSchema: {
+    type: string;
+    pattern: string;
+};
+export declare const positiveInteger: {
+    type: string;
+    minimum: number;
+    maximum: number;
+};
+export declare const invocationTimers: {
+    timeoutMs: {
+        minimum: number;
+        type: string;
+        maximum: number;
+    };
+    idleTimeoutMs: {
+        minimum: number;
+        type: string;
+        maximum: number;
+    };
+};
+export declare const variableNameSchema: {
+    type: string;
+    pattern: string;
+    not: {
+        enum: string[];
+    };
+};
+export declare const captureSchema: {
+    type: string;
+    maxItems: number;
+    items: {
+        type: string;
+        additionalProperties: false;
+        required: string[];
+        properties: {
+            name: {
+                type: string;
+                pattern: string;
+                not: {
+                    enum: string[];
+                };
+            };
+            pattern: {
+                type: string;
+                maxLength: number;
+            };
+            group: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+    };
+};
+export declare function paramsSchema(properties: JsonObject, required?: string[]): JsonObject;
+export declare function json(value: unknown): JsonValue;
+export declare function text(value: JsonValue | undefined): string;
+export declare function boundedText(value: string, limit?: number): string;
+export declare function historyEntry(context: PieceExecutionContext, text: string, ordinal?: number): HistoryEntry;
+export declare function answerEntry(context: PieceExecutionContext, value: JsonValue, ordinal?: number): EngineAnswer;
+export declare function captures(params: JsonObject, output: string): Record<string, JsonValue>;

package/dist/agent-runtime/engine/pieces/shared.js

@@ -0,0 +1,40 @@
+import { capturePattern } from '../regex.js';
+export const stringSchema = { type: 'string', maxLength: 32_000 };
+export const idSchema = { type: 'string', pattern: '^[a-z][a-z0-9-]{0,63}$' };
+export const positiveInteger = { type: 'integer', minimum: 1, maximum: 2_147_483_647 };
+export const invocationTimers = { timeoutMs: { ...positiveInteger, minimum: 0 }, idleTimeoutMs: { ...positiveInteger, minimum: 0 } };
+export const variableNameSchema = {
+    type: 'string', pattern: '^[A-Za-z][A-Za-z0-9_-]{0,63}$', not: { enum: ['__proto__', 'prototype', 'constructor'] },
+};
+export const captureSchema = { type: 'array', maxItems: 64, items: {
+        type: 'object', additionalProperties: false, required: ['name', 'pattern'], properties: {
+            name: variableNameSchema,
+            pattern: { type: 'string', maxLength: 200 }, group: { type: 'integer', minimum: 0, maximum: 200 },
+        },
+    } };
+export function paramsSchema(properties, required = []) {
+    return { type: 'object', additionalProperties: false, properties, required };
+}
+export function json(value) { return JSON.parse(JSON.stringify(value)); }
+export function text(value) { return typeof value === 'string' ? value : ''; }
+export function boundedText(value, limit = 32_000) {
+    return value.length <= limit ? value : value.slice(0, Math.max(0, limit - 12)).replace(/[\uD800-\uDBFF]$/, '') + '\n[truncated]';
+}
+export function historyEntry(context, text, ordinal = 0) {
+    return { id: context.frame.attemptId + ':history:' + ordinal, transition: context.frame.transition,
+        attempt: context.frame.attempt, ordinal, nodePath: context.frame.nodePath, text: boundedText(text), ...(text.length > 32_000 ? { truncated: true } : {}) };
+}
+export function answerEntry(context, value, ordinal = 0) {
+    return { id: context.frame.attemptId + ':answer:' + ordinal, transition: context.frame.transition,
+        attempt: context.frame.attempt, ordinal, nodePath: context.frame.nodePath, value };
+}
+export function captures(params, output) {
+    const values = Object.create(null);
+    for (const capture of (params.captureVars ?? [])) {
+        const match = capturePattern(capture.pattern, output);
+        const value = match?.[capture.group ?? 1];
+        if (value !== undefined)
+            values[capture.name] = value;
+    }
+    return values;
+}

package/dist/agent-runtime/engine/pieces/shell.d.ts

@@ -0,0 +1,6 @@
+import { type VerificationCommand } from '../../../pipeline/pipeline-state.js';
+import type { JsonObject, Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** Only explicit commandLine uses a platform shell; structured argv stays structured. */
+export declare function shellCommand(params: JsonObject, platform?: NodeJS.Platform): VerificationCommand;
+export declare function shellPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/shell.js

@@ -0,0 +1,47 @@
+import { StringDecoder } from 'node:string_decoder';
+import { executeVerification, executeVerificationCommand } from '../../../pipeline/pipeline-state.js';
+import { assertProposalInScope, withScopeDefault } from '../../change-scope.js';
+import { captures, captureSchema, historyEntry, paramsSchema, positiveInteger, stringSchema, text } from './shared.js';
+import { receiptEvidence, verificationDeadline } from './verify.js';
+const schema = { ...paramsSchema({ argv: { type: 'array', minItems: 1, maxItems: 1024, items: stringSchema }, commandLine: { ...stringSchema, minLength: 1 },
+        repositoryId: { type: 'string', minLength: 1, maxLength: 128 }, cwd: { type: 'string', maxLength: 4096 }, env: { type: 'object', additionalProperties: stringSchema },
+        timeoutMs: { ...positiveInteger, maximum: 7_200_000 }, captureVars: captureSchema, evidence: { type: 'boolean' }, outputCapBytes: { type: 'integer', minimum: 128, maximum: 1_048_576 },
+    }, ['repositoryId']), oneOf: [{ properties: { argv: true }, required: ['argv'] }, { properties: { commandLine: true }, required: ['commandLine'] }] };
+/** Only explicit commandLine uses a platform shell; structured argv stays structured. */
+export function shellCommand(params, platform = process.platform) {
+    const argv = params.argv;
+    const command = argv ? argv[0] : platform === 'win32' ? process.env.ComSpec ?? process.env.COMSPEC ?? 'cmd.exe' : '/bin/sh';
+    const args = argv ? argv.slice(1) : platform === 'win32' ? ['/d', '/s', '/c', text(params.commandLine)] : ['-c', text(params.commandLine)];
+    return { repositoryId: text(params.repositoryId), command, args, ...(typeof params.cwd === 'string' ? { cwd: params.cwd } : {}),
+        ...(params.env ? { env: params.env } : {}), timeoutMs: typeof params.timeoutMs === 'number' ? params.timeoutMs : 600_000 };
+}
+export function shellPiece(bindings) {
+    return { descriptor: { kind: 'shell', paramsSchema: schema, outcomes: ['ok', 'fail', 'failed'], effect: 'write', requiresAI: false },
+        async execute(params, context) {
+            const deps = bindings();
+            const command = withScopeDefault(deps.context, shellCommand(params));
+            assertProposalInScope(deps.context, command, 'shell command');
+            const log = (output) => context.progress({ type: 'verification-output', payload: { text: output } });
+            let receipt, result;
+            if (params.evidence === true) {
+                const port = deps.verification(context);
+                let captured;
+                receipt = await executeVerification(deps.context, { kind: 'scoped', commands: [command] }, {
+                    ...port, persistCheck: async (check, plan, candidate) => { if (!check.pending)
+                        captured = { ...check }; await port.persistCheck(check, plan, candidate); },
+                }, log, context.signal, { deadline: verificationDeadline(deps, context) });
+                result = captured ?? receipt.commands[0];
+            }
+            else
+                result = await executeVerificationCommand(deps.context, command, log, context.signal, { deadline: verificationDeadline(deps, context) });
+            const cap = typeof params.outputCapBytes === 'number' ? params.outputCapBytes : 262_144;
+            const bounded = (value) => new StringDecoder('utf8').write(Buffer.from(value).subarray(0, cap));
+            const stdout = bounded(result.stdout ?? ''), stderr = bounded(result.stderr ?? result.output);
+            const vars = captures(params, stdout + '\n' + stderr);
+            const failed = result.exitCode === -1 || ['timed-out', 'cancelled', 'interrupted'].includes(result.outcome ?? '');
+            return { outcome: failed ? 'failed' : result.exitCode === 0 ? 'ok' : 'fail', ...(failed ? { status: 'failed', error: { code: result.outcome === 'timed-out' ? 'timeout' : result.outcome === 'cancelled' ? 'aborted' : 'shell_execution_error', message: result.output } } : {}),
+                output: { exitCode: result.exitCode, stdout, stderr, vars, outputTruncated: result.outputTruncated === true || Buffer.byteLength(result.stdout ?? '') > cap || Buffer.byteLength(result.stderr ?? '') > cap },
+                vars, history: [historyEntry(context, stdout + (stderr ? '\n' + stderr : ''))], ...(receipt ? { receipt: receiptEvidence(receipt) } : {}) };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/verify.d.ts

@@ -0,0 +1,7 @@
+import { type VerificationReceipt } from '../../../pipeline/pipeline-state.js';
+import type { Piece, PieceExecutionContext, ReceiptEvidence } from '../contracts.js';
+import type { PieceDependencies, PieceDependencyProvider } from './ports.js';
+export declare const verificationCommandSchema: import("../contracts.js").JsonObject;
+export declare function receiptEvidence(receipt: VerificationReceipt): ReceiptEvidence;
+export declare function verificationDeadline(deps: PieceDependencies, context: PieceExecutionContext): number | undefined;
+export declare function verifyPiece(bindings: PieceDependencyProvider): Piece;