@mirasoth/soothe-client 0.4.0 → 0.4.1

package/README.md

@@ -1,12 +1,7 @@
 # @mirasoth/soothe-client
 
-TypeScript WebSocket client for the [Soothe](https://github.com/mirasoth/soothe) daemon.
-
-Provides a typed protocol-1 message stack, session bootstrap, reconnect/reattach,
-appkit (connection pool, turn runner, event classifier), and a dual-socket
-`DaemonSession` for streamed turns — matching the production Go and Python clients.
-
-## Install
+Talk to a running **soothe-daemon** over WebSocket — send prompts, stream agent
+turns, run jobs.
 
 ```bash
 npm install @mirasoth/soothe-client
@@ -14,7 +9,7 @@ npm install @mirasoth/soothe-client
 npm install sharp
 ```
 
-Requires Node.js `>=19`.
+Requires Node.js `>=19` and a local daemon (default `ws://127.0.0.1:8765`).
 
 ## Quick start
 
@@ -23,15 +18,17 @@ import { DaemonSession } from '@mirasoth/soothe-client';
 
 const session = new DaemonSession('ws://127.0.0.1:8765');
 await session.connect();
-await session.sendTurn('summarize this repo');
+await session.sendTurn('Summarize this in one sentence: agents need tools.');
 
-for await (const [namespace, mode, data] of session.iterTurnChunks()) {
+for await (const [_namespace, mode, data] of session.iterTurnChunks()) {
   console.log(mode, data);
 }
 
 await session.close();
 ```
 
+More patterns: [`examples/`](examples/) (hello → streaming → multi-turn → pool → jobs).
+
 ## What you get
 
 | Need | Use |
@@ -42,16 +39,23 @@ await session.close();
 | Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
 
 `iterTurnChunks` peels leftover prior-goal terminals at turn start, ignores
-premature `soothe.stream.end` until the turn has real progress, and drains a
-short post-idle window before returning. Terminal stream frames send
-`delivery_ack` (daemon drain gating).
+premature `soothe.stream.end` until the turn has real progress, drains a short
+post-idle window, and sends `delivery_ack` on terminal frames for daemon drain
+gating.
+
+```ts
+import { CommandClient } from '@mirasoth/soothe-client';
+
+const cc = new CommandClient('ws://127.0.0.1:8765', { timeoutMs: 30_000 });
+const created = await cc.jobCreate('Echo: smoke job', '/tmp/workspace');
+await cc.jobStatus(String(created.job_id));
+await cc.jobCancel(String(created.job_id));
+```
 
 ## Appkit TurnRunner
 
 Product backends that pool connections per chat session use `ConnectionPool` +
-`QueryGate` + `TurnRunner` + `EventClassifier` (RFC-629 Layer 1).
-
-Lifecycle knobs (all opt-in; defaults match historical fail-on-timeout behaviour):
+`QueryGate` + `TurnRunner` + `EventClassifier`.
 
 | Knob | Default | Notes |
 |------|---------|--------|
@@ -76,15 +80,23 @@ Lifecycle knobs (all opt-in; defaults match historical fail-on-timeout behaviour
 
 ## API surface
 
-- **`Client`** — WebSocket session, RPC, reconnect/reattach, peel stale pending frames
-- **`DaemonSession`** — dual-socket loop session + `iterTurnChunks`
-- **`TurnRunner` / `ConnectionPool` / `QueryGate` / `EventClassifier` / `SSEBroadcaster`** — appkit
+- **`DaemonSession`** — dual-socket loop session + `iterTurnChunks` (preferred for chat)
+- **`CommandClient`** — ephemeral connect → one RPC → close (jobs / cron)
+- **`Client`** — long-lived WebSocket, RPC, reconnect/reattach, peel-stale helpers
+- **`ConnectionPool` / `TurnRunner` / `QueryGate` / `EventClassifier` / `SSEBroadcaster`** — multi-user appkit
 - **`connectedWebsocket` / `protocol1Rpc`** — oneshot CLI-style helpers
-- **`bootstrapLoopSession`**, **`connectWithRetries`** — session helpers
+- **`bootstrapLoopSession` / `connectWithRetries`** — session helpers
 
 See `dist/index.d.ts` or `src/index.ts` for the full export list.
 
-## Development
+## Limitations
+
+Autopilot control is WebSocket-only (protocol-1 `autopilot_*` / `job_*`
+request RPCs). Prefer `CommandClient` for job/cron/autopilot one-shots so they
+do not share a streaming socket. Worker event streams use
+`client.autopilotSubscribe()` on a long-lived `Client`.
+
+## Develop
 
 ```bash
 make help        # list targets
@@ -92,8 +104,14 @@ make install     # install dependencies
 make build       # compile to dist/
 make test        # unit tests
 make verify      # full pre-publish verification
+npm test -- examples/progressive   # 01–06 ladder (offline)
 ```
 
+## Compatibility
+
+Same protocol-1 WebSocket contract as `soothe-client-python` and
+`soothe-client-go`.
+
 ## License
 
 MIT — see [LICENSE](./LICENSE).

package/dist/{chunk-U6RMINYV.js → chunk-YYUVHZ3W.js}

@@ -63,7 +63,7 @@ var ConnectionError = class extends Error {
   }
 };
 var DaemonError = class extends Error {
-  /** Numeric error code from the RFC-450 §7.3 registry. */
+  /** Numeric error code from the daemon error registry. */
   code;
   /** The daemon's error message text. */
   daemonMessage;
@@ -621,7 +621,7 @@ function messagesWireTerminal(data) {
 import { randomUUID } from "crypto";
 var PROTO_VERSION = "1";
 var DEFAULT_CLIENT_CAPABILITIES = ["streaming", "batch", "heartbeat", "receipts"];
-var CLIENT_VERSION = "0.4.0";
+var CLIENT_VERSION = "0.4.1";
 function encodeMessage(msg) {
   return JSON.stringify(msg) + "\n";
 }
@@ -793,7 +793,7 @@ var Client = class extends EventEmitter {
   inboundDroppedCount = 0;
   onStreamDegraded = null;
   resolvers = [];
-  // Protocol-1 handshake state (RFC-450 §8.2)
+  // Protocol-1 handshake state
   handshakeComplete = false;
   negotiatedCapabilities = /* @__PURE__ */ new Set();
   protocolVersion = null;
@@ -801,12 +801,12 @@ var Client = class extends EventEmitter {
   heartbeatIntervalMs = 0;
   heartbeatTimer = null;
   lastPongMonotonic = 0;
-  // Mid-session drop signal (RFC-450 §8.3). The 'disconnected' event is
+  // Mid-session drop signal. The 'disconnected' event is
   // emitted exactly once when the connection drops, carrying a DisconnectCause
   // that distinguishes clean (peer `disconnect`) from unclean (read/write
   // error or missed pong). `disconnFired` guards the once-only delivery.
   disconnFired = false;
-  // Pending-request/subscription multiplexer (RFC-629 constraint #1). Routes
+  // Pending-request/subscription multiplexer. Routes
   // inbound frames by (type, id) instead of discarding non-matching events.
   mux = new Multiplexer();
   deliveryRecvSeq = /* @__PURE__ */ new Map();
@@ -923,7 +923,7 @@ var Client = class extends EventEmitter {
     return this.ws !== null && this.ws.readyState === WebSocket.OPEN && this.handshakeComplete;
   }
   // ---------------------------------------------------------------------------
-  // Mid-session drop signal + reconnect/reattach (RFC-450 §8.3, RFC-629 L0)
+  // Mid-session drop signal + reconnect/reattach
   // ---------------------------------------------------------------------------
   /**
    * Returns whether the connection has dropped (the `'disconnected'` event has
@@ -958,8 +958,8 @@ var Client = class extends EventEmitter {
     }
   }
   /**
-   * 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.
@@ -993,7 +993,7 @@ var Client = class 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.
    */
@@ -1034,7 +1034,7 @@ var Client = class extends EventEmitter {
     }
   }
   // ---------------------------------------------------------------------------
-  // Protocol-1 handshake (RFC-450 §8.2)
+  // Protocol-1 handshake
   // ---------------------------------------------------------------------------
   /** Send connection_init and wait for connection_ack with readiness "ready". */
   async _performHandshake() {
@@ -1083,7 +1083,7 @@ var Client = class extends EventEmitter {
     throw new Error(`timeout after ${this.config.daemonReadyTimeout}ms waiting for connection_ack`);
   }
   // ---------------------------------------------------------------------------
-  // Heartbeat (RFC-450 §8.3)
+  // Heartbeat
   // ---------------------------------------------------------------------------
   _startHeartbeat() {
     if (!this.negotiatedCapabilities.has("heartbeat")) return;
@@ -1278,7 +1278,7 @@ var Client = class extends EventEmitter {
     }
   }
   // ---------------------------------------------------------------------------
-  // Protocol-1 RPC primitives (RFC-450 §5/§9)
+  // Protocol-1 RPC primitives
   // ---------------------------------------------------------------------------
   /**
    * Reads the next frame directly from the live socket (via a resolver),
@@ -1304,16 +1304,16 @@ var Client = class extends EventEmitter {
     });
   }
   /**
-   * Sends a `request` envelope and waits for the matching `response` (or
-   * `error`) correlated by `id` (RFC-450 §5/§9). Returns the `result` object.
-   *
-   * Multiplexer-aware (RFC-629 constraint #1): 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.
-   * Non-matching frames are routed to their own waiters by the multiplexer
-   * or flow on to the resolver queue for stream readers.
-   */
+    * Sends a `request` envelope and waits for the matching `response` (or
+  * `error`) correlated by `id`. Returns the `result` object.
+    *
+  * 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.
+    * Non-matching frames are routed to their own waiters by the multiplexer
+    * or flow on to the resolver queue for stream readers.
+    */
   async requestResponse(method, params, responseType, timeout = 15e3) {
     const req = requestEnvelope(method, params);
     const rid = req.id;
@@ -1464,7 +1464,7 @@ var Client = class extends EventEmitter {
     return ev;
   }
   // ---------------------------------------------------------------------------
-  // High-level API methods (Loop-first, RFC-503)
+  // High-level API methods
   // ---------------------------------------------------------------------------
   /** Sends user input to the daemon (loop_input notification; requires loopID). */
   sendInput(text, options) {
@@ -1503,7 +1503,7 @@ var Client = class extends EventEmitter {
     return this.notify("slash_command", { cmd });
   }
   // ---------------------------------------------------------------------------
-  // Loop lifecycle methods (RFC-503)
+  // Loop lifecycle methods
   // ---------------------------------------------------------------------------
   /** Requests the daemon to create a new StrangeLoop and waits for the response. */
   sendLoopNew(opts) {
@@ -1598,7 +1598,7 @@ var Client = class extends EventEmitter {
   sendLoopCardsFetch(loopID) {
     return this.sendMessage(requestEnvelope("loop_cards_fetch", { loop_id: loopID }));
   }
-  /** Requests the full loop history (RFC-631). */
+  /** Requests the full loop history. */
   sendLoopHistoryFetch(loopID) {
     return this.sendMessage(requestEnvelope("loop_history_fetch", { loop_id: loopID }));
   }
@@ -1693,7 +1693,7 @@ var Client = class extends EventEmitter {
     );
   }
   // ---------------------------------------------------------------------------
-  // RFC-228 Job IPC methods
+  // Job IPC methods
   // ---------------------------------------------------------------------------
   /** Creates an autopilot job and waits for the response. */
   createJob(goal, verificationRules, workspace, timeout) {
@@ -1728,6 +1728,98 @@ var Client = class extends EventEmitter {
     if (goalId) params.goal_id = goalId;
     return this.requestResponse("job_guidance", params, "job_guidance", timeout ?? 3e4);
   }
+  // ---------------------------------------------------------------------------
+  // Autopilot goal RPCs (protocol-1 request methods)
+  // ---------------------------------------------------------------------------
+  /** Return autopilot scheduler status (running / dreaming / pool). */
+  autopilotStatus(timeout) {
+    return this.requestResponse("autopilot_status", {}, "autopilot_status", timeout ?? 15e3);
+  }
+  /** Submit a new autopilot goal (returns goal_id). */
+  autopilotSubmit(description, opts) {
+    const params = {
+      description,
+      priority: opts?.priority ?? 50
+    };
+    if (opts?.workspace) params.workspace = opts.workspace;
+    return this.requestResponse(
+      "autopilot_submit",
+      params,
+      "autopilot_submit",
+      opts?.timeout ?? 15e3
+    );
+  }
+  /** List all goals (including non-root children). */
+  autopilotListGoals(timeout) {
+    return this.requestResponse(
+      "autopilot_list_goals",
+      {},
+      "autopilot_list_goals",
+      timeout ?? 15e3
+    );
+  }
+  /** Fetch one goal by id. */
+  autopilotGetGoal(goalId, timeout) {
+    return this.requestResponse(
+      "autopilot_get_goal",
+      { goal_id: goalId },
+      "autopilot_get_goal",
+      timeout ?? 15e3
+    );
+  }
+  /** Cancel a goal and its non-terminal descendants. */
+  autopilotCancelGoal(goalId, timeout) {
+    return this.requestResponse(
+      "autopilot_cancel_goal",
+      { goal_id: goalId },
+      "autopilot_cancel_goal",
+      timeout ?? 15e3
+    );
+  }
+  /** Cancel every open (non-terminal) goal. */
+  autopilotCancelAll(timeout) {
+    return this.requestResponse(
+      "autopilot_cancel_all",
+      {},
+      "autopilot_cancel_all",
+      timeout ?? 15e3
+    );
+  }
+  /** Exit dreaming mode and resume scheduling. */
+  autopilotWake(timeout) {
+    return this.requestResponse("autopilot_wake", {}, "autopilot_wake", timeout ?? 15e3);
+  }
+  /** Force dreaming mode. */
+  autopilotDream(timeout) {
+    return this.requestResponse("autopilot_dream", {}, "autopilot_dream", timeout ?? 15e3);
+  }
+  /** Resume a suspended or blocked goal. */
+  autopilotResume(goalId, timeout) {
+    return this.requestResponse(
+      "autopilot_resume",
+      { goal_id: goalId },
+      "autopilot_resume",
+      timeout ?? 15e3
+    );
+  }
+  /** List root goals only (jobs). Prefer createJob / getJobStatus for job control. */
+  autopilotListJobs(timeout) {
+    return this.requestResponse(
+      "autopilot_list_jobs",
+      {},
+      "autopilot_list_jobs",
+      timeout ?? 15e3
+    );
+  }
+  /** Get a root job with DAG snapshot. Prefer getJobStatus / getJobDag. */
+  autopilotGetJob(jobId, timeout) {
+    return this.requestResponse(
+      "autopilot_get_job",
+      { job_id: jobId },
+      "autopilot_get_job",
+      timeout ?? 15e3
+    );
+  }
   /** Subscribes to autopilot worker events. */
   autopilotSubscribe(timeout) {
     return this.subscribe("autopilot_events", {}, timeout ?? 15e3);
@@ -1738,7 +1830,7 @@ var Client = class extends EventEmitter {
     return this._requestResponseForEnvelope(req, "autopilot_unsubscribe", timeout ?? 15e3);
   }
   // ---------------------------------------------------------------------------
-  // RFC-229 Cron IPC methods
+  // Cron IPC methods
   // ---------------------------------------------------------------------------
   /** Creates a scheduled job from natural language. */
   cronAdd(text, priority, timeout) {
@@ -1880,4 +1972,4 @@ export {
   inboundNeedsDeliveryAck,
   Client
 };
-//# sourceMappingURL=chunk-U6RMINYV.js.map
+//# sourceMappingURL=chunk-YYUVHZ3W.js.map