@elpapi42/pi-fleet 0.1.0-beta.10 → 0.1.0-beta.14

package/dist/client/agent-target.d.ts

@@ -0,0 +1,33 @@
+import type { AgentId, ReceiveCursor } from "./contracts.js";
+/** A user-facing lookup that may resolve to the current generation for a name. */
+export interface AgentNameLookup {
+    readonly name: string;
+}
+/** A resolved target that must not retarget a later same-name agent. */
+export interface ExpectedAgentTarget extends AgentNameLookup {
+    readonly expectedAgentId: AgentId;
+}
+export type ReceiveStart = {
+    readonly kind: "live";
+} | {
+    readonly kind: "after";
+    readonly cursor: ReceiveCursor;
+} | {
+    readonly kind: "start";
+};
+/** The future cursor encoding contract; encoded cursor contents remain private. */
+export interface ReceiveCursorCodec {
+    readonly version: 1;
+    encode(boundary: {
+        readonly agentId: AgentId;
+        readonly epoch: number;
+        readonly position: number;
+        readonly kind?: "position" | "continuation";
+    }): ReceiveCursor;
+    decode(cursor: ReceiveCursor): {
+        readonly agentId: AgentId;
+        readonly epoch: number;
+        readonly position: number;
+        readonly kind: "position" | "continuation";
+    };
+}

package/dist/client/contracts.d.ts

@@ -0,0 +1,81 @@
+export type AgentId = string & {
+    readonly __brand: "AgentId";
+};
+export type AgentEventId = string & {
+    readonly __brand: "AgentEventId";
+};
+export type ActivityId = string & {
+    readonly __brand: "ActivityId";
+};
+export type ReceiveCursor = string & {
+    readonly __brand: "ReceiveCursor";
+};
+export type ContinuityEpoch = number & {
+    readonly __brand: "ContinuityEpoch";
+};
+export type AgentState = "restoring" | "working" | "idle" | "failed" | "destroying";
+export type ProcessState = "resident" | "starting" | "absent" | "cleanup_uncertain";
+export interface AgentSummary {
+    readonly id: string;
+    readonly name: string;
+    readonly state: AgentState;
+    readonly process: {
+        readonly state: ProcessState;
+    };
+    readonly session: {
+        readonly path: string | null;
+        readonly id: string | null;
+    };
+    readonly error?: {
+        readonly code: string;
+    } | undefined;
+}
+export declare const PI_FLEET_ERROR_CODES: readonly ["agent_busy", "agent_destroyed", "agent_destroying", "agent_not_found", "capacity_exceeded", "cancelled", "compaction_failed", "compaction_uncertain", "cursor_expired", "cursor_invalid", "cursor_wrong_agent", "delivery_uncertain", "destroy_incomplete", "incarnation_cleanup_uncertain", "internal_error", "invalid_arguments", "invalid_request", "name_taken", "nothing_to_compact", "observation_uncertain", "operation_conflict", "operation_in_progress", "pi_installation_changed", "pi_not_executable", "pi_not_found", "pi_runtime_mismatch", "pi_service_mismatch", "pi_start_failed", "pi_version_unavailable", "pi_version_unsupported", "protocol_error", "protocol_incompatible", "receive_resource_exhausted", "runtime_interrupted", "runtime_unavailable", "runtime_upgrade_deferred", "semantic_event_too_large", "stale_agent", "state_corrupt", "storage_unavailable", "timeout"];
+export type PiFleetErrorCode = (typeof PI_FLEET_ERROR_CODES)[number];
+export declare function isPiFleetErrorCode(value: unknown): value is PiFleetErrorCode;
+export interface SemanticEventBase {
+    readonly id: AgentEventId;
+    readonly activityId: ActivityId;
+    readonly agentId: AgentId;
+    readonly cursor: ReceiveCursor;
+    readonly epoch: ContinuityEpoch;
+    readonly sourceRawPosition: number;
+    readonly observedAt: string;
+}
+export interface AssistantThinkingStartedEvent extends SemanticEventBase {
+    readonly type: "assistant.thinking.started";
+}
+export interface AssistantThinkingFinishedEvent extends SemanticEventBase {
+    readonly type: "assistant.thinking.finished";
+    readonly text: string;
+}
+export interface AssistantMessageStartedEvent extends SemanticEventBase {
+    readonly type: "assistant.message.started";
+}
+export interface AssistantMessageFinishedEvent extends SemanticEventBase {
+    readonly type: "assistant.message.finished";
+    readonly text: string;
+}
+export interface ToolExecutionStartedEvent extends SemanticEventBase {
+    readonly type: "tool.execution.started";
+    readonly tool: {
+        readonly callId: string;
+        readonly name: string;
+        readonly input: unknown;
+    };
+}
+export interface ToolExecutionFinishedEvent extends SemanticEventBase {
+    readonly type: "tool.execution.finished";
+    readonly tool: {
+        readonly callId: string;
+        readonly name: string;
+        readonly input: unknown;
+        readonly output: unknown;
+        readonly isError: boolean;
+    };
+}
+export type SemanticEvent = AssistantThinkingStartedEvent | AssistantThinkingFinishedEvent | AssistantMessageStartedEvent | AssistantMessageFinishedEvent | ToolExecutionStartedEvent | ToolExecutionFinishedEvent;
+export interface ReceiveStream extends AsyncIterable<SemanticEvent> {
+    /** Cursor for the registered replay/live boundary, available before the first event. */
+    readonly cursor: ReceiveCursor;
+}

package/dist/client/fleet-client.d.ts

@@ -0,0 +1,118 @@
+import type { Readable, Writable } from "node:stream";
+import type { AgentSummary, PiFleetErrorCode, ReceiveCursor, SemanticEvent } from "./contracts.js";
+import type { ReceiveStart } from "./agent-target.js";
+import type { Result } from "../shared/result.js";
+export type { AgentSummary, AgentState, PiFleetErrorCode as FleetClientErrorCode, ProcessState, } from "./contracts.js";
+export interface CreateInput {
+    readonly name: string;
+    readonly instructions?: string;
+    readonly cwd: string;
+    readonly piArgv: readonly string[];
+}
+export interface SendInput {
+    readonly name: string;
+    readonly expectedAgentId?: string;
+    readonly message: string;
+    readonly delivery?: "steer" | "followUp";
+}
+export interface ReceiveInput {
+    readonly name: string;
+    readonly expectedAgentId?: string;
+    readonly start?: ReceiveStart;
+    readonly untilIdle?: boolean;
+}
+export interface StatusInput {
+    readonly name: string;
+    readonly expectedAgentId?: string;
+}
+export interface DestroyInput {
+    readonly name: string;
+    readonly expectedAgentId?: string;
+}
+export interface CompactInput {
+    readonly name: string;
+    readonly expectedAgentId?: string;
+}
+export interface OperationIdentity {
+    readonly operationId: string;
+    readonly createdAt: string;
+}
+export interface RequestOptions {
+    readonly signal: AbortSignal;
+    readonly timeoutMs?: number;
+}
+export interface MutationOptions extends RequestOptions {
+    readonly operation: OperationIdentity;
+}
+export interface FleetClientError {
+    /** Codes are intentionally content-safe; payload-bearing details remain optional and redacted. */
+    readonly code: PiFleetErrorCode;
+    readonly message: string;
+    readonly details?: Readonly<Record<string, unknown>>;
+}
+export interface CreateResult {
+    readonly schemaVersion: 1;
+    readonly type: "agent.created";
+    readonly agent: AgentSummary;
+}
+export interface SendResult {
+    readonly schemaVersion: 1;
+    readonly type: "message.accepted";
+    readonly agent: {
+        readonly id: string;
+        readonly name: string;
+    };
+    readonly acceptedAt: string;
+}
+export type ReceiveStreamItem = {
+    readonly type: "ready";
+    readonly cursor: ReceiveCursor;
+} | {
+    readonly type: "event";
+    readonly cursor: ReceiveCursor;
+    readonly event: SemanticEvent;
+};
+export interface StatusResult {
+    readonly schemaVersion: 1;
+    readonly type: "agent.status";
+    readonly agent: AgentSummary;
+}
+export interface ListResult {
+    readonly schemaVersion: 1;
+    readonly type: "agent.list";
+    readonly agents: readonly AgentSummary[];
+}
+export interface DestroyResult {
+    readonly schemaVersion: 1;
+    readonly type: "agent.destroyed";
+    readonly agent: {
+        readonly id: string;
+        readonly name: string;
+    };
+}
+export interface CompactResult {
+    readonly schemaVersion: 1;
+    readonly type: "agent.compacted";
+    readonly agent: {
+        readonly id: string;
+        readonly name: string;
+    };
+    readonly compaction: {
+        readonly tokensBefore: number;
+        readonly estimatedTokensAfter?: number;
+    };
+}
+export interface FleetClient {
+    create(input: CreateInput, options: MutationOptions): Promise<Result<CreateResult, FleetClientError>>;
+    send(input: SendInput, options: MutationOptions): Promise<Result<SendResult, FleetClientError>>;
+    receive(input: ReceiveInput, options: RequestOptions): AsyncIterable<Result<ReceiveStreamItem, FleetClientError>>;
+    status(input: StatusInput, options: RequestOptions): Promise<Result<StatusResult, FleetClientError>>;
+    list(options: RequestOptions): Promise<Result<ListResult, FleetClientError>>;
+    destroy(input: DestroyInput, options: MutationOptions): Promise<Result<DestroyResult, FleetClientError>>;
+    compact(input: CompactInput, options: MutationOptions): Promise<Result<CompactResult, FleetClientError>>;
+}
+export interface CliIo {
+    readonly stdin: Readable;
+    readonly stdout: Writable;
+    readonly stderr: Writable;
+}

package/dist/client/index.d.ts

@@ -0,0 +1,4 @@
+/** Explicit connection boundary for the shared per-user pi-fleet control plane. */
+export declare const connectPiFleet: import("./sdk-facade.js").ConnectPiFleet;
+export { PiFleetError, type Agent, type AgentReceiveOptions, type CompactionSummary, type ConnectPiFleetOptions, type CreateAgentInput, type InputReceipt, type PiFleetClient, type SdkRequestOptions, type SendDelivery, } from "./sdk-facade.js";
+export type { ActivityId, AgentEventId, AgentId, AgentState, AgentSummary, AssistantMessageFinishedEvent, AssistantMessageStartedEvent, AssistantThinkingFinishedEvent, AssistantThinkingStartedEvent, PiFleetErrorCode, ProcessState, ReceiveCursor, ReceiveStream, SemanticEvent, ToolExecutionFinishedEvent, ToolExecutionStartedEvent, } from "./contracts.js";

package/dist/client/sdk-connector.d.ts

@@ -0,0 +1,7 @@
+import { type SdkConnector } from "./sdk-facade.js";
+import { type SharedClientConnection, type SharedClientConnectionOptions } from "./shared-client.js";
+export interface SdkConnectorDependencies {
+    readonly createConnection?: (options: SharedClientConnectionOptions) => SharedClientConnection;
+}
+/** Creates the concrete connector while preserving side-effect-free module evaluation. */
+export declare function createSdkConnector(dependencies?: SdkConnectorDependencies): SdkConnector;

package/dist/client/sdk-facade.d.ts

@@ -0,0 +1,84 @@
+import type { ExpectedAgentTarget, ReceiveStart } from "./agent-target.js";
+import type { AgentId, AgentSummary, PiFleetErrorCode, ReceiveCursor, ReceiveStream } from "./contracts.js";
+export type SendDelivery = "steer" | "followUp";
+export interface ConnectPiFleetOptions {
+    readonly stateRoot?: string;
+    readonly applicationRoot?: string;
+    readonly autoStartRuntime?: boolean;
+    readonly signal?: AbortSignal;
+}
+export interface CreateAgentInput {
+    readonly name: string;
+    readonly cwd: string;
+    readonly piArgs?: readonly string[];
+    readonly instructions?: string;
+}
+export interface SdkRequestOptions {
+    readonly signal?: AbortSignal;
+}
+export interface InputReceipt {
+    readonly acceptedAt: string;
+}
+export interface CompactionSummary {
+    readonly tokensBefore: number;
+    readonly estimatedTokensAfter?: number;
+}
+export type AgentReceiveOptions = {
+    readonly signal?: AbortSignal;
+} & ({
+    readonly after?: never;
+    readonly fromStart?: false;
+} | {
+    readonly after: ReceiveCursor;
+    readonly fromStart?: never;
+} | {
+    readonly after?: never;
+    readonly fromStart: true;
+});
+export interface PiFleetClient {
+    create(input: CreateAgentInput, options?: SdkRequestOptions): Promise<Agent>;
+    get(name: string, options?: SdkRequestOptions): Promise<Agent>;
+    list(options?: SdkRequestOptions): Promise<readonly AgentSummary[]>;
+    close(): Promise<void>;
+}
+export interface Agent {
+    readonly id: AgentId;
+    readonly name: string;
+    status(options?: SdkRequestOptions): Promise<AgentSummary>;
+    send(message: string, options?: {
+        readonly delivery?: SendDelivery;
+        readonly signal?: AbortSignal;
+    }): Promise<InputReceipt>;
+    receive(options?: AgentReceiveOptions): Promise<ReceiveStream>;
+    compact(options?: SdkRequestOptions): Promise<CompactionSummary>;
+    destroy(options?: SdkRequestOptions): Promise<void>;
+}
+export interface SdkTransport {
+    create(input: CreateAgentInput, signal: AbortSignal): Promise<AgentSummary>;
+    get(name: string, signal: AbortSignal): Promise<AgentSummary | null>;
+    list(signal: AbortSignal): Promise<readonly AgentSummary[]>;
+    status(target: ExpectedAgentTarget, signal: AbortSignal): Promise<AgentSummary>;
+    send(target: ExpectedAgentTarget, message: string, delivery: SendDelivery, signal: AbortSignal): Promise<InputReceipt>;
+    receive(target: ExpectedAgentTarget, start: ReceiveStart, signal: AbortSignal, untilIdle?: boolean): Promise<ReceiveStream>;
+    compact(target: ExpectedAgentTarget, signal: AbortSignal): Promise<CompactionSummary>;
+    destroy(target: ExpectedAgentTarget, signal: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}
+export interface SdkConnector {
+    connect(options: ConnectPiFleetOptions): Promise<SdkTransport>;
+}
+export type ConnectPiFleet = (options?: ConnectPiFleetOptions) => Promise<PiFleetClient>;
+/** Creates the public connector while keeping runtime discovery outside this inert module. */
+export declare function createConnectPiFleet(connector: SdkConnector): ConnectPiFleet;
+/** @internal Shared CLI/SDK construction seam; not exported by the public client entry. */
+export declare function createPiFleetClient(transport: SdkTransport): PiFleetClient;
+/** @internal CLI adapter; not exported from the public client entry. */
+export declare function agentInitialStatus(agent: Agent): AgentSummary;
+/** @internal CLI-only finite projection over the same continuous receive contract. */
+export declare function receiveAgentUntilIdle(agent: Agent, options?: SdkRequestOptions): Promise<ReceiveStream>;
+export declare class PiFleetError extends Error {
+    readonly code: PiFleetErrorCode;
+    readonly details?: Readonly<Record<string, unknown>> | undefined;
+    constructor(code: PiFleetErrorCode, message: string, details?: Readonly<Record<string, unknown>> | undefined);
+    static from(error: unknown): PiFleetError;
+}

package/dist/client/sdk-transport.d.ts

@@ -0,0 +1,24 @@
+import type { FleetClient, OperationIdentity } from "./fleet-client.js";
+import type { ExpectedAgentTarget, ReceiveStart } from "./agent-target.js";
+import { type CompactionSummary, type CreateAgentInput, type InputReceipt, type SdkTransport, type SendDelivery } from "./sdk-facade.js";
+import { type AgentSummary, type ReceiveStream } from "./contracts.js";
+export interface FleetClientSdkTransportOptions {
+    readonly reconnectDelayMs?: number;
+    readonly autoReconnect?: boolean;
+}
+/** Public-shape adapter over the private Result/wire-oriented client. */
+export declare class FleetClientSdkTransport implements SdkTransport {
+    #private;
+    private readonly client;
+    private readonly operationIds;
+    constructor(client: FleetClient, operationIds: () => OperationIdentity, options?: FleetClientSdkTransportOptions);
+    create(input: CreateAgentInput, signal: AbortSignal): Promise<AgentSummary>;
+    get(name: string, signal: AbortSignal): Promise<AgentSummary | null>;
+    list(signal: AbortSignal): Promise<readonly AgentSummary[]>;
+    status(target: ExpectedAgentTarget, signal: AbortSignal): Promise<AgentSummary>;
+    send(target: ExpectedAgentTarget, message: string, delivery: SendDelivery, signal: AbortSignal): Promise<InputReceipt>;
+    receive(target: ExpectedAgentTarget, start: ReceiveStart, signal: AbortSignal, untilIdle?: boolean): Promise<ReceiveStream>;
+    compact(target: ExpectedAgentTarget, signal: AbortSignal): Promise<CompactionSummary>;
+    destroy(target: ExpectedAgentTarget, signal: AbortSignal): Promise<void>;
+    close(): Promise<void>;
+}

package/dist/client/shared-client.d.ts

@@ -0,0 +1,18 @@
+import type { FleetClient, OperationIdentity } from "./fleet-client.js";
+export interface SharedClientConnectionOptions {
+    readonly stateRoot?: string;
+    readonly applicationRoot?: string;
+    readonly autoStartRuntime: boolean;
+    readonly env?: NodeJS.ProcessEnv;
+}
+export interface SharedClientConnection {
+    readonly client: FleetClient;
+    readonly operationIds: () => OperationIdentity;
+    readonly ensureControlPlane: () => Promise<void>;
+    readonly selectPiForMutation: () => Promise<unknown>;
+}
+/**
+ * Creates the common CLI/SDK private client graph without performing I/O.
+ * Runtime discovery and Pi selection remain lazy explicit operations.
+ */
+export declare function createSharedClientConnection(options: SharedClientConnectionOptions): SharedClientConnection;

package/dist/client/socket-fleet-client.d.ts

@@ -0,0 +1,21 @@
+import { type Socket } from "node:net";
+import { type PiRuntimeIdentity } from "../protocol/pi-identity.js";
+import { type Result } from "../shared/result.js";
+import type { CompactInput, CompactResult, CreateInput, CreateResult, DestroyInput, DestroyResult, FleetClient, FleetClientError, ListResult, MutationOptions, ReceiveInput, ReceiveStreamItem, RequestOptions, SendInput, SendResult, StatusInput, StatusResult } from "./fleet-client.js";
+export declare class SocketFleetClient implements FleetClient {
+    #private;
+    private readonly options;
+    constructor(options: {
+        readonly socketPath: string;
+        readonly beforeConnect?: () => Promise<void>;
+        readonly piIdentity?: PiRuntimeIdentity | (() => Promise<PiRuntimeIdentity>);
+    });
+    create(input: CreateInput, options: MutationOptions): Promise<Result<CreateResult, FleetClientError>>;
+    send(input: SendInput, options: MutationOptions): Promise<Result<SendResult, FleetClientError>>;
+    receive(input: ReceiveInput, options: RequestOptions): AsyncIterable<Result<ReceiveStreamItem, FleetClientError>>;
+    status(input: StatusInput, options: RequestOptions): Promise<Result<StatusResult, FleetClientError>>;
+    list(options: RequestOptions): Promise<Result<ListResult, FleetClientError>>;
+    destroy(input: DestroyInput, options: MutationOptions): Promise<Result<DestroyResult, FleetClientError>>;
+    compact(input: CompactInput, options: MutationOptions): Promise<Result<CompactResult, FleetClientError>>;
+}
+export declare function frameIterator(socket: Socket, signal: AbortSignal, maxQueuedBytes?: number): AsyncIterable<unknown>;