agentic-orchestrator 0.1.13 → 0.1.15

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

@@ -0,0 +1,385 @@
+import crypto from 'node:crypto';
+import { ERROR_CODES } from '../core/error-codes.js';
+import {
+  NodeProviderCommandRunner,
+  type AppError,
+  type ProviderCommandResult,
+  type ProviderCommandRunner,
+  type ProviderSelection,
+  type WorkerProvider,
+  type WorkerSession,
+} from './providers.js';
+import type { ProviderOutputParser } from './output-parsers/types.js';
+
+interface ProviderCommandTemplate {
+  command: string;
+  args: string[];
+}
+
+interface CliWorkerProviderOptions {
+  outputParser: ProviderOutputParser;
+  commandRunner?: ProviderCommandRunner;
+  workerResponseTimeoutMs: number;
+}
+
+interface CommandTemplateValues {
+  sessionId: string;
+  prompt: string;
+  featureId: string;
+  role: string;
+  message?: string;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readStringArray(value: unknown): string[] | null {
+  if (!Array.isArray(value)) {
+    return null;
+  }
+  const strings = value.filter((item): item is string => typeof item === 'string');
+  return strings.length === value.length ? strings : null;
+}
+
+function asNonEmptyString(value: unknown): string | null {
+  if (typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function templateFromConfig(
+  config: Record<string, unknown> | null | undefined,
+  kind: 'run' | 'attach' | 'send',
+  fallback: ProviderCommandTemplate | undefined,
+): ProviderCommandTemplate | undefined {
+  const nested = isRecord(config?.[kind]) ? config?.[kind] : null;
+  const nestedCommand = asNonEmptyString(nested?.command);
+  const nestedArgs = readStringArray(nested?.args);
+
+  const explicitCommand = asNonEmptyString(config?.[`${kind}_command`]);
+  const explicitArgs = readStringArray(config?.[`${kind}_args`]);
+
+  const command = nestedCommand ?? explicitCommand ?? fallback?.command;
+  const args = nestedArgs ?? explicitArgs ?? fallback?.args;
+  if (!command || !args) {
+    return undefined;
+  }
+
+  return { command, args };
+}
+
+function resolveRunTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+  const defaults: Partial<Record<string, ProviderCommandTemplate>> = {
+    codex: {
+      command: 'codex',
+      args: ['chat', '--session', '{session_id}', '--message', '{prompt}'],
+    },
+    claude: {
+      command: 'claude-code',
+      args: ['chat', '--session', '{session_id}', '--message', '{prompt}'],
+    },
+    'kiro-cli': {
+      command: 'kiro-cli',
+      args: ['chat', '--session', '{session_id}', '--message', '{prompt}'],
+    },
+    copilot: {
+      command: 'copilot',
+      args: ['chat', '--session', '{session_id}', '--message', '{prompt}'],
+    },
+  };
+
+  const topLevelCommand = asNonEmptyString(selection.agent_config?.command);
+  const topLevelArgs = readStringArray(selection.agent_config?.args);
+  const topLevelTemplate =
+    topLevelCommand && topLevelArgs ? { command: topLevelCommand, args: topLevelArgs } : undefined;
+
+  return templateFromConfig(
+    selection.agent_config,
+    'run',
+    topLevelTemplate ?? defaults[selection.provider],
+  );
+}
+
+function resolveAttachTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+  const defaults: Partial<Record<string, ProviderCommandTemplate>> = {
+    codex: {
+      command: 'codex',
+      args: ['chat', '--session', '{session_id}'],
+    },
+    claude: {
+      command: 'claude-code',
+      args: ['chat', '--session', '{session_id}'],
+    },
+  };
+  return templateFromConfig(selection.agent_config, 'attach', defaults[selection.provider]);
+}
+
+function resolveSendTemplate(selection: ProviderSelection): ProviderCommandTemplate | undefined {
+  const defaults: Partial<Record<string, ProviderCommandTemplate>> = {
+    codex: {
+      command: 'codex',
+      args: ['chat', '--session', '{session_id}', '--message', '{message}'],
+    },
+    claude: {
+      command: 'claude-code',
+      args: ['chat', '--session', '{session_id}', '--message', '{message}'],
+    },
+  };
+  return templateFromConfig(selection.agent_config, 'send', defaults[selection.provider]);
+}
+
+function applyTemplateArgs(args: string[], values: CommandTemplateValues): string[] {
+  return args.map((arg) => {
+    if (arg === '{session_id}') {
+      return values.sessionId;
+    }
+    if (arg === '{prompt}') {
+      return values.prompt;
+    }
+    if (arg === '{feature_id}') {
+      return values.featureId;
+    }
+    if (arg === '{role}') {
+      return values.role;
+    }
+    if (arg === '{message}') {
+      return values.message ?? '';
+    }
+    return arg;
+  });
+}
+
+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 buildRunCommandEnv(selection: ProviderSelection): NodeJS.ProcessEnv {
+  const env: NodeJS.ProcessEnv = { ...process.env };
+  if (selection.provider_config_env && selection.provider_config_ref) {
+    env[selection.provider_config_env] = selection.provider_config_ref;
+  }
+  return env;
+}
+
+export class CliWorkerProvider implements WorkerProvider {
+  readonly mode = 'live' as const;
+  readonly selection: ProviderSelection;
+  sendMessage?: (sessionId: string, message: string) => Promise<void>;
+  attachToSession?: (sessionId: string) => Promise<void>;
+  getSessionInfo?: (sessionId: string) => Promise<{ active: boolean; provider: string }>;
+
+  private readonly outputParser: ProviderOutputParser;
+  private readonly commandRunner: ProviderCommandRunner;
+  private readonly workerResponseTimeoutMs: number;
+  private readonly runTemplate: ProviderCommandTemplate | undefined;
+  private readonly attachTemplate: ProviderCommandTemplate | undefined;
+  private readonly sendTemplate: ProviderCommandTemplate | undefined;
+  private readonly sessionsByRoleFeature = new Map<string, string>();
+
+  constructor(selection: ProviderSelection, options: CliWorkerProviderOptions) {
+    this.selection = selection;
+    this.outputParser = options.outputParser;
+    this.commandRunner = options.commandRunner ?? new NodeProviderCommandRunner();
+    this.workerResponseTimeoutMs = options.workerResponseTimeoutMs;
+    this.runTemplate = resolveRunTemplate(selection);
+    this.attachTemplate = resolveAttachTemplate(selection);
+    this.sendTemplate = resolveSendTemplate(selection);
+
+    if (this.attachTemplate) {
+      this.attachToSession = async (sessionId: string) => {
+        await this.executeControlCommand('attach', sessionId);
+      };
+      this.getSessionInfo = (sessionId: string) =>
+        Promise.resolve({
+          active: Boolean(sessionId) && sessionId !== 'unknown' && sessionId !== 'unassigned',
+          provider: this.selection.provider,
+        });
+    }
+
+    if (this.sendTemplate) {
+      this.sendMessage = async (sessionId: string, message: string) => {
+        await this.executeControlCommand('send', sessionId, message);
+      };
+    }
+  }
+
+  createSession(
+    role: string,
+    featureId: string,
+    systemPrompt: string | null,
+  ): Promise<WorkerSession> {
+    const sessionId = `${role}-${featureId}-${crypto.randomUUID()}`;
+    this.sessionsByRoleFeature.set(this.sessionKey(role, featureId), sessionId);
+    return Promise.resolve({
+      session_id: sessionId,
+      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 }> {
+    for (const [key, activeSessionId] of this.sessionsByRoleFeature.entries()) {
+      if (activeSessionId === sessionId) {
+        this.sessionsByRoleFeature.delete(key);
+      }
+    }
+    return Promise.resolve({ closed: true });
+  }
+
+  async 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>> {
+    if (!this.runTemplate) {
+      throw providerError(
+        ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
+        'Live worker provider is missing run command configuration',
+        {
+          provider: this.selection.provider,
+          reason: 'missing_run_command_template',
+        },
+      );
+    }
+
+    const sessionId =
+      this.sessionsByRoleFeature.get(this.sessionKey(input.role, input.feature_id)) ??
+      `${input.role}-${input.feature_id}-unassigned`;
+
+    const promptPayload = {
+      role: input.role,
+      feature_id: input.feature_id,
+      context_bundle: input.context_bundle ?? {},
+      instructions: input.instructions ?? '',
+      last_tool_results: input.last_tool_results ?? [],
+      runtime_selection: input.runtime_selection ?? null,
+      session_id: sessionId,
+    };
+    const prompt = JSON.stringify(promptPayload);
+
+    const args = applyTemplateArgs(this.runTemplate.args, {
+      sessionId,
+      prompt,
+      featureId: input.feature_id,
+      role: input.role,
+    });
+
+    const runResult = await this.commandRunner.run(this.runTemplate.command, args, {
+      stdin: prompt,
+      timeoutMs: this.workerResponseTimeoutMs,
+      env: buildRunCommandEnv(this.selection),
+    });
+
+    this.ensureRunSucceeded(runResult, this.runTemplate.command, args);
+
+    return this.outputParser.parse(runResult.stdout ?? '', {
+      sessionId,
+      role: input.role,
+      featureId: input.feature_id,
+      provider: this.selection.provider,
+      model: this.selection.model,
+    });
+  }
+
+  private sessionKey(role: string, featureId: string): string {
+    return `${role}::${featureId}`;
+  }
+
+  private ensureRunSucceeded(result: ProviderCommandResult, command: string, args: string[]): void {
+    if (result.exitCode === 0) {
+      return;
+    }
+
+    throw providerError(
+      ERROR_CODES.PROVIDER_RUNTIME_UNAVAILABLE,
+      'Live worker provider command failed',
+      {
+        provider: this.selection.provider,
+        command,
+        args,
+        exit_code: result.exitCode,
+        signal: result.signal,
+        error_code: result.errorCode,
+        stderr: result.stderr,
+      },
+    );
+  }
+
+  private async executeControlCommand(
+    kind: 'attach' | 'send',
+    sessionId: string,
+    message?: string,
+  ): Promise<void> {
+    const template = kind === 'attach' ? this.attachTemplate : this.sendTemplate;
+    if (!template) {
+      throw providerError(
+        ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER,
+        `Provider does not support ${kind}`,
+        {
+          provider: this.selection.provider,
+          kind,
+        },
+      );
+    }
+
+    const args = applyTemplateArgs(template.args, {
+      sessionId,
+      prompt: '',
+      featureId: 'global',
+      role: 'orchestrator',
+      message,
+    });
+
+    const result = await this.commandRunner.run(template.command, args, {
+      interactive: kind === 'attach',
+      timeoutMs: kind === 'send' ? 15_000 : undefined,
+      env: buildRunCommandEnv(this.selection),
+    });
+
+    if (result.exitCode === 0) {
+      return;
+    }
+
+    throw providerError(
+      result.exitCode === 127 || result.errorCode === 'ENOENT'
+        ? ERROR_CODES.UNSUPPORTED_AGENT_PROVIDER
+        : ERROR_CODES.INTERNAL_ERROR,
+      `Provider ${kind} command failed`,
+      {
+        provider: this.selection.provider,
+        kind,
+        command: template.command,
+        args,
+        exit_code: result.exitCode,
+        signal: result.signal,
+        error_code: result.errorCode,
+      },
+    );
+  }
+}

package/apps/control-plane/src/providers/output-parsers/generic-output-parser.ts

@@ -0,0 +1,100 @@
+import { ERROR_CODES } from '../../core/error-codes.js';
+import type {
+  ProviderOutputParser,
+  ProviderOutputParserContext,
+  WorkerOutputEnvelope,
+} from './types.js';
+
+interface ParserError extends Error {
+  code?: string;
+  details?: Record<string, unknown>;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function asOutputArray(value: unknown): Array<Record<string, unknown>> {
+  if (Array.isArray(value)) {
+    return value.filter(isRecord);
+  }
+  if (isRecord(value)) {
+    return [value];
+  }
+  return [];
+}
+
+function parserError(message: string, details: Record<string, unknown>): ParserError {
+  const error = new Error(message) as ParserError;
+  error.code = ERROR_CODES.PROVIDER_OUTPUT_INVALID;
+  error.details = details;
+  return error;
+}
+
+function parseJsonOutput(raw: string): unknown {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw parserError('Provider output must be valid JSON', {
+      reason: 'invalid_json',
+      raw_preview: raw.slice(0, 512),
+    });
+  }
+}
+
+export class GenericCliOutputParser implements ProviderOutputParser {
+  parse(raw: string, context: ProviderOutputParserContext): WorkerOutputEnvelope {
+    const trimmed = raw.trim();
+    if (trimmed.length === 0) {
+      throw parserError('Provider output was empty', {
+        reason: 'empty_output',
+        role: context.role,
+        feature_id: context.featureId,
+      });
+    }
+
+    const parsed = parseJsonOutput(trimmed);
+    const parsedRecord = isRecord(parsed) ? parsed : null;
+
+    const outputs =
+      parsedRecord && Array.isArray(parsedRecord.outputs)
+        ? asOutputArray(parsedRecord.outputs)
+        : parsedRecord && typeof parsedRecord.type === 'string'
+          ? [parsedRecord]
+          : [];
+
+    if (!parsedRecord || outputs.length === 0) {
+      throw parserError('Provider output did not include any parseable outputs', {
+        reason: 'missing_outputs',
+        role: context.role,
+        feature_id: context.featureId,
+      });
+    }
+
+    return {
+      session_id:
+        typeof parsedRecord.session_id === 'string' && parsedRecord.session_id.length > 0
+          ? parsedRecord.session_id
+          : context.sessionId,
+      role:
+        typeof parsedRecord.role === 'string' && parsedRecord.role.length > 0
+          ? parsedRecord.role
+          : context.role,
+      feature_id:
+        typeof parsedRecord.feature_id === 'string' && parsedRecord.feature_id.length > 0
+          ? parsedRecord.feature_id
+          : context.featureId,
+      outputs,
+      provider_meta: {
+        provider: context.provider,
+        model: context.model,
+      },
+    };
+  }
+}
+
+export class CodexOutputParser extends GenericCliOutputParser {}
+
+export class ClaudeOutputParser extends GenericCliOutputParser {}
+
+export class GeminiOutputParser extends GenericCliOutputParser {}

package/apps/control-plane/src/providers/output-parsers/index.ts

@@ -0,0 +1,11 @@
+export {
+  GenericCliOutputParser,
+  CodexOutputParser,
+  ClaudeOutputParser,
+  GeminiOutputParser,
+} from './generic-output-parser.js';
+export type {
+  ProviderOutputParser,
+  ProviderOutputParserContext,
+  WorkerOutputEnvelope,
+} from './types.js';

package/apps/control-plane/src/providers/output-parsers/types.ts

@@ -0,0 +1,23 @@
+export interface ProviderOutputParserContext {
+  sessionId: string;
+  role: string;
+  featureId: string;
+  provider: string;
+  model: string;
+}
+
+export interface WorkerOutputEnvelope {
+  [key: string]: unknown;
+  session_id: string;
+  role: string;
+  feature_id: string;
+  outputs: Array<Record<string, unknown>>;
+  provider_meta: {
+    provider: string;
+    model: string;
+  };
+}
+
+export interface ProviderOutputParser {
+  parse(raw: string, context: ProviderOutputParserContext): WorkerOutputEnvelope;
+}

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

@@ -212,6 +212,7 @@ export interface WorkerSession {
 }
 
 export interface WorkerProvider {
+  mode: 'live' | 'stub';
   selection: ProviderSelection;
   createSession(
     role: string,
@@ -241,6 +242,8 @@ export interface ProviderCommandResult {
   exitCode: number;
   signal: NodeJS.Signals | null;
   errorCode?: number | string;
+  stdout?: string;
+  stderr?: string;
 }
 
 export interface ProviderCommandRunnerOptions {
@@ -281,10 +284,23 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
       }
 
       let spawnErrorCode: number | string | undefined;
+      let stdout = '';
+      let stderr = '';
       child.on('error', (error: NodeJS.ErrnoException) => {
         spawnErrorCode = error.code;
       });
 
+      if (!options.interactive && child.stdout) {
+        child.stdout.on('data', (chunk: Buffer | string) => {
+          stdout += chunk.toString();
+        });
+      }
+      if (!options.interactive && child.stderr) {
+        child.stderr.on('data', (chunk: Buffer | string) => {
+          stderr += chunk.toString();
+        });
+      }
+
       if (!options.interactive && typeof options.stdin === 'string' && child.stdin) {
         child.stdin.write(options.stdin);
       }
@@ -307,6 +323,8 @@ export class NodeProviderCommandRunner implements ProviderCommandRunner {
           exitCode: code ?? (spawnErrorCode === 'ENOENT' ? 127 : 1),
           signal,
           errorCode: spawnErrorCode,
+          stdout,
+          stderr,
         });
       });
     });
@@ -422,6 +440,7 @@ function commandFailureError(
 }
 
 export class NullWorkerProvider implements WorkerProvider {
+  readonly mode = 'stub' as const;
   selection: ProviderSelection;
   sendMessage?: (sessionId: string, message: string) => Promise<void>;
   attachToSession?: (sessionId: string) => Promise<void>;