opencode-copilot-delegate 0.7.0 → 0.8.0

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,32 @@
1
1
  # opencode-copilot-delegate
2
2
 
3
+ ## 0.8.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 0c21f43: Make the plugin factory idempotent across multiple OpenCode config sources within the same process. When `~/.config/opencode/opencode.json` AND a project-level `opencode.json` (or any other combination of config sources) both list `opencode-copilot-delegate`, OpenCode previously invoked the factory once per source — each invocation evaluating the plugin module fresh, running orphan reaping, and registering its own copy of the three tools. The result was duplicated tools in the catalog, duplicated init side effects (PID-file `mkdir`, `reapOrphans`), and per-invocation closure state that could diverge across registrations.
8
+
9
+ The factory now resolves at most once per process via a `globalThis` symbol singleton (`Symbol.for('opencode-copilot-delegate.singleton.v1')`). Subsequent invocations within the same PID return the cached hooks promise, skip the heavy init, and emit a single one-shot warning (via `console.warn` AND `client.app.log` under `service=copilot-delegate`) so duplicate-config situations remain observable in logs. Across distinct OpenCode processes the singleton is fresh — each process initializes normally.
10
+
11
+ No configuration change is required for users with a single config source. Users with duplicate registrations will see one warning per process and a single set of tools in the catalog.
12
+
13
+ - 1fc343d: Tighten orphan-reaper internals and add two new exported helpers from `src/runtime/pid-file.ts`:
14
+
15
+ - `truncatePidFile(filePath)` — truncate under the per-file `serializeWrite` lock; ENOENT (file or parent missing) silently swallowed.
16
+ - `unlinkPidFile(filePath)` — unlink under the per-file `serializeWrite` lock; ENOENT silently swallowed.
17
+
18
+ Also export `ReapOptions` from `src/runtime/orphan-reaper.ts` (consolidates `ReapDeps` + reap-specific opts via interface extension), and consolidate `reapOneFile` to a single opts-bag parameter. `cleanupAfterReap` now routes its truncate-on-current and unlink-on-foreign paths through the new helpers so any future change that runs reap concurrent with task spawns is automatically race-safe.
19
+
20
+ No user-visible behavior change in default usage; the bump reflects the new exported surface.
21
+
22
+ - 42c5239: Add `timedOut: boolean` to `ReapResult` so consumers can distinguish a successful no-op reap (nothing to do) from a timeout-aborted reap (gave up; orphans may remain). The flag is `false` on every success path and `true` only when the overall `reapOrphans` timeout fires.
23
+
24
+ When `timedOut` is `true`, the count fields are zero placeholders, not partial-progress accounting — in-flight workers may have already invoked `killProcessTree` or scanned files before the abort signal landed, but those side effects are not reflected in the returned counts. Treat a timed-out result as "no reliable count signal" and warn or retry.
25
+
26
+ Note for TypeScript consumers: `ReapResult` is exported from the package's runtime types and gains a required field. Any caller constructing a `ReapResult` literal will need to add `timedOut` explicitly. Internal callers in this repo are already updated.
27
+
28
+ - 3491e63: Tighten the `setStatus` lifecycle helper to forbid terminal → non-terminal transitions. Once a task reaches `complete`, `failed`, or `cancelled`, every subsequent `setStatus` call is a no-op. Previously the helper short-circuited only when both old and new status were terminal, leaving an unintended resurrection path that no caller exercises but the contract permitted. This narrows the public API contract; no caller behavior changes.
29
+
3
30
  ## 0.7.0
4
31
 
5
32
  ### Minor Changes
package/dist/index.js CHANGED
@@ -9385,14 +9385,123 @@ function normalizeToolArgSchemas(toolDefinition) {
9385
9385
 
9386
9386
  // src/runtime/orphan-reaper.ts
9387
9387
  import { spawn as spawn2 } from "child_process";
9388
- import { readdir, readFile, unlink, writeFile } from "fs/promises";
9389
- import { basename as basename2, extname, join } from "path";
9388
+ import { readdir, readFile as readFile2 } from "fs/promises";
9389
+ import { basename as basename2, extname, join as join2 } from "path";
9390
9390
 
9391
9391
  // src/lib/errno.ts
9392
9392
  function isErrnoException(e) {
9393
9393
  return e instanceof Error && "code" in e;
9394
9394
  }
9395
9395
 
9396
+ // src/runtime/pid-file.ts
9397
+ import { randomBytes } from "crypto";
9398
+ import {
9399
+ chmod,
9400
+ constants as fsConstants,
9401
+ mkdir,
9402
+ open,
9403
+ readFile,
9404
+ rename,
9405
+ unlink,
9406
+ writeFile
9407
+ } from "fs/promises";
9408
+ import { homedir } from "os";
9409
+ import { dirname, join } from "path";
9410
+ var writeChains = new Map;
9411
+ async function serializeWrite(filePath, work) {
9412
+ const prev = writeChains.get(filePath) ?? Promise.resolve();
9413
+ const next = prev.catch(() => {}).then(work);
9414
+ writeChains.set(filePath, next);
9415
+ try {
9416
+ await next;
9417
+ } finally {
9418
+ if (writeChains.get(filePath) === next) {
9419
+ writeChains.delete(filePath);
9420
+ }
9421
+ }
9422
+ }
9423
+ function resolveInstancePidFilePath() {
9424
+ const stateDir = process.env.XDG_STATE_HOME ?? join(homedir(), ".local", "state");
9425
+ return join(stateDir, "opencode-copilot-delegate", "orphans", `${process.pid}.pids`);
9426
+ }
9427
+ async function appendPidEntry(filePath, pid, comm, lstart) {
9428
+ await serializeWrite(filePath, async () => {
9429
+ await mkdir(dirname(filePath), { recursive: true, mode: 448 });
9430
+ let existing = "";
9431
+ try {
9432
+ existing = await readFile(filePath, "utf-8");
9433
+ } catch (e) {
9434
+ if (!isErrnoException(e) || e.code !== "ENOENT")
9435
+ throw e;
9436
+ }
9437
+ const line = `${pid} ${comm} ${lstart}
9438
+ `;
9439
+ const content = existing + line;
9440
+ const tempPath = `${filePath}.tmp.${randomBytes(8).toString("hex")}`;
9441
+ const fd = await open(tempPath, fsConstants.O_EXCL | fsConstants.O_CREAT | fsConstants.O_WRONLY, 384);
9442
+ try {
9443
+ await fd.writeFile(content, { encoding: "utf-8" });
9444
+ } finally {
9445
+ await fd.close();
9446
+ }
9447
+ await rename(tempPath, filePath);
9448
+ await chmod(filePath, 384);
9449
+ });
9450
+ }
9451
+ async function removePidEntry(filePath, pid) {
9452
+ await serializeWrite(filePath, async () => {
9453
+ let existing = "";
9454
+ try {
9455
+ existing = await readFile(filePath, "utf-8");
9456
+ } catch (e) {
9457
+ if (!isErrnoException(e) || e.code !== "ENOENT")
9458
+ throw e;
9459
+ return;
9460
+ }
9461
+ const prefix = `${pid} `;
9462
+ const lines = existing.split(`
9463
+ `);
9464
+ const filtered = lines.filter((line) => !line.startsWith(prefix));
9465
+ if (filtered.length === lines.length) {
9466
+ return;
9467
+ }
9468
+ const content = filtered.join(`
9469
+ `);
9470
+ const tempPath = `${filePath}.tmp.${randomBytes(8).toString("hex")}`;
9471
+ const fd = await open(tempPath, fsConstants.O_EXCL | fsConstants.O_CREAT | fsConstants.O_WRONLY, 384);
9472
+ try {
9473
+ await fd.writeFile(content, { encoding: "utf-8" });
9474
+ } finally {
9475
+ await fd.close();
9476
+ }
9477
+ await rename(tempPath, filePath);
9478
+ await chmod(filePath, 384);
9479
+ if (content.trim().length === 0) {
9480
+ await unlink(filePath);
9481
+ }
9482
+ });
9483
+ }
9484
+ async function truncatePidFile(filePath) {
9485
+ await serializeWrite(filePath, async () => {
9486
+ try {
9487
+ await writeFile(filePath, "");
9488
+ } catch (e) {
9489
+ if (!isErrnoException(e) || e.code !== "ENOENT")
9490
+ throw e;
9491
+ }
9492
+ });
9493
+ }
9494
+ async function unlinkPidFile(filePath) {
9495
+ await serializeWrite(filePath, async () => {
9496
+ try {
9497
+ await unlink(filePath);
9498
+ } catch (e) {
9499
+ if (!isErrnoException(e) || e.code !== "ENOENT")
9500
+ throw e;
9501
+ }
9502
+ });
9503
+ }
9504
+
9396
9505
  // src/runtime/orphan-reaper.ts
9397
9506
  function defaultIsPluginAlive(pid) {
9398
9507
  try {
@@ -9507,7 +9616,7 @@ async function processEntries(entries, killProcessTree2, getPidIdentity2, signal
9507
9616
  async function readPidFileEntries(filePath) {
9508
9617
  let content;
9509
9618
  try {
9510
- content = await readFile(filePath, "utf-8");
9619
+ content = await readFile2(filePath, "utf-8");
9511
9620
  } catch {
9512
9621
  return null;
9513
9622
  }
@@ -9525,16 +9634,27 @@ async function readPidFileEntries(filePath) {
9525
9634
  async function cleanupAfterReap(filePath, isCurrent, currentInstancePath) {
9526
9635
  try {
9527
9636
  if (isCurrent) {
9528
- await writeFile(currentInstancePath, "");
9637
+ await truncatePidFile(currentInstancePath);
9529
9638
  return false;
9530
9639
  }
9531
- await unlink(filePath);
9640
+ await unlinkPidFile(filePath);
9532
9641
  return true;
9533
9642
  } catch {
9534
9643
  return false;
9535
9644
  }
9536
9645
  }
9537
- async function reapOneFile(filePath, filePid, isCurrent, currentInstancePath, isPluginAlive, killProcessTree2, getPidIdentity2, signal, psTimeoutMs) {
9646
+ async function reapOneFile(args) {
9647
+ const {
9648
+ filePath,
9649
+ filePid,
9650
+ isCurrent,
9651
+ currentInstancePath,
9652
+ isPluginAlive,
9653
+ killProcessTree: killProcessTree2,
9654
+ getPidIdentity: getPidIdentity2,
9655
+ signal,
9656
+ psTimeoutMs
9657
+ } = args;
9538
9658
  const empty = {
9539
9659
  reaped: 0,
9540
9660
  skipped: 0,
@@ -9569,7 +9689,13 @@ async function doReap(opts) {
9569
9689
  try {
9570
9690
  files = await readdir(pidFileDir);
9571
9691
  } catch {
9572
- return { reaped: 0, skipped: 0, scannedFiles: 0, deletedFiles: 0 };
9692
+ return {
9693
+ reaped: 0,
9694
+ skipped: 0,
9695
+ scannedFiles: 0,
9696
+ deletedFiles: 0,
9697
+ timedOut: false
9698
+ };
9573
9699
  }
9574
9700
  let reaped = 0;
9575
9701
  let skipped = 0;
@@ -9580,14 +9706,24 @@ async function doReap(opts) {
9580
9706
  break;
9581
9707
  if (!file.endsWith(".pids"))
9582
9708
  continue;
9583
- const filePath = join(pidFileDir, file);
9709
+ const filePath = join2(pidFileDir, file);
9584
9710
  const stem = basename2(file, extname(file));
9585
9711
  if (!/^[1-9]\d*$/.test(stem)) {
9586
9712
  console.warn(`[orphan-reaper] Skipping non-numeric PID file: ${file}`);
9587
9713
  continue;
9588
9714
  }
9589
9715
  const filePid = Number(stem);
9590
- const outcome = await reapOneFile(filePath, filePid, filePid === process.pid, currentInstancePath, isPluginAlive, killProcessTree2, getPidIdentity2, signal, psTimeoutMs);
9716
+ const outcome = await reapOneFile({
9717
+ filePath,
9718
+ filePid,
9719
+ isCurrent: filePid === process.pid,
9720
+ currentInstancePath,
9721
+ isPluginAlive,
9722
+ killProcessTree: killProcessTree2,
9723
+ getPidIdentity: getPidIdentity2,
9724
+ signal,
9725
+ psTimeoutMs
9726
+ });
9591
9727
  reaped += outcome.reaped;
9592
9728
  skipped += outcome.skipped;
9593
9729
  if (outcome.scanned)
@@ -9595,16 +9731,17 @@ async function doReap(opts) {
9595
9731
  if (outcome.deleted)
9596
9732
  deletedFiles++;
9597
9733
  }
9598
- return { reaped, skipped, scannedFiles, deletedFiles };
9734
+ return { reaped, skipped, scannedFiles, deletedFiles, timedOut: false };
9599
9735
  }
9600
9736
  var DEFAULT_REAP_TIMEOUT_MS = 15000;
9601
9737
  async function reapOrphans(opts) {
9602
9738
  const reapTimeoutMs = opts.reapTimeoutMs ?? DEFAULT_REAP_TIMEOUT_MS;
9603
- const empty = {
9739
+ const zeros = {
9604
9740
  reaped: 0,
9605
9741
  skipped: 0,
9606
9742
  scannedFiles: 0,
9607
- deletedFiles: 0
9743
+ deletedFiles: 0,
9744
+ timedOut: false
9608
9745
  };
9609
9746
  const controller = new AbortController;
9610
9747
  let timeoutId;
@@ -9612,7 +9749,7 @@ async function reapOrphans(opts) {
9612
9749
  timeoutId = setTimeout(() => {
9613
9750
  console.warn(`[orphan-reaper] reapOrphans exceeded ${reapTimeoutMs}ms budget; returning empty result`);
9614
9751
  controller.abort();
9615
- resolve(empty);
9752
+ resolve({ ...zeros, timedOut: true });
9616
9753
  }, reapTimeoutMs);
9617
9754
  });
9618
9755
  const reapPromise = doReap({ ...opts, signal: controller.signal });
@@ -9625,92 +9762,33 @@ async function reapOrphans(opts) {
9625
9762
  }
9626
9763
  }
9627
9764
 
9628
- // src/runtime/pid-file.ts
9629
- import { randomBytes } from "crypto";
9630
- import {
9631
- chmod,
9632
- constants as fsConstants,
9633
- mkdir,
9634
- open,
9635
- readFile as readFile2,
9636
- rename,
9637
- unlink as unlink2
9638
- } from "fs/promises";
9639
- import { homedir } from "os";
9640
- import { dirname, join as join2 } from "path";
9641
- var writeChains = new Map;
9642
- async function serializeWrite(filePath, work) {
9643
- const prev = writeChains.get(filePath) ?? Promise.resolve();
9644
- const next = prev.catch(() => {}).then(work);
9645
- writeChains.set(filePath, next);
9646
- try {
9647
- await next;
9648
- } finally {
9649
- if (writeChains.get(filePath) === next) {
9650
- writeChains.delete(filePath);
9765
+ // src/runtime/plugin-singleton.ts
9766
+ var SINGLETON_KEY = Symbol.for("opencode-copilot-delegate.singleton.v1");
9767
+ async function plugInOnce({
9768
+ doInit,
9769
+ onDuplicate,
9770
+ pid
9771
+ }) {
9772
+ const currentPid = pid ?? process.pid;
9773
+ const g = globalThis;
9774
+ const existing = g[SINGLETON_KEY];
9775
+ if (existing && existing.pid === currentPid) {
9776
+ if (!existing.warned) {
9777
+ existing.warned = true;
9778
+ try {
9779
+ onDuplicate?.(currentPid);
9780
+ } catch {}
9651
9781
  }
9782
+ return existing.hooksPromise;
9652
9783
  }
9653
- }
9654
- function resolveInstancePidFilePath() {
9655
- const stateDir = process.env.XDG_STATE_HOME ?? join2(homedir(), ".local", "state");
9656
- return join2(stateDir, "opencode-copilot-delegate", "orphans", `${process.pid}.pids`);
9657
- }
9658
- async function appendPidEntry(filePath, pid, comm, lstart) {
9659
- await serializeWrite(filePath, async () => {
9660
- await mkdir(dirname(filePath), { recursive: true, mode: 448 });
9661
- let existing = "";
9662
- try {
9663
- existing = await readFile2(filePath, "utf-8");
9664
- } catch (e) {
9665
- if (!isErrnoException(e) || e.code !== "ENOENT")
9666
- throw e;
9667
- }
9668
- const line = `${pid} ${comm} ${lstart}
9669
- `;
9670
- const content = existing + line;
9671
- const tempPath = `${filePath}.tmp.${randomBytes(8).toString("hex")}`;
9672
- const fd = await open(tempPath, fsConstants.O_EXCL | fsConstants.O_CREAT | fsConstants.O_WRONLY, 384);
9673
- try {
9674
- await fd.writeFile(content, { encoding: "utf-8" });
9675
- } finally {
9676
- await fd.close();
9677
- }
9678
- await rename(tempPath, filePath);
9679
- await chmod(filePath, 384);
9680
- });
9681
- }
9682
- async function removePidEntry(filePath, pid) {
9683
- await serializeWrite(filePath, async () => {
9684
- let existing = "";
9685
- try {
9686
- existing = await readFile2(filePath, "utf-8");
9687
- } catch (e) {
9688
- if (!isErrnoException(e) || e.code !== "ENOENT")
9689
- throw e;
9690
- return;
9691
- }
9692
- const prefix = `${pid} `;
9693
- const lines = existing.split(`
9694
- `);
9695
- const filtered = lines.filter((line) => !line.startsWith(prefix));
9696
- if (filtered.length === lines.length) {
9697
- return;
9698
- }
9699
- const content = filtered.join(`
9700
- `);
9701
- const tempPath = `${filePath}.tmp.${randomBytes(8).toString("hex")}`;
9702
- const fd = await open(tempPath, fsConstants.O_EXCL | fsConstants.O_CREAT | fsConstants.O_WRONLY, 384);
9703
- try {
9704
- await fd.writeFile(content, { encoding: "utf-8" });
9705
- } finally {
9706
- await fd.close();
9707
- }
9708
- await rename(tempPath, filePath);
9709
- await chmod(filePath, 384);
9710
- if (content.trim().length === 0) {
9711
- await unlink2(filePath);
9712
- }
9713
- });
9784
+ const hooksPromise = doInit();
9785
+ g[SINGLETON_KEY] = {
9786
+ pid: currentPid,
9787
+ loadedAt: Date.now(),
9788
+ hooksPromise,
9789
+ warned: false
9790
+ };
9791
+ return hooksPromise;
9714
9792
  }
9715
9793
 
9716
9794
  // src/tools/cancel.ts
@@ -9949,7 +10027,7 @@ function isTerminal(s) {
9949
10027
  return TERMINAL_STATUSES.has(s);
9950
10028
  }
9951
10029
  function setStatus(task, newStatus, options) {
9952
- if (isTerminal(task.status) && isTerminal(newStatus)) {
10030
+ if (isTerminal(task.status)) {
9953
10031
  return;
9954
10032
  }
9955
10033
  task.status = newStatus;
@@ -10359,7 +10437,7 @@ function getAgentsDirectories(directory) {
10359
10437
  repoAgentsDir: `${directory}/.github/agents`
10360
10438
  };
10361
10439
  }
10362
- var CopilotDelegate = async ({ client, directory }) => {
10440
+ async function initializePlugin({ client, directory }) {
10363
10441
  const agents = discoverAgents(getAgentsDirectories(directory));
10364
10442
  const delegateDescription = buildDescription(agents);
10365
10443
  const currentInstancePath = resolveInstancePidFilePath();
@@ -10385,7 +10463,21 @@ var CopilotDelegate = async ({ client, directory }) => {
10385
10463
  copilot_cancel: normalizeToolArgSchemas(createCancelTool())
10386
10464
  }
10387
10465
  };
10388
- };
10466
+ }
10467
+ var CopilotDelegate = async (input) => plugInOnce({
10468
+ doInit: () => initializePlugin(input),
10469
+ onDuplicate: (pid) => {
10470
+ const message = `[copilot-delegate] duplicate factory invocation in same process (pid=${pid}); reusing existing hooks. Multiple opencode.json sources may list this plugin.`;
10471
+ console.warn(message);
10472
+ input.client.app.log({
10473
+ body: {
10474
+ service: "copilot-delegate",
10475
+ level: "warn",
10476
+ message
10477
+ }
10478
+ }).catch(() => {});
10479
+ }
10480
+ });
10389
10481
  var src_default = CopilotDelegate;
10390
10482
  export {
10391
10483
  src_default as default
@@ -6,11 +6,27 @@ export interface ReapDeps {
6
6
  } | null>;
7
7
  isPluginAlive: (pid: number) => boolean;
8
8
  }
9
+ /**
10
+ * Aggregated outcome of a single `reapOrphans` invocation.
11
+ *
12
+ * `timedOut` is `true` when `reapOrphans` aborted due to its overall
13
+ * timeout budget. The flag distinguishes a successful no-op (no `.pids`
14
+ * files to scan, all counts naturally zero) from a timeout-aborted reap
15
+ * that stopped mid-flight (orphans may remain).
16
+ *
17
+ * IMPORTANT: when `timedOut` is `true`, the count fields are zero
18
+ * placeholders, NOT partial-progress accounting. In-flight workers may
19
+ * have already incremented internal counters or even invoked
20
+ * `killProcessTree` before the timeout fired, but those side effects are
21
+ * not reflected in the returned counts. Treat a timed-out result as "no
22
+ * reliable count signal" and consider warning or retrying.
23
+ */
9
24
  export interface ReapResult {
10
25
  reaped: number;
11
26
  skipped: number;
12
27
  scannedFiles: number;
13
28
  deletedFiles: number;
29
+ timedOut: boolean;
14
30
  }
15
31
  export declare function defaultIsPluginAlive(pid: number): boolean;
16
32
  /**
@@ -58,16 +74,13 @@ export declare function getPidIdentity(pid: number, timeoutMs?: number): Promise
58
74
  comm: string;
59
75
  lstart: string;
60
76
  } | null>;
61
- interface ReapOpts {
77
+ export interface ReapOptions extends Omit<ReapDeps, 'isPluginAlive'> {
62
78
  pidFileDir: string;
63
79
  currentInstancePath: string;
64
- killProcessTree: ReapDeps['killProcessTree'];
65
- getPidIdentity: ReapDeps['getPidIdentity'];
66
80
  isPluginAlive?: ReapDeps['isPluginAlive'];
67
81
  signal?: AbortSignal;
68
82
  psTimeoutMs?: number;
69
83
  }
70
- export declare function reapOrphans(opts: Omit<ReapOpts, 'signal'> & {
84
+ export declare function reapOrphans(opts: Omit<ReapOptions, 'signal'> & {
71
85
  reapTimeoutMs?: number;
72
86
  }): Promise<ReapResult>;
73
- export {};
@@ -1,3 +1,16 @@
1
1
  export declare function resolveInstancePidFilePath(): string;
2
2
  export declare function appendPidEntry(filePath: string, pid: number, comm: string, lstart: string): Promise<void>;
3
3
  export declare function removePidEntry(filePath: string, pid: number): Promise<void>;
4
+ /**
5
+ * Truncate a PID file under the same per-file serialize lock used by
6
+ * appendPidEntry/removePidEntry, so a concurrent writer cannot interleave
7
+ * with the truncation. ENOENT is silently swallowed in both forms:
8
+ * file-already-gone AND parent-directory-missing. Other errno values
9
+ * propagate.
10
+ */
11
+ export declare function truncatePidFile(filePath: string): Promise<void>;
12
+ /**
13
+ * Remove a PID file under the same per-file serialize lock. ENOENT is
14
+ * silently swallowed (file already gone). Other errno values propagate.
15
+ */
16
+ export declare function unlinkPidFile(filePath: string): Promise<void>;
@@ -0,0 +1,58 @@
1
+ /**
2
+ * Per-process singleton guard for the plugin factory.
3
+ *
4
+ * OpenCode invokes the plugin factory more than once per process when the
5
+ * same plugin is referenced by multiple config sources (for example a
6
+ * user-level `~/.config/opencode/opencode.json` AND a project-level
7
+ * `opencode.json`). Each invocation evaluates the plugin module fresh —
8
+ * module-local variables reset between calls — so the singleton state
9
+ * must live on `globalThis` to persist across module instances within
10
+ * the same process.
11
+ *
12
+ * On the first invocation the init runs normally and the resulting hooks
13
+ * promise is cached on `globalThis`. On subsequent invocations within
14
+ * the same PID the cached promise is returned and `onDuplicate` is
15
+ * invoked exactly once (subsequent duplicates are silent so logs do not
16
+ * spam). Across PIDs the singleton is treated as absent and init runs
17
+ * fresh — `globalThis` is per-process, but the explicit PID guard adds
18
+ * defensive belt-and-suspenders against any state-leakage edge case.
19
+ *
20
+ * The cached value is the init Promise rather than the resolved value so
21
+ * a second invocation that arrives while the first is still awaiting
22
+ * `mkdir` / `reapOrphans` converges on the same init result instead of
23
+ * starting a parallel init.
24
+ *
25
+ * **Known limitation — rejected init is cached.** If `doInit()` rejects,
26
+ * the rejected promise is stored on `globalThis` and every subsequent
27
+ * invocation in the same PID returns the same rejection without
28
+ * retrying init. This is intentional: re-running heavy init on every
29
+ * call would defeat the singleton's purpose. Recovery requires a
30
+ * process restart. OpenCode currently surfaces a failed plugin factory
31
+ * as a startup error rather than retrying within the process, so this
32
+ * matches the upstream contract.
33
+ */
34
+ export interface PlugInOnceOptions<T> {
35
+ /** Heavy init work that should run at most once per process. */
36
+ doInit: () => Promise<T>;
37
+ /**
38
+ * Called exactly once on the first duplicate invocation in the same
39
+ * process. Subsequent duplicates are silent. Receives the same `pid`
40
+ * value the guard used for its identity check (so test overrides flow
41
+ * through faithfully). Implementations must not throw; fire-and-forget
42
+ * side effects (logging, metrics) are expected. Synchronous exceptions
43
+ * are swallowed defensively.
44
+ */
45
+ onDuplicate?: (pid: number) => void;
46
+ /** Test override; defaults to `process.pid`. */
47
+ pid?: number;
48
+ }
49
+ /**
50
+ * Run `doInit` at most once per process, returning the cached hooks
51
+ * promise on subsequent invocations within the same PID.
52
+ */
53
+ export declare function plugInOnce<T>({ doInit, onDuplicate, pid, }: PlugInOnceOptions<T>): Promise<T>;
54
+ /**
55
+ * Test-only: clear the singleton state so the next invocation re-runs
56
+ * init. Must not be called in production code paths.
57
+ */
58
+ export declare function _resetPluginSingleton(): void;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "opencode-copilot-delegate",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "OpenCode plugin that delegates tasks to GitHub Copilot CLI as background subprocesses",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",