@anhlp/alp 0.0.1-beta.3 → 0.0.1-beta.4

package/packages/client/dist/integration-lock.js

@@ -0,0 +1,179 @@
+// packages/client/src/integration-lock.js
+import { randomUUID } from "node:crypto";
+import { mkdir, open, rename, rmdir, unlink } from "node:fs/promises";
+import path from "node:path";
+import { assertIntegrationName, bootTime } from "./index.js";
+function createIntegrationLock(home, name) {
+  const file = path.join(home, "integrations", `${assertIntegrationName(name)}.lock`);
+  const guard = `${file}.reclaim`;
+  let phase = "new";
+  let owned;
+  const recovery = (reason) => new Error(`${reason}. Stop ALL integration processes using this ALP_HOME before manual lock-only recovery of ${file} and ${guard}; see docs/modular-monorepo.md`);
+  async function guarded(run) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 448 });
+    const deadline = Date.now() + 2e4;
+    for (; ; ) {
+      try {
+        await mkdir(guard, { mode: 448 });
+        break;
+      } catch (error) {
+        if (
+          /** @type {any} */
+          error?.code !== "EEXIST"
+        ) throw error;
+        if (Date.now() >= deadline) throw recovery("Integration mutation guard remains busy or abandoned");
+        await new Promise((resolve) => setTimeout(resolve, 25));
+      }
+    }
+    const token = path.join(guard, `owner-${process.pid}-${randomUUID()}`);
+    try {
+      const handle = await open(token, "wx", 384);
+      await handle.close();
+    } catch (error) {
+      throw recovery(`Integration guard initialization failed: ${String(error)}`);
+    }
+    try {
+      return await run();
+    } finally {
+      try {
+        await unlink(token);
+      } catch (error) {
+        throw recovery(
+          /** @type {any} */
+          error?.code === "ENOENT" ? "Integration guard ownership was lost" : `Integration guard token cleanup failed: ${String(error)}`
+        );
+      }
+      try {
+        await rmdir(guard);
+      } catch (error) {
+        throw recovery(`Integration guard cleanup failed: ${String(error)}`);
+      }
+    }
+  }
+  async function snapshot() {
+    let handle;
+    try {
+      handle = await open(file, "r");
+    } catch (error) {
+      if (
+        /** @type {any} */
+        error?.code === "ENOENT"
+      ) return void 0;
+      throw error;
+    }
+    try {
+      const info = await handle.stat();
+      const raw = await handle.readFile("utf8");
+      let value;
+      try {
+        value = JSON.parse(raw);
+      } catch {
+        value = void 0;
+      }
+      return { value, info };
+    } finally {
+      await handle.close();
+    }
+  }
+  function complete(value) {
+    return value && Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.bootTime === "number" && Number.isFinite(value.bootTime) && value.bootTime > 0 && typeof value.startedAt === "string" && Number.isFinite(Date.parse(value.startedAt)) && typeof value.ready === "boolean" && (value.lockVersion === void 0 && value.owner === void 0 || value.lockVersion === 1 && typeof value.owner === "string" && /^[a-f0-9-]{36}$/.test(value.owner));
+  }
+  function dead(value) {
+    try {
+      process.kill(value.pid, 0);
+      return false;
+    } catch (error) {
+      if (
+        /** @type {any} */
+        error?.code !== "ESRCH"
+      ) return false;
+      if (Math.abs(value.bootTime - bootTime()) > 30) throw recovery("Integration owner boot context is uncertain");
+      return true;
+    }
+  }
+  function matches(current) {
+    return !!owned && current?.value?.owner === owned.owner && current.info.dev === owned.dev && current.info.ino === owned.ino;
+  }
+  return {
+    async acquire() {
+      if (phase !== "new") throw new Error("Integration lock instance has already been used");
+      phase = "acquiring";
+      try {
+        return await guarded(async () => {
+          const current = await snapshot();
+          if (current) {
+            if (!complete(current.value)) throw recovery("Integration lock is malformed, incomplete or unsupported");
+            if (!dead(current.value)) {
+              phase = "retired";
+              return { acquired: false, lock: current.value };
+            }
+            await unlink(file);
+          }
+          const value = { pid: process.pid, bootTime: bootTime(), startedAt: (/* @__PURE__ */ new Date()).toISOString(), ready: false, lockVersion: 1, owner: randomUUID() };
+          const handle = await open(file, "wx", 384);
+          let info;
+          try {
+            await handle.writeFile(JSON.stringify(value));
+            info = await handle.stat();
+          } finally {
+            await handle.close();
+          }
+          owned = { owner: value.owner, dev: info.dev, ino: info.ino };
+          phase = "owned";
+          return { acquired: true, lock: value };
+        });
+      } catch (error) {
+        phase = "retired";
+        owned = void 0;
+        throw error;
+      }
+    },
+    async setReady(ready) {
+      if (phase !== "owned") return false;
+      return guarded(async () => {
+        if (phase !== "owned") return false;
+        const current = await snapshot();
+        if (!current || !matches(current)) {
+          phase = "retired";
+          owned = void 0;
+          return false;
+        }
+        const value = { ...current.value, ready };
+        const tmp = `${file}.${randomUUID()}.tmp`;
+        const handle = await open(tmp, "wx", 384);
+        let info;
+        try {
+          try {
+            await handle.writeFile(JSON.stringify(value));
+            info = await handle.stat();
+          } finally {
+            await handle.close();
+          }
+          await rename(tmp, file);
+          owned = { owner: value.owner, dev: info.dev, ino: info.ino };
+          return true;
+        } finally {
+          await unlink(tmp).catch((error) => {
+            if (error?.code !== "ENOENT") throw error;
+          });
+        }
+      });
+    },
+    async release() {
+      if (phase !== "owned") return false;
+      return guarded(async () => {
+        if (phase !== "owned") return false;
+        const current = await snapshot();
+        const ours = matches(current);
+        phase = "retired";
+        owned = void 0;
+        if (!ours) return false;
+        await unlink(file);
+        return true;
+      });
+    }
+  };
+}
+export {
+  createIntegrationLock
+};

package/packages/client/dist/portable.d.ts

@@ -16,3 +16,4 @@ export { AlpClientError, CLIENT_ERROR, isAlpClientError } from "./rpc/errors.js"
 export { createLineDecoder, utf8Length } from "./rpc/framing.js";
 export { MAX_TIMER_MS, timerDelay } from "./rpc/timers.js";
 export { backoffDelay, createReconnectingClient, retryable } from "./rpc/reconnect.js";
+export { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from "./rpc/registry.js";

package/packages/client/dist/portable.js

@@ -6,6 +6,7 @@ import { createLineDecoder, utf8Length } from "./rpc/framing.js";
 import { MAX_TIMER_MS, timerDelay } from "./rpc/timers.js";
 import { hello } from "./rpc/handshake.js";
 import { backoffDelay, createReconnectingClient, retryable } from "./rpc/reconnect.js";
+import { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from "./rpc/registry.js";
 export {
   AlpClientError,
   AlpRpcClient,
@@ -16,12 +17,17 @@ export {
   MAX_FRAME,
   MAX_TIMER_MS,
   PROTOCOL_VERSION,
+  attachments,
   backoffDelay,
+  base64Encode,
+  conversation,
   createLineDecoder,
   createReconnectingClient,
   hello,
   isAlpClientError,
   retryable,
+  sha256Hex,
   timerDelay,
-  utf8Length
+  utf8Length,
+  workspaceRegistry
 };

package/packages/client/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;
+    }>;
+};

package/packages/client/dist/rpc/registry.js

@@ -0,0 +1,145 @@
+// packages/client/src/rpc/registry.js
+function workspaceRegistry(client) {
+  return {
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.options']['result']>} */
+    worktreeOptions: (workspaceId) => client.request("workspace.worktree.options", { workspaceId }),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['result']>} */
+    createWorktree: (params) => client.request("workspace.worktree.create", params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['result']>} */
+    removeWorktree: (params) => client.request("workspace.worktree.remove", params),
+    /** 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) => client.request("workspace.git.status", { workspaceId }),
+    /** 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) => client.request("workspace.git.diff", params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.list']['result']>} */
+    projects: (params = {}) => client.request("project.list", params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['result']>} */
+    workspaces: (params = {}) => client.request("workspace.list", params),
+    /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.get']['result']>} */
+    get: (workspaceId) => client.request("workspace.get", { workspaceId }),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.register']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.register']['result']>} */
+    register: (params) => client.request("project.register", params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['result']>} */
+    remove: (params) => client.request("project.remove", params),
+    /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['result']>} */
+    update: (params) => client.request("workspace.update", params)
+  };
+}
+var BASE64 = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+function base64Encode(bytes) {
+  let out = "";
+  let index = 0;
+  for (; index + 2 < bytes.length; index += 3) {
+    const n = bytes[index] << 16 | bytes[index + 1] << 8 | bytes[index + 2];
+    out += BASE64[n >> 18] + BASE64[n >> 12 & 63] + BASE64[n >> 6 & 63] + BASE64[n & 63];
+  }
+  if (index < bytes.length) {
+    const n = bytes[index] << 16 | (index + 1 < bytes.length ? bytes[index + 1] : 0) << 8;
+    out += BASE64[n >> 18] + BASE64[n >> 12 & 63] + (index + 1 < bytes.length ? BASE64[n >> 6 & 63] : "=") + "=";
+  }
+  return out;
+}
+async function sha256Hex(bytes) {
+  const subtle = globalThis.crypto?.subtle;
+  if (!subtle) throw new Error("SHA-256 needs WebCrypto here; pass sha256 yourself");
+  const digest = new Uint8Array(await subtle.digest("SHA-256", bytes));
+  return Array.from(digest, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function attachments(client) {
+  const api = {
+    /** @param {Map['attachment.begin']['params']} params @returns {Promise<Map['attachment.begin']['result']>} */
+    begin: (params) => client.request("attachment.begin", params),
+    /** @param {Map['attachment.chunk']['params']} params @returns {Promise<Map['attachment.chunk']['result']>} */
+    chunk: (params) => client.request("attachment.chunk", params),
+    /** @param {Map['attachment.commit']['params']} params @returns {Promise<Map['attachment.commit']['result']>} */
+    commit: (params) => client.request("attachment.commit", params),
+    /** @param {string} uploadId @returns {Promise<Map['attachment.abort']['result']>} */
+    abort: (uploadId) => client.request("attachment.abort", { uploadId }),
+    /** Metadata only (no bytes, no path). @param {string} attachmentId @returns {Promise<Map['attachment.get']['result']>} */
+    get: (attachmentId) => client.request("attachment.get", { attachmentId }),
+    /** Refused (1004 attachment_referenced) while a prompt references it. @param {string} attachmentId @returns {Promise<Map['attachment.delete']['result']>} */
+    delete: (attachmentId) => client.request("attachment.delete", { attachmentId }),
+    /**
+     * 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
+     */
+    async upload({ sessionId, name, mimeType, data, requestId, sha256, maxChunkBytes, onProgress }) {
+      const digest = sha256 ?? await sha256Hex(data);
+      const begun = await api.begin({ sessionId, name, size: data.length, mimeType, sha256: digest, requestId });
+      if (begun.state === "committed" && begun.attachmentId) return (await api.get(begun.attachmentId)).attachment;
+      const size = Math.max(1, Math.min(begun.maxChunkBytes, maxChunkBytes ?? Infinity));
+      let offset = begun.received;
+      for (let realigned = 0; offset < data.length; ) {
+        const end = Math.min(data.length, offset + size);
+        try {
+          const { received } = await api.chunk({ uploadId: begun.uploadId, offset, data: base64Encode(data.subarray(offset, end)) });
+          offset = received;
+        } catch (error) {
+          const held = (
+            /** @type {any} */
+            error?.data
+          );
+          if (held?.reason !== "offset_mismatch" || !Number.isSafeInteger(held.received) || ++realigned > 3) throw error;
+          offset = held.received;
+          continue;
+        }
+        onProgress?.(offset, data.length);
+      }
+      return (await api.commit({ uploadId: begun.uploadId, sha256: digest })).attachment;
+    }
+  };
+  return api;
+}
+function conversation(client) {
+  return {
+    /**
+     * 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) => client.request("session.fork", params),
+    /**
+     * 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) => client.request("session.rewind", params),
+    /**
+     * 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) => client.request("session.reload", params),
+    /**
+     * 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) => client.request("session.resumeCommand", params),
+    /**
+     * 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) => client.request("session.configure", params),
+    /**
+     * 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) => client.request("session.configure.preview", params)
+  };
+}
+export {
+  attachments,
+  base64Encode,
+  conversation,
+  sha256Hex,
+  workspaceRegistry
+};

package/packages/client/dist/supervise.d.ts

@@ -9,4 +9,6 @@ export function superviseDaemon(options: {
   intervalMs?: number;
   misses?: number;
   log?: (message: string) => void;
+  /** Who keeps alpd up, for the log: "alpd started with <by>". */
+  by?: string;
 }): (() => Promise<void>) & { started: Promise<void> };

package/packages/client/dist/supervise.js

@@ -40,12 +40,12 @@ async function startDaemon({ home, entry, env = process.env, timeoutMs = 15e3, a
   });
 }
 function superviseDaemon({ home, entry, env = process.env, intervalMs = 5e3, misses = 2, log = () => {
-} }) {
+}, by }) {
   let stopped = false;
   let missed = 0;
   let starting;
-  const start = (reason) => {
-    starting ??= startDaemon({ home, entry: typeof entry === "function" ? entry() : entry, env, automatic: reason !== "started with Paseo" }).then((socket) => {
+  const start = (reason, automatic = true) => {
+    starting ??= startDaemon({ home, entry: typeof entry === "function" ? entry() : entry, env, automatic }).then((socket) => {
       if (socket) log(`alpd ${reason}`);
     }, (error) => log(`could not start alpd: ${error?.message ?? error}`)).finally(() => {
       starting = void 0;
@@ -65,7 +65,7 @@ function superviseDaemon({ home, entry, env = process.env, intervalMs = 5e3, mis
     }
     if (++missed >= misses && !stopped) await start("was down; started it again");
   };
-  const initial = start("started with Paseo");
+  const initial = start(by ? `started with ${by}` : "started", false);
   const timer = setInterval(() => {
     void check();
   }, intervalMs);