@byok-sdk/client 0.1.0 → 0.2.0

package/dist/adapters/pi/events.d.ts

@@ -1,44 +1,17 @@
 import type { AgentEvent } from '@byok-sdk/protocol';
 import type { PiRpcMessage } from './rpc-client';
 /**
- * ROOT CAUSE of the 2026-07-16 live GLM run's "finding #2" hang (task stuck
- * `Running` forever after pi streamed its final answer; pi process alive,
- * idle, no sockets, only stdio pipes): this mapper used to listen for a pi
- * event type `agent_settled` to know a whole run had finished. That type
- * does not exist anywhere in the real, installed
- * `@earendil-works/pi-coding-agent@0.74.2` package — not in its bundled
- * `docs/rpc.md`, not in `dist/modes/rpc/rpc-types.d.ts`, not in
- * `pi-agent-core`'s own `AgentEvent` union (`dist/types.d.ts`), and not
- * observed even once across live probes against real GLM traffic (raw JSONL
- * frame capture). The real "whole run is done, pi is idle again" signal is
- * `agent_end` — confirmed both by `pi-agent-core`'s own doc comment ("
- * `agent_end` is the last event emitted for a run... The agent becomes idle
- * only after those listeners finish") and empirically: a live run's frame
- * sequence ended `...turn_end (tool call), ..., turn_end (final text),
- * agent_end` with nothing further arriving even after an 8s idle-grace
- * window. Because this switch had no `agent_end` case, it fell to
- * `default: return undefined` — silently dropped — so `task-runner.ts`'s
- * `pump()` loop never saw a `turn_end` `AgentEvent` and blocked forever on
- * the next one. This repo's own fixture (`fake-pi.mjs`) masked the bug for
- * the whole M0/M1 test suite by emitting a fictional `agent_settled` frame
- * of its own alongside the real `agent_end` one — fixed alongside this
- * change (see fake-pi.mjs's doc comment).
+ * Map pi 0.84.1 RPC frames into BYOK's runtime-neutral event contract.
  *
- * `agent_end` (not pi's own per-LLM-turn `turn_end`) is what maps to our
- * `turn_end`: a single pi prompt can produce several internal turns (tool
- * round-trips, each ending its own real `turn_end`); only once the whole
- * run is settled (no auto-retry, compaction-retry, or queued continuation
- * left) is the task actually done. Forwarding pi's own `turn_end` 1:1 would
- * emit multiple confusing `turn_end`s for what the daemon must treat as one
- * task — empirically confirmed: a single-tool-call prompt produced two real
- * `turn_end` frames (one after the tool call, one after the final text) and
- * exactly one `agent_end`.
+ * `agent_settled` is the only whole-task completion authority. `agent_end`
+ * ends one low-level agent run, but pi may still perform retry/compaction or
+ * consume queued work before it emits `agent_settled`. Pi's own `turn_end`
+ * is even narrower: a tool-using prompt can emit several of them. Mapping
+ * either earlier boundary to BYOK `turn_end` would acknowledge the task
+ * before the runtime is actually idle.
  *
- * Returns undefined for pi messages with no protocol equivalent (session/
- * compaction/retry bookkeeping — see `ROUTINE_PI_EVENT_TYPES` below —
- * extension UI dialogs, which never reach here at all in production since
- * `PiRpcClient` answers them itself before they'd ever be queued as an
- * event; see rpc-client.ts).
+ * `message_update` is delta-only in this contract. The mapper forwards text
+ * deltas and never reads the removed cumulative `message`/`partial` fields.
  */
 export declare function mapPiMessageToAgentEvent(msg: PiRpcMessage): AgentEvent | undefined;
 /**
@@ -48,7 +21,7 @@ export declare function mapPiMessageToAgentEvent(msg: PiRpcMessage): AgentEvent
  * (pi-adapter.ts) calls `PiRpcClient.recordUnmappedFrame` for any message
  * type that maps to `undefined` AND isn't in this set — i.e. traffic nobody
  * has ever told this adapter to expect. That distinction is what makes a
- * regression like this file's root-cause bug (`agent_end` going unhandled)
+ * regression like a changed completion event
  * self-diagnosing: a warning fires the first time the new/renamed settle
  * event shows up, instead of the daemon just quietly hanging. `default`-only
  * unknowns (a type not listed in the switch at all) are equally "not

package/dist/adapters/pi/permission-mapping.d.ts

@@ -8,7 +8,7 @@ export interface PiPermissionMapping {
 }
 /**
  * Map an effective {@link PermissionPolicy} to `pi --mode rpc` CLI args,
- * fail-closed. Empirically grounded (see the M0-3 report):
+ * fail-closed against the exact pi 0.84.1 CLI contract:
  *
  * - `auto` / `readonly` are expressible via `--tools` / `--no-tools`.
  * - `confirm` and `plan` are NOT expressible: pi ships no built-in per-call
@@ -23,24 +23,8 @@ export interface PiPermissionMapping {
  * Workspace confinement is NOT a pi flag — the caller spawns pi with
  * `cwd: ctx.workspaceDir`, the daemon-created per-task directory.
  *
- * SECOND SELF-DISCOVERED FINDING, same class as the pi-adapter.ts
- * `--session-id` bug (this task, while hardening argv validation):
- * `--exclude-tools` — what `denyTools` used to map to — is ALSO not a real
- * pi CLI flag. Confirmed against real pi 0.74.2: `pi --mode rpc
- * --exclude-tools bash` → `Error: Unknown option: --exclude-tools`, exit
- * code 1, before any model call — and it's absent from both `pi --help`'s
- * own listing and the CLI's actual arg parser (`dist/cli/args.js`), which
- * recognizes only `--tools`/`-t`, `--no-tools`/`-nt`, `--no-builtin-tools`/
- * `-nbt` for tool control. This crashed EVERY real pi invocation for any
- * policy with a non-empty `denyTools`, unconditionally — never caught by
- * this repo's own test suite for the exact same reason as the
- * `--session-id` bug (`fake-pi.mjs` never validated argv; fixed alongside
- * this change). pi has no "start from the default set, minus these" flag at
- * all — `--tools` always REPLACES the active set wholesale — so `denyTools`
- * is now resolved to an equivalent allowlist in-process: readonly mode
- * intersects with `READONLY_TOOLS` (as before), any other mode starts from
- * an explicit `allowTools` or pi's own `DEFAULT_ACTIVE_TOOLS`, and
- * `denyTools` is subtracted from that resolved set before it's ever handed
- * to pi as a single `--tools`/`--no-tools` pair of args.
+ * - `--tools` is an allowlist and `--exclude-tools` is a denylist. Passing
+ *   both lets pi remain the authority for its active tool registry instead
+ *   of duplicating pi's default tool list in this adapter.
  */
 export declare function mapPermissionPolicyToPiArgs(policy: PermissionPolicy): PiPermissionMapping;

package/dist/adapters/pi/resolve-bin.d.ts

@@ -5,40 +5,34 @@
  * `@mariozechner/pi` — the identifier this task was originally briefed with —
  * is NOT the coding agent. On npm it resolves to an unrelated "CLI tool for
  * managing vLLM deployments on GPU pods" (bin: `pi-pods`). The real coding
- * agent was `@mariozechner/pi-coding-agent`, which is now itself deprecated
- * in favor of this package (same maintainers: badlogic, mitsuhiko), as of
- * literally the day before this was written. `package.json` pins the
- * `legacy-node20` dist-tag (0.74.2) rather than `latest` (0.80.7), because
- * `latest` requires Node >=22.19 while this SDK's baseline is Node >=20;
- * both versions were empirically confirmed to speak the identical RPC-mode
- * frame shapes this adapter depends on.
+ * agent was `@mariozechner/pi-coding-agent`, which is now deprecated in
+ * favor of this package. `package.json` carries the exact supported version
+ * as a required dependency; pi is a core BYOK capability, not an optional
+ * enhancement or an unversioned global executable.
  */
 export declare const PI_PACKAGE_NAME = "@earendil-works/pi-coding-agent";
 export interface ResolvedBin {
     command: string;
-    source: 'package' | 'path';
+    source: 'package' | 'env';
 }
 /**
- * Resolve the pi CLI executable. Prefers the optionalDependency installed
- * alongside @byok-sdk/client (guarantees a known-good, version-matched build);
- * falls back to whatever `pi` is on PATH so users with a pre-existing global
- * pi install still work even when the optionalDependency didn't install.
+ * Resolve the pi CLI executable from the required package installed alongside
+ * `@byok-sdk/client`. There is intentionally no automatic PATH fallback: a
+ * global `pi` would create a second, unversioned authority for this contract.
  *
- * `BYOK_PI_BIN` overrides both of the above when set: `PiAdapterOptions.resolveBin`
+ * `BYOK_PI_BIN` explicitly overrides the package when set: `PiAdapterOptions.resolveBin`
  * is the injectable seam for in-process tests, but the `byok-agent` CLI bin
  * only ever constructs `new PiAdapter()` with no options (see `createDaemon`),
  * so an out-of-process substitution (e.g. examples/basic's e2e run swapping
- * in the fake-pi fixture ahead of a real pi install) has no other seam to use.
+ * in the fake-pi fixture, or a single-file product injecting its required
+ * Node 22.19+ pi sidecar) has no other seam to use.
  *
  * Deliberately does NOT use `createRequire(...).resolve()`: this package is
  * pure ESM with no `require` export condition (`exports["."]` only offers
- * `import`), so CJS-style resolution fails outright with
- * `ERR_PACKAGE_PATH_NOT_EXPORTED` — empirically confirmed, not a hypothetical.
- * It also does NOT resolve the `./package.json` subpath directly (also not
- * exported by this package); instead it resolves the package's main entry
- * via `import.meta.resolve` and walks up parent directories to find the
- * package root (identified by a `package.json` whose `name` matches), which
- * is robust to `dist/` layout changes and to whether `./package.json` is
- * ever exported.
+ * `import`), so CJS-style resolution fails with
+ * `ERR_PACKAGE_PATH_NOT_EXPORTED`. It also does NOT resolve the
+ * `./package.json` subpath directly (also not exported); instead it resolves
+ * the package's main entry via `import.meta.resolve` and walks upward to the
+ * package root identified by its manifest name.
  */
 export declare function resolvePiBin(): ResolvedBin;

package/dist/adapters/pi/rpc-client.d.ts

@@ -58,10 +58,7 @@ export declare class PiRpcClient {
      * traffic. Logs once per distinct type (not per occurrence, so a
      * repeating unmapped type can't spam stdout); the running tally is also
      * folded into this client's exit-time error message (`buildExitError`) so
-     * a post-mortem on a failed/hung task has it without needing separate log
-     * scraping. This is the exact mechanism that would have turned this
-     * task's root-cause hang (`agent_end` arriving with no mapping) into a
-     * one-line, immediate warning instead of a silent stall.
+     * a post-mortem on a failed/hung task has it without separate log scraping.
      */
     recordUnmappedFrame(type: string): void;
     /** Best-effort teardown. SIGTERM on POSIX; `taskkill /T /F` on Windows to also reap child processes pi itself spawned (e.g. bash). */

package/dist/bin/byok-agent.js

@@ -714,7 +714,7 @@ function readPackageJson(dir) {
 function resolvePiBin() {
   const override = process.env.BYOK_PI_BIN;
   if (override) {
-    return { command: override, source: "path" };
+    return { command: override, source: "env" };
   }
   try {
     const mainEntryUrl = import.meta.resolve(PI_PACKAGE_NAME);
@@ -732,14 +732,19 @@ function resolvePiBin() {
       if (parent === dir) break;
       dir = parent;
     }
-  } catch {
+  } catch (cause) {
+    throw new Error(
+      `Required ${PI_PACKAGE_NAME} could not be resolved; install @byok-sdk/client dependencies or set BYOK_PI_BIN to a Node 22.19+ pi sidecar`,
+      { cause }
+    );
   }
-  return { command: "pi", source: "path" };
+  throw new Error(
+    `Required ${PI_PACKAGE_NAME} does not expose the pi CLI; reinstall the pinned dependency or set BYOK_PI_BIN to a Node 22.19+ pi sidecar`
+  );
 }
 
 // src/adapters/pi/permission-mapping.ts
 var READONLY_TOOLS = ["read", "grep", "find", "ls"];
-var DEFAULT_ACTIVE_TOOLS = ["read", "bash", "edit", "write"];
 function mapPermissionPolicyToPiArgs(policy) {
   if (policy.network === false) {
     return {
@@ -758,22 +763,18 @@ function mapPermissionPolicyToPiArgs(policy) {
   const denyTools = policy.denyTools ?? [];
   if (policy.mode === "readonly") {
     const base = policy.allowTools ? policy.allowTools.filter((tool) => READONLY_TOOLS.includes(tool)) : [...READONLY_TOOLS];
-    const effective = subtractDenied(base, denyTools);
-    return { ok: true, args: effective.length === 0 ? ["--no-tools"] : ["--tools", effective.join(",")] };
-  }
-  if (denyTools.length > 0) {
-    const base = policy.allowTools && policy.allowTools.length > 0 ? policy.allowTools : [...DEFAULT_ACTIVE_TOOLS];
-    const effective = subtractDenied(base, denyTools);
-    return { ok: true, args: effective.length === 0 ? ["--no-tools"] : ["--tools", effective.join(",")] };
+    if (base.length === 0) return { ok: true, args: ["--no-tools"] };
+    return {
+      ok: true,
+      args: ["--tools", base.join(","), ...denyTools.length > 0 ? ["--exclude-tools", denyTools.join(",")] : []]
+    };
   }
+  const args = [];
   if (policy.allowTools && policy.allowTools.length > 0) {
-    return { ok: true, args: ["--tools", policy.allowTools.join(",")] };
+    args.push("--tools", policy.allowTools.join(","));
   }
-  return { ok: true, args: [] };
-}
-function subtractDenied(tools, denyTools) {
-  const denied = new Set(denyTools);
-  return tools.filter((tool) => !denied.has(tool));
+  if (denyTools.length > 0) args.push("--exclude-tools", denyTools.join(","));
+  return { ok: true, args };
 }
 
 // src/adapters/pi/events.ts
@@ -798,7 +799,7 @@ function mapPiMessageToAgentEvent(msg) {
         output: { result: msg.result, isError: msg.isError === true }
       };
     }
-    case "agent_end":
+    case "agent_settled":
       return { type: "turn_end" };
     /**
      * `artifact` is NOT a real pi RPC message — pi's own `write` tool only
@@ -834,16 +835,22 @@ function mapPiMessageToAgentEvent(msg) {
     // `recordUnmappedFrame`) can tell "known, expected, silently ignored"
     // apart from "genuinely never seen before" (falls to `default` below).
     case "agent_start":
+    case "agent_end":
+    // one low-level run; `agent_settled` is BYOK completion
     case "turn_start":
     case "turn_end":
-    // pi's own per-LLM-turn boundary, not ours — see `agent_end` above
+    // pi's own per-LLM-turn boundary, not ours
     case "message_start":
     case "message_end":
+    case "bash_execution_update":
     case "tool_execution_update":
     case "queue_update":
     case "compaction_start":
     case "compaction_end":
     case "auto_retry_start":
+    case "summarization_retry_scheduled":
+    case "summarization_retry_attempt_start":
+    case "summarization_retry_finished":
     case "session_info_changed":
     case "thinking_level_changed":
       return void 0;
@@ -853,15 +860,20 @@ function mapPiMessageToAgentEvent(msg) {
 }
 var ROUTINE_PI_EVENT_TYPES = /* @__PURE__ */ new Set([
   "agent_start",
+  "agent_end",
   "turn_start",
   "turn_end",
   "message_start",
   "message_end",
+  "bash_execution_update",
   "tool_execution_update",
   "queue_update",
   "compaction_start",
   "compaction_end",
   "auto_retry_start",
+  "summarization_retry_scheduled",
+  "summarization_retry_attempt_start",
+  "summarization_retry_finished",
   "session_info_changed",
   "thinking_level_changed"
 ]);
@@ -995,10 +1007,7 @@ var PiRpcClient = class {
    * traffic. Logs once per distinct type (not per occurrence, so a
    * repeating unmapped type can't spam stdout); the running tally is also
    * folded into this client's exit-time error message (`buildExitError`) so
-   * a post-mortem on a failed/hung task has it without needing separate log
-   * scraping. This is the exact mechanism that would have turned this
-   * task's root-cause hang (`agent_end` arriving with no mapping) into a
-   * one-line, immediate warning instead of a silent stall.
+   * a post-mortem on a failed/hung task has it without separate log scraping.
    */
   recordUnmappedFrame(type) {
     const next = (this.unmappedFrameCounts.get(type) ?? 0) + 1;
@@ -1139,8 +1148,8 @@ var PiAdapter = class {
   options;
   id = "pi";
   async detect() {
-    const bin = this.resolveBin();
     try {
+      const bin = this.resolveBin();
       const { stdout, stderr } = await execFileAsync(bin.command, ["--version"], { timeout: DETECT_TIMEOUT_MS });
       const version = stdout.trim() || stderr.trim();
       const authPresent = KNOWN_PROVIDER_ENV_VARS.some((name) => process.env[name] !== void 0);
@@ -1317,7 +1326,7 @@ function mapPermissionPolicyToClaudeArgs(policy) {
   }
   if (policy.mode === "readonly") {
     const base = policy.allowTools ? policy.allowTools.filter((tool) => READONLY_TOOLS2.includes(tool)) : [...READONLY_TOOLS2];
-    const effective = subtractDenied2(base, denyTools);
+    const effective = subtractDenied(base, denyTools);
     return { ok: true, args: ["--permission-mode", "default", "--tools", effective.join(",")] };
   }
   if (denyTools.length > 0) {
@@ -1334,7 +1343,7 @@ function mapPermissionPolicyToClaudeArgs(policy) {
   }
   return { ok: true, args };
 }
-function subtractDenied2(tools, denyTools) {
+function subtractDenied(tools, denyTools) {
   const denied = new Set(denyTools);
   return tools.filter((tool) => !denied.has(tool));
 }
@@ -2274,9 +2283,10 @@ var CodexAdapter = class {
    * Two independently-verified channel gotchas apply here, the "pi lesson"
    * yet again:
    *   - `codex login status`'s human-readable "Logged in using ChatGPT"
-   *     message prints on STDERR, not stdout (the opposite-channel
-   *     counterpart of pi's own `--version`-goes-to-stderr surprise) — both
-   *     streams are checked here for exactly that reason.
+   *     message prints on STDERR, not stdout — both streams are checked
+   *     here for exactly that reason. pi's `--version` is the same class of
+   *     hazard from the other direction: its channel has moved between pi
+   *     releases (see ../pi/pi-adapter.ts), so neither stream is assumed.
    *   - The NOT-logged-in message/exit-code shape was deliberately never
    *     empirically tested: this machine has a real, live ChatGPT login, and
    *     running `codex logout` to observe the negative case would have