@webpresso/agent-kit 0.21.0

package/dist/esm/blueprint/execution/progress-bridge.js

@@ -0,0 +1,302 @@
+import { z } from 'zod';
+import { parseBlueprint } from '#core/parser';
+import { evidenceListSchema } from '#evidence.js';
+import { applyBlueprintLifecycle } from '#lifecycle/engine';
+import { assertAllTasksHaveCanonicalPassingEvidence } from '#verification.js';
+import { writeBlueprintExecutionMetadata } from './metadata.js';
+import { executionBackendSchema, DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, runtimeStateSnapshotSchema, runtimeStateStatusSchema, } from './types.js';
+export const omxTeamTaskStatusSchema = z.enum([
+    'pending',
+    'blocked',
+    'in_progress',
+    'completed',
+    'failed',
+]);
+export const omxTeamTaskSnapshotSchema = z.object({
+    description: z.string().optional(),
+    error: z.string().optional(),
+    evidence: evidenceListSchema.optional(),
+    result: z.string().optional(),
+    runtimeTaskId: z.string().min(1),
+    status: omxTeamTaskStatusSchema,
+    subject: z.string().min(1),
+});
+export const blueprintProgressBridgeTaskBindingSchema = z.object({
+    blueprintTaskId: z.string().min(1),
+    runtimeTaskId: z.string().min(1),
+    title: z.string().min(1),
+});
+export const blueprintProgressBridgeStateSchema = z.object({
+    backend: executionBackendSchema,
+    blueprintPath: z.string().min(1),
+    blueprintSlug: z.string().min(1),
+    executionId: z.string().min(1),
+    tasks: z.array(blueprintProgressBridgeTaskBindingSchema),
+    updatedAt: z.string().min(1),
+});
+function extractBlueprintTaskId(snapshot) {
+    const candidate = [snapshot.subject, snapshot.description].filter(Boolean).join('\n');
+    const match = candidate.match(/\bTask\s+(\d+(?:\.\d+)+)\s*:/i);
+    return match?.[1] ?? null;
+}
+function buildFailureReason(snapshot) {
+    return (snapshot.error?.trim() ||
+        snapshot.result?.trim() ||
+        snapshot.description?.trim() ||
+        `OMX runtime task ${snapshot.runtimeTaskId} reported ${snapshot.status}.`);
+}
+function summarizeRuntimeStatus(tasks) {
+    if (!tasks.length) {
+        return runtimeStateStatusSchema.parse('pending');
+    }
+    const statuses = tasks.map((task) => task.status);
+    if (statuses.includes('failed')) {
+        return 'failed';
+    }
+    if (statuses.includes('blocked')) {
+        return 'blocked';
+    }
+    if (statuses.every((status) => status === 'completed')) {
+        return 'completed';
+    }
+    if (statuses.some((status) => status === 'in_progress' || status === 'completed')) {
+        return 'running';
+    }
+    return 'pending';
+}
+function applyProjectedIntent(taskStatuses, intent) {
+    if (intent.type === 'finalize') {
+        return;
+    }
+    if (!('taskId' in intent)) {
+        return;
+    }
+    const nextStatus = intent.type === 'task_start'
+        ? 'in_progress'
+        : intent.type === 'task_verify'
+            ? 'done'
+            : intent.type === 'task_block'
+                ? 'blocked'
+                : 'todo';
+    taskStatuses.set(intent.taskId, nextStatus);
+}
+export function buildBlueprintProgressBridgeState(spec, executionId, runtimeTasks, updatedAt) {
+    const bindings = spec.tasks.map((task) => {
+        const runtimeTask = runtimeTasks.find((candidate) => extractBlueprintTaskId(candidate) === task.id);
+        if (!runtimeTask) {
+            throw new Error(`Could not map runtime task for blueprint task ${task.id}. Ensure OMX team launch uses Task <id>: prefixes.`);
+        }
+        return {
+            blueprintTaskId: task.id,
+            runtimeTaskId: runtimeTask.runtimeTaskId,
+            title: task.title,
+        };
+    });
+    const duplicates = bindings
+        .map((binding) => binding.runtimeTaskId)
+        .filter((runtimeTaskId, index, values) => values.indexOf(runtimeTaskId) !== index);
+    if (duplicates.length > 0) {
+        throw new Error(`Duplicate runtime task bindings detected: ${duplicates.join(', ')}`);
+    }
+    return blueprintProgressBridgeStateSchema.parse({
+        backend: spec.backend,
+        blueprintPath: spec.blueprintPath,
+        blueprintSlug: spec.blueprintSlug,
+        executionId,
+        tasks: bindings,
+        updatedAt,
+    });
+}
+export function projectBlueprintLifecycleFromRuntime(blueprint, bridge, runtimeTasks) {
+    const runtimeTasksById = new Map(runtimeTasks.map((task) => [task.runtimeTaskId, task]));
+    const projectedStatuses = new Map(blueprint.tasks.map((task) => [task.id, task.status]));
+    const intents = [];
+    for (const binding of bridge.tasks) {
+        const runtimeTask = runtimeTasksById.get(binding.runtimeTaskId);
+        const blueprintTask = blueprint.tasks.find((task) => task.id === binding.blueprintTaskId);
+        if (!runtimeTask || !blueprintTask) {
+            continue;
+        }
+        const currentStatus = projectedStatuses.get(binding.blueprintTaskId) ?? blueprintTask.status;
+        const intent = runtimeTask.status === 'in_progress'
+            ? currentStatus === 'todo' || currentStatus === 'blocked'
+                ? {
+                    type: 'task_start',
+                    taskId: binding.blueprintTaskId,
+                }
+                : null
+            : runtimeTask.status === 'completed'
+                ? currentStatus !== 'done'
+                    ? taskVerifyIntent(binding.blueprintTaskId, runtimeTask.evidence) ??
+                        {
+                            type: 'task_block',
+                            taskId: binding.blueprintTaskId,
+                            reason: buildMissingEvidenceReason(binding.blueprintTaskId),
+                        }
+                    : null
+                : runtimeTask.status === 'blocked' || runtimeTask.status === 'failed'
+                    ? currentStatus !== 'done'
+                        ? {
+                            type: 'task_block',
+                            taskId: binding.blueprintTaskId,
+                            reason: buildFailureReason(runtimeTask),
+                        }
+                        : null
+                    : null;
+        if (!intent) {
+            continue;
+        }
+        intents.push(intent);
+        applyProjectedIntent(projectedStatuses, intent);
+    }
+    const status = summarizeRuntimeStatus(runtimeTasks);
+    const allProjectedDone = bridge.tasks.length > 0 &&
+        bridge.tasks.every((binding) => projectedStatuses.get(binding.blueprintTaskId) === 'done');
+    const allProjectedDoneHavePassingEvidence = allProjectedDone &&
+        bridge.tasks.every((binding) => {
+            if (projectedStatuses.get(binding.blueprintTaskId) !== 'done') {
+                return true;
+            }
+            const runtimeTask = runtimeTasksById.get(binding.runtimeTaskId);
+            return runtimeTask?.status === 'completed' && hasPassingEvidence(runtimeTask.evidence);
+        });
+    if (status === 'completed' &&
+        allProjectedDone &&
+        allProjectedDoneHavePassingEvidence &&
+        blueprint.status !== 'completed') {
+        intents.push({ type: 'finalize' });
+    }
+    return { intents, status };
+}
+export function normalizeOmxTeamTaskSnapshot(input) {
+    return omxTeamTaskSnapshotSchema.parse({
+        description: typeof input.description === 'string' ? input.description : undefined,
+        error: typeof input.error === 'string' ? input.error : undefined,
+        evidence: Array.isArray(input.evidence) ? input.evidence : undefined,
+        result: typeof input.result === 'string' ? input.result : undefined,
+        runtimeTaskId: typeof input.id === 'string' ? input.id : String(input.id ?? ''),
+        status: input.status,
+        subject: typeof input.subject === 'string' ? input.subject : '',
+    });
+}
+export function sanitizeBlueprintExecutionId(executionId) {
+    return executionId.trim().replace(/[^a-zA-Z0-9_-]+/g, '-');
+}
+export function resolveBlueprintProgressBridgePath(runtimeStateRoot, backend, executionId) {
+    return [
+        runtimeStateRoot.replace(/\/+$/u, ''),
+        'blueprint-execution',
+        backend,
+        `${sanitizeBlueprintExecutionId(executionId)}.json`,
+    ]
+        .filter(Boolean)
+        .join('/');
+}
+function shouldStartBlueprint(blueprint, snapshot) {
+    return ((snapshot.status === 'running' ||
+        snapshot.status === 'blocked' ||
+        snapshot.status === 'failed' ||
+        snapshot.status === 'completed') &&
+        (blueprint.status === 'draft' ||
+            blueprint.status === 'planned' ||
+            blueprint.status === 'parked'));
+}
+function buildBlockedReason(snapshot) {
+    const statusPrefix = snapshot.status === 'failed' ? 'Runtime failed' : 'Runtime blocked';
+    const taskSuffix = snapshot.taskId ? ` for task ${snapshot.taskId}` : '';
+    return `${statusPrefix} in ${snapshot.backend} execution ${snapshot.executionId}${taskSuffix}.`;
+}
+function buildMissingEvidenceReason(taskId) {
+    return `Runtime reported task ${taskId} completed without task-local verification evidence.`;
+}
+function hasPassingEvidence(evidence) {
+    return Array.isArray(evidence) && evidence.some((item) => item.result === 'pass');
+}
+function taskVerifyIntent(taskId, evidence) {
+    if (!hasPassingEvidence(evidence))
+        return null;
+    return { type: 'task_verify', taskId, evidence };
+}
+function shouldFinalizeBlueprint(markdown, blueprint, snapshot) {
+    if (snapshot.status !== 'completed' ||
+        blueprint.status === 'completed' ||
+        blueprint.status === 'archived' ||
+        blueprint.tasks.length === 0 ||
+        !blueprint.tasks.every((task) => task.status === 'done')) {
+        return false;
+    }
+    try {
+        assertAllTasksHaveCanonicalPassingEvidence(markdown, blueprint.tasks.map((task) => task.id));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function applyIntent(markdown, slug, appliedTransitions, intent) {
+    const result = applyBlueprintLifecycle(markdown, slug, intent);
+    appliedTransitions.push(intent.type);
+    return result.markdown;
+}
+export function runtimeSnapshotPathForExecution(executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT) {
+    return `${runtimeStateRoot}/blueprint-executions/${encodeURIComponent(executionId)}.json`;
+}
+export function applyRuntimeProgressSnapshot(markdown, slug, input) {
+    const snapshot = runtimeStateSnapshotSchema.parse(input);
+    const execution = {
+        backend: snapshot.backend,
+        executionId: snapshot.executionId,
+        status: snapshot.status,
+        updatedAt: snapshot.updatedAt,
+    };
+    const appliedTransitions = [];
+    let nextMarkdown = writeBlueprintExecutionMetadata(markdown, execution);
+    let nextBlueprint = parseBlueprint(nextMarkdown, slug);
+    if (shouldStartBlueprint(nextBlueprint, snapshot)) {
+        nextMarkdown = applyIntent(nextMarkdown, slug, appliedTransitions, { type: 'start' });
+        nextBlueprint = parseBlueprint(nextMarkdown, slug);
+    }
+    if (snapshot.taskId) {
+        const task = nextBlueprint.tasks.find((entry) => entry.id === snapshot.taskId);
+        if (!task) {
+            throw new Error(`Task ${snapshot.taskId} not found in blueprint ${slug}`);
+        }
+        if (snapshot.status === 'running' && task.status === 'todo') {
+            nextMarkdown = applyIntent(nextMarkdown, slug, appliedTransitions, {
+                type: 'task_start',
+                taskId: snapshot.taskId,
+            });
+            nextBlueprint = parseBlueprint(nextMarkdown, slug);
+        }
+        if ((snapshot.status === 'blocked' || snapshot.status === 'failed') &&
+            task.status !== 'done' &&
+            task.status !== 'blocked') {
+            nextMarkdown = applyIntent(nextMarkdown, slug, appliedTransitions, {
+                type: 'task_block',
+                taskId: snapshot.taskId,
+                reason: buildBlockedReason(snapshot),
+            });
+            nextBlueprint = parseBlueprint(nextMarkdown, slug);
+        }
+        if (snapshot.status === 'completed' && task.status !== 'done') {
+            const verifyIntent = taskVerifyIntent(snapshot.taskId, snapshot.evidence);
+            nextMarkdown = applyIntent(nextMarkdown, slug, appliedTransitions, verifyIntent ?? {
+                type: 'task_block',
+                taskId: snapshot.taskId,
+                reason: buildMissingEvidenceReason(snapshot.taskId),
+            });
+            nextBlueprint = parseBlueprint(nextMarkdown, slug);
+        }
+    }
+    if (shouldFinalizeBlueprint(nextMarkdown, nextBlueprint, snapshot)) {
+        nextMarkdown = applyIntent(nextMarkdown, slug, appliedTransitions, { type: 'finalize' });
+        nextBlueprint = parseBlueprint(nextMarkdown, slug);
+    }
+    return {
+        appliedTransitions,
+        blueprint: nextBlueprint,
+        execution,
+        markdown: nextMarkdown,
+    };
+}
+//# sourceMappingURL=progress-bridge.js.map

package/dist/esm/blueprint/execution/types.d.ts

@@ -0,0 +1,233 @@
+import { z } from 'zod';
+import { type Evidence } from '#evidence.js';
+import { type BlueprintExecutionBackend } from '#types/execution-backend.js';
+export { executionBackendSchema, type BlueprintExecutionBackend } from '#types/execution-backend.js';
+export declare const blueprintExecutionModeSchema: z.ZodEnum<{
+    durable: "durable";
+    interactive: "interactive";
+}>;
+export type BlueprintExecutionMode = z.infer<typeof blueprintExecutionModeSchema>;
+export declare const blueprintTaskBackendHintsSchema: z.ZodObject<{
+    buildHeavy: z.ZodOptional<z.ZodBoolean>;
+    longRunning: z.ZodOptional<z.ZodBoolean>;
+    testHeavy: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type BlueprintTaskBackendHints = z.infer<typeof blueprintTaskBackendHintsSchema>;
+export declare const blueprintTaskLaunchSpecSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    verificationCommands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    concurrencyGroup: z.ZodOptional<z.ZodString>;
+    backendHints: z.ZodDefault<z.ZodObject<{
+        buildHeavy: z.ZodOptional<z.ZodBoolean>;
+        longRunning: z.ZodOptional<z.ZodBoolean>;
+        testHeavy: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BlueprintTaskLaunchSpec = z.infer<typeof blueprintTaskLaunchSpecSchema>;
+export declare const blueprintExecutionPolicySchema: z.ZodObject<{
+    maxParallelism: z.ZodOptional<z.ZodNumber>;
+    preferWorktree: z.ZodDefault<z.ZodBoolean>;
+    requireVerificationForCompletion: z.ZodDefault<z.ZodBoolean>;
+    runtimeStateRoot: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type BlueprintExecutionPolicy = z.infer<typeof blueprintExecutionPolicySchema>;
+export declare const blueprintLaunchSpecSchema: z.ZodObject<{
+    backend: z.ZodEnum<{
+        "omx-team": "omx-team";
+        "omx-pll-interactive": "omx-pll-interactive";
+        "claude-subagent": "claude-subagent";
+        "codex-exec": "codex-exec";
+        "local-worktree": "local-worktree";
+    }>;
+    blueprintPath: z.ZodString;
+    blueprintSlug: z.ZodString;
+    mode: z.ZodEnum<{
+        durable: "durable";
+        interactive: "interactive";
+    }>;
+    policy: z.ZodObject<{
+        maxParallelism: z.ZodOptional<z.ZodNumber>;
+        preferWorktree: z.ZodDefault<z.ZodBoolean>;
+        requireVerificationForCompletion: z.ZodDefault<z.ZodBoolean>;
+        runtimeStateRoot: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        verificationCommands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        concurrencyGroup: z.ZodOptional<z.ZodString>;
+        backendHints: z.ZodDefault<z.ZodObject<{
+            buildHeavy: z.ZodOptional<z.ZodBoolean>;
+            longRunning: z.ZodOptional<z.ZodBoolean>;
+            testHeavy: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BlueprintLaunchSpec = z.infer<typeof blueprintLaunchSpecSchema>;
+export declare const blueprintExecutionSpecSchema: z.ZodObject<{
+    backend: z.ZodEnum<{
+        "omx-team": "omx-team";
+        "omx-pll-interactive": "omx-pll-interactive";
+        "claude-subagent": "claude-subagent";
+        "codex-exec": "codex-exec";
+        "local-worktree": "local-worktree";
+    }>;
+    blueprintPath: z.ZodString;
+    blueprintSlug: z.ZodString;
+    mode: z.ZodEnum<{
+        durable: "durable";
+        interactive: "interactive";
+    }>;
+    policy: z.ZodObject<{
+        maxParallelism: z.ZodOptional<z.ZodNumber>;
+        preferWorktree: z.ZodDefault<z.ZodBoolean>;
+        requireVerificationForCompletion: z.ZodDefault<z.ZodBoolean>;
+        runtimeStateRoot: z.ZodDefault<z.ZodString>;
+    }, z.core.$strip>;
+    tasks: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        dependsOn: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        files: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        verificationCommands: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        concurrencyGroup: z.ZodOptional<z.ZodString>;
+        backendHints: z.ZodDefault<z.ZodObject<{
+            buildHeavy: z.ZodOptional<z.ZodBoolean>;
+            longRunning: z.ZodOptional<z.ZodBoolean>;
+            testHeavy: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BlueprintExecutionSpec = BlueprintLaunchSpec;
+export declare const blueprintDerivedHandoffCodexGoalSchema: z.ZodObject<{
+    objective_hash: z.ZodOptional<z.ZodString>;
+    status_at_handoff: z.ZodOptional<z.ZodString>;
+    thread_id: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type BlueprintDerivedHandoffCodexGoal = z.infer<typeof blueprintDerivedHandoffCodexGoalSchema>;
+export declare const blueprintDerivedHandoffOmxContextSchema: z.ZodObject<{
+    execution_id: z.ZodOptional<z.ZodString>;
+    goal_id: z.ZodOptional<z.ZodString>;
+    ledger_path: z.ZodOptional<z.ZodString>;
+    mode: z.ZodOptional<z.ZodString>;
+    plan_path: z.ZodOptional<z.ZodString>;
+    session_id: z.ZodOptional<z.ZodString>;
+    state_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export type BlueprintDerivedHandoffOmxContext = z.infer<typeof blueprintDerivedHandoffOmxContextSchema>;
+export declare const blueprintDerivedHandoffSchema: z.ZodObject<{
+    blueprint_path: z.ZodString;
+    blueprint_slug: z.ZodString;
+    codex_goal: z.ZodOptional<z.ZodObject<{
+        objective_hash: z.ZodOptional<z.ZodString>;
+        status_at_handoff: z.ZodOptional<z.ZodString>;
+        thread_id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    content_hash: z.ZodString;
+    derived: z.ZodLiteral<true>;
+    generated_at: z.ZodOptional<z.ZodString>;
+    generated_by: z.ZodOptional<z.ZodString>;
+    head_at_ingest: z.ZodNullable<z.ZodString>;
+    "non-authoritative": z.ZodLiteral<true>;
+    omx_context: z.ZodOptional<z.ZodObject<{
+        execution_id: z.ZodOptional<z.ZodString>;
+        goal_id: z.ZodOptional<z.ZodString>;
+        ledger_path: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodString>;
+        plan_path: z.ZodOptional<z.ZodString>;
+        session_id: z.ZodOptional<z.ZodString>;
+        state_paths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type BlueprintDerivedHandoff = z.infer<typeof blueprintDerivedHandoffSchema>;
+export declare const runtimeStateStatusSchema: z.ZodEnum<{
+    pending: "pending";
+    running: "running";
+    blocked: "blocked";
+    completed: "completed";
+    failed: "failed";
+    stopped: "stopped";
+}>;
+export type RuntimeStateStatus = z.infer<typeof runtimeStateStatusSchema>;
+export declare const runtimeStateSnapshotSchema: z.ZodObject<{
+    backend: z.ZodEnum<{
+        "omx-team": "omx-team";
+        "omx-pll-interactive": "omx-pll-interactive";
+        "claude-subagent": "claude-subagent";
+        "codex-exec": "codex-exec";
+        "local-worktree": "local-worktree";
+    }>;
+    evidence: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        command: z.ZodString;
+        exit_code: z.ZodNumber;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+        }>;
+        ts: z.ZodString;
+        agent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"test">;
+    }, z.core.$strict>, z.ZodObject<{
+        target_files: z.ZodArray<z.ZodString>;
+        command: z.ZodString;
+        exit_code: z.ZodNumber;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+        }>;
+        ts: z.ZodString;
+        agent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"integration">;
+    }, z.core.$strict>, z.ZodObject<{
+        audit_kind: z.ZodString;
+        passed: z.ZodBoolean;
+        command: z.ZodOptional<z.ZodString>;
+        exit_code: z.ZodOptional<z.ZodNumber>;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+        }>;
+        ts: z.ZodString;
+        agent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"audit">;
+    }, z.core.$strict>, z.ZodObject<{
+        actor: z.ZodString;
+        description: z.ZodString;
+        allow_manual: z.ZodLiteral<true>;
+        log_excerpt: z.ZodString;
+        result: z.ZodEnum<{
+            pass: "pass";
+            fail: "fail";
+        }>;
+        ts: z.ZodString;
+        agent: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"manual">;
+    }, z.core.$strict>], "kind">>>;
+    executionId: z.ZodString;
+    status: z.ZodEnum<{
+        pending: "pending";
+        running: "running";
+        blocked: "blocked";
+        completed: "completed";
+        failed: "failed";
+        stopped: "stopped";
+    }>;
+    taskId: z.ZodOptional<z.ZodString>;
+    updatedAt: z.ZodString;
+}, z.core.$strip>;
+export type RuntimeStateSnapshot = z.infer<typeof runtimeStateSnapshotSchema>;
+export type RuntimeStateSnapshotEvidence = Evidence;
+export interface BlueprintExecutionAdapter {
+    readonly backend: BlueprintExecutionBackend;
+    buildLaunchCommand(spec: BlueprintLaunchSpec): {
+        args: string[];
+        command: string;
+    };
+}
+export declare const DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT = ".omx/state";
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/blueprint/execution/types.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+import { evidenceListSchema } from '#evidence.js';
+import { executionBackendSchema } from '#types/execution-backend.js';
+const LEGACY_BLUEPRINT_ROOT_SEGMENT = 'webpresso/blueprints/';
+const GENERIC_BLUEPRINT_ROOT_SEGMENT = 'blueprints/';
+const DEFAULT_RUNTIME_STATE_ROOT = '.omx/state';
+function isBlueprintPath(path) {
+    return (path.includes(LEGACY_BLUEPRINT_ROOT_SEGMENT) ||
+        path.startsWith(LEGACY_BLUEPRINT_ROOT_SEGMENT) ||
+        path.includes(`/${GENERIC_BLUEPRINT_ROOT_SEGMENT}`) ||
+        path.startsWith(GENERIC_BLUEPRINT_ROOT_SEGMENT));
+}
+function isOmxStatePath(path) {
+    return path === DEFAULT_RUNTIME_STATE_ROOT || path.startsWith(`${DEFAULT_RUNTIME_STATE_ROOT}/`);
+}
+export { executionBackendSchema } from '#types/execution-backend.js';
+export const blueprintExecutionModeSchema = z.enum(['durable', 'interactive']);
+export const blueprintTaskBackendHintsSchema = z.object({
+    buildHeavy: z.boolean().optional(),
+    longRunning: z.boolean().optional(),
+    testHeavy: z.boolean().optional(),
+});
+export const blueprintTaskLaunchSpecSchema = z.object({
+    id: z.string().min(1),
+    title: z.string().min(1),
+    dependsOn: z.array(z.string()).default([]),
+    files: z.array(z.string()).default([]),
+    verificationCommands: z.array(z.string()).default([]),
+    concurrencyGroup: z.string().optional(),
+    backendHints: blueprintTaskBackendHintsSchema.default({}),
+});
+export const blueprintExecutionPolicySchema = z.object({
+    maxParallelism: z.number().int().positive().optional(),
+    preferWorktree: z.boolean().default(false),
+    requireVerificationForCompletion: z.boolean().default(true),
+    runtimeStateRoot: z
+        .string()
+        .default(DEFAULT_RUNTIME_STATE_ROOT)
+        .refine(isOmxStatePath, 'runtimeStateRoot must stay under .omx/state'),
+});
+export const blueprintLaunchSpecSchema = z.object({
+    backend: executionBackendSchema,
+    blueprintPath: z
+        .string()
+        .min(1)
+        .refine(isBlueprintPath, 'blueprintPath must point at blueprints/ or webpresso/blueprints'),
+    blueprintSlug: z.string().min(1),
+    mode: blueprintExecutionModeSchema,
+    policy: blueprintExecutionPolicySchema,
+    tasks: z.array(blueprintTaskLaunchSpecSchema),
+});
+export const blueprintExecutionSpecSchema = blueprintLaunchSpecSchema;
+export const blueprintDerivedHandoffCodexGoalSchema = z.object({
+    objective_hash: z.string().min(1).optional(),
+    status_at_handoff: z.string().min(1).optional(),
+    thread_id: z.string().min(1).optional(),
+});
+export const blueprintDerivedHandoffOmxContextSchema = z.object({
+    execution_id: z.string().min(1).optional(),
+    goal_id: z.string().min(1).optional(),
+    ledger_path: z.string().min(1).optional(),
+    mode: z.string().min(1).optional(),
+    plan_path: z.string().min(1).optional(),
+    session_id: z.string().min(1).optional(),
+    state_paths: z.array(z.string().min(1)).optional(),
+});
+export const blueprintDerivedHandoffSchema = z.object({
+    blueprint_path: z
+        .string()
+        .min(1)
+        .refine(isBlueprintPath, 'blueprint_path must point at blueprints/ or webpresso/blueprints'),
+    blueprint_slug: z.string().min(1),
+    codex_goal: blueprintDerivedHandoffCodexGoalSchema.optional(),
+    content_hash: z.string().min(1),
+    derived: z.literal(true),
+    generated_at: z.string().min(1).optional(),
+    generated_by: z.string().min(1).optional(),
+    head_at_ingest: z.string().min(1).nullable(),
+    ['non-authoritative']: z.literal(true),
+    omx_context: blueprintDerivedHandoffOmxContextSchema.optional(),
+});
+export const runtimeStateStatusSchema = z.enum([
+    'pending',
+    'running',
+    'blocked',
+    'completed',
+    'failed',
+    'stopped',
+]);
+export const runtimeStateSnapshotSchema = z.object({
+    backend: executionBackendSchema,
+    evidence: evidenceListSchema.optional(),
+    executionId: z.string().min(1),
+    status: runtimeStateStatusSchema,
+    taskId: z.string().optional(),
+    updatedAt: z.string().min(1),
+});
+export const DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT = DEFAULT_RUNTIME_STATE_ROOT;
+//# sourceMappingURL=types.js.map

package/dist/esm/blueprint/export/spec-kit/_field-map.d.ts

@@ -0,0 +1,12 @@
+/**
+ * spec-kit field map — shared headers and templates.
+ * No string literals are duplicated across emitters; all shared content lives here.
+ */
+import type { ParsedBlueprintForDb } from '#db/parser/blueprint-db-parser';
+export declare const SPEC_KIT_HEADER_COMMENT = "<!-- Generated by wp blueprint export --format spec-kit. Do not edit manually. -->";
+export declare function titleLine(parsed: ParsedBlueprintForDb, suffix: string): string;
+export declare function overviewSection(parsed: ParsedBlueprintForDb): string;
+export declare function firstParagraphs(parsed: ParsedBlueprintForDb): string;
+export declare function taskIdLabel(index: number, waveOffset?: number): string;
+export declare const REVIEW_CHECKLIST = "## Review Checklist\n\n- [ ] All edge cases documented\n- [ ] Risks mitigated\n- [ ] Tasks have acceptance criteria";
+//# sourceMappingURL=_field-map.d.ts.map

package/dist/esm/blueprint/export/spec-kit/_field-map.js

@@ -0,0 +1,33 @@
+/**
+ * spec-kit field map — shared headers and templates.
+ * No string literals are duplicated across emitters; all shared content lives here.
+ */
+export const SPEC_KIT_HEADER_COMMENT = '<!-- Generated by wp blueprint export --format spec-kit. Do not edit manually. -->';
+export function titleLine(parsed, suffix) {
+    return `# ${parsed.title} — ${suffix}`;
+}
+export function overviewSection(parsed) {
+    const first = firstParagraphs(parsed);
+    return `## Overview\n\n${first}`;
+}
+export function firstParagraphs(parsed) {
+    // Extract up to 2 non-empty paragraphs that aren't frontmatter-style headers
+    const lines = parsed.title ? [parsed.title] : [];
+    if (parsed.tags.length > 0) {
+        lines.push(`Tags: ${parsed.tags.join(', ')}`);
+    }
+    if (parsed.complexity) {
+        lines.push(`Complexity: ${parsed.complexity}`);
+    }
+    return lines.length > 0 ? lines.join('\n') : parsed.slug;
+}
+export function taskIdLabel(index, waveOffset = 0) {
+    const n = index + 1 + waveOffset;
+    return `T${String(n).padStart(3, '0')}`;
+}
+export const REVIEW_CHECKLIST = `## Review Checklist
+
+- [ ] All edge cases documented
+- [ ] Risks mitigated
+- [ ] Tasks have acceptance criteria`;
+//# sourceMappingURL=_field-map.js.map