agentic-orchestrator 0.1.13 → 0.1.15

package/AGENTS.md

@@ -0,0 +1,139 @@
+# AGENTS.md
+
+This file provides guidance to coding agents operating in this repository.
+
+## Build & Development Commands
+
+```bash
+npm run build              # Lint + TypeScript compile
+npm run typecheck          # tsc --noEmit (type-check only)
+npm run lint               # ESLint with --max-warnings 0
+npm run lint:fix           # ESLint with auto-fix
+npm run test               # Vitest with coverage (via Nx)
+npm run run                # Run CLI: tsx apps/control-plane/src/cli/aop.ts
+
+# Run a single test file
+npx vitest run apps/control-plane/test/<file>.spec.ts
+
+# Run tests matching a pattern
+npx vitest run -t "pattern"
+
+# Validation scripts (also run in CI)
+npm run validate:mcp-contracts
+npm run validate:architecture
+npm run validate:docker-mcp
+```
+
+## Architecture
+
+This is an MCP-first, multi-agent orchestrator control plane. The codebase lives in an Nx monorepo with a single application at `apps/control-plane/`.
+
+### Layer Overview
+
+**CLI** (`apps/control-plane/src/cli/`) -> **Supervisor** (`supervisor/`) -> **Kernel** (`core/kernel.ts`) -> **Services** (`application/services/`)
+
+- **CLI**: Entry point at `cli/aop.ts` -> delegates to `interfaces/cli/bootstrap.ts`. Commands: `run`, `status`, `resume`, `stop`, `delete`, `cleanup`, `init`, `dashboard`, `retry`, `send`, `attach`, `help`. All responses are structured JSON with `{ ok, data/error }`. Run `aop --help` or `aop help <command>` for usage details.
+- **Kernel** (`core/kernel.ts`, ~900 lines): Deterministic orchestration engine. Manages schema validation, state, locks, plans, patches, gates, merges, and reporting. Delegates to 12+ domain services via port interfaces.
+- **Supervisor** (`supervisor/runtime.ts`): Multi-agent runtime. Resolves providers (codex, claude, gemini, etc.), loads role-specific prompts, orchestrates planning/build/QA waves, and manages lease heartbeats.
+- **MCP Tool Runtime** (`mcp/tool-runtime.ts`): Tool execution pipeline with registry-based dispatch, input/output schema validation, role-based authorization, and idempotency tracking via `operation_id`.
+- **Application Services** (`application/services/`): 12+ focused services (plan, patch, gates, QA, locks, merge, deletion, etc.) implementing port interfaces consumed by the kernel.
+
+### Configuration Layer (`config/agentic/orchestrator/`)
+
+- `policy.yaml` - Commit/patch/merge policies, lock TTL, RBAC, supervisor iteration limits
+- `gates.yaml` - Gate profiles (fast/full/merge) with commands and coverage thresholds
+- `agents.yaml` - Agent roles (planner/builder/qa), provider defaults, prompt paths
+- `prompts/` - Role-specific system prompts
+- `tools/` - MCP tool contracts: `catalog.json` (33 tools), per-tool `schemas/input/` and `schemas/output/`
+- `schemas/` - JSON schemas for policy, state, plan, index, gates, agents, qa_test_index
+
+### Runtime Artifacts (`.aop/`)
+
+- `.aop/features/index.json` - Global feature index (active/blocked/merged features, locks, sessions)
+- `.aop/features/<id>/state.md` - Per-feature state (YAML frontmatter + markdown)
+- `.aop/features/<id>/plan.json` - Versioned plan with optimistic concurrency
+- `.aop/features/<id>/evidence/` - Gate evidence artifacts
+
+## Key Patterns
+
+- **Port-based DI**: Services define interface ports; the kernel implements them. This decouples domain logic from infrastructure.
+- **Schema-driven validation**: All configs and artifacts validated via AJV against JSON schemas. Validation failures return structured errors with retry hints.
+- **Atomic state management**: File locks, version guards, and optimistic concurrency for all state mutations.
+- **Structured error codes**: 45+ error codes with `{ code, message, details: { retryable, requires_human, suggestions } }`.
+- **Tool registry dispatch**: `catalog.json` metadata drives tool routing, replacing switch-based dispatch. Mutating tools require `operation_id` for idempotency.
+
+## Design Principles
+
+- **KISS (Keep It Simple, Stupid)**: Prefer the simplest design that satisfies requirements and preserves deterministic behavior.
+- **SRP (Single Responsibility Principle)**: Each class/module should have one clear reason to change.
+- **SOLID (pragmatic application)**:
+  - Open/Closed: Extend by adding adapters/services instead of modifying unrelated orchestrator flow.
+  - Interface Segregation: Keep interfaces focused (avoid broad "do everything" contracts).
+  - Dependency Inversion: Depend on ports/interfaces, not concrete infrastructure.
+- **Hexagonal Architecture**: Domain/application layers must not depend directly on provider CLI/SDK details; keep those in adapter boundaries.
+- **Composition over Inheritance**: Build behavior through composed collaborators (factory + adapter + parser + service) rather than deep class hierarchies.
+- **High Cohesion, Low Coupling**: Keep CLI parsing, provider execution, orchestration logic, and persistence concerns in separate modules.
+
+## Lint Rules to Know
+
+- `no-explicit-any` is **enforced** in source, relaxed in tests
+- `no-floating-promises` and `no-misused-promises` are errors
+- `require-await` is enforced in source, relaxed in tests
+- `consistent-type-imports` is required (use `import type` for type-only imports)
+- `no-console` is an error in source (except `warn`/`error`); allowed in scripts and CLI entry point
+- Unused variables must be prefixed with `_`
+- Zero warnings allowed (`--max-warnings 0`)
+
+## Adding a New CLI Command or Flag
+
+When adding a new command or flag to the CLI, update **all** of the following in the same change:
+
+1. **`apps/control-plane/src/cli/types.ts`** - add the command to the `CliCommand` enum.
+2. **`apps/control-plane/src/cli/cli-argument-parser.ts`** - parse the new flag/command token.
+3. **`apps/control-plane/src/interfaces/cli/bootstrap.ts`** - dispatch the new command.
+4. **`apps/control-plane/src/cli/help-command-handler.ts`** - add or update the entry in `COMMAND_HELP` (both the command summary and its flags list). This is the source of truth for `aop --help` output.
+5. **`CLAUDE.md` and `AGENTS.md`** - update command lists/documentation to keep both assistant guides aligned.
+
+## Coverage Thresholds
+
+Lines: 90% | Branches: 90% | Functions: 90% | Statements: 90%
+
+## Updating progress.md
+
+`spec-files/progress.md` is the versioned work log for this repository. **After completing any meaningful code change** (new feature, bug fix, refactor, test coverage improvement, validator change, etc.), append a new numbered entry to the **Completed Tasks** section of `progress.md`.
+
+### Entry format
+
+Each entry must include:
+
+- A sequential number (increment from the last entry)
+- A short title describing what was done
+- **Goal** - one sentence on why the change was made
+- **Changes made** - bullet list of files modified and what changed; be specific (function names, test counts, metric deltas)
+- **Result** - outcome verification (e.g. `npm test [PASS]`, `npm run lint [PASS]`, validator output)
+
+```text
+Entry N - Short Title
+   - **Goal:** One-sentence description of the problem or objective.
+   - **Changes made:**
+     - `path/to/file.ts` - description of what changed and why.
+     - `apps/control-plane/test/foo.spec.ts` - X tests added covering Y branches.
+   - **Result:** `npm test` [PASS] (N test files / M tests passing). `npm run lint` [PASS].
+```
+
+### Rules
+
+- **One entry per logical unit of work.** Don't bundle unrelated changes into one entry.
+- **Do not edit or renumber past entries.** The log is append-only.
+- Entries go in the **Completed Tasks** section (before the `## Next Tasks:` heading).
+- The `## Next Tasks:` section lists only work that has **not yet been done**. Move items out of it once completed.
+- After completing work from a spec file, update the **Spec Gap Tracker** table (if present) to mark the item as complete.
+
+## Executing a Spec
+
+When beginning work from a spec file (for example `spec-files/agentic_orchestrator_*.md`):
+
+1. **Before writing any code**, read the spec and add all planned tasks to the `## Next Tasks:` section of `progress.md`. Use the spec's section numbers as identifiers (for example `Section 3.1 - Add mutating cross-check`).
+2. **As each task completes**, move it out of `## Next Tasks:` and into a new numbered `Entry N - ...` in the Completed Tasks section.
+3. **Never leave a completed task in `## Next Tasks:`**. The section must only contain work that hasn't started or isn't finished.
+4. If a task is blocked or deferred, leave it in `## Next Tasks:` with a `[BLOCKED]` or `[DEFERRED]` annotation and a one-line reason.

package/CLAUDE.md

@@ -62,6 +62,18 @@ This is an MCP-first, multi-agent orchestrator control plane. The codebase lives
 - **Structured error codes**: 45+ error codes with `{ code, message, details: { retryable, requires_human, suggestions } }`.
 - **Tool registry dispatch**: `catalog.json` metadata drives tool routing, replacing switch-based dispatch. Mutating tools require `operation_id` for idempotency.
 
+## Design Principles
+
+- **KISS (Keep It Simple, Stupid)**: Prefer the simplest design that satisfies requirements and preserves deterministic behavior.
+- **SRP (Single Responsibility Principle)**: Each class/module should have one clear reason to change.
+- **SOLID (pragmatic application)**:
+  - Open/Closed: Extend by adding adapters/services instead of modifying unrelated orchestrator flow.
+  - Interface Segregation: Keep interfaces focused (avoid broad "do everything" contracts).
+  - Dependency Inversion: Depend on ports/interfaces, not concrete infrastructure.
+- **Hexagonal Architecture**: Domain/application layers must not depend directly on provider CLI/SDK details; keep those in adapter boundaries.
+- **Composition over Inheritance**: Build behavior through composed collaborators (factory + adapter + parser + service) rather than deep class hierarchies.
+- **High Cohesion, Low Coupling**: Keep CLI parsing, provider execution, orchestration logic, and persistence concerns in separate modules.
+
 ## Lint Rules to Know
 
 - `no-explicit-any` is **enforced** in source, relaxed in tests

package/agentic/orchestrator/agents.yaml

@@ -10,6 +10,9 @@ missing_prompt_behavior: ignore
 runtime:
   default_provider: custom
   default_model: local-default
+  worker_provider_mode: live
+  worker_response_timeout_ms: 120000
+  max_consecutive_no_progress_iterations: 2
   provider_config_env: AOP_PROVIDER_CONFIG_ENV
   provider_configs:
     kiro-cli:

package/agentic/orchestrator/defaults/policy.defaults.yaml

@@ -48,6 +48,9 @@ path_rules:
   allow_symlink_traversal: false
 execution:
   default_step_timeout_seconds: 600
+  require_live_provider_for_run: true
+  malformed_worker_output_action: block_feature
+  no_progress_action: block_feature
   retry_policy:
     transient_max_retries: 1
     transient_error_codes:

package/agentic/orchestrator/policy.yaml

@@ -48,6 +48,9 @@ path_rules:
   allow_symlink_traversal: false
 execution:
   default_step_timeout_seconds: 600
+  require_live_provider_for_run: true
+  malformed_worker_output_action: block_feature
+  no_progress_action: block_feature
   retry_policy:
     transient_max_retries: 1
     transient_error_codes:

package/agentic/orchestrator/schemas/agents.schema.json

@@ -48,6 +48,21 @@
           "type": "string",
           "description": "Default model string passed to the provider SDK. Overridden by --agent-model CLI flag or AOP_AGENT_MODEL env var."
         },
+        "worker_provider_mode": {
+          "type": "string",
+          "description": "Execution mode for worker providers. 'live' uses provider-backed execution, 'stub' uses NullWorkerProvider.",
+          "enum": ["live", "stub"]
+        },
+        "worker_response_timeout_ms": {
+          "type": "number",
+          "description": "Timeout in milliseconds for a single worker execution request.",
+          "minimum": 1
+        },
+        "max_consecutive_no_progress_iterations": {
+          "type": "number",
+          "description": "Consecutive no-progress worker iterations allowed before no-progress policy action is triggered.",
+          "minimum": 1
+        },
         "default_agent_config": {
           "type": "object",
           "description": "Default agent configuration object forwarded to the provider SDK when no provider-specific entry exists in provider_configs."

package/agentic/orchestrator/schemas/policy.schema.json

@@ -206,6 +206,20 @@
           "minimum": 1,
           "description": "Default execution timeout applied to each gate step that does not declare its own timeout_seconds."
         },
+        "require_live_provider_for_run": {
+          "type": "boolean",
+          "description": "When true, run/resume reject stub worker providers and require live provider execution."
+        },
+        "malformed_worker_output_action": {
+          "type": "string",
+          "description": "Action taken when worker output cannot be parsed or contains unsupported output types.",
+          "enum": ["block_feature", "fail_run"]
+        },
+        "no_progress_action": {
+          "type": "string",
+          "description": "Action taken when a live worker repeatedly produces no actionable outputs.",
+          "enum": ["block_feature", "fail_run"]
+        },
         "retry_policy": {
           "type": "object",
           "description": "Governs automatic retries for transient gate execution failures.",

package/apps/control-plane/src/cli/cli-argument-parser.ts

@@ -99,6 +99,13 @@ export class CliArgumentParser {
         index += 1;
         continue;
       }
+      if (token === '--worker-provider-mode') {
+        if (next === 'live' || next === 'stub') {
+          options.worker_provider_mode = next;
+          index += 1;
+        }
+        continue;
+      }
       if (token === '--transport') {
         options.transport = next;
         index += 1;

package/apps/control-plane/src/cli/help-command-handler.ts

@@ -27,6 +27,10 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
         flag: '--provider-config-env <var>',
         description: 'Env var name used for API-backed provider auth/config',
       },
+      {
+        flag: '--worker-provider-mode <live|stub>',
+        description: 'Worker execution mode override (default: live for run/resume)',
+      },
       { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
       { flag: '--takeover-stale-run', description: 'Take over a stale run lease' },
       { flag: '--project <name>', description: 'Select project from multi-project.yaml' },
@@ -47,6 +51,10 @@ const COMMAND_HELP: Record<CliCommand, CommandHelp> = {
     flags: [
       { flag: '--feature-id <id>', description: 'Resume a specific feature' },
       { flag: '--force', description: 'Force-resume even if the feature is not blocked' },
+      {
+        flag: '--worker-provider-mode <live|stub>',
+        description: 'Worker execution mode override (default: live)',
+      },
       { flag: '--transport <inprocess|mcp>', description: 'Tool transport layer (default: mcp)' },
     ],
   },

package/apps/control-plane/src/cli/init-command-handler.ts

@@ -259,6 +259,9 @@ path_rules:
   allow_symlink_traversal: false
 execution:
   default_step_timeout_seconds: 600
+  require_live_provider_for_run: true
+  malformed_worker_output_action: block_feature
+  no_progress_action: block_feature
   retry_policy:
     transient_max_retries: 1
     transient_error_codes:
@@ -420,6 +423,9 @@ missing_prompt_behavior: ignore
 runtime:
   default_provider: ${wizard.defaultProvider}
   default_model: ${wizard.defaultModel}
+  worker_provider_mode: live
+  worker_response_timeout_ms: 120000
+  max_consecutive_no_progress_iterations: 2
 ${providerConfigEnvLine}  role_provider_overrides: {}
 `;
 }

package/apps/control-plane/src/cli/resume-command-handler.ts

@@ -1,5 +1,12 @@
 import { STATUS } from '../core/constants.js';
-import { resolveProviderSelection, NullWorkerProvider } from '../providers/providers.js';
+import { resolveProviderSelection } from '../providers/providers.js';
+import {
+  DefaultWorkerProviderFactory,
+  resolveWorkerProviderMode,
+  resolveWorkerProviderPolicy,
+  resolveWorkerProviderRuntime,
+  type WorkerProviderFactory,
+} from '../providers/worker-provider-factory.js';
 import { SupervisorRuntime } from '../supervisor/runtime.js';
 import type { AopKernel } from '../core/kernel.js';
 import type { ToolClient } from '../mcp/tool-client.js';
@@ -84,6 +91,12 @@ interface ResumePlan {
 }
 
 export class ResumeCommandHandler {
+  private readonly workerProviderFactory: WorkerProviderFactory;
+
+  constructor(workerProviderFactory: WorkerProviderFactory = new DefaultWorkerProviderFactory()) {
+    this.workerProviderFactory = workerProviderFactory;
+  }
+
   async execute(context: ResumeCommandContext): Promise<unknown> {
     const { env, runId, transport, options, kernel, toolClient } = context;
     const recovery = await kernel.recoverFromState();
@@ -108,7 +121,23 @@ export class ResumeCommandHandler {
       agentsConfig: kernel.getAgentsConfig(),
     });
 
-    const provider = new NullWorkerProvider(selection);
+    const runtimeConfig = resolveWorkerProviderRuntime(kernel.getAgentsConfig().runtime);
+    const policySnapshot = kernel.getPolicySnapshot();
+    const executionPolicy =
+      policySnapshot.execution && typeof policySnapshot.execution === 'object'
+        ? (policySnapshot.execution as Record<string, unknown>)
+        : null;
+    const provider = this.workerProviderFactory.create({
+      selection,
+      mode: resolveWorkerProviderMode(
+        options.worker_provider_mode,
+        kernel.getAgentsConfig().runtime?.worker_provider_mode,
+        'live',
+      ),
+      context: 'resume',
+      policy: resolveWorkerProviderPolicy(executionPolicy),
+      runtime: runtimeConfig,
+    });
     const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
       max_active_features: 5,
       max_parallel_gate_runs: 3,

package/apps/control-plane/src/cli/run-command-handler.ts

@@ -1,6 +1,13 @@
 import fs from 'node:fs/promises';
 import path from 'node:path';
-import { resolveProviderSelection, NullWorkerProvider } from '../providers/providers.js';
+import { resolveProviderSelection } from '../providers/providers.js';
+import {
+  DefaultWorkerProviderFactory,
+  resolveWorkerProviderMode,
+  resolveWorkerProviderPolicy,
+  resolveWorkerProviderRuntime,
+  type WorkerProviderFactory,
+} from '../providers/worker-provider-factory.js';
 import { SupervisorRuntime } from '../supervisor/runtime.js';
 import { TOOLS } from '../core/constants.js';
 import type { AopKernel } from '../core/kernel.js';
@@ -36,9 +43,14 @@ interface FeatureIndex {
 
 export class RunCommandHandler {
   private readonly spawnDelayMs: number;
+  private readonly workerProviderFactory: WorkerProviderFactory;
 
-  constructor(spawnDelayMs = 500) {
+  constructor(
+    spawnDelayMs = 500,
+    workerProviderFactory: WorkerProviderFactory = new DefaultWorkerProviderFactory(),
+  ) {
     this.spawnDelayMs = spawnDelayMs;
+    this.workerProviderFactory = workerProviderFactory;
   }
 
   async execute(context: RunCommandContext): Promise<unknown> {
@@ -70,7 +82,23 @@ export class RunCommandHandler {
       agentsConfig: kernel.getAgentsConfig(),
     });
 
-    const provider = new NullWorkerProvider(selection);
+    const runtimeConfig = resolveWorkerProviderRuntime(kernel.getAgentsConfig().runtime);
+    const policySnapshot = kernel.getPolicySnapshot();
+    const executionPolicy =
+      policySnapshot.execution && typeof policySnapshot.execution === 'object'
+        ? (policySnapshot.execution as Record<string, unknown>)
+        : null;
+    const provider = this.workerProviderFactory.create({
+      selection,
+      mode: resolveWorkerProviderMode(
+        options.worker_provider_mode,
+        kernel.getAgentsConfig().runtime?.worker_provider_mode,
+        'live',
+      ),
+      context: 'run',
+      policy: resolveWorkerProviderPolicy(executionPolicy),
+      runtime: runtimeConfig,
+    });
     const supervisor = new SupervisorRuntime(kernel, provider, toolClient, {
       max_active_features: maxActiveFeatures ?? 5,
       max_parallel_gate_runs: maxParallelGateRuns ?? 3,

package/apps/control-plane/src/cli/types.ts

@@ -27,6 +27,7 @@ export interface CliOptions {
   agent_model?: string;
   agent_config?: string;
   provider_config_env?: string;
+  worker_provider_mode?: 'live' | 'stub';
   transport?: string;
   takeover_stale_run?: boolean;
   batch?: boolean;

package/apps/control-plane/src/core/error-codes.ts

@@ -31,6 +31,10 @@ export const ERROR_CODES = {
   AGENT_PROVIDER_NOT_CONFIGURED: 'agent_provider_not_configured',
   UNSUPPORTED_AGENT_PROVIDER: 'unsupported_agent_provider',
   PROVIDER_AUTH_MISSING: 'provider_auth_missing',
+  PROVIDER_STUB_DISALLOWED: 'provider_stub_disallowed',
+  PROVIDER_RUNTIME_UNAVAILABLE: 'provider_runtime_unavailable',
+  PROVIDER_OUTPUT_INVALID: 'provider_output_invalid',
+  PROVIDER_NO_PROGRESS: 'provider_no_progress',
   UNAUTHENTICATED: 'unauthenticated',
   INVALID_ACTOR_CLAIM: 'invalid_actor_claim',
   OPERATION_ID_REQUIRED: 'operation_id_required',

package/apps/control-plane/src/core/kernel.ts

@@ -95,6 +95,9 @@ export interface AgentsRuntimeConfig {
   provider_config_env?: string;
   default_agent_config?: Record<string, unknown>;
   provider_configs?: Record<string, Record<string, unknown>>;
+  worker_provider_mode?: 'live' | 'stub' | string;
+  worker_response_timeout_ms?: number;
+  max_consecutive_no_progress_iterations?: number;
 }
 
 export interface AgentsConfigSnapshot {

package/apps/control-plane/src/index.ts

@@ -3,6 +3,20 @@ export type { AgentsConfigSnapshot } from './core/kernel.js';
 export { SupervisorRuntime } from './supervisor/runtime.js';
 export { resolveProviderSelection, NullWorkerProvider } from './providers/providers.js';
 export type { WorkerProvider, ProviderSelectionResolver } from './providers/providers.js';
+export {
+  DefaultWorkerProviderFactory,
+  resolveWorkerProviderMode,
+  resolveWorkerProviderRuntime,
+  resolveWorkerProviderPolicy,
+  resolveMalformedWorkerOutputAction,
+  resolveNoProgressAction,
+} from './providers/worker-provider-factory.js';
+export type {
+  WorkerProviderMode,
+  ProviderCommandContext,
+  WorkerProviderFactory,
+  CreateWorkerProviderInput,
+} from './providers/worker-provider-factory.js';
 export { createToolingRuntime, resolveToolClient } from './mcp/runtime-factory.js';
 export type { ToolingKernelPort, CreateToolingRuntimeOptions } from './mcp/runtime-factory.js';
 export { InProcessToolClient, McpToolClient, createOperationId } from './mcp/tool-client.js';

package/apps/control-plane/src/interfaces/cli/bootstrap.ts

@@ -26,7 +26,13 @@ import { AttachCommandHandler } from '../../cli/attach-command-handler.js';
 import { HelpCommandHandler } from '../../cli/help-command-handler.js';
 import { readEnvFileValues } from '../../cli/env-file.js';
 import { MultiProjectLoader } from '../../application/multi-project-loader.js';
-import { NullWorkerProvider, resolveProviderSelection } from '../../providers/providers.js';
+import { resolveProviderSelection } from '../../providers/providers.js';
+import {
+  DefaultWorkerProviderFactory,
+  resolveWorkerProviderMode,
+  resolveWorkerProviderPolicy,
+  resolveWorkerProviderRuntime,
+} from '../../providers/worker-provider-factory.js';
 import type { RuntimeContext } from '../../cli/types.js';
 import type { ProjectConfig } from '../../application/multi-project-loader.js';
 
@@ -315,7 +321,7 @@ export async function runCli(
     const tooling = await createToolingRuntime(repoRoot, kernel);
     const toolClient = resolveToolClient(transport, tooling);
 
-    let commandProvider: NullWorkerProvider | null = null;
+    let commandProvider = null;
     if (options.command === CliCommand.Send || options.command === CliCommand.Attach) {
       let selection;
       try {
@@ -332,7 +338,23 @@ export async function runCli(
           provider_config_ref: null,
         };
       }
-      commandProvider = new NullWorkerProvider(selection);
+      const workerProviderFactory = new DefaultWorkerProviderFactory();
+      const policySnapshot = kernel.getPolicySnapshot();
+      const executionPolicy =
+        policySnapshot.execution && typeof policySnapshot.execution === 'object'
+          ? (policySnapshot.execution as Record<string, unknown>)
+          : null;
+      commandProvider = workerProviderFactory.create({
+        selection,
+        mode: resolveWorkerProviderMode(
+          options.worker_provider_mode,
+          kernel.getAgentsConfig().runtime?.worker_provider_mode,
+          'stub',
+        ),
+        context: options.command === CliCommand.Send ? 'send' : 'attach',
+        policy: resolveWorkerProviderPolicy(executionPolicy),
+        runtime: resolveWorkerProviderRuntime(kernel.getAgentsConfig().runtime),
+      });
       kernel.setProvider(commandProvider);
     }
 

package/apps/control-plane/src/providers/api-worker-provider.ts

@@ -0,0 +1,115 @@
+import crypto from 'node:crypto';
+import { ERROR_CODES } from '../core/error-codes.js';
+import type { AppError, ProviderSelection, WorkerProvider, WorkerSession } from './providers.js';
+import type { ProviderOutputParser } from './output-parsers/types.js';
+
+interface ApiWorkerProviderOptions {
+  outputParser: ProviderOutputParser;
+  workerResponseTimeoutMs: number;
+}
+
+function providerError(code: string, message: string, details: Record<string, unknown>): AppError {
+  const error = new Error(message) as AppError;
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export class ApiWorkerProvider implements WorkerProvider {
+  readonly mode = 'live' as const;
+  readonly selection: ProviderSelection;
+
+  private readonly outputParser: ProviderOutputParser;
+  private readonly workerResponseTimeoutMs: number;
+
+  constructor(selection: ProviderSelection, options: ApiWorkerProviderOptions) {
+    this.selection = selection;
+    this.outputParser = options.outputParser;
+    this.workerResponseTimeoutMs = options.workerResponseTimeoutMs;
+  }
+
+  createSession(
+    role: string,
+    featureId: string,
+    systemPrompt: string | null,
+  ): Promise<WorkerSession> {
+    return Promise.resolve({
+      session_id: `${role}-${featureId}-${crypto.randomUUID()}`,
+      role,
+      feature_id: featureId,
+      system_prompt_loaded: Boolean(systemPrompt),
+    });
+  }
+
+  reattachSession(sessionId: string): Promise<WorkerSession | null> {
+    if (!sessionId || sessionId === 'unknown') {
+      return Promise.resolve(null);
+    }
+    return Promise.resolve({
+      session_id: sessionId,
+      role: 'orchestrator',
+      feature_id: 'global',
+      system_prompt_loaded: false,
+    });
+  }
+
+  closeSession(_sessionId: string): Promise<{ closed: true }> {
+    return Promise.resolve({ closed: true });
+  }
+
+  runWorker(input: {
+    role: string;
+    feature_id: string;
+    context_bundle?: Record<string, unknown>;
+    instructions?: string;
+    last_tool_results?: Array<Record<string, unknown>>;
+    runtime_selection?: {
+      provider: string;
+      model: string;
+      provider_config_ref: string | null;
+    };
+  }): Promise<Record<string, unknown>> {
+    // API-backed providers (gemini) require explicit adapter wiring. Until that is configured,
+    // fail deterministically instead of silently producing NOTE-only progress.
+    if (!this.selection.provider_config_ref) {
+      throw providerError(
+        ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
+        'API-backed provider credentials are not available',
+        {
+          provider: this.selection.provider,
+          reason: 'missing_provider_config_ref',
+        },
+      );
+    }
+
+    const mockResponse = isRecord(this.selection.agent_config)
+      ? this.selection.agent_config.mock_response
+      : null;
+    if (!isRecord(mockResponse)) {
+      throw providerError(
+        ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
+        'API-backed worker adapter is not configured for this provider',
+        {
+          provider: this.selection.provider,
+          reason: 'missing_api_adapter_configuration',
+          timeout_ms: this.workerResponseTimeoutMs,
+        },
+      );
+    }
+
+    const sessionId = `${input.role}-${input.feature_id}-api`;
+    return Promise.resolve(
+      this.outputParser.parse(JSON.stringify(mockResponse), {
+        sessionId,
+        role: input.role,
+        featureId: input.feature_id,
+        provider: this.selection.provider,
+        model: this.selection.model,
+      }),
+    );
+  }
+}