@mirasoth/soothe-client 0.2.1 → 0.4.1

package/README.md

@@ -1,82 +1,116 @@
 # @mirasoth/soothe-client
 
-TypeScript WebSocket client for the [Soothe](https://github.com/mirasoth/soothe) daemon.
-
-Provides a typed message protocol, session bootstrap, event helpers, and convenience RPCs for
-interacting with a running `soothe-daemon` from Node.js.
-
-## Install
+Talk to a running **soothe-daemon** over WebSocket — send prompts, stream agent
+turns, run jobs.
 
 ```bash
 npm install @mirasoth/soothe-client
-# or
-pnpm add @mirasoth/soothe-client
-# or
-yarn add @mirasoth/soothe-client
+# optional: real image downscale for CompactAttachmentsBeforeSend
+npm install sharp
 ```
 
-Requires Node.js `>=19`.
+Requires Node.js `>=19` and a local daemon (default `ws://127.0.0.1:8765`).
 
 ## Quick start
 
 ```ts
-import { Client, bootstrapLoopSession, defaultConfig } from '@mirasoth/soothe-client';
+import { DaemonSession } from '@mirasoth/soothe-client';
+
+const session = new DaemonSession('ws://127.0.0.1:8765');
+await session.connect();
+await session.sendTurn('Summarize this in one sentence: agents need tools.');
+
+for await (const [_namespace, mode, data] of session.iterTurnChunks()) {
+  console.log(mode, data);
+}
 
-const config = defaultConfig();
-const client = new Client(config.daemonURL, config);
+await session.close();
+```
+
+More patterns: [`examples/`](examples/) (hello → streaming → multi-turn → pool → jobs).
 
-await client.connect();
-const loopId = await bootstrapLoopSession(client, null, config);
+## What you get
 
-client.on('message', (msg) => {
-  console.log('event:', msg);
-});
+| Need | Use |
+|------|-----|
+| One conversation, stream replies | `DaemonSession` |
+| Jobs / cron one-shots | `CommandClient` |
+| Raw WebSocket / custom RPCs | `Client` |
+| Many users / HTTP backend | `ConnectionPool` + `TurnRunner` |
 
-await client.sendMessage({
-  type: 'loop_input',
-  loop_id: loopId,
-  input: 'hello soothe',
-});
+`iterTurnChunks` peels leftover prior-goal terminals at turn start, ignores
+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`.
+
+| Knob | Default | Notes |
+|------|---------|--------|
+| `idleTimeout` | off (`0`) | Silence watchdog between events (ms) |
+| `minIdleTimeoutWithAttachments` | off | Floor when attachments are present |
+| `onIdleTimeout` / `onQueryTimeout` / `onStreamClose` | `Fail` | Or `SoftComplete` |
+| `compactAttachmentsBeforeSend` | `false` | Needs optional `sharp` for real downscale |
+| `treatStatusIdleAsComplete` (classifier) | `false` | Opt-in idle deliverable |
+
 ## Configuration
 
-`defaultConfig()` returns a `Config` object with sensible defaults. `loadConfigFromEnv()` reads
-overrides from these environment variables:
+`defaultConfig()` / `loadConfigFromEnv()`:
 
-| Variable                              | Default                  | Description                              |
-| ------------------------------------- | ------------------------ | ---------------------------------------- |
-| `SOOTHE_DAEMON_URL`                   | `ws://localhost:8765`    | Daemon WebSocket URL                     |
-| `SOOTHE_VERBOSITY`                    | `normal`                 | `quiet` \| `minimal` \| `normal` \| `detailed` \| `debug` |
-| `SOOTHE_MAX_RETRIES`                  | `5`                      | Reconnect attempts                       |
-| `SOOTHE_DAEMON_READY_TIMEOUT_SEC`     | `20`                     | Daemon-ready handshake timeout (seconds) |
-| `SOOTHE_LOOP_STATUS_TIMEOUT_SEC`      | `60`                     | Loop status wait timeout (seconds)       |
-| `SOOTHE_SUBSCRIPTION_TIMEOUT_SEC`     | `10`                     | Subscription confirmation timeout (seconds) |
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `SOOTHE_DAEMON_URL` | `ws://localhost:8765` | Daemon WebSocket URL |
+| `SOOTHE_VERBOSITY` | `normal` | quiet / minimal / normal / detailed / debug |
+| `SOOTHE_MAX_RETRIES` | `5` | Reconnect attempts |
+| `SOOTHE_DAEMON_READY_TIMEOUT_SEC` | `20` | Handshake timeout |
+| `SOOTHE_LOOP_STATUS_TIMEOUT_SEC` | `60` | Loop status wait |
+| `SOOTHE_SUBSCRIPTION_TIMEOUT_SEC` | `10` | Subscription confirmation |
 
 ## API surface
 
-- **`Client`** — WebSocket session, message I/O, request/response, RPC helpers
-- **`bootstrapLoopSession`**, **`waitDaemonReady`**, **`connectWithRetries`** — session helpers
-- **`checkDaemonStatus`**, **`fetchSkillsCatalog`**, **`fetchConfigSection`** — daemon RPCs
-- **`encodeMessage` / `decodeMessage`** — protocol codec
-- **`Event*` classes** — typed event payloads (plan, explore, tacitus, tool, agent-loop)
-- **`VerbosityTier`**, **`classifyEventVerbosity`** — verbosity filtering
-- **Errors** — `ConnectionError`, `DaemonError`, `TimeoutError`
+- **`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
 
-See `dist/index.d.ts` (published) or `src/index.ts` (source) for the full export list.
+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 all targets
+make help        # list targets
 make install     # install dependencies
 make build       # compile to dist/
-make test        # run unit tests
+make test        # unit tests
 make verify      # full pre-publish verification
-make publish     # publish to npm (after verify)
+npm test -- examples/progressive   # 01–06 ladder (offline)
 ```
 
-See [`Makefile`](./Makefile) for the complete list of targets.
+## Compatibility
+
+Same protocol-1 WebSocket contract as `soothe-client-python` and
+`soothe-client-go`.
 
 ## License