pi-background-tasks 2.4.2 → 2.6.0

package/dist/src/core/delegate/seed.js

@@ -0,0 +1,334 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from '../canonical-json.js';
+import { UnsupportedConversationBlockError, projectVisibleConversationV2, } from '../context/visible-conversation-v2.js';
+import { snapshotParentConversation, } from '../context/parent-snapshot.js';
+import { DELEGATE_BRANCH_FILTER_ID, DELEGATE_CONTEXT_POLICY_ID, DELEGATE_LEDGER_SCHEMA_VERSION, DELEGATE_SEED_SCHEMA_VERSION, DELEGATE_TOOL_NAME, DelegateError, } from './types.js';
+function sha256Text(value) {
+    return createHash('sha256').update(Buffer.from(value, 'utf8')).digest('hex');
+}
+function policyDescriptor() {
+    return {
+        id: 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',
+    };
+}
+/**
+ * Seal the shared transform under delegate's own envelope.
+ *
+ * Delegate never imports Fusion's canonical-input builder and never emits
+ * `fusion-input.v4`. The ledger root commits only to ledger rows, so the two
+ * consumers can seal identical bodies without either affecting the other.
+ */
+function sealDelegateProjection(projected, branchFilter) {
+    return {
+        projection: {
+            policy: policyDescriptor(),
+            branch_filter: branchFilter,
+            entries: projected.entries,
+            accounting: projected.accounting,
+        },
+        ledger: {
+            schema_version: DELEGATE_LEDGER_SCHEMA_VERSION,
+            policy_id: DELEGATE_CONTEXT_POLICY_ID,
+            transform: 'visible-conversation-ledger-v2',
+            entries: projected.ledger.entries,
+            projection_map: projected.ledger.projection_map,
+            root_sha256: projected.ledger.root_sha256,
+        },
+    };
+}
+/**
+ * Build the frozen delegate seed.
+ *
+ * The projection excludes the assistant message carrying the in-flight
+ * `bg_delegate` call. That message is excluded as a whole, so when several
+ * `bg_delegate` calls share one assistant message every sibling call is excluded
+ * for every child: two delegates launched together receive identical projected
+ * history, and neither can observe the other's arguments.
+ *
+ * The directive is authoritative; projected history is supporting, untrusted
+ * context. That relationship is stated to the child explicitly in its system
+ * prompt, and recorded structurally here as `authority: 'explicit_text'`.
+ */
+export function buildDelegateSeed(ctx, options) {
+    const directiveText = options.directive;
+    if (directiveText.trim().length === 0) {
+        throw new DelegateError('bg_delegate prompt must not be blank', {
+            code: 'invalid_arguments',
+            childCreated: false,
+            remediation: ['Provide a non-blank prompt describing what the delegate should investigate.'],
+        });
+    }
+    const snapshotOptions = {
+        toolName: DELEGATE_TOOL_NAME,
+        excludeActiveToolCallLeaf: true,
+    };
+    if (options.toolCallId !== undefined)
+        snapshotOptions.toolCallId = options.toolCallId;
+    let snapshot;
+    let projected;
+    try {
+        snapshot = snapshotParentConversation(ctx, snapshotOptions);
+        projected = projectVisibleConversationV2(snapshot.messages);
+    }
+    catch (error) {
+        if (error instanceof UnsupportedConversationBlockError) {
+            throw new DelegateError(`bg_delegate could not project the parent conversation: ${error.message}`, {
+                code: 'seed_projection_failed',
+                childCreated: false,
+                remediation: [
+                    'The parent conversation contains a block type this package version does not know how to project.',
+                    'Nothing was dropped or guessed and no child was created. Report the block type so the transform can be versioned.',
+                ],
+            });
+        }
+        throw error;
+    }
+    const branchFilter = {
+        id: DELEGATE_BRANCH_FILTER_ID,
+        tool_name: DELEGATE_TOOL_NAME,
+        tool_call_id: options.toolCallId ?? null,
+        active_tool_call_leaf_excluded: snapshot.activeToolCallLeafExcluded,
+    };
+    const sealed = sealDelegateProjection(projected, branchFilter);
+    const directive = {
+        text: directiveText,
+        sha256: sha256Text(directiveText),
+        authority: 'explicit_text',
+    };
+    const seed = {
+        schema_version: DELEGATE_SEED_SCHEMA_VERSION,
+        task_id: options.taskId,
+        launch_nonce: options.launchNonce,
+        cwd: ctx.cwd,
+        capability: options.capability,
+        extension_mode: options.extensionMode,
+        route: options.route,
+        parent_system_prompt: ctx.getSystemPrompt(),
+        parent_leaf_id: snapshot.leafId,
+        directive,
+        conversation_projection: sealed.projection,
+        limits: options.limits,
+    };
+    const serialized = canonicalJson(seed);
+    return { seed, serialized, sha256: sha256Text(serialized), ledger: sealed.ledger };
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/**
+ * Receive-side seed validation performed inside the child before its first model
+ * call. A seed that does not match its declared length, hash, schema, task id,
+ * and launch nonce is a loud refusal, never a best-effort continue.
+ */
+export function verifyDelegateSeedBytes(raw, expected) {
+    const actual = sha256Text(raw);
+    if (actual !== expected.sha256) {
+        throw new DelegateError(`delegate seed hash mismatch: expected ${expected.sha256}, received ${actual}`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId: expected.taskId,
+            remediation: ['The seed bytes delivered to the child differ from the persisted seed.'],
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new DelegateError(`delegate seed is not valid JSON: ${error instanceof Error ? error.message : String(error)}`, { code: 'seed_hash_mismatch', childCreated: true, taskId: expected.taskId });
+    }
+    if (!isRecord(parsed)) {
+        throw new DelegateError('delegate seed must be a JSON object', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId: expected.taskId,
+        });
+    }
+    if (parsed['schema_version'] !== DELEGATE_SEED_SCHEMA_VERSION) {
+        throw new DelegateError(`delegate seed schema_version must be ${DELEGATE_SEED_SCHEMA_VERSION}`, { code: 'seed_hash_mismatch', childCreated: true, taskId: expected.taskId });
+    }
+    if (parsed['task_id'] !== expected.taskId || parsed['launch_nonce'] !== expected.launchNonce) {
+        throw new DelegateError('delegate seed task identity does not match this child', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId: expected.taskId,
+        });
+    }
+    // The hash pins the exact bytes; this rebuild pins the shape the child is
+    // allowed to act on. Every field the child reads is validated and copied
+    // explicitly, so a structurally malformed seed cannot reach the agent loop by
+    // way of an unchecked assertion.
+    return rebuildSeed(parsed, expected.taskId);
+}
+function requireString(record, key, taskId) {
+    const value = record[key];
+    if (typeof value !== 'string') {
+        throw new DelegateError(`delegate seed field ${key} must be a string`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    return value;
+}
+function requireRecord(record, key, taskId) {
+    const value = record[key];
+    if (!isRecord(value)) {
+        throw new DelegateError(`delegate seed field ${key} must be an object`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    return value;
+}
+function requireNonNegativeInteger(record, key, taskId) {
+    const value = record[key];
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {
+        throw new DelegateError(`delegate seed field ${key} must be a non-negative safe integer`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    return value;
+}
+/** Explicit, field-by-field reconstruction of the seed fields the child consumes. */
+function rebuildSeed(record, taskId) {
+    const capability = requireString(record, 'capability', taskId);
+    if (capability !== 'inspect') {
+        throw new DelegateError(`delegate seed capability ${capability} is not supported`, {
+            code: 'delegate_isolation_unsupported',
+            childCreated: true,
+            taskId,
+        });
+    }
+    const extensionMode = requireString(record, 'extension_mode', taskId);
+    if (extensionMode !== 'isolated' && extensionMode !== 'ambient') {
+        throw new DelegateError(`delegate seed extension mode ${extensionMode} is not recognised`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    const routeRecord = requireRecord(record, 'route', taskId);
+    const routeOrigin = requireString(routeRecord, 'origin', taskId);
+    if (routeOrigin !== 'parent_current' && routeOrigin !== 'explicit') {
+        throw new DelegateError(`delegate seed route origin ${routeOrigin} is not recognised`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    const route = {
+        provider: requireString(routeRecord, 'provider', taskId),
+        model: requireString(routeRecord, 'model', taskId),
+        qualified_id: requireString(routeRecord, 'qualified_id', taskId),
+        context_window_tokens: requireNonNegativeInteger(routeRecord, 'context_window_tokens', taskId),
+        thinking_level: requireString(routeRecord, 'thinking_level', taskId),
+        origin: routeOrigin,
+    };
+    const limitsRecord = requireRecord(record, 'limits', taskId);
+    const limits = {
+        max_turns: requireNonNegativeInteger(limitsRecord, 'max_turns', taskId),
+        max_tool_calls: requireNonNegativeInteger(limitsRecord, 'max_tool_calls', taskId),
+        timeout_seconds: requireNonNegativeInteger(limitsRecord, 'timeout_seconds', taskId),
+        max_tool_result_bytes: requireNonNegativeInteger(limitsRecord, 'max_tool_result_bytes', taskId),
+        max_total_tool_output_bytes: requireNonNegativeInteger(limitsRecord, 'max_total_tool_output_bytes', taskId),
+        max_answer_bytes: requireNonNegativeInteger(limitsRecord, 'max_answer_bytes', taskId),
+        allowed_input_tokens: requireNonNegativeInteger(limitsRecord, 'allowed_input_tokens', taskId),
+    };
+    const directiveRecord = requireRecord(record, 'directive', taskId);
+    const authority = requireString(directiveRecord, 'authority', taskId);
+    if (authority !== 'explicit_text') {
+        throw new DelegateError(`delegate seed directive authority ${authority} is not recognised`, {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    const directive = {
+        text: requireString(directiveRecord, 'text', taskId),
+        sha256: requireString(directiveRecord, 'sha256', taskId),
+        authority,
+    };
+    if (sha256Text(directive.text) !== directive.sha256) {
+        throw new DelegateError('delegate seed directive hash does not match its text', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    const parentLeafId = record['parent_leaf_id'];
+    if (parentLeafId !== null && typeof parentLeafId !== 'string') {
+        throw new DelegateError('delegate seed parent_leaf_id must be a string or null', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    const projection = requireRecord(record, 'conversation_projection', taskId);
+    const projectionPolicy = requireRecord(projection, 'policy', taskId);
+    if (requireString(projectionPolicy, 'id', taskId) !== DELEGATE_CONTEXT_POLICY_ID) {
+        throw new DelegateError('delegate seed projection policy id is not the delegate policy', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    if (!Array.isArray(projection['entries'])) {
+        throw new DelegateError('delegate seed projection entries must be an array', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+            taskId,
+        });
+    }
+    return {
+        schema_version: DELEGATE_SEED_SCHEMA_VERSION,
+        task_id: requireString(record, 'task_id', taskId),
+        launch_nonce: requireString(record, 'launch_nonce', taskId),
+        cwd: requireString(record, 'cwd', taskId),
+        capability,
+        extension_mode: extensionMode,
+        route,
+        parent_system_prompt: requireString(record, 'parent_system_prompt', taskId),
+        parent_leaf_id: parentLeafId,
+        directive,
+        conversation_projection: readDelegateProjection(projection),
+        limits,
+    };
+}
+/**
+ * The projection body is already hash-pinned by the seed digest verified above,
+ * so it is carried through without re-deriving values that would only duplicate
+ * the parent's computation.
+ */
+function readDelegateProjection(record) {
+    const projection = record;
+    if (!isDelegateProjection(projection)) {
+        throw new DelegateError('delegate seed conversation_projection is malformed', {
+            code: 'seed_hash_mismatch',
+            childCreated: true,
+        });
+    }
+    return projection;
+}
+function isDelegateProjection(value) {
+    if (!isRecord(value))
+        return false;
+    if (!isRecord(value['policy']) || !isRecord(value['branch_filter']))
+        return false;
+    if (!isRecord(value['accounting']))
+        return false;
+    return Array.isArray(value['entries']);
+}
+//# sourceMappingURL=seed.js.map

package/dist/src/core/delegate/seed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed.js","sourceRoot":"","sources":["../../../../src/core/delegate/seed.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHash } from 'node:crypto';\nimport { canonicalJson } from '../canonical-json.js';\nimport {\n  UnsupportedConversationBlockError,\n  projectVisibleConversationV2,\n  type ProjectedConversationV2,\n} from '../context/visible-conversation-v2.js';\nimport {\n  snapshotParentConversation,\n  type ParentContextSource,\n  type ParentSnapshotOptions,\n} from '../context/parent-snapshot.js';\nimport {\n  DELEGATE_BRANCH_FILTER_ID,\n  DELEGATE_CONTEXT_POLICY_ID,\n  DELEGATE_LEDGER_SCHEMA_VERSION,\n  DELEGATE_SEED_SCHEMA_VERSION,\n  DELEGATE_TOOL_NAME,\n  DelegateError,\n  type DelegateBranchFilterDescriptor,\n  type DelegateCapability,\n  type DelegateContextPolicyDescriptor,\n  type DelegateConversationProjection,\n  type DelegateLedgerV1,\n  type DelegateExtensionMode,\n  type DelegateLimits,\n  type DelegatePinnedRoute,\n  type DelegateSeedV1,\n  type DelegateTaskDirective,\n} from './types.js';\n\nexport interface BuildDelegateSeedOptions {\n  taskId: string;\n  launchNonce: string;\n  toolCallId: string | undefined;\n  directive: string;\n  capability: DelegateCapability;\n  extensionMode: DelegateExtensionMode;\n  route: DelegatePinnedRoute;\n  limits: DelegateLimits;\n}\n\nexport interface BuiltDelegateSeed {\n  seed: DelegateSeedV1;\n  /** Exact bytes persisted and written to the child. Nothing re-serializes them. */\n  serialized: string;\n  sha256: string;\n  ledger: DelegateLedgerV1;\n}\n\nfunction sha256Text(value: string): string {\n  return createHash('sha256').update(Buffer.from(value, 'utf8')).digest('hex');\n}\n\nfunction policyDescriptor(): DelegateContextPolicyDescriptor {\n  return {\n    id: DELEGATE_CONTEXT_POLICY_ID,\n    transform: 'visible-conversation-ledger-v2',\n    version: 1,\n    receipt_format: 'omitted_activity.v2',\n    user_text: 'verbatim',\n    assistant_text: 'verbatim',\n    assistant_thinking: 'ledger_only',\n    tool_call_arguments: 'ledger_only',\n    tool_results: 'ledger_only',\n    tool_payload_preview_bytes: 0,\n    images: 'marker_or_ledger_only',\n    unknown_block_behavior: 'error',\n  };\n}\n\n/**\n * Seal the shared transform under delegate's own envelope.\n *\n * Delegate never imports Fusion's canonical-input builder and never emits\n * `fusion-input.v4`. The ledger root commits only to ledger rows, so the two\n * consumers can seal identical bodies without either affecting the other.\n */\nfunction sealDelegateProjection(\n  projected: ProjectedConversationV2,\n  branchFilter: DelegateBranchFilterDescriptor,\n): { projection: DelegateConversationProjection; ledger: DelegateLedgerV1 } {\n  return {\n    projection: {\n      policy: policyDescriptor(),\n      branch_filter: branchFilter,\n      entries: projected.entries,\n      accounting: projected.accounting,\n    },\n    ledger: {\n      schema_version: DELEGATE_LEDGER_SCHEMA_VERSION,\n      policy_id: DELEGATE_CONTEXT_POLICY_ID,\n      transform: 'visible-conversation-ledger-v2',\n      entries: projected.ledger.entries,\n      projection_map: projected.ledger.projection_map,\n      root_sha256: projected.ledger.root_sha256,\n    },\n  };\n}\n\n/**\n * Build the frozen delegate seed.\n *\n * The projection excludes the assistant message carrying the in-flight\n * `bg_delegate` call. That message is excluded as a whole, so when several\n * `bg_delegate` calls share one assistant message every sibling call is excluded\n * for every child: two delegates launched together receive identical projected\n * history, and neither can observe the other's arguments.\n *\n * The directive is authoritative; projected history is supporting, untrusted\n * context. That relationship is stated to the child explicitly in its system\n * prompt, and recorded structurally here as `authority: 'explicit_text'`.\n */\nexport function buildDelegateSeed(\n  ctx: ParentContextSource,\n  options: BuildDelegateSeedOptions,\n): BuiltDelegateSeed {\n  const directiveText = options.directive;\n  if (directiveText.trim().length === 0) {\n    throw new DelegateError('bg_delegate prompt must not be blank', {\n      code: 'invalid_arguments',\n      childCreated: false,\n      remediation: ['Provide a non-blank prompt describing what the delegate should investigate.'],\n    });\n  }\n  const snapshotOptions: ParentSnapshotOptions = {\n    toolName: DELEGATE_TOOL_NAME,\n    excludeActiveToolCallLeaf: true,\n  };\n  if (options.toolCallId !== undefined) snapshotOptions.toolCallId = options.toolCallId;\n\n  let snapshot: ReturnType<typeof snapshotParentConversation>;\n  let projected: ProjectedConversationV2;\n  try {\n    snapshot = snapshotParentConversation(ctx, snapshotOptions);\n    projected = projectVisibleConversationV2(snapshot.messages);\n  } catch (error) {\n    if (error instanceof UnsupportedConversationBlockError) {\n      throw new DelegateError(\n        `bg_delegate could not project the parent conversation: ${error.message}`,\n        {\n          code: 'seed_projection_failed',\n          childCreated: false,\n          remediation: [\n            'The parent conversation contains a block type this package version does not know how to project.',\n            'Nothing was dropped or guessed and no child was created. Report the block type so the transform can be versioned.',\n          ],\n        },\n      );\n    }\n    throw error;\n  }\n\n  const branchFilter: DelegateBranchFilterDescriptor = {\n    id: DELEGATE_BRANCH_FILTER_ID,\n    tool_name: DELEGATE_TOOL_NAME,\n    tool_call_id: options.toolCallId ?? null,\n    active_tool_call_leaf_excluded: snapshot.activeToolCallLeafExcluded,\n  };\n  const sealed = sealDelegateProjection(projected, branchFilter);\n  const directive: DelegateTaskDirective = {\n    text: directiveText,\n    sha256: sha256Text(directiveText),\n    authority: 'explicit_text',\n  };\n  const seed: DelegateSeedV1 = {\n    schema_version: DELEGATE_SEED_SCHEMA_VERSION,\n    task_id: options.taskId,\n    launch_nonce: options.launchNonce,\n    cwd: ctx.cwd,\n    capability: options.capability,\n    extension_mode: options.extensionMode,\n    route: options.route,\n    parent_system_prompt: ctx.getSystemPrompt(),\n    parent_leaf_id: snapshot.leafId,\n    directive,\n    conversation_projection: sealed.projection,\n    limits: options.limits,\n  };\n  const serialized = canonicalJson(seed);\n  return { seed, serialized, sha256: sha256Text(serialized), ledger: sealed.ledger };\n}\n\nconst isRecord = (value: unknown): value is Record<PropertyKey, unknown> =>\n  typeof value === 'object' && value !== null && !Array.isArray(value);\n\n/**\n * Receive-side seed validation performed inside the child before its first model\n * call. A seed that does not match its declared length, hash, schema, task id,\n * and launch nonce is a loud refusal, never a best-effort continue.\n */\nexport function verifyDelegateSeedBytes(\n  raw: string,\n  expected: { sha256: string; taskId: string; launchNonce: string },\n): DelegateSeedV1 {\n  const actual = sha256Text(raw);\n  if (actual !== expected.sha256) {\n    throw new DelegateError(\n      `delegate seed hash mismatch: expected ${expected.sha256}, received ${actual}`,\n      {\n        code: 'seed_hash_mismatch',\n        childCreated: true,\n        taskId: expected.taskId,\n        remediation: ['The seed bytes delivered to the child differ from the persisted seed.'],\n      },\n    );\n  }\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch (error) {\n    throw new DelegateError(\n      `delegate seed is not valid JSON: ${error instanceof Error ? error.message : String(error)}`,\n      { code: 'seed_hash_mismatch', childCreated: true, taskId: expected.taskId },\n    );\n  }\n  if (!isRecord(parsed)) {\n    throw new DelegateError('delegate seed must be a JSON object', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId: expected.taskId,\n    });\n  }\n  if (parsed['schema_version'] !== DELEGATE_SEED_SCHEMA_VERSION) {\n    throw new DelegateError(\n      `delegate seed schema_version must be ${DELEGATE_SEED_SCHEMA_VERSION}`,\n      { code: 'seed_hash_mismatch', childCreated: true, taskId: expected.taskId },\n    );\n  }\n  if (parsed['task_id'] !== expected.taskId || parsed['launch_nonce'] !== expected.launchNonce) {\n    throw new DelegateError('delegate seed task identity does not match this child', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId: expected.taskId,\n    });\n  }\n  // The hash pins the exact bytes; this rebuild pins the shape the child is\n  // allowed to act on. Every field the child reads is validated and copied\n  // explicitly, so a structurally malformed seed cannot reach the agent loop by\n  // way of an unchecked assertion.\n  return rebuildSeed(parsed, expected.taskId);\n}\n\nfunction requireString(record: Record<PropertyKey, unknown>, key: string, taskId: string): string {\n  const value = record[key];\n  if (typeof value !== 'string') {\n    throw new DelegateError(`delegate seed field ${key} must be a string`, {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  return value;\n}\n\nfunction requireRecord(\n  record: Record<PropertyKey, unknown>,\n  key: string,\n  taskId: string,\n): Record<PropertyKey, unknown> {\n  const value = record[key];\n  if (!isRecord(value)) {\n    throw new DelegateError(`delegate seed field ${key} must be an object`, {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  return value;\n}\n\nfunction requireNonNegativeInteger(\n  record: Record<PropertyKey, unknown>,\n  key: string,\n  taskId: string,\n): number {\n  const value = record[key];\n  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value < 0) {\n    throw new DelegateError(`delegate seed field ${key} must be a non-negative safe integer`, {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  return value;\n}\n\n/** Explicit, field-by-field reconstruction of the seed fields the child consumes. */\nfunction rebuildSeed(record: Record<PropertyKey, unknown>, taskId: string): DelegateSeedV1 {\n  const capability = requireString(record, 'capability', taskId);\n  if (capability !== 'inspect') {\n    throw new DelegateError(`delegate seed capability ${capability} is not supported`, {\n      code: 'delegate_isolation_unsupported',\n      childCreated: true,\n      taskId,\n    });\n  }\n  const extensionMode = requireString(record, 'extension_mode', taskId);\n  if (extensionMode !== 'isolated' && extensionMode !== 'ambient') {\n    throw new DelegateError(`delegate seed extension mode ${extensionMode} is not recognised`, {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  const routeRecord = requireRecord(record, 'route', taskId);\n  const routeOrigin = requireString(routeRecord, 'origin', taskId);\n  if (routeOrigin !== 'parent_current' && routeOrigin !== 'explicit') {\n    throw new DelegateError(`delegate seed route origin ${routeOrigin} is not recognised`, {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  const route: DelegatePinnedRoute = {\n    provider: requireString(routeRecord, 'provider', taskId),\n    model: requireString(routeRecord, 'model', taskId),\n    qualified_id: requireString(routeRecord, 'qualified_id', taskId),\n    context_window_tokens: requireNonNegativeInteger(routeRecord, 'context_window_tokens', taskId),\n    thinking_level: requireString(routeRecord, 'thinking_level', taskId),\n    origin: routeOrigin,\n  };\n  const limitsRecord = requireRecord(record, 'limits', taskId);\n  const limits: DelegateLimits = {\n    max_turns: requireNonNegativeInteger(limitsRecord, 'max_turns', taskId),\n    max_tool_calls: requireNonNegativeInteger(limitsRecord, 'max_tool_calls', taskId),\n    timeout_seconds: requireNonNegativeInteger(limitsRecord, 'timeout_seconds', taskId),\n    max_tool_result_bytes: requireNonNegativeInteger(limitsRecord, 'max_tool_result_bytes', taskId),\n    max_total_tool_output_bytes: requireNonNegativeInteger(\n      limitsRecord,\n      'max_total_tool_output_bytes',\n      taskId,\n    ),\n    max_answer_bytes: requireNonNegativeInteger(limitsRecord, 'max_answer_bytes', taskId),\n    allowed_input_tokens: requireNonNegativeInteger(limitsRecord, 'allowed_input_tokens', taskId),\n  };\n  const directiveRecord = requireRecord(record, 'directive', taskId);\n  const authority = requireString(directiveRecord, 'authority', taskId);\n  if (authority !== 'explicit_text') {\n    throw new DelegateError(`delegate seed directive authority ${authority} is not recognised`, {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  const directive: DelegateTaskDirective = {\n    text: requireString(directiveRecord, 'text', taskId),\n    sha256: requireString(directiveRecord, 'sha256', taskId),\n    authority,\n  };\n  if (sha256Text(directive.text) !== directive.sha256) {\n    throw new DelegateError('delegate seed directive hash does not match its text', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  const parentLeafId = record['parent_leaf_id'];\n  if (parentLeafId !== null && typeof parentLeafId !== 'string') {\n    throw new DelegateError('delegate seed parent_leaf_id must be a string or null', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  const projection = requireRecord(record, 'conversation_projection', taskId);\n  const projectionPolicy = requireRecord(projection, 'policy', taskId);\n  if (requireString(projectionPolicy, 'id', taskId) !== DELEGATE_CONTEXT_POLICY_ID) {\n    throw new DelegateError('delegate seed projection policy id is not the delegate policy', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  if (!Array.isArray(projection['entries'])) {\n    throw new DelegateError('delegate seed projection entries must be an array', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n      taskId,\n    });\n  }\n  return {\n    schema_version: DELEGATE_SEED_SCHEMA_VERSION,\n    task_id: requireString(record, 'task_id', taskId),\n    launch_nonce: requireString(record, 'launch_nonce', taskId),\n    cwd: requireString(record, 'cwd', taskId),\n    capability,\n    extension_mode: extensionMode,\n    route,\n    parent_system_prompt: requireString(record, 'parent_system_prompt', taskId),\n    parent_leaf_id: parentLeafId,\n    directive,\n    conversation_projection: readDelegateProjection(projection),\n    limits,\n  };\n}\n\n/**\n * The projection body is already hash-pinned by the seed digest verified above,\n * so it is carried through without re-deriving values that would only duplicate\n * the parent's computation.\n */\nfunction readDelegateProjection(\n  record: Record<PropertyKey, unknown>,\n): DelegateConversationProjection {\n  const projection: unknown = record;\n  if (!isDelegateProjection(projection)) {\n    throw new DelegateError('delegate seed conversation_projection is malformed', {\n      code: 'seed_hash_mismatch',\n      childCreated: true,\n    });\n  }\n  return projection;\n}\n\nfunction isDelegateProjection(value: unknown): value is DelegateConversationProjection {\n  if (!isRecord(value)) return false;\n  if (!isRecord(value['policy']) || !isRecord(value['branch_filter'])) return false;\n  if (!isRecord(value['accounting'])) return false;\n  return Array.isArray(value['entries']);\n}\n"]}

package/dist/src/core/delegate/types.js

@@ -0,0 +1,103 @@
+export const DELEGATE_SEED_SCHEMA_VERSION = 'pi-background-tasks.delegate-seed.v2';
+export const DELEGATE_LEDGER_SCHEMA_VERSION = 'pi-background-tasks.delegate-ledger.v1';
+export const DELEGATE_RESULT_PACKAGE_SCHEMA_VERSION = 'pi-background-tasks.delegate-result.v1';
+export const DELEGATE_RECEIPT_SCHEMA_VERSION = 'pi-background-tasks.delegate-receipt.v1';
+export const DELEGATE_BUDGET_PLAN_SCHEMA_VERSION = 'pi-background-tasks.delegate-budget-plan.v3';
+export const DELEGATE_MANIFEST_SCHEMA_VERSION = 'pi-background-tasks.delegate-manifest.v2';
+/**
+ * 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'];
+/**
+ * Controls only Pi's ambient extension discovery for delegate children.
+ * Tool and project-resource restrictions remain independently enforced.
+ */
+export const DELEGATE_EXTENSION_MODES = ['isolated', 'ambient'];
+export const DELEGATE_AUTO_DELIVER_MODES = ['never', 'when_small', 'always'];
+export const DELEGATE_DELIVERY_MODES = ['inline', 'artifact'];
+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',
+];
+/**
+ * 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 {
+    code;
+    childCreated;
+    taskId;
+    artifactDir;
+    budget;
+    preserved;
+    remediation;
+    constructor(message, details) {
+        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() {
+        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');
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/src/core/delegate/types.js.map

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