@pi-unipi/background-tasks 2.6.3 → 2.9.0

package/src/__tests__/scripted-provider/hook-probe-extension.ts

@@ -1,126 +0,0 @@
-import { appendFileSync } from 'node:fs';
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-
-/**
- * Instrumented probe extension used by the Pi hook-contract characterisation
- * gate. Its behaviour is selected by `UNIPI_BG_HOOK_PROBE_MODE` so one extension
- * body can answer every question the delegate child-side guard depends on.
- */
-export type HookProbeMode =
-  | 'observe'
-  | 'context-replace'
-  | 'context-throw'
-  | 'context-abort'
-  | 'tool-result-replace';
-
-type JsonObject = Record<PropertyKey, unknown>;
-
-export const HOOK_PROBE_INJECTED_TEXT = 'HOOK_PROBE_INJECTED_CONTEXT_MESSAGE';
-export const HOOK_PROBE_REPLACED_TOOL_TEXT = 'HOOK_PROBE_REPLACED_TOOL_RESULT';
-
-function record(event: JsonObject): void {
-  const path = process.env['UNIPI_BG_HOOK_PROBE_LOG'];
-  if (!path) return;
-  appendFileSync(path, `${JSON.stringify(event)}\n`, 'utf8');
-}
-
-function mode(): HookProbeMode {
-  const value = process.env['UNIPI_BG_HOOK_PROBE_MODE'];
-  if (
-    value === 'context-replace' ||
-    value === 'context-throw' ||
-    value === 'context-abort' ||
-    value === 'tool-result-replace'
-  )
-    return value;
-  return 'observe';
-}
-
-interface ContentPartLike {
-  readonly type: string;
-  readonly text?: unknown;
-}
-
-function messageText(message: object): string {
-  const content: unknown = Reflect.get(message, 'content');
-  if (typeof content === 'string') return content;
-  if (!Array.isArray(content)) return '';
-  const parts: readonly ContentPartLike[] = content.filter(
-    (part): part is ContentPartLike =>
-      typeof part === 'object' && part !== null && typeof Reflect.get(part, 'type') === 'string',
-  );
-  return parts.map((part) => (typeof part.text === 'string' ? part.text : `<${part.type}>`)).join('');
-}
-
-/**
- * Build the probe extension factory for one probe identity. Two distinct probe
- * modules share this body so handler ordering across separate extensions can be
- * observed directly.
- */
-export function createHookProbeExtension(probeId: string): (pi: ExtensionAPI) => void {
-  return (pi: ExtensionAPI): void => {
-    let contextFires = 0;
-    let toolResultFires = 0;
-
-    pi.on('context', (event, ctx) => {
-      contextFires += 1;
-      record({
-        hook: 'context',
-        probeId,
-        contextFires,
-        roles: event.messages.map((message) => message.role),
-        texts: event.messages.map(messageText),
-      });
-      const selected = mode();
-      if (selected === 'context-throw' && probeId === 'probe-a') {
-        record({ hook: 'context_throwing', probeId });
-        throw new Error('HOOK_PROBE_CONTEXT_THROW');
-      }
-      if (selected === 'context-abort' && probeId === 'probe-a') {
-        record({ hook: 'context_aborting', probeId });
-        ctx.abort();
-        return undefined;
-      }
-      if (selected === 'context-replace' && probeId === 'probe-a') {
-        return {
-          messages: [
-            ...event.messages,
-            { role: 'user', content: HOOK_PROBE_INJECTED_TEXT, timestamp: Date.now() },
-          ],
-        };
-      }
-      return undefined;
-    });
-
-    pi.on('tool_result', (event) => {
-      toolResultFires += 1;
-      record({
-        hook: 'tool_result',
-        probeId,
-        toolResultFires,
-        toolName: event.toolName,
-        toolCallId: event.toolCallId,
-        isError: event.isError,
-        texts: event.content.map((part) => (part.type === 'text' ? part.text : `<${part.type}>`)),
-      });
-      if (mode() === 'tool-result-replace' && probeId === 'probe-a') {
-        return { content: [{ type: 'text' as const, text: HOOK_PROBE_REPLACED_TOOL_TEXT }] };
-      }
-      return undefined;
-    });
-
-    pi.on('tool_execution_end', (event) => {
-      record({
-        hook: 'tool_execution_end',
-        probeId,
-        toolName: event.toolName,
-        toolCallId: event.toolCallId,
-        isError: event.isError,
-      });
-    });
-
-    pi.on('message_end', (event) => {
-      record({ hook: 'message_end', probeId, role: event.message.role });
-    });
-  };
-}

package/src/__tests__/scripted-provider/output-recovery-provider.ts

@@ -1,153 +0,0 @@
-import { appendFileSync, writeFileSync } from 'node:fs';
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import {
-  createAssistantMessageEventStream,
-  type Api,
-  type AssistantMessage,
-  type AssistantMessageEventStream,
-  type Context,
-  type Message,
-  type Model,
-  type TextContent,
-} from '@earendil-works/pi-ai';
-import { FUSION_CANDIDATE_OUTPUT_COMPRESSION_PROMPT } from '../../fusion/output-contract.js';
-
-export const OUTPUT_RECOVERY_PROVIDER = 'pi-bg-output-recovery';
-export const OUTPUT_RECOVERY_MODEL = 'output-recovery-model';
-const API = 'pi-bg-output-recovery-api';
-export const OUTPUT_RECOVERY_ORIGINAL = 'x'.repeat(49_152);
-export const OUTPUT_RECOVERY_REPLACEMENT = 'compressed replacement';
-
-interface OutputRecoveryLogEvent {
-  event: 'provider_call' | 'agent_settled';
-  pid: number;
-  calls?: number;
-  call?: number;
-  roles?: string[];
-  tools?: string[];
-  saw_original?: boolean;
-  saw_compression_prompt?: boolean;
-}
-
-function record(value: OutputRecoveryLogEvent): void {
-  const path = process.env['UNIPI_BG_OUTPUT_RECOVERY_LOG'];
-  if (path) appendFileSync(path, `${JSON.stringify(value)}\n`, 'utf8');
-}
-
-function messageText(message: Message): string {
-  if (typeof message.content === 'string') return message.content;
-  if (!Array.isArray(message.content)) return '';
-  return message.content.map((part) => ('text' in part ? part.text : '')).join('');
-}
-
-function pushText(stream: AssistantMessageEventStream, text: string): void {
-  const usage = {
-    input: 10,
-    output: text.length,
-    cacheRead: 0,
-    cacheWrite: 0,
-    totalTokens: 10 + text.length,
-    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
-  };
-  const message: AssistantMessage = {
-    role: 'assistant',
-    content: [{ type: 'text', text }],
-    api: API,
-    provider: OUTPUT_RECOVERY_PROVIDER,
-    model: OUTPUT_RECOVERY_MODEL,
-    usage,
-    stopReason: 'stop',
-    timestamp: Date.now(),
-  };
-  const partial: AssistantMessage = { ...message, content: [] };
-  const partialText: TextContent = { type: 'text', text: '' };
-  stream.push({ type: 'start', partial: { ...partial } });
-  partial.content = [partialText];
-  stream.push({ type: 'text_start', contentIndex: 0, partial: { ...partial } });
-  partialText.text = text;
-  stream.push({ type: 'text_delta', contentIndex: 0, delta: text, partial: { ...partial } });
-  stream.push({ type: 'text_end', contentIndex: 0, content: text, partial: { ...partial } });
-  stream.push({ type: 'done', reason: 'stop', message });
-  stream.end(message);
-}
-
-const RecoveryProbeParams = {
-  type: 'object',
-  properties: {},
-  additionalProperties: false,
-} as const;
-
-export default function outputRecoveryProvider(pi: ExtensionAPI): void {
-  let calls = 0;
-  let recoveryQueued = false;
-
-  pi.registerTool<typeof RecoveryProbeParams, Record<string, never>>({
-    name: 'recovery_probe',
-    label: 'Recovery Probe',
-    description: 'Test-only tool used to prove that output compression disables tools.',
-    parameters: RecoveryProbeParams,
-    execute() {
-      return Promise.resolve({ content: [{ type: 'text' as const, text: 'unused' }], details: {} });
-    },
-  });
-
-  pi.on('message_end', (event) => {
-    if (event.message.role !== 'assistant' || recoveryQueued) return;
-    const text = event.message.content
-      .flatMap((part) => (part.type === 'text' ? [part.text] : []))
-      .join('');
-    if (text !== OUTPUT_RECOVERY_ORIGINAL) return;
-    const recoveryPath = process.env['UNIPI_BG_OUTPUT_RECOVERY_ARTIFACT'];
-    if (!recoveryPath) throw new Error('UNIPI_BG_OUTPUT_RECOVERY_ARTIFACT is required');
-    writeFileSync(recoveryPath, text, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
-    recoveryQueued = true;
-    pi.setActiveTools([]);
-    pi.sendUserMessage(FUSION_CANDIDATE_OUTPUT_COMPRESSION_PROMPT, {
-      deliverAs: 'followUp',
-    });
-  });
-
-  // OUR SDK lacks agent_settled; agent_end carries the same end-of-run signal for probes.
-  pi.on('agent_end', () => {
-    record({ event: 'agent_settled', pid: process.pid, calls });
-  });
-
-  pi.registerProvider(OUTPUT_RECOVERY_PROVIDER, {
-    name: 'Pi Background Tasks Output Recovery Provider',
-    baseUrl: 'http://localhost:0',
-    apiKey: 'UNIPI_BG_OUTPUT_RECOVERY_API_KEY',
-    api: API,
-    models: [
-      {
-        id: OUTPUT_RECOVERY_MODEL,
-        name: 'Output Recovery Model',
-        reasoning: false,
-        input: ['text'],
-        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
-        contextWindow: 200_000,
-        maxTokens: 64_000,
-      },
-    ],
-    streamSimple(_model: Model<Api>, context: Context): AssistantMessageEventStream {
-      calls += 1;
-      const texts = context.messages.map(messageText);
-      const tools = Array.isArray(context.tools) ? context.tools.map((tool) => tool.name) : [];
-      record({
-        event: 'provider_call',
-        pid: process.pid,
-        call: calls,
-        roles: context.messages.map((message) => message.role),
-        tools,
-        saw_original: texts.includes(OUTPUT_RECOVERY_ORIGINAL),
-        saw_compression_prompt: texts.some((text) =>
-          text.includes('Compress and restructure only your immediately previous answer'),
-        ),
-      });
-      const stream = createAssistantMessageEventStream();
-      queueMicrotask(() => {
-        pushText(stream, calls === 1 ? OUTPUT_RECOVERY_ORIGINAL : OUTPUT_RECOVERY_REPLACEMENT);
-      });
-      return stream;
-    },
-  });
-}

package/src/__tests__/scripted-provider/pi-hook-contract-evidence.json

@@ -1,18 +0,0 @@
-{
-  "schema_version": "pi-background-tasks.delegate-hook-contract.v1",
-  "contract_id": "context-measure-abort-v1+tool-result-spill-v1",
-  "guarantees": {
-    "context_fires_before_every_model_call": true,
-    "context_result_messages_reach_provider": true,
-    "context_abort_blocks_provider_call": true,
-    "context_abort_skips_stream_invocation": false,
-    "context_abort_terminates_run": true,
-    "context_throw_blocks_provider_call": false,
-    "context_throw_isolated_to_throwing_handler": true,
-    "tool_result_fires_before_transcript_entry": true,
-    "tool_result_replacement_reaches_provider": true,
-    "tool_result_replacement_preserves_identity": true,
-    "tool_result_chains_in_load_order": true,
-    "handlers_run_in_extension_load_order": true
-  }
-}