agentic-orchestrator 0.1.27 → 0.2.0

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

@@ -2,7 +2,13 @@ import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { ERROR_CODES } from '../core/error-codes.js';
 import { REGISTERED_PROVIDER_NAMES } from '../application/adapters/adapter-registry.js';
-import { PROVIDER_CLI_DEFAULTS, type ProviderCommandTemplate } from './provider-defaults.js';
+import {
+  PROVIDER_CLI_DEFAULTS,
+  generateProviderCliExtraArgs,
+  type ProviderCommandTemplate,
+} from './provider-defaults.js';
+import type { NormalizedUsageRecord } from '../application/usage-types.js';
+import { unavailableUsage } from '../application/usage-types.js';
 
 /**
  * @fileoverview Worker provider interfaces and credential resolution.
@@ -19,6 +25,7 @@ export interface ProviderSelection {
   provider_config_env: string | null;
   provider_config_ref: string | null;
   agent_config?: Record<string, unknown> | null;
+  cli_extra_args?: string[];
 }
 
 interface ResolveSelectionInput {
@@ -31,13 +38,23 @@ interface ResolveSelectionInput {
       provider_config_env?: string;
       default_agent_config?: unknown;
       provider_configs?: Record<string, unknown>;
+      provider_cli_config?: Record<string, unknown>;
+      role_provider_overrides?: Record<string, unknown>;
     };
   };
+  role?: string;
 }
 
 type ResolveSelectionRuntimeConfig = NonNullable<ResolveSelectionInput['agentsConfig']>['runtime'];
 const ENV_VAR_NAME_PATTERN = /^[A-Z_][A-Z0-9_]*$/;
 
+interface RoleProviderOverride {
+  provider?: string;
+  model?: string;
+  provider_config_env?: string;
+  agent_config?: Record<string, unknown>;
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -93,6 +110,20 @@ function resolveConfiguredAgentConfig(
   return null;
 }
 
+function resolveRoleOverride(
+  role: string | undefined,
+  runtime: ResolveSelectionRuntimeConfig,
+): RoleProviderOverride | null {
+  if (!role || !runtime?.role_provider_overrides) {
+    return null;
+  }
+  const override = runtime.role_provider_overrides[role];
+  if (!isPlainObject(override)) {
+    return null;
+  }
+  return override as RoleProviderOverride;
+}
+
 function readNonEmptyEnvValue(env: NodeJS.ProcessEnv, key: string | null): string | null {
   if (!key) {
     return null;
@@ -152,19 +183,37 @@ export const LOCAL_CLI_PROVIDERS: Set<string> = new Set([
   'copilot',
   'custom',
 ]);
-export const CREDENTIAL_REQUIRED_PROVIDERS: Set<string> = new Set(['gemini']);
+export const CREDENTIAL_REQUIRED_PROVIDERS: Set<string> = new Set([]);
 export type ProviderSelectionResolver = (input: ResolveSelectionInput) => ProviderSelection;
 
-export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env, agentsConfig }) => {
+export const resolveProviderSelection: ProviderSelectionResolver = ({
+  cli,
+  env,
+  agentsConfig,
+  role,
+}) => {
+  const runtime = agentsConfig?.runtime;
+  const roleOverride = resolveRoleOverride(role, runtime);
+  const roleProvider = roleOverride?.provider;
+  const roleModel = roleOverride?.model;
+  const roleProviderConfigEnv = roleOverride?.provider_config_env;
+  const roleAgentConfig = isPlainObject(roleOverride?.agent_config)
+    ? roleOverride?.agent_config
+    : null;
+
   const provider =
-    cli.agent_provider || env.AOP_AGENT_PROVIDER || agentsConfig?.runtime?.default_provider || null;
+    cli.agent_provider ||
+    env.AOP_AGENT_PROVIDER ||
+    roleProvider ||
+    runtime?.default_provider ||
+    null;
 
   const model =
-    cli.agent_model || env.AOP_AGENT_MODEL || agentsConfig?.runtime?.default_model || null;
+    cli.agent_model || env.AOP_AGENT_MODEL || roleModel || runtime?.default_model || null;
 
   const { providerConfigEnv, providerConfigRef } = resolveProviderCredentialReference(
     cli.provider_config_env,
-    agentsConfig?.runtime?.provider_config_env,
+    roleProviderConfigEnv ?? runtime?.provider_config_env,
     env,
   );
 
@@ -198,7 +247,12 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
         ? parseAgentConfigJson(env.AOP_AGENT_CONFIG, 'env')
         : typeof env.AOP_AGENT_CONFIG_JSON === 'string' && env.AOP_AGENT_CONFIG_JSON.length > 0
           ? parseAgentConfigJson(env.AOP_AGENT_CONFIG_JSON, 'env')
-          : resolveConfiguredAgentConfig(provider, agentsConfig?.runtime);
+          : (roleAgentConfig ?? resolveConfiguredAgentConfig(provider, runtime));
+
+  const providerCliConfig = isPlainObject(runtime?.provider_cli_config)
+    ? runtime.provider_cli_config
+    : null;
+  const cliExtraArgs = generateProviderCliExtraArgs(provider, providerCliConfig);
 
   return {
     provider,
@@ -206,9 +260,83 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
     provider_config_env: providerConfigEnv,
     provider_config_ref: providerConfigRef,
     agent_config: agentConfig,
+    ...(cliExtraArgs.length > 0 ? { cli_extra_args: cliExtraArgs } : {}),
   };
 };
 
+export function resolveProviderSelectionsByRole(
+  input: ResolveSelectionInput,
+): Record<string, ProviderSelection> {
+  const roles = ['planner', 'builder', 'qa', 'reconciler'] as const;
+  const selections: Record<string, ProviderSelection> = {};
+  for (const role of roles) {
+    selections[role] = resolveProviderSelection({ ...input, role });
+  }
+  return selections;
+}
+
+export interface RoleProviderCompatibilityResult {
+  valid: boolean;
+  errors: Array<{ role: string; code: string; message: string; details: Record<string, unknown> }>;
+}
+
+/**
+ * Validates that each role's resolved provider is supported, has credentials
+ * where required, and is compatible with the requested execution mode.
+ *
+ * This replaces the previous same-provider equality check, allowing cross-provider
+ * role overrides (e.g. planner on claude, builder on codex).
+ *
+ * @param roleSelections - per-role provider selections
+ * @param executionMode - requested execution mode (deterministic or interactive)
+ * @returns validation result with per-role errors
+ */
+export function validateRoleProviderCompatibility(
+  roleSelections: Record<string, ProviderSelection>,
+  executionMode?: ExecutionMode | null,
+): RoleProviderCompatibilityResult {
+  const errors: RoleProviderCompatibilityResult['errors'] = [];
+
+  for (const [role, selection] of Object.entries(roleSelections)) {
+    if (!SUPPORTED_PROVIDERS.has(selection.provider)) {
+      errors.push({
+        role,
+        code: ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+        message: `Provider '${selection.provider}' is not supported`,
+        details: { provider: selection.provider },
+      });
+      continue;
+    }
+
+    if (CREDENTIAL_REQUIRED_PROVIDERS.has(selection.provider) && !selection.provider_config_ref) {
+      errors.push({
+        role,
+        code: ERROR_CODES.PROVIDER_AUTH_MISSING,
+        message: `Provider '${selection.provider}' requires credentials for role '${role}'`,
+        details: {
+          provider: selection.provider,
+          provider_config_env: selection.provider_config_env,
+        },
+      });
+      continue;
+    }
+
+    if (executionMode === 'interactive' && !LOCAL_CLI_PROVIDERS.has(selection.provider)) {
+      errors.push({
+        role,
+        code: ERROR_CODES.INVALID_CLI_ARGS,
+        message: `Provider '${selection.provider}' does not support interactive execution mode for role '${role}'`,
+        details: {
+          provider: selection.provider,
+          execution_mode: executionMode,
+        },
+      });
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}
+
 /**
  * Worker session metadata.
  *
@@ -217,7 +345,7 @@ export const resolveProviderSelection: ProviderSelectionResolver = ({ cli, env,
 export interface WorkerSession {
   /** Unique session identifier */
   session_id: string;
-  /** Agent role (orchestrator, planner, builder, qa) */
+  /** Agent role (orchestrator, planner, builder, qa, reconciler) */
   role: string;
   /** Feature identifier (empty for orchestrator) */
   feature_id: string;
@@ -238,19 +366,33 @@ export interface WorkerProviderCapabilities {
 export interface WorkerRunInput {
   role: string;
   feature_id: string;
+  planner_phase?: 'intake' | 'planning';
   context_bundle?: Record<string, unknown>;
   instructions?: string;
   last_tool_results?: Array<Record<string, unknown>>;
   runtime_selection?: {
     provider: string;
     model: string;
+    provider_config_env?: string | null;
     provider_config_ref: string | null;
+    agent_config?: Record<string, unknown> | null;
   };
   execution_mode?: ExecutionMode;
   working_directory?: string;
   pause_resume_protocol?: 'signal' | 'message' | 'none';
 }
 
+/**
+ * Worker run output with optional token usage telemetry.
+ *
+ * Extends Record<string, unknown> for backward compatibility with existing
+ * output parsing. The `usage` field is optional; providers that do not
+ * expose token data omit it or return status: 'unavailable'.
+ */
+export interface WorkerRunOutput extends Record<string, unknown> {
+  usage?: NormalizedUsageRecord;
+}
+
 /**
  * Worker provider interface for agent session management.
  *
@@ -317,9 +459,9 @@ export interface WorkerProvider {
    * Executes worker with context and instructions.
    *
    * @param input - execution input with role, feature, context, instructions
-   * @returns Worker output with tool calls and text
+   * @returns Worker output with tool calls, text, and optional usage telemetry
    */
-  runWorker(input: WorkerRunInput): Promise<Record<string, unknown>>;
+  runWorker(input: WorkerRunInput): Promise<WorkerRunOutput>;
 
   /**
    * Sends a message to an active session (optional).
@@ -383,6 +525,12 @@ export interface ProviderCommandResult {
   stderr?: string;
 }
 
+export interface ProviderOutputChunk {
+  stream: 'stdout' | 'stderr';
+  text: string;
+  ts: number;
+}
+
 export interface ProviderCommandRunnerOptions {
   interactive?: boolean;
   stdin?: string;
@@ -390,6 +538,7 @@ export interface ProviderCommandRunnerOptions {
   cwd?: string;
   timeoutMs?: number;
   onLifecycleEvent?: (event: WorkerLifecycleEvent) => void;
+  onOutputChunk?: (chunk: ProviderOutputChunk) => void;
   registerKill?: (kill: (signal: 'SIGTERM' | 'SIGKILL') => void) => void;
 }
 
@@ -444,6 +593,7 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
       options.registerKill?.(killProcess);
 
       let spawnErrorCode: number | string | undefined;
+      let stdinErrorCode: number | string | undefined;
       let stdout = '';
       let stderr = '';
       child.on('error', (error: NodeJS.ErrnoException) => {
@@ -460,6 +610,15 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
         child.stdout.on('data', (chunk: Buffer | string) => {
           const text = chunk.toString();
           stdout += text;
+          try {
+            options.onOutputChunk?.({
+              stream: 'stdout',
+              text,
+              ts: Date.now(),
+            });
+          } catch {
+            // Output chunk callbacks must never break command execution.
+          }
           emitLifecycleEvent({
             type: 'activity',
             ts: Date.now(),
@@ -471,6 +630,15 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
         child.stderr.on('data', (chunk: Buffer | string) => {
           const text = chunk.toString();
           stderr += text;
+          try {
+            options.onOutputChunk?.({
+              stream: 'stderr',
+              text,
+              ts: Date.now(),
+            });
+          } catch {
+            // Output chunk callbacks must never break command execution.
+          }
           emitLifecycleEvent({
             type: 'activity',
             ts: Date.now(),
@@ -479,10 +647,22 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
         });
       }
 
-      if (!options.interactive && typeof options.stdin === 'string' && child.stdin) {
+      if (!options.interactive && child.stdin) {
+        child.stdin.on('error', (error: NodeJS.ErrnoException) => {
+          stdinErrorCode = error.code ?? 'EPIPE';
+        });
+      }
+
+      if (
+        !options.interactive &&
+        typeof options.stdin === 'string' &&
+        child.stdin &&
+        child.stdin.writable &&
+        !child.stdin.destroyed
+      ) {
         child.stdin.write(options.stdin);
       }
-      if (!options.interactive && child.stdin) {
+      if (!options.interactive && child.stdin && !child.stdin.destroyed) {
         child.stdin.end();
       }
 
@@ -503,10 +683,14 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
         if (timeoutHandle) {
           clearTimeout(timeoutHandle);
         }
+        const errorCode = spawnErrorCode ?? stdinErrorCode;
+        const baseExitCode = code ?? (spawnErrorCode === 'ENOENT' ? 127 : 1);
+        const exitCode =
+          baseExitCode === 0 && errorCode ? (errorCode === 'ENOENT' ? 127 : 1) : baseExitCode;
         resolve({
-          exitCode: code ?? (spawnErrorCode === 'ENOENT' ? 127 : 1),
+          exitCode,
           signal,
-          errorCode: spawnErrorCode,
+          errorCode,
           timedOut: killedByTimeout,
           stdout,
           stderr,
@@ -565,9 +749,27 @@ function resolveTemplateFromAgentConfig(
 
 function resolveProviderCommands(selection: ProviderSelection): ProviderCliCommands {
   const defaults = PROVIDER_CLI_DEFAULTS[selection.provider] ?? {};
+  const attachTemplate = resolveTemplateFromAgentConfig(
+    selection.agent_config,
+    'attach',
+    defaults.attach,
+  );
+  const sendTemplate = resolveTemplateFromAgentConfig(
+    selection.agent_config,
+    'send',
+    defaults.send,
+  );
+
+  const extra = selection.cli_extra_args;
   return {
-    attach: resolveTemplateFromAgentConfig(selection.agent_config, 'attach', defaults.attach),
-    send: resolveTemplateFromAgentConfig(selection.agent_config, 'send', defaults.send),
+    attach:
+      attachTemplate && extra?.length
+        ? { command: attachTemplate.command, args: [...attachTemplate.args, ...extra] }
+        : attachTemplate,
+    send:
+      sendTemplate && extra?.length
+        ? { command: sendTemplate.command, args: [...sendTemplate.args, ...extra] }
+        : sendTemplate,
   };
 }
 
@@ -656,11 +858,8 @@ export class NullWorkerProvider implements WorkerProvider {
     return Promise.resolve({ closed: true });
   }
 
-  runWorker({
-    role,
-    feature_id,
-    context_bundle,
-  }: WorkerRunInput): Promise<Record<string, unknown>> {
+  runWorker({ role, feature_id, context_bundle }: WorkerRunInput): Promise<WorkerRunOutput> {
+    const usage = unavailableUsage(this.selection.provider, this.selection.model, role);
     if (role === 'planner') {
       const state = context_bundle?.state;
       const frontMatter =
@@ -675,12 +874,14 @@ export class NullWorkerProvider implements WorkerProvider {
         context_snapshot: {
           status: typeof status === 'string' ? status : 'unknown',
         },
+        usage,
       });
     }
 
     return Promise.resolve({
       type: 'NOTE',
       content: `${role} session active for ${feature_id}.`,
+      usage,
     });
   }
 
@@ -715,6 +916,9 @@ export class NullWorkerProvider implements WorkerProvider {
       exit_code: result.exitCode,
       signal: result.signal,
       error_code: result.errorCode,
+      timed_out: result.timedOut ?? false,
+      stdout: result.stdout,
+      stderr: result.stderr,
     };
     if (result.exitCode === 127 || result.errorCode === 'ENOENT') {
       throw commandFailureError(

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

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import { ERROR_CODES } from '../core/error-codes.js';
 import { ApiWorkerProvider } from './api-worker-provider.js';
 import { CliWorkerProvider } from './cli-worker-provider.js';
@@ -58,6 +59,7 @@ export interface CreateWorkerProviderInput {
   runtime: WorkerProviderFactoryRuntime;
   repoRoot?: string;
   commandRunner?: ProviderCommandRunner;
+  overlayDir?: string;
 }
 
 export interface WorkerProviderFactory {
@@ -238,10 +240,29 @@ export function resolvePlanConformanceStallAction(
   return input?.plan_conformance_stall_action === 'fail_run' ? 'fail_run' : 'block_feature';
 }
 
+export function resolvePromptOverlayDir(
+  repoRoot: string,
+  promptOverlayDirConfig: string | undefined,
+): string {
+  return path.join(
+    repoRoot,
+    promptOverlayDirConfig ?? 'config/agentic/orchestrator/prompts/overrides',
+  );
+}
+
 export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
   create(input: CreateWorkerProviderInput): WorkerProvider {
-    const { selection, mode, context, policy, runtime, observability, repoRoot, commandRunner } =
-      input;
+    const {
+      selection,
+      mode,
+      context,
+      policy,
+      runtime,
+      observability,
+      repoRoot,
+      commandRunner,
+      overlayDir,
+    } = input;
     const resolvedObservability = observability ?? {
       raw_agent_logs_enabled: false,
       raw_agent_logs_retention_days: 60,
@@ -293,6 +314,7 @@ export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
         workerIdleTimeoutMs: runtime.worker_idle_timeout_ms,
         workerWatchdogPollIntervalMs: runtime.worker_watchdog_poll_interval_ms,
         workerKillGracePeriodMs: runtime.worker_kill_grace_period_ms,
+        overlayDir,
       });
     }
 
@@ -308,6 +330,7 @@ export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
         workerIdleTimeoutMs: runtime.worker_idle_timeout_ms,
         workerWatchdogPollIntervalMs: runtime.worker_watchdog_poll_interval_ms,
         workerKillGracePeriodMs: runtime.worker_kill_grace_period_ms,
+        overlayDir,
       });
     }
 
@@ -327,6 +350,7 @@ export class DefaultWorkerProviderFactory implements WorkerProviderFactory {
         workerIdleTimeoutMs: runtime.worker_idle_timeout_ms,
         workerWatchdogPollIntervalMs: runtime.worker_watchdog_poll_interval_ms,
         workerKillGracePeriodMs: runtime.worker_kill_grace_period_ms,
+        overlayDir,
       });
     }
 

package/apps/control-plane/src/supervisor/artifact-stager.ts

@@ -0,0 +1,52 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+
+const REQUIRED_ARTIFACTS = ['spec.md', 'plan.md', 'plan.json'] as const;
+const OPTIONAL_ARTIFACTS = ['qa_test_index.json'] as const;
+
+const CONTEXT_README = `# Staged Artifacts
+
+These files are read-only copies staged by the orchestrator for the builder agent.
+
+| File | Description |
+|---|---|
+| spec.md | Original feature specification — read this to understand the "why" |
+| plan.md | Human-readable implementation plan |
+| plan.json | Structured plan with tasks and acceptance criteria |
+| qa_test_index.json | Test expectations (if available) |
+
+Do not edit these files. They are copied from the canonical feature directory.
+`;
+
+export class ArtifactStager {
+  private readonly repoRoot: string;
+
+  constructor(repoRoot: string) {
+    this.repoRoot = repoRoot;
+  }
+
+  async stage(featureId: string, worktreePath: string): Promise<void> {
+    const featureDir = path.join(this.repoRoot, '.aop', 'features', featureId);
+    const contextDir = path.join(worktreePath, '.aop', 'context');
+
+    await fs.mkdir(contextDir, { recursive: true });
+
+    for (const artifact of REQUIRED_ARTIFACTS) {
+      const src = path.join(featureDir, artifact);
+      const dst = path.join(contextDir, artifact);
+      await fs.copyFile(src, dst);
+    }
+
+    for (const artifact of OPTIONAL_ARTIFACTS) {
+      const src = path.join(featureDir, artifact);
+      const dst = path.join(contextDir, artifact);
+      try {
+        await fs.copyFile(src, dst);
+      } catch {
+        // Optional — skip if not present
+      }
+    }
+
+    await fs.writeFile(path.join(contextDir, 'README.md'), CONTEXT_README);
+  }
+}