@anhlp/alp-client 0.0.0-stage → 0.0.1-beta.4

package/dist/rpc/framing.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Newline-delimited JSON framing for stream transports (a Unix socket, a named pipe, a TCP
+ * stream). Portable: strings in, strings out; the stream owner decodes bytes to text first.
+ * Message transports such as a WebSocket carry whole frames and need none of this.
+ */
+/** UTF-8 length of `text` without Buffer or TextEncoder; an unpaired surrogate counts as U+FFFD (3 bytes). @param {string} text */
+export function utf8Length(text: string): number;
+/**
+ * Splits decoded text chunks into frames. `push` returns the complete frames in order, blank
+ * lines skipped, and throws once a frame (complete or still arriving) exceeds `maxFrame` bytes;
+ * the decoder is unusable after that. Each character is measured once, so a frame that arrives
+ * in many chunks costs linear time.
+ * @param {{ maxFrame: number }} options
+ * @returns {{ push(chunk: string): string[], readonly buffered: number }}
+ */
+export function createLineDecoder({ maxFrame }: {
+    maxFrame: number;
+}): {
+    push(chunk: string): string[];
+    readonly buffered: number;
+};

package/dist/rpc/framing.js

@@ -0,0 +1,57 @@
+// packages/client/src/rpc/framing.js
+function utf8Length(text) {
+  let bytes = 0;
+  for (let index = 0; index < text.length; index++) {
+    const code = text.charCodeAt(index);
+    if (code < 128) bytes += 1;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 55296 && code <= 56319 && index + 1 < text.length && (text.charCodeAt(index + 1) & 64512) === 56320) {
+      bytes += 4;
+      index++;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+function createLineDecoder({ maxFrame }) {
+  let parts = [];
+  let bytes = 0;
+  let failed = false;
+  const overflow = () => {
+    failed = true;
+    parts = [];
+    bytes = 0;
+    return new RangeError(`Frame exceeds ${maxFrame} bytes`);
+  };
+  return {
+    push(chunk) {
+      if (failed) throw new RangeError("Line decoder already failed");
+      const frames = [];
+      let start = 0;
+      for (let index = chunk.indexOf("\n"); index >= 0; index = chunk.indexOf("\n", start)) {
+        const piece = chunk.slice(start, index);
+        bytes += utf8Length(piece);
+        if (bytes > maxFrame) throw overflow();
+        parts.push(piece);
+        const line = parts.length === 1 ? parts[0] : parts.join("");
+        parts = [];
+        bytes = 0;
+        start = index + 1;
+        if (line.trim()) frames.push(line);
+      }
+      if (start < chunk.length) {
+        const rest = chunk.slice(start);
+        bytes += utf8Length(rest);
+        if (bytes > maxFrame) throw overflow();
+        parts.push(rest);
+      }
+      return frames;
+    },
+    get buffered() {
+      return bytes;
+    }
+  };
+}
+export {
+  createLineDecoder,
+  utf8Length
+};

package/dist/rpc/handshake.d.ts

@@ -0,0 +1,19 @@
+/** @typedef {{ name: string, version: string }} ClientInfo */
+/**
+ * The version handshake every ALP connection starts with (plans/reference/ALPD.md §3): alpd
+ * answers nothing else before it. Shared by the Node `connect` and portable clients, so a change
+ * to the handshake (Task 06) lands in one place.
+ * @param {{ request(method: string, params?: unknown, options?: import('./client.js').RequestOptions): Promise<any> }} client
+ * @param {ClientInfo} [info]
+ * @param {import('./client.js').RequestOptions} [options]
+ * @returns {Promise<{ protocolVersion: number } & Record<string, unknown>>}
+ */
+export function hello(client: {
+    request(method: string, params?: unknown, options?: import("./client.js").RequestOptions): Promise<any>;
+}, info?: ClientInfo, options?: import("./client.js").RequestOptions): Promise<{
+    protocolVersion: number;
+} & Record<string, unknown>>;
+export type ClientInfo = {
+    name: string;
+    version: string;
+};

package/dist/rpc/handshake.js

@@ -0,0 +1,8 @@
+// packages/client/src/rpc/handshake.js
+import { PROTOCOL_VERSION } from "@anhlp/alp-protocol";
+function hello(client, info = { name: "alp", version: "0" }, options) {
+  return client.request("daemon.hello", { protocolVersion: PROTOCOL_VERSION, client: info }, options);
+}
+export {
+  hello
+};

package/dist/rpc/reconnect.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Keeps an ALP connection up: connects, runs the caller's `onConnect` (handshake, reattach and
+ * replay as the protocol defines them), and after a disconnect connects again with exponential
+ * backoff until stopped. A connection counts as up only once it has stayed open `stableMs`; one
+ * that drops sooner (a gateway closing right after the handshake) counts as a failed attempt, so
+ * backoff and `maxAttempts` still apply. It never resends a request: requests in flight when the connection drops
+ * reject as `disconnected`, and requests made while it is down reject at once. Whether and how to
+ * retry belongs to the caller, who knows which methods are safe to repeat.
+ */
+/**
+ * @typedef {import('./client.js').AlpTransport} AlpTransport
+ * @typedef {import('./client.js').AlpRpcClientOptions} AlpRpcClientOptions
+ * @typedef {import('./client.js').RequestOptions} RequestOptions
+ * @typedef {import('./client.js').AbortSignalLike} AbortSignalLike
+ * @typedef {'connecting' | 'open' | 'waiting' | 'stopped'} ReconnectState
+ * @typedef {{ initialMs?: number, maxMs?: number, factor?: number, jitter?: number }} Backoff
+ * @typedef {{
+ *   connect(context: { attempt: number, signal: AbortSignalLike }): Promise<AlpTransport>,
+ *   onConnect?(client: AlpRpcClient, context: { attempt: number, reconnect: boolean, signal: AbortSignalLike }): unknown,
+ *   onDisconnect?(error: Error, context: { reconnect: boolean }): void,
+ *   backoff?: Backoff,
+ *   maxAttempts?: number,
+ *   stableMs?: number,
+ *   shouldRetry?(error: Error): boolean,
+ *   client?: AlpRpcClientOptions,
+ *   random?: () => number,
+ * }} ReconnectOptions
+ * @typedef {{
+ *   readonly state: ReconnectState,
+ *   readonly client: AlpRpcClient | undefined,
+ *   readonly attempt: number,
+ *   ready(options?: { signal?: AbortSignalLike }): Promise<AlpRpcClient>,
+ *   request<T = any>(method: string, params?: unknown, options?: RequestOptions): Promise<T>,
+ *   onEvent(listener: (envelope: any) => void): () => boolean,
+ *   onNotification(listener: (method: string, params: any) => void): () => boolean,
+ *   onState(listener: (state: ReconnectState, error?: Error) => void): () => boolean,
+ *   stop(): void,
+ * }} ReconnectingClient
+ */
+/** The delay before attempt `attempt` (1-based), with ±jitter. @param {number} attempt @param {Backoff} backoff @param {() => number} random */
+export function backoffDelay(attempt: number, { initialMs, maxMs, factor, jitter }?: Backoff, random?: () => number): number;
+/**
+ * Whether a failed connect or onConnect is worth another attempt: everything but alpd refusing the
+ * handshake (ERROR.protocol, an unsupported protocol version), which retrying cannot fix.
+ * @param {Error} error
+ */
+export function retryable(error: Error): boolean;
+/**
+ * @param {ReconnectOptions} options
+ * @returns {ReconnectingClient}
+ */
+export function createReconnectingClient({ connect, onConnect, onDisconnect, backoff, maxAttempts, stableMs, shouldRetry, client: clientOptions, random }: ReconnectOptions): ReconnectingClient;
+export type AlpTransport = import("./client.js").AlpTransport;
+export type AlpRpcClientOptions = import("./client.js").AlpRpcClientOptions;
+export type RequestOptions = import("./client.js").RequestOptions;
+export type AbortSignalLike = import("./client.js").AbortSignalLike;
+export type ReconnectState = "connecting" | "open" | "waiting" | "stopped";
+export type Backoff = {
+    initialMs?: number;
+    maxMs?: number;
+    factor?: number;
+    jitter?: number;
+};
+export type ReconnectOptions = {
+    connect(context: {
+        attempt: number;
+        signal: AbortSignalLike;
+    }): Promise<AlpTransport>;
+    onConnect?(client: AlpRpcClient, context: {
+        attempt: number;
+        reconnect: boolean;
+        signal: AbortSignalLike;
+    }): unknown;
+    onDisconnect?(error: Error, context: {
+        reconnect: boolean;
+    }): void;
+    backoff?: Backoff;
+    maxAttempts?: number;
+    stableMs?: number;
+    shouldRetry?(error: Error): boolean;
+    client?: AlpRpcClientOptions;
+    random?: () => number;
+};
+export type ReconnectingClient = {
+    readonly state: ReconnectState;
+    readonly client: AlpRpcClient | undefined;
+    readonly attempt: number;
+    ready(options?: {
+        signal?: AbortSignalLike;
+    }): Promise<AlpRpcClient>;
+    request<T = any>(method: string, params?: unknown, options?: RequestOptions): Promise<T>;
+    onEvent(listener: (envelope: any) => void): () => boolean;
+    onNotification(listener: (method: string, params: any) => void): () => boolean;
+    onState(listener: (state: ReconnectState, error?: Error) => void): () => boolean;
+    stop(): void;
+};
+import { AlpRpcClient } from './client.js';

package/dist/rpc/reconnect.js

@@ -0,0 +1,227 @@
+// packages/client/src/rpc/reconnect.js
+import { AlpRpcError, ERROR } from "@anhlp/alp-protocol";
+import { AlpRpcClient } from "./client.js";
+import { AlpClientError } from "./errors.js";
+function backoffDelay(attempt, { initialMs = 250, maxMs = 1e4, factor = 2, jitter = 0.2 } = {}, random = Math.random) {
+  const base = Math.min(maxMs, initialMs * factor ** Math.max(0, attempt - 1));
+  return Math.max(0, Math.round(base * (1 + jitter * (2 * random() - 1))));
+}
+function retryable(error) {
+  return !(error instanceof AlpRpcError && error.code === ERROR.protocol);
+}
+function controller() {
+  if (typeof globalThis.AbortController === "function") {
+    const native = new globalThis.AbortController();
+    return {
+      signal: (
+        /** @type {AbortSignalLike} */
+        native.signal
+      ),
+      /** @param {unknown} reason */
+      abort: (reason) => native.abort(reason)
+    };
+  }
+  const listeners = /* @__PURE__ */ new Set();
+  const signal = {
+    aborted: false,
+    /** @type {unknown} */
+    reason: void 0,
+    /** @param {'abort'} _type @param {() => void} listener */
+    addEventListener(_type, listener) {
+      listeners.add(listener);
+    },
+    /** @param {'abort'} _type @param {() => void} listener */
+    removeEventListener(_type, listener) {
+      listeners.delete(listener);
+    }
+  };
+  return {
+    signal,
+    /** @param {unknown} reason */
+    abort(reason) {
+      if (signal.aborted) return;
+      signal.aborted = true;
+      signal.reason = reason;
+      for (const listener of [...listeners]) listener();
+      listeners.clear();
+    }
+  };
+}
+function createReconnectingClient({ connect, onConnect, onDisconnect, backoff = {}, maxAttempts = Infinity, stableMs = 5e3, shouldRetry = retryable, client: clientOptions, random = Math.random }) {
+  if (typeof connect !== "function") throw new TypeError("createReconnectingClient needs connect()");
+  let state = "connecting";
+  let current;
+  let attempt = 0;
+  let connectedBefore = false;
+  let timer;
+  const run = controller();
+  const events = /* @__PURE__ */ new Set();
+  const notifications = /* @__PURE__ */ new Set();
+  const states = /* @__PURE__ */ new Set();
+  const waiters = /* @__PURE__ */ new Set();
+  const onListenerError = clientOptions?.onListenerError ?? ((error) => {
+    setTimeout(() => {
+      throw error;
+    }, 0);
+  });
+  const dispatch = (listener, ...args) => {
+    try {
+      listener(...args);
+    } catch (error) {
+      onListenerError(error);
+    }
+  };
+  const enter = (next, error) => {
+    state = next;
+    for (const listener of [...states]) {
+      dispatch(listener, next, error);
+      if (state !== next) return;
+    }
+    if (next === "open" && current) for (const waiter of [...waiters]) {
+      waiters.delete(waiter);
+      waiter.resolve(current);
+    }
+    if (next === "stopped") for (const waiter of [...waiters]) {
+      waiters.delete(waiter);
+      waiter.reject(error ?? new AlpClientError("ALP connection stopped", { reason: "closed" }));
+    }
+  };
+  const retry = (error) => {
+    if (state === "stopped") return;
+    if (attempt >= maxAttempts || !shouldRetry(error)) return enter("stopped", error);
+    enter("waiting", error);
+    if (state !== "waiting") return;
+    timer = setTimeout(() => {
+      timer = void 0;
+      void open();
+    }, backoffDelay(attempt, backoff, random));
+  };
+  const open = async () => {
+    if (state === "stopped") return;
+    attempt++;
+    enter("connecting");
+    const { signal } = run;
+    if (state !== "connecting" || signal.aborted) return;
+    let candidate;
+    const closeCandidate = () => candidate?.close();
+    signal.addEventListener("abort", closeCandidate, { once: true });
+    try {
+      const transport = await connect({ attempt, signal });
+      if (signal.aborted) {
+        try {
+          transport.close();
+        } catch {
+        }
+        return;
+      }
+      candidate = new AlpRpcClient(transport, clientOptions);
+      candidate.onEvent((envelope) => {
+        for (const listener of [...events]) dispatch(listener, envelope);
+      });
+      candidate.onNotification((method, params) => {
+        for (const listener of [...notifications]) dispatch(listener, method, params);
+      });
+      if (onConnect) await onConnect(candidate, { attempt, reconnect: connectedBefore, signal });
+      if (signal.aborted) {
+        candidate.close();
+        return;
+      }
+      if (candidate.closed) throw new AlpClientError("ALP connection closed during onConnect", { reason: "disconnected" });
+    } catch (error) {
+      candidate?.close();
+      if (signal.aborted) return;
+      return retry(error instanceof Error ? error : new Error(String(error)));
+    } finally {
+      signal.removeEventListener("abort", closeCandidate);
+    }
+    const connected = (
+      /** @type {AlpRpcClient} */
+      candidate
+    );
+    current = connected;
+    const reconnect = connectedBefore;
+    connectedBefore = true;
+    const openedAt = Date.now();
+    connected.onClose((error) => {
+      if (current !== connected) return;
+      current = void 0;
+      if (Date.now() - openedAt >= stableMs) attempt = 0;
+      dispatch(() => onDisconnect?.(error, { reconnect }));
+      retry(error);
+    });
+    enter("open");
+  };
+  void open();
+  return {
+    get state() {
+      return state;
+    },
+    get client() {
+      return current;
+    },
+    get attempt() {
+      return attempt;
+    },
+    ready({ signal } = {}) {
+      if (state === "open" && current) return Promise.resolve(current);
+      if (state === "stopped") return Promise.reject(new AlpClientError("ALP connection stopped", { reason: "closed" }));
+      return new Promise((resolve, reject) => {
+        const waiter = {
+          /** @param {AlpRpcClient} client */
+          resolve: (client) => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve(client);
+          },
+          /** @param {Error} error */
+          reject: (error) => {
+            signal?.removeEventListener("abort", onAbort);
+            reject(error);
+          }
+        };
+        const onAbort = () => {
+          waiters.delete(waiter);
+          reject(new AlpClientError("Waiting for the ALP connection was aborted", { reason: "aborted", cause: signal?.reason }));
+        };
+        if (signal?.aborted) return onAbort();
+        waiters.add(waiter);
+        signal?.addEventListener("abort", onAbort, { once: true });
+      });
+    },
+    request(method, params, options) {
+      if (state !== "open" || !current) return Promise.reject(new AlpClientError("ALP daemon connection closed", { reason: state === "stopped" ? "closed" : "disconnected" }));
+      return current.request(method, params, options);
+    },
+    onEvent(listener) {
+      events.add(listener);
+      return () => events.delete(listener);
+    },
+    onNotification(listener) {
+      notifications.add(listener);
+      return () => notifications.delete(listener);
+    },
+    onState(listener) {
+      states.add(listener);
+      return () => states.delete(listener);
+    },
+    stop() {
+      if (state === "stopped") return;
+      if (timer !== void 0) {
+        clearTimeout(timer);
+        timer = void 0;
+      }
+      run.abort(new AlpClientError("ALP connection stopped", { reason: "closed" }));
+      const last = current;
+      current = void 0;
+      enter("stopped");
+      last?.close();
+      events.clear();
+      notifications.clear();
+      states.clear();
+    }
+  };
+}
+export {
+  backoffDelay,
+  createReconnectingClient,
+  retryable
+};

package/dist/rpc/registry.d.ts

@@ -0,0 +1,211 @@
+/** Typed registry methods for portable clients. Mutations are sent once: callers retain requestId
+ * and ifRevision to reconcile a timeout by repeating the identical request. @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client */
+export function workspaceRegistry(client: {
+    request<T = any>(method: string, params?: unknown): Promise<T>;
+}): {
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.options']['result']>} */
+    worktreeOptions: (workspaceId: string) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.options"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['result']>} */
+    createWorktree: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.create"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.create"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['result']>} */
+    removeWorktree: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.remove"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.remove"]["result"]>;
+    /** Read-only Git status of a registry workspace (capability `workspace.git`, §12.5). @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.status']['result']>} */
+    gitStatus: (workspaceId: string) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.git.status"]["result"]>;
+    /** One page of a read-only Git diff; pass `nextCursor` back as `cursor` with the same comparison and path. @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.diff']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.git.diff']['result']>} */
+    gitDiff: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.git.diff"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.git.diff"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.list']['result']>} */
+    projects: (params?: import("@anhlp/alp-protocol").RpcMethodMap["project.list"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["project.list"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['result']>} */
+    workspaces: (params?: import("@anhlp/alp-protocol").RpcMethodMap["workspace.list"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.list"]["result"]>;
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.get']['result']>} */
+    get: (workspaceId: string) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.get"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.register']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.register']['result']>} */
+    register: (params: import("@anhlp/alp-protocol").RpcMethodMap["project.register"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["project.register"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['result']>} */
+    remove: (params: import("@anhlp/alp-protocol").RpcMethodMap["project.remove"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["project.remove"]["result"]>;
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['result']>} */
+    update: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.update"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.update"]["result"]>;
+};
+/** Canonical base64 of `bytes`, without Buffer or btoa, so it runs in browsers and Node alike. @param {Uint8Array} bytes */
+export function base64Encode(bytes: Uint8Array): string;
+/** Lowercase hex SHA-256 of `bytes` through WebCrypto (browsers' secure contexts, Node 19+). @param {Uint8Array} bytes */
+export function sha256Hex(bytes: Uint8Array): Promise<string>;
+/**
+ * Typed attachment methods (capability `attachments`, docs/protocol/alp-json-rpc-v1.md §12.6) and a
+ * chunked upload that keeps to the limits the daemon (or gateway) advertised. Mutations are sent
+ * once: `upload` resumes an interrupted upload by repeating its begin with the same requestId and
+ * continues from what the daemon holds.
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
+ */
+export function attachments(client: {
+    request<T = any>(method: string, params?: unknown): Promise<T>;
+}): {
+    /** @param {Map['attachment.begin']['params']} params @returns {Promise<Map['attachment.begin']['result']>} */
+    begin: (params: import("@anhlp/alp-protocol").PrincipalContext & {
+        sessionId: string;
+        name: string;
+        size: number;
+        mimeType: string;
+        sha256?: string;
+        requestId: string;
+    }) => Promise<{
+        uploadId: string;
+        state: "uploading" | "committed";
+        received: number;
+        size: number;
+        maxChunkBytes: number;
+        expiresAt?: string;
+        attachmentId?: string;
+    }>;
+    /** @param {Map['attachment.chunk']['params']} params @returns {Promise<Map['attachment.chunk']['result']>} */
+    chunk: (params: import("@anhlp/alp-protocol").PrincipalContext & {
+        uploadId: string;
+        offset: number;
+        data: string;
+    }) => Promise<{
+        received: number;
+        size: number;
+    }>;
+    /** @param {Map['attachment.commit']['params']} params @returns {Promise<Map['attachment.commit']['result']>} */
+    commit: (params: import("@anhlp/alp-protocol").PrincipalContext & {
+        uploadId: string;
+        sha256: string;
+    }) => Promise<{
+        attachment: import("@anhlp/alp-protocol").AttachmentInfo;
+    }>;
+    /** @param {string} uploadId @returns {Promise<Map['attachment.abort']['result']>} */
+    abort: (uploadId: string) => Promise<{
+        aborted: true;
+    }>;
+    /** Metadata only (no bytes, no path). @param {string} attachmentId @returns {Promise<Map['attachment.get']['result']>} */
+    get: (attachmentId: string) => Promise<{
+        attachment: import("@anhlp/alp-protocol").AttachmentInfo;
+    }>;
+    /** Refused (1004 attachment_referenced) while a prompt references it. @param {string} attachmentId @returns {Promise<Map['attachment.delete']['result']>} */
+    delete: (attachmentId: string) => Promise<{
+        deleted: true;
+    }>;
+    /**
+     * Uploads `data` and commits it: begin (or resume, with the same requestId), chunks of at most
+     * the smaller of `maxChunkBytes` and what begin answered, commit with its SHA-256. A chunk
+     * refused `offset_mismatch` continues from the daemon's `received`. Returns the attachment.
+     * @param {{ sessionId: string, name: string, mimeType: string, data: Uint8Array, requestId: string, sha256?: string, maxChunkBytes?: number, onProgress?: (received: number, size: number) => void }} options
+     */
+    upload({ sessionId, name, mimeType, data, requestId, sha256, maxChunkBytes, onProgress }: {
+        sessionId: string;
+        name: string;
+        mimeType: string;
+        data: Uint8Array;
+        requestId: string;
+        sha256?: string;
+        maxChunkBytes?: number;
+        onProgress?: (received: number, size: number) => void;
+    }): Promise<import("@anhlp/alp-protocol").AttachmentInfo>;
+};
+/**
+ * Typed conversation methods (capabilities `session.fork` and `session.rewind`, docs/protocol/
+ * alp-json-rpc-v1.md §12.7; `session.reload` and `session.resumeCommand`, §12.8). Both change the conversation only, never a file. Mutations are sent
+ * once: keep `requestId` (and `ifGeneration`) to repeat the identical request after a timeout, which
+ * answers the first result with `duplicate: true`. After a rewind, attached clients get a
+ * `history.reset` event: drop cached history, fetch a new tail and attach with its generation.
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
+ */
+export function conversation(client: {
+    request<T = any>(method: string, params?: unknown): Promise<T>;
+}): {
+    /**
+     * A new closed root whose conversation is the source root's through or before a turn (`boundary`),
+     * or a branch a rewind set aside (`branchId`); resume it with session.create { sessionId, resume: true }.
+     * Principal fields are set by a trusted gateway on its own connection, never by a remote client.
+     * @param {Map['session.fork']['params']} params @returns {Promise<Map['session.fork']['result']>}
+     */
+    fork: (params: import("@anhlp/alp-protocol").PrincipalContext & {
+        sessionId: string;
+        requestId: string;
+        ifGeneration: string;
+        boundary?: import("@anhlp/alp-protocol").ForkBoundary;
+        branchId?: string;
+        workspaceId?: string;
+        newSessionId?: string;
+        title?: string;
+    }) => Promise<{
+        session: import("@anhlp/alp-protocol").SessionSummary;
+        forkedFrom: import("@anhlp/alp-protocol").ForkProvenance;
+        duplicate?: true;
+    }>;
+    /**
+     * Continues the root's conversation from before `beforeTurnId` under the same session id; the
+     * later turns stay a branch (`branch.branchId`) that `fork({ branchId })` recovers.
+     * @param {Map['session.rewind']['params']} params @returns {Promise<Map['session.rewind']['result']>}
+     */
+    rewind: (params: {
+        sessionId: string;
+        requestId: string;
+        ifGeneration: string;
+        beforeTurnId: string;
+    }) => Promise<{
+        session: import("@anhlp/alp-protocol").SessionSummary;
+        generation: string;
+        branch: import("@anhlp/alp-protocol").ConversationBranch;
+        duplicate?: true;
+    }>;
+    /**
+     * Restarts a live root's native process on its own conversation and configuration at the idle
+     * barrier (capability `session.reload`, §12.8); id, history and receipts stay. Sent once: repeat
+     * the same `requestId` after a lost answer.
+     * @param {Map['session.reload']['params']} params @returns {Promise<Map['session.reload']['result']>}
+     */
+    reload: (params: {
+        sessionId: string;
+        requestId: string;
+        ifGeneration: string;
+    }) => Promise<{
+        session: import("@anhlp/alp-protocol").SessionSummary;
+        duplicate?: true;
+    }>;
+    /**
+     * The ALP CLI command that follows the session in a terminal (capability `session.resumeCommand`,
+     * §12.8), built by alpd: for the clipboard only, never to run.
+     * @param {Map['session.resumeCommand']['params']} params @returns {Promise<Map['session.resumeCommand']['result']>}
+     */
+    resumeCommand: (params: {
+        sessionId: string;
+    }) => Promise<import("@anhlp/alp-protocol").ResumeCommand>;
+    /**
+     * Changes a live root's model, effort or team (capability `session.configure.live`, §12.9) at the
+     * idle barrier, through a restart of its native process on the same conversation; `configured` says
+     * what it runs with now. Sent once: repeat the same `requestId` after a lost answer. A change to
+     * another runtime is refused (1005 runtime_mismatch, `data.action: 'session.create'`).
+     * @param {Map['session.configure']['params'] & { requestId: string; ifGeneration: string }} params @returns {Promise<Map['session.configure']['result']>}
+     */
+    configure: (params: {
+        sessionId: string;
+        mode?: string;
+        model?: string;
+        thinking?: string;
+        team?: string;
+        requestId?: string;
+        ifGeneration?: string;
+    } & {
+        requestId: string;
+        ifGeneration: string;
+    }) => Promise<{
+        session: import("@anhlp/alp-protocol").SessionSnapshot | import("@anhlp/alp-protocol").SessionSummary;
+        configured?: import("@anhlp/alp-protocol").ConfigureOutcome;
+        duplicate?: true;
+    }>;
+    /**
+     * What a change of model, effort, team or mode would run a live root with, and whether it would be
+     * taken now (capability `session.configure.live`, §12.9). Reads only.
+     * @param {Map['session.configure.preview']['params']} params @returns {Promise<Map['session.configure.preview']['result']>}
+     */
+    configurePreview: (params: {
+        sessionId: string;
+        mode?: string;
+        model?: string;
+        thinking?: string;
+        team?: string;
+    }) => Promise<{
+        preview: import("@anhlp/alp-protocol").ConfigurePreview;
+    }>;
+};