@flowy-agent-store/client 0.1.0-beta.2

package/dist/index.d.cts

@@ -0,0 +1,501 @@
+import { AgentDetail, AgentRunInput, AgentSummary, CancelRunInput, ClientCapabilities, ClientInfo, ConnectorDetail, ConnectorProbeResult, ConnectorStatusView, ConnectorSummary, ContextUsage, ConversationCreateInput, ConversationEvent, ConversationMessage, ConversationMessagesPage, ConversationMessagesQuery, ConversationModelOptions, ConversationSendReceipt, ConversationUpdateInput, ConversationView, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallRequest, InstallResult, InstallStatus, MarketplaceAddRequest, MarketplaceDetail, MarketplaceRefreshResult, MarketplaceRemoveResult, MarketplaceSummary, ModelSummary, OAuthStartResult, OAuthStatusView, RunEvent, RunEventsQuery, RunReceipt, RunResult, RunStatus, RunView, ServerNotification, SkillDetail, SkillSummary, SteerRunInput, StoreInstallResult, StoreList, TeamDetail, TeamSummary, WorkspaceRevokeResult, WorkspaceView } from "@flowy-agent-store/protocol";
+//#region src/transport.d.ts
+export type NotificationListener = (notification: ServerNotification) => void;
+/**
+ * True for loopback-only URLs (`127.0.0.0/8`, `::1`, `localhost`).
+ * SDK spawn contract (docs/agent-store/12-sdk-packaging.md P0-4): an SDK
+ * must only speak the local-trusted mode over loopback; anything else is
+ * rejected before connecting.
+ */
+export declare function isLoopbackUrl(raw: string): boolean;
+/**
+ * Transport abstraction (docs/agent-store/07-typescript-sdk.md §2.3).
+ * A transport only frames JSON-RPC over some channel; the
+ * initialize → initialized → ready lifecycle lives in `AppServerClient`,
+ * so business code never knows whether it runs over WebSocket (browser),
+ * stdio (Node/CLI, future) or a one-shot HTTP binding.
+ */
+export interface Transport {
+  connect(): Promise<void>;
+  request<T>(method: string, params: unknown): Promise<T>;
+  notify(method: string, params: unknown): void;
+  onNotification(listener: NotificationListener): () => void;
+  close(): void;
+}
+export interface TransportOptions {
+  requestTimeoutMs?: number;
+  token?: string;
+}
+export declare class WebSocketTransport implements Transport {
+  private socket;
+  private nextId;
+  private pending;
+  private listeners;
+  private connectResolvers;
+  private connectRejecters;
+  private closedByCaller;
+  readonly requestTimeoutMs: number;
+  readonly url: string;
+  readonly token?: string;
+  constructor(url: string, options?: TransportOptions);
+  get connected(): boolean;
+  connect(): Promise<void>;
+  request<T>(method: string, params: unknown): Promise<T>;
+  notify(method: string, params: unknown): void;
+  onNotification(listener: NotificationListener): () => void;
+  close(): void;
+  private requireSocket;
+  private handleMessage;
+  private failAllPending;
+}
+//#endregion
+//#region src/agents.d.ts
+export declare class AgentClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List Agent Store AgentDefinitions (public summaries only). */
+  list(): Promise<AgentSummary[]>;
+  /** Fetch one AgentDefinition; raw prompts never cross the wire. */
+  get(agentId: string): Promise<AgentDetail>;
+}
+//#endregion
+//#region src/conversations.d.ts
+export declare class ConversationClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  create(input: ConversationCreateInput): Promise<ConversationView>;
+  update(conversationId: string, input: ConversationUpdateInput): Promise<ConversationView>;
+  modelOptions(): Promise<ConversationModelOptions>;
+  list(limit?: number): Promise<ConversationView[]>;
+  get(conversationId: string): Promise<ConversationView>;
+  messages(query: ConversationMessagesQuery): Promise<ConversationMessagesPage>;
+  send(conversationId: string, content: string, idempotencyKey: string): Promise<ConversationSendReceipt>;
+  cancel(conversationId: string): Promise<ConversationView>;
+  delete(conversationId: string): Promise<{
+    conversation_id: string;
+    deleted: boolean;
+  }>;
+  follow(conversationId: string): Promise<ConversationSubscription>;
+}
+export type ConversationEventListener = (event: ConversationEvent) => void;
+export type ConversationResyncListener = (reason: string) => void;
+export declare class ConversationSubscription {
+  private readonly transport;
+  readonly conversationId: string;
+  private events;
+  private resyncs;
+  private closed;
+  private lastSeenSequence;
+  private removeListener;
+  constructor(transport: Transport, conversationId: string);
+  get lastSequence(): number;
+  onEvent(listener: ConversationEventListener): () => void;
+  onResync(listener: ConversationResyncListener): () => void;
+  close(): Promise<void>;
+  private dispatch;
+}
+//#endregion
+//#region src/connectors.d.ts
+export declare class ConnectorClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List the Agent Store Connector catalog (public summaries only). */
+  list(): Promise<ConnectorSummary[]>;
+  /** Fetch one Connector detail: namespaced tools + auth state. */
+  get(connectorId: string): Promise<ConnectorDetail>;
+  /** Combined auth × probe status. `connected` only when auth is ready AND the last probe succeeded. */
+  status(connectorId: string): Promise<ConnectorStatusView>;
+  /** Run a connection probe; the server persists the result. */
+  test(connectorId: string): Promise<ConnectorProbeResult>;
+  /** Check the current OAuth state for a connector. */
+  authStatus(connectorId: string): Promise<OAuthStatusView>;
+  /**
+   * Kick off the OAuth browser flow on the trusted host. Returns the start
+   * acknowledgement immediately; poll `authStatus` until `authenticated`.
+   */
+  authStart(connectorId: string): Promise<OAuthStartResult>;
+  /** Revoke the OAuth token for a connector. */
+  logout(connectorId: string): Promise<void>;
+}
+//#endregion
+//#region src/runs.d.ts
+export declare class RunClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** Start an Agent run and return its asynchronous receipt. */
+  agent(input: AgentRunInput): Promise<RunReceipt>;
+  /** Read the authoritative run state. */
+  get(runId: string): Promise<RunView>;
+  /** Read the terminal result (fails until the run reaches a terminal state). */
+  result(runId: string): Promise<RunResult>;
+  /** Replay persisted events after a cursor. */
+  events(query: RunEventsQuery): Promise<RunEvent[]>;
+  /** Request cancellation; the terminal state is confirmed by events/run/get. */
+  cancel(input: CancelRunInput): Promise<RunView>;
+  /**
+   * Inject steering text into the currently active step of a running Agent
+   * (runtime durable conversation effect; server resolves the opaque step).
+   */
+  steer(input: SteerRunInput): Promise<RunView>;
+  /** Subscribe to best-effort realtime events for one run. */
+  follow(runId: string, options?: FollowOptions): Promise<EventSubscription>;
+}
+export interface FollowOptions {
+  /** Silent cursor catch-up after subscribe (default true). */
+  catchUp?: boolean;
+  /** Automatic `run/events`追平 on `run/resync-required` (default true). */
+  autoResync?: boolean;
+}
+export type RunEventListener = (event: RunEvent) => void;
+export type RunResyncListener = (params: {
+  run_ids: string[];
+  reason: string;
+}) => void;
+export type RunErrorListener = (error: unknown) => void;
+export declare class EventSubscription {
+  private readonly transport;
+  readonly runId: string;
+  private readonly fetchAfter?;
+  private eventListeners;
+  private resyncListeners;
+  private errorListeners;
+  private closed;
+  private unsubscribeNotification;
+  private lastSeenSequence;
+  private seenSequences;
+  private resyncInFlight;
+  private readonly autoResync;
+  constructor(transport: Transport, runId: string, fetchAfter?: ((afterSequence: number) => Promise<RunEvent[]>) | undefined, options?: FollowOptions);
+  onEvent(listener: RunEventListener): () => void;
+  onResync(listener: RunResyncListener): () => void;
+  onError(listener: RunErrorListener): () => void;
+  get lastSequence(): number;
+  close(): Promise<void>;
+  private dispatch;
+  /**
+   * Silent cursor baseline: mark already-persisted events seen WITHOUT
+   * dispatching, so the first resync never replays history as "new".
+   * For explicit history use `RunClient.events({ afterSequence: 0 })`.
+   */
+  catchUp(): Promise<void>;
+  /**
+   *追平 missed events via `run/events` after the cursor. Returned (and
+   * dispatched) in sequence order, deduplicated against live delivery.
+   * Concurrent calls share one flight.
+   */
+  resync(): Promise<RunEvent[]>;
+  private markSeen;
+  private emitEvent;
+  private emitError;
+  /** Forward transport-level errors into subscription error listeners. */
+  deliverError(error: unknown): void;
+}
+//#endregion
+//#region src/skills.d.ts
+export declare class SkillClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List the Agent Store Skill catalog (public summaries only). */
+  list(): Promise<SkillSummary[]>;
+  /** Fetch one Skill detail; instructions are a bounded public summary. */
+  get(skillId: string): Promise<SkillDetail>;
+}
+//#endregion
+//#region src/teams.d.ts
+export declare class TeamClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List AgentTeamDefinitions (fixed-member rosters). */
+  list(): Promise<TeamSummary[]>;
+  /** Fetch one TeamDefinition; planning-context bodies are never returned. */
+  get(teamId: string): Promise<TeamDetail>;
+}
+//#endregion
+//#region src/models.d.ts
+export declare class ModelClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** Enabled providers' models; `is_default` marks the `agent/run` fallback. */
+  list(): Promise<ModelSummary[]>;
+}
+//#endregion
+//#region src/workspaces.d.ts
+export declare class WorkspaceClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  list(): Promise<WorkspaceView[]>;
+  /**
+   * Validate + register (idempotently per canonical root) an absolute local
+   * directory chosen by the owner. The server canonicalizes the path and
+   * rejects links/reparse points; the returned view only carries the
+   * canonical path back to this same authenticated connection.
+   */
+  create(path: string): Promise<WorkspaceView>;
+  /**
+   * Revoke (soft-delete) an owner's active workspace. Its conversations are
+   * kept and their `workspace_id` reference is preserved, so re-registering
+   * the same path re-activates the same workspace and those conversations
+   * become visible again.
+   */
+  revoke(workspaceId: string): Promise<WorkspaceRevokeResult>;
+}
+//#endregion
+//#region src/client.d.ts
+export interface AppServerClientOptions {
+  /** Ready-made transport (07 §2.3); the host app owns its lifecycle. */
+  transport: Transport;
+  client: ClientInfo;
+  capabilities?: ClientCapabilities;
+}
+export declare class AppServerClient {
+  readonly transport: Transport;
+  /** Legacy preset/execution workflow client. */
+  readonly runs: RunClient;
+  /** Persistent presetless Nomi chat client. */
+  readonly conversations: ConversationClient;
+  /** Owner-scoped workspace registry client (user-chosen paths). */
+  readonly workspaces: WorkspaceClient;
+  /** Agent Store Skill catalog client (`skill/list`, `skill/get`). */
+  readonly skills: SkillClient;
+  /** Agent Store Connector catalog/status/probe/OAuth client. */
+  readonly connectors: ConnectorClient;
+  /** Agent Store AgentDefinition catalog client (`agent/list`, `agent/get`). */
+  readonly agents: AgentClient;
+  /** Agent Store Team catalog client (`team/list`, `team/get`). */
+  readonly teams: TeamClient;
+  /** Public model directory (`models/list`, REQ-PAR-05b). */
+  readonly models: ModelClient;
+  readonly clientInfo: ClientInfo;
+  readonly capabilities?: ClientCapabilities;
+  private initializeResult;
+  private notificationListeners;
+  constructor(options: AppServerClientOptions);
+  get ready(): boolean;
+  get initializeInfo(): InitializeResult | null;
+  /** Connect and perform the initialize/initialized handshake. */
+  connect(): Promise<InitializeResult>;
+  onNotification(listener: NotificationListener): () => void;
+  /** Close the transport; the server revokes the connection immediately. */
+  close(): void;
+  /** Import a local CodeBuddy/WorkBuddy source directory (roadmap Phase 1). */
+  runImport(input: ImportRequest): Promise<ImportResult>;
+  listImports(): Promise<ImportSummary[]>;
+  /** One immutable snapshot with its standardized components. */
+  getImport(snapshotId: string): Promise<ImportDetail>;
+  /** Install a snapshot into the runtime (roadmap Phase 2). */
+  runInstall(input: InstallRequest): Promise<InstallResult>;
+  /** Per-component installation state of a snapshot. */
+  getInstallStatus(snapshotId: string): Promise<InstallStatus>;
+  /** Disable installed components (runtime artifacts stay). */
+  disableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  /** Re-enable previously disabled components. */
+  enableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  /** Uninstall: remove runtime artifacts and clear the state (snapshot kept). */
+  uninstallInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  /** Register a marketplace source on the trusted host. */
+  addMarketplace(input: MarketplaceAddRequest): Promise<MarketplaceSummary>;
+  /** All active marketplaces. */
+  listMarketplaces(): Promise<MarketplaceSummary[]>;
+  /** One marketplace with its discovered entries. */
+  getMarketplace(marketplaceId: string): Promise<MarketplaceDetail>;
+  /** Remove a marketplace (`cascade` uninstalls snapshots installed from it). */
+  removeMarketplace(marketplaceId: string, cascade: boolean): Promise<MarketplaceRemoveResult>;
+  /** Toggle auto-update for a marketplace. */
+  setMarketplaceAutoUpdate(marketplaceId: string, enabled: boolean): Promise<MarketplaceSummary>;
+  /** Re-fetch a marketplace source and rebuild entries when the revision changed. */
+  refreshMarketplace(marketplaceId: string): Promise<MarketplaceRefreshResult>;
+  /** Import one discovered marketplace entry (provenance linked). */
+  importMarketplaceEntry(marketplaceId: string, entryName: string): Promise<ImportResult>;
+  /** All store items across enabled marketplaces (display + install state). */
+  listStore(): Promise<StoreList>;
+  /** One-click install: import (when missing) + register in one call. */
+  installStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
+}
+//#endregion
+//#region src/conversation-handle.d.ts
+/** One completed (or in-flight / timed-out) turn in a conversation. */
+export interface ConversationTurn {
+  conversation_id: string;
+  /** The user content that was submitted. */
+  content: string;
+  /** Durable user message id (`ConversationSendReceipt.message_id`). */
+  message_id: string;
+  /** Wire/billing turn id when the server assigned one. */
+  turn_id?: string | null;
+  accepted: boolean;
+  completed: boolean;
+  /** Events observed for this turn (sequence order). */
+  events: ConversationEvent[];
+  /** Terminal assistant text: `receipt.result_text` (authoritative backfill)
+   *  else aggregated from `message.delta` events. */
+  assistant_text: string | null;
+  isError: boolean;
+  result_error?: string | null;
+  result_error_code?: string | null;
+  /** Context occupancy when the runtime reported it during the turn. */
+  usage?: ContextUsage | null;
+}
+export interface ConversationTurnOptions {
+  /** Idempotency key; defaults to `crypto.randomUUID()`. */
+  idempotencyKey?: string;
+  /** Per-turn model override (applied server-side when set). */
+  model?: ConversationCreateInput["model"];
+  reasoningEffort?: string;
+}
+export declare class ConversationHandle {
+  readonly conversationId: string;
+  private readonly conversations;
+  private readonly subscription;
+  private constructor();
+  /** Create a new conversation and subscribe to its live event stream. */
+  static open(conversations: ConversationClient, input?: ConversationCreateInput): Promise<ConversationHandle>;
+  /** Attach to an existing conversation (by id) and subscribe. */
+  static attach(conversations: ConversationClient, conversationId: string): Promise<ConversationHandle>;
+  /** Register a listener for every conversation event (returns an unsubscribe). */
+  onEvent(listener: (event: ConversationEvent) => void): () => void;
+  /**
+   * Send a message (a "turn") and await its terminal state. The event collector
+   * is installed before the send so streaming deltas / usage are captured even
+   * when they arrive before the send acknowledgment is parsed.
+   */
+  send(content: string, options?: ConversationTurnOptions): Promise<ConversationTurn>;
+  /** Cancel the in-flight turn (idempotent; erases the current transcript row). */
+  cancel(): Promise<void>;
+  /** Fetch the transcript (paginated). */
+  messages(query?: Partial<ConversationMessagesQuery>): Promise<ConversationMessagesPage>;
+  /** Unsubscribe and release the handle. */
+  close(): Promise<void>;
+}
+/** Convenience: simple transcript snapshot (all roles, newest last). */
+export declare function conversationMessages(page: ConversationMessagesPage): ConversationMessage[];
+//#endregion
+//#region src/turn-result.d.ts
+/** Token/context usage for the turn (absent until the runtime projects it). */
+export interface TurnUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+}
+/** One event-derived item (plan revision, task, attempt, approval, ...). */
+export interface TurnItem {
+  sequence: number;
+  event_type: string;
+  kind: "plan" | "task" | "attempt" | "status" | "approval" | "other";
+  /** Attempt/step identity when the event payload carries one. */
+  ref_id?: string;
+  status?: string;
+  reason?: string;
+}
+/** Aggregated terminal result returned by `AgentRunHandle.finished`. */
+export interface TurnResult {
+  run_id: string;
+  status: RunStatus;
+  version: number;
+  /** Terminal assistant text (`run/result` summary). */
+  final_response: string | null;
+  output_files: string[];
+  preset_revision?: number | null;
+  content_digest?: string | null;
+  /** Persisted event stream in sequence order (authoritative backfill). */
+  events: RunEvent[];
+  /** Event-derived items in the same order. */
+  items: TurnItem[];
+  usage?: TurnUsage;
+}
+/** Build the terminal turn result from the authoritative view + event stream. */
+export declare function aggregateTurnResult(view: RunView, events: RunEvent[]): TurnResult;
+//#endregion
+//#region src/run-handle.d.ts
+/** Options for `RunClient.launch()` (Codex-parity handle). */
+export interface LaunchHandleOptions {
+  /** Whether to attach a live `EventSubscription` (default true). */
+  follow?: boolean;
+}
+/**
+ * A launched Agent run. Async-iterable over live events; await `.finished`
+ * for the blocking Codex `thread.run()` shape.
+ */
+export declare class AgentRunHandle {
+  readonly runId: string;
+  readonly receipt: RunReceipt;
+  private readonly runClient;
+  private readonly poll;
+  private subscription;
+  private terminalView;
+  private terminalResult;
+  private finishWaiters;
+  private iteratorQueue;
+  private iteratorWaiters;
+  private iteratorClosed;
+  private readonly bufferedEvents;
+  private readonly bufferedSequences;
+  constructor(runClient: RunClient, receipt: RunReceipt, subscription: EventSubscription | null, poll: (runId: string) => Promise<RunView>);
+  /**
+   * Resolves with the aggregated terminal turn result (≈ `thread.run()`):
+   * authoritative status/version plus `final_response`, output files, the
+   * persisted event stream and derived items.
+   */
+  get finished(): Promise<TurnResult>;
+  /** Latest live cursor (proxied from the subscription when attached). */
+  get lastSequence(): number;
+  /** Ask the server to cancel; terminal confirmation still arrives via events/get. */
+  cancel(): Promise<void>;
+  /**
+   * Inject steering text into the currently active step (≈ Codex turn steer).
+   * Throws `conflict` when the run already changed or has no active step —
+   * refresh `receipt`-level state via `runClient.get()` and retry.
+   */
+  steer(text: string): Promise<RunView>;
+  /** Detach the live subscription (events may still be polled via run/events). */
+  close(): Promise<void>;
+  /** Async iterator over live events (≈ `thread.runStreamed()`). */
+  [Symbol.asyncIterator](): AsyncIterator<RunEvent>;
+  private pushEvent;
+  /**
+   * Authoritative backfill for `finished`: `run/result` (terminal summary)
+   * plus the persisted `run/events` stream, falling back to the live buffer
+   * when the query fails.
+   */
+  private aggregate;
+  /** Poll run/get until terminal, then resolve all `finished` waiters once. */
+  private ensureTerminalWatch;
+}
+/** Codex-parity launch: start the run and return a live handle immediately. */
+export declare function launchRun(runClient: RunClient, input: AgentRunInput, options?: LaunchHandleOptions): Promise<AgentRunHandle>;
+//#endregion
+//#region src/retry.d.ts
+/**
+ * Retry helper (REQ-PAR-05e, ≈ Codex `retry_on_overload`): exponential backoff
+ * with jitter, driven by the protocol's stable `retryable` hint.
+ *
+ * Only errors the server/transport marks retryable are retried; protocol
+ * errors that carry `retryable: false` (validation, not_found, ...) surface
+ * immediately. `command_id` / `idempotency_key` callers stay safe because the
+ * App Server deduplicates replayed mutations.
+ */
+export interface RetryInfo {
+  /** 1-based attempt that just failed and triggered the next try. */
+  attempt: number;
+  /** Delay applied before the next attempt. */
+  delayMs: number;
+  error: unknown;
+}
+export interface RetryOptions {
+  /** Total attempts including the first (default 3). */
+  maxAttempts?: number;
+  /** First backoff delay in ms (default 500). */
+  baseDelayMs?: number;
+  /** Upper bound for one delay in ms (default 8000). */
+  maxDelayMs?: number;
+  /** Jitter fraction in [0, 1] (default 0.25 → delay ∈ [0.75×, 1.0×]). */
+  jitter?: number;
+  /** Observer hook for logging/metrics. */
+  onRetry?: (info: RetryInfo) => void;
+  /** Custom predicate; defaults to the protocol `retryable` hint. */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+  /** Deterministic delay override (tests). */
+  sleep?: (ms: number) => Promise<void>;
+}
+/** Run `operation`, retrying retryable failures with exponential backoff. */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//#endregion