pi-background-tasks 0.7.6 → 0.9.0

package/src/core/delegate/types.ts

@@ -0,0 +1,304 @@
+import type { Usage } from '@earendil-works/pi-ai';
+import type {
+  TokenBudgetByteClassBreakdown,
+  TokenBudgetDominantByteClass,
+  TokenBudgetFamily,
+  TokenBudgetRateSource,
+} from '../context/token-budget.js';
+import type {
+  ContextProjectionMapEntry,
+  OmittedEventRecord,
+  ProjectionAccounting,
+  ProjectionEntry,
+} from '../context/visible-conversation-v2.js';
+
+export const DELEGATE_SEED_SCHEMA_VERSION = 'pi-background-tasks.delegate-seed.v1' as const;
+export const DELEGATE_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.delegate-ledger.v1' as const;
+export const DELEGATE_RESULT_PACKAGE_SCHEMA_VERSION =
+  'pi-background-tasks.delegate-result.v1' as const;
+export const DELEGATE_RECEIPT_SCHEMA_VERSION = 'pi-background-tasks.delegate-receipt.v1' as const;
+export const DELEGATE_BUDGET_PLAN_SCHEMA_VERSION =
+  'pi-background-tasks.delegate-budget-plan.v2' as const;
+export const DELEGATE_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.delegate-manifest.v1' as const;
+
+/**
+ * Delegate's own context policy id. It shares the frozen
+ * `visible-conversation-ledger-v2` transform with Fusion but is a distinct
+ * consumer identity, so a delegate artifact can never be mistaken for a Fusion
+ * artifact and neither can claim the other's provenance.
+ */
+export const DELEGATE_CONTEXT_POLICY_ID = 'delegate-inspect-v1';
+export const DELEGATE_BRANCH_FILTER_ID = 'exclude-active-delegate-batch-v1';
+export const DELEGATE_TOOL_NAME = 'bg_delegate';
+export const DELEGATE_RESULT_TOOL_NAME = 'bg_result';
+
+export const DELEGATE_CAPABILITIES = ['inspect'] as const;
+export type DelegateCapability = (typeof DELEGATE_CAPABILITIES)[number];
+
+export const DELEGATE_AUTO_DELIVER_MODES = ['never', 'when_small', 'always'] as const;
+export type DelegateAutoDeliverMode = (typeof DELEGATE_AUTO_DELIVER_MODES)[number];
+
+export const DELEGATE_DELIVERY_MODES = ['inline', 'artifact'] as const;
+export type DelegateDeliveryMode = (typeof DELEGATE_DELIVERY_MODES)[number];
+
+export interface DelegateRoute {
+  provider: string;
+  model: string;
+}
+
+export interface DelegatePinnedRoute extends DelegateRoute {
+  qualified_id: string;
+  context_window_tokens: number;
+  thinking_level: string;
+  /** Whether the route came from the parent's current model or an explicit argument. */
+  origin: 'parent_current' | 'explicit';
+}
+
+export interface DelegateBudgetRouteSource {
+  family: TokenBudgetFamily;
+  rate_source: TokenBudgetRateSource;
+}
+
+export interface DelegateContextPolicyDescriptor {
+  id: typeof DELEGATE_CONTEXT_POLICY_ID;
+  transform: 'visible-conversation-ledger-v2';
+  version: 1;
+  receipt_format: 'omitted_activity.v2';
+  user_text: 'verbatim';
+  assistant_text: 'verbatim';
+  assistant_thinking: 'ledger_only';
+  tool_call_arguments: 'ledger_only';
+  tool_results: 'ledger_only';
+  tool_payload_preview_bytes: 0;
+  images: 'marker_or_ledger_only';
+  unknown_block_behavior: 'error';
+}
+
+export interface DelegateBranchFilterDescriptor {
+  id: typeof DELEGATE_BRANCH_FILTER_ID;
+  tool_name: typeof DELEGATE_TOOL_NAME;
+  tool_call_id: string | null;
+  active_tool_call_leaf_excluded: boolean;
+}
+
+export interface DelegateConversationProjection {
+  policy: DelegateContextPolicyDescriptor;
+  branch_filter: DelegateBranchFilterDescriptor;
+  entries: readonly ProjectionEntry[];
+  accounting: ProjectionAccounting;
+}
+
+export interface DelegateLedgerV1 {
+  schema_version: typeof DELEGATE_LEDGER_SCHEMA_VERSION;
+  policy_id: typeof DELEGATE_CONTEXT_POLICY_ID;
+  transform: 'visible-conversation-ledger-v2';
+  entries: readonly OmittedEventRecord[];
+  projection_map: readonly ContextProjectionMapEntry[];
+  root_sha256: string;
+}
+
+export interface DelegateTaskDirective {
+  /** Verbatim operator/agent prompt. Always authoritative over projected history. */
+  text: string;
+  sha256: string;
+  authority: 'explicit_text';
+}
+
+export interface DelegateSeedV1 {
+  schema_version: typeof DELEGATE_SEED_SCHEMA_VERSION;
+  task_id: string;
+  launch_nonce: string;
+  cwd: string;
+  capability: DelegateCapability;
+  route: DelegatePinnedRoute;
+  parent_system_prompt: string;
+  parent_leaf_id: string | null;
+  directive: DelegateTaskDirective;
+  conversation_projection: DelegateConversationProjection;
+  limits: DelegateLimits;
+}
+
+export interface DelegateLimits {
+  max_turns: number;
+  max_tool_calls: number;
+  timeout_seconds: number;
+  /** Per-tool-result transcript cap; larger results spill to hashed artifacts. */
+  max_tool_result_bytes: number;
+  /** Cumulative spilled+inline tool output across the whole run. */
+  max_total_tool_output_bytes: number;
+  /** Cap on the child's captured final answer. */
+  max_answer_bytes: number;
+  /** Usable input tokens for the pinned route after reserves. */
+  allowed_input_tokens: number;
+}
+
+export interface DelegateAnswerBlock {
+  kind: 'text';
+  byte_length: number;
+  sha256: string;
+  data_base64: string;
+}
+
+export interface DelegateRouteAttestation {
+  provider: string;
+  model: string;
+  stop_reason: string;
+}
+
+/**
+ * Usage that is explicitly absent is reported as absent.
+ *
+ * A child that never produced a usable usage record must not be reported as
+ * having cost zero, so the status is carried alongside the value.
+ */
+export type DelegateUsageReport =
+  | { status: 'observed'; usage: Usage }
+  | { status: 'unavailable'; reason: string };
+
+/**
+ * The single atomically-committed answer data plane.
+ *
+ * The child writes exactly this document to a temporary file, fsyncs it, and
+ * renames it into place. The rename is the commit point: a package that exists
+ * under its final name is complete, and one that does not exist means the child
+ * produced no accepted answer. There is no second channel to reconcile.
+ */
+export interface DelegateResultPackageV1 {
+  schema_version: typeof DELEGATE_RESULT_PACKAGE_SCHEMA_VERSION;
+  task_id: string;
+  launch_nonce: string;
+  seed_sha256: string;
+  directive_sha256: string;
+  route: DelegateRoute;
+  route_attestations: readonly DelegateRouteAttestation[];
+  stop_reason: string;
+  turns: number;
+  tool_calls: number;
+  usage: DelegateUsageReport;
+  answer: {
+    encoding: 'utf-8';
+    byte_length: number;
+    sha256: string;
+    blocks: readonly DelegateAnswerBlock[];
+  };
+  spilled_artifacts: readonly DelegateSpillReceipt[];
+}
+
+export interface DelegateSpillReceipt {
+  schema_version: typeof DELEGATE_RECEIPT_SCHEMA_VERSION;
+  artifact: string;
+  tool_name: string;
+  tool_call_id: string;
+  turn_sequence: number;
+  source_call_index: number;
+  byte_length: number;
+  sha256: string;
+}
+
+export const DELEGATE_ERROR_CODES = [
+  // Admission failures. No child process exists in these states.
+  'delegate_hook_contract_unsupported',
+  'delegate_isolation_unsupported',
+  'route_unresolved',
+  'route_capacity_unknown',
+  'seed_projection_failed',
+  'seed_budget_exceeded',
+  'seed_persist_failed',
+  'invalid_arguments',
+  // Launch and execution.
+  'child_spawn_failed',
+  'child_startup_failed',
+  'child_timeout',
+  'child_cancelled',
+  'child_turn_limit',
+  'child_tool_call_limit',
+  'child_exited_without_commit',
+  // Budget, split by which budget was exhausted.
+  'provider_context_budget_exhausted',
+  'aggregate_tool_output_cap',
+  'child_model_output_limit',
+  'child_capture_limit',
+  // Integrity.
+  'child_result_invalid',
+  'child_result_encoding_invalid',
+  'route_attestation_missing',
+  'route_mismatch',
+  'seed_hash_mismatch',
+  'answer_hash_mismatch',
+  'artifact_spill_failed',
+  'artifact_read_failed',
+  'artifact_error',
+  // Retrieval states and outcomes.
+  'result_not_ready',
+  'result_unavailable',
+  'result_too_large_for_inline',
+  'task_unknown',
+] as const;
+
+export type DelegateErrorCode = (typeof DELEGATE_ERROR_CODES)[number];
+
+export interface DelegateBudgetErrorDetail {
+  measurement_kind: 'launch_admission' | 'runtime_context';
+  measured_utf8_bytes: number;
+  measured_input_tokens_upper_bound: number;
+  allowed_input_tokens: number;
+  rate_source: TokenBudgetRateSource;
+  backed: boolean;
+  dominant_byte_class: TokenBudgetDominantByteClass;
+  byte_class_breakdown: TokenBudgetByteClassBreakdown;
+}
+
+export interface DelegateErrorDetails {
+  code: DelegateErrorCode;
+  /** True only when an OS process was actually created. Admission failures are false. */
+  childCreated?: boolean;
+  taskId?: string;
+  artifactDir?: string;
+  budget?: DelegateBudgetErrorDetail;
+  /** What is preserved on disk despite the failure. */
+  preserved?: readonly string[];
+  /** Concrete operator actions. */
+  remediation?: readonly string[];
+}
+
+/**
+ * Typed delegate failure.
+ *
+ * Every instance states what happened, what was preserved, and what the operator
+ * can do. There is no untyped delegate failure path.
+ */
+export class DelegateError extends Error {
+  readonly code: DelegateErrorCode;
+  readonly childCreated: boolean;
+  readonly taskId: string | undefined;
+  readonly artifactDir: string | undefined;
+  readonly budget: DelegateBudgetErrorDetail | undefined;
+  readonly preserved: readonly string[];
+  readonly remediation: readonly string[];
+
+  constructor(message: string, details: DelegateErrorDetails) {
+    super(message);
+    this.name = 'DelegateError';
+    this.code = details.code;
+    this.childCreated = details.childCreated ?? false;
+    this.taskId = details.taskId;
+    this.artifactDir = details.artifactDir;
+    this.budget = details.budget;
+    this.preserved = details.preserved ?? [];
+    this.remediation = details.remediation ?? [];
+  }
+
+  /** Operator-facing rendering: cause, preserved evidence, and next action. */
+  describe(): string {
+    const lines = [`[${this.code}] ${this.message}`];
+    lines.push(`Child process created: ${this.childCreated ? 'yes' : 'no'}`);
+    if (this.artifactDir !== undefined) lines.push(`Artifacts: ${this.artifactDir}`);
+    lines.push(
+      this.preserved.length > 0
+        ? `Preserved: ${this.preserved.join(', ')}`
+        : 'Preserved: nothing was written for this failure',
+    );
+    if (this.remediation.length > 0) lines.push(`Remediation: ${this.remediation.join(' ')}`);
+    return lines.join('\n');
+  }
+}

package/src/core/fusion/artifacts.ts

@@ -13,7 +13,9 @@ import {
   type FusionArtifactRef,
   type FusionAttemptArtifactRecord,
   type FusionBudgetPlanV1,
+  type FusionCalibrationViolation,
   type FusionCandidateId,
+  type FusionCapability,
   type FusionContextOmissionLedgerV2,
   type FusionChildRunResult,
   type FusionModelConfigV1,
@@ -22,14 +24,21 @@ import {
   type FusionState,
   type FusionTerminalState,
   type FusionUsage,
+  type FusionWorkflowId,
   type ResolvedFusionModels,
 } from './types.js';
+import { FUSION_BRAINSTORM_WORKFLOW, type FusionWorkflowProfile } from './workflows.js';
 
-const RUN_ID_PATTERN = /^f[0-9a-f]{32}$/;
+/**
+ * Run ids are prefixed by workflow so an artifact directory is self-describing.
+ * The prefix set is closed: an unknown prefix must fail rather than be accepted.
+ */
+const RUN_ID_PATTERN = /^[fv][0-9a-f]{32}$/;
 
 interface MutableFusionArtifactManifest {
   schema_version: typeof FUSION_MANIFEST_SCHEMA_VERSION;
   run_id: string;
+  workflow: FusionWorkflowId;
   source: FusionSource;
   state: FusionState;
   created_at: string;
@@ -42,6 +51,11 @@ interface MutableFusionArtifactManifest {
     merger: string;
     thinking_level: string;
   };
+  capabilities: {
+    candidate: FusionCapability;
+    evaluation: FusionCapability;
+    merge: FusionCapability;
+  };
   usage: FusionUsage;
   attempts: FusionAttemptArtifactRecord[];
   artifacts: Record<string, FusionArtifactRef>;
@@ -53,9 +67,15 @@ export interface CreateFusionArtifactStoreOptions {
   cwd: string;
   sessionId?: string | undefined;
   runId?: string | undefined;
+  profile?: FusionWorkflowProfile | undefined;
   source: FusionSource;
   config: FusionModelConfigV1;
   models: ResolvedFusionModels;
+  capabilities?: {
+    candidate: FusionCapability;
+    evaluation: FusionCapability;
+    merge: FusionCapability;
+  };
   now?: () => Date;
 }
 
@@ -82,8 +102,8 @@ export interface RecordFusionFailedAttemptInput {
   usage?: FusionUsage;
 }
 
-function makeRunId(): string {
-  return `f${randomBytes(16).toString('hex')}`;
+function makeRunId(profile: FusionWorkflowProfile): string {
+  return `${profile.runIdPrefix}${randomBytes(16).toString('hex')}`;
 }
 
 function modelsForManifest(models: ResolvedFusionModels): MutableFusionArtifactManifest['models'] {
@@ -148,6 +168,7 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
   const out: FusionArtifactManifest = {
     schema_version: manifest.schema_version,
     run_id: manifest.run_id,
+    workflow: manifest.workflow,
     source: manifest.source,
     state: manifest.state,
     created_at: manifest.created_at,
@@ -155,6 +176,7 @@ function publicManifest(manifest: MutableFusionArtifactManifest): FusionArtifact
     cwd: manifest.cwd,
     config: manifest.config,
     models: manifest.models,
+    capabilities: manifest.capabilities,
     usage: cloneFusionUsage(manifest.usage),
     attempts: [...manifest.attempts],
     artifacts: { ...manifest.artifacts },
@@ -178,6 +200,10 @@ function responseName(prefix: string, kind: 'md' | 'txt'): string {
   return `${prefix}.response.${kind}`;
 }
 
+function calibrationViolationName(prefix: string): string {
+  return `${prefix}.calibration-violation.json`;
+}
+
 export class FusionArtifactStore {
   private readonly runDirAbs: string;
   private readonly runDirDisplay: string;
@@ -198,8 +224,14 @@ export class FusionArtifactStore {
   }
 
   static async create(options: CreateFusionArtifactStoreOptions): Promise<FusionArtifactStore> {
-    const runId = options.runId ?? makeRunId();
+    const profile = options.profile ?? FUSION_BRAINSTORM_WORKFLOW;
+    const runId = options.runId ?? makeRunId(profile);
     if (!RUN_ID_PATTERN.test(runId)) throw errorForArtifact(`invalid fusion run id: ${runId}`);
+    if (!runId.startsWith(profile.runIdPrefix)) {
+      throw errorForArtifact(
+        `fusion run id ${runId} does not carry the ${profile.id} workflow prefix ${profile.runIdPrefix}`,
+      );
+    }
     const sessionSegment = sanitizePathSegment(
       options.sessionId ?? `session-${String(process.pid)}`,
     );
@@ -212,6 +244,7 @@ export class FusionArtifactStore {
     const manifest: MutableFusionArtifactManifest = {
       schema_version: FUSION_MANIFEST_SCHEMA_VERSION,
       run_id: runId,
+      workflow: profile.id,
       source: options.source,
       state: 'initializing',
       created_at: timestamp,
@@ -219,6 +252,11 @@ export class FusionArtifactStore {
       cwd: options.cwd,
       config: options.config,
       models: modelsForManifest(options.models),
+      capabilities: options.capabilities ?? {
+        candidate: 'reason',
+        evaluation: 'reason',
+        merge: 'reason',
+      },
       usage: cloneFusionUsage(EMPTY_FUSION_USAGE),
       attempts: [],
       artifacts: {},
@@ -245,6 +283,10 @@ export class FusionArtifactStore {
     return this.runDirAbs;
   }
 
+  childToolCallLogPath(stage: FusionStage, slot: 1 | 2 | 3 | undefined, attempt: number): string {
+    return this.artifactPath(`${attemptPrefix(stage, slot, attempt)}.tool-calls.jsonl`);
+  }
+
   snapshot(): FusionArtifactManifest {
     return publicManifest(this.manifest);
   }
@@ -333,6 +375,10 @@ export class FusionArtifactStore {
       responseName(prefix, input.responseKind),
       input.result.text,
     );
+    const toolCallsRef =
+      input.result.toolCallTrace === undefined
+        ? undefined
+        : await this.writeArtifact(`${prefix}.tool-calls.jsonl`, input.result.toolCallTrace.bytes);
     await this.updateManifest((manifest) => {
       const record: FusionAttemptArtifactRecord = {
         stage: input.result.stage,
@@ -347,11 +393,25 @@ export class FusionArtifactStore {
         qualifiedId: input.result.qualifiedId,
         usage: cloneFusionUsage(input.result.usage),
       };
+      if (toolCallsRef !== undefined && input.result.toolCallTrace !== undefined) {
+        record.tool_calls_path = toolCallsRef.path;
+        record.tool_calls = { ...input.result.toolCallTrace.summary };
+      }
       if (input.result.slot !== undefined) record.slot = input.result.slot;
       manifest.attempts.push(record);
     });
   }
 
+  async recordCalibrationViolation(input: {
+    stage: FusionStage;
+    slot?: 1 | 2 | 3;
+    attempt: number;
+    violation: FusionCalibrationViolation;
+  }): Promise<FusionArtifactRef> {
+    const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
+    return this.writeArtifact(calibrationViolationName(prefix), `${canonicalJson(input.violation)}\n`);
+  }
+
   async recordFailedAttempt(input: RecordFusionFailedAttemptInput): Promise<void> {
     const prefix = attemptPrefix(input.stage, input.slot, input.attempt);
     const promptRef = await this.writeArtifact(`${prefix}.prompt.txt`, input.prompt);