@webpresso/agent-kit 0.21.0

package/dist/esm/cli/commands/blueprint/execution-io.js

@@ -0,0 +1,78 @@
+/**
+ * execution-io.ts — thin I/O layer with injected writers/readers.
+ *
+ * All file system operations live here. The writer/reader parameters default
+ * to the real `node:fs/promises` implementations so callers don't need to
+ * inject anything for production use. Tests pass fakes.
+ *
+ * Tested by execution-io.test.ts.
+ */
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { blueprintProgressBridgeStateSchema, clearBlueprintExecutionArtifacts, clearBlueprintExecutionMetadata, DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, readBlueprintExecutionArtifacts, readBlueprintExecutionMetadata, runtimeStateSnapshotSchema, writeBlueprintExecutionArtifacts, writeBlueprintExecutionMetadata, } from '#index';
+import { normalizeCompletionEvidence, } from './execution-state.js';
+import { resolveBridgeAbsolutePath, resolveRuntimeSnapshotAbsolutePath } from './execution-spec.js';
+// ---------------------------------------------------------------------------
+// Blueprint markdown persistence (read + transform + write)
+// ---------------------------------------------------------------------------
+export async function persistBlueprintExecutionMetadata(blueprintPath, metadata, writer = writeFile, reader = readFile) {
+    const raw = await reader(blueprintPath, 'utf-8');
+    const updated = writeBlueprintExecutionMetadata(raw, metadata);
+    await writer(blueprintPath, updated, 'utf-8');
+}
+export async function readBlueprintExecutionState(blueprintPath, reader = readFile) {
+    const raw = await reader(blueprintPath, 'utf-8');
+    return readBlueprintExecutionMetadata(raw);
+}
+export async function clearBlueprintExecutionState(blueprintPath, writer = writeFile, reader = readFile) {
+    const raw = await reader(blueprintPath, 'utf-8');
+    const updated = clearBlueprintExecutionArtifacts(clearBlueprintExecutionMetadata(raw));
+    await writer(blueprintPath, updated, 'utf-8');
+}
+export async function persistBlueprintExecutionArtifacts(blueprintPath, evidence, writer = writeFile, reader = readFile) {
+    const raw = await reader(blueprintPath, 'utf-8');
+    const updated = writeBlueprintExecutionArtifacts(raw, normalizeCompletionEvidence(evidence));
+    await writer(blueprintPath, updated, 'utf-8');
+}
+export async function readBlueprintExecutionArtifactsState(blueprintPath, reader = readFile) {
+    const raw = await reader(blueprintPath, 'utf-8');
+    return readBlueprintExecutionArtifacts(raw);
+}
+// ---------------------------------------------------------------------------
+// Progress bridge persistence
+// ---------------------------------------------------------------------------
+export async function persistBlueprintProgressBridgeState(projectRoot, bridge, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, writer = writeFile, dirMaker = mkdir) {
+    const bridgePath = resolveBridgeAbsolutePath(projectRoot, bridge.backend, bridge.executionId, runtimeStateRoot);
+    await dirMaker(path.dirname(bridgePath), { recursive: true });
+    await writer(bridgePath, JSON.stringify(bridge, null, 2), 'utf-8');
+    return bridgePath;
+}
+export async function readBlueprintProgressBridgeState(projectRoot, backend, executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, reader = readFile) {
+    const bridgePath = resolveBridgeAbsolutePath(projectRoot, backend, executionId, runtimeStateRoot);
+    const raw = await reader(bridgePath, 'utf-8');
+    return blueprintProgressBridgeStateSchema.parse(JSON.parse(raw));
+}
+// ---------------------------------------------------------------------------
+// Runtime snapshot persistence
+// ---------------------------------------------------------------------------
+export async function writeBlueprintRuntimeSnapshot(projectRoot, snapshot, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, writer = writeFile, dirMaker = mkdir) {
+    const parsed = runtimeStateSnapshotSchema.parse(snapshot);
+    const snapshotPath = resolveRuntimeSnapshotAbsolutePath(projectRoot, parsed.executionId, runtimeStateRoot);
+    await dirMaker(path.dirname(snapshotPath), { recursive: true });
+    await writer(snapshotPath, JSON.stringify(parsed, null, 2), 'utf-8');
+    return snapshotPath;
+}
+export async function readBlueprintRuntimeSnapshot(projectRoot, executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, reader = readFile) {
+    const snapshotPath = resolveRuntimeSnapshotAbsolutePath(projectRoot, executionId, runtimeStateRoot);
+    const raw = await reader(snapshotPath, 'utf-8');
+    return runtimeStateSnapshotSchema.parse(JSON.parse(raw));
+}
+// ---------------------------------------------------------------------------
+// Blueprint file move (lifecycle transition)
+// ---------------------------------------------------------------------------
+export async function moveBlueprintDirectory(currentDir, targetDir, targetPath, nextMarkdown, writer = writeFile, dirMaker = mkdir, renamer = rename) {
+    await dirMaker(path.dirname(targetDir), { recursive: true });
+    await renamer(currentDir, targetDir);
+    await writer(targetPath, nextMarkdown, 'utf-8');
+}
+//# sourceMappingURL=execution-io.js.map

package/dist/esm/cli/commands/blueprint/execution-spec.d.ts

@@ -0,0 +1,45 @@
+/**
+ * execution-spec.ts — pure spec-building / env-composition logic.
+ *
+ * Zero I/O. All functions take inputs and return structured objects.
+ * Tested by execution-spec.test.ts.
+ */
+import type { BlueprintExecutionArtifacts, BlueprintExecutionBackend, BlueprintLaunchSpec, RuntimeStateStatus } from '#index';
+import type { Blueprint } from '#local';
+export interface BuildBlueprintLaunchSpecInput {
+    blueprint: Blueprint;
+    blueprintPath: string;
+    blueprintSlug: string;
+}
+export interface BlueprintExecutionRuntimePaths {
+    artifactPaths: string[];
+    bridgePath: string;
+    logPath?: string;
+    runtimeSnapshotPath: string;
+    teamStateRoot: string;
+}
+export declare function nowIsoTimestamp(): string;
+export declare function toProjectRelativePath(projectRoot: string, targetPath: string): string;
+export declare function uniqueStrings(values: string[]): string[];
+export declare function isMissingFileError(error: unknown): boolean;
+export declare function buildListTasksVerificationCommand(executionId: string): string;
+export declare function resolveRuntimeSnapshotRelativePath(executionId: string, runtimeStateRoot?: string): string;
+export declare function resolveTeamStateRelativePath(executionId: string, runtimeStateRoot?: string): string;
+export declare function resolveBridgeRelativePath(backend: BlueprintExecutionBackend, executionId: string, runtimeStateRoot?: string): string;
+export declare function resolveBridgeAbsolutePath(projectRoot: string, backend: BlueprintExecutionBackend, executionId: string, runtimeStateRoot?: string): string;
+export declare function resolveRuntimeSnapshotAbsolutePath(projectRoot: string, executionId: string, runtimeStateRoot?: string): string;
+export declare function buildBlueprintLaunchSpec(input: BuildBlueprintLaunchSpecInput): BlueprintLaunchSpec;
+export declare function buildBlueprintExecutionLaunchCommand(spec: BlueprintLaunchSpec): {
+    args: string[];
+    command: string;
+    workerCount: number;
+};
+export declare function parseTeamExecutionId(output: string): string;
+export declare function buildBlueprintExecutionControlCommand(backend: BlueprintExecutionBackend, action: 'status' | 'resume' | 'stop', executionId: string): {
+    args: string[];
+    command: string;
+};
+export declare function parseOmxTeamApiResponse<T>(output: string, operation: string): T;
+export declare function buildBlueprintExecutionRuntimePaths(backend: BlueprintExecutionBackend, executionId: string, artifacts: BlueprintExecutionArtifacts | null): BlueprintExecutionRuntimePaths;
+export declare function resolveControlStatus(action: 'status' | 'resume' | 'stop'): RuntimeStateStatus;
+//# sourceMappingURL=execution-spec.d.ts.map

package/dist/esm/cli/commands/blueprint/execution-spec.js

@@ -0,0 +1,177 @@
+/**
+ * execution-spec.ts — pure spec-building / env-composition logic.
+ *
+ * Zero I/O. All functions take inputs and return structured objects.
+ * Tested by execution-spec.test.ts.
+ */
+import path from 'node:path';
+import { blueprintLaunchSpecSchema, DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT, resolveBlueprintProgressBridgePath, runtimeSnapshotPathForExecution, } from '#index';
+// ---------------------------------------------------------------------------
+// Small pure helpers
+// ---------------------------------------------------------------------------
+export function nowIsoTimestamp() {
+    return new Date().toISOString();
+}
+export function toProjectRelativePath(projectRoot, targetPath) {
+    return path.relative(projectRoot, targetPath).replace(/\\/g, '/');
+}
+export function uniqueStrings(values) {
+    return [...new Set(values.map((value) => value.trim()).filter((value) => value.length > 0))];
+}
+export function isMissingFileError(error) {
+    return (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string' &&
+        error.code === 'ENOENT');
+}
+export function buildListTasksVerificationCommand(executionId) {
+    return `omx team api list-tasks --input '${JSON.stringify({ team_name: executionId })}' --json`;
+}
+// ---------------------------------------------------------------------------
+// Path resolution (pure — no I/O)
+// ---------------------------------------------------------------------------
+export function resolveRuntimeSnapshotRelativePath(executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT) {
+    return runtimeSnapshotPathForExecution(executionId, runtimeStateRoot);
+}
+export function resolveTeamStateRelativePath(executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT) {
+    return `${runtimeStateRoot.replace(/\/+$/u, '')}/team/${executionId}`;
+}
+export function resolveBridgeRelativePath(backend, executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT) {
+    return resolveBlueprintProgressBridgePath(runtimeStateRoot, backend, executionId);
+}
+export function resolveBridgeAbsolutePath(projectRoot, backend, executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT) {
+    return path.join(projectRoot, resolveBridgeRelativePath(backend, executionId, runtimeStateRoot));
+}
+export function resolveRuntimeSnapshotAbsolutePath(projectRoot, executionId, runtimeStateRoot = DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT) {
+    return path.join(projectRoot, resolveRuntimeSnapshotRelativePath(executionId, runtimeStateRoot));
+}
+// ---------------------------------------------------------------------------
+// Spec builders
+// ---------------------------------------------------------------------------
+function toTaskLaunchSpec(task) {
+    return {
+        backendHints: {
+            longRunning: task.stepType === 'implement' || task.stepType === 'research',
+            testHeavy: task.stepType === 'test-fix' || task.stepType === 'verify',
+        },
+        dependsOn: task.depends ?? [],
+        files: task.targetFile ? [task.targetFile] : [],
+        id: task.id,
+        title: task.title,
+        verificationCommands: [],
+    };
+}
+function countReadyTasks(tasks) {
+    return tasks.filter((task) => task.dependsOn.length === 0).length;
+}
+export function buildBlueprintLaunchSpec(input) {
+    const tasks = input.blueprint.tasks.map(toTaskLaunchSpec);
+    const suggestedParallelism = Math.max(1, Math.min(3, countReadyTasks(tasks)));
+    return blueprintLaunchSpecSchema.parse({
+        backend: 'omx-team',
+        blueprintPath: input.blueprintPath,
+        blueprintSlug: input.blueprintSlug,
+        mode: 'durable',
+        policy: {
+            maxParallelism: suggestedParallelism,
+            runtimeStateRoot: DEFAULT_BLUEPRINT_RUNTIME_STATE_ROOT,
+        },
+        tasks,
+    });
+}
+function buildTeamPrompt(spec) {
+    const taskLines = spec.tasks.map((task) => {
+        const details = [
+            task.dependsOn.length > 0 ? `depends on ${task.dependsOn.join(', ')}` : null,
+            task.files.length > 0 ? `files ${task.files.join(', ')}` : null,
+            task.verificationCommands.length > 0
+                ? `verify with ${task.verificationCommands.join(' && ')}`
+                : null,
+        ]
+            .filter(Boolean)
+            .join('; ');
+        return `- Task ${task.id}: ${task.title}${details ? ` (${details})` : ''}`;
+    });
+    return [
+        `Execute blueprint ${spec.blueprintSlug}.`,
+        `Blueprint path: ${spec.blueprintPath}.`,
+        'Treat the blueprint as the source of truth.',
+        'Use the OMX team task queue below as the execution substrate.',
+        ...taskLines,
+        'Verify changed work before reporting completion.',
+    ].join('\n');
+}
+export function buildBlueprintExecutionLaunchCommand(spec) {
+    const workerCount = spec.policy.maxParallelism ?? 1;
+    return {
+        args: ['team', `${workerCount}:executor`, buildTeamPrompt(spec)],
+        command: 'omx',
+        workerCount,
+    };
+}
+export function parseTeamExecutionId(output) {
+    const match = output.match(/Team started:\s*([^\n]+)/i);
+    if (!match?.[1]) {
+        throw new Error('Could not determine OMX team identity from launch output.');
+    }
+    return match[1].trim();
+}
+export function buildBlueprintExecutionControlCommand(backend, action, executionId) {
+    // Only 'omx-team' maps to the `omx team` CLI surface (status / resume / shutdown).
+    // The Runner backends ('omx-pll-interactive', 'claude-subagent', 'codex-exec',
+    // 'local-worktree') do not use the OMX CLI and have no equivalent control command
+    // at this layer — callers must dispatch them through their own runner-specific
+    // control path. Throwing here is intentional and correct for all non-omx-team values.
+    if (backend !== 'omx-team') {
+        throw new Error(`Unsupported execution backend for control command: ${backend}`);
+    }
+    const subcommand = action === 'stop' ? 'shutdown' : action;
+    return {
+        args: ['team', subcommand, executionId],
+        command: 'omx',
+    };
+}
+export function parseOmxTeamApiResponse(output, operation) {
+    let parsed;
+    try {
+        parsed = JSON.parse(output);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse OMX team api ${operation} response: ${error instanceof Error ? error.message : String(error)}`, {
+            cause: error,
+        });
+    }
+    if (!parsed.ok) {
+        throw new Error(parsed.error?.message ||
+            `OMX team api ${operation} failed${parsed.error?.code ? ` (${parsed.error.code})` : ''}.`);
+    }
+    if (!parsed.data) {
+        throw new Error(`OMX team api ${operation} returned no data.`);
+    }
+    return parsed.data;
+}
+export function buildBlueprintExecutionRuntimePaths(backend, executionId, artifacts) {
+    const bridgePath = resolveBridgeRelativePath(backend, executionId);
+    const runtimeSnapshotPath = resolveRuntimeSnapshotRelativePath(executionId);
+    const teamStateRoot = resolveTeamStateRelativePath(executionId);
+    return {
+        artifactPaths: uniqueStrings([
+            runtimeSnapshotPath,
+            bridgePath,
+            teamStateRoot,
+            ...(artifacts?.artifacts ?? []),
+        ]),
+        bridgePath,
+        logPath: artifacts?.logPath,
+        runtimeSnapshotPath,
+        teamStateRoot,
+    };
+}
+// ---------------------------------------------------------------------------
+// Status helpers
+// ---------------------------------------------------------------------------
+export function resolveControlStatus(action) {
+    return action === 'stop' ? 'stopped' : 'running';
+}
+//# sourceMappingURL=execution-spec.js.map

package/dist/esm/cli/commands/blueprint/execution-state.d.ts

@@ -0,0 +1,17 @@
+/**
+ * execution-state.ts — pure evidence/artifact state composition.
+ *
+ * Zero I/O. Functions take plain data and return plain data.
+ * Tested by execution-state.test.ts.
+ */
+import type { BlueprintExecutionArtifacts } from '#index';
+export interface BlueprintExecutionCompletionEvidence {
+    artifacts: string[];
+    logPath?: string;
+    verifications: string[];
+}
+export declare function normalizeEvidenceArray(values: string[]): string[];
+export declare function normalizeCompletionEvidence(evidence: BlueprintExecutionCompletionEvidence): BlueprintExecutionArtifacts;
+export declare function mergeExecutionArtifacts(current: BlueprintExecutionArtifacts | null, next: BlueprintExecutionCompletionEvidence): BlueprintExecutionArtifacts;
+export declare function assertCompletionEvidence(evidence: BlueprintExecutionArtifacts | null, executionId: string): BlueprintExecutionArtifacts;
+//# sourceMappingURL=execution-state.d.ts.map

package/dist/esm/cli/commands/blueprint/execution-state.js

@@ -0,0 +1,38 @@
+/**
+ * execution-state.ts — pure evidence/artifact state composition.
+ *
+ * Zero I/O. Functions take plain data and return plain data.
+ * Tested by execution-state.test.ts.
+ */
+import { uniqueStrings } from './execution-spec.js';
+// ---------------------------------------------------------------------------
+// Pure evidence composers
+// ---------------------------------------------------------------------------
+export function normalizeEvidenceArray(values) {
+    return values.map((value) => value.trim()).filter((value) => value.length > 0);
+}
+export function normalizeCompletionEvidence(evidence) {
+    return {
+        artifacts: normalizeEvidenceArray(evidence.artifacts),
+        logPath: evidence.logPath?.trim() || undefined,
+        verifications: normalizeEvidenceArray(evidence.verifications),
+    };
+}
+export function mergeExecutionArtifacts(current, next) {
+    const normalized = normalizeCompletionEvidence(next);
+    return {
+        artifacts: uniqueStrings([...(current?.artifacts ?? []), ...normalized.artifacts]),
+        logPath: normalized.logPath ?? current?.logPath,
+        verifications: uniqueStrings([...(current?.verifications ?? []), ...normalized.verifications]),
+    };
+}
+export function assertCompletionEvidence(evidence, executionId) {
+    if (!evidence || evidence.verifications.length === 0) {
+        throw new Error(`Blueprint execution ${executionId} cannot record completion without named verification output.`);
+    }
+    if (evidence.artifacts.length === 0 && !evidence.logPath) {
+        throw new Error(`Blueprint execution ${executionId} cannot record completion without artifact or log identity.`);
+    }
+    return evidence;
+}
+//# sourceMappingURL=execution-state.js.map

package/dist/esm/cli/commands/blueprint/execution.d.ts

@@ -0,0 +1,74 @@
+/**
+ * execution.ts — orchestrator layer.
+ *
+ * Imports spec, state, and io modules and exposes the high-level actions
+ * that CAC command handlers call. No direct node:fs/promises usage here.
+ */
+import type { BlueprintExecutionArtifacts, BlueprintExecutionBackend, BlueprintLaunchSpec, BlueprintProgressBridgeState, Evidence, OmxTeamTaskSnapshot, RuntimeStateStatus } from '#index';
+import { clearBlueprintExecutionState, persistBlueprintExecutionArtifacts, persistBlueprintExecutionMetadata, persistBlueprintProgressBridgeState, readBlueprintExecutionArtifactsState, readBlueprintExecutionState, readBlueprintProgressBridgeState, readBlueprintRuntimeSnapshot, writeBlueprintRuntimeSnapshot } from './execution-io.js';
+import { type BlueprintExecutionCompletionEvidence } from './execution-state.js';
+import { buildBlueprintExecutionControlCommand, buildBlueprintExecutionLaunchCommand, buildBlueprintExecutionRuntimePaths, buildBlueprintLaunchSpec, type BlueprintExecutionRuntimePaths, type BuildBlueprintLaunchSpecInput } from './execution-spec.js';
+export type { BlueprintExecutionCompletionEvidence, BlueprintExecutionRuntimePaths, BuildBlueprintLaunchSpecInput, };
+export { buildBlueprintExecutionControlCommand, buildBlueprintExecutionLaunchCommand, buildBlueprintExecutionRuntimePaths, buildBlueprintLaunchSpec, clearBlueprintExecutionState, persistBlueprintExecutionArtifacts, persistBlueprintExecutionMetadata, persistBlueprintProgressBridgeState, readBlueprintExecutionArtifactsState, readBlueprintExecutionState, readBlueprintProgressBridgeState, readBlueprintRuntimeSnapshot, writeBlueprintRuntimeSnapshot, };
+export interface ExecutionCommandRunner {
+    exec: (command: string, args: string[], options: {
+        cwd: string;
+    }) => string;
+}
+export declare const realExecutionCommandRunner: ExecutionCommandRunner;
+export interface BlueprintExecutionLaunchResult {
+    args: string[];
+    backend: BlueprintExecutionBackend;
+    command: string;
+    executionId: string;
+    output: string;
+    workerCount: number;
+}
+export interface BlueprintExecutionControlResult {
+    backend: BlueprintExecutionBackend;
+    executionId: string;
+    output: string;
+    status: RuntimeStateStatus;
+}
+export interface BlueprintExecutionRuntimeDescription {
+    artifacts: BlueprintExecutionArtifacts | null;
+    backend: BlueprintExecutionBackend;
+    executionId: string;
+    paths: BlueprintExecutionRuntimePaths;
+    status: RuntimeStateStatus;
+}
+export interface SyncBlueprintExecutionProgressResult {
+    blueprintPath: string;
+    bridgePath: string;
+    executionId: string;
+    runtimeSnapshotPath: string;
+    status: RuntimeStateStatus;
+    teamStateRoot: string;
+}
+export interface ReconcileBlueprintRuntimeSnapshotResult {
+    moved: boolean;
+    path: string;
+    status: RuntimeStateStatus;
+}
+interface SyncBlueprintExecutionProgressOptions {
+    evidence?: BlueprintExecutionCompletionEvidence;
+    runner?: ExecutionCommandRunner;
+}
+export declare function launchBlueprintExecution(spec: BlueprintLaunchSpec, projectRoot: string, runner?: ExecutionCommandRunner): BlueprintExecutionLaunchResult;
+export declare function describeBlueprintExecutionRuntime(blueprintPath: string): Promise<BlueprintExecutionRuntimeDescription>;
+export declare function listOmxTeamTasks(executionId: string, projectRoot: string, runner?: ExecutionCommandRunner): OmxTeamTaskSnapshot[];
+export declare function initializeBlueprintExecutionProgressBridge(spec: BlueprintLaunchSpec, executionId: string, projectRoot: string, runner?: ExecutionCommandRunner): Promise<BlueprintProgressBridgeState>;
+export declare function reconcileBlueprintRuntimeSnapshot(projectRoot: string, blueprintPath: string, slug: string, snapshot: {
+    backend: BlueprintExecutionBackend;
+    evidence?: readonly Evidence[];
+    executionId: string;
+    status: RuntimeStateStatus;
+    taskId?: string;
+    updatedAt: string;
+}, evidence?: BlueprintExecutionCompletionEvidence): Promise<ReconcileBlueprintRuntimeSnapshotResult>;
+export declare function syncBlueprintExecutionProgress(blueprintPath: string, slug: string, projectRoot: string, options?: SyncBlueprintExecutionProgressOptions): Promise<SyncBlueprintExecutionProgressResult>;
+export declare function controlBlueprintExecution(backend: BlueprintExecutionBackend, action: 'status' | 'resume' | 'stop', executionId: string, projectRoot: string, runner?: ExecutionCommandRunner): BlueprintExecutionControlResult;
+export declare function recordLaunchFailure(blueprintPath: string, projectRoot: string, backend: BlueprintExecutionBackend, executionId: string, reason: string): Promise<never>;
+export declare function buildStoppedRuntimeEvidence(blueprintPath: string): Promise<BlueprintExecutionCompletionEvidence>;
+export declare function readStoredRuntimeSnapshotStatus(blueprintPath: string, projectRoot: string): Promise<RuntimeStateStatus | null>;
+//# sourceMappingURL=execution.d.ts.map