@orchestrator-claude/cli 3.25.2 → 3.26.0

package/templates/base/scripts/lib/mailbox/types.ts

@@ -0,0 +1,175 @@
+/**
+ * types.ts — Mailbox protocol types and Zod schemas (RFC-025 M1)
+ *
+ * Tasks:
+ *   1.1 — MessageEnvelope + Zod schema
+ *   1.2 — MailboxAddress / Role value types
+ *   1.3 — Body variant types + Zod sub-schemas
+ */
+
+import { z } from 'zod';
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.2 — Role value type
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * Role identifies the agent type in the mailbox system.
+ * Each role may have multiple instances (differentiated by index in MailboxAddress).
+ */
+export const RoleSchema = z.enum([
+  'orchestrator',
+  'implementer',
+  'planner',
+  'reviewer',
+  'debug-sidecar',
+  'test-sidecar',
+  'doc-sidecar',
+]);
+export type Role = z.infer<typeof RoleSchema>;
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.2 — MailboxAddress value type
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * MailboxAddress uniquely identifies an agent mailbox.
+ * Multiple instances of the same role are distinguished by index.
+ *
+ * @example { role: 'implementer', index: 0 } → "implementer-0"
+ */
+export const MailboxAddressSchema = z.object({
+  role: RoleSchema,
+  index: z.number().int().nonnegative(),
+});
+export type MailboxAddress = z.infer<typeof MailboxAddressSchema>;
+
+/**
+ * Converts a MailboxAddress to its canonical directory-safe string form.
+ * Example: { role: 'implementer', index: 0 } → "implementer-0"
+ */
+export function addressToString(address: MailboxAddress): string {
+  return `${address.role}-${address.index}`;
+}
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.3 — Body variant schemas
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * TaskAssignmentBody — orchestrator → implementer/planner
+ * Assigns a specific task with acceptance criteria.
+ */
+export const TaskAssignmentBodySchema = z.object({
+  type: z.literal('task_assignment'),
+  taskId: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string(),
+  acceptanceCriteria: z.array(z.string()),
+});
+export type TaskAssignmentBody = z.infer<typeof TaskAssignmentBodySchema>;
+
+/**
+ * TaskCompleteBody — implementer/planner → orchestrator
+ * Signals that a task has been completed successfully.
+ */
+export const TaskCompleteBodySchema = z.object({
+  type: z.literal('task_complete'),
+  taskId: z.string().min(1),
+  summary: z.string(),
+});
+export type TaskCompleteBody = z.infer<typeof TaskCompleteBodySchema>;
+
+/**
+ * StatusUpdateBody — implementer/planner → orchestrator
+ * Reports incremental progress on a task.
+ */
+export const StatusUpdateBodySchema = z.object({
+  type: z.literal('status_update'),
+  taskId: z.string().min(1),
+  progress: z.number().int().min(0).max(100),
+  message: z.string(),
+});
+export type StatusUpdateBody = z.infer<typeof StatusUpdateBodySchema>;
+
+/**
+ * ErrorReportBody — any → any
+ * Reports an error. taskId is optional (error may not be task-scoped).
+ */
+export const ErrorReportBodySchema = z.object({
+  type: z.literal('error_report'),
+  errorCode: z.string().min(1),
+  message: z.string(),
+  taskId: z.string().optional(),
+});
+export type ErrorReportBody = z.infer<typeof ErrorReportBodySchema>;
+
+/**
+ * PingBody — any → any
+ * Heartbeat request.
+ */
+export const PingBodySchema = z.object({
+  type: z.literal('ping'),
+});
+export type PingBody = z.infer<typeof PingBodySchema>;
+
+/**
+ * PongBody — any → any
+ * Heartbeat response.
+ */
+export const PongBodySchema = z.object({
+  type: z.literal('pong'),
+});
+export type PongBody = z.infer<typeof PongBodySchema>;
+
+/**
+ * MessageBodySchema — discriminated union over all body variants.
+ * Discriminant key: `type`.
+ */
+export const MessageBodySchema = z.discriminatedUnion('type', [
+  TaskAssignmentBodySchema,
+  TaskCompleteBodySchema,
+  StatusUpdateBodySchema,
+  ErrorReportBodySchema,
+  PingBodySchema,
+  PongBodySchema,
+]);
+export type MessageBody = z.infer<typeof MessageBodySchema>;
+
+// ─────────────────────────────────────────────────────────────
+// Task 1.1 — MessageEnvelope + Zod schema
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * MessageEnvelope is the top-level protocol unit exchanged between agents.
+ * All messages on the filesystem are JSON-serialized MessageEnvelope objects.
+ */
+export const MessageEnvelopeSchema = z.object({
+  /** UUID v4 — unique message identifier */
+  id: z.string().uuid(),
+  /** Sender address */
+  from: MailboxAddressSchema,
+  /** Recipient address */
+  to: MailboxAddressSchema,
+  /** ISO 8601 UTC timestamp of creation */
+  timestamp: z.string().datetime(),
+  /** Typed message payload */
+  body: MessageBodySchema,
+});
+export type MessageEnvelope = z.infer<typeof MessageEnvelopeSchema>;
+
+// ─────────────────────────────────────────────────────────────
+// RegistryEntry — sprint agent registration record (RFC-025 M4)
+// ─────────────────────────────────────────────────────────────
+
+export const RegistryEntrySchema = z.object({
+  role: RoleSchema,
+  sprintId: z.string(),
+  sessionId: z.string().optional(),
+  pid: z.number(),
+  registeredAt: z.string().datetime(),
+  worktreePath: z.string().optional(),
+  workflowId: z.string().optional(),
+  resumedAt: z.string().datetime().optional(),
+});
+export type RegistryEntry = z.infer<typeof RegistryEntrySchema>;

package/templates/base/scripts/lib/sidecar/SidecarWatcher.ts

@@ -0,0 +1,249 @@
+/**
+ * SidecarWatcher.ts — Reactive sidecar process for sprint mailbox events (RFC-025 v3.3)
+ *
+ * A Node.js watcher that listens for incoming mailbox messages and spawns
+ * Agent SDK `query()` calls on demand — zero idle resource usage.
+ *
+ * Architecture:
+ *   1. chokidar watches the inbox directory for new .json files
+ *   2. On "add" event: read + validate envelope via Zod, then unlink (consume)
+ *   3. Build a prompt from the envelope body and call SDK query()
+ *   4. Stream query output to stdout (visible in the tmux pane)
+ *
+ * DI via factory function — same pattern as MailboxWatcher.ts and gate-guardian.ts.
+ * All external dependencies (chokidar, SDK, fs) are injected for testability.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { watch as chokidarWatchFn } from 'chokidar';
+import type { FSWatcher, WatchOptions } from 'chokidar';
+import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
+import type { Options } from '@anthropic-ai/claude-agent-sdk';
+import { MessageEnvelopeSchema } from '../mailbox/types.js';
+import type { MessageEnvelope } from '../mailbox/types.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Minimal query function signature — accepts prompt + options, returns async iterable.
+ * Matches @anthropic-ai/claude-agent-sdk's query() signature.
+ */
+export type QueryFn = (params: {
+  prompt: string;
+  options?: Options;
+}) => AsyncIterable<unknown>;
+
+export interface SidecarWatcherDeps {
+  /** Absolute path to the inbox directory to watch. */
+  inboxPath: string;
+  /** Absolute path to the worktree — passed as cwd to SDK query(). */
+  worktreePath: string;
+  /** Agent slug passed to SDK query() options.agent. */
+  agentSlug: string;
+  /** Chokidar watch function (injected for testability). */
+  watch: (inboxPath: string, options?: WatchOptions) => FSWatcher;
+  /** Agent SDK query function (injected for testability). */
+  query: QueryFn;
+  /** fs.readFileSync (injected for testability). */
+  readFileSync: (filePath: string, encoding: BufferEncoding) => string;
+  /** fs.unlinkSync (injected for testability). */
+  unlinkSync: (filePath: string) => void;
+}
+
+export interface SidecarWatcher {
+  /** Start watching the inbox directory. Idempotent — calling twice is safe. */
+  start(): void;
+  /** Stop watching and release resources. Resolves when the watcher is closed. */
+  stop(): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+
+/**
+ * Builds the prompt string sent to the Agent SDK from a validated envelope.
+ * For task_assignment: includes taskId, title, description, and acceptance criteria.
+ * For other body types: includes the serialised body as JSON context.
+ */
+function buildPrompt(envelope: MessageEnvelope): string {
+  const { body } = envelope;
+
+  if (body.type === 'task_assignment') {
+    const criteria = body.acceptanceCriteria.length > 0
+      ? `\n\nAcceptance criteria:\n${body.acceptanceCriteria.map(c => `- ${c}`).join('\n')}`
+      : '';
+    return [
+      `Task: ${body.taskId} — ${body.title}`,
+      body.description ? `\n${body.description}` : '',
+      criteria,
+    ].join('');
+  }
+
+  if (body.type === 'status_update') {
+    return `Status update for ${body.taskId}: [${body.progress}%] ${body.message}`;
+  }
+
+  if (body.type === 'task_complete') {
+    return `Task ${body.taskId} is complete. Summary: ${body.summary}`;
+  }
+
+  if (body.type === 'error_report') {
+    const taskSuffix = body.taskId ? ` (task: ${body.taskId})` : '';
+    return `Error [${body.errorCode}]${taskSuffix}: ${body.message}`;
+  }
+
+  // ping / pong / unknown — send minimal context
+  return `Received message of type "${body.type}" from ${envelope.from.role}-${envelope.from.index}. Acknowledge and stand by.`;
+}
+
+// ---------------------------------------------------------------------------
+// File guard
+// ---------------------------------------------------------------------------
+
+function isMessageFile(filePath: string): boolean {
+  const basename = path.basename(filePath);
+  return basename.endsWith('.json') && !basename.startsWith('.tmp-');
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+const defaultDeps: Pick<SidecarWatcherDeps, 'watch' | 'query' | 'readFileSync' | 'unlinkSync'> = {
+  watch: chokidarWatchFn,
+  query: sdkQuery,
+  readFileSync: (p, enc) => fs.readFileSync(p, enc),
+  unlinkSync: fs.unlinkSync,
+};
+
+export function createSidecarWatcher(deps: SidecarWatcherDeps): SidecarWatcher {
+  const {
+    inboxPath,
+    worktreePath,
+    agentSlug,
+    watch,
+    query,
+    readFileSync,
+    unlinkSync,
+  } = { ...defaultDeps, ...deps };
+
+  let fsWatcher: FSWatcher | null = null;
+
+  /**
+   * Handles a newly-added file in the inbox.
+   * Steps:
+   *   1. Guard: skip non-message files
+   *   2. Read + parse the envelope JSON
+   *   3. Validate against Zod schema
+   *   4. Unlink (consume) the file
+   *   5. Call SDK query() and drain the stream to stdout
+   */
+  async function handleAddedFile(filePath: string): Promise<void> {
+    if (!isMessageFile(filePath)) {
+      return;
+    }
+
+    let envelope: MessageEnvelope;
+
+    try {
+      const raw = readFileSync(filePath, 'utf-8');
+      const parsed: unknown = JSON.parse(raw);
+      envelope = MessageEnvelopeSchema.parse(parsed);
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[sidecar:${agentSlug}] Failed to parse envelope at ${filePath}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+      return;
+    }
+
+    // Consume the file — done before query() so re-entry is safe
+    try {
+      unlinkSync(filePath);
+    } catch {
+      // Best-effort — continue even if unlink fails (e.g. concurrent consumer)
+    }
+
+    const prompt = buildPrompt(envelope);
+
+    // eslint-disable-next-line no-console
+    console.log(`[sidecar:${agentSlug}] Processing message ${envelope.id} — calling query()...`);
+
+    try {
+      // Defense-in-depth: strip API keys from env passed to query().
+      // Primary stripping happens in run.ts (process.env level), but this
+      // ensures keys are never passed even if run.ts is bypassed.
+      const sidecarEnv: Record<string, string | undefined> = { ...process.env };
+      delete sidecarEnv['ANTHROPIC_API_KEY'];
+      delete sidecarEnv['CLAUDE_API_KEY'];
+
+      const stream = query({
+        prompt,
+        options: {
+          agent: agentSlug,
+          cwd: worktreePath,
+          // Sidecar runs non-interactively — must bypass all permission prompts.
+          permissionMode: 'bypassPermissions',
+          allowDangerouslySkipPermissions: true,
+          // Ephemeral — no need to persist session history for reactive sidecars.
+          persistSession: false,
+          // Force OAuth — same as `env -u ANTHROPIC_API_KEY` in TmuxManager.
+          env: sidecarEnv,
+        },
+      });
+
+      // Drain the stream — log result messages for observability
+      for await (const msg of stream) {
+        const m = msg as Record<string, unknown>;
+        if (m.type === 'result') {
+          // eslint-disable-next-line no-console
+          console.log(
+            `[sidecar:${agentSlug}] query() completed — result: ${m.subtype}`,
+            typeof m.result === 'string' ? m.result.slice(0, 200) : '',
+          );
+        }
+      }
+    } catch (err) {
+      // eslint-disable-next-line no-console
+      console.error(
+        `[sidecar:${agentSlug}] query() error for message ${envelope.id}:`,
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
+  function start(): void {
+    if (fsWatcher !== null) {
+      // Already started — idempotent
+      return;
+    }
+
+    fsWatcher = watch(inboxPath, {
+      ignoreInitial: true,
+      persistent: true,
+      // usePolling fallback: when inotify watchers are exhausted (ENOSPC),
+      // chokidar falls back to polling. 1s interval is fine for mailbox events.
+      usePolling: true,
+      interval: 1000,
+    });
+
+    fsWatcher.on('add', (filePath: string) => {
+      // Fire-and-forget — errors are caught inside handleAddedFile
+      void handleAddedFile(filePath);
+    });
+  }
+
+  async function stop(): Promise<void> {
+    if (fsWatcher !== null) {
+      await fsWatcher.close();
+      fsWatcher = null;
+    }
+  }
+
+  return { start, stop };
+}

package/templates/base/scripts/lib/sidecar/run.ts

@@ -0,0 +1,90 @@
+#!/usr/bin/env npx tsx
+/**
+ * run.ts — CLI entry point for the reactive sidecar watcher (RFC-025 v3.3)
+ *
+ * Launched by TmuxManager in sidecar panes. Parses CLI args, creates a
+ * SidecarWatcher, and runs until SIGTERM/SIGINT.
+ *
+ * Usage:
+ *   npx tsx scripts/lib/sidecar/run.ts --inbox /path/to/inbox --worktree /path/to/wt --agent doc-sidecar
+ */
+
+import { createSidecarWatcher } from './SidecarWatcher.js';
+import { parseArgs } from 'node:util';
+
+// ---------------------------------------------------------------------------
+// CLI argument parsing
+// ---------------------------------------------------------------------------
+
+const { values } = parseArgs({
+  options: {
+    inbox: { type: 'string' },
+    worktree: { type: 'string' },
+    agent: { type: 'string' },
+  },
+  strict: true,
+});
+
+if (!values.inbox || !values.worktree || !values.agent) {
+  // eslint-disable-next-line no-console
+  console.error('Usage: npx tsx run.ts --inbox <path> --worktree <path> --agent <slug>');
+  process.exit(1);
+}
+
+// ---------------------------------------------------------------------------
+// Force OAuth/Claude Max — strip API keys from process.env BEFORE any SDK use.
+// The SDK reads process.env internally; passing `env` in query() options alone
+// is not sufficient. This mirrors `env -u ANTHROPIC_API_KEY` from TmuxManager.
+// ---------------------------------------------------------------------------
+
+const API_KEY_VARS = ['ANTHROPIC_API_KEY', 'CLAUDE_API_KEY'] as const;
+for (const key of API_KEY_VARS) {
+  if (process.env[key]) {
+    // eslint-disable-next-line no-console
+    console.log(`[sidecar:${values.agent}] Stripping ${key} from env to force OAuth`);
+    delete process.env[key];
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Resilience: prevent unhandled rejections from killing the watcher.
+// The SDK's internal chokidar/inotify errors (ENOSPC) are non-fatal —
+// they surface as unhandled rejections and must not crash the process.
+// ---------------------------------------------------------------------------
+
+process.on('unhandledRejection', (reason) => {
+  // eslint-disable-next-line no-console
+  console.error(
+    `[sidecar:${values.agent}] Unhandled rejection (non-fatal):`,
+    reason instanceof Error ? reason.message : String(reason),
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Start watcher
+// ---------------------------------------------------------------------------
+
+// eslint-disable-next-line no-console
+console.log(`[sidecar:${values.agent}] Starting reactive watcher on ${values.inbox}`);
+
+const watcher = createSidecarWatcher({
+  inboxPath: values.inbox,
+  worktreePath: values.worktree,
+  agentSlug: values.agent,
+});
+
+watcher.start();
+
+// ---------------------------------------------------------------------------
+// Graceful shutdown
+// ---------------------------------------------------------------------------
+
+async function shutdown(signal: string): Promise<void> {
+  // eslint-disable-next-line no-console
+  console.log(`[sidecar:${values.agent}] Received ${signal}, shutting down...`);
+  await watcher.stop();
+  process.exit(0);
+}
+
+process.on('SIGTERM', () => void shutdown('SIGTERM'));
+process.on('SIGINT', () => void shutdown('SIGINT'));