pi-link 0.6.0 → 0.6.1

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
@@ -6,6 +6,28 @@ This changelog is based on the git history from `2026-03-21` (initial commit) th
6
6
 
7
7
  ---
8
8
 
9
+ ## 0.6.1 — 2026-11-02
10
+
11
+ ### Fixed
12
+
13
+ - **✗ for host errors in `link_send` and `link_compact` results.** When the host rejects a call before pi-link runs it, such as a failed argument validation, a blocked call or an abort, or when the call throws, the result row now shows ✗ instead of ✓. Pi marks these errors in the render context, and Oh My Pi in the result (from source reading; not tested under Oh My Pi). pi-link's own errors keep ✗ and successes keep ✓. Only the icon changes: results, the wire and the skill are unchanged.
14
+
15
+ - **`pi-link <name>` rejects `--session-id`.** Pi's `--session-id` opens or creates a session by ID, so it passed through and either failed against the `--session` the wrapper adds or bypassed the lookup by name under the link name `<name>`. It now fails like the other session flags, with `Error: --session-id is managed by pi-link. Remove it.`
16
+
17
+ - **`pi-link <name> --` no longer lets session and link-name flags through.** The wrapper drops its own `--` and passes the rest to Pi, so a flag after it, such as `pi-link foo -- --session-id abc`, still reached Pi as a flag and bypassed the session lookup or the link name. Tokens after `--` are now refused like the ones before it, in any position, including after Pi's own `--`, because the wrapper cannot tell where Pi's options end. A prompt that only begins with a flag name, as in `pi-link foo -- -- "--session-id explained"`, still passes.
18
+
19
+ - **The CLI reads a `settings.json` that starts with a BOM.** `pi-link` ignored such a file with a warning and dropped its `sessionDir`, while Pi strips the BOM and uses it, so `--list`, `--resolve` and `pi-link <name>` could look in the default directory instead of Pi's. It now drops one leading BOM before parsing, as Pi does; a file that is still invalid JSON keeps the warning and is ignored.
20
+
21
+ ### Changed
22
+
23
+ - **A target no longer answers `unsupported`.** The `compact_request` branch that declined with it when the target had no context or no compaction capability was unreachable on every supported host, and is removed. A requester still reads `unsupported` from a target on an earlier version as `not done: compaction unavailable on target`.
24
+
25
+ - **Consistent CLI messages.** `pi-link --help`, `-h` and `pi-link` with no arguments now print the usage to stdout, as Pi does, so it can be piped or saved; exit codes are unchanged. The settings warning reads `Warning: Ignored <path>: <reason>` instead of `pi-link: ignored <path>: <reason>`. Prose after `Error: ` or `Warning: ` starts with a capital letter unless it begins with a literal token such as a flag, a quoted command or `pi-link`, as in `Error: Cannot combine --list and --resolve.`; sentences end with a period, and commands embedded in prose use double quotes, as in `"pi-link list" was removed. Use "pi-link --list".` The `--link-name` rejection now reads `Error: --link-name is not accepted by pi-link.` and points to `pi-link <name>` to open the named session on the link, or `pi --link-name <name>` to set only the link name.
26
+
27
+ - **Consistent extension messages.** The `link_compact` self-target result reads `Cannot compact yourself`, without a period, like `link_send`'s `Cannot send to yourself`; `/link` when disconnected warns `Not connected to the link`, the text the tools return, instead of `Link: not connected`.
28
+
29
+ ---
30
+
9
31
  ## 0.6.0 — 2026-10-25
10
32
 
11
33
  ### Changed
package/README.md CHANGED
@@ -243,7 +243,7 @@ The tool's parameters are:
243
243
  - **Success** — `compacted`. Compaction finished, but this does not reserve the target: it may be busy again by the next request.
244
244
  - **Already requested** — `not done: target already has a compaction request waiting or running`. A target holds one request at a time, from any requester; another one is declined rather than queued, merged or allowed to replace it.
245
245
  - **Navigation** — `not done: target navigated its session tree while the request waited`. Completing a `/tree` navigation on the target ends a request that has not started. A running compaction is unaffected, and other session changes, such as new messages or a session rename, end nothing.
246
- - **Other declines or errors** — `not done: compaction unavailable on target` if the target has no compaction available when the request arrives, or `not done: target not found` if the target cannot be found when the request is routed. The wire carries the codes `already_requested`, `tree_navigated`, `unsupported` and `not_found`; the requester shows them as this text. Pi may report a reason such as `Nothing to compact (session too small)` or `Already compacted`; runtime errors and cancellations also appear after `not done: `.
246
+ - **Other declines or errors** — `not done: target not found` if the target cannot be found when the request is routed. The wire carries the codes `already_requested`, `tree_navigated`, `not_found` and `unsupported`; the requester shows them as this text, and `unsupported`, which only earlier versions send, as `not done: compaction unavailable on target`. Pi may report a reason such as `Nothing to compact (session too small)` or `Already compacted`; runtime errors and cancellations also appear after `not done: `.
247
247
  - **Earlier target** — `not done: target busy`. A target on an earlier pi-link version declines at once while busy instead of waiting.
248
248
  - **Departure** — `left the link before answering; result unknown`. The target may or may not have compacted. A target that disconnects or ends its session drops a request it has not started, so this is also how such a request ends.
249
249
  - **Disconnect** — `/link-disconnect` in the requesting terminal reports outstanding requests as `link disconnected before an answer; result unknown, the target may still be compacting`.
@@ -350,7 +350,7 @@ Lookup is **scoped to the current cwd by default**; pass `--global` (`-g`) to co
350
350
  - **One match in scope** → resumes that session
351
351
  - **No match in scope** → creates a new session in the current cwd, and advises `--global` without claiming a session exists elsewhere.
352
352
  - **Multiple matches in scope** → prints candidates to stderr, exits 1
353
- - **Conflicting flags** (`--session`, `--continue`, `--resume`, `--fork`, etc.) → rejected with an error
353
+ - **Conflicting flags** (`--session`, `--session-id`, `--continue`, `--resume`, `--fork`, etc.) → rejected with an error
354
354
 
355
355
  ### Discovering sessions
356
356
 
@@ -736,9 +736,9 @@ Delivery is held while a `manual`-reason compaction holds this terminal's gate,
736
736
 
737
737
  ### Remote compaction
738
738
 
739
- The tool returns the request ID in `details.id` as well as in its sent text. Failures before sending return immediately without a later outcome: `not_connected`, `self_target` (`Cannot compact yourself.`), `not_found` for a target absent from the requester's group list, `aborted` for an already-aborted call, or `not_delivered` if routing could not hand the request on. These tool-result errors are distinct from a later `not done: <reason>` notification.
739
+ The tool returns the request ID in `details.id` as well as in its sent text. Failures before sending return immediately without a later outcome: `not_connected`, `self_target` (`Cannot compact yourself`), `not_found` for a target absent from the requester's group list, `aborted` for an already-aborted call, or `not_delivered` if routing could not hand the request on. These tool-result errors are distinct from a later `not done: <reason>` notification.
740
740
 
741
- A `compact_request` is answered at once with `unsupported` if the target has no compaction capability, and with `already_requested` if another request holds the target's one slot. Otherwise it takes that slot, `remoteCompact`, and starts at once if Pi reports the session idle and no compaction gate stands. If not, a single `setTimeout` checks again every `COMPACT_WAIT_CHECK_MS` while it waits; there is no deadline, and waiting raises no gate. Polling is deliberate: Pi emits `session_compact` before it clears its own compacting state, and a gate left by a failed compaction is released by its backstop or the next run, so no event marks every moment the target becomes free. Each check reads local state only. A request is served by calling `ctx.compact()` — the same operation as `/compact`. The requester is answered with a `compact_response` carrying its request ID when the runtime reports a result through `onComplete`/`onError`, once; a failure is not retried. A waiting request is dropped unanswered by `disconnect()` and teardown, and answered with `tree_navigated` after a completed tree navigation; a running one keeps its slot until its compaction ends. Each call targets one terminal, independent requests can be outstanding concurrently, and link participants are cooperating peers: nothing here is privileged.
741
+ A `compact_request` is answered at once with `already_requested` if another request holds the target's one slot. Otherwise it takes that slot, `remoteCompact`, and starts at once if Pi reports the session idle and no compaction gate stands. If not, a single `setTimeout` checks again every `COMPACT_WAIT_CHECK_MS` while it waits; there is no deadline, and waiting raises no gate. Polling is deliberate: Pi emits `session_compact` before it clears its own compacting state, and a gate left by a failed compaction is released by its backstop or the next run, so no event marks every moment the target becomes free. Each check reads local state only. A request is served by calling `ctx.compact()` — the same operation as `/compact`. The requester is answered with a `compact_response` carrying its request ID when the runtime reports a result through `onComplete`/`onError`, once; a failure is not retried. A waiting request is dropped unanswered by `disconnect()` and teardown, and answered with `tree_navigated` after a completed tree navigation; a running one keeps its slot until its compaction ends. Each call targets one terminal, independent requests can be outstanding concurrently, and link participants are cooperating peers: nothing here is privileged.
742
742
 
743
743
  Serving a request raises the inbox gates in order, and not always both. `compactRunning` is set synchronously before `ctx.compact()` is called; `localCompacting` rises only if execution reaches the manual `session_before_compact` hook, so a runtime that refuses early — nothing to compact, already compacted, or another preparation failure — returns through `onError` without the local gate ever going up. When the compaction does succeed, `session_compact` clears the local gate first, and the later `finish()` clears `compactRunning` and calls `releaseInbox()`, which is what drains the inbox.
744
744
 
package/bin/pi-link.mjs CHANGED
@@ -39,9 +39,10 @@ function readSessionDirFromSettings(settingsPath) {
39
39
  if (!existsSync(settingsPath)) return undefined;
40
40
  let parsed;
41
41
  try {
42
- parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
42
+ // Like Pi's stripBom, drop one leading BOM before parsing.
43
+ parsed = JSON.parse(readFileSync(settingsPath, "utf-8").replace(/^\uFEFF/, ""));
43
44
  } catch (err) {
44
- console.error(`pi-link: ignored ${settingsPath}: ${err.message}`);
45
+ console.error(`Warning: Ignored ${settingsPath}: ${err.message}`);
45
46
  return undefined;
46
47
  }
47
48
  const value = parsed?.sessionDir;
@@ -193,7 +194,7 @@ async function scanSessions(dir, isCustom, scopeCwd) {
193
194
  entries = await readdir(dir, { withFileTypes: true });
194
195
  } catch (err) {
195
196
  if (err.code === "ENOENT") return [];
196
- fail(`cannot read session directory: ${err.message}`);
197
+ fail(`Cannot read session directory: ${err.message}`);
197
198
  }
198
199
 
199
200
  const tasks = [];
@@ -278,13 +279,13 @@ function rejectManagedFlag(token) {
278
279
  const key = token.split("=")[0];
279
280
  if (key === "--link-name") {
280
281
  console.error(
281
- "Error: --link-name is not accepted by the pi-link wrapper.\n" +
282
- " Use 'pi-link <name>' for combined link+session,\n" +
283
- " or run 'pi --link-name <name>' directly to set link name without session resolution.",
282
+ "Error: --link-name is not accepted by pi-link.\n" +
283
+ ' Use "pi-link <name>" to open the named session on the link,\n' +
284
+ ' or "pi --link-name <name>" to set only the link name.',
284
285
  );
285
286
  process.exit(1);
286
287
  }
287
- if (["--session", "--continue", "-c", "--resume", "-r", "--fork", "--no-session", "--session-dir"].includes(key)) {
288
+ if (["--session", "--continue", "-c", "--resume", "-r", "--fork", "--no-session", "--session-dir", "--session-id"].includes(key)) {
288
289
  console.error(`Error: ${key} is managed by pi-link. Remove it.`);
289
290
  process.exit(1);
290
291
  }
@@ -306,15 +307,15 @@ function fail(msg) {
306
307
  }
307
308
 
308
309
  function printHelp() {
309
- console.error("Usage: pi-link <name> [--global|-g] [pi flags...]");
310
- console.error(" pi-link --list [--global|-g]");
311
- console.error(" pi-link --status [--json]");
312
- console.error(" pi-link --resolve <name> [--global|-g]");
313
- console.error(" pi-link --version");
314
- console.error("");
315
- console.error("By default, name lookup is scoped to the current cwd.");
316
- console.error("--global / -g widens the search to sessions in any cwd.");
317
- console.error("--list reads saved sessions; --status asks the running hub who is connected.");
310
+ console.log("Usage: pi-link <name> [--global|-g] [pi flags...]");
311
+ console.log(" pi-link --list [--global|-g]");
312
+ console.log(" pi-link --status [--json]");
313
+ console.log(" pi-link --resolve <name> [--global|-g]");
314
+ console.log(" pi-link --version");
315
+ console.log("");
316
+ console.log("By default, name lookup is scoped to the current cwd.");
317
+ console.log("--global / -g widens the search to sessions in any cwd.");
318
+ console.log("--list reads saved sessions; --status asks the running hub who is connected.");
318
319
  }
319
320
 
320
321
  function printVersion() {
@@ -322,9 +323,9 @@ function printVersion() {
322
323
  try {
323
324
  pkg = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf-8"));
324
325
  } catch (err) {
325
- fail(`cannot read pi-link's package.json: ${err.message}`);
326
+ fail(`Cannot read pi-link's package.json: ${err.message}`);
326
327
  }
327
- if (!pkg.version) fail("pi-link's package.json has no version");
328
+ if (!pkg.version) fail("pi-link's package.json has no version.");
328
329
  console.log(pkg.version);
329
330
  }
330
331
 
@@ -360,7 +361,7 @@ const state = {
360
361
 
361
362
  function setMode(mode) {
362
363
  if (state.mode !== null && state.mode !== mode) {
363
- fail(`cannot combine ${describeMode(state.mode)} and ${describeMode(mode)}`);
364
+ fail(`Cannot combine ${describeMode(state.mode)} and ${describeMode(mode)}.`);
364
365
  }
365
366
  state.mode = mode;
366
367
  }
@@ -387,10 +388,13 @@ for (let i = 0; i < rawArgs.length; i++) {
387
388
  if (a === "--") {
388
389
  // `--` only meaningful in launcher mode (separates pi flags from positionals).
389
390
  if (state.mode !== "launcher") {
390
- fail(`-- is only valid after a session name`);
391
+ fail(`-- is only valid after a session name.`);
391
392
  }
392
- for (let j = i + 1; j < rawArgs.length; j++) {
393
- state.piPassthrough.push(rawArgs[j]);
393
+ // The wrapper drops its own `--`, so the tokens after it still reach pi and can
394
+ // be options. Managed flags are refused in any position, as before the `--`.
395
+ for (const token of rawArgs.slice(i + 1)) {
396
+ rejectManagedFlag(token);
397
+ state.piPassthrough.push(token);
394
398
  }
395
399
  i = rawArgs.length;
396
400
  break;
@@ -417,13 +421,13 @@ for (let i = 0; i < rawArgs.length; i++) {
417
421
  }
418
422
  if (a.startsWith("--resolve=")) {
419
423
  setMode("resolve");
420
- if (state.resolveName !== null) fail(`--resolve specified more than once`);
424
+ if (state.resolveName !== null) fail(`--resolve specified more than once.`);
421
425
  state.resolveName = a.slice("--resolve=".length);
422
426
  continue;
423
427
  }
424
428
  if (a === "--resolve") {
425
429
  setMode("resolve");
426
- if (state.resolveName !== null) fail(`--resolve specified more than once`);
430
+ if (state.resolveName !== null) fail(`--resolve specified more than once.`);
427
431
  const next = rawArgs[i + 1];
428
432
  if (next === undefined || next.startsWith("-")) {
429
433
  fail(`--resolve requires a name argument.\n Usage: pi-link --resolve <name> [--global|-g]`);
@@ -441,7 +445,7 @@ for (let i = 0; i < rawArgs.length; i++) {
441
445
  fail(`--version does not accept arguments: ${a}`);
442
446
  }
443
447
  if (state.mode === "list") {
444
- fail(`--list does not accept argument: ${a}\n Usage: pi-link --list [--global|-g]`);
448
+ fail(`--list does not accept arguments: ${a}\n Usage: pi-link --list [--global|-g]`);
445
449
  }
446
450
  if (state.mode === "status") {
447
451
  fail(`--status does not accept arguments: ${a}\n Usage: pi-link --status [--json]`);
@@ -458,7 +462,7 @@ for (let i = 0; i < rawArgs.length; i++) {
458
462
  fail(`Unknown argument: ${a}\n Usage: pi-link <name> [--global|-g] [pi flags...]`);
459
463
  }
460
464
  if (a === "list" || a === "resolve") {
461
- fail(`'pi-link ${a}' was removed. Use 'pi-link --${a}'.`);
465
+ fail(`"pi-link ${a}" was removed. Use "pi-link --${a}".`);
462
466
  }
463
467
  state.mode = "launcher";
464
468
  state.launcherName = a;
@@ -498,15 +502,15 @@ if (state.mode === "resolve") {
498
502
  // `--status` reads one running hub, so a cwd scope is meaningless rather than
499
503
  // merely unused: silently ignoring `-g` would imply a filter that cannot exist.
500
504
  if (state.mode === "status" && state.global) {
501
- fail(`cannot combine --status and --global`);
505
+ fail(`Cannot combine --status and --global.`);
502
506
  }
503
507
  if (state.json && state.mode !== "status") {
504
- fail(`--json is only valid with --status`);
508
+ fail(`--json is only valid with --status.`);
505
509
  }
506
510
  if (state.mode === "launcher") {
507
511
  const normalized = normalizeName(state.launcherName);
508
512
  if (!normalized) {
509
- fail(`session name cannot be empty.\n Usage: pi-link <name> [--global|-g] [pi flags...]`);
513
+ fail(`Session name cannot be empty.\n Usage: pi-link <name> [--global|-g] [pi flags...]`);
510
514
  }
511
515
  state.launcherName = normalized;
512
516
  }
@@ -534,7 +538,7 @@ switch (state.mode) {
534
538
  await runLauncher(state);
535
539
  break;
536
540
  default:
537
- fail(`internal error: unknown mode ${state.mode}`);
541
+ fail(`Internal error: unknown mode ${state.mode}`);
538
542
  }
539
543
 
540
544
  // ── Mode handlers ──────────────────────────────────────────────────────────
package/index.ts CHANGED
@@ -150,7 +150,8 @@ function piVersionSupported(version: string): boolean {
150
150
  /**
151
151
  * The reason a `compact_response` gives, as the requester shows it. The wire keeps
152
152
  * the codes; anything else, such as a runtime's own message, is shown as sent.
153
- * Only targets on earlier versions answer `busy`: they declined instead of waiting.
153
+ * Only targets on earlier versions answer `busy` (they declined instead of waiting)
154
+ * or `unsupported`.
154
155
  */
155
156
  function compactReasonText(reason: string | undefined): string {
156
157
  switch (reason) {
@@ -974,25 +975,22 @@ export default function (pi: ExtensionAPI) {
974
975
 
975
976
  // ── Another terminal asks us to compact our context ──
976
977
  case "compact_request": {
977
- // Answered at once, without taking the request on: with no capability or no
978
- // context there is nothing to wait for, and a second request is refused
979
- // rather than queued, merged or allowed to replace the held one.
980
- if (!ctx || !ctx.compact) {
981
- answerCompact(msg, false, "unsupported");
982
- break;
983
- }
978
+ // A second request is refused at once rather than queued, merged or
979
+ // allowed to replace the held one.
984
980
  if (remoteCompact) {
985
981
  answerCompact(msg, false, "already_requested");
986
982
  break;
987
983
  }
984
+ // Messages are handled only while isRuntimeLive(), which requires ctx.
985
+ const context = ctx!;
988
986
  remoteCompact = msg;
989
987
  notify(
990
- remoteCompactMustWait(ctx)
988
+ remoteCompactMustWait(context)
991
989
  ? `"${msg.from}" asked this terminal to compact; waiting until it is idle`
992
990
  : `"${msg.from}" asked this terminal to compact`,
993
991
  "info",
994
992
  );
995
- startRemoteCompactWhenFree(msg, ctx);
993
+ startRemoteCompactWhenFree(msg, context);
996
994
  break;
997
995
  }
998
996
 
@@ -1637,14 +1635,26 @@ export default function (pi: ExtensionAPI) {
1637
1635
  );
1638
1636
  }
1639
1637
 
1640
- // Shared ✓/✗ result renderer for link_send and link_compact.
1638
+ // Shared ✓/✗ result renderer for link_send and link_compact. Host errors
1639
+ // (a failed validation, a blocked call, a throw) need not set details.error: Pi
1640
+ // flags them in the render context, Oh My Pi in result.isError, where the fourth
1641
+ // argument is the call's arguments instead.
1641
1642
  function renderIconResult(
1642
- result: { content: { type: string; text?: string }[]; details?: unknown },
1643
+ result: {
1644
+ content: { type: string; text?: string }[];
1645
+ details?: unknown;
1646
+ isError?: boolean;
1647
+ },
1643
1648
  theme: { fg(role: string, text: string): string },
1649
+ context?: { isError?: boolean },
1644
1650
  ) {
1645
1651
  const txt = result.content[0];
1646
1652
  const details = result.details as Record<string, unknown> | undefined;
1647
- const icon = details?.error
1653
+ const failed =
1654
+ context?.isError === true ||
1655
+ result.isError === true ||
1656
+ Boolean(details?.error);
1657
+ const icon = failed
1648
1658
  ? theme.fg("error", "✗ ")
1649
1659
  : theme.fg("success", "✓ ");
1650
1660
  return new Text(icon + (txt?.type === "text" ? txt.text : ""), 0, 0);
@@ -1720,7 +1730,8 @@ export default function (pi: ExtensionAPI) {
1720
1730
  return new Text(text, 0, 0);
1721
1731
  },
1722
1732
 
1723
- renderResult: (result, _options, theme) => renderIconResult(result, theme),
1733
+ renderResult: (result, _options, theme, context) =>
1734
+ renderIconResult(result, theme, context),
1724
1735
  });
1725
1736
 
1726
1737
  pi.registerTool({
@@ -1754,7 +1765,7 @@ export default function (pi: ExtensionAPI) {
1754
1765
  if (role === "disconnected") return notConnectedResult();
1755
1766
 
1756
1767
  if (params.to === terminalName) {
1757
- return textResult("Cannot compact yourself.", {
1768
+ return textResult("Cannot compact yourself", {
1758
1769
  to: params.to,
1759
1770
  error: "self_target",
1760
1771
  });
@@ -1804,7 +1815,8 @@ export default function (pi: ExtensionAPI) {
1804
1815
  return new Text(text, 0, 0);
1805
1816
  },
1806
1817
 
1807
- renderResult: (result, _options, theme) => renderIconResult(result, theme),
1818
+ renderResult: (result, _options, theme, context) =>
1819
+ renderIconResult(result, theme, context),
1808
1820
  });
1809
1821
 
1810
1822
  pi.registerTool({
@@ -1894,7 +1906,7 @@ export default function (pi: ExtensionAPI) {
1894
1906
  description: "Show link status",
1895
1907
  handler: async (_args, _ctx) => {
1896
1908
  if (role === "disconnected") {
1897
- _ctx.ui.notify("Link: not connected", "warning");
1909
+ _ctx.ui.notify("Not connected to the link", "warning");
1898
1910
  return;
1899
1911
  }
1900
1912
  const visible = visibleTerminals();
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-link",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "WebSocket-based inter-terminal communication for Pi. Connect multiple Pi terminals over a local link network.",
5
5
  "author": "alvivar",
6
6
  "license": "MIT",