@mclawnet/agent 0.6.20 → 0.6.22

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 (99) hide show
  1. package/cli.js +63 -0
  2. package/dist/__tests__/checkpoint.test.d.ts +2 -0
  3. package/dist/__tests__/checkpoint.test.d.ts.map +1 -0
  4. package/dist/__tests__/fs-handler-decode.test.d.ts +2 -0
  5. package/dist/__tests__/fs-handler-decode.test.d.ts.map +1 -0
  6. package/dist/__tests__/idle-sweeper.test.d.ts +2 -0
  7. package/dist/__tests__/idle-sweeper.test.d.ts.map +1 -0
  8. package/dist/__tests__/mcp-config.test.d.ts +2 -0
  9. package/dist/__tests__/mcp-config.test.d.ts.map +1 -0
  10. package/dist/__tests__/schedule-runtime-spawn.test.d.ts +2 -0
  11. package/dist/__tests__/schedule-runtime-spawn.test.d.ts.map +1 -0
  12. package/dist/__tests__/schedule-runtime.test.d.ts +2 -0
  13. package/dist/__tests__/schedule-runtime.test.d.ts.map +1 -0
  14. package/dist/__tests__/session-limit.test.d.ts +2 -0
  15. package/dist/__tests__/session-limit.test.d.ts.map +1 -0
  16. package/dist/__tests__/swarm-cli-client.test.d.ts +2 -0
  17. package/dist/__tests__/swarm-cli-client.test.d.ts.map +1 -0
  18. package/dist/__tests__/swarm-control-dispatch.test.d.ts +2 -0
  19. package/dist/__tests__/swarm-control-dispatch.test.d.ts.map +1 -0
  20. package/dist/__tests__/swarm-session-bridge.test.d.ts +2 -0
  21. package/dist/__tests__/swarm-session-bridge.test.d.ts.map +1 -0
  22. package/dist/backend-adapter.d.ts +43 -0
  23. package/dist/backend-adapter.d.ts.map +1 -1
  24. package/dist/checkpoint.d.ts +67 -0
  25. package/dist/checkpoint.d.ts.map +1 -0
  26. package/dist/{chunk-RIK7IXSW.js → chunk-WJWCYGLQ.js} +1130 -147
  27. package/dist/chunk-WJWCYGLQ.js.map +1 -0
  28. package/dist/errors.d.ts +40 -0
  29. package/dist/errors.d.ts.map +1 -0
  30. package/dist/fs-handler.d.ts.map +1 -1
  31. package/dist/hub-connection.d.ts +13 -0
  32. package/dist/hub-connection.d.ts.map +1 -1
  33. package/dist/index.js +1 -1
  34. package/dist/schedule-runtime.d.ts +125 -0
  35. package/dist/schedule-runtime.d.ts.map +1 -0
  36. package/dist/session-manager.d.ts +102 -0
  37. package/dist/session-manager.d.ts.map +1 -1
  38. package/dist/skill-loader.d.ts +20 -0
  39. package/dist/skill-loader.d.ts.map +1 -1
  40. package/dist/start.d.ts +2 -0
  41. package/dist/start.d.ts.map +1 -1
  42. package/dist/start.js +1 -1
  43. package/dist/swarm-cli-client.d.ts +24 -0
  44. package/dist/swarm-cli-client.d.ts.map +1 -0
  45. package/dist/swarm-cli-client.js +83 -0
  46. package/dist/swarm-cli-client.js.map +1 -0
  47. package/dist/swarm-control-dispatch.d.ts +47 -0
  48. package/dist/swarm-control-dispatch.d.ts.map +1 -0
  49. package/dist/swarm-session-bridge.d.ts +22 -0
  50. package/dist/swarm-session-bridge.d.ts.map +1 -0
  51. package/package.json +6 -4
  52. package/skills/cocos-creator-3x-cn/SKILL.md +475 -0
  53. package/skills/cocos-creator-3x-cn/references/framework/asset-management.md +322 -0
  54. package/skills/cocos-creator-3x-cn/references/framework/component-system.md +348 -0
  55. package/skills/cocos-creator-3x-cn/references/framework/event-patterns.md +410 -0
  56. package/skills/cocos-creator-3x-cn/references/framework/playable-optimization.md +257 -0
  57. package/skills/cocos-creator-3x-cn/references/language/performance.md +363 -0
  58. package/skills/cocos-creator-3x-cn/references/language/quality-hygiene.md +307 -0
  59. package/skills/cocos-creator-3x-cn/references/review/architecture-review.md +183 -0
  60. package/skills/cocos-creator-3x-cn/references/review/quality-review.md +251 -0
  61. package/skills/cocos-performance-optimizer/SKILL.md +214 -0
  62. package/skills/game-development/2d-games/SKILL.md +129 -0
  63. package/skills/game-development/3d-games/SKILL.md +145 -0
  64. package/skills/game-development/SKILL.md +175 -0
  65. package/skills/game-development/game-art/SKILL.md +195 -0
  66. package/skills/game-development/game-audio/SKILL.md +200 -0
  67. package/skills/game-development/game-design/SKILL.md +139 -0
  68. package/skills/game-development/mobile-games/SKILL.md +118 -0
  69. package/skills/game-development/multiplayer/SKILL.md +142 -0
  70. package/skills/game-development/pc-games/SKILL.md +154 -0
  71. package/skills/game-development/vr-ar/SKILL.md +133 -0
  72. package/skills/game-development/web-games/SKILL.md +160 -0
  73. package/skills/game-engine/SKILL.md +140 -0
  74. package/skills/game-engine/assets/2d-maze-game.md +528 -0
  75. package/skills/game-engine/assets/2d-platform-game.md +1855 -0
  76. package/skills/game-engine/assets/gameBase-template-repo.md +310 -0
  77. package/skills/game-engine/assets/paddle-game-template.md +1528 -0
  78. package/skills/game-engine/assets/simple-2d-engine.md +507 -0
  79. package/skills/game-engine/references/3d-web-games.md +754 -0
  80. package/skills/game-engine/references/algorithms.md +843 -0
  81. package/skills/game-engine/references/basics.md +343 -0
  82. package/skills/game-engine/references/game-control-mechanisms.md +617 -0
  83. package/skills/game-engine/references/game-engine-core-principles.md +695 -0
  84. package/skills/game-engine/references/game-publishing.md +352 -0
  85. package/skills/game-engine/references/techniques.md +894 -0
  86. package/skills/game-engine/references/terminology.md +354 -0
  87. package/skills/game-engine/references/web-apis.md +1394 -0
  88. package/skills/theone-cocos-standards/SKILL.md +557 -0
  89. package/skills/theone-cocos-standards/references/framework/component-system.md +645 -0
  90. package/skills/theone-cocos-standards/references/framework/event-patterns.md +433 -0
  91. package/skills/theone-cocos-standards/references/framework/playable-optimization.md +429 -0
  92. package/skills/theone-cocos-standards/references/framework/size-optimization.md +308 -0
  93. package/skills/theone-cocos-standards/references/language/modern-typescript.md +658 -0
  94. package/skills/theone-cocos-standards/references/language/performance.md +580 -0
  95. package/skills/theone-cocos-standards/references/language/quality-hygiene.md +582 -0
  96. package/skills/theone-cocos-standards/references/review/architecture-review.md +250 -0
  97. package/skills/theone-cocos-standards/references/review/performance-review.md +288 -0
  98. package/skills/theone-cocos-standards/references/review/quality-review.md +239 -0
  99. package/dist/chunk-RIK7IXSW.js.map +0 -1
package/cli.js CHANGED
@@ -344,6 +344,69 @@ configCmd
344
344
  console.log("Edit via 'clawnet-agent config set <key> <value>' or by editing ~/.clawnet/settings.json directly.");
345
345
  });
346
346
 
347
+ // === swarm ===
348
+ const swarmCmd = program
349
+ .command("swarm")
350
+ .description("Manage swarms via the agent (sends control messages over the hub)");
351
+
352
+ swarmCmd
353
+ .command("new")
354
+ .description("Spawn a new swarm on a peer agent")
355
+ .requiredOption("--team <name>", "Team / template name")
356
+ .option("--msg <text>", "Initial message to queen")
357
+ .option("--agent <agentId>", "Target agent (default: first peer of same user)")
358
+ .option("--work-dir <path>", "Working directory for the swarm")
359
+ .action(async (opts) => {
360
+ const { loadConfig } = await import("./dist/index.js");
361
+ const cfg = loadConfig();
362
+ if (!cfg.token) {
363
+ printNeedsInit();
364
+ process.exit(1);
365
+ }
366
+ const hubUrl = cfg.hubUrl || "wss://mclaw.work/ws/agent";
367
+ const { randomUUID } = await import("node:crypto");
368
+ const swarmId = randomUUID();
369
+ const msg = { type: "swarm_spawn", teamName: opts.team, swarmId };
370
+ if (opts.msg !== undefined) msg.msg = opts.msg;
371
+ if (opts.workDir !== undefined) msg.workDir = opts.workDir;
372
+ if (opts.agent !== undefined) msg.agentId = opts.agent;
373
+
374
+ const { sendControlMessage } = await import("./dist/swarm-cli-client.js");
375
+ try {
376
+ await sendControlMessage(msg, { hubUrl, token: cfg.token });
377
+ console.log(`swarm_spawn dispatched (swarmId=${swarmId})`);
378
+ console.log(`Resume later with: clawnet-agent swarm resume ${swarmId}`);
379
+ } catch (err) {
380
+ console.error("[clawnet] swarm new failed:", err.message || err);
381
+ process.exit(1);
382
+ }
383
+ });
384
+
385
+ swarmCmd
386
+ .command("resume <swarmId>")
387
+ .description("Resume a previously persisted swarm on a peer agent")
388
+ .option("--agent <agentId>", "Target agent")
389
+ .action(async (swarmId, opts) => {
390
+ const { loadConfig } = await import("./dist/index.js");
391
+ const cfg = loadConfig();
392
+ if (!cfg.token) {
393
+ printNeedsInit();
394
+ process.exit(1);
395
+ }
396
+ const hubUrl = cfg.hubUrl || "wss://mclaw.work/ws/agent";
397
+ const msg = { type: "swarm_resume", swarmId };
398
+ if (opts.agent !== undefined) msg.agentId = opts.agent;
399
+
400
+ const { sendControlMessage } = await import("./dist/swarm-cli-client.js");
401
+ try {
402
+ await sendControlMessage(msg, { hubUrl, token: cfg.token });
403
+ console.log("swarm_resume dispatched");
404
+ } catch (err) {
405
+ console.error("[clawnet] swarm resume failed:", err.message || err);
406
+ process.exit(1);
407
+ }
408
+ });
409
+
347
410
  program.parseAsync(process.argv).catch((err) => {
348
411
  console.error("[clawnet] Fatal:", err.message || err);
349
412
  process.exit(1);
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=checkpoint.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/checkpoint.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=fs-handler-decode.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"fs-handler-decode.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/fs-handler-decode.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=idle-sweeper.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"idle-sweeper.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/idle-sweeper.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=mcp-config.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"mcp-config.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/mcp-config.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=schedule-runtime-spawn.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schedule-runtime-spawn.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/schedule-runtime-spawn.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=schedule-runtime.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schedule-runtime.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/schedule-runtime.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=session-limit.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-limit.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/session-limit.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=swarm-cli-client.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"swarm-cli-client.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/swarm-cli-client.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=swarm-control-dispatch.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"swarm-control-dispatch.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/swarm-control-dispatch.test.ts"],"names":[],"mappings":""}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=swarm-session-bridge.test.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"swarm-session-bridge.test.d.ts","sourceRoot":"","sources":["../../src/__tests__/swarm-session-bridge.test.ts"],"names":[],"mappings":""}
@@ -11,6 +11,17 @@ export interface BackendProcess {
11
11
  id: string;
12
12
  /** Working directory for this process */
13
13
  workDir: string;
14
+ /**
15
+ * OS process id of the underlying backend process, if applicable.
16
+ *
17
+ * Optional because not every backend is a child process — a future in-process
18
+ * adapter (mock / stubbed / WASM) wouldn't have one. SessionManager uses pid
19
+ * for the PR-C checkpoint: a restart probes `process.kill(pid, 0)` to decide
20
+ * whether the recorded session is `dead` or an `orphan`. Adapters that omit
21
+ * pid forfeit the dead/orphan classification — checkpointed sessions will
22
+ * silently appear as "no longer here", which is also acceptable behavior.
23
+ */
24
+ pid?: number;
14
25
  /** Kill the backend process */
15
26
  kill(): Promise<void>;
16
27
  /**
@@ -37,6 +48,21 @@ export interface SpawnOptions {
37
48
  roleId?: string;
38
49
  /** Extra directories to mount via --add-dir */
39
50
  additionalDirs?: string[];
51
+ /** Optional allowlist of tool names to forward to the backend (PR3.5). */
52
+ allowedTools?: string[];
53
+ /** Optional denylist of tool names to forward to the backend (PR3.5). */
54
+ disallowedTools?: string[];
55
+ /**
56
+ * Override CLAUDE_CODE_MAX_OUTPUT_TOKENS for this spawn. Drives the
57
+ * server-side hard limit (200k − maxOutputTokens) and the CLI's own
58
+ * effective window. Lower = wider prompt budget. SessionManager pulls this
59
+ * from `getRecommendedMaxOutputTokens()` on each spawn so the ladder
60
+ * (32k → 16k → 8k) survives across `--resume` restarts.
61
+ *
62
+ * Optional: when omitted the CLI uses its own default — adapters that
63
+ * don't honour it lose D-lite escalation but never crash.
64
+ */
65
+ maxOutputTokens?: number;
40
66
  }
41
67
  export interface BackendAdapter {
42
68
  /** Backend type identifier */
@@ -90,5 +116,22 @@ export interface BackendAdapter {
90
116
  * accumulate until the next abortSession/closeSession call.
91
117
  */
92
118
  onExit?(process: BackendProcess, handler: (code: number | null) => void): void;
119
+ /**
120
+ * Register a handler for token-budget warnings. Fires when the backend
121
+ * estimates the prompt is approaching the server-side hard limit.
122
+ * SessionManager uses this to escalate the max_output_tokens ladder so
123
+ * the next spawn gets a wider budget.
124
+ *
125
+ * Optional: adapters that can't introspect token usage simply skip this —
126
+ * the ladder stays at index 0 forever, falling back to claude-code's own
127
+ * auto-compact (which works most of the time, just less defensively).
128
+ */
129
+ onTokenBudgetWarning?(process: BackendProcess, handler: (info: {
130
+ used: number;
131
+ hardLimit: number;
132
+ threshold: number;
133
+ distanceToHard: number;
134
+ maxOutputTokens: number;
135
+ }) => void): void;
93
136
  }
94
137
  //# sourceMappingURL=backend-adapter.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"backend-adapter.d.ts","sourceRoot":"","sources":["../src/backend-adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,MAAM,WAAW,cAAc;IAC7B,kDAAkD;IAClD,EAAE,EAAE,MAAM,CAAC;IACX,yCAAyC;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;OAIG;IACH,OAAO,IAAI,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,yBAAyB;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,+CAA+C;IAC/C,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,8FAA8F;IAC9F,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+CAA+C;IAC/C,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;CAC3B;AAED,MAAM,WAAW,cAAc;IAC7B,8BAA8B;IAC9B,IAAI,EAAE,MAAM,CAAC;IAEb,kCAAkC;IAClC,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IAEtD,qCAAqC;IACrC,IAAI,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE7C,6CAA6C;IAC7C,IAAI,CAAC,OAAO,EAAE,cAAc,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IAEnD,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAEzE,qCAAqC;IACrC,cAAc,CAAC,CACb,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,CAAC,IAAI,EAAE;QACd,eAAe,CAAC,EAAE,MAAM,CAAC;QACzB,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,YAAY,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAA;SAAE,CAAC;KAChD,KAAK,IAAI,GACT,IAAI,CAAC;IAER,6BAA6B;IAC7B,OAAO,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,GAAG,IAAI,CAAC;IAEzE;;;;;;;;;;;;OAYG;IACH,gBAAgB,CAAC,CACf,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,CAAC,IAAI,EAAE;QAAE,eAAe,EAAE,MAAM,CAAA;KAAE,KAAK,IAAI,GACnD,IAAI,CAAC;IAER;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,KAAK,IAAI,GAAG,IAAI,CAAC;CAChF"}
1
+ {"version":3,"file":"backend-adapter.d.ts","sourceRoot":"","sources":["../src/backend-adapter.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,67 @@
1
+ import type { SessionKind } from "./errors.js";
2
+ /**
3
+ * One checkpointed session. `pid` is recorded **only** for the startup probe
4
+ * (`process.kill(pid, 0)`) — the agent never tries to take over an old pid,
5
+ * which is the safety property that prevents two agents racing on the same
6
+ * Claude CLI child process.
7
+ */
8
+ export interface CheckpointEntry {
9
+ sessionId: string;
10
+ kind: SessionKind;
11
+ workDir: string;
12
+ claudeSessionId?: string;
13
+ agentInstanceId?: string;
14
+ startedAt: number;
15
+ lastActivityAt: number;
16
+ pid: number;
17
+ /**
18
+ * Token-budget ladder index (0 = 32k, 1 = 16k, 2 = 8k). Persisted so a
19
+ * SessionManager restart resumes at the same step instead of starting over
20
+ * at 32k — otherwise a session that just escalated to 16k right before a
21
+ * restart would re-hit the 168k wall on the very first turn after recover.
22
+ * Undefined for entries written before this field existed (treat as 0).
23
+ */
24
+ currentLadderIndex?: number;
25
+ }
26
+ export interface CheckpointFile {
27
+ version: 1;
28
+ agentStartedAt: number;
29
+ entries: CheckpointEntry[];
30
+ }
31
+ /**
32
+ * Result of `recoverFromCheckpoint`. `dead` should be reported to hub via
33
+ * `session.died`; `orphan` is logged as a warning but not actioned (we don't
34
+ * SIGKILL processes we don't own — see design §5).
35
+ */
36
+ export interface RecoveryReport {
37
+ dead: CheckpointEntry[];
38
+ orphan: CheckpointEntry[];
39
+ }
40
+ /**
41
+ * Atomically write `data` to `path` via temp+rename — POSIX guarantees rename
42
+ * atomicity within the same filesystem, so a partial write or kill -9 mid-flush
43
+ * leaves either the previous version or the new version, never a corrupted
44
+ * file. Mirrors hermes `tools/process_registry.py:19-24`.
45
+ */
46
+ export declare function atomicWriteJson(path: string, data: unknown): Promise<void>;
47
+ /**
48
+ * Read the checkpoint file. Returns `null` (not throws) on ENOENT — first
49
+ * boot has no file, and the caller treats that the same as "empty file".
50
+ * Throws on any other I/O error and on JSON parse failure: a corrupt
51
+ * checkpoint should surface loudly rather than silently lose state.
52
+ */
53
+ export declare function readCheckpoint(path: string): Promise<CheckpointFile | null>;
54
+ /**
55
+ * Standard pid-liveness probe. `process.kill(pid, 0)` doesn't actually send
56
+ * a signal — kernel just returns success/ESRCH/EPERM based on whether the
57
+ * pid exists and whether we have permission. `EPERM` means the pid exists
58
+ * but isn't owned by us → still alive, just not killable from here.
59
+ *
60
+ * Behavior differences across platforms:
61
+ * - POSIX (Linux/macOS): exact semantics described above.
62
+ * - Windows: Node's runtime translates to OpenProcess; ESRCH/EPERM still
63
+ * surface but the boundary cases are rarer. Acceptable; the worst case
64
+ * is a slightly stale "alive" classification on Windows.
65
+ */
66
+ export declare function isPidAlive(pid: number): boolean;
67
+ //# sourceMappingURL=checkpoint.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../src/checkpoint.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,SAAS,EAAE,MAAM,CAAC;IAClB,cAAc,EAAE,MAAM,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ;;;;;;OAMG;IACH,kBAAkB,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,CAAC,CAAC;IACX,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,eAAe,EAAE,CAAC;CAC5B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,eAAe,EAAE,CAAC;IACxB,MAAM,EAAE,eAAe,EAAE,CAAC;CAC3B;AAED;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,GACZ,OAAO,CAAC,IAAI,CAAC,CAIf;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC,CAShC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAO/C"}