@byok-sdk/client 0.5.0 → 0.6.1

package/dist/daemon/agent-content-read.d.ts

@@ -0,0 +1,169 @@
+import { AgentHomeLayout, type AgentRef } from '../agent-home';
+import { AgentContentAuditStore } from './agent-content-audit-store';
+export declare const AGENT_CONTENT_READ_SURFACES: readonly ['workspace', 'transcript', 'artifact'];
+export type AgentContentReadSurface = (typeof AGENT_CONTENT_READ_SURFACES)[number];
+/** Additive capability names. Each surface is independently admitted. */
+export declare const AGENT_CONTENT_READ_CAPABILITIES: Readonly<{
+    readonly workspace: "agent-content-workspace-read";
+    readonly transcript: "agent-content-transcript-read";
+    readonly artifact: "agent-content-artifact-read";
+}>;
+export declare const AGENT_CONTENT_READ_CAPABILITY_WORKSPACE: "agent-content-workspace-read";
+export declare const AGENT_CONTENT_READ_CAPABILITY_TRANSCRIPT: "agent-content-transcript-read";
+export declare const AGENT_CONTENT_READ_CAPABILITY_ARTIFACT: "agent-content-artifact-read";
+export declare const AGENT_CONTENT_READ_DECISIONS: readonly ['allow', 'deny'];
+export type AgentContentReadDecision = (typeof AGENT_CONTENT_READ_DECISIONS)[number];
+/**
+ * Reasons are stable policy observations, not user-facing prose. A denied
+ * read has exactly one reason and never returns any bytes.
+ */
+export declare const AGENT_CONTENT_READ_REASONS: readonly ['invalid-request', 'policy-disabled', 'capability-missing', 'policy-revision-mismatch', 'absolute-target', 'non-relative-target', 'dot-segment', 'sensitive-name', 'root-not-allowlisted', 'root-invalid', 'path-escape', 'target-missing', 'symlink', 'not-regular-file', 'byte-limit', 'mime-not-allowlisted', 'text-not-allowlisted', 'text-decode-failed', 'identity-mismatch'];
+export type AgentContentReadReason = (typeof AGENT_CONTENT_READ_REASONS)[number];
+export type AgentContentReadDropReason = AgentContentReadReason;
+export type AgentContentActorKind = 'user' | 'agent' | 'system';
+export interface AgentContentReadActor {
+    readonly kind: AgentContentActorKind;
+    readonly id: string;
+}
+/** Exact identity copied from the persisted Agent session handoff. */
+export interface AgentContentSessionIdentity {
+    readonly agentRef: AgentRef;
+    readonly sessionRef: string;
+    readonly runtimeId: string;
+    readonly cwd: string;
+}
+export type AgentContentReadRoot = {
+    readonly kind: 'agent-home';
+} | {
+    readonly kind: 'runtime-allowlisted';
+    readonly root: string;
+};
+/** The policy is one authority; no semantic defaults are inferred from a request. */
+export interface AgentContentReadPolicy {
+    readonly enabled: true;
+    readonly capability: string;
+    readonly root: AgentContentReadRoot;
+    readonly policyRevision: string;
+    /** Positive hard limit applied before allocating the file contents. */
+    readonly maxBytes: number;
+    /** Positive hard limit for an explicitly requested UTF-8 decode. */
+    readonly maxTextBytes: number;
+    /** Exact MIME strings. Wildcards are not accepted. */
+    readonly allowedMimeTypes: readonly string[];
+    /** Exact subset of allowedMimeTypes permitted with decodeAs=utf8. */
+    readonly textMimeTypes: readonly string[];
+    /** Product additions may tighten this list; SDK-reserved names cannot be removed. */
+    readonly sensitiveNames?: readonly string[];
+    /** Transcript reads must bind to this persisted identity, unless a resolver is supplied. */
+    readonly expectedTranscriptIdentity?: AgentContentSessionIdentity;
+}
+export type AgentContentReadPolicySelection = 'disabled' | AgentContentReadPolicy;
+export type ContentReadPolicy = AgentContentReadPolicy;
+export interface AgentContentReadRequest {
+    readonly requestId: string;
+    readonly actor: AgentContentReadActor;
+    readonly tenantId: string;
+    readonly deviceId: string;
+    readonly agentRef: AgentRef;
+    readonly surface: AgentContentReadSurface;
+    /** Portable, slash-separated relative target. */
+    readonly relativeTarget: string;
+    /** Caller-declared MIME. No extension or content inference is performed. */
+    readonly mimeType: string;
+    readonly capability: string;
+    readonly policyRevision: string;
+    /** Optional narrower request bound; it can never widen policy.maxBytes. */
+    readonly maxBytes?: number;
+    /** Optional narrower request MIME declaration; it can never widen policy allowlist. */
+    readonly allowedMimeTypes?: readonly string[];
+    /** Omit for bytes; utf8 is explicit and bounded by maxTextBytes. */
+    readonly decodeAs?: 'bytes' | 'utf8';
+    /** Required for transcript; optional for workspace/artifact projections. */
+    readonly session?: AgentContentSessionIdentity;
+}
+export interface AgentContentAuditReceipt {
+    readonly version: 1;
+    readonly requestId: string;
+    readonly actor: AgentContentReadActor;
+    readonly tenantId: string;
+    readonly deviceId: string;
+    readonly agentRef: AgentRef;
+    readonly surface: AgentContentReadSurface;
+    readonly session?: AgentContentSessionIdentity;
+    /** Canonical relative target only; no absolute pathname is ever recorded. */
+    readonly relativeTarget: string;
+    readonly policyRevision: string;
+    readonly byteCount: number;
+    readonly contentHash?: string;
+    readonly decision: AgentContentReadDecision;
+    readonly reason?: AgentContentReadReason;
+    readonly recordedAt: string;
+}
+export interface AgentContentReadAllowed {
+    readonly decision: 'allow';
+    readonly surface: AgentContentReadSurface;
+    readonly relativeTarget: string;
+    readonly mimeType: string;
+    readonly byteCount: number;
+    readonly contentHash: string;
+    readonly content: Uint8Array;
+    readonly text?: string;
+    readonly receipt: AgentContentAuditReceipt;
+}
+export interface AgentContentReadDenied {
+    readonly decision: 'deny';
+    readonly surface: AgentContentReadSurface;
+    readonly relativeTarget: string;
+    readonly reason: AgentContentReadReason;
+    readonly receipt: AgentContentAuditReceipt;
+}
+export type AgentContentReadResult = AgentContentReadAllowed | AgentContentReadDenied;
+export type AgentContentReadDecisionRecord = AgentContentReadResult;
+export declare class AgentContentReadPolicyError extends Error {
+    constructor(message: string);
+}
+export declare class AgentContentReadRequestError extends Error {
+    constructor(message: string);
+}
+export declare class AgentContentReadAuditError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+export interface AgentContentReadPolicyEngineOptions {
+    readonly agentHomeLayout?: AgentHomeLayout;
+    readonly policies: Readonly<Record<AgentContentReadSurface, AgentContentReadPolicySelection>>;
+    readonly capabilities: Iterable<string>;
+    readonly runtimeAllowlistedRoots?: readonly string[];
+    readonly auditStore: AgentContentAuditStore;
+    /** Optional all-surface session gate for hosts that require a live handoff before every read. */
+    readonly resolveSessionIdentity?: (request: AgentContentReadRequest) => Promise<AgentContentSessionIdentity | undefined> | AgentContentSessionIdentity | undefined;
+    /** Binds transcript claims to AgentSessionHandoffStore-backed exact identity. */
+    readonly resolveTranscriptIdentity?: (request: AgentContentReadRequest) => Promise<AgentContentSessionIdentity | undefined> | AgentContentSessionIdentity | undefined;
+}
+export declare const SDK_RESERVED_CONTENT_NAMES: readonly string[];
+export declare function createAgentContentReadPolicy(input: AgentContentReadPolicy): AgentContentReadPolicy;
+/**
+ * Independent local content-read policy engine. It reads one explicitly
+ * requested file at a time; it never walks, mirrors, indexes, or parses an
+ * Agent home or runtime directory.
+ */
+export declare class AgentContentReadPolicyEngine {
+    private readonly options;
+    private readonly policies;
+    private readonly capabilities;
+    private readonly runtimeRoots;
+    private readonly runtimeRootCache;
+    private readonly resolveSessionIdentity?;
+    private readonly resolveTranscriptIdentity?;
+    constructor(options: AgentContentReadPolicyEngineOptions);
+    read(input: AgentContentReadRequest): Promise<AgentContentReadResult>;
+    /** Alias used by integration adapters that call the operation request. */
+    readContent(request: AgentContentReadRequest): Promise<AgentContentReadResult>;
+    /** A request is one bounded read, never a directory listing or recursive mirror. */
+    request(request: AgentContentReadRequest): Promise<AgentContentReadResult>;
+    private resolveRoot;
+    private validateRuntimeRoot;
+    private checkSessionIdentity;
+    private checkTranscriptIdentity;
+    private deny;
+    private appendReceipt;
+}

package/dist/daemon/agent-egress-controller.d.ts

@@ -0,0 +1,76 @@
+import type { AgentEvent } from '@byok-sdk/protocol';
+import type { AgentRef } from '../agent-home';
+import { type AgentEgressDropReason, type AgentEgressDropReceipt, type AgentEgressPolicy, type AgentEgressStatus } from './agent-egress-policy';
+import { type AgentReliableAck, type AgentContentReceiptWithoutReliableIdentity, type AgentReliableEgressRecord } from './agent-egress-spool';
+import { type AgentEgressSanitizer } from './agent-egress-sanitizer';
+export interface AgentEgressControllerOptions {
+    readonly policy: Readonly<AgentEgressPolicy>;
+    /** Authenticated tenant identity, never accepted from an egress event. */
+    readonly tenantId?: string;
+    readonly sanitizer?: AgentEgressSanitizer;
+}
+export interface AgentEgressProgressInput {
+    readonly agentRef?: AgentRef;
+    readonly taskId: string;
+    readonly events: readonly AgentEvent[];
+    readonly serverCapabilities: readonly string[];
+}
+export interface AgentEgressReliableInput {
+    readonly homeDir: string;
+    readonly agentRef: AgentRef;
+    readonly payload: unknown;
+    readonly sessionRef: string;
+    readonly taskId?: string;
+    readonly eventId?: string;
+}
+export interface AgentEgressContentReceiptInput {
+    readonly homeDir: string;
+    readonly agentRef: AgentRef;
+    /** The content-free payload before the spool supplies stable event/cursor identity. */
+    readonly payload: AgentContentReceiptWithoutReliableIdentity;
+    readonly taskId?: string;
+}
+export type AgentEgressReliableAppendResult = Readonly<{
+    ok: true;
+    record: AgentReliableEgressRecord;
+}> | Readonly<{
+    ok: false;
+    reason: AgentEgressDropReason;
+}>;
+/**
+ * The one daemon-owned policy consumer. Reliable and latest-value retain
+ * distinct types and stores; retries are sends, and only exact acknowledgments
+ * retire durable records.
+ */
+export declare class AgentEgressController {
+    private readonly options;
+    private readonly latest;
+    private readonly spools;
+    private readonly latestStatus;
+    private readonly reliableStatus;
+    private readonly drops;
+    constructor(options: AgentEgressControllerOptions);
+    get policy(): Readonly<AgentEgressPolicy>;
+    status(): AgentEgressStatus;
+    dropReceipts(): readonly AgentEgressDropReceipt[];
+    noteTransportDrop(reason: AgentEgressDropReason, agentRef?: AgentRef): void;
+    /** Project before TaskRunner builds a `task.progress` envelope. */
+    projectLatestValue(input: AgentEgressProgressInput): readonly AgentEvent[];
+    appendReliable(input: AgentEgressReliableInput): Promise<AgentEgressReliableAppendResult>;
+    /**
+     * Content decisions are reliable facts too. They never enter the generic
+     * egress payload authority: the spool persists their exact protocol payload
+     * with `wireType: agent.content.receipt` before any transport attempt.
+     */
+    appendContentReceipt(input: AgentEgressContentReceiptInput): Promise<AgentEgressReliableAppendResult>;
+    /** Retires only the record whose full Agent/tenant/revision/id/cursor tuple matches. */
+    acknowledge(ack: AgentReliableAck): Promise<boolean>;
+    /** Re-open every existing Agent-local spool before retrying stable records after restart. */
+    recover(agentsRoot: string): Promise<void>;
+    reliableRecords(): readonly AgentReliableEgressRecord[];
+    /** Missing ack capability holds records in their reliable lane; it never makes them lossy. */
+    retryableReliableRecords(serverCapabilities: readonly string[]): readonly AgentReliableEgressRecord[];
+    private spoolFor;
+    private tenantPendingBytes;
+    private noteDrop;
+}

package/dist/daemon/agent-egress-policy.d.ts

@@ -0,0 +1,36 @@
+import { type AgentEgressDropReason, type AgentEgressPolicy, type AgentEvent } from '@byok-sdk/protocol';
+export type { AgentEgressDropReason, AgentEgressPolicy } from '@byok-sdk/protocol';
+export interface AgentEgressDropReceipt {
+    lane: 'latest-value' | 'reliable';
+    reason: AgentEgressDropReason;
+    agentId?: string;
+    tenantId?: string;
+    eventId?: string;
+    occurredAt: string;
+}
+export interface AgentEgressLaneStatus {
+    pendingEvents: number;
+    pendingBytes: number;
+    replaced: number;
+    dropped: number;
+    lastDropReason?: AgentEgressDropReason;
+}
+export interface AgentEgressStatus {
+    policyRevision: string;
+    latestValue: AgentEgressLaneStatus;
+    reliable: AgentEgressLaneStatus;
+}
+/** Safe policy selected only when the host has not opted into content. */
+export declare const DEFAULT_AGENT_EGRESS_POLICY: Readonly<AgentEgressPolicy>;
+export declare class AgentEgressPolicyError extends Error {
+    constructor(message: string);
+}
+/** Resolve/validate once at construction; unknown policy shapes never become an implicit default. */
+export declare function resolveAgentEgressPolicy(policy: AgentEgressPolicy | undefined): Readonly<AgentEgressPolicy>;
+/**
+ * Default activity projection. Every retained string is SDK-authored; no
+ * runtime trajectory, tool, prompt, environment, argv, path, or credential
+ * value survives this transformation.
+ */
+export declare function metadataStatusEvent(event: AgentEvent): AgentEvent;
+export declare function eventBytes(event: AgentEvent): number;

package/dist/daemon/agent-egress-sanitizer.d.ts

@@ -0,0 +1,38 @@
+import { type Envelope } from '@byok-sdk/protocol';
+import { type AgentEgressDropReason, type AgentEgressPolicy } from './agent-egress-policy';
+export interface AgentEgressSanitizerContext {
+    readonly lane: 'latest-value' | 'reliable';
+    readonly policyRevision: string;
+    readonly envelopeType?: string;
+    readonly agentId?: string;
+    readonly tenantId?: string;
+}
+/**
+ * Optional named host redaction hook for an explicitly contentful policy.
+ * It receives the SDK-projected value, never a second raw wire
+ * representation. Throwing/refusing drops the event; callers never receive
+ * an original-payload fallback.
+ */
+export type AgentEgressSanitizer = (value: unknown, context: AgentEgressSanitizerContext) => unknown;
+export declare class AgentEgressSanitizationError extends Error {
+    readonly reason: AgentEgressDropReason;
+    constructor(message: string, reason?: AgentEgressDropReason);
+}
+export type SanitizedEnvelope = Readonly<{
+    ok: true;
+    envelope: Envelope;
+}> | Readonly<{
+    ok: false;
+    reason: AgentEgressDropReason;
+}>;
+/**
+ * The one envelope-boundary sanitizer used before either transport sees an
+ * envelope. It parses the final value through the frozen protocol so a
+ * broken custom sanitizer also fails locally, before WS bytes or long-poll
+ * JSON can be created.
+ */
+export declare function sanitizeEgressEnvelope(envelope: Envelope, policy: Readonly<AgentEgressPolicy>, sanitizer: AgentEgressSanitizer | undefined, context?: Omit<AgentEgressSanitizerContext, 'lane' | 'policyRevision' | 'envelopeType'> & {
+    lane?: 'latest-value' | 'reliable';
+}): SanitizedEnvelope;
+/** Sanitizes a reliable payload before it is hashed/appended, never after. */
+export declare function sanitizeReliablePayload(payload: unknown, policy: Readonly<AgentEgressPolicy>, sanitizer: AgentEgressSanitizer | undefined, context?: Omit<AgentEgressSanitizerContext, 'lane' | 'policyRevision'>): unknown;

package/dist/daemon/agent-egress-spool.d.ts

@@ -0,0 +1,116 @@
+import { type AgentContentReceiptPayload } from '@byok-sdk/protocol';
+import type { AgentRef } from '../agent-home';
+import { type AgentEgressPolicy, type AgentEgressDropReason } from './agent-egress-policy';
+export declare const AGENT_EGRESS_DIRECTORY: string;
+export declare const AGENT_RELIABLE_SPOOL_FILENAME = "reliable-v1.jsonl";
+/** A spool row's intended envelope type, never inferred from its payload. */
+export declare const AGENT_RELIABLE_WIRE_TYPES: readonly ['agent.egress.reliable', 'agent.content.receipt'];
+export type AgentReliableWireType = (typeof AGENT_RELIABLE_WIRE_TYPES)[number];
+type OmitReliableIdentity<T> = T extends unknown ? Omit<T, 'eventId' | 'cursor'> : never;
+export type AgentContentReceiptWithoutReliableIdentity = OmitReliableIdentity<AgentContentReceiptPayload>;
+export interface AgentReliableEgressRecord {
+    readonly schema: 1;
+    readonly wireType: AgentReliableWireType;
+    readonly agentRef: AgentRef;
+    readonly tenantId: string;
+    readonly policyRevision: string;
+    readonly eventId: string;
+    readonly cursor: number;
+    readonly payload: unknown;
+    readonly payloadHash: string;
+    readonly byteCount: number;
+    readonly createdAt: string;
+    readonly sessionRef?: string;
+    readonly taskId?: string;
+}
+export interface AgentReliableAppendInput {
+    readonly agentRef: AgentRef;
+    readonly tenantId: string;
+    readonly policyRevision: string;
+    readonly payload: unknown;
+    readonly sessionRef?: string;
+    readonly taskId?: string;
+    readonly eventId?: string;
+    readonly createdAt?: string;
+}
+/**
+ * Content receipts use the existing durable spool but retain their own wire
+ * type and validated receipt payload. The request id is the stable event id:
+ * a retried local read cannot mint a competing receipt identity.
+ */
+export interface AgentContentReceiptAppendInput {
+    readonly agentRef: AgentRef;
+    readonly tenantId: string;
+    readonly policyRevision: string;
+    readonly sessionRef: string;
+    readonly payload: AgentContentReceiptWithoutReliableIdentity;
+    readonly taskId?: string;
+}
+export interface AgentReliableAck {
+    readonly agentRef: AgentRef;
+    readonly tenantId: string;
+    readonly sessionRef: string;
+    readonly policyRevision: string;
+    readonly eventId: string;
+    readonly cursor: number;
+}
+export declare class AgentReliableSpoolError extends Error {
+    constructor(message: string);
+}
+export declare class AgentReliableQuotaError extends AgentReliableSpoolError {
+    readonly reason: Extract<AgentEgressDropReason, 'quota_exceeded' | 'backpressure'>;
+    constructor(reason: Extract<AgentEgressDropReason, 'quota_exceeded' | 'backpressure'>, message: string);
+}
+/**
+ * Per-Agent durable append-before-send log. It is deliberately separate from
+ * the inbound task journal: its only truth is outbound reliable egress
+ * pending/exact-ack state.
+ */
+export declare class AgentReliableSpool {
+    readonly homeDir: string;
+    readonly spoolPath: string;
+    private readonly pending;
+    private nextCursor;
+    private logEntries;
+    private writeTail;
+    private constructor();
+    static open(homeDir: string): Promise<AgentReliableSpool>;
+    get pendingEvents(): number;
+    get pendingBytes(): number;
+    records(): readonly AgentReliableEgressRecord[];
+    append(input: AgentReliableAppendInput, policy: Readonly<AgentEgressPolicy>, tenantPendingBytes: number): Promise<AgentReliableEgressRecord>;
+    /**
+     * Append one complete, protocol-validated content receipt before its first
+     * send. `eventId` is fixed to `requestId`; the durable spool alone allocates
+     * the positive cursor, then validates the final payload before fsync.
+     */
+    appendContentReceipt(input: AgentContentReceiptAppendInput, policy: Readonly<AgentEgressPolicy>, tenantPendingBytes: number): Promise<AgentReliableEgressRecord>;
+    /** Exact matching ack is the only transition which retires a record. */
+    acknowledge(ack: AgentReliableAck): Promise<boolean>;
+    private load;
+    private appendEntry;
+    private compact;
+    private exclusive;
+}
+export interface LatestValueRecord {
+    readonly agentRef: AgentRef;
+    readonly tenantId: string;
+    readonly event: import('@byok-sdk/protocol').AgentEvent;
+    readonly byteCount: number;
+    readonly updatedAt: string;
+}
+/** In-memory latest-value state; it is never replayed as durable history. */
+export declare class AgentLatestValueState {
+    private readonly recordsByAgent;
+    offer(record: Omit<LatestValueRecord, 'byteCount' | 'updatedAt'>, policy: Readonly<AgentEgressPolicy>): Readonly<{
+        accepted: true;
+        replaced: boolean;
+        record: LatestValueRecord;
+    }> | Readonly<{
+        accepted: false;
+        reason: Extract<AgentEgressDropReason, 'quota_exceeded' | 'backpressure'>;
+    }>;
+    get pendingEvents(): number;
+    get pendingBytes(): number;
+}
+export {};

package/dist/daemon/agent-session-handoff-store.d.ts

@@ -0,0 +1,82 @@
+import { type AgentRef } from '../agent-home';
+export type AgentTerminalCause = 'complete' | 'failed' | 'cancelled';
+export interface AgentSessionHandoff {
+    readonly agentRef: AgentRef;
+    /** Task that created the native runtime session. */
+    readonly taskId: string;
+    readonly sessionRef: string;
+    readonly runtimeId: string;
+    /** Canonical Agent home and runtime cwd; these are intentionally one value. */
+    readonly cwd: string;
+    readonly leaseId: string;
+    readonly terminalCause?: AgentTerminalCause;
+    readonly terminalReason?: string;
+    readonly updatedAt: string;
+}
+export interface AgentSessionHandoffMatch {
+    readonly agentRef: AgentRef;
+    readonly sessionRef: string;
+    readonly runtimeId: string;
+    readonly cwd: string;
+}
+export interface AgentTaskTerminalEvidence {
+    readonly agentRef: AgentRef;
+    readonly taskId: string;
+    readonly runtimeId: string;
+    /** Canonical Agent home and sealed runtime cwd. */
+    readonly cwd: string;
+    readonly leaseId: string;
+    /** Present when adapter start succeeded but handoff persistence failed. */
+    readonly sessionRef?: string;
+    readonly terminalCause: 'failed';
+    readonly terminalReason: string;
+    readonly updatedAt: string;
+}
+export interface AgentTaskTerminalMatch {
+    readonly agentRef: AgentRef;
+    readonly taskId: string;
+    readonly runtimeId: string;
+    readonly cwd: string;
+}
+export declare class AgentSessionHandoffStoreError extends Error {
+    constructor(message: string);
+}
+export declare class AgentSessionHandoffCorruptError extends AgentSessionHandoffStoreError {
+    constructor(message: string);
+}
+export declare class AgentSessionHandoffMismatchError extends AgentSessionHandoffStoreError {
+    constructor(message: string);
+}
+/**
+ * Durable, fail-closed session evidence stored inside the canonical Agent
+ * home. Each session gets one hash-addressed append-only JSONL ledger under
+ * `.byok/runtime-sessions/`; session text never becomes a pathname. Unlike
+ * the legacy SessionWorkspaceStore, corrupt bytes are never interpreted as a
+ * missing mapping.
+ */
+export declare class AgentSessionHandoffStore {
+    private readonly queues;
+    get(expected: AgentSessionHandoffMatch): Promise<AgentSessionHandoff | undefined>;
+    /** Append-only readback for audit/recovery; every historical terminal remains visible. */
+    history(expected: AgentSessionHandoffMatch): Promise<readonly AgentSessionHandoff[]>;
+    /** Exact identity check used before a strict Agent resume is admitted. */
+    requireMatch(expected: AgentSessionHandoffMatch): Promise<AgentSessionHandoff>;
+    /** Append-only, fsynced write. The caller awaits this before task.started. */
+    record(input: Omit<AgentSessionHandoff, 'updatedAt' | 'terminalCause' | 'terminalReason'>): Promise<AgentSessionHandoff>;
+    /** Records the first terminal cause without changing the exact handoff identity. */
+    recordTerminal(expected: AgentSessionHandoffMatch, cause: AgentTerminalCause, reason?: string): Promise<AgentSessionHandoff>;
+    /**
+     * Persists a claimed Agent task failure that happened before an active
+     * session handoff existed. Callers await the fsync before sending
+     * `task.fail`, so cloud state can never outrun the Agent-local evidence.
+     */
+    recordTaskTerminal(input: Omit<AgentTaskTerminalEvidence, 'updatedAt' | 'terminalCause'>): Promise<AgentTaskTerminalEvidence>;
+    getTaskTerminal(expectedInput: AgentTaskTerminalMatch): Promise<AgentTaskTerminalEvidence | undefined>;
+    private filePath;
+    private taskTerminalFilePath;
+    private enqueue;
+    private load;
+    private loadAll;
+    private loadTaskTerminal;
+    private append;
+}

package/dist/daemon/blob-client.d.ts

@@ -3,7 +3,9 @@ import type { AuthManager } from './auth-manager';
 /** Seam `TaskRunner` depends on, so tests can substitute a fake without spinning up real HTTP endpoints. */
 export interface BlobResolver {
     resolveInstruction(blobRef: BlobRef): Promise<string>;
-    uploadArtifact(content: string | Uint8Array, contentType: string): Promise<BlobRef>;
+    uploadArtifact(content: string | Uint8Array, contentType: string, options?: {
+        readonly idempotencyKey?: string;
+    }): Promise<BlobRef>;
 }
 /**
  * HTTP-side blob transfer (protocol §7): resolving an instruction `blobRef`
@@ -18,5 +20,7 @@ export declare class BlobClient implements BlobResolver {
     /** `blobRef` -> `GET /byok/blobs/:id/url` -> fetch the presigned download URL -> text content. Always resolves fresh rather than trusting any inlined `BlobRef.url`, per docs/protocol.md §7. */
     resolveInstruction(blobRef: BlobRef): Promise<string>;
     /** `POST /byok/blobs` (declares size/contentType/contentHash) -> PUT the bytes to the presigned upload URL -> a `BlobRef` for `task.artifact.blobRef`. */
-    uploadArtifact(content: string | Uint8Array, contentType: string): Promise<BlobRef>;
+    uploadArtifact(content: string | Uint8Array, contentType: string, options?: {
+        readonly idempotencyKey?: string;
+    }): Promise<BlobRef>;
 }

package/dist/daemon/connection-manager.d.ts

@@ -9,9 +9,11 @@ export interface ConnectionManagerOptions {
     deviceId: string;
     productId: string;
     capabilities: CapabilityFlag[];
+    /** U4a Local Agent release version; passed unchanged to both transports. */
+    clientVersion?: string;
     runtimes: RuntimeInfo[];
-    /** Sorted logical IDs from the validated local registry; executable definitions stay local. */
-    configuredToolsets?: readonly ToolsetId[];
+    /** Reads current sorted logical IDs from the validated local registry for every WS hello. */
+    getConfiguredToolsets?: () => readonly ToolsetId[];
     auth: AuthManager;
     cursorStore: CursorStore;
     /**

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

@@ -3,6 +3,8 @@ 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';
+import type { LocalAgentReleaseIdentity } from '../release-identity';
+import type { McpToolsetConfig, McpToolsetRegistryStatus } from '../types';
 /**
  * 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`)
@@ -244,6 +246,8 @@ export interface ControlStorageCompaction {
 }
 /** 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 {
+    /** Process-immutable Local Agent application release; absent only for an older control peer. */
+    localAgentRelease?: Readonly<LocalAgentReleaseIdentity>;
     pid: number;
     uptimeMs: number;
     paired: boolean;
@@ -270,7 +274,15 @@ export interface ControlStatusResult {
     storage?: ControlStorageStatus;
     /** Local lifecycle/retry budget. This is not the transport state above. */
     operationalHealth: OperationalHealthSnapshot;
+    /** Redacted content-addressed status from the daemon's single local registry. */
+    toolsets: McpToolsetRegistryStatus;
 }
+export interface ToolsetsReloadParams {
+    expectedRevision: string;
+    mcpToolsets: Record<string, McpToolsetConfig>;
+}
+/** Shape-only parser; executable definition validation remains registry-owned. */
+export declare function parseToolsetsReloadParams(value: unknown): ToolsetsReloadParams | undefined;
 export interface ApprovalsListResult {
     approvals: PendingApproval[];
 }