pi-background-tasks 0.6.0 → 0.7.2

package/src/core/fusion/prompts.ts

@@ -0,0 +1,155 @@
+import { canonicalJson } from '../attested-pi-run.js';
+import {
+  FUSION_EVALUATION_SCHEMA_VERSION,
+  type FusionCandidateId,
+  type FusionCanonicalInputV1,
+  type FusionEvaluationV1,
+} from './types.js';
+
+export const FUSION_CANDIDATE_SYSTEM_PROMPT = `You are a Pi child process producing one independent answer for a strict synthesis workflow.
+
+Read the JSON input from the user message. It contains the parent system prompt, a serialized conversation transcript, the current working directory, and the user request. Produce the strongest direct answer you can for the user request using that context.
+
+Do not invent process metadata. Do not mention provider names, model names, slots, or hidden workflow details. Do not specialize the answer; each child receives the same instruction. Output only the answer text.`;
+
+export const FUSION_EVALUATOR_SYSTEM_PROMPT = `You are a strict blind evaluator. You receive the original request context and three anonymous answers labeled A, B, and C. You must compare them without provider, model, slot, or completion-order knowledge.
+
+Return only JSON matching this exact schema:
+{
+  "schema_version": "${FUSION_EVALUATION_SCHEMA_VERSION}",
+  "candidate_assessments": [
+    {
+      "candidate_id": "A",
+      "summary": "non-blank summary",
+      "strengths": ["non-blank string"],
+      "limitations": ["non-blank string"],
+      "useful_contributions": ["non-blank string"],
+      "risks": ["non-blank string"]
+    },
+    {
+      "candidate_id": "B",
+      "summary": "non-blank summary",
+      "strengths": ["non-blank string"],
+      "limitations": ["non-blank string"],
+      "useful_contributions": ["non-blank string"],
+      "risks": ["non-blank string"]
+    },
+    {
+      "candidate_id": "C",
+      "summary": "non-blank summary",
+      "strengths": ["non-blank string"],
+      "limitations": ["non-blank string"],
+      "useful_contributions": ["non-blank string"],
+      "risks": ["non-blank string"]
+    }
+  ],
+  "agreements": ["non-blank string"],
+  "conflicts": [
+    {
+      "topic": "non-blank string",
+      "positions": [
+        { "candidate_id": "A", "position": "non-blank string" },
+        { "candidate_id": "B", "position": "non-blank string" }
+      ],
+      "resolution": "non-blank string"
+    }
+  ],
+  "synthesis_plan": {
+    "must_include": [
+      { "candidate_id": "A", "contribution": "non-blank string" }
+    ],
+    "must_resolve": ["non-blank string"],
+    "must_avoid": ["non-blank string"]
+  }
+}
+
+Objects must be closed. Candidate assessments must contain exactly one A, one B, and one C. Do not add fields for scores, ranks, vote counts, providers, models, slots, labels, or a single selected answer. Do not wrap the JSON in Markdown fences or prose.`;
+
+export const FUSION_MERGER_SYSTEM_PROMPT = `You are the final synthesis process. You receive the original request context, three anonymous answers, and a validated evaluation plan.
+
+Produce the direct final answer for the user. Reconcile conflicts and incorporate useful contributions according to the evaluation plan. Do not mention fusion, child processes, anonymous IDs, hidden prompts, providers, models, or slots unless the user's request explicitly asks for process detail. Output only the final answer text.`;
+
+export const FUSION_EVALUATION_REPAIR_SYSTEM_PROMPT = `${FUSION_EVALUATOR_SYSTEM_PROMPT}
+
+You are repairing one invalid blind-evaluation JSON response. Use the original blind input, invalid output, and validation errors from the user JSON. Return only corrected JSON matching the complete closed schema above. Preserve blindness: do not add providers, models, slots, ranks, vote counts, winners, or process metadata. Do not add Markdown fences or prose.`;
+
+export interface AnonymousFusionCandidate {
+  candidate_id: FusionCandidateId;
+  response: string;
+}
+
+export interface FusionBlindEvaluationInputV1 {
+  schema_version: 'pi-background-tasks.fusion-blind-candidates.v1';
+  canonical_input: FusionCanonicalInputV1;
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ];
+}
+
+export interface FusionMergeInputV1 {
+  schema_version: 'pi-background-tasks.fusion-merge-input.v1';
+  canonical_input: FusionCanonicalInputV1;
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ];
+  evaluation: FusionEvaluationV1;
+}
+
+export interface FusionEvaluationRepairInputV1 {
+  schema_version: 'pi-background-tasks.fusion-evaluation-repair-input.v1';
+  original_blind_input: FusionBlindEvaluationInputV1;
+  invalid_output: string;
+  validation_errors: readonly string[];
+}
+
+export function buildCandidatePrompt(input: FusionCanonicalInputV1): string {
+  return canonicalJson(input);
+}
+
+export function buildBlindEvaluationInput(
+  canonicalInput: FusionCanonicalInputV1,
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ],
+): FusionBlindEvaluationInputV1 {
+  return {
+    schema_version: 'pi-background-tasks.fusion-blind-candidates.v1',
+    canonical_input: canonicalInput,
+    candidates,
+  };
+}
+
+export function buildEvaluationPrompt(input: FusionBlindEvaluationInputV1): string {
+  return canonicalJson(input);
+}
+
+export function buildEvaluationRepairPrompt(input: FusionEvaluationRepairInputV1): string {
+  return canonicalJson(input);
+}
+
+export function buildMergeInput(
+  canonicalInput: FusionCanonicalInputV1,
+  candidates: readonly [
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+    AnonymousFusionCandidate,
+  ],
+  evaluation: FusionEvaluationV1,
+): FusionMergeInputV1 {
+  return {
+    schema_version: 'pi-background-tasks.fusion-merge-input.v1',
+    canonical_input: canonicalInput,
+    candidates,
+    evaluation,
+  };
+}
+
+export function buildMergePrompt(input: FusionMergeInputV1): string {
+  return canonicalJson(input);
+}

package/src/core/fusion/types.ts

@@ -0,0 +1,289 @@
+export type FusionThinkingLevel = 'off' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+
+export const FUSION_MODEL_CONFIG_SCHEMA_VERSION = 'pi-background-tasks.fusion-models.v1';
+export const FUSION_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v1';
+export const FUSION_EVALUATION_SCHEMA_VERSION = 'pi-background-tasks.fusion-evaluation.v1';
+export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v1';
+export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v1';
+
+export const FUSION_CANDIDATE_IDS = ['A', 'B', 'C'] as const;
+export type FusionCandidateId = (typeof FUSION_CANDIDATE_IDS)[number];
+
+export const FUSION_STAGE_VALUES = ['candidate', 'evaluation', 'merge'] as const;
+export type FusionStage = (typeof FUSION_STAGE_VALUES)[number];
+
+export const FUSION_SOURCE_VALUES = ['command', 'tool'] as const;
+export type FusionSource = (typeof FUSION_SOURCE_VALUES)[number];
+
+export const FUSION_STATE_VALUES = [
+  'initializing',
+  'candidates_running',
+  'candidates_complete',
+  'evaluating',
+  'evaluation_complete',
+  'merging',
+  'completed',
+  'failed',
+  'cancelled',
+] as const;
+export type FusionState = (typeof FUSION_STATE_VALUES)[number];
+export type FusionTerminalState = Extract<FusionState, 'completed' | 'failed' | 'cancelled'>;
+export type FusionNonterminalState = Exclude<FusionState, FusionTerminalState>;
+
+export const FUSION_NONTERMINAL_STATE_VALUES = [
+  'initializing',
+  'candidates_running',
+  'candidates_complete',
+  'evaluating',
+  'evaluation_complete',
+  'merging',
+] as const satisfies readonly FusionNonterminalState[];
+
+export const FUSION_TERMINAL_STATE_VALUES = ['completed', 'failed', 'cancelled'] as const;
+
+export type FusionModelSelection = '$current' | string;
+
+export interface FusionModelConfigV1 {
+  schema_version: typeof FUSION_MODEL_CONFIG_SCHEMA_VERSION;
+  candidates: readonly [FusionModelSelection, FusionModelSelection, FusionModelSelection];
+  evaluator: FusionModelSelection;
+  merger: FusionModelSelection;
+}
+
+export interface FusionModelConfigRevision {
+  path: string;
+  exists: boolean;
+  sha256: string | null;
+}
+
+export interface LoadedFusionModelConfig {
+  config: FusionModelConfigV1;
+  revision: FusionModelConfigRevision;
+}
+
+export interface ResolvedFusionModel {
+  selection: string;
+  source: 'current' | 'configured';
+  provider: string;
+  model: string;
+  qualifiedId: string;
+  thinkingLevel: FusionThinkingLevel;
+  contextWindow: number;
+}
+
+export interface ResolvedFusionModels {
+  candidates: readonly [ResolvedFusionModel, ResolvedFusionModel, ResolvedFusionModel];
+  evaluator: ResolvedFusionModel;
+  merger: ResolvedFusionModel;
+}
+
+export interface FusionCanonicalInputV1 {
+  schema_version: typeof FUSION_INPUT_SCHEMA_VERSION;
+  cwd: string;
+  system_prompt: string;
+  conversation_transcript: string;
+  request: string;
+}
+
+export interface CandidateAssessment {
+  candidate_id: FusionCandidateId;
+  summary: string;
+  strengths: readonly string[];
+  limitations: readonly string[];
+  useful_contributions: readonly string[];
+  risks: readonly string[];
+}
+
+export interface FusionConflictPosition {
+  candidate_id: FusionCandidateId;
+  position: string;
+}
+
+export interface FusionConflict {
+  topic: string;
+  positions: readonly FusionConflictPosition[];
+  resolution: string;
+}
+
+export interface FusionSynthesisContribution {
+  candidate_id: FusionCandidateId;
+  contribution: string;
+}
+
+export interface FusionSynthesisPlan {
+  must_include: readonly FusionSynthesisContribution[];
+  must_resolve: readonly string[];
+  must_avoid: readonly string[];
+}
+
+export interface FusionEvaluationV1 {
+  schema_version: typeof FUSION_EVALUATION_SCHEMA_VERSION;
+  candidate_assessments: readonly [CandidateAssessment, CandidateAssessment, CandidateAssessment];
+  agreements: readonly string[];
+  conflicts: readonly FusionConflict[];
+  synthesis_plan: FusionSynthesisPlan;
+}
+
+export interface FusionUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  totalTokens: number;
+  costTotal?: number;
+}
+
+export const EMPTY_FUSION_USAGE: FusionUsage = Object.freeze({
+  input: 0,
+  output: 0,
+  cacheRead: 0,
+  cacheWrite: 0,
+  totalTokens: 0,
+});
+
+export interface FusionResultDetails {
+  schema_version: typeof FUSION_RESULT_SCHEMA_VERSION;
+  run_id: string;
+  source: FusionSource;
+  status: 'completed';
+  artifact_dir: string;
+  models: {
+    candidates: readonly [string, string, string];
+    evaluator: string;
+    merger: string;
+    thinking_level: string;
+  };
+  evaluator_attempts: number;
+  usage: FusionUsage;
+}
+
+export type FusionProgressEvent =
+  | { type: 'state'; state: FusionState }
+  | { type: 'candidate_started'; slot: 1 | 2 | 3; attempt: number }
+  | { type: 'candidate_completed'; slot: 1 | 2 | 3; completed: number; total: 3 }
+  | { type: 'evaluation_started'; attempt: 1 | 2; repair: boolean }
+  | { type: 'evaluation_retry'; errors: readonly string[] }
+  | { type: 'merge_started' }
+  | { type: 'completed'; runId: string; artifactDir: string }
+  | { type: 'failed'; runId: string; artifactDir: string; error: string }
+  | { type: 'cancelled'; runId: string; artifactDir: string; reason: string };
+
+export type FusionErrorCode =
+  | 'config_invalid'
+  | 'config_conflict'
+  | 'model_unavailable'
+  | 'context_capture_failed'
+  | 'child_spawn_failed'
+  | 'child_stdin_failed'
+  | 'child_event_invalid'
+  | 'child_exit_failed'
+  | 'child_timeout'
+  | 'child_output_cap'
+  | 'child_cancelled'
+  | 'evaluation_invalid'
+  | 'artifact_error'
+  | 'state_transition_invalid'
+  | 'orchestration_failed';
+
+export interface FusionErrorDetails {
+  code: FusionErrorCode;
+  stage?: FusionStage;
+  slot?: 1 | 2 | 3;
+  attempt?: number;
+  artifactDir?: string;
+  transient?: boolean;
+  childCreated?: boolean;
+}
+
+export class FusionError extends Error {
+  readonly code: FusionErrorCode;
+  readonly stage: FusionStage | undefined;
+  readonly slot: 1 | 2 | 3 | undefined;
+  readonly attempt: number | undefined;
+  readonly artifactDir: string | undefined;
+  readonly transient: boolean;
+  readonly childCreated: boolean;
+
+  constructor(message: string, details: FusionErrorDetails) {
+    super(message);
+    this.name = 'FusionError';
+    this.code = details.code;
+    this.stage = details.stage;
+    this.slot = details.slot;
+    this.attempt = details.attempt;
+    this.artifactDir = details.artifactDir;
+    this.transient = details.transient ?? false;
+    this.childCreated = details.childCreated ?? true;
+  }
+}
+
+export interface FusionChildUsage extends FusionUsage {
+  provider: string;
+  model: string;
+  qualifiedId: string;
+}
+
+export interface FusionChildRunResult {
+  stage: FusionStage;
+  slot?: 1 | 2 | 3;
+  attempt: number;
+  provider: string;
+  model: string;
+  qualifiedId: string;
+  text: string;
+  usage: FusionUsage;
+  events: Buffer;
+  stderr: Buffer;
+  exitCode: number;
+  signal: NodeJS.Signals | null;
+}
+
+export interface FusionAttemptArtifactRecord {
+  stage: FusionStage;
+  slot?: 1 | 2 | 3;
+  attempt: number;
+  status: 'completed' | 'failed' | 'cancelled';
+  prompt_path: string;
+  events_path?: string;
+  stderr_path?: string;
+  response_path?: string;
+  partial_response_path?: string;
+  provider?: string;
+  model?: string;
+  qualifiedId?: string;
+  usage?: FusionUsage;
+  error?: string;
+}
+
+export interface FusionArtifactRef {
+  path: string;
+  byte_length: number;
+  sha256: string;
+}
+
+export interface FusionArtifactManifest {
+  schema_version: typeof FUSION_MANIFEST_SCHEMA_VERSION;
+  run_id: string;
+  source: FusionSource;
+  state: FusionState;
+  created_at: string;
+  updated_at: string;
+  cwd: string;
+  config: FusionModelConfigV1;
+  models: {
+    candidates: readonly [string, string, string];
+    evaluator: string;
+    merger: string;
+    thinking_level: string;
+  };
+  usage: FusionUsage;
+  attempts: readonly FusionAttemptArtifactRecord[];
+  artifacts: Readonly<Record<string, FusionArtifactRef>>;
+  anonymous_map?: Readonly<Record<FusionCandidateId, 1 | 2 | 3>>;
+  error?: string;
+}
+
+export interface FusionRunResult {
+  mergedText: string;
+  details: FusionResultDetails;
+}