@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
package/dist/index.d.ts CHANGED
@@ -14,15 +14,60 @@ export function assertPrivateSocket(socketPath: any): Promise<import("fs").Stats
14
14
  /**
15
15
  * Finds alpd.js for a client that cannot locate it beside itself, such as the Paseo
16
16
  * plugin, which Paseo re-bundles: the first existing candidate, then where alpd last
17
- * recorded itself ($ALP_HOME/alpd.json), then the ALP CLI (`alp`) on PATH.
17
+ * recorded itself ($ALP_HOME/alpd.json), then the ALP CLI (`alp`) on PATH and in the usual install
18
+ * directories (`binDirectories`; a test passes [] so the caller's own install is not found).
18
19
  */
19
- export function findDaemonEntry({ home, env, candidates }?: {
20
+ export function findDaemonEntry({ home, env, candidates, binDirectories }?: {
20
21
  home?: string | undefined;
21
22
  env?: NodeJS.ProcessEnv | undefined;
22
23
  candidates?: (string | undefined)[] | undefined;
23
- }): Promise<string | undefined>;
24
+ binDirectories?: string[] | undefined;
25
+ }): Promise<any>;
26
+ /**
27
+ * Integration names are single lowercase path segments: they name `<home>/integrations/<name>.lock`,
28
+ * its guard and `<home>/<name>.json`. Returns the name, or throws a TypeError.
29
+ * @param {unknown} name
30
+ * @returns {string}
31
+ */
32
+ export function assertIntegrationName(name: unknown): string;
33
+ /**
34
+ * Returns a stable identifier for the current OS boot session,
35
+ * or undefined if unavailable on the platform or inaccessible.
36
+ *
37
+ * On Linux, reads /proc/sys/kernel/random/boot_id.
38
+ * On Darwin (macOS), queries sysctl kern.bootsessionuuid.
39
+ *
40
+ * @returns {string | undefined}
41
+ */
42
+ export function bootId(): string | undefined;
43
+ /**
44
+ * Internal/testing seam: resets or sets the cached boot identifier.
45
+ * @param {string | undefined | null} [id]
46
+ */
47
+ export function _setBootIdForTest(id?: string | undefined | null): void;
24
48
  /** Wall-clock boot time; a lock from an earlier boot is stale even if its pid is reused. */
25
49
  export function bootTime(): number;
50
+ /**
51
+ * Evaluates whether a lock record belongs to the current boot session.
52
+ *
53
+ * When both the lock and the current environment supply a bootId (Linux
54
+ * /proc/sys/kernel/random/boot_id or macOS kern.bootsessionuuid), identity is
55
+ * determined by exact bootId match, which is immune to wall-clock jumps.
56
+ *
57
+ * For legacy locks or environments without a bootId, falls back to checking
58
+ * whether wall-clock bootTime is within a 30-second window.
59
+ *
60
+ * @param {{ bootId?: string, bootTime?: number }} [lock]
61
+ * @param {{ bootId?: string, bootTime?: number }} [current]
62
+ * @returns {boolean}
63
+ */
64
+ export function isSameBoot(lock?: {
65
+ bootId?: string;
66
+ bootTime?: number;
67
+ }, { bootId: curBootId, bootTime: curBootTime }?: {
68
+ bootId?: string;
69
+ bootTime?: number;
70
+ }): boolean;
26
71
  export function readLock(home: any): Promise<any>;
27
72
  export function lockAlive(lock: any): boolean;
28
73
  /**
@@ -42,11 +87,13 @@ export function acquireDaemonLock(home: string, contents: {
42
87
  protocolVersion: number;
43
88
  socket: string;
44
89
  maintenance?: string;
90
+ uid: number;
91
+ ready: boolean;
92
+ bootId?: string | undefined;
45
93
  pid: number;
46
94
  startedAt: string;
95
+ startedUptime: number;
47
96
  bootTime: number;
48
- uid: number;
49
- ready: boolean;
50
97
  }>;
51
98
  /** Lets go of alpd's lock if this process holds it. */
52
99
  export function releaseDaemonLock(home: any): Promise<void>;
@@ -68,20 +115,74 @@ export function connect(socketPath: string, client?: {
68
115
  name: string;
69
116
  version: string;
70
117
  }, options?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions): Promise<AlpClient>;
118
+ export function readDaemonLifecycle(home: any): Promise<{
119
+ token: string;
120
+ pid: number;
121
+ bootTime: number;
122
+ action: string;
123
+ } | undefined>;
124
+ /** Serializes requested starts and stops, including the time before alpd has a lock.
125
+ * Rename publishes a fully populated directory: an existing nonempty directory cannot
126
+ * be replaced. Reaping/release unlinks only its unique owner token, then rmdir; even
127
+ * racing stale reapers cannot remove a successor's nonempty directory.
128
+ */
129
+ export function withDaemonLifecycle(home: any, action: any, run: any, { joinStart, signal }?: {
130
+ joinStart?: boolean | undefined;
131
+ signal?: AbortSignal | undefined;
132
+ }): Promise<any>;
133
+ /**
134
+ * The time a start of alpd waits for it to become ready, in ms: ALP_DAEMON_START_TIMEOUT_MS when it
135
+ * is a positive whole number of at most one hour, else DAEMON_START_TIMEOUT_MS.
136
+ * @param {NodeJS.ProcessEnv} [env]
137
+ */
138
+ export function daemonStartTimeoutMs(env?: NodeJS.ProcessEnv): number;
71
139
  /**
72
140
  * Returns the socket of a ready daemon, starting one when none runs.
73
141
  * `entry` is the daemon script; it is started through its own detaching launcher so the
74
142
  * daemon outlives the client that started it.
75
143
  */
76
- export function ensureDaemon({ home, entry, env, execPath, timeoutMs }?: {
144
+ export function ensureDaemon({ home, entry, env, execPath, timeoutMs, lifecycleLocked, signal }?: {
77
145
  home?: string | undefined;
78
146
  entry?: string | undefined;
79
147
  env?: NodeJS.ProcessEnv | undefined;
80
148
  execPath?: string | undefined;
81
149
  timeoutMs?: number | undefined;
150
+ lifecycleLocked?: boolean | undefined;
151
+ signal?: AbortSignal | undefined;
152
+ }): Promise<any>;
153
+ /**
154
+ * The entry of integration `name`: an environment override, a descriptor under the home or a
155
+ * distribution root, or an `alp-<name>-integration` binary. Discovery never returns an entry for
156
+ * `dashboard`: that is alp dashboard's service, which ships with the CLI and is started with its
157
+ * explicit entry; nor for `web`, its name before the rename (t-81b0.5). Everything once registered
158
+ * under `web` (the descriptor `integrations/web.json`, the
159
+ * `alp-web-integration` binary, `ALP_WEB_INTEGRATION`) is the Paseo integration from before its
160
+ * rename to `paseo`, which must never run under the web lock. `ALP_WEB_INTEGRATION` is read for
161
+ * `paseo` only, after `ALP_PASEO_INTEGRATION`, for one release (like the alp-web-integration alias).
162
+ * @param {string} [name]
163
+ * @param {{ home?: string, env?: NodeJS.ProcessEnv, binDirectories?: string[], roots?: string[] }} [options]
164
+ */
165
+ export function discoverIntegration(name?: string, options?: {
166
+ home?: string;
167
+ env?: NodeJS.ProcessEnv;
168
+ binDirectories?: string[];
169
+ roots?: string[];
170
+ }): Promise<string | undefined>;
171
+ export function integrationAlive(lock: any): boolean;
172
+ /**
173
+ * Starts integration `name` (default `dashboard`) detached with `--service` (then `args`) unless its lock
174
+ * already names a live owner, then waits until its ready lock and `<home>/<name>.json` name the same
175
+ * pid. `entry` names the script to run with this Node and skips descriptor, environment and PATH
176
+ * discovery; `dashboard` is never discovered, so it needs its entry. `"dashboard": { "enabled": false }`
177
+ * in the home's settings.json (or `web.enabled`, its key before the rename) refuses `dashboard` only.
178
+ * @param {string | { name?: string, entry?: string, home?: string, args?: string[] }} [nameOrOptions]
179
+ */
180
+ export function startIntegration(nameOrOptions?: string | {
181
+ name?: string;
182
+ entry?: string;
183
+ home?: string;
184
+ args?: string[];
82
185
  }): Promise<any>;
83
- export function discoverIntegration(name?: string, options?: {}): Promise<string | undefined>;
84
- export function startIntegration(nameOrOptions?: string): Promise<any>;
85
186
  export * from "./portable.js";
86
187
  export { createSocketTransport } from "./ipc.js";
87
188
  /**
@@ -95,7 +196,21 @@ export class AlpClient extends AlpRpcClient {
95
196
  * @param {import('./rpc/client.js').AlpRpcClientOptions & import('./ipc.js').SocketTransportOptions} [options]
96
197
  */
97
198
  constructor(socket: import("node:net").Socket, { maxFrame, maxBufferedBytes, ...options }?: import("./rpc/client.js").AlpRpcClientOptions & import("./ipc.js").SocketTransportOptions);
199
+ /** Host features captured by connect's handshake. @type {readonly string[]} */
200
+ capabilities: readonly string[];
201
+ /** Limits captured by connect's handshake. @type {import('@anhlp/alp-protocol').AttachmentLimits | undefined} */
202
+ attachmentLimits: import("@anhlp/alp-protocol").AttachmentLimits | undefined;
203
+ /** @type {{ readonly maxCount: number; readonly maxBytes: number; readonly maxTotalBytes: number } | undefined} */
204
+ promptImageLimits: {
205
+ readonly maxCount: number;
206
+ readonly maxBytes: number;
207
+ readonly maxTotalBytes: number;
208
+ } | undefined;
209
+ /** @type {import('@anhlp/alp-protocol').TerminalLimits | undefined} */
210
+ terminalLimits: import("@anhlp/alp-protocol").TerminalLimits | undefined;
98
211
  }
212
+ /** How long a start waits for alpd to be ready by default: generous, as a loaded host can take a while. */
213
+ export const DAEMON_START_TIMEOUT_MS: 60000;
99
214
  import { AlpRpcClient } from './rpc/client.js';
100
215
  export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, encodeFrame } from "@anhlp/alp-protocol";
101
216
  export { connectWebSocket, createWebSocketTransport, redactUrl, CLOSE_CODE } from "./websocket.js";