@byok-sdk/client 0.1.1 → 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,30 +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).
- *
- * This constant identifies the user-installed runtime for diagnostics and
- * documentation only. The client package deliberately does not install pi:
- * security-fixed pi releases require Node >=22.19 while this SDK supports
- * Node >=20, and runtime credentials/lifecycle remain user-owned.
+ * 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: 'path';
+    source: 'package' | 'env';
 }
 /**
- * Resolve the user-installed pi CLI executable.
+ * 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 PATH lookup 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.
  *
- * Resolution is deliberately the same authority shape as Claude Code and
- * Codex: an explicit product/test override, otherwise the user's PATH. The
- * SDK does not infer package-manager layouts or install a second runtime.
+ * 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 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). */