@anhlp/alp-client 0.0.0-beta.2 → 0.0.1-beta.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (46) hide show
  1. package/README.md +23 -1
  2. package/dist/acp-probe.d.ts +3 -2
  3. package/dist/acp-probe.js +11 -2
  4. package/dist/antigravity-probe.d.ts +1 -2
  5. package/dist/antigravity-probe.js +11 -5
  6. package/dist/command.js +3 -1
  7. package/dist/doctor.d.ts +8 -0
  8. package/dist/doctor.js +276 -13
  9. package/dist/index.d.ts +123 -8
  10. package/dist/index.js +332 -52
  11. package/dist/integration-lock.d.ts +37 -0
  12. package/dist/integration-lock.js +199 -0
  13. package/dist/mcp-probe.js +1 -1
  14. package/dist/portable.d.ts +3 -1
  15. package/dist/portable.js +11 -2
  16. package/dist/render.js +3 -0
  17. package/dist/rpc/handshake.d.ts +6 -1
  18. package/dist/rpc/handshake.js +4 -2
  19. package/dist/rpc/registry.d.ts +227 -0
  20. package/dist/rpc/registry.js +223 -0
  21. package/dist/rpc/terminal-directory.d.ts +24 -0
  22. package/dist/rpc/terminal-directory.js +70 -0
  23. package/dist/service.d.ts +2 -2
  24. package/dist/service.js +3 -1
  25. package/dist/setup.d.ts +7 -1
  26. package/dist/setup.js +159 -32
  27. package/dist/supervise.d.ts +3 -1
  28. package/dist/supervise.js +26 -16
  29. package/package.json +11 -3
  30. package/src/acp-probe.js +10 -3
  31. package/src/antigravity-probe.js +12 -5
  32. package/src/command.js +3 -1
  33. package/src/doctor.d.ts +8 -0
  34. package/src/doctor.js +345 -3
  35. package/src/index.js +411 -55
  36. package/src/integration-lock.js +203 -0
  37. package/src/mcp-probe.js +1 -1
  38. package/src/portable.js +4 -1
  39. package/src/render.js +3 -0
  40. package/src/rpc/handshake.js +7 -2
  41. package/src/rpc/registry.js +229 -0
  42. package/src/rpc/terminal-directory.js +61 -0
  43. package/src/service.js +7 -3
  44. package/src/setup.js +201 -35
  45. package/src/supervise.d.ts +3 -1
  46. package/src/supervise.js +31 -19
@@ -0,0 +1,199 @@
1
+ // packages/client/src/integration-lock.js
2
+ import { randomUUID } from "node:crypto";
3
+ import { mkdir, open, rmdir, unlink } from "node:fs/promises";
4
+ import os from "node:os";
5
+ import path from "node:path";
6
+ import { moveFile } from "@anhlp/alp-core/atomic";
7
+ import { assertIntegrationName, bootId, bootTime, isSameBoot } from "./index.js";
8
+ function createIntegrationLock(home, name) {
9
+ const file = path.join(home, "integrations", `${assertIntegrationName(name)}.lock`);
10
+ const guard = `${file}.reclaim`;
11
+ let phase = "new";
12
+ let owned;
13
+ let readyQueue = Promise.resolve();
14
+ 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`);
15
+ async function guarded(run) {
16
+ await mkdir(path.dirname(file), { recursive: true, mode: 448 });
17
+ const deadline = Date.now() + 2e4;
18
+ for (; ; ) {
19
+ try {
20
+ await mkdir(guard, { mode: 448 });
21
+ break;
22
+ } catch (error) {
23
+ if (
24
+ /** @type {any} */
25
+ error?.code !== "EEXIST"
26
+ ) throw error;
27
+ if (Date.now() >= deadline) throw recovery("Integration mutation guard remains busy or abandoned");
28
+ await new Promise((resolve) => setTimeout(resolve, 25));
29
+ }
30
+ }
31
+ const token = path.join(guard, `owner-${process.pid}-${randomUUID()}`);
32
+ try {
33
+ const handle = await open(token, "wx", 384);
34
+ await handle.close();
35
+ } catch (error) {
36
+ throw recovery(`Integration guard initialization failed: ${String(error)}`);
37
+ }
38
+ try {
39
+ return await run();
40
+ } finally {
41
+ try {
42
+ await unlink(token);
43
+ } catch (error) {
44
+ throw recovery(
45
+ /** @type {any} */
46
+ error?.code === "ENOENT" ? "Integration guard ownership was lost" : `Integration guard token cleanup failed: ${String(error)}`
47
+ );
48
+ }
49
+ try {
50
+ await rmdir(guard);
51
+ } catch (error) {
52
+ throw recovery(`Integration guard cleanup failed: ${String(error)}`);
53
+ }
54
+ }
55
+ }
56
+ async function snapshot() {
57
+ let handle;
58
+ try {
59
+ handle = await open(file, "r");
60
+ } catch (error) {
61
+ if (
62
+ /** @type {any} */
63
+ error?.code === "ENOENT"
64
+ ) return void 0;
65
+ throw error;
66
+ }
67
+ try {
68
+ const info = await handle.stat();
69
+ const raw = await handle.readFile("utf8");
70
+ let value;
71
+ try {
72
+ value = JSON.parse(raw);
73
+ } catch {
74
+ value = void 0;
75
+ }
76
+ return { value, info };
77
+ } finally {
78
+ await handle.close();
79
+ }
80
+ }
81
+ function complete(value) {
82
+ return value && Number.isSafeInteger(value.pid) && value.pid > 0 && typeof value.bootTime === "number" && Number.isFinite(value.bootTime) && value.bootTime > 0 && (value.bootId === void 0 || typeof value.bootId === "string" && value.bootId.length > 0) && (value.startedUptime === void 0 || typeof value.startedUptime === "number" && Number.isFinite(value.startedUptime)) && 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));
83
+ }
84
+ function dead(value) {
85
+ try {
86
+ process.kill(value.pid, 0);
87
+ return false;
88
+ } catch (error) {
89
+ if (
90
+ /** @type {any} */
91
+ error?.code !== "ESRCH"
92
+ ) return false;
93
+ if (!isSameBoot(value)) throw recovery("Integration owner boot context is uncertain");
94
+ return true;
95
+ }
96
+ }
97
+ function matches(current) {
98
+ return !!owned && current?.value?.owner === owned.owner && current.info.dev === owned.dev && current.info.ino === owned.ino;
99
+ }
100
+ return {
101
+ async acquire() {
102
+ if (phase !== "new") throw new Error("Integration lock instance has already been used");
103
+ phase = "acquiring";
104
+ try {
105
+ return await guarded(async () => {
106
+ const current = await snapshot();
107
+ if (current) {
108
+ if (!complete(current.value)) throw recovery("Integration lock is malformed, incomplete or unsupported");
109
+ if (!dead(current.value)) {
110
+ phase = "retired";
111
+ return { acquired: false, lock: current.value };
112
+ }
113
+ await unlink(file);
114
+ }
115
+ const currentBootId = bootId();
116
+ const value = {
117
+ pid: process.pid,
118
+ bootTime: bootTime(),
119
+ ...currentBootId ? { bootId: currentBootId } : {},
120
+ startedAt: (/* @__PURE__ */ new Date()).toISOString(),
121
+ startedUptime: Math.floor(os.uptime()),
122
+ ready: false,
123
+ lockVersion: 1,
124
+ owner: randomUUID()
125
+ };
126
+ const handle = await open(file, "wx", 384);
127
+ let info;
128
+ try {
129
+ await handle.writeFile(JSON.stringify(value));
130
+ info = await handle.stat();
131
+ } finally {
132
+ await handle.close();
133
+ }
134
+ owned = { owner: value.owner, dev: info.dev, ino: info.ino };
135
+ phase = "owned";
136
+ return { acquired: true, lock: value };
137
+ });
138
+ } catch (error) {
139
+ phase = "retired";
140
+ owned = void 0;
141
+ throw error;
142
+ }
143
+ },
144
+ async setReady(ready) {
145
+ if (phase !== "owned") return false;
146
+ const execute = async () => {
147
+ if (phase !== "owned") return false;
148
+ return guarded(async () => {
149
+ if (phase !== "owned") return false;
150
+ const current = await snapshot();
151
+ if (!current || !matches(current)) {
152
+ phase = "retired";
153
+ owned = void 0;
154
+ return false;
155
+ }
156
+ const value = { ...current.value, ready };
157
+ const tmp = `${file}.${randomUUID()}.tmp`;
158
+ const handle = await open(tmp, "wx", 384);
159
+ let info;
160
+ try {
161
+ try {
162
+ await handle.writeFile(JSON.stringify(value));
163
+ info = await handle.stat();
164
+ } finally {
165
+ await handle.close();
166
+ }
167
+ await moveFile(tmp, file);
168
+ owned = { owner: value.owner, dev: info.dev, ino: info.ino };
169
+ return true;
170
+ } finally {
171
+ await unlink(tmp).catch((error) => {
172
+ if (error?.code !== "ENOENT") throw error;
173
+ });
174
+ }
175
+ });
176
+ };
177
+ const chained = readyQueue.then(execute, execute);
178
+ readyQueue = chained.catch(() => {
179
+ });
180
+ return chained;
181
+ },
182
+ async release() {
183
+ if (phase !== "owned") return false;
184
+ return guarded(async () => {
185
+ if (phase !== "owned") return false;
186
+ const current = await snapshot();
187
+ const ours = matches(current);
188
+ phase = "retired";
189
+ owned = void 0;
190
+ if (!ours) return false;
191
+ await unlink(file);
192
+ return true;
193
+ });
194
+ }
195
+ };
196
+ }
197
+ export {
198
+ createIntegrationLock
199
+ };
package/dist/mcp-probe.js CHANGED
@@ -25,7 +25,7 @@ async function probeMcp(server, { cwd, timeoutMs = 15e3 } = {}) {
25
25
  function stdioSession(server, cwd, timeoutMs) {
26
26
  const env = { ...process.env, ...server.env ?? {} };
27
27
  const launch = launchCommand(server.command, server.args ?? [], env);
28
- const child = spawn(launch.command, launch.args, { cwd: server.cwd ?? cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: true });
28
+ const child = spawn(launch.command, launch.args, { cwd: server.cwd ?? cwd, env: launch.env ? { ...env, ...launch.env } : env, stdio: ["pipe", "pipe", "pipe"], detached: true });
29
29
  const signal = (name) => {
30
30
  try {
31
31
  process.kill(-child.pid, name);
@@ -1,4 +1,4 @@
1
- export { hello } from "./rpc/handshake.js";
1
+ export { watchTerminals } from "./rpc/terminal-directory.js";
2
2
  export type AlpTransport = import("./rpc/client.js").AlpTransport;
3
3
  export type TransportClose = import("./rpc/client.js").TransportClose;
4
4
  export type TransportState = import("./rpc/client.js").TransportState;
@@ -15,4 +15,6 @@ export { AlpRpcClient, DEFAULT_MAX_PENDING } from "./rpc/client.js";
15
15
  export { AlpClientError, CLIENT_ERROR, isAlpClientError } from "./rpc/errors.js";
16
16
  export { createLineDecoder, utf8Length } from "./rpc/framing.js";
17
17
  export { MAX_TIMER_MS, timerDelay } from "./rpc/timers.js";
18
+ export { AGENT_CAPABILITY, hello } from "./rpc/handshake.js";
18
19
  export { backoffDelay, createReconnectingClient, retryable } from "./rpc/reconnect.js";
20
+ export { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from "./rpc/registry.js";
package/dist/portable.js CHANGED
@@ -4,9 +4,12 @@ import { AlpRpcClient, DEFAULT_MAX_PENDING } from "./rpc/client.js";
4
4
  import { AlpClientError, CLIENT_ERROR, isAlpClientError } from "./rpc/errors.js";
5
5
  import { createLineDecoder, utf8Length } from "./rpc/framing.js";
6
6
  import { MAX_TIMER_MS, timerDelay } from "./rpc/timers.js";
7
- import { hello } from "./rpc/handshake.js";
7
+ import { AGENT_CAPABILITY, hello } from "./rpc/handshake.js";
8
8
  import { backoffDelay, createReconnectingClient, retryable } from "./rpc/reconnect.js";
9
+ import { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from "./rpc/registry.js";
10
+ import { watchTerminals } from "./rpc/terminal-directory.js";
9
11
  export {
12
+ AGENT_CAPABILITY,
10
13
  AlpClientError,
11
14
  AlpRpcClient,
12
15
  AlpRpcError,
@@ -16,12 +19,18 @@ export {
16
19
  MAX_FRAME,
17
20
  MAX_TIMER_MS,
18
21
  PROTOCOL_VERSION,
22
+ attachments,
19
23
  backoffDelay,
24
+ base64Encode,
25
+ conversation,
20
26
  createLineDecoder,
21
27
  createReconnectingClient,
22
28
  hello,
23
29
  isAlpClientError,
24
30
  retryable,
31
+ sha256Hex,
25
32
  timerDelay,
26
- utf8Length
33
+ utf8Length,
34
+ watchTerminals,
35
+ workspaceRegistry
27
36
  };
package/dist/render.js CHANGED
@@ -75,6 +75,9 @@ function renderLog(rootId, entries) {
75
75
  case "skill":
76
76
  text = Array.isArray(entry.roles) ? `\u2726 ${entry.agent} saved skill ${entry.name} for ${entry.roles.join(", ")}` : `\u2726 ${entry.agent} uses skill ${entry.skill}${entry.via === "skill" ? " (Skill tool)" : ""}`;
77
77
  break;
78
+ case "skill-resource":
79
+ text = `\u2726 ${entry.agent} ${entry.action === "run" ? "runs" : "reads"} ${entry.skill}/${entry.resource}`;
80
+ break;
78
81
  case "compacted":
79
82
  text = entry.failed ? `\u2717 ${entry.agent}'s context could not be compacted${entry.error ? `: ${entry.error}` : ""}` : `\u25D1 ${entry.agent}'s context compacted${entry.preTokens !== void 0 ? ` from ${tokens(entry.preTokens)}` : ""}${entry.postTokens !== void 0 ? ` to ${tokens(entry.postTokens)}` : ""}${entry.trigger === "manual" ? " on request" : ""}`;
80
83
  break;
@@ -6,13 +6,18 @@
6
6
  * @param {{ request(method: string, params?: unknown, options?: import('./client.js').RequestOptions): Promise<any> }} client
7
7
  * @param {ClientInfo} [info]
8
8
  * @param {import('./client.js').RequestOptions} [options]
9
+ * @param {{ agent?: boolean }} [principal] `agent`: an ALP agent started this process (the Node entry reads ALP_AGENT_SESSION).
9
10
  * @returns {Promise<{ protocolVersion: number } & Record<string, unknown>>}
10
11
  */
11
12
  export function hello(client: {
12
13
  request(method: string, params?: unknown, options?: import("./client.js").RequestOptions): Promise<any>;
13
- }, info?: ClientInfo, options?: import("./client.js").RequestOptions): Promise<{
14
+ }, info?: ClientInfo, options?: import("./client.js").RequestOptions, { agent }?: {
15
+ agent?: boolean;
16
+ }): Promise<{
14
17
  protocolVersion: number;
15
18
  } & Record<string, unknown>>;
19
+ /** The daemon.hello capability a process an ALP agent started announces. */
20
+ export const AGENT_CAPABILITY: "principal.agent";
16
21
  export type ClientInfo = {
17
22
  name: string;
18
23
  version: string;
@@ -1,8 +1,10 @@
1
1
  // packages/client/src/rpc/handshake.js
2
2
  import { PROTOCOL_VERSION } from "@anhlp/alp-protocol";
3
- function hello(client, info = { name: "alp", version: "0" }, options) {
4
- return client.request("daemon.hello", { protocolVersion: PROTOCOL_VERSION, client: info }, options);
3
+ var AGENT_CAPABILITY = "principal.agent";
4
+ function hello(client, info = { name: "alp", version: "0" }, options, { agent = false } = {}) {
5
+ return client.request("daemon.hello", { protocolVersion: PROTOCOL_VERSION, client: info, ...agent ? { capabilities: [AGENT_CAPABILITY] } : {} }, options);
5
6
  }
6
7
  export {
8
+ AGENT_CAPABILITY,
7
9
  hello
8
10
  };
@@ -0,0 +1,227 @@
1
+ /** Typed registry methods for portable clients. Mutations are sent once: callers retain requestId
2
+ * and ifRevision to reconcile a timeout by repeating the identical request. @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client */
3
+ export function workspaceRegistry(client: {
4
+ request<T = any>(method: string, params?: unknown): Promise<T>;
5
+ }): {
6
+ /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.options']['result']>} */
7
+ worktreeOptions: (workspaceId: string) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.options"]["result"]>;
8
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.create']['result']>} */
9
+ createWorktree: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.create"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.create"]["result"]>;
10
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.worktree.remove']['result']>} */
11
+ removeWorktree: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.remove"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.worktree.remove"]["result"]>;
12
+ /** 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']>} */
13
+ gitStatus: (workspaceId: string) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.git.status"]["result"]>;
14
+ /** 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']>} */
15
+ gitDiff: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.git.diff"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.git.diff"]["result"]>;
16
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.list']['result']>} */
17
+ projects: (params?: import("@anhlp/alp-protocol").RpcMethodMap["project.list"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["project.list"]["result"]>;
18
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['params']} [params] @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.list']['result']>} */
19
+ workspaces: (params?: import("@anhlp/alp-protocol").RpcMethodMap["workspace.list"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.list"]["result"]>;
20
+ /** @param {string} workspaceId @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.get']['result']>} */
21
+ get: (workspaceId: string) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.get"]["result"]>;
22
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.register']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.register']['result']>} */
23
+ register: (params: import("@anhlp/alp-protocol").RpcMethodMap["project.register"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["project.register"]["result"]>;
24
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['project.remove']['result']>} */
25
+ remove: (params: import("@anhlp/alp-protocol").RpcMethodMap["project.remove"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["project.remove"]["result"]>;
26
+ /** @param {import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['params']} params @returns {Promise<import('@anhlp/alp-protocol').RpcMethodMap['workspace.update']['result']>} */
27
+ update: (params: import("@anhlp/alp-protocol").RpcMethodMap["workspace.update"]["params"]) => Promise<import("@anhlp/alp-protocol").RpcMethodMap["workspace.update"]["result"]>;
28
+ };
29
+ /** Canonical base64 of `bytes`, without Buffer or btoa, so it runs in browsers and Node alike. @param {Uint8Array} bytes */
30
+ export function base64Encode(bytes: Uint8Array): string;
31
+ /** Lowercase hex SHA-256 of `bytes` through WebCrypto (browsers' secure contexts, Node 19+). @param {Uint8Array} bytes */
32
+ export function sha256Hex(bytes: Uint8Array): Promise<string>;
33
+ /**
34
+ * Typed attachment methods (capability `attachments`, docs/protocol/alp-json-rpc-v1.md §12.6) and a
35
+ * chunked upload that keeps to the limits the daemon (or gateway) advertised. Mutations are sent
36
+ * once: `upload` resumes an interrupted upload by repeating its begin with the same requestId and
37
+ * continues from what the daemon holds.
38
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
39
+ */
40
+ export function attachments(client: {
41
+ request<T = any>(method: string, params?: unknown): Promise<T>;
42
+ }): {
43
+ /** @param {Map['attachment.begin']['params']} params @returns {Promise<Map['attachment.begin']['result']>} */
44
+ begin: (params: import("@anhlp/alp-protocol").PrincipalContext & {
45
+ sessionId: string;
46
+ name: string;
47
+ size: number;
48
+ mimeType: string;
49
+ sha256?: string;
50
+ requestId: string;
51
+ }) => Promise<{
52
+ uploadId: string;
53
+ state: "uploading" | "committed";
54
+ received: number;
55
+ size: number;
56
+ maxChunkBytes: number;
57
+ expiresAt?: string;
58
+ attachmentId?: string;
59
+ }>;
60
+ /** @param {Map['attachment.chunk']['params']} params @returns {Promise<Map['attachment.chunk']['result']>} */
61
+ chunk: (params: import("@anhlp/alp-protocol").PrincipalContext & {
62
+ uploadId: string;
63
+ offset: number;
64
+ data: string;
65
+ }) => Promise<{
66
+ received: number;
67
+ size: number;
68
+ }>;
69
+ /** @param {Map['attachment.commit']['params']} params @returns {Promise<Map['attachment.commit']['result']>} */
70
+ commit: (params: import("@anhlp/alp-protocol").PrincipalContext & {
71
+ uploadId: string;
72
+ sha256: string;
73
+ }) => Promise<{
74
+ attachment: import("@anhlp/alp-protocol").AttachmentInfo;
75
+ }>;
76
+ /** @param {string} uploadId @returns {Promise<Map['attachment.abort']['result']>} */
77
+ abort: (uploadId: string) => Promise<{
78
+ aborted: true;
79
+ }>;
80
+ /** Metadata only (no bytes, no path). @param {string} attachmentId @returns {Promise<Map['attachment.get']['result']>} */
81
+ get: (attachmentId: string) => Promise<{
82
+ attachment: import("@anhlp/alp-protocol").AttachmentInfo;
83
+ }>;
84
+ /** Refused (1004 attachment_referenced) while a prompt references it. @param {string} attachmentId @returns {Promise<Map['attachment.delete']['result']>} */
85
+ delete: (attachmentId: string) => Promise<{
86
+ deleted: true;
87
+ }>;
88
+ /**
89
+ * Uploads `data` and commits it: begin (or resume, with the same requestId), chunks of at most
90
+ * the smaller of `maxChunkBytes` and what begin answered, commit with its SHA-256. A chunk
91
+ * refused `offset_mismatch` continues from the daemon's `received`. Returns the attachment.
92
+ * The returned promise exposes `.uploadId` once begun and `.abort(reason?: any)` to abort on alpd.
93
+ * @param {{ sessionId: string, name: string, mimeType: string, data: Uint8Array, requestId: string, sha256?: string, maxChunkBytes?: number, signal?: AbortSignal, onBegun?: (uploadId: string) => void, onProgress?: (received: number, size: number) => void }} options
94
+ * @returns {Promise<Map['attachment.commit']['result']['attachment']> & { readonly uploadId?: string, abort(reason?: any): Promise<void> }}
95
+ */
96
+ upload({ sessionId, name, mimeType, data, requestId, sha256, maxChunkBytes, signal, onBegun, onProgress }: {
97
+ sessionId: string;
98
+ name: string;
99
+ mimeType: string;
100
+ data: Uint8Array;
101
+ requestId: string;
102
+ sha256?: string;
103
+ maxChunkBytes?: number;
104
+ signal?: AbortSignal;
105
+ onBegun?: (uploadId: string) => void;
106
+ onProgress?: (received: number, size: number) => void;
107
+ }): Promise<import("@anhlp/alp-protocol").AttachmentInfo> & {
108
+ readonly uploadId?: string;
109
+ abort(reason?: any): Promise<void>;
110
+ };
111
+ };
112
+ /**
113
+ * Typed conversation methods (capabilities `session.fork` and `session.rewind`, docs/protocol/
114
+ * 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
115
+ * once: keep `requestId` (and `ifGeneration`) to repeat the identical request after a timeout, which
116
+ * answers the first result with `duplicate: true`. After a rewind, attached clients get a
117
+ * `history.reset` event: drop cached history, fetch a new tail and attach with its generation.
118
+ * @param {{request<T = any>(method: string, params?: unknown): Promise<T>}} client
119
+ */
120
+ export function conversation(client: {
121
+ request<T = any>(method: string, params?: unknown): Promise<T>;
122
+ }): {
123
+ /**
124
+ * A new closed root whose conversation is the source root's through or before a turn (`boundary`),
125
+ * or a branch a rewind set aside (`branchId`); resume it with session.create { sessionId, resume: true }.
126
+ * Principal fields are set by a trusted gateway on its own connection, never by a remote client.
127
+ * @param {Map['session.fork']['params']} params @returns {Promise<Map['session.fork']['result']>}
128
+ */
129
+ fork: (params: import("@anhlp/alp-protocol").PrincipalContext & {
130
+ sessionId: string;
131
+ requestId: string;
132
+ ifGeneration: string;
133
+ boundary?: import("@anhlp/alp-protocol").ForkBoundary;
134
+ branchId?: string;
135
+ workspaceId?: string;
136
+ newSessionId?: string;
137
+ title?: string;
138
+ }) => Promise<{
139
+ session: import("@anhlp/alp-protocol").SessionSummary;
140
+ forkedFrom: import("@anhlp/alp-protocol").ForkProvenance;
141
+ duplicate?: true;
142
+ }>;
143
+ /**
144
+ * Continues the root's conversation from before `beforeTurnId` under the same session id; the
145
+ * later turns stay a branch (`branch.branchId`) that `fork({ branchId })` recovers.
146
+ * @param {Map['session.rewind']['params']} params @returns {Promise<Map['session.rewind']['result']>}
147
+ */
148
+ rewind: (params: {
149
+ sessionId: string;
150
+ requestId: string;
151
+ ifGeneration: string;
152
+ beforeTurnId: string;
153
+ }) => Promise<{
154
+ session: import("@anhlp/alp-protocol").SessionSummary;
155
+ generation: string;
156
+ branch: import("@anhlp/alp-protocol").ConversationBranch;
157
+ duplicate?: true;
158
+ }>;
159
+ /**
160
+ * Restarts a live root's native process on its own conversation and configuration at the idle
161
+ * barrier (capability `session.reload`, §12.8); id, history and receipts stay. Sent once: repeat
162
+ * the same `requestId` after a lost answer.
163
+ * @param {Map['session.reload']['params']} params @returns {Promise<Map['session.reload']['result']>}
164
+ */
165
+ reload: (params: {
166
+ sessionId: string;
167
+ requestId: string;
168
+ ifGeneration: string;
169
+ }) => Promise<{
170
+ session: import("@anhlp/alp-protocol").SessionSummary;
171
+ duplicate?: true;
172
+ }>;
173
+ /**
174
+ * The ALP CLI command that follows the session in a terminal (capability `session.resumeCommand`,
175
+ * §12.8), built by alpd: for the clipboard only, never to run.
176
+ * @param {Map['session.resumeCommand']['params']} params @returns {Promise<Map['session.resumeCommand']['result']>}
177
+ */
178
+ resumeCommand: (params: {
179
+ sessionId: string;
180
+ }) => Promise<import("@anhlp/alp-protocol").ResumeCommand>;
181
+ /**
182
+ * The slash commands and skills the session's composer offers after "/" (capability `session.commands`, §12.12).
183
+ * @param {Map['session.commands']['params']} params @returns {Promise<Map['session.commands']['result']>}
184
+ */
185
+ commands: (params: {
186
+ sessionId: string;
187
+ }) => Promise<{
188
+ commands: import("@anhlp/alp-protocol").SessionCommand[];
189
+ }>;
190
+ /**
191
+ * Changes a live root's model, effort or team (capability `session.configure.live`, §12.9) at the
192
+ * idle barrier, through a restart of its native process on the same conversation; `configured` says
193
+ * what it runs with now. Sent once: repeat the same `requestId` after a lost answer. A change to
194
+ * another runtime is refused (1005 runtime_mismatch, `data.action: 'session.create'`).
195
+ * @param {Map['session.configure']['params'] & { requestId: string; ifGeneration: string }} params @returns {Promise<Map['session.configure']['result']>}
196
+ */
197
+ configure: (params: {
198
+ sessionId: string;
199
+ mode?: string;
200
+ model?: string;
201
+ thinking?: string;
202
+ team?: string;
203
+ requestId?: string;
204
+ ifGeneration?: string;
205
+ } & {
206
+ requestId: string;
207
+ ifGeneration: string;
208
+ }) => Promise<{
209
+ session: import("@anhlp/alp-protocol").SessionSnapshot | import("@anhlp/alp-protocol").SessionSummary;
210
+ configured?: import("@anhlp/alp-protocol").ConfigureOutcome;
211
+ duplicate?: true;
212
+ }>;
213
+ /**
214
+ * What a change of model, effort, team or mode would run a live root with, and whether it would be
215
+ * taken now (capability `session.configure.live`, §12.9). Reads only.
216
+ * @param {Map['session.configure.preview']['params']} params @returns {Promise<Map['session.configure.preview']['result']>}
217
+ */
218
+ configurePreview: (params: {
219
+ sessionId: string;
220
+ mode?: string;
221
+ model?: string;
222
+ thinking?: string;
223
+ team?: string;
224
+ }) => Promise<{
225
+ preview: import("@anhlp/alp-protocol").ConfigurePreview;
226
+ }>;
227
+ };