intentdna 1.8.7 → 1.9.0-rc.2

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.7",
+      "version": "1.9.0-rc.2",
       "author": {
         "name": "Samuel"
       },
@@ -25,5 +25,5 @@
       ]
     }
   ],
-  "version": "1.8.7"
+  "version": "1.9.0-rc.2"
 }

package/.claude-plugin/plugin.json

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

package/dist/cli/commands/candidate-promotion.d.ts

@@ -0,0 +1,15 @@
+export interface PromoteCandidateOptions {
+    projectDir: string;
+    candidatePath: string;
+    templateName: string;
+}
+export interface CandidatePromotionResult {
+    schema_version: "intentdna.candidate_promotion_result.v1";
+    candidate_path: string;
+    template_path: string;
+    receipt_path: string;
+    candidate_sha256: string;
+    template_sha256: string;
+    exact_bytes_preserved: true;
+}
+export declare function promoteCandidate(options: PromoteCandidateOptions): Promise<CandidatePromotionResult>;

package/dist/cli/commands/candidate-promotion.js

@@ -0,0 +1,197 @@
+import { createHash } from "node:crypto";
+import { lstat, mkdir, open, readFile, realpath, rm, stat, } from "node:fs/promises";
+import { basename, isAbsolute, join, relative, resolve } from "node:path";
+import { formatDiagnostics, hasDiagnosticErrors } from "../../compiler/diagnostics.js";
+import { loadDNAWithDiagnostics } from "../../compiler/input-resolver.js";
+const CANDIDATE_SUFFIX = ".candidate.dna.yaml";
+const SAFE_TEMPLATE_NAME = /^[A-Za-z0-9][A-Za-z0-9_-]*$/;
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function isErrnoException(error) {
+    return error instanceof Error && "code" in error;
+}
+function isStrictlyWithin(parent, child) {
+    const pathFromParent = relative(parent, child);
+    return pathFromParent !== ""
+        && pathFromParent !== ".."
+        && !pathFromParent.startsWith(`..${process.platform === "win32" ? "\\" : "/"}`)
+        && !isAbsolute(pathFromParent);
+}
+function validateTemplateName(templateName) {
+    if (!SAFE_TEMPLATE_NAME.test(templateName)) {
+        throw new Error("Invalid template name: use one safe path component containing only letters, numbers, hyphens, or underscores");
+    }
+}
+async function assertPathMissing(path, label) {
+    try {
+        await lstat(path);
+    }
+    catch (error) {
+        if (isErrnoException(error) && error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    throw new Error(`${label} already exists; overwrite is not allowed`);
+}
+async function ensureSafeTemplatesDirectory(templatesDir, dnaRealPath) {
+    try {
+        const entry = await lstat(templatesDir);
+        if (entry.isSymbolicLink()) {
+            throw new Error("Templates directory must not be a symlink");
+        }
+        if (!entry.isDirectory()) {
+            throw new Error("Templates path is not a directory");
+        }
+    }
+    catch (error) {
+        if (!isErrnoException(error) || error.code !== "ENOENT")
+            throw error;
+        await mkdir(templatesDir);
+    }
+    const entry = await lstat(templatesDir);
+    if (entry.isSymbolicLink()) {
+        throw new Error("Templates directory must not be a symlink");
+    }
+    if (!entry.isDirectory()) {
+        throw new Error("Templates path is not a directory");
+    }
+    const templatesRealPath = await realpath(templatesDir);
+    if (!isStrictlyWithin(dnaRealPath, templatesRealPath)) {
+        throw new Error("Templates directory escapes the project .dna directory");
+    }
+    return templatesRealPath;
+}
+async function removeCreatedPath(path) {
+    try {
+        await rm(path, { force: true });
+        return undefined;
+    }
+    catch (error) {
+        return error;
+    }
+}
+export async function promoteCandidate(options) {
+    validateTemplateName(options.templateName);
+    const projectPath = resolve(options.projectDir);
+    const projectRealPath = await realpath(projectPath);
+    const dnaPath = join(projectPath, ".dna");
+    const authoringPath = join(dnaPath, "authoring");
+    const candidatePath = resolve(projectPath, options.candidatePath);
+    if (!isStrictlyWithin(authoringPath, candidatePath)) {
+        throw new Error("Candidate must be located within the project .dna/authoring directory");
+    }
+    const candidateFilename = basename(candidatePath);
+    if (!candidateFilename.endsWith(CANDIDATE_SUFFIX)
+        || candidateFilename.length === CANDIDATE_SUFFIX.length) {
+        throw new Error(`Candidate filename must end with ${CANDIDATE_SUFFIX}`);
+    }
+    const dnaRealPath = await realpath(dnaPath);
+    if (!isStrictlyWithin(projectRealPath, dnaRealPath)) {
+        throw new Error("Project .dna directory escapes the project root");
+    }
+    const authoringRealPath = await realpath(authoringPath);
+    if (!isStrictlyWithin(dnaRealPath, authoringRealPath)) {
+        throw new Error("Authoring directory escapes the project .dna directory");
+    }
+    const candidateRealPath = await realpath(candidatePath);
+    if (!isStrictlyWithin(authoringRealPath, candidateRealPath)) {
+        throw new Error("Candidate symlink or path escapes the project authoring directory");
+    }
+    const candidateEntry = await stat(candidateRealPath);
+    if (!candidateEntry.isFile()) {
+        throw new Error("Candidate must be a regular file in the project authoring directory");
+    }
+    const candidateBytesBeforeValidation = await readFile(candidateRealPath);
+    const validation = await loadDNAWithDiagnostics(candidateRealPath);
+    if (!validation.dna || hasDiagnosticErrors(validation.diagnostics)) {
+        const details = formatDiagnostics(validation.diagnostics);
+        throw new Error(`Candidate validation failed${details ? `:\n${details}` : ""}`);
+    }
+    const candidateRealPathAfterValidation = await realpath(candidatePath);
+    if (candidateRealPathAfterValidation !== candidateRealPath) {
+        throw new Error("Candidate path changed during validation; promotion refused");
+    }
+    const candidateBytes = await readFile(candidateRealPathAfterValidation);
+    if (!candidateBytes.equals(candidateBytesBeforeValidation)) {
+        throw new Error("Candidate bytes changed during validation; promotion refused");
+    }
+    const templatesPath = join(dnaPath, "templates");
+    const templatesRealPath = await ensureSafeTemplatesDirectory(templatesPath, dnaRealPath);
+    const templatePath = join(templatesPath, `${options.templateName}.dna.yaml`);
+    const templateWritePath = join(templatesRealPath, `${options.templateName}.dna.yaml`);
+    const candidateName = candidateFilename.slice(0, -CANDIDATE_SUFFIX.length);
+    const receiptPath = join(authoringPath, `${candidateName}.candidate-review.json`);
+    const receiptWritePath = join(authoringRealPath, `${candidateName}.candidate-review.json`);
+    await assertPathMissing(templateWritePath, "Promotion target");
+    await assertPathMissing(receiptWritePath, "Candidate review receipt");
+    const candidateHash = sha256(candidateBytes);
+    let templateCreated = false;
+    let receiptCreated = false;
+    let templateHandle;
+    let receiptHandle;
+    try {
+        templateHandle = await open(templateWritePath, "wx");
+        templateCreated = true;
+        await templateHandle.writeFile(candidateBytes);
+        await templateHandle.sync();
+        await templateHandle.close();
+        templateHandle = undefined;
+        const currentTemplatesRealPath = await realpath(templatesPath);
+        if (currentTemplatesRealPath !== templatesRealPath) {
+            throw new Error("Templates directory changed during promotion; promotion refused");
+        }
+        const promotedBytes = await readFile(templateWritePath);
+        const templateHash = sha256(promotedBytes);
+        if (!promotedBytes.equals(candidateBytes) || templateHash !== candidateHash) {
+            throw new Error("Promoted template does not preserve the validated candidate bytes exactly");
+        }
+        const receipt = {
+            schema_version: "intentdna.candidate_promotion_receipt.v1",
+            decision: "promoted",
+            source: "explicit_human_promotion",
+            mutation_performed: true,
+            promoted_at: new Date().toISOString(),
+            candidate_path: candidatePath,
+            template_path: templatePath,
+            candidate_sha256: candidateHash,
+            template_sha256: templateHash,
+            exact_bytes_preserved: true,
+        };
+        const receiptBytes = Buffer.from(`${JSON.stringify(receipt, null, 2)}\n`, "utf8");
+        receiptHandle = await open(receiptWritePath, "wx");
+        receiptCreated = true;
+        await receiptHandle.writeFile(receiptBytes);
+        await receiptHandle.sync();
+        await receiptHandle.close();
+        receiptHandle = undefined;
+        return {
+            schema_version: "intentdna.candidate_promotion_result.v1",
+            candidate_path: candidatePath,
+            template_path: templatePath,
+            receipt_path: receiptPath,
+            candidate_sha256: candidateHash,
+            template_sha256: templateHash,
+            exact_bytes_preserved: true,
+        };
+    }
+    catch (error) {
+        await receiptHandle?.close().catch(() => undefined);
+        await templateHandle?.close().catch(() => undefined);
+        const cleanupErrors = [];
+        if (receiptCreated) {
+            const cleanupError = await removeCreatedPath(receiptWritePath);
+            if (cleanupError)
+                cleanupErrors.push(cleanupError);
+        }
+        if (templateCreated) {
+            const cleanupError = await removeCreatedPath(templateWritePath);
+            if (cleanupError)
+                cleanupErrors.push(cleanupError);
+        }
+        if (cleanupErrors.length > 0) {
+            throw new AggregateError([error, ...cleanupErrors], "Candidate promotion failed and cleanup did not complete");
+        }
+        throw error;
+    }
+}

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

@@ -9,6 +9,7 @@ const TASK_STATES = [
     "ready",
     "claimed",
     "running",
+    "round_succeeded",
     "succeeded",
     "failed",
     "skipped",

package/dist/cli/commands/run.js

@@ -10,19 +10,20 @@ import { isAbsolute, join, relative, resolve, sep, } from "node:path";
 import { cascadeDNA } from "../../compiler/cascade.js";
 import { compileFromFiles, expandDNAInputFiles, loadDNA, } from "../../compiler/index.js";
 import { compileWorkflow } from "../../compiler/workflow.js";
-import { trustedEvidenceCaptureAttribution } from "../../governance/index.js";
 import { DNAStateManager } from "../../hooks/state-manager.js";
 import { appendEvidenceCaptureEvent, EVIDENCE_CAPTURE_SCHEMA_VERSION, } from "../../hooks/state.js";
 import { compileAllRolesToAgentMD, toKebabCase, writeAgentMDFiles, } from "../../runtime/agent-md.js";
 import { HandoffResolver } from "../../runtime/handoff-resolver.js";
 import { createCompiledIR, writeCompiledIR } from "../../runtime/plugin-adapter.js";
+import { createWorkflowRuntimeManifest, WORKFLOW_RUNTIME_INPUT_VARIABLE_NAMES, } from "../../runtime/workflow-runtime-manifest.js";
+import { defaultResolvedVariableScopes, indexWorkflowVariableScopes, resolvedVariablesForNamespace, } from "../../runtime/workflow-variable-scopes.js";
 import { ImmutableResultStore } from "../../runtime/result-store.js";
 import { RunController, } from "../../runtime/run-controller.js";
 import { DurableRunStore, RunStoreError, } from "../../runtime/run-store.js";
 import { createClaudeExecutionProvider } from "../../runtime/providers/claude.js";
 import { createCodexExecutionProvider } from "../../runtime/providers/codex.js";
 import { runCheckpointVerifier, runCompletionVerifier, } from "../../runtime/verifier.js";
-import { adaptWorkflowPlan, } from "../../runtime/workflow-plan-adapter.js";
+import { adaptWorkflowPlan, adaptWorkflowRetryLoop, } from "../../runtime/workflow-plan-adapter.js";
 import { executeWorkerAttempt, } from "../../runtime/worker-executor.js";
 import { allocateAttemptWorkspace, applyWorkspaceLifecycleDecision, planAttemptWorkspace, } from "../../runtime/workspace-isolation.js";
 import { runLifecycleCancel, runLifecycleInspect, runLifecycleResume, runLifecycleStart, runLifecycleStatus, } from "./run-lifecycle.js";
@@ -191,6 +192,8 @@ async function compileRunAssets(metadata) {
     for (const file of metadata.dna_files)
         dnas.push(await loadDNA(file));
     const cascaded = cascadeDNA(dnas);
+    const variableScopeIndex = indexWorkflowVariableScopes(dnas);
+    const defaultVariableScopes = defaultResolvedVariableScopes(variableScopeIndex);
     const ir = await compileFromFiles([...metadata.dna_files], {
         context: metadata.context ?? undefined,
     });
@@ -199,26 +202,31 @@ async function compileRunAssets(metadata) {
         throw new Error(`workflow '${metadata.workflow_name}' not found; available: `
             + `${Object.keys(cascaded.workflows).join(", ") || "(none)"}`);
     }
-    const result = compileWorkflow(definition, {
-        workflow_key: metadata.workflow_name,
-    });
-    if (!result.ok || !result.plan) {
-        throw new Error("workflow compilation failed:\n"
-            + result.errors.map((error) => `  ${error.path}: ${error.message}`).join("\n"));
+    const runtimePlans = [];
+    for (const [workflowKey, workflowDefinition] of Object.entries(cascaded.workflows)) {
+        const result = compileWorkflow(workflowDefinition, { workflow_key: workflowKey });
+        if (!result.ok || !result.plan) {
+            throw new Error(`workflow '${workflowKey}' compilation failed:\n`
+                + result.errors.map((error) => `  ${error.path}: ${error.message}`).join("\n"));
+        }
+        const namespace = variableScopeIndex.workflowNamespaces.get(workflowKey) ?? "";
+        runtimePlans.push({
+            plan: result.plan,
+            workflow_asset: variableScopeIndex.workflowAssets.get(workflowKey) ?? null,
+            resolved_variables: resolvedVariablesForNamespace(defaultVariableScopes, namespace, workflowKey === metadata.workflow_name ? { ...metadata.variables } : {}),
+        });
     }
-    const plan = result.plan;
-    const attribution = trustedEvidenceCaptureAttribution(ir, {
-        workflowId: metadata.workflow_name,
-    });
-    const workflowAsset = attribution.workflowAsset === "unknown"
-        ? null
-        : attribution.workflowAsset;
+    const plan = runtimePlans.find((item) => item.plan.workflow_key === metadata.workflow_name)?.plan;
+    if (!plan)
+        throw new Error(`compiled workflow '${metadata.workflow_name}' is missing from runtime plans`);
+    const workflowAsset = runtimePlans.find((item) => item.plan.workflow_key === metadata.workflow_name)?.workflow_asset ?? null;
     if (metadata.workflow_asset !== null
         && workflowAsset !== metadata.workflow_asset) {
         throw new Error(`workflow asset changed from '${metadata.workflow_asset}' to '${workflowAsset ?? "unknown"}'`);
     }
     return {
         plan,
+        runtime_plans: runtimePlans,
         roles: cascaded.roles,
         ir,
         plan_digest: planDigest(plan, cascaded.roles),
@@ -227,6 +235,20 @@ async function compileRunAssets(metadata) {
 }
 async function compileCanonicalRun(metadata) {
     const assets = await compileRunAssets(metadata);
+    if (!assets.ir.compiled_ir_hash) {
+        throw new Error("Compiled IR hash is required for canonical workflow runtime bindings");
+    }
+    const workflowRuntime = createWorkflowRuntimeManifest({
+        plans: assets.runtime_plans.map((runtimePlan) => ({
+            plan: runtimePlan.plan,
+            resolvedVariables: runtimePlan.resolved_variables,
+            workflowAsset: runtimePlan.workflow_asset ?? undefined,
+            additionalRuntimeValues: assets.ir.verifier_specs?.filter((spec) => spec.workflow_name === runtimePlan.plan.workflow_key) ?? [],
+        })),
+        compiledAt: assets.ir.compiled_at,
+        compiledIrHash: assets.ir.compiled_ir_hash,
+        sourceDnaIds: assets.ir.source_dna_ids,
+    });
     const adapterOptions = {
         roles: assets.roles,
         variables: metadata.variables,
@@ -236,13 +258,15 @@ async function compileCanonicalRun(metadata) {
     };
     return {
         ...assets,
+        workflow_runtime: workflowRuntime,
         definitions: adaptWorkflowPlan(assets.plan, adapterOptions),
+        retry_loop: adaptWorkflowRetryLoop(assets.plan, adapterOptions),
     };
 }
 async function syncRuntimeArtifacts(compiled, metadata) {
     const agents = compileAllRolesToAgentMD(compiled.roles, compiled.ir);
     await writeAgentMDFiles(agents, metadata.agents_directory);
-    await writeCompiledIR(metadata.project_directory, createCompiledIR(compiled.ir, compiled.roles));
+    await writeCompiledIR(metadata.project_directory, createCompiledIR(compiled.ir, compiled.roles, compiled.workflow_runtime));
 }
 function projectPathInWorkspace(metadata, workspaceDirectory, projectPath) {
     const projectRelative = relative(metadata.project_directory, projectPath);
@@ -261,7 +285,7 @@ async function syncAttemptRuntimeArtifacts(compiled, metadata, workspace) {
         const agents = compileAllRolesToAgentMD(compiled.roles, compiled.ir);
         await writeAgentMDFiles(agents, agentsDirectory);
     }
-    await writeCompiledIR(workspace.working_directory, createCompiledIR(compiled.ir, compiled.roles));
+    await writeCompiledIR(workspace.working_directory, createCompiledIR(compiled.ir, compiled.roles, compiled.workflow_runtime));
 }
 function createProvider(metadata) {
     if (metadata.provider.kind === "codex") {
@@ -371,7 +395,7 @@ async function applyStepValidation(metadata, compiled, packet, execution) {
     }
     const variables = {
         ...metadata.variables,
-        round: String(packet.attempt_number),
+        round: String(packet.workflow_round),
     };
     let failure = null;
     for (const completion of step.completion ?? []) {
@@ -461,31 +485,40 @@ function createWorkspaceAwareExecutor(metadata, compiled, runStore) {
         let lifecycleRecorded = false;
         try {
             await syncAttemptRuntimeArtifacts(compiled, metadata, workspace);
-            try {
-                await state.writeWorkflowState({
-                    active: true,
-                    workflow_asset: metadata.workflow_asset ?? undefined,
-                    workflow: metadata.workflow_name,
-                    current_step: packet.step_id,
-                    current_role: packet.role,
-                    iteration: packet.attempt_number,
-                    session_id: packet.worker_session_id,
-                    worker_session_id: packet.worker_session_id,
-                    run_id: packet.run_id,
-                    step_id: packet.step_id,
-                    attempt_id: packet.attempt_id,
-                    started_at: packet.created_at,
-                    inputs: { ...metadata.variables },
-                    resolved_variables: {
-                        ...metadata.variables,
-                        round: String(packet.attempt_number),
-                    },
-                });
-            }
-            catch (error) {
-                log(`Workflow evidence state unavailable for ${packet.step_id}; `
-                    + `continuing fail-open: ${error instanceof Error ? error.message : String(error)}`);
+            const runtimeBinding = compiled.workflow_runtime.workflows[metadata.workflow_name];
+            if (!runtimeBinding)
+                throw new Error(`Missing runtime binding for ${metadata.workflow_name}`);
+            const canonicalArguments = metadata.variables.ARGUMENTS ??
+                metadata.variables.arguments ?? metadata.variables.task_id;
+            const runtimeInputs = {};
+            for (const name of runtimeBinding.runtime_input_refs) {
+                const value = WORKFLOW_RUNTIME_INPUT_VARIABLE_NAMES.has(name)
+                    ? canonicalArguments
+                    : metadata.variables[name];
+                if (value === undefined)
+                    throw new Error(`Missing runtime input ${name} for ${metadata.workflow_name}`);
+                runtimeInputs[name] = value;
             }
+            await state.writeWorkflowState({
+                active: true,
+                workflow_asset: runtimeBinding.workflow_asset,
+                workflow: metadata.workflow_name,
+                current_step: packet.step_id,
+                current_role: packet.role,
+                iteration: packet.workflow_round,
+                session_id: packet.worker_session_id,
+                worker_session_id: packet.worker_session_id,
+                run_id: packet.run_id,
+                step_id: packet.step_id,
+                attempt_id: packet.attempt_id,
+                started_at: packet.created_at,
+                inputs: Object.keys(runtimeInputs).length > 0 ? runtimeInputs : undefined,
+                resolved_variables: runtimeBinding.resolved_variables,
+                resolved_variables_source: "compiled_manifest",
+                workflow_runtime_manifest_hash: compiled.workflow_runtime.manifest_hash,
+                workflow_runtime_compiled_ir_hash: compiled.workflow_runtime.compiled_ir_hash,
+                workflow_inputs_pinned: true,
+            });
             const inheritedProcessObserver = options?.onProcessStart;
             let execution = await executeWorkerAttempt(workerPacket, provider, {
                 ...options,
@@ -533,6 +566,7 @@ function buildRuntime(metadata, compiled) {
         run_store: runStore,
         handoff_resolver: resolver,
         steps: compiled.definitions,
+        workflow_retry_loop: compiled.retry_loop,
         provider_for_step: () => provider,
         reconcile_attempt: reconcileLocalProcess,
         execute_attempt: createWorkspaceAwareExecutor(metadata, compiled, runStore),

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

@@ -19,4 +19,14 @@ export interface SetupOptions {
     yes: boolean;
     upgrade: boolean;
 }
+/**
+ * Check if intentdna is already registered as a plugin.
+ */
+export interface InstalledPluginInfo {
+    version: string | null;
+    enabled: boolean;
+}
+export declare function parseInstalledPluginInfo(output: string): InstalledPluginInfo | null;
+export declare function releaseChannelForVersion(version: string | null): "latest" | "next";
+export declare function shouldInstallLatestVersion(installedVersion: string, latestVersion: string): boolean;
 export declare function runSetup(opts: SetupOptions): Promise<number>;