@anureo/adapter-pi 0.0.0-stage → 0.3.0

package/src/adapter.d.ts

@@ -0,0 +1,212 @@
+import { type AhpRequestMap, type AhpResultMap, type Capabilities, type InitializeParams, type InitializeResult, type SessionBinding, type SessionOpenParams } from '@anureo/protocol';
+import { type BackendSession, type HarnessAdapter, type SessionEventSink, type SessionMethod, type StructuredOutputToolPort } from '@anureo/sdk';
+import { type PiHostFactory, type PiSessionHost } from "./host.js";
+import { type Redactor } from "./mapping.js";
+import type { PiAdapterOptions } from "./options.js";
+import { type PiProfile } from "./profile.js";
+/** Connect an SDK client to Pi. Hosts open on session admission. Await client disposal to release them. */
+export declare function createPiAdapter(options?: PiAdapterOptions): PiAdapter;
+/**
+ * Connect createClient to Pi hosts. Applications normally use createPiAdapter and await client
+ * disposal. Direct adapter consumers must await disposal of the adapter and its tracked sessions.
+ */
+export declare class PiAdapter implements HarnessAdapter {
+    /** Capture the version, host factory and redactor without I/O. Omitting the version selects the baseline profile. */
+    constructor(options?: PiAdapterOptions);
+    /** Requested persistence, defaulting to true. Hosts persist only when the version profile supports resume. */
+    get persist(): boolean;
+    /** Native capability set for negotiation; the SDK may add structured output when a host exposes its tool port. */
+    get capabilities(): Capabilities;
+    /**
+     * Negotiate protocol v1 without opening Pi. Return runtime info and native capabilities for
+     * Client.initialize through the output wrapper. Invalid or incompatible requests and disposed
+     * adapters reject.
+     */
+    initialize(params: InitializeParams): Promise<InitializeResult>;
+    /**
+     * Acquire an owned backend for OutputSession.open with host observation registered. A disposed
+     * adapter, non-Pi binding or nonempty MCP server list rejects before acquisition. If open fails
+     * after construction, attempt backend disposal before rethrowing the setup failure. The output
+     * wrapper owns disposal of the returned backend.
+     */
+    openSession(params: SessionOpenParams, sink: SessionEventSink): Promise<BackendSession>;
+    /** Attempt release of all tracked sessions concurrently. Reject the first failure in tracking order after all attempts settle. Later calls are no-ops. */
+    dispose(): Promise<void>;
+    /** Supply the host factory to PiBackendSession.open. The acquiring backend owns each returned host. */
+    hostFactory(): PiHostFactory;
+    /** PiBackendSession.dispose removes itself after release. Turn mappings remain available for resume and fork. */
+    forget(session: PiBackendSession): void;
+    /** Find a tracked source for PiBackendSession.forkHost to borrow. The source backend retains disposal ownership. */
+    liveHost(nativeId: string): PiSessionHost | undefined;
+    /** Original option object retained by reference; host paths/history limits are read when used. */
+    readonly options: PiAdapterOptions;
+    /** Version profile selected at construction. Persistence policy also affects advertised capabilities. */
+    readonly profile: PiProfile;
+    private readonly sessions;
+    /** Shared maps keyed by Pi session ID, then native user entry ID, to retain SDK turn IDs across resume and fork. */
+    readonly turnMaps: Map<string, Map<string, string>>;
+    /** Content redactor shared by backends, captured from the constructor options. */
+    readonly redact: Redactor;
+    private readonly factory;
+    private disposed;
+    private version;
+}
+/**
+ * Observe and control one Pi session through the SDK backend port. OutputSession adopts the
+ * backend returned by PiAdapter.openSession and owns disposal. Input receipts acknowledge native
+ * admission. Sink events carry later execution and settlement.
+ */
+export declare class PiBackendSession implements BackendSession {
+    private readonly adapter;
+    private readonly params;
+    private readonly sink;
+    /**
+     * Prepare one backend without acquiring a host. PiAdapter.openSession supplies the request and sink.
+     * Unknown config options throw CAPABILITY_UNSUPPORTED and invalid schema values throw
+     * INVALID_PARAMS. Await open before dispatching requests and dispose after use or failed open.
+     */
+    constructor(adapter: PiAdapter, params: SessionOpenParams, sink: SessionEventSink);
+    /**
+     * Expose direct tool registration when the acquired host supports it. OutputSession supplies the
+     * definition and its validation callback before dispatch. It passes undefined on terminal,
+     * definite rejection of an unbound submission or release. Host registration failures propagate
+     * to the wrapper, which owns candidate validation and publication.
+     */
+    get structuredOutputTool(): StructuredOutputToolPort | undefined;
+    /** Pi session ID after open, or the requested native reference before acquisition. A missing reference returns an empty string. */
+    get nativeId(): string;
+    /**
+     * PiAdapter.openSession calls once before returning this backend. Acquire and bind the host,
+     * retain pre-run entries and subscribe in that order so new user entries can identify live turns.
+     * Acquisition failures use sdkError with PI_SESSION_OPEN_FAILED as fallback. The adapter owns
+     * disposal if binding or subscription setup fails after acquisition.
+     */
+    open(): Promise<void>;
+    /**
+     * Dispatch an SDK-validated request from OutputSession.execute after open. Submission resolves
+     * on native admission, interrupt after abort and compact after native compaction. Sink events
+     * independently report execution completion. Unsupported requests, closed sessions and native
+     * failures reject. Close awaits disposal and reports execution stop as unconfirmed.
+     */
+    execute<M extends SessionMethod>(method: M, params: AhpRequestMap[M]): Promise<AhpResultMap[M]>;
+    /**
+     * Share one cleanup attempt across callers. Stop admission, unsubscribe and discard pending
+     * inputs before best-effort abort and awaited host disposal. Host disposal failure rejects the
+     * shared promise and leaves adapter tracking intact; cleanup does not await event-tail drainage.
+     */
+    dispose(): Promise<void>;
+    /** Acquired by open; backend disposal owns its release, including partially completed setup. */
+    host: PiSessionHost;
+    /** Requested SDK identity, with the native reference replaced after acquisition. */
+    binding: SessionBinding;
+    /** Native capabilities captured for attachment; direct output support is projected by the SDK wrapper. */
+    readonly capabilities: Capabilities;
+    private readonly redact;
+    private unsubscribe?;
+    private active?;
+    private pending;
+    private closed;
+    private release?;
+    private config;
+    private model?;
+    private capabilityRevision;
+    private title?;
+    private tail;
+    private turns;
+    private snapshots;
+    private compactions;
+    /** Entry ids that existed before the current run, so the run's own user entry can be told apart. */
+    private known;
+    /** Snapshot entry ids at open/turn completion so the next run can associate its first new user entry. */
+    private markKnown;
+    /** Build host options before native-open error wrapping, preserving validation failures as parameter errors. */
+    private hostOptions;
+    /** Acquire a new, resumed or forked host; open publishes its binding only after acquisition succeeds. */
+    private acquireHost;
+    /** Resolve config before the open request's permission mode; omission keeps native host defaults. */
+    private permissionMode;
+    /**
+     * Fork from a tracked source or a temporary resumed host. Copy the SDK turn IDs retained by
+     * the branch so open can register them for the new session. Always attempt to dispose the
+     * temporary source and suppress that cleanup failure. The live source remains borrowed.
+     */
+    private forkHost;
+    /**
+     * The listener registered by open appends events here without blocking Pi. Await each handler in
+     * arrival order and skip queued work after close. Report mapping or publication failures through
+     * OutputSession's forwarding sink, which delegates observation failure to Session.fail. Disposal
+     * unsubscribes and leaves any in-flight handler to finish independently.
+     */
+    private enqueue;
+    /** Return detached binding and config for config receipts and post-terminal state. Capabilities remain shared. */
+    private snapshot;
+    /** Publish a new turn before binding pending inputs; retries/continuations reuse the active turn until settlement. */
+    private beginTurn;
+    /**
+     * Route serialized host callbacks to the sink or turn state. Wait for settlement across native
+     * retries and continuations. A run error can end the turn early, and source loss fails observation.
+     */
+    private handle;
+    /** Start tool items only at execution, when Pi has finalized the name and arguments. */
+    private startTool;
+    /** Ignore updates without a running turn's matching tool item; publish redacted output deltas otherwise. */
+    private updateTool;
+    /** Complete only tool items already observed in the active turn. */
+    private endTool;
+    /** Outside a turn, report compaction as a notice because item events require a turn scope. */
+    private startCompaction;
+    /** Match the latest compaction item inside a turn, or publish an unscoped completion/failure notice. */
+    private endCompaction;
+    /** Native settlement completes the active turn, or rejects inputs that never acquired an execution. */
+    private settle;
+    /** Address the same assistant content block in both streaming updates and the final message. */
+    private itemId;
+    /**
+     * Accumulate streamed text and reasoning using stable item IDs. Text completion waits for
+     * message_end to select its phase. Tool items start at execution, when arguments are final.
+     */
+    private messageUpdate;
+    /**
+     * Associate the first new user entry with this turn. For assistant messages, retain usage and
+     * errors and publish completed text blocks with their final or commentary phase. Successful
+     * assistant continuations clear earlier attempt failures.
+     */
+    private messageEnd;
+    /**
+     * On the first user message end, record the new Pi entry so history and fork can resolve the
+     * SDK turn ID. Further user messages may belong to queued continuations of the same turn.
+     */
+    private recordTurnStart;
+    /**
+     * Complete unfinished tool items, then publish usage, the terminal and ready state in order.
+     * Native interruption takes precedence over a recorded failure. Clear active state before terminal
+     * publication so the emitted snapshot is ready; publication failures flow to enqueue's sink failure.
+     */
+    private finishTurn;
+    /**
+     * Convert input before native admission. Reserve idle input before prompt can emit events. Other
+     * inputs use followUp or steer, then join an active turn if present or wait for a binding event.
+     * Extension handling returns acceptance without a turn. Native failures use PI_SUBMIT_FAILED
+     * as a fallback code. OutputSession prepares schema-bearing input before dispatch.
+     */
+    private submit;
+    /**
+     * Check the patch before applying model, thinking and tools in order, then publish and return
+     * the new state. PI_CONFIG_FAILED is the fallback for host mutations with an unknown outcome.
+     * Earlier mutations can survive later failures. The config and revision commit after all host
+     * mutations succeed, before publication.
+     */
+    private setConfig;
+    /**
+     * Return the validated model and thinking level for setConfig to apply, or throw INVALID_PARAMS.
+     * A requested model governs the allowed thinking levels, with the host's active levels as fallback.
+     */
+    private validateModelConfig;
+    /**
+     * Return detached item pages from redacted active-branch history. Reuse snapshotToken with
+     * nextCursor to keep paging over the same snapshot. New reads retain the configured history
+     * suffix, keep up to eight snapshots and evict the oldest first. Pages default to 200 items,
+     * capped at 1000. Invalid offsets reject CURSOR_INVALID and unavailable tokens reject CURSOR_EXPIRED.
+     */
+    private readHistory;
+}