@williambeto/ai-workflow 2.8.2 → 2.9.0

package/core/index.d.ts

@@ -168,8 +168,10 @@ declare class EvidenceLedger {
     verifyRoleConfinement(): Promise<RoleConfinementResult>;
 }
 
-interface InspectResult {
+type RuntimeName = "opencode" | "codex";
+interface RuntimeInspection {
     available: boolean;
+    projectTrusted?: boolean;
     supports: {
         run: boolean;
         server: boolean;
@@ -178,7 +180,7 @@ interface InspectResult {
         model: boolean;
     };
 }
-interface ExecuteOptions {
+interface RuntimeExecuteOptions {
     agent?: string | null;
     model?: string | null;
     readOnly?: boolean;
@@ -193,7 +195,7 @@ interface ObservedCommand {
     exitCode: number | null;
     source: "sdk" | "json-event" | "text-output";
 }
-interface ExecuteResult {
+interface RuntimeExecuteResult {
     success: boolean;
     status?: string;
     commandsRun: string[];
@@ -208,27 +210,20 @@ interface ExecuteResult {
     output?: string;
 }
 /**
- * OpenCodeAdapter - Real runtime integration with the OpenCode CLI.
+ * Runtime boundary used by the execution controller. Adapters must report
+ * only commands and actors observed from the runtime, never agent claims.
  */
-declare class OpenCodeAdapter {
-    cwd: string;
-    constructor({ cwd }?: {
-        cwd?: string;
-    });
-    /**
-     * Inspects the availability and capability of the OpenCode CLI.
-     */
-    inspect(): Promise<InspectResult>;
-    /**
-     * Runs opencode with a prompt and options.
-     */
-    execute(message: string, { agent, model, readOnly, fastTrack, requireActorConfirmation, orchestratedChild }?: ExecuteOptions): Promise<ExecuteResult>;
+interface RuntimeAdapter {
+    readonly runtime: RuntimeName;
+    readonly provenance: string;
+    inspect(): Promise<RuntimeInspection>;
+    execute(message: string, options?: RuntimeExecuteOptions): Promise<RuntimeExecuteResult>;
 }
 
 interface DelegationControllerOptions {
     cwd?: string;
     ledger?: EvidenceLedger;
-    adapter?: OpenCodeAdapter;
+    adapter?: RuntimeAdapter;
 }
 interface PhaseArtifactResult {
     artifactPath?: string;
@@ -243,7 +238,7 @@ interface DelegationPhaseOptions {
     requireExplicitActor?: boolean;
     onOutput?: (output: string) => Promise<PhaseArtifactResult | void>;
 }
-interface DelegationPhaseResult extends ExecuteResult {
+interface DelegationPhaseResult extends RuntimeExecuteResult {
     artifact?: PhaseArtifactResult;
 }
 /**
@@ -252,7 +247,7 @@ interface DelegationPhaseResult extends ExecuteResult {
 declare class DelegationController {
     cwd: string;
     ledger?: EvidenceLedger;
-    adapter: OpenCodeAdapter;
+    adapter: RuntimeAdapter;
     lastRoutingDecision: RoutingDecision | null;
     constructor({ cwd, ledger, adapter }?: DelegationControllerOptions);
     /**
@@ -487,4 +482,53 @@ declare class SpecValidator {
     validate(filePath: string): Promise<SpecValidationResult>;
 }
 
-export { BranchGate, DelegationController, EvidenceLedger, ExecutionPlanner, Finalizer, HandoffEngine, HealerEngine, MergeGate, OpenCodeAdapter, RequestClassifier, SpecValidator, WorkflowStateMachine };
+/**
+ * OpenCodeAdapter - Real runtime integration with the OpenCode CLI.
+ */
+declare class OpenCodeAdapter implements RuntimeAdapter {
+    readonly runtime: "opencode";
+    readonly provenance = "opencode-adapter";
+    cwd: string;
+    constructor({ cwd }?: {
+        cwd?: string;
+    });
+    /**
+     * Inspects the availability and capability of the OpenCode CLI.
+     */
+    inspect(): Promise<RuntimeInspection>;
+    /**
+     * Runs opencode with a prompt and options.
+     */
+    execute(message: string, { agent, model, readOnly, fastTrack, requireActorConfirmation, orchestratedChild }?: RuntimeExecuteOptions): Promise<RuntimeExecuteResult>;
+}
+
+/**
+ * Codex capability boundary. Native Codex assets support interactive sessions;
+ * non-interactive `codex exec` is blocked until an app-server adapter can
+ * observe custom-agent ownership reliably.
+ */
+declare class CodexRuntimeAdapter implements RuntimeAdapter {
+    readonly runtime: "codex";
+    readonly provenance = "codex-cli-jsonl";
+    cwd: string;
+    constructor({ cwd }?: {
+        cwd?: string;
+    });
+    private isProjectTrusted;
+    inspect(): Promise<RuntimeInspection>;
+    execute(_message: string, { agent, readOnly }?: RuntimeExecuteOptions): Promise<RuntimeExecuteResult>;
+}
+
+interface CreateRuntimeAdapterOptions {
+    cwd: string;
+    runtime?: RuntimeName | string;
+}
+/**
+ * Resolves an explicitly requested runtime first. A dual-runtime installation
+ * keeps OpenCode as its default so existing consumers do not change behavior
+ * until they opt into `--runtime=codex`.
+ */
+declare function resolveRuntime({ cwd, runtime }: CreateRuntimeAdapterOptions): Promise<RuntimeName>;
+declare function createRuntimeAdapter(options: CreateRuntimeAdapterOptions): Promise<RuntimeAdapter>;
+
+export { BranchGate, CodexRuntimeAdapter, DelegationController, EvidenceLedger, ExecutionPlanner, Finalizer, HandoffEngine, HealerEngine, MergeGate, OpenCodeAdapter, RequestClassifier, type RuntimeAdapter, type RuntimeExecuteOptions, type RuntimeExecuteResult, type RuntimeInspection, type RuntimeName, SpecValidator, WorkflowStateMachine, createRuntimeAdapter, resolveRuntime };

package/core/index.js

@@ -1,4 +1,5 @@
 import {
+  CodexRuntimeAdapter,
   DelegationController,
   EvidenceLedger,
   ExecutionPlanner,
@@ -8,8 +9,10 @@ import {
   OpenCodeAdapter,
   RequestClassifier,
   SpecValidator,
-  WorkflowStateMachine
-} from "../chunk-4FI5ODAM.js";
+  WorkflowStateMachine,
+  createRuntimeAdapter,
+  resolveRuntime
+} from "../chunk-JDSEOEYW.js";
 import {
   MergeGate
 } from "../chunk-H7GIKXFO.js";
@@ -19,6 +22,7 @@ import {
 import "../chunk-5WRI5ZAA.js";
 export {
   BranchGate,
+  CodexRuntimeAdapter,
   DelegationController,
   EvidenceLedger,
   ExecutionPlanner,
@@ -29,6 +33,8 @@ export {
   OpenCodeAdapter,
   RequestClassifier,
   SpecValidator,
-  WorkflowStateMachine
+  WorkflowStateMachine,
+  createRuntimeAdapter,
+  resolveRuntime
 };
 //# sourceMappingURL=index.js.map

package/dist-assets/docs/cli-reference.md

@@ -49,7 +49,7 @@ Orchestrates execution of a natural language request through the workflow state
 
 **Synopsis:**
 ```bash
-ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"]
+ai-workflow execute "<request>" [--task=<slug>] [--request="<request>"] [--runtime=<opencode|codex>]
 ```
 
 **Description:**
@@ -60,6 +60,7 @@ Accepts a natural language request, classifies intent, selects the appropriate p
 | `"<request>"` | Positional argument: the natural language request |
 | `--request="<request>"` | Named alternative for the request string |
 | `--task=<slug>` | Optional custom task slug for the workflow execution |
+| `--runtime=<runtime>` | Runtime override: `opencode` or `codex`; Codex CLI delivery blocks until an app-server adapter can prove native-agent ownership |
 
 **Example:**
 ```bash
@@ -75,7 +76,7 @@ Runs formal orchestration for an approved specification with branch safety, obse
 
 **Synopsis:**
 ```bash
-ai-workflow run --spec-path=<path> [--approval-path=<path>]
+ai-workflow run --spec-path=<path> [--approval-path=<path>] [--runtime=<opencode|codex>]
 ```
 
 **Description:**
@@ -85,6 +86,7 @@ Reads an approved specification file and orchestrates the full implementation wo
 | --- | --- |
 | `--spec-path=<path>` | Path to the approved specification file (required) |
 | `--approval-path=<path>` | Path to the approval receipt required for DEEP specifications |
+| `--runtime=<runtime>` | Runtime override: `opencode` or `codex` for DEEP workflow delegation; Codex blocks until app-server-based ownership evidence exists |
 
 **Example:**
 ```bash

package/dist-assets/docs/compatibility/provider-usage.md

@@ -15,7 +15,7 @@ For CLI-enforced branch, delivery, validation, and evidence gates, use:
 npx @williambeto/ai-workflow execute "<natural-language request>"
 ```
 
-Direct Atlas sessions depend on the selected provider model following the installed agent contract. GPT-5.6 Sol is the validated direct-session model for this release. GPT-5.3 Codex Spark in medium mode is experimental because observed sessions delegated correctly but did not consistently produce a runnable, validated workspace delivery. The finalizer still blocks false success, but it cannot make an incompatible model complete the implementation.
+Direct Atlas sessions depend on the selected provider model following the installed agent contract. GPT-5.6 Sol Medium is the validated direct-session model for this release. GPT-5.3 Codex Spark is unsupported for workspace-write delivery: repeated clean-repository tests with the same local tarball returned source code in chat without observed branch gating, Astra delegation, file changes, or validation. The finalizer can block false success, but it cannot make an incompatible model complete the implementation.
 
 ## Codex
 
@@ -23,7 +23,18 @@ Direct Atlas sessions depend on the selected provider model following the instal
 npx @williambeto/ai-workflow init --yes --codex
 ```
 
-Review generated `AGENTS.md`, `CODEX.md`, `.codex/skills/`, `.codex/prompts/`, and `.codex/docs/policies/`. The root `AGENTS.md` provides the primary project-level instruction contract. The `ai-workflow doctor` command will automatically validate these assets.
+Review generated `AGENTS.md`, `.codex/agents/`, `.codex/skills/`, and `.codex/docs/policies/`. The root `AGENTS.md` provides the primary project-level instruction contract, native role definitions are TOML files under `.codex/agents/`, and AIWK commands are installed as `aiwk-command-*` skills rather than prompt files.
+
+Use a trusted interactive Codex session only for experimental evaluation. `ai-workflow execute --runtime=codex` intentionally returns `BLOCKED`: current non-interactive `codex exec` cannot select and prove the custom agent that made the change, so AIWK will not claim Astra ownership without evidence.
+
+`ai-workflow doctor` validates generated structure and local CLI capabilities without spending model tokens. Codex remains experimental until an app-server-based release E2E proves native delegation, a workspace delivery, and observed validation.
+
+Codex loads project-local agent configuration only after the repository is trusted. Trust the consumer repository in Codex before running a delegated workflow; `ai-workflow doctor` fails closed while that trust gate is absent. The equivalent user-level Codex configuration is:
+
+```toml
+[projects."/absolute/path/to/project"]
+trust_level = "trusted"
+```
 
 ## Claude Code
 

package/dist-assets/docs/compatibility/runtime-matrix.md

@@ -10,7 +10,7 @@
 | Runtime | Level | Generated integration | Current evidence | Known limitations |
 | --- | --- | --- | --- | --- |
 | OpenCode | Primary | `opencode.jsonc`, OpenCode agents, commands, and skills | init, doctor, package smoke, generated-file checks, real GPT-5.6 Sol delivery | Direct-agent behavior depends on a validated model; use `ai-workflow execute` for CLI-enforced gates |
-| Codex | Supported | `AGENTS.md`, `CODEX.md`, `.codex/skills/`, `.codex/prompts/` | full `ai-workflow doctor` runtime validation, e2e smoke checks | `.codex/` output requires `--codex` flag |
+| Codex | Experimental | `AGENTS.md`, `.codex/agents/`, `.codex/skills/`, `.codex/docs/policies/` | native-asset unit tests, consumer init/doctor smoke, and real discovery of AGENTS.md plus skills | The consumer must be trusted by Codex; `codex exec` cannot prove custom-agent ownership, so CLI delivery blocks pending an app-server E2E |
 | Claude Code | Supported with limitations | `CLAUDE.md`, `.claude/rules/` | adapter/unit/structural checks and generated asset inspection | Rule loading and tool permissions depend on Claude Code configuration |
 | Antigravity | Supported | `ANTIGRAVITY.md`, `.agents/agents/`, `.agents/skills/`, `.agents/commands/` | unit tests, validation suite, and WSL/Desktop consumer validation | Agents are only listed under `/agents` when actively running (instantiated via `invoke_subagent`) |
 
@@ -24,10 +24,10 @@ OpenCode runtime compatibility does not imply that every provider model follows
 
 | Model and mode | Direct Atlas status | Observed behavior |
 | --- | --- | --- |
-| GPT-5.6 Sol | Supported | Completed branch gate, one Astra delegation, workspace implementation, proportional validation, browser inspection, and finalization |
-| GPT-5.3 Codex Spark, medium | Experimental | Delegated to Astra, but produced an incomplete scaffold, failed required validation, and repeated source code in the handoff; the finalizer correctly blocked false success |
+| GPT-5.6 Sol, medium | Supported | Completed branch gate, one Astra delegation, workspace implementation, proportional validation, browser inspection, and finalization in a clean repository installed from the local release tarball |
+| GPT-5.3 Codex Spark | Unsupported for workspace-write delivery | Repeated clean-repository tests with the same tarball returned source code in chat without observed branch gating, Astra delegation, workspace changes, or validation |
 
-The canonical enforcement path is `ai-workflow execute`. Direct Atlas sessions are supported only for model configurations that pass the release smoke suite. Experimental models may inspect or generate partial work, but their direct-session behavior is not a supported delivery guarantee.
+The canonical enforcement path is `ai-workflow execute`. Direct Atlas sessions are supported only for model configurations that pass the release smoke suite. Unsupported write models may still be used for read-only analysis, but their output must not be accepted as workspace delivery.
 
 ## Promotion requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@williambeto/ai-workflow",
-  "version": "2.8.2",
+  "version": "2.9.0",
   "description": "AI Workflow Kit — OpenCode-first software delivery workflow with agents, commands, skills, validation, and evidence",
   "license": "MIT",
   "author": "José Willams",