pi-background-tasks 0.7.7 → 1.0.3

package/src/core/fusion/types.ts

@@ -11,14 +11,20 @@ import type {
 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.v4';
+export const FUSION_LEGACY_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v4';
+export const FUSION_INPUT_SCHEMA_VERSION = 'pi-background-tasks.fusion-input.v5';
 export const FUSION_EVALUATION_SCHEMA_VERSION = 'pi-background-tasks.fusion-evaluation.v1';
-export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v3';
-export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v2';
+export const FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION = 'pi-background-tasks.fusion-validation-candidate.v1';
+export const FUSION_LEGACY_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v4';
+export const FUSION_RESULT_SCHEMA_VERSION = 'pi-background-tasks.fusion-result.v5';
+export const FUSION_LEGACY_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v3';
+export const FUSION_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.fusion-manifest.v4';
 export const FUSION_CONTEXT_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.fusion-context-ledger.v2';
+export const FUSION_SOURCE_POLICY_SCHEMA_VERSION = 'pi-background-tasks.fusion-source-policy.v1';
 export const FUSION_BUDGET_PLAN_SCHEMA_VERSION = 'pi-background-tasks.fusion-budget-plan.v3';
 export const FUSION_CALIBRATION_VIOLATION_SCHEMA_VERSION =
   'pi-background-tasks.fusion-calibration-violation.v1';
+export const FUSION_TOOL_CALL_LOG_SCHEMA_VERSION = 'pi-background-tasks.fusion-tool-call.v1';
 
 /**
  * Conversation-projection transform shared by every Fusion entry point.
@@ -43,6 +49,74 @@ 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_CAPABILITY_VALUES = Object.freeze(['reason', 'inspect', 'research'] as const);
+export type FusionCapability = (typeof FUSION_CAPABILITY_VALUES)[number];
+
+/** No-tools capability for reason candidates, evaluator, repair, and merger. */
+export const FUSION_NO_TOOLS_CAPABILITY: FusionCapability = 'reason';
+/** Legacy default retained for old type imports only. New workflows never default. */
+export const FUSION_BRAINSTORM_DEFAULT_CAPABILITY: FusionCapability = 'inspect';
+/** @deprecated New v5 workflows have no caller capability default. */
+export const FUSION_DEFAULT_CAPABILITY: FusionCapability = FUSION_BRAINSTORM_DEFAULT_CAPABILITY;
+
+export const FUSION_WEB_FETCH_TOOL_NAME = 'fusion_web_fetch' as const;
+export const FUSION_INSPECT_TOOLS = Object.freeze(['read', 'grep', 'find', 'ls'] as const);
+export const FUSION_RESEARCH_TOOLS = Object.freeze([
+  'read',
+  'grep',
+  'find',
+  'ls',
+  FUSION_WEB_FETCH_TOOL_NAME,
+] as const);
+
+/**
+ * Workflow identities sharing one orchestrator, one context projection, one
+ * evaluation schema, and one artifact store. A workflow selects stage framing and
+ * capability policy only; it never changes the canonical input schema.
+ */
+export const FUSION_WORKFLOW_IDS = Object.freeze([
+  'reason',
+  'investigate',
+  'research',
+  'validate',
+] as const);
+export type FusionWorkflowId = (typeof FUSION_WORKFLOW_IDS)[number];
+export const FUSION_PUBLIC_WORKFLOW_NAMES = Object.freeze([
+  'fusion_reason',
+  'fusion_investigate',
+  'fusion_research',
+  'fusion_validate',
+] as const);
+export type FusionPublicWorkflowName = (typeof FUSION_PUBLIC_WORKFLOW_NAMES)[number];
+export type FusionContextKind = 'session_projection' | 'clean_task';
+
+/**
+ * The single capability the validate workflow ever runs candidates with.
+ *
+ * Deliberately separate from the caller-selectable brainstorm default. Although
+ * both workflows currently give candidates read-only inspection, validation pins
+ * that capability as fixed policy rather than exposing a caller override.
+ */
+export const FUSION_VALIDATE_CAPABILITY: FusionCapability = 'inspect';
+
+export const FUSION_FORBIDDEN_TOOLS = Object.freeze([
+  'bash',
+  'edit',
+  'write',
+  'fusion_brainstorm',
+  'fusion_reason',
+  'fusion_investigate',
+  'fusion_research',
+  'fusion_validate',
+  'bg_delegate',
+  'bg_result',
+  'bg_run',
+  'bg_kill',
+  'bg_status',
+  'bg_logs',
+  'bg_run_pi_attested',
+] as const);
+
 /**
  * Prompt-expansion stages guarded by deterministic size accounting. `evaluation`
  * and `evaluation_repair` share the evaluator model but render different prompts.
@@ -261,15 +335,73 @@ export interface FusionConversationProjectionV4 {
 
 export type FusionConversationProjectionV3 = FusionConversationProjectionV4;
 
-export interface FusionCanonicalInputV4 {
+export interface FusionDeclaredSourceV1 {
+  url: string;
+  canonical_url: string;
+  purpose: string;
+  sha256: string;
+}
+
+export interface FusionCleanTaskContextV1 {
+  kind: 'clean_task';
+  policy_id: 'fusion-clean-task-v1';
+  declared_sources: readonly FusionDeclaredSourceV1[];
+}
+
+export interface FusionSessionProjectionContextV1 {
+  kind: 'session_projection';
+  policy_id: 'fusion-session-projection-v1';
+  system_prompt: string;
+  conversation_projection: FusionConversationProjectionV4;
+}
+
+export interface FusionCanonicalInputV5Base {
   schema_version: typeof FUSION_INPUT_SCHEMA_VERSION;
+  workflow?: FusionWorkflowId | undefined;
+  cwd: string;
+  request: FusionCanonicalRequestV3;
+}
+
+export interface FusionSessionProjectionCanonicalInputV5 extends FusionCanonicalInputV5Base {
+  workflow?: FusionWorkflowId | undefined;
+  /** @deprecated v4 readability alias. Present only for session-projection inputs at runtime. */
+  system_prompt: string;
+  /** @deprecated v4 readability alias. Present only for session-projection inputs at runtime. */
+  conversation_projection: FusionConversationProjectionV4;
+  context?: FusionSessionProjectionContextV1 | undefined;
+}
+
+export interface FusionCleanTaskCanonicalInputV5 extends FusionCanonicalInputV5Base {
+  workflow: Exclude<FusionWorkflowId, 'reason'>;
+  context: FusionCleanTaskContextV1;
+}
+
+export type FusionCanonicalInputV5 =
+  | FusionSessionProjectionCanonicalInputV5
+  | FusionCleanTaskCanonicalInputV5;
+
+/** Legacy v4 shape retained for frozen golden fixtures/readability only. */
+export interface FusionCanonicalInputV4 {
+  schema_version: typeof FUSION_LEGACY_INPUT_SCHEMA_VERSION;
   cwd: string;
   system_prompt: string;
   request: FusionCanonicalRequestV3;
   conversation_projection: FusionConversationProjectionV4;
 }
 
-export type FusionCanonicalInputV3 = FusionCanonicalInputV4;
+export type FusionCanonicalInputV3 = FusionCanonicalInputV5;
+
+export interface FusionSourcePolicyV1 {
+  schema_version: typeof FUSION_SOURCE_POLICY_SCHEMA_VERSION;
+  workflow: 'research';
+  cwd: string;
+  sources: readonly FusionDeclaredSourceV1[];
+  root_sha256: string;
+}
+
+export interface FusionSourcePolicyArtifactRef extends FusionArtifactRef {
+  root_sha256: string;
+}
 
 export interface CandidateAssessment {
   candidate_id: FusionCandidateId;
@@ -302,12 +434,56 @@ export interface FusionSynthesisPlan {
   must_avoid: readonly string[];
 }
 
+export type FusionValidationSeverity = 'critical' | 'high' | 'minor';
+
+export interface FusionValidationFindingRecord {
+  id: string;
+  candidate_id: FusionCandidateId;
+  severity: FusionValidationSeverity;
+  location: string;
+  evidence: string;
+  impact: string;
+  summary: string;
+}
+
+export interface FusionValidationFindingDecision {
+  source_id: string;
+  disposition: 'include' | 'exclude';
+  rationale: string;
+  group_id?: string | undefined;
+}
+
+export interface FusionValidationFindingGroup {
+  group_id: string;
+  source_ids: readonly string[];
+  severity: FusionValidationSeverity;
+  location: string;
+  evidence: string;
+  impact: string;
+  summary: string;
+  rationale: string;
+}
+
+export interface FusionValidationFindingAccounting {
+  findings: readonly FusionValidationFindingRecord[];
+  decisions: readonly FusionValidationFindingDecision[];
+  groups: readonly FusionValidationFindingGroup[];
+}
+
+export interface FusionValidationCandidateReportV1 {
+  schema_version: typeof FUSION_VALIDATE_CANDIDATE_SCHEMA_VERSION;
+  findings: readonly Omit<FusionValidationFindingRecord, 'id' | 'candidate_id'>[];
+  verified: readonly string[];
+  limitations: 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;
+  validation_accounting?: FusionValidationFindingAccounting | undefined;
 }
 
 /** Exact Pi usage contract used at the child, artifact, and host tool-result boundaries. */
@@ -376,8 +552,11 @@ export interface FusionResultBudgetDetails {
 export interface FusionResultDetails {
   schema_version: typeof FUSION_RESULT_SCHEMA_VERSION;
   run_id: string;
+  workflow: FusionWorkflowId;
   source: FusionSource;
   status: 'completed';
+  context: { kind: FusionContextKind; policy_id: string };
+  tool_policy: { candidate_tools: readonly string[]; evaluation_tools: readonly []; merge_tools: readonly [] };
   artifact_dir: string;
   models: {
     candidates: readonly [string, string, string];
@@ -541,6 +720,39 @@ export interface FusionChildUsage extends FusionUsage {
   qualifiedId: string;
 }
 
+export type FusionToolCallLogStatus = 'ok' | 'error';
+
+export interface FusionToolCallLogRecord {
+  schema_version: typeof FUSION_TOOL_CALL_LOG_SCHEMA_VERSION;
+  ordinal: number;
+  tool_name: string;
+  arguments_sha256: string;
+  arguments_bytes: number;
+  result_bytes: number;
+  result_sha256: string;
+  status: FusionToolCallLogStatus;
+  duration_ms: number;
+  url?: string | undefined;
+  /** SHA-256 of a rejected attempted fetch URL; raw rejected URLs are never persisted. */
+  rejected_url_sha256?: string | undefined;
+  final_url?: string | undefined;
+  http_status?: number | undefined;
+  response_bytes?: number | undefined;
+  content_sha256?: string | undefined;
+}
+
+export interface FusionToolCallLogSummary {
+  count: number;
+  total_result_bytes: number;
+  trace_complete: boolean;
+}
+
+export interface FusionToolCallTrace {
+  bytes: Buffer;
+  records: readonly FusionToolCallLogRecord[];
+  summary: FusionToolCallLogSummary;
+}
+
 export interface FusionChildRunResult {
   stage: FusionStage;
   slot?: 1 | 2 | 3;
@@ -554,6 +766,7 @@ export interface FusionChildRunResult {
   stderr: Buffer;
   exitCode: number;
   signal: NodeJS.Signals | null;
+  toolCallTrace?: FusionToolCallTrace;
 }
 
 export interface FusionAttemptArtifactRecord {
@@ -566,6 +779,8 @@ export interface FusionAttemptArtifactRecord {
   stderr_path?: string;
   response_path?: string;
   partial_response_path?: string;
+  tool_calls_path?: string;
+  tool_calls?: FusionToolCallLogSummary;
   provider?: string;
   model?: string;
   qualifiedId?: string;
@@ -582,6 +797,7 @@ export interface FusionArtifactRef {
 export interface FusionArtifactManifest {
   schema_version: typeof FUSION_MANIFEST_SCHEMA_VERSION;
   run_id: string;
+  workflow: FusionWorkflowId;
   source: FusionSource;
   state: FusionState;
   created_at: string;
@@ -594,6 +810,13 @@ export interface FusionArtifactManifest {
     merger: string;
     thinking_level: string;
   };
+  capabilities: {
+    candidate: FusionCapability;
+    evaluation: FusionCapability;
+    merge: FusionCapability;
+  };
+  context: { kind: FusionContextKind; policy_id: string; ledger_artifact?: string; source_policy_artifact?: string };
+  tool_policy: { candidate_tools: readonly string[]; evaluation_tools: readonly []; merge_tools: readonly [] };
   usage: FusionUsage;
   attempts: readonly FusionAttemptArtifactRecord[];
   artifacts: Readonly<Record<string, FusionArtifactRef>>;
@@ -674,6 +897,10 @@ export interface FusionBudgetEmptyRequestVerdict {
 
 export interface FusionBudgetPlanV1 {
   schema_version: typeof FUSION_BUDGET_PLAN_SCHEMA_VERSION;
+  workflow: FusionWorkflowId;
+  context: { kind: FusionContextKind; policy_id: string };
+  fixed_candidate_policy: { capability: FusionCapability; tools: readonly string[] };
+  tool_policy: { candidate_tools: readonly string[]; evaluation_tools: readonly []; merge_tools: readonly [] };
   policy: FusionBudgetPolicyDescriptor;
   routes: readonly FusionRouteCapacity[];
   stages: readonly FusionStageBudgetPlanEntry[];