trellis/dist/client/vcs-client.d.ts

Agentic State Engine — event-sourced causal graph with branching, decision traces, and realtime sync for AI-native applications

/**
 * Trellis VCS Client — Reactive SDK
 *
 * High-level client that wraps TrellisVcsEngine with reactive signals
 * and optional PartyKit sync. Works in browsers (IndexedDB) and Node.
 *
 *   const client = await TrellisClient.open({
 *     repo: 'my-project',
 *     sync: { url: 'wss://party.trellis.dev/room/123' },
 *     persist: 'indexeddb',
 *   });
 *
 *   client.subscribe('issues', (issues) => render(issues));
 *   await client.sync();
 */
import { TrellisVcsEngine } from '../engine.js';
import type { SyncTransport } from '../sync/types.js';
import type { VcsOp } from '../vcs/types.js';
import type { IssueCreateOptions, IssueInfo } from '../vcs/issue.js';
import { Signal } from './reactive.js';
export type TrellisClientTopic = 'ops' | 'issues' | 'milestones' | 'branches' | 'syncStatus';
export interface TrellisClientSyncOptions {
    /** PartyKit room WebSocket URL. */
    url?: string;
    /** Optional auth token (JWT, passkey) — appended as `?token=` on the WS URL. */
    auth?: string;
    /** Inject a transport for tests or custom relays. Mutually exclusive with `url`. */
    transport?: SyncTransport;
    /** Logical room peer ID for sync calls. Default: `room`. */
    roomId?: string;
    /** Debounced auto-push after local writes (ms). Default: 200. Set 0 to disable. */
    pushDebounceMs?: number;
    /** Connect and catch up on open. Default: true when sync is configured. */
    connectOnOpen?: boolean;
    /**
     * Request a tail snapshot before full sync on connect/reconnect.
     * Default: 500. Set 0 to skip snapshot and use full op replay only.
     */
    snapshotMaxOps?: number;
    /** Reconnect with backoff when using `url` (PartyKit transport). Default: true. */
    reconnect?: boolean;
}
export interface TrellisClientOptions {
    /** Repository root path or logical name (for IDB). */
    repo: string;
    /** Peer/agent identity. Generated if omitted. */
    agentId?: string;
    /** Sync configuration. Omit for offline-only. */
    sync?: TrellisClientSyncOptions;
    /** Persistence backend. Default: filesystem (Node) or IndexedDB (browser). */
    persist?: 'indexeddb' | 'opfs' | 'memory';
}
export interface SyncStatus {
    /** Whether the transport connection is open (WebSocket rooms). */
    connected: boolean;
    /** Number of in-flight sync operations. */
    pending: number;
    /** Whether the client believes it is in sync with the room. */
    synced: boolean;
    /** ISO timestamp of the last successful push/pull, or null. */
    lastSyncAt: string | null;
    /** Last sync or connection error message, or null. */
    lastError: string | null;
}
/**
 * Reactive Trellis client with VCS operations and optional multiplayer sync.
 */
export declare class TrellisClient {
    private _engine;
    private _syncPeer?;
    private _peerId;
    private _opLog;
    private _roomId;
    private _pushDebounceMs;
    private _snapshotMaxOps;
    private _pushTimer?;
    private _closed;
    /** Raw causal log. Updated on every local or remote op. */
    private _ops;
    /** Sync connection state. */
    private _syncStatus;
    private _opHandlers;
    private _topicSubs;
    private constructor();
    /** Factory — opens the repo, loads ops, and optionally connects to sync. */
    static open(opts: TrellisClientOptions): Promise<TrellisClient>;
    /** Subscribe to reactive topics. Callback receives current value immediately. */
    subscribe(topic: TrellisClientTopic | string, callback: (data: unknown) => void): () => void;
    /** Listen for raw op events (local or remote). */
    on(event: 'op', handler: (op: VcsOp) => void): () => void;
    /** Create an issue and emit reactive updates. */
    createIssue(title: string, opts?: IssueCreateOptions & {
        lane?: string;
    }): Promise<VcsOp>;
    /** Force a push/pull sync with the room. */
    sync(): Promise<void>;
    /** Close (complete) an issue. */
    closeIssue(id: string, opts?: {
        confirm?: boolean;
    }): Promise<VcsOp | null>;
    /** Reopen a closed issue. */
    reopenIssue(id: string): Promise<VcsOp>;
    /** Read current ops without subscribing. */
    getOps(): VcsOp[];
    /** Read current issues without subscribing. */
    listIssues(): IssueInfo[];
    /** Clean up resources. */
    close(): void;
    /** Signal exposing the full causal op log. */
    get opsSignal(): Signal<VcsOp[]>;
    /** Signal exposing sync connection status. */
    get syncStatusSignal(): Signal<SyncStatus>;
    /** Underlying VCS engine (for advanced sync wiring and queries). */
    get engine(): TrellisVcsEngine;
    private _createTransport;
    private _createOpLog;
    private _connectTransport;
    private _connectAndCatchUp;
    private _onTransportReconnect;
    private _requestSnapshot;
    private _schedulePush;
    private _pushToRoom;
    private _refreshState;
    private _emitOp;
    private _broadcastTopic;
    private _getTopicValue;
    private _setSyncStatus;
}
//# sourceMappingURL=vcs-client.d.ts.map