pi-background-tasks 0.7.6 → 0.9.0

package/src/core/fusion/workflows.ts

@@ -0,0 +1,130 @@
+import {
+  FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+  FUSION_EVALUATOR_SYSTEM_PROMPT,
+  FUSION_MERGER_SYSTEM_PROMPT,
+  FUSION_VALIDATE_EVALUATION_REPAIR_SYSTEM_PROMPT,
+  FUSION_VALIDATE_EVALUATOR_SYSTEM_PROMPT,
+  FUSION_VALIDATE_MERGER_SYSTEM_PROMPT,
+  fusionCandidateSystemPrompt,
+  fusionValidateCandidateSystemPrompt,
+} from './prompts.js';
+import {
+  FUSION_DEFAULT_CAPABILITY,
+  FUSION_VALIDATE_CAPABILITY,
+  FusionError,
+  type FusionCapability,
+  type FusionWorkflowId,
+} from './types.js';
+
+export const FUSION_BRAINSTORM_TOOL_NAME = 'fusion_brainstorm';
+export const FUSION_VALIDATE_TOOL_NAME = 'fusion_validate';
+
+/**
+ * How a workflow decides which capability its candidate children run with.
+ *
+ * `caller_selected` lets the tool schema offer a capability argument and defaults
+ * to the least-privileged profile. `fixed` pins one capability for every run and
+ * makes each other value a loud orchestration failure rather than a silent
+ * downgrade.
+ */
+export type FusionCapabilityPolicy = 'caller_selected' | 'fixed';
+
+/**
+ * Stage framing for one Fusion workflow.
+ *
+ * Everything a workflow can vary lives here: the four system prompts, the
+ * capability policy, and presentation strings. Everything else - the conversation
+ * projection, canonical input schema, budget policy, evaluation schema, artifact
+ * store, and state machine - is shared and must never be branched per workflow.
+ */
+export interface FusionWorkflowProfile {
+  readonly id: FusionWorkflowId;
+  readonly toolName: string;
+  /** First character of the run id, so artifact directories are self-describing. */
+  readonly runIdPrefix: string;
+  readonly capabilityPolicy: FusionCapabilityPolicy;
+  /** The only capability permitted when `capabilityPolicy` is `fixed`. */
+  readonly fixedCapability: FusionCapability | undefined;
+  readonly defaultCapability: FusionCapability;
+  readonly candidateSystemPrompt: (capability: FusionCapability) => string;
+  readonly evaluatorSystemPrompt: string;
+  readonly evaluationRepairSystemPrompt: string;
+  readonly mergerSystemPrompt: string;
+  /** Human-readable noun used in progress lines and rendered results. */
+  readonly label: string;
+}
+
+export const FUSION_BRAINSTORM_WORKFLOW: FusionWorkflowProfile = Object.freeze({
+  id: 'brainstorm',
+  toolName: FUSION_BRAINSTORM_TOOL_NAME,
+  runIdPrefix: 'f',
+  capabilityPolicy: 'caller_selected',
+  fixedCapability: undefined,
+  defaultCapability: FUSION_DEFAULT_CAPABILITY,
+  candidateSystemPrompt: fusionCandidateSystemPrompt,
+  evaluatorSystemPrompt: FUSION_EVALUATOR_SYSTEM_PROMPT,
+  evaluationRepairSystemPrompt: FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT,
+  mergerSystemPrompt: FUSION_MERGER_SYSTEM_PROMPT,
+  label: 'fusion',
+});
+
+export const FUSION_VALIDATE_WORKFLOW: FusionWorkflowProfile = Object.freeze({
+  id: 'validate',
+  toolName: FUSION_VALIDATE_TOOL_NAME,
+  runIdPrefix: 'v',
+  capabilityPolicy: 'fixed',
+  fixedCapability: FUSION_VALIDATE_CAPABILITY,
+  defaultCapability: FUSION_VALIDATE_CAPABILITY,
+  candidateSystemPrompt: fusionValidateCandidateSystemPrompt,
+  evaluatorSystemPrompt: FUSION_VALIDATE_EVALUATOR_SYSTEM_PROMPT,
+  evaluationRepairSystemPrompt: FUSION_VALIDATE_EVALUATION_REPAIR_SYSTEM_PROMPT,
+  mergerSystemPrompt: FUSION_VALIDATE_MERGER_SYSTEM_PROMPT,
+  label: 'validate',
+});
+
+const PROFILES_BY_ID: Readonly<Record<FusionWorkflowId, FusionWorkflowProfile>> = Object.freeze({
+  brainstorm: FUSION_BRAINSTORM_WORKFLOW,
+  validate: FUSION_VALIDATE_WORKFLOW,
+});
+
+export function fusionWorkflowProfile(id: FusionWorkflowId): FusionWorkflowProfile {
+  const profile = PROFILES_BY_ID[id];
+  if (profile === undefined) {
+    throw new FusionError(`unknown fusion workflow ${String(id)}`, {
+      code: 'orchestration_failed',
+      childCreated: false,
+    });
+  }
+  return profile;
+}
+
+/**
+ * Resolve the candidate capability for one run under its workflow's policy.
+ *
+ * A `fixed` workflow rejects each other capability instead of quietly substituting
+ * its own: silently accepting `reason` for a validation run would produce a review
+ * that never read the code, which is exactly the failure this workflow exists to
+ * prevent.
+ */
+export function resolveWorkflowCapability(
+  profile: FusionWorkflowProfile,
+  requested: FusionCapability | undefined,
+): FusionCapability {
+  if (profile.capabilityPolicy === 'caller_selected') {
+    return requested ?? profile.defaultCapability;
+  }
+  const fixed = profile.fixedCapability;
+  if (fixed === undefined) {
+    throw new FusionError(
+      `fusion workflow ${profile.id} declares a fixed capability policy without a capability`,
+      { code: 'orchestration_failed', childCreated: false },
+    );
+  }
+  if (requested !== undefined && requested !== fixed) {
+    throw new FusionError(
+      `fusion workflow ${profile.id} always runs candidates with the ${fixed} capability; received ${String(requested)}`,
+      { code: 'orchestration_failed', childCreated: false },
+    );
+  }
+  return fixed;
+}

package/src/core/registry.ts

@@ -27,6 +27,7 @@ import {
   type JsonObject,
   type KillKind,
   type StartAttestedPiTaskOptions,
+  type StartDelegateTaskOptions,
   type StartTaskOptions,
   type TaskContextUsage,
   type TaskStatus,
@@ -52,6 +53,7 @@ import {
 } from './attested-pi-run.js';
 import {
   assertWindowsCommandLineWithinLimit,
+  piLaunchArgv,
   resolvePiLaunch,
   type PiLaunchSpec,
 } from './pi-launch.js';
@@ -87,8 +89,15 @@ interface OutputEventSource {
   on(event: 'data', listener: (data: Buffer | string) => void): unknown;
 }
 
+interface ChildStdin {
+  write(data: Buffer, callback: (error?: Error | null) => void): boolean;
+  end(callback?: () => void): unknown;
+  once(event: 'error', listener: (error: Error) => void): unknown;
+}
+
 export interface BackgroundTaskChildProcess {
   pid?: number | undefined;
+  stdin?: ChildStdin | null | undefined;
   stdout?: OutputEventSource | null | undefined;
   stderr?: OutputEventSource | null | undefined;
   kill(signal?: NodeJS.Signals): boolean;
@@ -678,6 +687,32 @@ function noopOnChange(): void {
   return undefined;
 }
 
+/**
+ * Deliver the delegate prompt bytes over stdin.
+ *
+ * A failure to deliver the seed is loud: the caller terminates the task rather
+ * than letting a child run without the context it was supposed to receive.
+ */
+function writeDelegateStdin(
+  child: BackgroundTaskChildProcess,
+  bytes: Buffer,
+  onError: (error: Error) => void,
+): void {
+  const stdin = child.stdin;
+  if (stdin === undefined || stdin === null) {
+    onError(new Error('delegate child stdin pipe is unavailable'));
+    return;
+  }
+  stdin.once('error', onError);
+  stdin.write(bytes, (error?: Error | null) => {
+    if (error !== undefined && error !== null) {
+      onError(error);
+      return;
+    }
+    stdin.end();
+  });
+}
+
 export class BackgroundTaskRegistry {
   private readonly tasks = new Map<string, BgTask>();
   private runtimeDir: RuntimeDir | undefined;
@@ -927,6 +962,145 @@ export class BackgroundTaskRegistry {
     }
   }
 
+  /**
+   * Start a prepared delegate child.
+   *
+   * The caller has already completed preflight, so by the time this runs the
+   * seed, budget plan, and artifact directory exist and the argv is fixed. The
+   * child is launched directly, never through a shell, and its terminal state
+   * flows through the same durable notification path as `bg_run`.
+   */
+  async startDelegateTask(
+    ctx: BackgroundTaskContext,
+    request: StartDelegateTaskOptions,
+  ): Promise<BgTask> {
+    if (this.shuttingDown)
+      throw new Error('Cannot start a delegate task while Pi is shutting down');
+
+    const launch = resolvePiLaunch({ platform: this.platform });
+    assertWindowsCommandLineWithinLimit(launch, request.argv, this.platform, 'bg-delegate');
+
+    const dir = await this.ensureRuntimeDir(ctx);
+    const id = request.facts.taskId;
+    const outputAbsPath = join(dir.abs, `${id}.output`);
+    const metadataAbsPath = join(dir.abs, `${id}.json`);
+    const outputPath = join(dir.display, `${id}.output`);
+
+    const task: BgTask = {
+      id,
+      name: normalizeTaskName(request.name) ?? 'Delegate task',
+      command: ['pi', ...request.argv].map(shellQuote).join(' '),
+      status: 'running',
+      outputPath,
+      outputAbsPath,
+      metadataAbsPath,
+      cwd: ctx.cwd,
+      startTime: this.now(),
+      exitCode: undefined,
+      pid: undefined,
+      bytesWritten: 0,
+      isAgent: true,
+      notified: false,
+      notifyOnCompletion: request.notifyOnCompletion,
+      triggerOnCompletion: request.triggerOnCompletion,
+      timeoutSeconds: request.timeoutSeconds,
+      model: request.facts.route.qualifiedId,
+      delegate: request.facts,
+      waiters: [],
+    };
+    this.tasks.set(id, task);
+
+    const stream = createWriteStream(outputAbsPath, { flags: 'a', encoding: 'utf8' });
+    task.stream = stream;
+    stream.on('error', (error) => {
+      task.error = `Output file write failed: ${error.message}`;
+    });
+
+    try {
+      const child = this.spawn(launch.executable, piLaunchArgv(launch, [...request.argv]), {
+        cwd: ctx.cwd,
+        detached: this.platform !== 'win32',
+        shell: false,
+        // The seed travels over stdin, never as a shell or positional argument,
+        // so the bytes the child reads are exactly the bytes that were persisted
+        // and hashed, with no quoting or command-line length limit in the path.
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env: request.env,
+        windowsHide: true,
+      });
+      task.child = child;
+      task.pid = child.pid;
+      writeDelegateStdin(child, request.stdinBytes, (error) => {
+        this.writeNotice(task, `\n[delegate stdin write failed: ${error.message}]\n`);
+        if (task.status === 'running') {
+          task.killKind = 'user';
+          task.error = `Delegate seed could not be delivered: ${error.message}`;
+          try {
+            this.requestKill(task, 'SIGTERM');
+          } catch {
+            void this.finalizeTask(task, 'failed', null, undefined, task.error);
+          }
+        }
+      });
+
+      child.stdout?.on('data', (data) => {
+        this.appendChildOutput(task, data, 'stdout');
+      });
+      child.stderr?.on('data', (data) => {
+        this.appendChildOutput(task, data, 'stderr');
+      });
+      child.on('error', (error) => {
+        this.writeNotice(task, `\n[delegate spawn error: ${error.message}]\n`);
+        void this.finalizeTask(task, 'failed', null, undefined, error.message);
+      });
+      child.on('close', (code, signalName) => {
+        let status: TaskStatus;
+        let error: string | undefined;
+        if (task.killKind === 'user' || task.killKind === 'shutdown') {
+          status = 'killed';
+        } else if (task.killKind === 'timeout') {
+          status = 'failed';
+          error = task.error ?? `Timed out after ${String(request.timeoutSeconds ?? 0)}s`;
+        } else if ((code ?? 0) === 0) {
+          status = 'completed';
+        } else {
+          status = 'failed';
+          error = `Exited with code ${code === null ? 'null' : String(code)}${signalName ? ` (${signalName})` : ''}`;
+        }
+        void this.finalizeTask(task, status, code, signalName, error);
+      });
+
+      if (request.timeoutSeconds !== undefined) {
+        task.timeoutHandle = setTimeout(() => {
+          if (task.status !== 'running') return;
+          task.killKind = 'timeout';
+          task.error = `Timed out after ${String(request.timeoutSeconds)}s`;
+          this.writeNotice(task, `\n[delegate timeout: ${task.error}]\n`);
+          try {
+            this.requestKill(task, 'SIGTERM');
+          } catch (error) {
+            void this.finalizeTask(
+              task,
+              'failed',
+              null,
+              undefined,
+              `${task.error}; kill failed: ${error instanceof Error ? error.message : String(error)}`,
+            );
+          }
+        }, request.timeoutSeconds * 1000);
+      }
+
+      await this.writeMetadata(task);
+      this.onChange();
+      return task;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      this.writeNotice(task, `\n[delegate spawn exception: ${message}]\n`);
+      await this.finalizeTask(task, 'failed', null, undefined, message);
+      throw new Error(`Failed to start delegate task: ${message}`);
+    }
+  }
+
   async startAttestedPiTask(
     ctx: BackgroundTaskContext,
     request: StartAttestedPiTaskOptions,