@mirasoth/soothe-client 0.2.1 → 0.4.1

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { EventEmitter } from 'node:events';
 
 /**
- * Custom error types for the Soothe client (RFC-450 protocol-1).
+ * Custom error types for the Soothe client.
  */
 /** Represents a WebSocket connection failure. */
 declare class ConnectionError extends Error {
@@ -11,13 +11,13 @@ declare class ConnectionError extends Error {
     constructor(url: string, attempt: number, cause: Error);
 }
 /**
- * Represents an error reported by the Soothe daemon (RFC-450 §7).
+ * Represents an error reported by the Soothe daemon.
  *
  * The daemon's structured error object carries a numeric `code` from the
  * reserved ranges, a human-readable `message`, and optional `data`.
  */
 declare class DaemonError extends Error {
-    /** Numeric error code from the RFC-450 §7.3 registry. */
+    /** Numeric error code from the daemon error registry. */
     readonly code: number;
     /** The daemon's error message text. */
     readonly daemonMessage: string;
@@ -32,7 +32,7 @@ declare class TimeoutError extends Error {
     constructor(operation: string, duration: string);
 }
 /**
- * Distinguishes clean vs unclean connection loss (RFC-450 §4, §8.3).
+ * Distinguishes clean vs unclean connection loss.
  *
  * A clean drop follows a `disconnect` notification (loops keep running
  * server-side); an unclean drop is a read/write error or a missed pong
@@ -40,9 +40,9 @@ declare class TimeoutError extends Error {
  * event: the cause is emitted exactly once when the connection drops.
  */
 declare enum DisconnectCause {
-    /** Abrupt loss: read/write error or missed pong (RFC-450 §8.3). */
+    /** Abrupt loss: read/write error or missed pong. */
     Unclean = 0,
-    /** Graceful peer-initiated `disconnect` notification (RFC-450 §9.2). */
+    /** Graceful peer-initiated `disconnect` notification. */
     Clean = 1
 }
 /** Human-readable cause name for logging. */
@@ -155,22 +155,22 @@ declare const DEFAULT_DELIVERABLE_PHASES: ReadonlySet<string>;
 
 /**
  * Protocol-1 wire envelope: message types, encode/decode, NDJSON splitting,
- * and factory functions for the Soothe daemon (RFC-450).
+ * and factory functions for the Soothe daemon.
  *
  * The unified `{proto, type, method, params, id}` envelope combines
  * JSON-RPC 2.0's `method`/`params`/`id` structure with graphql-ws's `type`
  * semantics for message class distinction.
  */
 
-/** Protocol version string (RFC-450 §8.1). */
+/** Protocol version string. */
 declare const PROTO_VERSION = "1";
 /** Default client capabilities declared in the connection_init handshake. */
 declare const DEFAULT_CLIENT_CAPABILITIES: string[];
 /** Client version reported in the connection_init handshake. */
-declare const CLIENT_VERSION = "0.1.0";
+declare const CLIENT_VERSION = "0.4.1";
 type MessageType = "connection_init" | "connection_ack" | "request" | "response" | "notification" | "subscribe" | "next" | "error" | "complete" | "unsubscribe" | "ping" | "pong" | "receipt_response" | "disconnect" | "status";
-/** Method names carried in the envelope `method` field (RFC-450 §9.2). */
-type MethodName = "loop_list" | "loop_get" | "loop_tree" | "loop_prune" | "loop_delete" | "loop_new" | "loop_reattach" | "loop_detach" | "loop_input" | "loop_messages" | "loop_state_get" | "loop_state_update" | "loop_cards_fetch" | "loop_history_fetch" | "loop_events" | "autopilot_events" | "job_create" | "job_status" | "job_pause" | "job_resume" | "job_cancel" | "job_dag" | "job_guidance" | "daemon_status" | "daemon_shutdown" | "config_get" | "config_reload" | "skills_list" | "invoke_skill" | "models_list" | "mcp_status" | "auth" | "auth_refresh" | "slash_command" | "rpc_command" | "delivery_ack" | "cron_add" | "cron_list" | "cron_show" | "cron_cancel" | "disconnect";
+/** Method names carried in the envelope `method` field. */
+type MethodName = "loop_list" | "loop_get" | "loop_tree" | "loop_prune" | "loop_delete" | "loop_new" | "loop_reattach" | "loop_detach" | "loop_input" | "loop_messages" | "loop_state_get" | "loop_state_update" | "loop_cards_fetch" | "loop_history_fetch" | "loop_events" | "autopilot_events" | "job_create" | "job_status" | "job_pause" | "job_resume" | "job_cancel" | "job_dag" | "job_guidance" | "autopilot_status" | "autopilot_submit" | "autopilot_list_goals" | "autopilot_get_goal" | "autopilot_cancel_goal" | "autopilot_cancel_all" | "autopilot_wake" | "autopilot_dream" | "autopilot_resume" | "autopilot_list_jobs" | "autopilot_get_job" | "daemon_status" | "daemon_shutdown" | "config_get" | "config_reload" | "skills_list" | "invoke_skill" | "models_list" | "mcp_status" | "auth" | "auth_refresh" | "slash_command" | "rpc_command" | "delivery_ack" | "cron_add" | "cron_list" | "cron_show" | "cron_cancel" | "disconnect";
 /** Base fields shared by every protocol-1 message. */
 interface BaseEnvelope {
     proto: string;
@@ -194,7 +194,7 @@ interface NotificationEnvelope extends BaseEnvelope {
     type: "notification";
     method: MethodName;
     params?: Record<string, unknown>;
-    /** Optional receipt id for delivery confirmation (RFC-450 §5.7). */
+    /** Optional receipt id for delivery confirmation. */
     receipt?: string;
 }
 /** Start a subscription stream (events arrive as `next`). */
@@ -276,9 +276,9 @@ interface DisconnectEnvelope extends BaseEnvelope {
     type: "disconnect";
 }
 /**
- * A daemon status frame. `status` is a defined protocol-1 top-level type
- * (RFC-450 §9.1): it passes through the daemon's legacy→`next` translator
- * unchanged, so it is NOT wrapped in a `next` envelope.
+ * A daemon status frame. `status` is a defined protocol-1 top-level type:
+ * it passes through the daemon's legacy→`next` translator unchanged, so it
+ * is NOT wrapped in a `next` envelope.
  */
 interface StatusFrame extends BaseEnvelope {
     type: "status";
@@ -370,7 +370,7 @@ declare function splitWirePayload(data: string): string[];
  * both shapes.
  */
 declare function extractSootheLoopID(msg: unknown): [string, boolean];
-/** Generates a new UUID correlation ID (RFC-450 §5.2 `id`). */
+/** Generates a new UUID correlation ID. */
 declare function newRequestID(): string;
 /** Creates a `loop_input` notification envelope. */
 declare function newLoopInputMessage(loopID: string, content: string): NotificationEnvelope;
@@ -438,7 +438,7 @@ declare function isCompletionEvent(eventType: string): boolean;
 declare function isSubagentProgressEvent(eventType: string): boolean;
 
 /**
- * Client manages a WebSocket session with the Soothe daemon (RFC-450 protocol-1).
+ * Client manages a WebSocket session with the Soothe daemon.
  *
  * After close(), a new Client must be created to reconnect. The connection
  * begins with a bidirectional connection_init/connection_ack handshake; no
@@ -479,6 +479,9 @@ declare class Client extends EventEmitter {
     private config;
     private ws;
     private messageBuffer;
+    private inboundMaxSize;
+    private inboundDroppedCount;
+    private onStreamDegraded;
     private resolvers;
     private handshakeComplete;
     private negotiatedCapabilities;
@@ -489,6 +492,8 @@ declare class Client extends EventEmitter {
     private lastPongMonotonic;
     private disconnFired;
     private mux;
+    private deliveryRecvSeq;
+    private deliveryAckedSeq;
     constructor(url: string, config?: Config);
     /**
      * Dials the Soothe daemon WebSocket and completes the protocol-1 handshake
@@ -519,8 +524,8 @@ declare class Client extends EventEmitter {
      */
     private _signalDisconnect;
     /**
-     * Re-dials the daemon and re-handshakes after a connection drop (RFC-450
-     * §8.3). Does not re-establish loop subscriptions; follow with
+     * Re-dials the daemon and re-handshakes after a connection drop.
+     * Does not re-establish loop subscriptions; follow with
      * `reattachAndProbe()` to resume a loop session. The caller should invoke
      * this after the `'disconnected'` event fires. Reuses the same Client,
      * resetting the drop signal and multiplexer.
@@ -535,7 +540,7 @@ declare class Client extends EventEmitter {
      * Returns a `StaleLoopError` when the probe fails; callers should fall back
      * to a fresh `loop_new` bootstrap.
      *
-     * Per RFC-629: connection-level readiness is the handshake's readiness_state
+     * Note: connection-level readiness is the handshake's readiness_state
      * (+ daemon_status); loop_get is a loop-scoped probe only, not a readiness
      * probe.
      */
@@ -556,6 +561,21 @@ declare class Client extends EventEmitter {
     readEvent(): Promise<Record<string, unknown> | null>;
     /** Reads a single event with a timeout. Returns null on timeout or close. */
     readEventWithTimeout(timeout: number): Promise<Record<string, unknown> | null>;
+    /**
+     * Remove stale handshake/terminal frames left in `messageBuffer` before a turn.
+     * Returns labels of removed frames (in order).
+     */
+    peelStalePendingControlEvents(): string[];
+    /** True when the underlying socket is still open (may not be handshaked). */
+    isConnectionAlive(): boolean;
+    /** Override pending buffer cap (tests / tuning). */
+    setInboundMaxSize(n: number): void;
+    /** How many NORMAL-priority frames were dropped under backpressure. */
+    inboundDropped(): number;
+    /** Hook invoked on the first inbound overflow drop. */
+    setStreamDegradedCallback(fn: ((dropped: number, reason: string) => void) | null): void;
+    private enqueueMessageBuffer;
+    private noteInboundDrop;
     /**
      * Reads the next frame directly from the live socket (via a resolver),
      * bypassing `messageBuffer`. Used by RPC waits so that stream events
@@ -567,9 +587,9 @@ declare class Client extends EventEmitter {
     private readLiveEventWithTimeout;
     /**
      * Sends a `request` envelope and waits for the matching `response` (or
-     * `error`) correlated by `id` (RFC-450 §5/§9). Returns the `result` object.
+   * `error`) correlated by `id`. Returns the `result` object.
      *
-     * Multiplexer-aware (RFC-629 constraint #1): registers a pending RPC wait
+   * Multiplexer-aware: registers a pending RPC wait
      * keyed by the request id so that, even when a `receiveMessages()` reader
      * is concurrently active, the matching `response`/`error` is routed to
      * this caller instead of being discarded or buffered behind a stream.
@@ -593,6 +613,8 @@ declare class Client extends EventEmitter {
     private _requestResponseForEnvelope;
     /** Sends a fire-and-forget `notification` envelope (no response expected). */
     notify(method: MethodName, params: Record<string, unknown>): Promise<void>;
+    private _trackInboundDeliveryAck;
+    private _sendDeliveryAck;
     /**
      * Starts a subscription stream. Returns the subscription `id` for later
      * correlation and `unsubscribe()`. Stream events arrive as `next` frames
@@ -647,7 +669,7 @@ declare class Client extends EventEmitter {
     sendLoopStateUpdate(loopID: string, values: Record<string, unknown>, asNode?: string): Promise<void>;
     /** Requests display card ledger snapshot. */
     sendLoopCardsFetch(loopID: string): Promise<void>;
-    /** Requests the full loop history (RFC-631). */
+    /** Requests the full loop history. */
     sendLoopHistoryFetch(loopID: string): Promise<void>;
     /** Requests MCP server status. */
     sendMCPStatus(): Promise<void>;
@@ -689,6 +711,32 @@ declare class Client extends EventEmitter {
     getJobDag(jobId: string, timeout?: number): Promise<Record<string, unknown>>;
     /** Sends guidance to a job or specific goal. */
     sendJobGuidance(jobId: string, text: string, goalId?: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Return autopilot scheduler status (running / dreaming / pool). */
+    autopilotStatus(timeout?: number): Promise<Record<string, unknown>>;
+    /** Submit a new autopilot goal (returns goal_id). */
+    autopilotSubmit(description: string, opts?: {
+        priority?: number;
+        workspace?: string;
+        timeout?: number;
+    }): Promise<Record<string, unknown>>;
+    /** List all goals (including non-root children). */
+    autopilotListGoals(timeout?: number): Promise<Record<string, unknown>>;
+    /** Fetch one goal by id. */
+    autopilotGetGoal(goalId: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Cancel a goal and its non-terminal descendants. */
+    autopilotCancelGoal(goalId: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** Cancel every open (non-terminal) goal. */
+    autopilotCancelAll(timeout?: number): Promise<Record<string, unknown>>;
+    /** Exit dreaming mode and resume scheduling. */
+    autopilotWake(timeout?: number): Promise<Record<string, unknown>>;
+    /** Force dreaming mode. */
+    autopilotDream(timeout?: number): Promise<Record<string, unknown>>;
+    /** Resume a suspended or blocked goal. */
+    autopilotResume(goalId: string, timeout?: number): Promise<Record<string, unknown>>;
+    /** List root goals only (jobs). Prefer createJob / getJobStatus for job control. */
+    autopilotListJobs(timeout?: number): Promise<Record<string, unknown>>;
+    /** Get a root job with DAG snapshot. Prefer getJobStatus / getJobDag. */
+    autopilotGetJob(jobId: string, timeout?: number): Promise<Record<string, unknown>>;
     /** Subscribes to autopilot worker events. */
     autopilotSubscribe(timeout?: number): Promise<string>;
     /** Unsubscribes from autopilot worker events. */
@@ -710,86 +758,55 @@ declare class Client extends EventEmitter {
 }
 
 /**
- * Inbound-frame multiplexer for the protocol-1 client (RFC-629 constraint #1,
- * RFC-450 §5.2/§5.5).
- *
- * Routes inbound protocol-1 frames to the correct waiter by `(type, id)`
- * instead of discarding non-matching events. This makes the Client safe for
- * concurrent RPCs and lets an active subscription stream coexist with RPC
- * waits without starvation.
- *
- * Routing rules:
- *   - `response`/`error` with `id` in pending RPCs   → pending RPC waiter
- *   - `next`/`complete` with `id` in pending subs     → pending subscription waiter
- *   - `receipt_response` with `receipt` in receipts   → receipt waiter
- *   - everything else                                  → not consumed (flows to
- *                                                          the application event
- *                                                          stream / resolver queue)
- *
- * `ping`/`pong`/`connection_ack` are id-less lifecycle frames handled by the
- * Client before reaching the multiplexer; the multiplexer leaves them
- * un-consumed so the Client's existing handlers still see them.
- *
- * A frame routed to a waiter is consumed (returns `true`) and must NOT be
- * forwarded to the resolver queue / event stream.
- */
-/**
- * Multiplexer holds pending RPC, subscription, and receipt waiters keyed by
- * their correlation id. The Client consults `route()` for each inbound frame
- * before pushing it to the resolver queue.
+ * Ephemeral one-shot RPC client for jobs / cron / autopilot.
+ * Mirrors Python AsyncCommandClient / CommandClient.
  */
-declare class Multiplexer {
-    private rpcs;
-    private subs;
-    private receipts;
-    /**
-     * Installs a pending RPC wait keyed by `id`. Returns the pending call and an
-     * unregister function that MUST be called when the wait ends (success,
-     * timeout, or cancel) to avoid leaks. If a late response arrives after the
-     * caller has unregistered, it is dropped (log-and-drop) — no leak.
-     */
-    registerRPC(id: string): {
-        call: Promise<Record<string, unknown>>;
-        unregister: () => void;
-    };
-    /**
-     * Installs a pending subscription stream keyed by `id`. Returns the stream
-     * channel (an async-iterable-like push sink), a `done` signal, and an
-     * unregister function. The Client pushes `next`/`complete` frames via
-     * `push`; the application reads from the channel.
-     */
-    registerSubscription(id: string): {
-        push: (frame: Record<string, unknown>) => void;
-        done: Promise<void>;
-        unregister: () => void;
-    };
-    /**
-     * Installs a pending receipt wait keyed by `receipt`. Returns an unregister
-     * function.
-     */
-    registerReceipt(receipt: string): {
-        wait: Promise<Record<string, unknown>>;
-        unregister: () => void;
-    };
-    /**
-     * Wires a real sink for a registered subscription's `push`. Called by the
-     * Client right after `registerSubscription` to install the channel/queue the
-     * application reads from.
-     */
-    setSubscriptionSink(id: string, sink: (frame: Record<string, unknown>) => void): void;
-    /**
-     * Inspects one decoded frame, delivers it to a matching waiter if one
-     * exists, and returns `true` (consumed). Returns `false` for frames with no
-     * matching waiter — these flow on to the resolver queue / event stream.
-     * Safe to call from the message handler.
-     */
-    route(frame: Record<string, unknown>): boolean;
-    /** Reports whether an RPC waiter is registered for `id`. */
-    hasRPCWaiter(id: string): boolean;
+
+declare class CommandClient {
+    readonly url: string;
+    readonly timeoutMs: number;
+    private readonly config;
+    constructor(url: string, opts?: {
+        timeoutMs?: number;
+        config?: Config;
+    });
+    private withClient;
+    /** Generic one-shot RPC. */
+    request(method: MethodName, params?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    jobCreate(goal: string, workspace?: string): Promise<Record<string, unknown>>;
+    jobStatus(jobId: string): Promise<Record<string, unknown>>;
+    jobCancel(jobId: string): Promise<Record<string, unknown>>;
+    /** Return autopilot scheduler status (running / dreaming / pool). */
+    autopilotStatus(): Promise<Record<string, unknown>>;
+    /** Submit a new autopilot goal (returns goal_id). */
+    autopilotSubmit(description: string, opts?: {
+        priority?: number;
+        workspace?: string;
+    }): Promise<Record<string, unknown>>;
+    /** List all goals (including non-root children). */
+    autopilotListGoals(): Promise<Record<string, unknown>>;
+    /** Fetch one goal by id. */
+    autopilotGetGoal(goalId: string): Promise<Record<string, unknown>>;
+    /** Cancel a goal and its non-terminal descendants. */
+    autopilotCancelGoal(goalId: string): Promise<Record<string, unknown>>;
+    /** Cancel every open (non-terminal) goal. */
+    autopilotCancelAll(): Promise<Record<string, unknown>>;
+    /** Exit dreaming mode and resume scheduling. */
+    autopilotWake(): Promise<Record<string, unknown>>;
+    /** Force dreaming mode. */
+    autopilotDream(): Promise<Record<string, unknown>>;
+    /** Resume a suspended or blocked goal. */
+    autopilotResume(goalId: string): Promise<Record<string, unknown>>;
+    /** List root goals only (jobs). Prefer job* for job control. */
+    autopilotListJobs(): Promise<Record<string, unknown>>;
+    /** Get a root job with DAG snapshot. Prefer jobStatus / getJobDag. */
+    autopilotGetJob(jobId: string): Promise<Record<string, unknown>>;
+    cronAdd(text: string, priority?: number): Promise<Record<string, unknown>>;
+    cronList(status?: string): Promise<Record<string, unknown>>;
 }
 
 /**
- * Convenience RPC helper functions for the Soothe client (RFC-450 protocol-1).
+ * Convenience RPC helper functions for the Soothe client.
  */
 
 /** Checks daemon status via RPC. */
@@ -804,12 +821,33 @@ declare function fetchSkillsCatalog(client: Client, timeout?: number): Promise<R
 declare function fetchConfigSection(client: Client, section: string, timeout?: number): Promise<Record<string, unknown>>;
 /** Requests daemon config reload via RPC. */
 declare function requestDaemonConfigReload(client: Client, timeout?: number): Promise<Record<string, unknown>>;
-/** Requests loop history (RFC-631) and waits for the response. */
+/** Requests loop history and waits for the response. */
 declare function fetchLoopHistory(client: Client, loopID: string, timeout?: number): Promise<Record<string, unknown>>;
 /** Submits credentials for daemon-side authentication and waits for the response. */
 declare function authenticate(client: Client, accessKey: string, secretKey: string, timeout?: number): Promise<Record<string, unknown>>;
 /** Refreshes the daemon-side auth token and waits for the response. */
 declare function refreshAuthToken(client: Client, refreshToken: string, timeout?: number): Promise<Record<string, unknown>>;
+/** Fetch bound display-card snapshot for a loop. */
+declare function fetchLoopCards(client: Client, loopID: string, timeout?: number): Promise<Record<string, unknown>>;
+/** Fetch persisted conversation/activity rows for a loop. */
+declare function fetchLoopMessages(client: Client, loopID: string, opts?: {
+    limit?: number;
+    offset?: number;
+    includeEvents?: boolean;
+    timeout?: number;
+}): Promise<Record<string, unknown>>;
+/**
+ * Connect, handshake, and yield a ready Client. Always closes in finally.
+ */
+declare function connectedWebsocket<T>(wsUrl: string, fn: (client: Client) => Promise<T>, timeoutMs?: number): Promise<T>;
+/**
+ * One-shot protocol-1 RPC / notify / subscribe with dict-style error contract.
+ * Callers check `if ("error" in response)`.
+ */
+declare function protocol1Rpc(wsUrl: string, method: string, params?: Record<string, unknown> | null, opts?: {
+    mode?: "request" | "notify" | "subscribe";
+    timeoutMs?: number;
+}): Promise<Record<string, unknown>>;
 
 /**
  * loop_new (or reuse id) → subscribe(loop_events); returns the loop id.
@@ -829,7 +867,26 @@ declare function waitSubscriptionConfirmed(client: Client, wantLoopID: string, _
 declare function connectWithRetries(client: Client, maxRetries?: number, retryDelay?: number): Promise<void>;
 
 /**
- * Persistence seam for appkit (RFC-629 Layer 1).
+ * Shared stream/turn terminal frame helpers for Client and DaemonSession.
+ *
+ * Keeps peel-at-turn-start and turn-end detection on one vocabulary so leftover
+ * prior-goal terminals cannot blank the next query.
+ */
+/** Daemon turn-scoped stream end custom type. */
+declare const STREAM_END = "soothe.stream.end";
+/** True when `data` is a turn-scoped terminal custom payload. */
+declare function isTurnEndCustomData(data: unknown): data is Record<string, unknown>;
+/**
+ * True when a chunk proves the active turn has non-intake progress.
+ * Used so late prior-goal stream.end cannot close a turn that has only seen
+ * intake lifecycle (e.g. plan.phase).
+ */
+declare function isTurnProgressChunk(mode: string, data: unknown): boolean;
+/** True when the client should bump delivery_ack sequence for this frame. */
+declare function inboundNeedsDeliveryAck(event: Record<string, unknown>): boolean;
+
+/**
+ * Persistence seam for appkit.
  *
  * SessionStore abstracts per-application storage: the session↔loop-id mapping
  * that ConnectionPool consults to decide bootstrap vs reattach, and the
@@ -890,7 +947,7 @@ interface SessionStore {
 }
 
 /**
- * SSE-style pub/sub fan-out for appkit (RFC-629 Layer 1).
+ * SSE-style pub/sub fan-out for appkit.
  *
  * Generic, string-keyed pub/sub for SSE-style event delivery. The
  * application-agnostic successor to a domain-keyed broadcaster: applications
@@ -938,7 +995,7 @@ declare class SSEBroadcaster {
 }
 
 /**
- * Thinking-step extraction for appkit (RFC-629 Layer 1).
+ * Thinking-step extraction for appkit.
  *
  * Maps an allowlisted progress event to one structured UI line. Free-form
  * streams (tokens, reports, reasoning) are excluded. Ported from the Go
@@ -954,18 +1011,17 @@ declare const DEFAULT_THINKING_STEP_EVENTS: ReadonlySet<string>;
 declare function extractThinkingStep(eventType: string, data: Record<string, unknown> | null, allow?: ReadonlySet<string>): [string, boolean];
 
 /**
- * Event classifier for appkit (RFC-629 Layer 1).
+ * Event classifier for appkit.
  *
  * Maps a stream of decoded daemon events into deliverable/streaming/terminal
- * outcomes, keyed on (namespace, mode, phase) per RFC-614/RFC-403
- * (RFC-629 constraint #4). The app-agnostic successor to triarch's
- * ProcessChatEvent, with the deliverable phase set promoted from hardcoded
- * constants to configuration.
+ * outcomes, keyed on (namespace, mode, phase). The app-agnostic successor to
+ * product-specific ProcessChatEvent helpers, with the deliverable phase set
+ * promoted from hardcoded constants to configuration.
  *
  * Event shape: a protocol-1 `next` envelope carries
  * `{type:"next", payload:{namespace, mode, data, loop_id}}`. The daemon
  * wraps legacy free-form frames as `{payload:{namespace, mode:<orig type>,
- * data:<orig frame>}}` (RFC-450 §9.3). The classifier inspects the payload's
+ * data:<orig frame>}}`. The classifier inspects the payload's
  * `mode`/`data`/`namespace` and the inner message's `phase`/`type`/`content`.
  */
 
@@ -1004,12 +1060,19 @@ interface ClassifierConfig {
     minDeliverableRunes?: number;
     /** Optional app override of the default thinking-step event allowlist. */
     thinkingStepEvents?: ReadonlySet<string>;
+    /**
+     * When true, a status frame with state=idle and non-empty accumulated
+     * assistant text is DeliverableComplete (typical for direct-model turns).
+     * Default false keeps Continue-on-status behaviour.
+     */
+    treatStatusIdleAsComplete?: boolean;
 }
 /** Maps a stream of decoded daemon events into deliverable/streaming/terminal outcomes. */
 declare class EventClassifier {
     private deliverablePhases;
     private minDeliverableRunes;
     private thinkingStepEvents?;
+    private treatStatusIdleAsComplete;
     constructor(cfg: ClassifierConfig);
     /**
      * Inspects one decoded event and returns its outcome. `accumulated` is the
@@ -1056,7 +1119,7 @@ declare class EventClassifier {
 }
 
 /**
- * Single-flight query gate for appkit (RFC-629 Layer 1).
+ * Single-flight query gate for appkit.
  *
  * Enforces single-flight query execution per session id and the
  * cancel-before-context ordering: when a query is cancelled, the daemon is
@@ -1104,7 +1167,7 @@ declare class QueryGate {
 
 /**
  * ManagedClient — the subset of the core Client that appkit's ConnectionPool
- * and TurnRunner depend on (RFC-629 Layer 1).
+ * and TurnRunner depend on.
  *
  * The concrete `Client` satisfies it; tests supply a fake. Defining it as an
  * interface lets appkit be unit-tested without a live WebSocket daemon.
@@ -1142,19 +1205,15 @@ interface ManagedClient {
  * (e.g. wrapping Client with logging/metrics).
  */
 type ClientFactory = (url: string, config?: Config) => ManagedClient;
-/** Returns a ClientFactory that builds a core Client. */
-declare function defaultClientFactory(): ClientFactory;
 /**
  * Creates a new loop (loop_new + subscribe) on a connected client and returns
  * the new loop id. The default implementation calls bootstrapLoopSession;
  * apps may override it.
  */
 type BootstrapFunc = (client: ManagedClient, workspaceID: string, userID: string, config?: Config) => Promise<string>;
-/** Default bootstrap: loop_new + subscribe(loop_events). */
-declare function defaultBootstrapFunc(): BootstrapFunc;
 
 /**
- * Per-session connection pool for appkit (RFC-629 Layer 1).
+ * Per-session connection pool for appkit.
  *
  * Manages a pool of daemon connections, one active per session. Reuses an
  * active connection when still live, otherwise bootstraps a fresh loop
@@ -1178,7 +1237,8 @@ interface PoolConfig {
     maxIdleTime: number;
     healthCheckInterval: number;
 }
-/** Returns env-overridable defaults (mirrors triarch). */
+/** Returns env-overridable defaults (mirrors triarch).
+ * `maxIdleTime` is enforced on acquire; `healthCheckInterval` is reserved. */
 declare function defaultPoolConfig(): PoolConfig;
 /** One connection slot in the pool. */
 declare class PooledConn {
@@ -1247,23 +1307,76 @@ declare class ConnectionPool {
 }
 
 /**
- * Turn runner for appkit (RFC-629 Layer 1).
+ * Attachment image compaction for appkit.
+ *
+ * When `sharp` is installed (optionalDependency), oversized image/* payloads
+ * are downscaled. Without sharp, attachments pass through unchanged.
+ */
+interface CompactImageOptions {
+    /** Max width or height in pixels. Default 768. */
+    maxDim?: number;
+    /** JPEG encode quality 1–100. Default 85. */
+    jpegQuality?: number;
+}
+/**
+ * Downscales image/* payloads when either dimension exceeds MaxDim.
+ * Non-images and decode failures pass through unchanged.
+ * PNG stays PNG; other image types re-encode as JPEG when sharp is available.
+ */
+declare function compactImageAttachment(mimeType: string, dataB64: string, opts?: CompactImageOptions | null): Promise<[string, string]>;
+/**
+ * Applies compactImageAttachment to each attachment map with mime_type + data.
+ */
+declare function compactAttachments(atts: Record<string, unknown>[], opts?: CompactImageOptions | null): Promise<Record<string, unknown>[]>;
+
+/**
+ * Turn runner for appkit.
  *
  * Executes one query turn end-to-end: acquire a pooled connection, enforce
  * single-flight, send loop_input, consume the event stream, classify events,
  * resolve the deliverable, persist the reply, and broadcast completion.
  *
- * The app-agnostic successor to triarch's ExecuteQuery.
+ * Supports lifecycle knobs: idle timeout, soft-complete
+ * policies, attachment compaction, and stream-close soft-complete.
  */
 
-/** Returned when a turn exceeds the configured timeout. */
+/** Returned when a turn exceeds the configured timeout and policy is Fail. */
 declare class ErrQueryTimeout extends Error {
     constructor();
 }
+/** Returned when no events arrive within IdleTimeout and policy is Fail. */
+declare class ErrIdleTimeout extends Error {
+    constructor();
+}
+/** Selects fail vs soft-complete behaviour for idle, query, and stream-close. */
+declare enum TimeoutPolicy {
+    Fail = 0,
+    SoftComplete = 1
+}
+type StreamClosePolicy = TimeoutPolicy;
+declare const StreamCloseFail = TimeoutPolicy.Fail;
+declare const StreamCloseSoftComplete = TimeoutPolicy.SoftComplete;
 /** Configures a TurnRunner. */
 interface TurnConfig {
     /** Per-turn deadline in ms. Defaults to 30m. */
     queryTimeout: number;
+    /** Max silence between classified events in ms. Zero disables (default). */
+    idleTimeout?: number;
+    /**
+     * When > 0, raises idleTimeout for turns with attachments if idleTimeout
+     * is positive but below this floor.
+     */
+    minIdleTimeoutWithAttachments?: number;
+    /** Fail vs soft-complete when the idle watchdog fires. Default Fail. */
+    onIdleTimeout?: TimeoutPolicy;
+    /** Fail vs soft-complete when queryTimeout fires. Default Fail. */
+    onQueryTimeout?: TimeoutPolicy;
+    /** Fail vs soft-complete when the event stream closes. Default Fail. */
+    onStreamClose?: StreamClosePolicy;
+    /** Run compactAttachments before buildInput. Default false. */
+    compactAttachmentsBeforeSend?: boolean;
+    /** Overrides for compactAttachmentsBeforeSend. */
+    compactImageOpts?: CompactImageOptions | null;
 }
 /** Carries optional daemon hints on a loop_input payload. */
 interface InputOpts {
@@ -1273,13 +1386,15 @@ interface InputOpts {
     responseSchemaName?: string;
     responseSchemaStrict?: boolean;
 }
-/** Optional attachment shape (IG-327: {mime_type, data(base64)}). */
+/** Optional attachment shape ({mime_type, data(base64)}). */
 type Attachment = Record<string, unknown>;
 /**
  * Builds a loop_input payload with optional attachments. Apps build this from
  * their product modes (e.g. triarch's ask/agent/deep-research).
  */
 declare function inputMessageForLoop(text: string, loopID: string, attachments?: Attachment[], opts?: InputOpts): Record<string, unknown>;
+/** Effective idle timeout for a turn (attachment floor applied). */
+declare function idleTimeoutForTurn(cfg: TurnConfig, hasAttachments: boolean): number;
 /** Completion hook signature. */
 type OnComplete = (sessionID: string, loopID: string, content: string, completionEvent: string, elapsedMs: number) => void;
 /** Error hook signature. */
@@ -1297,25 +1412,13 @@ declare class TurnRunner {
     private buildInput;
     private onComplete;
     private onError;
-    /**
-     * Constructs a TurnRunner. pool, gate, classifier, and store are required;
-     * broadcaster may be null.
-     */
     constructor(pool: ConnectionPool, gate: QueryGate, classifier: EventClassifier, store: SessionStore, broadcaster: SSEBroadcaster | null, cfg: TurnConfig);
-    /** Overrides the loop_input payload builder. */
     withInputBuilder(f: typeof inputMessageForLoop): TurnRunner;
-    /** Sets a completion hook (runs inline on success). */
     withOnComplete(f: OnComplete): TurnRunner;
-    /** Sets an error hook (runs inline on failure). */
     withOnError(f: OnError): TurnRunner;
-    /**
-     * Runs one query turn. The response is broadcast via the SSE broadcaster and
-     * persisted via the SessionStore; it is not returned to the caller (SSE
-     * subscribers receive it). Resolves on success; rejects on failure
-     * (ErrQueryTimeout, AbortError, or a daemon/processing error).
-     */
     execute(sessionID: string, message: string, userID: string, workspaceID: string, attachments: Attachment[] | null, opts: InputOpts | null, signal?: AbortSignal): Promise<void>;
-    /** Asks the daemon to cooperatively stop the loop runner on a detached signal. */
+    private finishTimeout;
+    private completeTurn;
     private sendLoopCancel;
     private persistResponse;
     private persistFailed;
@@ -1324,4 +1427,120 @@ declare class TurnRunner {
     private broadcastError;
 }
 
-export { type Attachment, type BaseEnvelope, type BootstrapFunc, CLIENT_VERSION, type ChatEventResult, ChatEventTerminal, type ClassifierConfig, Client, type ClientFactory, type CompleteEnvelope, type Config, type ConnectionAckEnvelope, ConnectionError, type ConnectionInitEnvelope, ConnectionPool, DEFAULT_CLIENT_CAPABILITIES, DEFAULT_DELIVERABLE_PHASES, DEFAULT_THINKING_STEP_EVENTS, DaemonError, type DecodedMessage, DisconnectCause, type DisconnectEnvelope, ErrPoolExhausted, ErrQueryBusy, ErrQueryTimeout, type ErrorEnvelope, EventAutopilotGoalCompleted, EventAutopilotGoalCreated, EventAutopilotGoalProgress, EventAutopilotGoalStatus, EventAutopilotWorkerAssigned, EventAutopilotWorkerUnassigned, EventCardCreated, EventCardReplayBegin, EventCardReplayEnd, EventClassifier, EventExploreCompleted, EventExploreMilestone, EventExploreStarted, EventExploreStepCompleted, EventFinalReport, EventGeneralFailed, EventLoopReattachedWire, EventMessageReceived, EventMessageSent, EventPlanCreated, EventReplayComplete, EventStrangeLoopCompleted, EventStrangeLoopContextCompacted, EventStrangeLoopPlanDecision, EventStrangeLoopReasoned, EventStrangeLoopStarted, EventStrangeLoopStepCompleted, EventStrangeLoopStepQueued, EventStrangeLoopStepStarted, EventStreamToolCallUpdate, EventTacitusCompleted, EventTacitusGatherSummary, EventTacitusStarted, EventToolCallUpdatesBatch, EventToolCompleted, EventToolError, EventToolStarted, INTENT_HINT_EMBED, INTENT_HINT_IMAGE_TO_TEXT, INTENT_HINT_OCR, INTENT_HINT_TEXT_COMPLETION, type InputOptions, type InputOpts, type IntentHint, LOOP_ASSISTANT_OUTPUT_PHASES, type LoopAssistantOutputPhase, type LoopInputIntentHint, type LoopInputParams, type LoopNewOptions, type ManagedClient, type MessageType, type MethodName, Multiplexer, type NegotiatedCapabilities, type NextEnvelope, type NotificationEnvelope, type OnComplete, type OnError, PROTO_VERSION, type PingEnvelope, type PongEnvelope, type PoolConfig, PooledConn, QueryGate, REMOVED_INTENT_HINTS, type ReceiptResponseEnvelope, ReconnectError, type RemovedIntentHint, type RequestEnvelope, type ResponseEnvelope, SSEBroadcaster, type SSEEvent, type SessionEntry, type SessionMessage, type SessionStore, StaleLoopError, type StatusFrame, type StreamEventPayload, type SubscribeEnvelope, TimeoutError, type TurnConfig, TurnRunner, type UnsubscribeEnvelope, type VerbosityLevel, VerbosityTier, authenticate, bootstrapLoopSession, checkDaemonStatus, classifyEventVerbosity, connectWithRetries, connectionInitEnvelope, decodeMessage, defaultBootstrapFunc, defaultClientFactory, defaultConfig, defaultPoolConfig, disconnectCauseName, disconnectEnvelope, encodeMessage, extractSootheLoopID, extractThinkingStep, fetchConfigSection, fetchLoopHistory, fetchSkillsCatalog, inputMessageForLoop, isCompletionEvent, isDaemonLive, isSubagentProgressEvent, isValidVerbosityLevel, loadConfigFromEnv, newLoopInputMessage, newLoopNewMessage, newLoopSubscribeMessage, newRequestID, notificationEnvelope, parseNamespace, pingEnvelope, pongEnvelope, refreshAuthToken, requestDaemonConfigReload, requestDaemonShutdown, requestEnvelope, shouldShow, splitWirePayload, subscribeEnvelope, unsubscribeEnvelope, validateLoopInputIntentHint, waitDaemonReady, waitLoopStatusWithID, waitSubscriptionConfirmed };
+/**
+ * Per-turn observability counters for daemon stream consumption.
+ */
+declare class TurnEventStats {
+    total: number;
+    messages: number;
+    updates: number;
+    custom: number;
+    skipped: number;
+    filteredEarly: number;
+    toolCalls: number;
+    toolResults: number;
+    textChunks: number;
+    heartbeatsDropped: number;
+    postIdleDrained: number;
+    inboundDropped: number;
+}
+
+/**
+ * Dual-socket daemon loop session with turn streaming (Python DaemonSession parity).
+ *
+ * Owns a subscribed stream WebSocket plus an RPC sidecar so metadata calls do not
+ * starve loop events. `iterTurnChunks` handles idle timeout, post-idle drain,
+ * loop scoping, and connection-loss detection.
+ */
+
+declare const DEFAULT_POST_IDLE_DRAIN_MS = 500;
+type EarlyDropFn = (namespace: unknown[], mode: string, data: unknown) => boolean;
+type StatsFactory = () => TurnEventStats;
+type StreamDeliveryResolver = () => string;
+interface DaemonSessionOptions {
+    workspace?: string | null;
+    streamDelivery?: string | StreamDeliveryResolver;
+    postIdleDrainDeadlineMs?: number;
+    earlyDropFn?: EarlyDropFn | null;
+    statsFactory?: StatsFactory | null;
+    config?: Config;
+}
+type TurnChunk = [namespace: unknown[], mode: string, data: unknown];
+/** Daemon-backed loop session with stream + RPC sockets. */
+declare class DaemonSession {
+    private wsUrl;
+    private workspace;
+    private streamDelivery;
+    private client;
+    private rpcClient;
+    private loopId;
+    private readBusy;
+    private rpcBusy;
+    private rpcConnected;
+    private streaming;
+    private postIdleDrainDeadlineMs;
+    private closed;
+    private earlyDropFn;
+    private statsFactory;
+    private config;
+    turnEventStats: TurnEventStats;
+    lastTurnEndState: string | null;
+    lastTurnCancellationSeen: boolean;
+    lastTurnErrorMessage: string | null;
+    constructor(wsUrl: string, opts?: DaemonSessionOptions);
+    get streamClient(): Client;
+    get rpcSideClient(): Client;
+    get activeLoopId(): string | null;
+    private resolveStreamDeliveryMode;
+    get streamDeliveryMode(): string;
+    private shouldDrop;
+    connect(resumeLoopId?: string | null): Promise<Record<string, unknown>>;
+    private bootstrapLoop;
+    newLoop(): Promise<Record<string, unknown>>;
+    switchLoop(loopId: string): Promise<Record<string, unknown>>;
+    ensureConnected(): Promise<void>;
+    close(): Promise<void>;
+    detach(): Promise<void>;
+    sendTurn(text: string, options?: {
+        autonomous?: boolean;
+        maxIterations?: number;
+        preferredSubagent?: string;
+        model?: string;
+        modelParams?: Record<string, unknown>;
+        attachments?: Array<{
+            mime_type: string;
+            data: string;
+        }>;
+        clarificationMode?: string;
+        clarificationAnswer?: boolean;
+        intentHint?: string;
+    }): Promise<void>;
+    cancelActiveTurn(): Promise<void>;
+    private drainStreamEventsAfterIdle;
+    private withRpcLock;
+    private ensureRpcConnected;
+    listLoops(_limit?: number): Promise<Record<string, unknown>>;
+    fetchLoopCards(loopId: string): Promise<{
+        cards: unknown[];
+        seq: number;
+        contextTokens: number;
+        success: boolean;
+    }>;
+    fetchLoopHistory(loopId: string): Promise<{
+        goals: unknown[];
+        liveCards: unknown[];
+        liveGoalIndex: number | null;
+        contextTokens: number;
+        success: boolean;
+    }>;
+    fetchConversationLog(loopId: string, opts?: {
+        limit?: number;
+        offset?: number;
+        includeEvents?: boolean;
+    }): Promise<Record<string, unknown>[]>;
+    iterTurnChunks(opts?: {
+        maxWaitMs?: number;
+    }): AsyncGenerator<TurnChunk>;
+}
+
+export { type Attachment, type BaseEnvelope, CLIENT_VERSION, type ChatEventResult, ChatEventTerminal, type ClassifierConfig, Client, CommandClient, type CompactImageOptions, type CompleteEnvelope, type Config, type ConnectionAckEnvelope, ConnectionError, type ConnectionInitEnvelope, ConnectionPool, DEFAULT_CLIENT_CAPABILITIES, DEFAULT_DELIVERABLE_PHASES, DEFAULT_POST_IDLE_DRAIN_MS, DEFAULT_THINKING_STEP_EVENTS, DaemonError, DaemonSession, type DaemonSessionOptions, type DecodedMessage, DisconnectCause, type DisconnectEnvelope, ErrIdleTimeout, ErrPoolExhausted, ErrQueryBusy, ErrQueryTimeout, type ErrorEnvelope, EventAutopilotGoalCompleted, EventAutopilotGoalCreated, EventAutopilotGoalProgress, EventAutopilotGoalStatus, EventAutopilotWorkerAssigned, EventAutopilotWorkerUnassigned, EventCardCreated, EventCardReplayBegin, EventCardReplayEnd, EventClassifier, EventExploreCompleted, EventExploreMilestone, EventExploreStarted, EventExploreStepCompleted, EventFinalReport, EventGeneralFailed, EventLoopReattachedWire, EventMessageReceived, EventMessageSent, EventPlanCreated, EventReplayComplete, EventStrangeLoopCompleted, EventStrangeLoopContextCompacted, EventStrangeLoopPlanDecision, EventStrangeLoopReasoned, EventStrangeLoopStarted, EventStrangeLoopStepCompleted, EventStrangeLoopStepQueued, EventStrangeLoopStepStarted, EventStreamToolCallUpdate, EventTacitusCompleted, EventTacitusGatherSummary, EventTacitusStarted, EventToolCallUpdatesBatch, EventToolCompleted, EventToolError, EventToolStarted, INTENT_HINT_EMBED, INTENT_HINT_IMAGE_TO_TEXT, INTENT_HINT_OCR, INTENT_HINT_TEXT_COMPLETION, type InputOptions, type InputOpts, type IntentHint, LOOP_ASSISTANT_OUTPUT_PHASES, type LoopAssistantOutputPhase, type LoopInputIntentHint, type LoopInputParams, type LoopNewOptions, type MessageType, type MethodName, type NegotiatedCapabilities, type NextEnvelope, type NotificationEnvelope, type OnComplete, type OnError, PROTO_VERSION, type PingEnvelope, type PongEnvelope, type PoolConfig, PooledConn, QueryGate, REMOVED_INTENT_HINTS, type ReceiptResponseEnvelope, ReconnectError, type RemovedIntentHint, type RequestEnvelope, type ResponseEnvelope, SSEBroadcaster, type SSEEvent, STREAM_END, type SessionEntry, type SessionMessage, type SessionStore, StaleLoopError, type StatusFrame, StreamCloseFail, type StreamClosePolicy, StreamCloseSoftComplete, type StreamEventPayload, type SubscribeEnvelope, TimeoutError, TimeoutPolicy, type TurnChunk, type TurnConfig, TurnEventStats, TurnRunner, type UnsubscribeEnvelope, type VerbosityLevel, VerbosityTier, authenticate, bootstrapLoopSession, checkDaemonStatus, classifyEventVerbosity, compactAttachments, compactImageAttachment, connectWithRetries, connectedWebsocket, connectionInitEnvelope, decodeMessage, defaultConfig, defaultPoolConfig, disconnectCauseName, disconnectEnvelope, encodeMessage, extractSootheLoopID, extractThinkingStep, fetchConfigSection, fetchLoopCards, fetchLoopHistory, fetchLoopMessages, fetchSkillsCatalog, idleTimeoutForTurn, inboundNeedsDeliveryAck, inputMessageForLoop, isCompletionEvent, isDaemonLive, isSubagentProgressEvent, isTurnEndCustomData, isTurnProgressChunk, isValidVerbosityLevel, loadConfigFromEnv, newLoopInputMessage, newLoopNewMessage, newLoopSubscribeMessage, newRequestID, notificationEnvelope, parseNamespace, pingEnvelope, pongEnvelope, protocol1Rpc, refreshAuthToken, requestDaemonConfigReload, requestDaemonShutdown, requestEnvelope, shouldShow, splitWirePayload, subscribeEnvelope, unsubscribeEnvelope, validateLoopInputIntentHint, waitDaemonReady, waitLoopStatusWithID, waitSubscriptionConfirmed };