@byok-sdk/client 0.1.0

package/dist/daemon/control-protocol.d.ts

@@ -0,0 +1,299 @@
+import type { TaskState } from '@byok-sdk/protocol';
+import type { ApprovalDecision, PendingApproval } from './approvals';
+import type { StorageCategory } from './journal/journal';
+import type { StoragePressureState } from './journal/storage-policy';
+import type { OperationalHealthSnapshot } from './operational-health';
+/**
+ * M4 Phase 2: shared local-IPC contract between the daemon's control server
+ * (`control-server.ts`) and the CLI's control client (`bin/control-client.ts`)
+ * — frame shapes, endpoint path/pipe-name derivation, and the HMAC handshake
+ * math. Both sides import from here so the two can never independently drift
+ * (e.g. a mismatched HMAC label string, or a socket path computed two
+ * slightly different ways).
+ *
+ * Transport: NDJSON (one JSON object per line) over a Unix domain socket
+ * (darwin/linux) or a Windows named pipe — both addressed by the same
+ * path-like string via Node's `net` module, so neither `control-server.ts`
+ * nor `bin/control-client.ts` needs to special-case the transport itself,
+ * only the path/pipe-name derivation below.
+ */
+export declare const CONTROL_PROTOCOL_VERSION = 1;
+/** Handshake must complete within this long, on both sides — see each side's own timer. */
+export declare const HANDSHAKE_TIMEOUT_MS = 3000;
+/**
+ * The Unix domain socket path for a daemon rooted at `storeDir`. Prefers
+ * `<storeDir>/control.sock` (keeps every one of this daemon's local state
+ * files under one directory, which is already created+chmod'd 0700 by the
+ * time this matters — see `control-server.ts`'s `startControlServer`);
+ * falls back, whenever the natural path would risk exceeding {@link
+ * UNIX_SOCKET_PATH_SOFT_LIMIT}, to a short, deterministic path nested under
+ * a PER-DAEMON PRIVATE subdirectory of `os.tmpdir()` — derived from a hash
+ * of `storeDir` alone, so both the daemon and any CLI invocation pointed at
+ * the same `storeDir` independently compute the identical fallback path.
+ *
+ * Nested one level deep (rather than a bare `<hash>.sock` file directly in
+ * the shared, world-traversable `os.tmpdir()`) specifically so
+ * `control-server.ts`'s `bindControlEndpoint` can create+chmod that
+ * subdirectory 0700 BEFORE ever binding inside it — the directory's own
+ * mode gates traversal into it regardless of the socket file's own
+ * (briefly default-permissioned, until the post-bind `chmod`) mode, closing
+ * what would otherwise be a real window for another user on the same
+ * machine to reach a socket living directly in a shared tmpdir.
+ */
+export declare function controlSocketPath(storeDir: string): string;
+/**
+ * The Windows named pipe name for a daemon identified by `productId` +
+ * (`path.resolve`-normalized) `storeDir`. Named pipes have no filesystem
+ * path (no stale-file cleanup concern the way Unix sockets have — see
+ * `control-server.ts`), but DO share one flat namespace across the whole
+ * machine, so the name must be scoped to this exact daemon instance: two
+ * different products, or two different store directories (e.g. two agents
+ * of the same product — see `templates/service/README.md`'s "running
+ * multiple agents" section), must never collide. `storeDir` is resolved
+ * before hashing so a trivial path-form difference (trailing slash, etc.)
+ * between the two sides can't split the name.
+ *
+ * NOT keyed by the OS user: a WinSW-installed service runs the daemon under
+ * the Windows service account (e.g. `SYSTEM`) while the operator CLI runs
+ * as the interactive user, so both sides must derive the identical name
+ * from the same `storeDir` alone. Impostor servers are defeated by the
+ * mutual HMAC handshake below, not by pipe-name secrecy — keying by user
+ * was security theater that broke the service-account topology.
+ */
+export declare function controlPipeName(productId: string, storeDir: string): string;
+/**
+ * Dispatches to {@link controlPipeName} on `win32`, {@link controlSocketPath}
+ * everywhere else. `platform` defaults to `process.platform`; overridable
+ * for tests exercising a specific platform's branch on any host (mirrors
+ * `lifecycle/create-service-lifecycle.ts`'s identical `platform` override —
+ * the REAL win32 named-pipe semantics can only be proven on actual Windows,
+ * which CI's `ipc-smoke` job does; this override just makes the PATH-CHOICE
+ * logic itself testable everywhere).
+ */
+export declare function controlEndpointPath(productId: string, storeDir: string, platform?: NodeJS.Platform): string;
+/** Where the daemon writes its per-session control-auth token (see the handshake section below). Always a real file, even on Windows (pipes have no path of their own to piggyback secrets on). */
+export declare function controlTokenPath(storeDir: string): string;
+export declare function randomNonceHex(): string;
+/** What the server proves to the client: it holds `token`, bound to the client's own nonce so a captured proof can't be replayed against a different handshake. */
+export declare function computeServerProof(token: string, clientNonce: string): string;
+/** What the client proves to the server, symmetrically, bound to the server's nonce. */
+export declare function computeClientAuth(token: string, serverNonce: string): string;
+/** Constant-time hex-string comparison (`crypto.timingSafeEqual` requires equal-length buffers; a length mismatch is itself a safe, immediate "not equal" — no early-exit on content). */
+export declare function timingSafeEqualHex(a: string, b: string): boolean;
+export interface ClientHello {
+    v: 1;
+    hello: 'client';
+    nonce: string;
+}
+export interface ServerHello {
+    v: 1;
+    hello: 'server';
+    proof: string;
+    nonce: string;
+}
+export interface ClientAuth {
+    v: 1;
+    auth: string;
+}
+export interface ServerReady {
+    v: 1;
+    ready: true;
+}
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseClientHello(value: unknown): ClientHello | undefined;
+export declare function parseServerHello(value: unknown): ServerHello | undefined;
+export declare function parseClientAuth(value: unknown): ClientAuth | undefined;
+export declare function parseServerReady(value: unknown): ServerReady | undefined;
+export interface RawControlRequest {
+    /** Not narrowed to `1` here on purpose — an unexpected value is a `bad_version` RESPONSE, not a parse failure; see `control-server.ts`. */
+    v: unknown;
+    id: string;
+    method: string;
+    params?: unknown;
+}
+/** Loose shape check for an incoming request line: only `id`/`method` need to be well-formed for the server to be able to respond at all (including a `bad_version`/`unknown_method` response) — `v` is deliberately passed through unvalidated. */
+export declare function parseRawControlRequest(value: unknown): RawControlRequest | undefined;
+export interface ControlErrorShape {
+    code: string;
+    message: string;
+}
+export interface ControlResponseOk {
+    v: 1;
+    id: string;
+    ok: true;
+    result?: unknown;
+    /** Present (and `true`) only on the final frame of a streaming method — see `control-server.ts`'s dispatch. */
+    done?: true;
+}
+export interface ControlResponseErr {
+    v: 1;
+    id: string;
+    ok: false;
+    error: ControlErrorShape;
+}
+export type ControlResponse = ControlResponseOk | ControlResponseErr;
+export interface ControlEventFrame {
+    v: 1;
+    id: string;
+    event: unknown;
+}
+export declare function encodeFrame(frame: unknown): string;
+/** Thrown by a method handler to control the wire error `{code, message}` a caller sees — anything else thrown surfaces as a generic `internal_error`. See `control-server.ts`'s dispatch and `bin/control-client.ts`'s `request()` (which re-throws this same class on the client side). */
+export declare class ControlError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/**
+ * Bound on a single NDJSON line's byte length. Every real frame this
+ * protocol ever sends (handshake frames, requests/responses/events) is well
+ * under this — it exists purely as a defensive cap against a misbehaving or
+ * hostile peer streaming an unterminated line forever to grow `pending`
+ * without bound. Exceeding it is a fail-closed condition: {@link
+ * NdjsonLineReader.push} throws, and every caller (`control-server.ts`,
+ * `bin/control-client.ts`) destroys the connection on that throw.
+ */
+export declare const MAX_LINE_BYTES: number;
+/**
+ * Buffers raw socket bytes and yields complete lines. Splits on the raw byte
+ * `0x0a` BEFORE any UTF-8 decoding (mirrors `bin/audit-log.ts`'s
+ * `followAuditLog`) — `0x0A` can only ever appear as an actual newline in
+ * valid UTF-8, so this never risks decoding a multi-byte character that
+ * happened to straddle a chunk boundary.
+ */
+export declare class NdjsonLineReader {
+    private pending;
+    /** @throws if the still-unterminated remainder exceeds {@link MAX_LINE_BYTES} — see that constant's own doc comment. */
+    push(chunk: Buffer): string[];
+}
+export interface ControlActiveTask {
+    taskId: string;
+    state: TaskState;
+}
+/**
+ * M4 Phase 4 (part B.3, observability): a cheap per-active-task queue-depth
+ * watermark for the `status` result. The IDEAL metric here would be each
+ * runtime adapter's own event-queue depth (`util/async-queue.ts`'s
+ * `AsyncQueue`) — but that queue lives inside each adapter's concrete
+ * `Session` implementation, and `Session.events` (`types.ts`) is typed only
+ * as a plain `AsyncIterable<AgentEvent>`, which has no queryable backlog
+ * size; reaching it would mean adding a new method to the `Session`
+ * interface AND implementing it in all three bundled adapters
+ * (pi/claude/codex), which is out of scope for this pass. This instead
+ * reflects two things `TaskRunner` already cheaply knows about the SAME
+ * task without any new plumbing: how much progress is buffered locally
+ * (not yet flushed as a `task.progress` batch), and how many out-of-band
+ * approval requests are currently in flight for it. See
+ * `task-runner.ts`'s `getQueueWatermarks` for how each field is computed.
+ */
+export interface TaskQueueWatermark {
+    taskId: string;
+    /** Events buffered in this task's `ProgressBatcher`, not yet flushed as a `task.progress` batch. */
+    progressBatcherPending: number;
+    /** Approval requests currently in flight for this task: 1 if one is actively dispatched (registered + `task.await_approval` sent) plus however many more are queued behind it (M4 Phase 4 fold-in — see `TaskRunner.requestApproval`). */
+    pendingApprovals: number;
+}
+/**
+ * S3b (L-003): local storage usage and pressure, as the `status` method
+ * reports them (architecture §12.7.2.1).
+ *
+ * Named `storage*` throughout, NOT `watermark*`: {@link TaskQueueWatermark}
+ * above is a per-task progress-buffer depth and has nothing to do with disk.
+ * Two unrelated concepts sharing a name on one status result is how an
+ * operator reads the wrong number during an incident.
+ *
+ * Present only when a daemon actually runs a storage policy
+ * (`DaemonConfig.hostedJournal.storagePolicy`). Absent means "not measured",
+ * which is a different statement from "measured, and fine" — so it is an
+ * absent field rather than a zeroed one.
+ */
+export interface ControlStorageStatus {
+    /** §12.7.2.1's four states. `hard-pressure` declines new offers; `emergency` refuses to ack at all. */
+    pressureState: StoragePressureState;
+    /** `maxStoreBytes` — the budget `usedBytes` is measured against. */
+    budgetBytes: number;
+    /** Total across every category below, as of `measuredAt`. */
+    usedBytes: number;
+    /** Bytes available to this daemon on the store's filesystem — the free-space axis of the watermark, independent of the budget. */
+    freeBytes: number;
+    measuredAt: string;
+    /** The five §12.7.2.1 categories, always reported separately — a single total cannot drive a category-scoped cleanup order or a category-scoped never-delete list. */
+    categories: ControlStorageCategoryUsage[];
+    /** The most recent bounded WAL checkpoint + incremental vacuum, if one has run in this daemon's lifetime. */
+    lastCompaction?: ControlStorageCompaction;
+}
+export interface ControlStorageCategoryUsage {
+    category: StorageCategory;
+    bytes: number;
+    /** `true` when this is a host-reported or sampled figure rather than one measured off the filesystem. */
+    approximate: boolean;
+}
+export interface ControlStorageCompaction {
+    checkpointed: boolean;
+    walFramesRemaining: number;
+    pagesVacuumed: number;
+    durationMs: number;
+    at: string;
+}
+/** Result shape for the `status` method — see `create-daemon.ts`'s control-method wiring for how each field is sourced, and `bin/format.ts`'s `formatLiveStatusLines` for how the CLI renders it. */
+export interface ControlStatusResult {
+    pid: number;
+    uptimeMs: number;
+    paired: boolean;
+    deviceId?: string;
+    /** The connection state machine's own current value (`ws-transport.ts`'s `ConnectionState`) — e.g. `'open'`, `'degraded'` (long-poll fallback), `'revoked'`, `'closed'`, `'connecting'`. */
+    transport: string;
+    activeTasks: ControlActiveTask[];
+    runtimeIds: string[];
+    /** M4 Phase 4 (part B.3): per-active-task queue watermarks — see {@link TaskQueueWatermark}. */
+    queueWatermarks: TaskQueueWatermark[];
+    /**
+     * Finding F4 (cross-model adversarial review): the actual pending
+     * approvals currently dispatched — the SAME entries `approvals.list`
+     * returns (`ApprovalRegistry.list()`), surfaced here too so a single
+     * `status` call can show an operator every `approvalId` they'd need to
+     * `approve`/`reject`, without a second control-socket round trip. This is
+     * `approvalsPending`'s own source list (`approvalsPending ===
+     * approvals.length`, always).
+     */
+    approvals: PendingApproval[];
+    /** M4 Phase 4 (part B.3): total approvals currently DISPATCHED (registered) across the whole daemon — the same count `approvals.list` returns, surfaced here too for a one-call status view. */
+    approvalsPending: number;
+    /** S3b (L-003): local storage usage + pressure — see {@link ControlStorageStatus}. Absent unless a storage policy is configured. */
+    storage?: ControlStorageStatus;
+    /** Local lifecycle/retry budget. This is not the transport state above. */
+    operationalHealth: OperationalHealthSnapshot;
+}
+export interface ApprovalsListResult {
+    approvals: PendingApproval[];
+}
+export type { ApprovalDecision, PendingApproval } from './approvals';
+export interface ApprovalsResolveParams {
+    approvalId: string;
+    decision: ApprovalDecision;
+    reason?: string;
+}
+export declare function parseApprovalsResolveParams(value: unknown): ApprovalsResolveParams | undefined;
+/**
+ * M4 Phase 3: the control method `byok-approval-mcp` (`bin/byok-approval-mcp.ts`)
+ * calls FROM a claude-spawned MCP-server child process — a genuinely
+ * different OS process from the daemon, reachable only over this same
+ * control socket (see `../types.ts`'s `ApprovalChannel` doc comment for the
+ * full why). `taskId` correlates the request to an active task;
+ * `summary` is a short, human-readable description of the gated action
+ * (carried verbatim into the wire `task.await_approval.summary`).
+ */
+export interface ApprovalsRequestParams {
+    taskId: string;
+    summary: string;
+}
+export declare function parseApprovalsRequestParams(value: unknown): ApprovalsRequestParams | undefined;
+/** Result of `approvals.request` — the outcome `byok-approval-mcp` translates into its own MCP `allow`/`deny` answer. */
+export interface ApprovalsRequestResult {
+    approved: boolean;
+    reason?: string;
+}
+export type ShutdownReason = 'unpair' | 'operator';
+export interface ShutdownParams {
+    reason?: ShutdownReason;
+}
+export declare function parseShutdownParams(value: unknown): ShutdownParams;

package/dist/daemon/control-server.d.ts

@@ -0,0 +1,61 @@
+/**
+ * M4 Phase 2: the daemon-side local control socket — Unix domain socket
+ * (darwin/linux) or Windows named pipe, mutually authenticated by an
+ * HMAC handshake over a token that never crosses the wire (see
+ * `control-protocol.ts`), speaking a small NDJSON request/response(/event)
+ * RPC protocol. Transport-only and daemon-agnostic: `create-daemon.ts`
+ * supplies the actual method handlers (`status`, `tasks.subscribe`,
+ * `approvals.*`, `shutdown`) as a plain registry — this module knows
+ * nothing about `Daemon`/`TaskRunner` internals, which keeps it testable
+ * (and reusable) on its own.
+ */
+export declare class AnotherControlServerRunningError extends Error {
+    constructor(endpoint: string);
+}
+/** Default cap on simultaneous pre-handshake ("half-open") connections — see `startControlServer`'s own comment on why. */
+export declare const MAX_HALF_OPEN_CONNECTIONS = 8;
+export interface ControlMethodContext {
+    /** Emits one `event` frame for a streaming method's current request. */
+    emit: (event: unknown) => void;
+    /** Aborts once the client disconnects — a streaming handler must stop producing events and release whatever it subscribed to. */
+    signal: AbortSignal;
+}
+export type UnaryMethod = (params: unknown) => Promise<unknown> | unknown;
+export type StreamMethod = (params: unknown, ctx: ControlMethodContext) => Promise<void>;
+export interface ControlMethods {
+    unary: Record<string, UnaryMethod>;
+    stream: Record<string, StreamMethod>;
+}
+export interface ControlServerOptions {
+    storeDir: string;
+    productId: string;
+    methods: ControlMethods;
+    /** Test-only override — default `HANDSHAKE_TIMEOUT_MS` (3000ms). */
+    handshakeTimeoutMs?: number;
+    /** Test-only override — default `MAX_HALF_OPEN_CONNECTIONS` (8). */
+    maxHalfOpenConnections?: number;
+}
+export interface ControlServerHandle {
+    /** The bound Unix socket path or Windows pipe name. */
+    endpoint: string;
+    /** Stops accepting new connections, destroys every open one, and removes the socket/token files (a Windows pipe leaves no file to remove). Idempotent. */
+    close(): Promise<void>;
+}
+/**
+ * Binds the platform endpoint (Unix socket or Windows pipe — see
+ * `control-protocol.ts`) FIRST, and only once that succeeds generates and
+ * persists a fresh per-session token to `<storeDir>/control.token` (0600).
+ * This ordering matters: if a bind fails because ANOTHER daemon's control
+ * server already owns this endpoint (see
+ * {@link AnotherControlServerRunningError}), that other daemon's own token
+ * file must be left completely untouched — writing (and, on failure,
+ * deleting) a token before the bind attempt would corrupt or erase the
+ * still-running daemon's valid token out from under it.
+ *
+ * Throws {@link AnotherControlServerRunningError} if a live listener already
+ * owns this endpoint (fatal — the caller, `create-daemon.ts`, treats this as
+ * a hard startup failure); any OTHER bind failure propagates as a plain
+ * `Error` so the caller can decide to degrade instead (the control socket
+ * must never be allowed to brick the rest of the daemon).
+ */
+export declare function startControlServer(opts: ControlServerOptions): Promise<ControlServerHandle>;