@byok-sdk/client 0.1.0

package/dist/bin/approval-mcp-server.d.ts

@@ -0,0 +1,69 @@
+/**
+ * M4 Phase 3: the testable core of `byok-approval-mcp` (`byok-approval-mcp.ts`
+ * is the thin stdio-wiring entry point — mirrors this repo's existing
+ * `bin/commands/*.ts` split: real logic lives in a plain module, the bin
+ * script itself is glue no test ever imports directly).
+ *
+ * `byok-approval-mcp` is the MCP stdio server `claude`'s own
+ * `--permission-prompt-tool` spawns AS ITS OWN CHILD PROCESS when the claude
+ * adapter runs a task under `PermissionPolicy.mode: 'confirm'` (see
+ * `../adapters/claude/permission-mapping.ts`'s `confirm`-mode doc comment).
+ * It implements just enough of the MCP stdio transport (JSON-RPC 2.0,
+ * newline-delimited, per the spec) to expose ONE tool — empirically
+ * confirmed end-to-end against the real installed claude 2.1.216 binary
+ * (M4 Phase 3 STEP 0): `initialize` -> `notifications/initialized` ->
+ * `tools/list` -> `tools/call`, with the tool's arguments shaped exactly
+ * `{tool_name, input, tool_use_id}` (claude's own real wire shape,
+ * live-captured) and its expected response shaped
+ * `{content:[{type:'text', text: JSON.stringify({behavior:'allow',
+ * updatedInput} | {behavior:'deny', message})}]}` — the SAME shape the
+ * Claude Agent SDK's in-process `canUseTool` callback returns (see
+ * platform.claude.com/docs/en/agent-sdk/user-input), just crossing a
+ * process boundary via MCP instead of an in-process function call.
+ */
+export declare const APPROVAL_TOOL_NAME = "approval_prompt";
+/** Bound on how much of a tool call's `input` gets folded into the wire `task.await_approval.summary` — mirrors `events.ts`'s `RESULT_DIAGNOSTIC_MAX_CHARS`/`truncateResultDiagnostic` convention: a human-facing summary, not a full audit record. */
+export declare const APPROVAL_SUMMARY_MAX_CHARS = 500;
+/** `${toolName}: ${input}`, bounded — the human-readable description carried into `task.await_approval.summary` and (via the daemon/CLI's own rendering) whatever a real approver actually reads before deciding. */
+export declare function summarizeToolCall(toolName: string, input: unknown): string;
+export interface ApprovalOutcome {
+    approved: boolean;
+    reason?: string;
+}
+/** What `byok-approval-mcp.ts` (the real entry point) injects — the one real dependency this module has on the outside world. */
+export interface ApprovalMcpDeps {
+    /** Requests a decision from the daemon this task is running on. Any rejection/throw here is treated as fail-closed (deny) by `handleMcpRequest` — never surfaced to claude as a raw protocol error. */
+    requestApproval(taskId: string, summary: string): Promise<ApprovalOutcome>;
+}
+interface JsonRpcRequestLike {
+    jsonrpc?: unknown;
+    id?: unknown;
+    method?: unknown;
+    params?: unknown;
+}
+/**
+ * Handles exactly one already-parsed JSON-RPC request object and returns the
+ * exact response object to write back (`undefined` for a notification that
+ * expects no reply, e.g. `notifications/initialized`) — no stdio/process
+ * concerns at all, so tests call this directly with a stub {@link
+ * ApprovalMcpDeps} instead of spawning a real process or a real control
+ * socket. `serveApprovalMcpOverStdio` below is the only caller in production.
+ */
+export declare function handleMcpRequest(req: JsonRpcRequestLike, deps: ApprovalMcpDeps, taskId: string): Promise<Record<string, unknown> | undefined>;
+export interface ServeApprovalMcpOptions {
+    taskId: string;
+    deps: ApprovalMcpDeps;
+    /** Defaults to `process.stdin`/`process.stdout` — overridable so tests can drive this over in-memory streams. */
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+}
+/**
+ * Wires {@link handleMcpRequest} to real NDJSON stdio (the MCP stdio
+ * transport: one JSON-RPC message per line, both directions) — the only
+ * genuinely process-shaped piece of this module. Each line is handled
+ * independently and asynchronously (never serialized against the others),
+ * since claude's own parallel-tool-use can legitimately fire more than one
+ * concurrent `tools/call` over the same connection.
+ */
+export declare function serveApprovalMcpOverStdio(opts: ServeApprovalMcpOptions): void;
+export {};

package/dist/bin/audit-log.d.ts

@@ -0,0 +1,212 @@
+import { type DaemonEvent, type DaemonEventListener } from '../index';
+/**
+ * The audit log is the ONLY channel a separate, short-lived CLI invocation
+ * (`status`/`tasks`/`tasks --follow`) has into what an already-running
+ * `byok-agent start` process has observed — see `byok-agent.ts`'s header
+ * comment for the full read-model rationale. One JSON line per
+ * `DaemonEvent`, oldest first, append-only.
+ *
+ * Finding P1 #3 (SECURITY): a `DaemonEvent` can carry a task's raw
+ * instruction-derived output — `tool_use.input`/`tool_result.output` are
+ * `z.unknown()` in `@byok-sdk/protocol` (a shell command, a whole file's
+ * contents echoed back, anything), `progress`/`needs_approval`/`completed`/
+ * `failed`/`cancelled` all carry free-form agent/operator text, and
+ * `artifact.inline` is literally base64 file bytes. Persisting all of that
+ * VERBATIM into a durable, append-only, potentially long-retained file —
+ * previously created at the default `0666 & umask` mode (NOT 0600), with
+ * `storeDir` only chmod'd 0700 at the moment it's first created (a
+ * pre-existing custom `storeDir` kept whatever mode it already had) — is
+ * exactly the kind of thing that turns "helpful audit trail" into "durable
+ * secret/credential/source leak" the moment anything else on the machine can
+ * read it. Fixed on two independent axes:
+ *
+ * 1. **Redaction** (`redactForAudit`/`redactAgentEvent`): only event type,
+ *    taskId, timestamps, tool/runtime NAMES, sizes/counts, and closed-enum
+ *    state fields are ever written to disk — every free-form text/bytes
+ *    field is replaced with its byte SIZE. `readAuditEvents`/`followAuditLog`
+ *    reconstruct a `DaemonEvent`-shaped value from that redacted projection
+ *    for their callers (`tasks-view.ts`/`format.ts` stay unchanged and none
+ *    the wiser) by substituting an unambiguous `[redacted: N bytes]`
+ *    placeholder wherever real content used to be — so a replayed
+ *    `tasks`/`status`/`tasks --follow` view degrades to showing sizes
+ *    instead of content, which is the correct, honest trade-off for a
+ *    broadly-readable-by-default durable file. The LIVE human-facing stdout
+ *    stream (`bin/commands/start.ts`, fed directly from the in-memory
+ *    `DaemonEvent` before it ever reaches this module) is unaffected and
+ *    keeps full fidelity — this redaction applies ONLY to what's written to
+ *    disk.
+ * 2. **Permissions**: the file is tightened to 0600 BEFORE any new content
+ *    is written, on every single append (mirrors `util/atomic-write.ts`'s
+ *    own defensive re-chmod, for the identical reason: `open()`'s own
+ *    `mode` argument only governs permissions at CREATION time, so a
+ *    pre-existing file — predating this fix, or loosened by something else
+ *    — keeps whatever mode it already had until explicitly chmod'd).
+ *    `storeDir` gets the same defensive re-`chmod` to 0700 on every append.
+ *
+ *    Finding P1 #3b (STILL-OPEN, now fixed): the chmod used to run AFTER
+ *    `appendFile` rather than before — for a pre-existing permissive file
+ *    that meant the newly-appended line briefly landed in a file that was
+ *    still world-readable, and if `appendFile` itself failed, the chmod
+ *    (being sequenced after it) never ran at all, leaving the file exactly
+ *    as permissive as it started. Fixed by reordering so the chmod always
+ *    happens FIRST: there is no window where a new append lands in a
+ *    still-permissive file, and the tightening takes effect even when the
+ *    append that follows it fails. This closes the gap going forward; it
+ *    does NOT retroactively scrub plaintext a pre-fix build of this code
+ *    may have already written into an inherited permissive file — only
+ *    that the file stops being world-readable from the first append
+ *    onward.
+ *
+ * Finding P2/#11 (audit half): also bounded/rotated now — `appendAuditEvent`
+ * checks the file's size (cheap `fs.stat`) on every append and, once it
+ * exceeds `MAX_AUDIT_LOG_BYTES`, atomically rewrites it down to the most
+ * recent `AUDIT_LOG_TRIM_TARGET_LINES` lines (reusing `atomicWriteFile`, so
+ * a concurrent `tasks`/`tasks --follow` read never observes a torn file
+ * mid-rotation) — so a long-lived daemon's audit.jsonl no longer grows
+ * forever. `followAuditLog` no longer re-reads the entire file every poll
+ * either; see its own doc comment.
+ *
+ * Finding P2 (new, round 1, now fixed): that trim used to be purely
+ * positional (the most recent N lines, full stop) — which could evict
+ * EVERY event a still-running task ever had if it went quiet for long
+ * enough, permanently erasing it from `tasks`/`status` even though it was
+ * never actually done. `compactPreservingLiveTasks` now preserves one
+ * lifecycle-anchor line for any still-open (non-terminal) task that would
+ * otherwise be fully evicted — see its own doc comment.
+ *
+ * Finding P2 (new, round 2, now fixed): round 1's anchor preservation had no
+ * cap of its own — a daemon that crashes leaving many non-terminal tasks
+ * behind (or one that keeps creating non-terminal tasks that never reach a
+ * terminal kind) accumulates one anchor per distinct non-terminal taskId
+ * FOREVER, defeating `MAX_AUDIT_LOG_BYTES`'s own size cap (the whole point
+ * of rotation) and making every append past the cap an ever-larger O(n)
+ * read + atomic-rewrite. `compactPreservingLiveTasks` now also bounds the
+ * anchors themselves to `MAX_LIVE_TASK_ANCHORS`, keeping the most
+ * recently-touched ones and dropping the oldest overflow with a single
+ * logged warning — see that constant's own doc comment.
+ */
+export declare function auditLogPath(storeDir: string): string;
+/**
+ * Finding P2/#11 (audit half): rotate once the file exceeds this size,
+ * trimming to the most recent `AUDIT_LOG_TRIM_TARGET_LINES` lines. Checked
+ * via a cheap `fs.stat` (O(1), not a full read) on every single append; the
+ * expensive read-all-lines + atomic-rewrite only actually runs once the cap
+ * is crossed, and trimming well under the cap (redacted lines are small —
+ * mostly ids/sizes/counts) means it won't immediately re-trigger on the next
+ * append either. Deliberately simple size/line based bounding, not a
+ * time-based retention policy — "keep it simple" per this finding's own
+ * scope note.
+ */
+export declare const MAX_AUDIT_LOG_BYTES: number;
+export declare const AUDIT_LOG_TRIM_TARGET_LINES = 5000;
+/**
+ * Finding P2 (new, round 2): the hard cap on how many non-terminal-task
+ * lifecycle anchors {@link compactPreservingLiveTasks} will ever preserve in
+ * a single rotation — without this, a daemon that crashes leaving many
+ * non-terminal tasks behind (or a bug that keeps creating tasks that never
+ * reach a terminal kind) accumulates one anchor per distinct taskId with no
+ * upper bound, defeating `MAX_AUDIT_LOG_BYTES`'s own size cap and turning
+ * every subsequent append into an ever-larger O(n) read + atomic-rewrite.
+ * Mirrors `daemon/observer.ts`'s `MAX_TRACKED_TASKS`/`task-runner.ts`'s
+ * `MAX_TRACKED_TASK_IDS` registries: bounded to a generously-sized "a
+ * handful of genuinely concurrent tasks never gets close to this" cap, kept
+ * the most RECENTLY-touched (by last-seen line index) and dropping the
+ * oldest overflow with a single `console.warn` per rotation (not one per
+ * dropped anchor — a runaway leak should be visible without spamming the
+ * log). A dropped task simply reverts to the pre-round-1 behavior (falls
+ * out of `tasks`/`status` once its own events age out of the retained
+ * tail) rather than the file growing without bound.
+ */
+export declare const MAX_LIVE_TASK_ANCHORS = 500;
+/**
+ * Appends one `DaemonEvent` as a single redacted JSON line (finding P1 #3 —
+ * see this file's module doc comment) at 0600, and rotates the file if it's
+ * grown past the size cap (finding P2/#11). Plain `fs.open('a')` +
+ * `appendFile` — sufficient for an append-only log (no torn-read risk the
+ * way a whole-file replace has; see `util/atomic-write.ts`'s own doc comment
+ * for why THAT helper exists for whole-file writes instead of just being
+ * used here too — rotation below is the one path in this file that DOES
+ * replace the whole file, and does use it).
+ */
+export declare function appendAuditEvent(storeDir: string, event: DaemonEvent): Promise<void>;
+/**
+ * Adapts {@link appendAuditEvent} into a `DaemonEventListener` for
+ * `daemon.subscribe()` (used by the `start` command). `DaemonEventListener`
+ * is synchronous — `observer.ts`'s `emit()` never awaits a listener (see its
+ * own doc comment on why, including the finding #6 async-safety fix) — so a
+ * naive fire-and-forget `appendAuditEvent(...).catch(...)` per call would
+ * have a real problem: the underlying `fs.open`/`appendFile` calls could
+ * complete OUT OF ORDER under load, silently corrupting the log's own event
+ * ordering. This chains each append onto the previous one (still
+ * async/non-blocking from the listener's point of view) so writes always
+ * land in emission order, and a failed write (reported via `onError`) never
+ * breaks the chain for subsequent events.
+ */
+export declare function createAuditAppender(storeDir: string, onError?: (err: unknown) => void): DaemonEventListener;
+/** Full historical read (oldest first) — `[]` if the log doesn't exist yet (e.g. `start` has never run). Used by `status`/`tasks` (no `--follow`). */
+export declare function readAuditEvents(storeDir: string): Promise<DaemonEvent[]>;
+export interface FollowOptions {
+    signal: AbortSignal;
+    /** How often to check the file for new bytes. Default 200ms — plenty responsive for a human tailing output, without busy-looping. */
+    pollIntervalMs?: number;
+    /**
+     * `true` (default): start at the file's CURRENT length — a `tail -f`,
+     * streaming only events appended from the moment `followAuditLog` was
+     * called. `false`: replay the full existing log first, then keep
+     * streaming — mainly useful for tests that want both in one pass.
+     */
+    fromEnd?: boolean;
+}
+/**
+ * Tails `filePath` (the audit log) for newly-appended `DaemonEvent` lines
+ * until `options.signal` aborts. No native filesystem-event watching (no
+ * `fs.watch` — inconsistent across platforms, especially the rename-based
+ * atomic writes this package uses elsewhere for OTHER files).
+ *
+ * Finding P2/#11 (audit half): the previous implementation re-read the
+ * ENTIRE file from byte 0 on every single poll, re-parsing every
+ * already-emitted line just to find the handful of new ones at the end —
+ * O(file size) work every `pollIntervalMs`, forever, for as long as
+ * `tasks --follow` stays attached. This tracks a byte OFFSET across polls
+ * instead: each poll opens the file and reads only the bytes appended since
+ * the last read (`FileHandle.read` at a specific position), advancing
+ * `offset` by exactly that many bytes — only genuinely new bytes are ever
+ * read or decoded.
+ *
+ * UTF-8 safety: the new bytes are split on the RAW BYTE `0x0a` ('\n')
+ * BEFORE any UTF-8 decoding happens, not on an already-decoded string —
+ * `0x0A` can only ever appear as an actual newline in valid UTF-8
+ * (continuation bytes are always `0x80`-`0xBF`), so this never risks
+ * decoding a torn multi-byte character that happened to straddle a chunk
+ * boundary. Bytes after the last `\n` in a chunk are held in `pending`
+ * (as a `Buffer`, still undecoded) until a future poll's bytes complete
+ * that line — mirrors `completeLines`'s existing "never guess at a torn
+ * trailing line" contract for `readAuditEvents`, just incremental.
+ *
+ * Rotation tolerance: if `appendAuditEvent`'s own size-cap rotation (or
+ * anything else) replaces the file out from under an in-progress follow,
+ * `offset` resets to 0 and `pending` is cleared — the follow session
+ * survives (rather than throwing or garbling) at the cost of re-emitting
+ * the post-rotation file's retained lines as if they were new.
+ *
+ * Finding P2 (new): that replacement is detected by file IDENTITY
+ * (`dev:ino`), not by comparing sizes. The previous implementation only
+ * reset `offset` when the new file was SMALLER than it (`st.size <
+ * offset`) — sufficient for the common case (a big pre-rotation file
+ * trimmed down to a small one), but `rotateIfNeeded`'s replace is an atomic
+ * temp-file + `fs.rename` (see `atomicWriteFile`), which swaps the
+ * underlying INODE regardless of whether the new file happens to be
+ * smaller OR LARGER than the reader's current offset. A `--follow` session
+ * that attached while the log was still tiny (a small `offset`) can have a
+ * rotation land a compacted-but-still-much-bigger-than-that-tiny-offset
+ * file in its place — the old size-only check missed exactly that case
+ * (`st.size < offset` was false), so it kept reading from the stale
+ * `offset` INTO THE NEW FILE's bytes: skipping that file's own prefix
+ * entirely and very likely starting mid-JSON-line. Tracking `dev:ino`
+ * across polls catches ANY replacement — smaller, larger, anything — and
+ * resets `offset` to 0 so the new file is always re-read from its own
+ * start. The size-based check is kept as a secondary fallback (a
+ * same-identity in-place truncate, or a platform where `ino` isn't a
+ * reliable identity signal).
+ */
+export declare function followAuditLog(filePath: string, onEvent: (event: DaemonEvent) => void, options: FollowOptions): Promise<void>;

package/dist/bin/byok-agent.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};