intentdna 1.8.5 → 1.8.7

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "intentdna",
       "description": "Declarative policy layer for AI agent behavior with plugin-managed hook runtime for Claude Code.",
-      "version": "1.8.5",
+      "version": "1.8.7",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.8.5"
+  "version": "1.8.7"
 }

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "intentdna",
-  "version": "1.8.5",
+  "version": "1.8.7",
   "description": "Declarative policy layer for AI agent behavior",
   "author": {
     "name": "Samuel"

package/README.md

@@ -181,6 +181,7 @@ Trusted cloud ingestion may increase persistence and visibility, but it does not
 
 - [docs/README.md](docs/README.md) - living docs map and two-state documentation rule.
 - [docs/quickstart.md](docs/quickstart.md) - local developer quickstart.
+- [docs/foundation-runtime.md](docs/foundation-runtime.md) - durable `dna run` Controller, lifecycle, handoff, isolation, and recovery guide.
 - [docs/product/milestone-review-protocol.md](docs/product/milestone-review-protocol.md) - lightweight P-stage review protocol.
 - [docs/product/online-product-spec.md](docs/product/online-product-spec.md) - Online IA, K5 boundary, forbidden copy, and acceptance.
 - [docs/decisions/ADR-001-product-reset.md](docs/decisions/ADR-001-product-reset.md) - product reset decision record.

package/dist/cli/commands/run-lifecycle.d.ts

@@ -0,0 +1,73 @@
+import type { JsonValue, RunId, TaskState } from "../../runtime/run-contracts.js";
+import type { RunController } from "../../runtime/run-controller.js";
+import type { DurableRunStore, RunRecord, RunStatus, RunStoreSnapshot } from "../../runtime/run-store.js";
+export type RunLifecycleAction = "start" | "status" | "inspect" | "resume" | "cancel";
+interface LifecycleOutputOptions {
+    readonly json?: boolean;
+}
+export interface RunLifecycleStartOptions extends LifecycleOutputOptions {
+    readonly controller: RunController;
+    readonly run: RunRecord;
+}
+export interface RunLifecycleStatusOptions extends LifecycleOutputOptions {
+    readonly run_store: DurableRunStore;
+    readonly run_id: RunId;
+}
+export interface RunLifecycleInspectOptions extends LifecycleOutputOptions {
+    readonly run_store: DurableRunStore;
+    readonly run_id: RunId;
+}
+export interface RunLifecycleResumeOptions extends LifecycleOutputOptions {
+    readonly controller: RunController;
+    readonly run_id: RunId;
+}
+export interface RunLifecycleCancelOptions extends LifecycleOutputOptions {
+    readonly controller: RunController;
+    readonly run_id: RunId;
+    readonly reason?: string | null;
+}
+export interface RunStatusProjection {
+    readonly schema_version: "intentdna.run_status.v1";
+    readonly run_id: RunId;
+    readonly workflow_id: string;
+    readonly workflow_version: string | null;
+    readonly status: RunStatus;
+    readonly record_version: number;
+    readonly task_counts: Readonly<Record<TaskState, number>>;
+    readonly attempt_count: number;
+    readonly result_count: number;
+    readonly cancellation: RunRecord["cancellation"];
+    readonly terminal: RunRecord["terminal"];
+    readonly created_at: string;
+    readonly updated_at: string;
+}
+export interface DurableHandoffInspection {
+    readonly event_id: string;
+    readonly sequence: number;
+    readonly run_id: RunId;
+    readonly step_id: string;
+    readonly attempt_id: string;
+    readonly worker_session_id: string;
+    readonly result_id: string | null;
+    readonly occurred_at: string;
+    readonly binding: JsonValue;
+}
+export interface RunInspectionProjection {
+    readonly schema_version: "intentdna.run_inspection.v1";
+    readonly record_version: number;
+    readonly run: RunRecord;
+    readonly tasks: RunStoreSnapshot["tasks"];
+    readonly attempts: RunStoreSnapshot["attempts"];
+    readonly claims: RunStoreSnapshot["claims"];
+    readonly handoffs: readonly DurableHandoffInspection[];
+    readonly events: RunStoreSnapshot["events"];
+    readonly results: RunStoreSnapshot["results"];
+    readonly ledger_created_at: string;
+    readonly ledger_updated_at: string;
+}
+export declare function runLifecycleStart(options: RunLifecycleStartOptions): Promise<number>;
+export declare function runLifecycleStatus(options: RunLifecycleStatusOptions): Promise<number>;
+export declare function runLifecycleInspect(options: RunLifecycleInspectOptions): Promise<number>;
+export declare function runLifecycleResume(options: RunLifecycleResumeOptions): Promise<number>;
+export declare function runLifecycleCancel(options: RunLifecycleCancelOptions): Promise<number>;
+export {};

package/dist/cli/commands/run-lifecycle.js

@@ -0,0 +1,240 @@
+class LifecycleUsageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LifecycleUsageError";
+    }
+}
+const TASK_STATES = [
+    "dependency_blocked",
+    "ready",
+    "claimed",
+    "running",
+    "succeeded",
+    "failed",
+    "skipped",
+    "cancelled",
+];
+function requireText(value, label) {
+    if (!value.trim()) {
+        throw new LifecycleUsageError(`${label} is required`);
+    }
+}
+function requireRunId(runId) {
+    requireText(runId, "run_id");
+}
+function validateStartRun(run) {
+    requireRunId(run.run_id);
+    requireText(run.workflow_id, "workflow_id");
+    requireText(run.plan_digest, "plan_digest");
+    requireText(run.created_at, "created_at");
+    requireText(run.updated_at, "updated_at");
+    if (run.status !== "active"
+        || run.cancellation !== null
+        || run.terminal !== null) {
+        throw new LifecycleUsageError("start requires an active run without cancellation or terminal state");
+    }
+}
+function statusProjection(snapshot) {
+    const taskCounts = Object.fromEntries(TASK_STATES.map((state) => [state, 0]));
+    for (const task of snapshot.tasks) {
+        taskCounts[task.state] += 1;
+    }
+    return {
+        schema_version: "intentdna.run_status.v1",
+        run_id: snapshot.run.run_id,
+        workflow_id: snapshot.run.workflow_id,
+        workflow_version: snapshot.run.workflow_version,
+        status: snapshot.run.status,
+        record_version: snapshot.record_version,
+        task_counts: taskCounts,
+        attempt_count: snapshot.attempts.length,
+        result_count: snapshot.results.length,
+        cancellation: snapshot.run.cancellation,
+        terminal: snapshot.run.terminal,
+        created_at: snapshot.run.created_at,
+        updated_at: snapshot.run.updated_at,
+    };
+}
+function durableHandoffs(snapshot) {
+    return snapshot.events.flatMap((event) => {
+        if (event.type !== "handoff_resolved"
+            || event.step_id === null
+            || event.attempt_id === null
+            || event.worker_session_id === null) {
+            return [];
+        }
+        return [{
+                event_id: event.event_id,
+                sequence: event.sequence,
+                run_id: event.run_id,
+                step_id: event.step_id,
+                attempt_id: event.attempt_id,
+                worker_session_id: event.worker_session_id,
+                result_id: event.result_id,
+                occurred_at: event.occurred_at,
+                binding: event.payload,
+            }];
+    });
+}
+function inspectionProjection(snapshot) {
+    return {
+        schema_version: "intentdna.run_inspection.v1",
+        record_version: snapshot.record_version,
+        run: snapshot.run,
+        tasks: snapshot.tasks,
+        attempts: snapshot.attempts,
+        claims: snapshot.claims,
+        handoffs: durableHandoffs(snapshot),
+        events: snapshot.events,
+        results: snapshot.results,
+        ledger_created_at: snapshot.created_at,
+        ledger_updated_at: snapshot.updated_at,
+    };
+}
+function writeJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+function nonZeroTaskCounts(counts) {
+    const summary = TASK_STATES
+        .filter((state) => counts[state] > 0)
+        .map((state) => `${state}=${counts[state]}`)
+        .join(", ");
+    return summary || "none";
+}
+function writeHumanStatus(status, action) {
+    if (action)
+        process.stdout.write(`Action: ${action}\n`);
+    process.stdout.write(`Run: ${status.run_id}\n`);
+    process.stdout.write(`Workflow: ${status.workflow_id}\n`);
+    process.stdout.write(`Status: ${status.status}\n`);
+    process.stdout.write(`Ledger version: ${status.record_version}\n`);
+    process.stdout.write(`Tasks: ${nonZeroTaskCounts(status.task_counts)}\n`);
+    process.stdout.write(`Attempts: ${status.attempt_count}; results: ${status.result_count}\n`);
+    if (status.cancellation) {
+        process.stdout.write(`Cancellation: ${status.cancellation.requested_at}`
+            + `${status.cancellation.reason ? ` (${status.cancellation.reason})` : ""}\n`);
+    }
+    if (status.terminal) {
+        process.stdout.write(`Terminal: ${status.terminal.status} at ${status.terminal.completed_at}`
+            + `${status.terminal.reason ? ` (${status.terminal.reason})` : ""}\n`);
+    }
+}
+function writeInspection(snapshot, json) {
+    const projection = inspectionProjection(snapshot);
+    if (json) {
+        writeJson(projection);
+        return;
+    }
+    writeHumanStatus(statusProjection(snapshot));
+    process.stdout.write("\nAttempts:\n");
+    if (projection.attempts.length === 0) {
+        process.stdout.write("  (none)\n");
+    }
+    for (const attempt of projection.attempts) {
+        process.stdout.write(`  ${attempt.attempt_id} step=${attempt.step_id}`
+            + ` worker=${attempt.worker_session_id} phase=${attempt.phase}`
+            + ` pid=${attempt.process_id ?? "-"}`
+            + ` outcome=${attempt.terminal_outcome?.kind ?? "none"}\n`);
+    }
+    process.stdout.write("\nResolved handoffs:\n");
+    if (projection.handoffs.length === 0) {
+        process.stdout.write("  (none)\n");
+    }
+    for (const handoff of projection.handoffs) {
+        process.stdout.write(`  attempt=${handoff.attempt_id} worker=${handoff.worker_session_id}`
+            + ` binding=${JSON.stringify(handoff.binding)}\n`);
+    }
+    process.stdout.write("\nCommitted results:\n");
+    if (projection.results.length === 0) {
+        process.stdout.write("  (none)\n");
+    }
+    for (const result of projection.results) {
+        process.stdout.write(`  ${result.result_id} attempt=${result.attempt_id}`
+            + ` worker=${result.worker_session_id}`
+            + ` outputs=${JSON.stringify(result.outputs)}\n`);
+    }
+    process.stdout.write("\nEvents:\n");
+    if (projection.events.length === 0) {
+        process.stdout.write("  (none)\n");
+    }
+    for (const event of projection.events) {
+        process.stdout.write(`  ${event.sequence} ${event.type}`
+            + ` step=${event.step_id ?? "-"} attempt=${event.attempt_id ?? "-"}`
+            + ` worker=${event.worker_session_id ?? "-"}`
+            + ` payload=${JSON.stringify(event.payload)}\n`);
+    }
+}
+function writeOperation(action, snapshot, json) {
+    const status = statusProjection(snapshot);
+    if (json) {
+        writeJson({
+            schema_version: "intentdna.run_lifecycle_operation.v1",
+            action,
+            status,
+        });
+        return;
+    }
+    writeHumanStatus(status, action);
+}
+function operationExitCode(snapshot) {
+    return snapshot.run.status === "failed" ? 1 : 0;
+}
+async function handle(operation) {
+    try {
+        return await operation();
+    }
+    catch (error) {
+        const prefix = error instanceof LifecycleUsageError ? "Usage error" : "Error";
+        process.stderr.write(`${prefix}: ${error instanceof Error ? error.message : String(error)}\n`);
+        return error instanceof LifecycleUsageError ? 2 : 1;
+    }
+}
+export async function runLifecycleStart(options) {
+    return handle(async () => {
+        validateStartRun(options.run);
+        await options.controller.createRun({ run: options.run });
+        const snapshot = await options.controller.runUntilTerminal(options.run.run_id);
+        writeOperation("start", snapshot, options.json === true);
+        return operationExitCode(snapshot);
+    });
+}
+export async function runLifecycleStatus(options) {
+    return handle(async () => {
+        requireRunId(options.run_id);
+        const snapshot = await options.run_store.requireRun(options.run_id);
+        const projection = statusProjection(snapshot);
+        if (options.json === true)
+            writeJson(projection);
+        else
+            writeHumanStatus(projection);
+        return 0;
+    });
+}
+export async function runLifecycleInspect(options) {
+    return handle(async () => {
+        requireRunId(options.run_id);
+        const snapshot = await options.run_store.requireRun(options.run_id);
+        writeInspection(snapshot, options.json === true);
+        return 0;
+    });
+}
+export async function runLifecycleResume(options) {
+    return handle(async () => {
+        requireRunId(options.run_id);
+        const snapshot = await options.controller.runUntilTerminal(options.run_id);
+        writeOperation("resume", snapshot, options.json === true);
+        return operationExitCode(snapshot);
+    });
+}
+export async function runLifecycleCancel(options) {
+    return handle(async () => {
+        requireRunId(options.run_id);
+        const reason = options.reason ?? null;
+        if (reason !== null && !reason.trim()) {
+            throw new LifecycleUsageError("reason must not be empty");
+        }
+        const snapshot = await options.controller.requestCancellation(options.run_id, reason);
+        writeOperation("cancel", snapshot, options.json === true);
+        return 0;
+    });
+}

package/dist/cli/commands/run.d.ts

@@ -1,16 +1,19 @@
 /**
- * Intent DNA — dna run command
+ * Intent DNA - canonical dna run command.
  *
- * TypeScript runtime execution of workflows.
- * Loads DNA → compiles → auto-syncs agents/hooks → executes steps
- * via `claude -p --agent` child processes.
+ * The CLI compiles one workflow into Controller definitions, persists one
+ * durable run ledger, and launches one disposable provider session per Step
+ * attempt. Cross-Step inputs come only from committed results.
  */
-import type { WorkflowStep, ParallelGroup, TransitionRule } from "../../schema/types.js";
-import type { ConstraintIR } from "../../schema/types.js";
+import type { TransitionRule } from "../../schema/types.js";
+import { type RunLifecycleAction } from "./run-lifecycle.js";
+export type RunProviderKind = "claude" | "codex";
 export interface RunOptions {
+    action?: RunLifecycleAction;
+    runId?: string;
     dnaFiles: string[];
-    workflowName: string;
-    taskId: string;
+    workflowName?: string;
+    taskId?: string;
     context?: string;
     vars?: Record<string, string>;
     dryRun?: boolean;
@@ -20,46 +23,25 @@ export interface RunOptions {
     agentsDir?: string;
     hooksDir?: string;
     projectDir?: string;
+    provider?: RunProviderKind;
+    providerExecutable?: string;
+    maxConcurrency?: number;
+    timeoutMs?: number | null;
+    cancellationGraceMs?: number;
+    reason?: string | null;
+    json?: boolean;
 }
+/**
+ * Retained as a source-compatible result shape for callers that only use the
+ * pure legacy routing helper below. Canonical execution truth is RunStoreSnapshot.
+ */
 export interface StepResult {
     stepId: string;
     status: "pass" | "fail" | "skipped";
     durationMs: number;
     resultFile?: string;
 }
-interface StepExecOptions {
-    agentPrefix: string;
-    maxBudget: number;
-    permissionMode: string;
-    logDir: string;
-    projectDir: string;
-    workflowName: string;
-    workflowAsset?: string;
-    inputs: Record<string, string>;
-    ir: Pick<ConstraintIR, "verifier_policy">;
-}
-/**
- * Replace {{var}} placeholders in a template string.
- * Unmatched placeholders are preserved as-is.
- */
 export declare function substituteTemplate(template: string, vars: Record<string, string>): string;
-/**
- * Evaluate a run_if condition against the current round.
- * Returns true if the step should execute.
- */
 export declare function evaluateRunIf(condition: string | null, round: number): boolean;
-/**
- * Execute a single workflow step via `claude -p --agent`.
- * Returns StepResult with pass/fail status.
- */
-export declare function executeStep(step: WorkflowStep, vars: Record<string, string>, opts: StepExecOptions, iteration?: number): Promise<StepResult>;
-/**
- * Execute a parallel group of steps.
- */
-export declare function executeGroup(group: ParallelGroup, allSteps: WorkflowStep[], round: number, vars: Record<string, string>, opts: StepExecOptions): Promise<StepResult[]>;
-/**
- * Check if any transition requires retry.
- */
 export declare function checkRetryNeeded(stepResults: Map<string, StepResult>, transitions: TransitionRule[]): boolean;
 export declare function runRun(opts: RunOptions): Promise<number>;
-export {};