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

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;
+    }>;
+};

package/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/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/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);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhlp/alp-client",
-  "version": "0.0.1-beta.3",
+  "version": "0.0.1-beta.4",
   "type": "module",
   "description": "ALP client: portable JSON-RPC SDK, WebSocket and Node IPC transports, daemon discovery and setup",
   "files": [
@@ -57,6 +57,14 @@
       "types": "./dist/index.d.ts",
       "default": "./src/index.js"
     },
+    "./integration-lock": {
+      "alp-source": {
+        "types": "./src/integration-lock.js",
+        "default": "./src/integration-lock.js"
+      },
+      "types": "./dist/integration-lock.d.ts",
+      "default": "./src/integration-lock.js"
+    },
     "./ipc": {
       "alp-source": {
         "types": "./src/ipc.js",
@@ -142,8 +150,8 @@
     "node": ">=22.12"
   },
   "dependencies": {
-    "@anhlp/alp-core": "0.0.1-beta.3",
-    "@anhlp/alp-protocol": "0.0.1-beta.3"
+    "@anhlp/alp-core": "0.0.1-beta.4",
+    "@anhlp/alp-protocol": "0.0.1-beta.4"
   },
   "scripts": {
     "build": "node ../../scripts/build-workspace.mjs client",

package/src/index.js

@@ -114,6 +114,17 @@ export async function findDaemonEntry({ home = alpHome(), env = process.env, can
   return undefined;
 }
 
+/**
+ * Integration names are single lowercase path segments: they name `<home>/integrations/<name>.lock`,
+ * its guard and `<home>/<name>.json`. Returns the name, or throws a TypeError.
+ * @param {unknown} name
+ * @returns {string}
+ */
+export function assertIntegrationName(name) {
+  if (typeof name !== 'string' || !/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new TypeError(`Invalid integration name: ${JSON.stringify(name)}`);
+  return name;
+}
+
 /** Wall-clock boot time; a lock from an earlier boot is stale even if its pid is reused. */
 export function bootTime() {
   return Math.round((Date.now() - os.uptime() * 1000) / 1000);
@@ -178,6 +189,8 @@ export async function releaseDaemonLock(home) {
  * CLI, alpd's tests and the Paseo plugin use.
  */
 export class AlpClient extends AlpRpcClient {
+  /** Host features captured by connect's handshake. @type {readonly string[]} */
+  capabilities = [];
   /**
    * @param {import('node:net').Socket} socket a connected or connecting socket; the client owns it
    * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
@@ -217,7 +230,8 @@ export async function connectSocket(socketPath, options) {
 export async function connect(socketPath, client = { name: 'alp', version: '0' }, options = {}) {
   const connection = new AlpClient(await openSocket(socketPath), options);
   try {
-    await hello(connection, client);
+    const greeting = await hello(connection, client);
+    connection.capabilities = Object.freeze(Array.isArray(greeting.capabilities) ? greeting.capabilities.filter(value => typeof value === 'string') : []);
   } catch (error) {
     connection.close();
     throw error;
@@ -391,7 +405,7 @@ async function integrationCandidateFromHome(home, name) {
 }
 
 function integrationBinaryName(name) {
-  return name === 'web' ? 'alp-web-integration' : `alp-${name}-integration`;
+  return `alp-${name}-integration`;
 }
 
 /** Distribution roots that may carry a bundled integration descriptor. */
@@ -415,12 +429,26 @@ async function distributionRoots() {
   return [...new Set(roots)];
 }
 
+/**
+ * The entry of integration `name`: an environment override, a descriptor under the home or a
+ * distribution root, or an `alp-<name>-integration` binary. Discovery never returns an entry for
+ * `web`: that name belongs to alp-web, which ships with the CLI and is started with its explicit
+ * entry. Everything once registered under `web` (the descriptor `integrations/web.json`, the
+ * `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its
+ * rename to `paseo`, which must never run under the web lock. `ALP_WEB_INTEGRATION` is read for
+ * `paseo` only, after `ALP_PASEO_INTEGRATION`, for one release (like the alp-web-integration alias).
+ * @param {string} [name]
+ * @param {{ home?: string }} [options]
+ */
 export async function discoverIntegration(name = 'web', options = {}) {
-  // Explicit environment override always wins.
+  // The name becomes a descriptor path under <home>/integrations, so it must stay one safe segment.
+  assertIntegrationName(name);
+  if (name === 'web') return undefined;
+  // Explicit environment override always wins: the integration's own, then the generic one.
   const envCandidates = [
-    process.env.ALP_WEB_INTEGRATION,
+    process.env[`ALP_${name.toUpperCase()}_INTEGRATION`],
+    name === 'paseo' ? process.env.ALP_WEB_INTEGRATION : undefined,
     process.env.ALP_INTEGRATION_ENTRY,
-    name !== 'web' ? process.env[`ALP_${name.toUpperCase()}_INTEGRATION`] : undefined,
   ].filter(Boolean);
   for (const candidate of envCandidates) if (await isFile(candidate)) return candidate;
 
@@ -454,20 +482,62 @@ function integrationAlive(lock) {
   return true;
 }
 
+/**
+ * What startIntegration says about integration `name`, and where its service writes its log: alp-web
+ * (`web`) is part of the CLI, Paseo (`paseo`) an optional package, anything else named as is.
+ * @param {string} name
+ * @param {string} home
+ */
+function integrationText(name, home) {
+  const logs = path.join(home, 'logs', 'integrations');
+  if (name === 'web') return {
+    what: 'alp web',
+    log: path.join(logs, 'alp-web.log'),
+    missing: 'alp web runs the alp-web service of the ALP CLI, which is started with its entry (packages/cli/dist/alp-web.js); run `alp web`',
+  };
+  if (name === 'paseo') return {
+    what: 'The Paseo integration',
+    log: path.join(logs, 'paseo.log'),
+    missing: 'The Paseo integration is an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`), then run the command again.',
+  };
+  return {
+    what: `ALP integration ${name}`,
+    log: path.join(logs, `${name}.log`),
+    missing: `ALP integration ${name} is not installed: no ALP_${name.toUpperCase()}_INTEGRATION, descriptor <home>/integrations/${name}.json or alp-${name}-integration binary was found.`,
+  };
+}
+
+/**
+ * Starts integration `name` (default `web`) detached with `--service` (then `args`) unless its lock
+ * already names a live owner, then waits until its ready lock and `<home>/<name>.json` name the same
+ * pid. `entry` names the script to run with this Node and skips descriptor, environment and PATH
+ * discovery; `web` (alp-web) is never discovered, so it needs its entry. `"web": { "enabled": false }`
+ * in the home's settings.json refuses `web` only.
+ * @param {string | { name?: string, entry?: string, home?: string, args?: string[] }} [nameOrOptions]
+ */
 export async function startIntegration(nameOrOptions = 'web') {
   const options = typeof nameOrOptions === 'string' ? { name: nameOrOptions } : (nameOrOptions ?? {});
-  const name = options.name ?? 'web';
+  const name = assertIntegrationName(options.name ?? 'web');
+  if (options.entry !== undefined && (typeof options.entry !== 'string' || !options.entry)) throw new TypeError('startIntegration entry must be a non-empty path');
+  const args = options.args ?? [];
+  if (!Array.isArray(args) || !args.every(arg => typeof arg === 'string')) throw new TypeError('startIntegration args must be a list of strings');
   const fs = await import('node:fs/promises');
   const pathMod = await import('node:path');
   const home = options.home ? pathMod.resolve(options.home) : alpHome();
+  const text = integrationText(name, home);
+  // An explicit entry is the caller's own service script: it must exist even when a live owner is
+  // reused, and it replaces descriptor, environment and PATH discovery.
+  const explicit = options.entry !== undefined ? pathMod.resolve(options.entry) : undefined;
+  if (explicit !== undefined && !(await isFile(explicit))) throw new Error(`${text.what}: integration entry not found: ${explicit}`);
   const lockPath = pathMod.join(home, 'integrations', `${name}.lock`);
   const webPath = pathMod.join(home, `${name}.json`);
+  const started = explicit ? ` (entry ${explicit})` : '';
 
-  // Clear, actionable diagnostics for a disabled optional integration.
-  let settings = {};
-  try { settings = JSON.parse(await fs.readFile(pathMod.join(home, 'settings.json'), 'utf8')); } catch {}
-  if (settings?.web?.enabled === false) {
-    throw new Error('ALP web app is disabled by settings ("web.enabled": false).');
+  // web.enabled turns off alp web only; other integrations have their own switches.
+  if (name === 'web') {
+    let settings = {};
+    try { settings = JSON.parse(await fs.readFile(pathMod.join(home, 'settings.json'), 'utf8')); } catch {}
+    if (settings?.web?.enabled === false) throw new Error('alp web is disabled by settings ("web.enabled": false).');
   }
 
   const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
@@ -478,7 +548,7 @@ export async function startIntegration(nameOrOptions = 'web') {
     try { return JSON.parse(await fs.readFile(webPath, 'utf8')); } catch { return undefined; }
   };
 
-  // The authoritative check: the ready integration lock and live web.json must name the same pid.
+  // The authoritative check: the ready integration lock and live <name>.json must name the same pid.
   // A loser of a concurrent start accepts the winning pid after its own contender has exited or
   // the lock already names the winner.
   async function waitForReady() {
@@ -492,9 +562,9 @@ export async function startIntegration(nameOrOptions = 'web') {
       await sleep(100);
     }
     const lock = await readLock();
-    if (lock && !lock.ready) throw new Error('ALP web integration started but did not become ready; see ~/.alp/logs/integrations/paseo.log');
-    if (!lock) throw new Error('ALP web app is provided by an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`) and run `alp web` again.');
-    throw new Error('ALP web integration did not publish a matching web.json lock');
+    if (lock && !lock.ready) throw new Error(`${text.what}${started} started but did not become ready; see ${text.log}`);
+    if (!lock) throw new Error(explicit ? `${text.what}${started} did not start; see ${text.log}` : text.missing);
+    throw new Error(`${text.what}${started} did not publish a ${name}.json matching its lock; see ${text.log}`);
   }
 
   const existing = await readLock();
@@ -502,16 +572,14 @@ export async function startIntegration(nameOrOptions = 'web') {
     return waitForReady();
   }
 
-  const entry = await discoverIntegration(name, { home });
-  if (!entry) {
-    throw new Error('ALP web app is provided by an optional integration package. Install it (for example `npm install -g @anhlp/alp-paseo@beta`) and run `alp web` again.');
-  }
+  const entry = explicit ?? await discoverIntegration(name, { home });
+  if (!entry) throw new Error(text.missing);
 
   const { spawn } = await import('node:child_process');
   // The child is detached with its stdio ignored, so it cannot rely on the parent's console. `--service`
   // is the generic contract: the entry writes its own log (the path its error messages advertise) and
   // keeps the process alive as a service. `--register` still prints to stdout and is not passed here.
-  const child = spawn(process.execPath, [entry, '--service'], { stdio: 'ignore', detached: true, env: { ...process.env, ALP_HOME: home } });
+  const child = spawn(process.execPath, [entry, '--service', ...args], { stdio: 'ignore', detached: true, env: { ...process.env, ALP_HOME: home } });
   let spawnError = null;
   child.on('error', error => { spawnError = error; });
   let exited = false;
@@ -522,7 +590,7 @@ export async function startIntegration(nameOrOptions = 'web') {
   // Give the process a moment to fail immediately on missing entry or bad permissions.
   await sleep(150);
   if (spawnError) throw spawnError;
-  if (exited) throw new Error('ALP web integration failed to start; see ~/.alp/logs/integrations/paseo.log');
+  if (exited) throw new Error(`${text.what}${explicit ? started : ` (${entry})`} failed to start; see ${text.log}`);
 
   return waitForReady();
 }