@mirasoth/soothe-client 0.4.0 → 0.4.1

package/dist/index.d.cts

@@ -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.4.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
@@ -524,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.
@@ -540,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.
      */
@@ -587,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.
@@ -669,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>;
@@ -711,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. */
@@ -733,7 +759,7 @@ declare class Client extends EventEmitter {
 
 /**
  * Ephemeral one-shot RPC client for jobs / cron / autopilot.
- * Mirrors Python AsyncCommandClient / CommandClient (RFC-629 / IG-662).
+ * Mirrors Python AsyncCommandClient / CommandClient.
  */
 
 declare class CommandClient {
@@ -750,12 +776,37 @@ declare class CommandClient {
     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. */
@@ -770,7 +821,7 @@ 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>>;
@@ -835,7 +886,7 @@ declare function isTurnProgressChunk(mode: string, data: unknown): boolean;
 declare function inboundNeedsDeliveryAck(event: Record<string, unknown>): boolean;
 
 /**
- * Persistence seam for appkit (RFC-629 Layer 1).
+ * Persistence seam for appkit.
  *
  * SessionStore abstracts per-application storage: the session↔loop-id mapping
  * that ConnectionPool consults to decide bootstrap vs reattach, and the
@@ -896,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
@@ -944,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
@@ -960,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`.
  */
 
@@ -1069,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
@@ -1117,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.
@@ -1163,7 +1213,7 @@ type ClientFactory = (url: string, config?: Config) => ManagedClient;
 type BootstrapFunc = (client: ManagedClient, workspaceID: string, userID: string, config?: Config) => Promise<string>;
 
 /**
- * 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
@@ -1257,7 +1307,7 @@ declare class ConnectionPool {
 }
 
 /**
- * Attachment image compaction for appkit (Go IG-651 / SIL-04 parity).
+ * Attachment image compaction for appkit.
  *
  * When `sharp` is installed (optionalDependency), oversized image/* payloads
  * are downscaled. Without sharp, attachments pass through unchanged.
@@ -1280,13 +1330,13 @@ declare function compactImageAttachment(mimeType: string, dataB64: string, opts?
 declare function compactAttachments(atts: Record<string, unknown>[], opts?: CompactImageOptions | null): Promise<Record<string, unknown>[]>;
 
 /**
- * Turn runner for appkit (RFC-629 Layer 1).
+ * 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.
  *
- * Supports IG-651 / SIL-04 lifecycle knobs: idle timeout, soft-complete
+ * Supports lifecycle knobs: idle timeout, soft-complete
  * policies, attachment compaction, and stream-close soft-complete.
  */