engineering-behavior-observatory 0.2.1

package/dist/src/pi.d.ts

@@ -0,0 +1,203 @@
+import { type AgentSessionEvent, type InlineExtension } from "@earendil-works/pi-coding-agent";
+import { type ArtifactReference } from "./contracts.js";
+import { type RunAttemptResult, type TerminalRecord, type VerifierExecutionContext, type WorkspaceCoordinator } from "./lifecycle.js";
+import { type AdapterCoverageReport, type NormalizedDataset } from "./normalization-integrity.js";
+import { JsonlEvidenceWriter } from "./process-protocol.js";
+import { type CaptureQualificationReport, type CaptureQualificationStatus, type CapturedWorkspaceOutcome, type RunBundleDefinition, type RunManifest } from "./run-bundles.js";
+import { type TaskPacket } from "./task-packets.js";
+import { type VerifierResult } from "./verifiers.js";
+import { type AdapterCapabilityProfile, type NativeEvidenceResolver, type NormalizationInput, type NormalizationResult } from "./uniform-events.js";
+export declare const PI_HARNESS = "pi-sdk";
+export declare const PI_CONFIG_SCHEMA_VERSION = "ebo.pi-config/v1";
+export declare const PI_ADAPTER_VERSION = "1.0.0";
+export declare const PINNED_PI_SDK_VERSION = "0.85.1";
+declare const PI_APIS: readonly ["anthropic-messages", "openai-completions", "openai-responses", "google-generative-ai"];
+declare const PI_THINKING_LEVELS: readonly ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+declare const PI_TOOLS: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"];
+type PiCost = {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+};
+type PiThinkingLevel = typeof PI_THINKING_LEVELS[number];
+export type PiModelConfiguration = {
+    schemaVersion: typeof PI_CONFIG_SCHEMA_VERSION;
+    kind: "model";
+    provider: string;
+    queueModelId: string;
+    model: string;
+    api: typeof PI_APIS[number];
+    baseUrl: string;
+    apiKeyEnv: string;
+    thinkingLevel: typeof PI_THINKING_LEVELS[number];
+    thinkingLevelMap?: Partial<Record<PiThinkingLevel, string | null>>;
+    reasoning: boolean;
+    input: Array<"text" | "image">;
+    contextWindow: number;
+    maxTokens: number;
+    cost: PiCost;
+};
+export type PiHarnessConfiguration = {
+    schemaVersion: typeof PI_CONFIG_SCHEMA_VERSION;
+    kind: "harness";
+    adapter: typeof PI_HARNESS;
+    version: typeof PINNED_PI_SDK_VERSION;
+    extensions?: ArtifactReference[];
+    skills?: ArtifactReference[];
+    prompts?: ArtifactReference[];
+    contextFiles?: ArtifactReference[];
+    systemPrompt?: ArtifactReference;
+};
+export type PiNativeLimitsConfiguration = {
+    schemaVersion: typeof PI_CONFIG_SCHEMA_VERSION;
+    kind: "native-limits";
+    shutdownGraceMs?: number;
+    maxRetries?: number;
+    retryBaseDelayMs?: number;
+    providerTimeoutMs?: number;
+};
+export type PiNativeToolPolicyConfiguration = {
+    schemaVersion: typeof PI_CONFIG_SCHEMA_VERSION;
+    kind: "native-tool-policy";
+    tools: typeof PI_TOOLS[number][];
+    excludeTools?: typeof PI_TOOLS[number][];
+    environmentAllowlist: string[];
+};
+export type PiCaptureProfileConfiguration = {
+    schemaVersion: typeof PI_CONFIG_SCHEMA_VERSION;
+    kind: "capture-profile";
+    passiveObserver?: boolean;
+    includeProviderPayloads?: boolean;
+    workspaceOutcome?: {
+        excludeDirectoryNames: string[];
+        respectGitignore?: boolean;
+        omitEmptyDirectories?: boolean;
+    };
+};
+export type PiConfigurationRecord = PiModelConfiguration | PiHarnessConfiguration | PiNativeLimitsConfiguration | PiNativeToolPolicyConfiguration | PiCaptureProfileConfiguration;
+export type PiConfigurationKind = PiConfigurationRecord["kind"];
+export type PiNativeRecord = Record<string, unknown>;
+export declare const piCapabilityProfile: AdapterCapabilityProfile;
+type PiRecordedEnvelope = {
+    schemaVersion: "ebo.pi-native-record/v1";
+    sequence: number;
+    receivedAt: string;
+    channel: "stream" | "observer" | "adapter";
+    nativeType: string;
+    sessionId?: string;
+    hook?: string;
+    stage?: string;
+    extensionOrder?: number;
+    payload: unknown;
+};
+declare class PiEvidenceRecorder {
+    readonly writer: JsonlEvidenceWriter;
+    private sequence;
+    private queue;
+    private error;
+    constructor(path: string);
+    record(input: Omit<PiRecordedEnvelope, "schemaVersion" | "sequence" | "receivedAt">): Promise<void>;
+    flush(): Promise<void>;
+    close(): Promise<void>;
+}
+export type PiSession = {
+    readonly sessionId: string;
+    readonly sessionFile?: string;
+    readonly messages: unknown[];
+    readonly extensionRunner?: {
+        emit(event: unknown): Promise<unknown>;
+    };
+    subscribe(listener: (event: AgentSessionEvent) => void): () => void;
+    prompt(text: string, options?: {
+        expandPromptTemplates?: boolean;
+        source?: "extension";
+    }): Promise<void>;
+    waitForIdle(): Promise<void>;
+    abort(): Promise<void>;
+    exportToJsonl(outputPath?: string): string;
+    getActiveToolNames(): string[];
+    dispose(): void;
+};
+export type PiSessionFactoryInput = {
+    workspacePath: string;
+    sessionDirectory: string;
+    model: PiModelConfiguration;
+    harness: PiHarnessConfiguration;
+    limits: PiNativeLimitsConfiguration;
+    toolPolicy: PiNativeToolPolicyConfiguration;
+    captureProfile: PiCaptureProfileConfiguration;
+    bundleRoot: string;
+    observer: PiEvidenceRecorder;
+    signal: AbortSignal;
+};
+export type PiSessionFactory = (input: PiSessionFactoryInput) => Promise<PiSession>;
+export type CapturePiSdkRunOptions = {
+    definition: RunBundleDefinition;
+    configurationRoot: string;
+    startingWorkspacePath: string;
+    workspace: WorkspaceCoordinator;
+    model: PiModelConfiguration;
+    harness: PiHarnessConfiguration;
+    limits: PiNativeLimitsConfiguration;
+    toolPolicy: PiNativeToolPolicyConfiguration;
+    captureProfile: PiCaptureProfileConfiguration;
+    prompt: string;
+    verifier?: (context: VerifierExecutionContext, workspace: CapturedWorkspaceOutcome, workspacePath: string) => VerifierResult | Promise<VerifierResult>;
+    workspaceOutcomeExcludedDirectoryNames?: readonly string[];
+    workspaceOutcomeRespectsGitignore?: boolean;
+    workspaceOutcomeOmitsEmptyDirectories?: boolean;
+    signal?: AbortSignal;
+    maxWallClockMs?: number;
+    createSession?: PiSessionFactory;
+};
+export type CapturePiSdkRunResult = {
+    attempt: RunAttemptResult;
+    manifest: RunManifest;
+    qualification: CaptureQualificationReport;
+};
+/** Execute one direct Pi TypeScript SDK session and retain native history, transient events, and passive observations. */
+export declare function capturePiSdkRun(options: CapturePiSdkRunOptions): Promise<CapturePiSdkRunResult>;
+export declare function filterPiToolEnvironment(environment: NodeJS.ProcessEnv, allowlist: ReadonlySet<string>, apiKeyEnv: string): NodeJS.ProcessEnv;
+export declare function createPiPassiveObserver(recorder: PiEvidenceRecorder, extensionOrder: number, includeProviderPayloads: boolean): InlineExtension;
+export declare function normalizePiCapture(input: NormalizationInput<PiNativeRecord>): Promise<NormalizationResult>;
+export declare function describeAndValidatePiDataset(capture: NormalizationInput<PiNativeRecord>): Promise<{
+    dataset: NormalizedDataset;
+    coverage: AdapterCoverageReport;
+    resolver: NativeEvidenceResolver;
+}>;
+export declare function piNativeType(record: PiNativeRecord): string;
+export declare function assertPiNativeRecord(record: unknown, line: number): asserts record is PiNativeRecord;
+export declare function qualifyRetainedPiCapture(capture: NormalizationInput<PiNativeRecord>, sessionId: string | undefined, expectsCompletion: boolean): NormalizationInput<PiNativeRecord>;
+export type RunPiQueueEntryOptions = {
+    bundleRoot: string;
+    queuePath: string;
+    runId: string;
+    outputRoot: string;
+    workspaceRoot?: string;
+    attemptId?: string;
+    signal?: AbortSignal;
+    createSession?: PiSessionFactory;
+};
+export type PiRunSummary = {
+    runId: string;
+    attemptId: string;
+    bundlePath: string;
+    terminal: TerminalRecord;
+    classification: RunAttemptResult["classification"]["kind"];
+    captureQualification: CaptureQualificationStatus;
+    assessmentMode: TaskPacket["assessmentMode"];
+    sessionId?: string;
+    retainedWorkspacePath?: string;
+};
+/** Execute exactly one frozen queue entry through the pinned direct Pi SDK integration. */
+export declare function runPiQueueEntry(options: RunPiQueueEntryOptions): Promise<PiRunSummary>;
+type PiConfigurationByKind = {
+    model: PiModelConfiguration;
+    harness: PiHarnessConfiguration;
+    "native-limits": PiNativeLimitsConfiguration;
+    "native-tool-policy": PiNativeToolPolicyConfiguration;
+    "capture-profile": PiCaptureProfileConfiguration;
+};
+export declare function resolvePiConfigurationRecord<Kind extends PiConfigurationKind>(bundleRoot: string, reference: ArtifactReference, kind: Kind): PiConfigurationByKind[Kind];
+export {};