@skaile/workspaces 0.8.5

package/dist/store/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../store/src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AACtD,YAAY,EACV,eAAe,EACf,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,iBAAiB,GAClB,MAAM,YAAY,CAAC"}

package/dist/store/src/react.d.ts

@@ -0,0 +1,75 @@
+import type { ResourceClient } from "./resource-client.js";
+import type { AgentStore } from "./store.js";
+import type { AgentStoreSnapshot, ConnectionStatus, ResourceClientSnapshot } from "./types.js";
+/**
+ * Subscribe to an {@link AgentStore} and re-render whenever state changes.
+ *
+ * Uses `useSyncExternalStore` internally for concurrent-mode safety. The
+ * returned snapshot is the same object reference until the next state change,
+ * so destructuring is stable across renders.
+ *
+ * @param store - The store to subscribe to.
+ * @returns Current immutable state snapshot.
+ *
+ * @example
+ * ```tsx
+ * function ChatPanel({ store }: { store: AgentStore }) {
+ *   const { messages, streamingText, phase } = useAgentStore(store)
+ *   // ...
+ * }
+ * ```
+ * @docLink packages/store/concepts#react-hooks
+ */
+export declare function useAgentStore(store: AgentStore): AgentStoreSnapshot;
+/**
+ * Return stable action dispatchers bound to an {@link AgentStore}.
+ *
+ * The returned object is referentially stable across renders (memoised on
+ * `store` identity), so it is safe to pass as a dependency to `useCallback`
+ * or `useMemo` without causing unnecessary re-computations.
+ *
+ * @param store - The store to bind actions to.
+ * @returns Object with `prompt`, `reply`, `cancel`, `loadPreviousMessages`,
+ *   and `setStatus` action functions.
+ *
+ * @example
+ * ```tsx
+ * function ChatInput({ store }: { store: AgentStore }) {
+ *   const { prompt, cancel } = useAgentStoreActions(store)
+ *   return <button onClick={() => prompt('Hello')}>Send</button>
+ * }
+ * ```
+ * @docLink packages/store/concepts#react-hooks
+ */
+export declare function useAgentStoreActions(store: AgentStore): {
+    /** Send a user prompt to the agent. */
+    prompt: (text: string) => void;
+    /** Send a reply to the agent's pending question. */
+    reply: (answer: string) => void;
+    /** Cancel the current agent turn. */
+    cancel: () => void;
+    /** Load the previous page of messages. */
+    loadPreviousMessages: () => Promise<void>;
+    /** Programmatically update the connection status. */
+    setStatus: (status: ConnectionStatus) => void;
+};
+/**
+ * Subscribe to a {@link ResourceClient} and re-render when resources change.
+ *
+ * Uses `useSyncExternalStore` for concurrent-mode safety. Re-renders only
+ * when the agent emits a `resources_available` event (typically once on connect).
+ *
+ * @param client - The resource client to subscribe to.
+ * @returns Current immutable resource snapshot (mounts + connectors).
+ *
+ * @example
+ * ```tsx
+ * function ResourcePanel({ client }: { client: ResourceClient }) {
+ *   const { mounts, connectors } = useResourceClient(client)
+ *   // ...
+ * }
+ * ```
+ * @docLink packages/store/concepts#react-hooks
+ */
+export declare function useResourceClient(client: ResourceClient): ResourceClientSnapshot;
+//# sourceMappingURL=react.d.ts.map

package/dist/store/src/react.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../../store/src/react.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,kBAAkB,EAAE,gBAAgB,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAE/F;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,UAAU,GAAG,kBAAkB,CAOnE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,UAAU;IAGhD,uCAAuC;mBACxB,MAAM;IACrB,oDAAoD;oBACpC,MAAM;IACtB,qCAAqC;;IAErC,0CAA0C;;IAE1C,qDAAqD;wBACjC,gBAAgB;EAIzC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,cAAc,GAAG,sBAAsB,CAOhF"}

package/dist/store/src/resource-client.d.ts

@@ -0,0 +1,128 @@
+import type { ConnectorContent, ConnectorEntry, ConnectorInfo, ListOptions, SearchOptions, MountInfo } from "@skaile/workspaces/types";
+import type { ConnectorStatus, ResourceClientSnapshot, StoreTransport, SubscribableStore } from "./types.js";
+/**
+ * Lazy resource browser for agent connectors.
+ *
+ * Provides a reactive list of connected mounts and connectors, and
+ * request/response methods for browsing connector contents. Shares
+ * the same transport (`send` + `onEvent`) as `AgentStore`.
+ * @docLink packages/store/concepts#resource-client
+ */
+export declare class ResourceClient implements SubscribableStore<ResourceClientSnapshot> {
+    private readonly _send;
+    private _mounts;
+    private _connectors;
+    /** Live connection status per connector, keyed by connector ID. Updated by connector_status events. */
+    connectorStatus: Map<string, ConnectorStatus>;
+    private _snapshot;
+    private readonly _listeners;
+    private readonly _pendingRequests;
+    private readonly _unsubEvent;
+    /**
+     * @param transport - Shared transport (same instance as the AgentStore for this session).
+     */
+    constructor(transport: StoreTransport);
+    /** Mounts available in this session, populated from `resources_available` events. */
+    get mounts(): readonly MountInfo[];
+    /** Tool-based connectors available in this session, populated from `resources_available` events. */
+    get connectors(): readonly ConnectorInfo[];
+    /**
+     * List directory entries at the given path within a connector.
+     *
+     * @param connectorId - ID of the connector to query.
+     * @param path - Directory path to list. Omit for the connector root.
+     * @param opts - Optional pagination and filter options.
+     * @returns Array of entries (files, directories, etc.) at the given path.
+     * @throws If the request times out or the connector returns an error.
+     */
+    list(connectorId: string, path?: string, opts?: ListOptions): Promise<ConnectorEntry[]>;
+    /**
+     * Read the content of a single resource.
+     *
+     * @param connectorId - ID of the connector to query.
+     * @param path - Full path to the resource within the connector.
+     * @returns The resource content object.
+     * @throws If the request times out or the connector returns an error.
+     */
+    read(connectorId: string, path: string): Promise<ConnectorContent>;
+    /**
+     * Write content to a resource, creating it if it does not exist.
+     *
+     * @param connectorId - ID of the connector to write to.
+     * @param path - Full path to the resource within the connector.
+     * @param content - Content to write.
+     * @throws If the request times out or the connector returns an error.
+     */
+    write(connectorId: string, path: string, content: ConnectorContent): Promise<void>;
+    /**
+     * Delete a resource from a connector.
+     *
+     * @param connectorId - ID of the connector to delete from.
+     * @param path - Full path to the resource within the connector.
+     * @throws If the request times out or the connector returns an error.
+     */
+    delete(connectorId: string, path: string): Promise<void>;
+    /**
+     * Full-text search within a connector.
+     *
+     * @param connectorId - ID of the connector to search.
+     * @param query - Search query string.
+     * @param opts - Optional search options (e.g. path prefix, result limit).
+     * @returns Matching entries, ordered by relevance as determined by the connector.
+     * @throws If the request times out or the connector returns an error.
+     */
+    search(connectorId: string, query: string, opts?: SearchOptions): Promise<ConnectorEntry[]>;
+    /**
+     * Register a change listener. Called after every resource availability change.
+     *
+     * Conforms to the `subscribe` parameter of React's `useSyncExternalStore`.
+     *
+     * @param listener - Callback invoked whenever mounts or connectors change.
+     * @returns Unsubscribe function — call to stop receiving notifications.
+     */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Return the current immutable resource snapshot.
+     *
+     * A new object is produced lazily after each `resources_available` event.
+     * Conforms to the `getSnapshot` parameter of React's `useSyncExternalStore`.
+     */
+    getSnapshot: () => ResourceClientSnapshot;
+    /**
+     * Send a `connector_config` add command to wire a new connector at runtime,
+     * without restarting the session. The runner receives this command and
+     * calls `ConnectorManager.connect()`, which fires a `connector_status` event
+     * back to the store once the connector is live.
+     *
+     * @param declaration - Connector declaration (id, driver, access level, options).
+     */
+    addConnector(declaration: {
+        id: string;
+        driver: string;
+        access?: "read-only" | "read-write";
+        options?: Record<string, unknown>;
+    }): void;
+    /**
+     * Send a `connector_config` remove command to disconnect a connector by ID
+     * without restarting the session.
+     *
+     * @param connectorId - ID of the connector to disconnect and remove.
+     */
+    removeConnector(connectorId: string): void;
+    /**
+     * Send a `connector_config` refresh command to reconnect all configured
+     * connectors (e.g. after a credentials change).
+     */
+    refreshConnectors(): void;
+    /**
+     * Unsubscribe from transport events, reject all pending requests, and
+     * clear all change listeners.
+     *
+     * All in-flight `list`/`read`/`write`/`delete`/`search` calls will reject
+     * with `"ResourceClient disposed"`.
+     */
+    dispose(): void;
+    private _handleEvent;
+    private _request;
+}
+//# sourceMappingURL=resource-client.d.ts.map

package/dist/store/src/resource-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource-client.d.ts","sourceRoot":"","sources":["../../../store/src/resource-client.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,gBAAgB,EAChB,cAAc,EACd,aAAa,EAGb,WAAW,EACX,aAAa,EACb,SAAS,EACV,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EACV,eAAe,EACf,sBAAsB,EACtB,cAAc,EACd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAIpB;;;;;;;GAOG;AACH,qBAAa,cAAe,YAAW,iBAAiB,CAAC,sBAAsB,CAAC;IAC9E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,OAAO,CAA4B;IAC3C,OAAO,CAAC,WAAW,CAAgC;IAEnD,uGAAuG;IACvG,eAAe,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAa;IAE1D,OAAO,CAAC,SAAS,CAAuC;IACxD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;IACpD,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAO7B;IACJ,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAa;IAEzC;;OAEG;gBACS,SAAS,EAAE,cAAc;IAOrC,qFAAqF;IACrF,IAAI,MAAM,IAAI,SAAS,SAAS,EAAE,CAEjC;IAED,oGAAoG;IACpG,IAAI,UAAU,IAAI,SAAS,aAAa,EAAE,CAEzC;IAID;;;;;;;;OAQG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK7F;;;;;;;OAOG;IACG,IAAI,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAKxE;;;;;;;OAOG;IACG,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIxF;;;;;;OAMG;IACG,MAAM,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D;;;;;;;;OAQG;IACG,MAAM,CACV,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,MAAM,EACb,IAAI,CAAC,EAAE,aAAa,GACnB,OAAO,CAAC,cAAc,EAAE,CAAC;IAO5B;;;;;;;OAOG;IACH,SAAS,GAAI,UAAU,MAAM,IAAI,KAAG,CAAC,MAAM,IAAI,CAAC,CAG9C;IAEF;;;;;OAKG;IACH,WAAW,QAAO,sBAAsB,CAKtC;IAIF;;;;;;;OAOG;IACH,YAAY,CAAC,WAAW,EAAE;QACxB,EAAE,EAAE,MAAM,CAAC;QACX,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,CAAC,EAAE,WAAW,GAAG,YAAY,CAAC;QACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KACnC,GAAG,IAAI;IAIR;;;;;OAKG;IACH,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAI1C;;;OAGG;IACH,iBAAiB,IAAI,IAAI;IAMzB;;;;;;OAMG;IACH,OAAO,IAAI,IAAI;IAYf,OAAO,CAAC,YAAY;IA8CpB,OAAO,CAAC,QAAQ;CAgCjB"}

package/dist/store/src/store.d.ts

@@ -0,0 +1,172 @@
+import type { AgentCommand, AgentPhase, Message } from "@skaile/workspaces/types";
+import type { AgentClientLike, AgentStoreOptions, AgentStoreSnapshot, ConnectionStatus, SubscribableStore } from "./types.js";
+/**
+ * Headless reactive store for agent conversation state.
+ *
+ * Framework-agnostic — works with React (`useSyncExternalStore`),
+ * Vue (`shallowRef` + `subscribe`), or any other UI framework.
+ *
+ * Accepts a minimal transport interface (`send` + `onEvent`) so it works
+ * with WebSocket, tRPC, SSE, or any other delivery mechanism.
+ * @docLink packages/store/concepts#agent-store
+ */
+export declare class AgentStore implements SubscribableStore<AgentStoreSnapshot> {
+    private readonly _options;
+    private _messages;
+    private _streamingText;
+    private _cancelledText;
+    private _status;
+    private _phase;
+    private _pendingQuestion;
+    private _error;
+    private _isAllLoaded;
+    private _seq;
+    private _streamingFlushed;
+    /** Shared state per store namespace — new Map instance on every mutation. */
+    private _sharedState;
+    /** Protocol v2 capability registry — new Map instance on every mutation. */
+    private _capabilities;
+    /** Protocol v2 active render invocations — new Map instance on every mutation. */
+    private _activeRenderInvocations;
+    /** Protocol v2 — most recent `protocol_info` event from the runner. */
+    private _protocolInfo;
+    /** Protocol v2 — latest incompatible-protocol notice. */
+    private _incompatibleProtocol;
+    private _snapshot;
+    private readonly _listeners;
+    private readonly _unsubEvent;
+    private readonly _unsubStatus;
+    /**
+     * @param options - Store configuration including transport and optional pagination support.
+     */
+    constructor(options: AgentStoreOptions);
+    /** Accumulated conversation messages, oldest first. */
+    get messages(): readonly Message[];
+    /** Text currently streaming from the agent. Empty when not streaming. */
+    get streamingText(): string;
+    /** Current connection lifecycle state. */
+    get status(): ConnectionStatus;
+    /** Current agent execution phase (e.g. `"idle"`, `"thinking"`, `"executing"`). */
+    get phase(): AgentPhase;
+    /** The pending question the agent is waiting for the user to answer, or null. */
+    get pendingQuestion(): AgentStoreSnapshot["pendingQuestion"];
+    /** Most recent error, or null when no error is active. */
+    get error(): AgentStoreSnapshot["error"];
+    /** Partial text that was visible when the user cancelled. Empty when not cancelled. */
+    get cancelledText(): string;
+    /** True when there are no more older messages to load via pagination. */
+    get isAllLoaded(): boolean;
+    /**
+     * Send a user prompt to the agent and optimistically update local state.
+     *
+     * Clears any previous error and cancelled text, sets phase to `"thinking"`,
+     * and appends the prompt as a local message before forwarding to the agent.
+     *
+     * @param text - The user's prompt text.
+     */
+    prompt(text: string): void;
+    /**
+     * Send a reply to the agent's pending question.
+     *
+     * Clears the pending question locally before forwarding the reply command.
+     *
+     * @param answer - The user's answer text.
+     */
+    reply(answer: string): void;
+    /**
+     * Cancel the current agent turn.
+     *
+     * Preserves partial streaming text in {@link cancelledText} so the UI can
+     * display it. Clears streaming state, resets phase to `"idle"`, and sends
+     * a `cancel` command to the agent.
+     */
+    cancel(): void;
+    /**
+     * Update shared state for a store namespace.
+     *
+     * Sends a `state_update` command to the agent and optimistically
+     * updates local state so the change is reflected immediately.
+     *
+     * @param store - Store namespace (e.g. "app", "component:render-123").
+     * @param state - Full state snapshot (replaces previous).
+     */
+    updateState(store: string, state: Record<string, unknown>): void;
+    /**
+     * Send an arbitrary command to the agent.
+     *
+     * Use this for commands that don't have a dedicated convenience method
+     * (e.g. `ui_interaction`). No local state changes — the command is
+     * forwarded as-is to the transport.
+     *
+     * @param cmd - The command to send.
+     */
+    send(cmd: AgentCommand): void;
+    /**
+     * Load the previous page of messages and prepend them to the current list.
+     *
+     * No-op when `loadMessages` was not provided at construction time or when
+     * all history has already been loaded ({@link isAllLoaded} is true).
+     * Sets {@link isAllLoaded} to true once the server returns fewer messages
+     * than the configured page size.
+     */
+    loadPreviousMessages(): Promise<void>;
+    /**
+     * Programmatically update the connection status.
+     *
+     * Called by transport wrappers that cannot use the `onStatusChange`
+     * callback (e.g. tRPC subscriptions that track status externally).
+     *
+     * @param status - The new connection status.
+     */
+    setStatus(status: ConnectionStatus): void;
+    /**
+     * Register a change listener. Called synchronously after every state change.
+     *
+     * Conforms to the `subscribe` parameter of React's `useSyncExternalStore`.
+     *
+     * @param listener - Callback invoked whenever state changes.
+     * @returns Unsubscribe function — call to stop receiving notifications.
+     */
+    subscribe: (listener: () => void) => (() => void);
+    /**
+     * Return the current immutable state snapshot.
+     *
+     * A new object is produced lazily on the first call after each state change.
+     * Subsequent calls return the same cached object until the next change.
+     * Conforms to the `getSnapshot` parameter of React's `useSyncExternalStore`.
+     */
+    getSnapshot: () => AgentStoreSnapshot;
+    /**
+     * Unsubscribe from transport events and clear all change listeners.
+     *
+     * Call this when the component or service that owns the store unmounts or
+     * shuts down to prevent memory leaks.
+     */
+    dispose(): void;
+    /**
+     * Create an {@link AgentStore} connected to a duck-typed agent client.
+     *
+     * Adapts the client's `send`/`onEvent`/`offEvent` API to the
+     * {@link StoreTransport} interface expected by the constructor, without
+     * creating a hard runtime dependency on `@skaile/workspaces/client`.
+     *
+     * @param client - Any object implementing {@link AgentClientLike}.
+     * @param opts - Optional store configuration.
+     * @param opts.sessionId - Session ID for message envelopes (defaults to a new UUID).
+     * @param opts.initialMessages - Messages to pre-populate the store with.
+     *
+     * @example
+     * ```ts
+     * const store = AgentStore.fromClient(agentClient, { sessionId: 'sess-123' })
+     * ```
+     */
+    static fromClient(client: AgentClientLike, opts?: {
+        sessionId?: string;
+        initialMessages?: Message[];
+    }): AgentStore;
+    private _handleEvent;
+    private _flushStreaming;
+    private _appendMessage;
+    private _notify;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store/src/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../../store/src/store.ts"],"names":[],"mappings":"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"}

package/dist/store/src/types.d.ts

@@ -0,0 +1,248 @@
+import type { AgentCommand, AgentEvent, AgentPhase, Capability, ConnectorInfo, IncompatibleProtocolEvent, Message, MountInfo, ProtocolInfoEvent, QuestionEvent, RenderInvokedEvent } from "@skaile/workspaces/types";
+/**
+ * Minimal transport interface shared by {@link AgentStore} and {@link ResourceClient}.
+ *
+ * Wire this to any delivery mechanism: WebSocket, tRPC subscription, SSE,
+ * or in-process callbacks for tests. Both `send` and `onEvent` must target
+ * the same underlying connection so commands and responses are correlated.
+ *
+ * @example
+ * ```ts
+ * // SSE + fetch
+ * const transport: StoreTransport = {
+ *   send: (cmd) => fetch('/api/agent', { method: 'POST', body: JSON.stringify(cmd) }),
+ *   onEvent: (handler) => {
+ *     const es = new EventSource('/api/agent/stream')
+ *     es.onmessage = (e) => handler(JSON.parse(e.data))
+ *     return () => es.close()
+ *   },
+ * }
+ * ```
+ * @docLink packages/store/concepts#transport-abstraction
+ */
+export interface StoreTransport {
+    /** Send a command to the agent backend. */
+    send(command: AgentCommand): void;
+    /**
+     * Subscribe to agent events.
+     *
+     * @param handler - Called for every incoming event.
+     * @returns Unsubscribe function — call to stop receiving events.
+     */
+    onEvent(handler: (event: AgentEvent) => void): () => void;
+}
+/**
+ * Minimal `useSyncExternalStore`-shaped subscription contract.
+ *
+ * Any object that conforms to this can be wrapped by `@skaile/workspace-bridge-react`
+ * or `@skaile/workspace-bridge-vue` (sibling packages of `@skaile/workspaces`)
+ * without modification. Both {@link AgentStore} and {@link ResourceClient}
+ * implement this interface naturally — promoting it to a named export
+ * makes the contract explicit for future stores the framework may add.
+ *
+ * @typeParam TSnapshot - Immutable snapshot type the store exposes via `getSnapshot()`.
+ *
+ * @example
+ * ```typescript
+ * // React binding (in @skaile/workspace-bridge-react)
+ * import { useSyncExternalStore } from "react";
+ * import type { SubscribableStore } from "@skaile/workspaces/store";
+ *
+ * export function useSubscribableStore<T>(store: SubscribableStore<T>): T {
+ *   return useSyncExternalStore(
+ *     (cb) => store.subscribe(cb),
+ *     () => store.getSnapshot(),
+ *     () => store.getSnapshot(),
+ *   );
+ * }
+ * ```
+ *
+ * @since 0.8.0
+ */
+export interface SubscribableStore<TSnapshot> {
+    /**
+     * Register a change listener.
+     *
+     * @param listener - Called (with no arguments) whenever a new snapshot is available.
+     * @returns Unsubscribe function — call to stop receiving change notifications.
+     */
+    subscribe(listener: () => void): () => void;
+    /**
+     * Return the current immutable snapshot.
+     *
+     * Implementations must return the same object reference between mutations
+     * so consumers (especially `useSyncExternalStore`) can detect changes
+     * via `Object.is` identity comparison.
+     */
+    getSnapshot(): TSnapshot;
+}
+/**
+ * Connection lifecycle states reported by {@link AgentStoreOptions.onStatusChange}.
+ *
+ * - `"idle"` — transport not yet connected.
+ * - `"connecting"` — transport handshake in progress.
+ * - `"connected"` — transport ready; events flowing.
+ * - `"disconnected"` — transport closed cleanly.
+ * - `"error"` — transport closed with an error.
+ * @docLink packages/store/concepts#connection-status
+ */
+export type ConnectionStatus = "idle" | "connecting" | "connected" | "disconnected" | "error";
+/**
+ * Construction options for {@link AgentStore}.
+ *
+ * Extends {@link StoreTransport} so the transport can be passed directly
+ * as an object literal without wrapping.
+ * @docLink packages/store/concepts#agent-store-options
+ */
+export interface AgentStoreOptions extends StoreTransport {
+    /** Session identifier used when creating synthetic message envelopes. */
+    sessionId: string;
+    /**
+     * Subscribe to connection status changes.
+     *
+     * @param handler - Callback invoked on every status transition.
+     * @returns Unsubscribe function.
+     */
+    onStatusChange?(handler: (status: ConnectionStatus) => void): () => void;
+    /**
+     * Load older messages for backward pagination.
+     *
+     * When provided, {@link AgentStore.loadPreviousMessages} calls this function
+     * and prepends the returned messages to the current list.
+     *
+     * @param opts.before - Return messages with seq strictly less than this value.
+     * @param opts.limit - Maximum number of messages to return.
+     */
+    loadMessages?(opts: {
+        before?: number;
+        limit?: number;
+    }): Promise<Message[]>;
+    /** Initial messages to seed the store with (e.g. from SSR or an initial API fetch). */
+    initialMessages?: Message[];
+    /** Page size used by {@link AgentStore.loadPreviousMessages} (default: 50). */
+    pageSize?: number;
+}
+/**
+ * Immutable point-in-time snapshot of {@link AgentStore} state.
+ *
+ * A new object is produced on every state change. Consumers should treat
+ * this as a value type and use object identity (`Object.is`) to detect changes.
+ * This is required for React's `useSyncExternalStore` to work correctly.
+ * @docLink packages/store/concepts#agent-store-options
+ */
+export interface AgentStoreSnapshot {
+    /** Accumulated conversation messages, oldest first. */
+    messages: readonly Message[];
+    /** Text currently streaming from the agent. Empty when not streaming. */
+    streamingText: string;
+    /** Partial text that was visible when the user cancelled. Empty when not cancelled. */
+    cancelledText: string;
+    /** Current connection lifecycle state. */
+    status: ConnectionStatus;
+    /** Current agent execution phase (e.g. `"idle"`, `"thinking"`, `"executing"`). */
+    phase: AgentPhase;
+    /** The pending question the agent is waiting for the user to answer, or null. */
+    pendingQuestion: QuestionEvent | null;
+    /** Most recent error, or null when no error is active. */
+    error: {
+        message: string;
+        fatal: boolean;
+    } | null;
+    /** True when there are no more older messages to load via pagination. */
+    isAllLoaded: boolean;
+    /**
+     * Shared state per store namespace. Updated by `state_changed` events.
+     *
+     * Namespaces include `"flow"`, `"session"`, and any custom namespaces the
+     * agent emits. Always a new `Map` instance on mutation so reactivity systems
+     * detect changes.
+     */
+    sharedState: ReadonlyMap<string, Record<string, unknown>>;
+    /**
+     * Capability registry — all capabilities the LLM can invoke this session.
+     *
+     * Populated by `capability_register` events (replay on (re)attach +
+     * mid-session registration). Removed entries by `capability_deregister`.
+     * Keyed by capability name.
+     *
+     * Frontends use this map for UI render lookup ({@link Capability.render}
+     * is set on {@link RenderCapability}). Consumers should narrow with
+     * `isRenderCapability` from `@skaile/workspaces/types`.
+     *
+     * @since 2.0.0
+     */
+    capabilities: ReadonlyMap<string, Capability>;
+    /**
+     * Most recent render invocation (one per `render_id`/`callId`). Populated
+     * by `render_invoked` events. Frontends pair these with {@link capabilities}
+     * to render the configured component.
+     *
+     * @since 2.0.0
+     */
+    activeRenderInvocations: ReadonlyMap<string, RenderInvokedEvent>;
+    /**
+     * Protocol version announced by the runner via `protocol_info`. `null`
+     * before the event arrives. Surfaced by the platform debug panel.
+     *
+     * @since 2.0.0
+     */
+    protocolInfo: ProtocolInfoEvent | null;
+    /**
+     * Latest `incompatible_protocol` event, or `null` when versions match.
+     * The platform restarts the session in response; this field powers the
+     * banner shown until the new container connects.
+     *
+     * @since 2.0.0
+     */
+    incompatibleProtocol: IncompatibleProtocolEvent | null;
+}
+/**
+ * Immutable point-in-time snapshot of {@link ResourceClient} state.
+ *
+ * Populated from the agent's `resources_available` event emitted on connect.
+ * @docLink packages/store/concepts#resource-client-snapshot
+ */
+export interface ResourceClientSnapshot {
+    /** Mounts available in this session (filesystem-backed). */
+    mounts: readonly MountInfo[];
+    /** Tool-based connectors available in this session (database, cache, etc.). */
+    connectors: readonly ConnectorInfo[];
+}
+/**
+ * Live connection status for a single connector instance.
+ *
+ * Updated by `connector_status` events emitted by the runner whenever a
+ * connector transitions between lifecycle states. Maintained as a reactive
+ * `Map<string, ConnectorStatus>` on {@link ResourceClient}.
+ * @docLink packages/store/concepts#resource-client-snapshot
+ */
+export interface ConnectorStatus {
+    /** Matches ConnectorDeclaration.id. */
+    id: string;
+    /** Driver name (e.g. "postgres"). */
+    driver: string;
+    /** Current connection state. */
+    state: "connecting" | "connected" | "error" | "disconnected";
+    /** Error message when state === "error". */
+    error?: string;
+    /** Round-trip latency in milliseconds from last health check. */
+    latencyMs?: number;
+    /** When this status was last updated. */
+    lastUpdated: Date;
+}
+/**
+ * Duck-typed subset of `AgentClient` accepted by {@link AgentStore.fromClient}.
+ *
+ * Allows the store to accept any object with compatible `send`/`onEvent`/`offEvent`
+ * methods without a hard runtime dependency on `@skaile/workspaces/client`.
+ * @docLink packages/store/concepts#transport-abstraction
+ */
+export interface AgentClientLike {
+    /** Send a command to the agent. */
+    send(command: AgentCommand): void;
+    /** Register a handler for incoming agent events. */
+    onEvent(handler: (event: AgentEvent) => void): void;
+    /** Deregister a previously registered event handler. */
+    offEvent(handler: (event: AgentEvent) => void): void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/store/src/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../store/src/types.ts"],"names":[],"mappings":"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"}