@smooai/smooth-operator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Smoo AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,157 @@
+<p align="center"><img src="../assets/smooth-logo.svg" alt="Smooth" width="360" /></p>
+
+<p align="center"><strong><code>@smooai/smooth-operator</code></strong> — the Lambda-native TypeScript client for the smooth-operator protocol. Streaming agent turns, HITL resume, fully typed.</p>
+
+<p align="center">
+  <a href="../LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <img src="https://img.shields.io/badge/tests-16%20passing-success" alt="16 tests passing" />
+  <img src="https://img.shields.io/badge/serverless%20%C2%B7%20polyglot%20%C2%B7%20TDD-6f42c1" alt="serverless · polyglot · TDD" />
+  <a href="https://lom.smoo.ai"><img src="https://img.shields.io/badge/hosted-lom.smoo.ai-0aa" alt="lom.smoo.ai" /></a>
+</p>
+
+---
+
+## What is this?
+
+The **native TypeScript client** for the [smooth-operator](../docs/PROTOCOL.md) WebSocket protocol — and the one the [smooai monorepo dogfoods](https://github.com/SmooAI/smooth-operator). Types are **generated** from the language-neutral JSON Schemas in [`../spec`](../spec) (and committed, so consumers don't need the generator), with an ergonomic layer — discriminated unions + type guards — on top. It's Lambda-native and transport-injectable, so it runs in a browser, on Node, or inside a Lambda handler unchanged.
+
+---
+
+## 30-second quickstart
+
+```bash
+pnpm add @smooai/smooth-operator   # npm publish pending — use a workspace / file: dep today
+```
+
+Requires Node ≥ 22, ESM only. Until the package is published, depend on it from a
+sibling checkout (`"@smooai/smooth-operator": "workspace:*"` in a pnpm workspace, or
+`"file:../smooth-operator/typescript"`).
+
+```ts
+import { SmoothAgentClient } from '@smooai/smooth-operator';
+
+const client = new SmoothAgentClient({ url: 'ws://127.0.0.1:8787/ws' });
+await client.connect();
+
+const session = await client.createConversationSession({ agentId, userName: 'Alice' });
+const turn = client.sendMessage({ sessionId: session.sessionId, message: 'How long is your return window?' });
+
+const final = await turn; // EventualResponse — cost, tokens, messageId
+console.log(final.data.payload.messageId);
+```
+
+(Point `url` at your own [`smooth-operator-server`](../rust/README.md), or at the hosted endpoint.)
+
+---
+
+## Watch it stream
+
+`sendMessage` returns a `MessageTurn` that is **both** an async-iterable of events **and** awaitable for the authoritative terminal state. Iterate tokens as they arrive; `await` the same handle for the final response.
+
+```ts
+const turn = client.sendMessage({ sessionId: session.sessionId, message: 'Where is my order?' });
+
+for await (const ev of turn) {
+  if (ev.type === 'stream_chunk') console.error(`  ↳ node: ${ev.node}`);     // workflow node boundary
+  if (ev.type === 'stream_token') process.stdout.write(ev.token ?? '');       // tokens, live
+  if (ev.type === 'write_confirmation_required') {
+    // HITL: a tool wants to write. Approve, and the resumed stream flows back into THIS turn.
+    client.confirmToolAction({ sessionId: session.sessionId, requestId: turn.requestId, approved: true });
+  }
+}
+
+const final = await turn; // EventualResponse — the authoritative terminal state
+```
+
+```mermaid
+sequenceDiagram
+  participant App
+  participant C as SmoothAgentClient
+  participant S as Service
+  App->>C: sendMessage(...)
+  C->>S: { action: send_message }
+  S-->>C: immediate_response (202)
+  S-->>C: stream_token "Our" "return" "window" …
+  S-->>C: stream_chunk { node: response_gen }
+  S-->>C: eventual_response (200)
+  C-->>App: for-await yields events · await resolves final
+```
+
+---
+
+## Transport injection
+
+The client never touches a real socket directly — it talks to an injectable `Transport`. The default uses the global `WebSocket`. On Node, inject the `ws` package; in tests, inject a mock — which is how the conformance suite exercises real client code (correlation, parsing, HITL routing) without a network.
+
+```ts
+import WebSocket from 'ws';
+new SmoothAgentClient({ url, webSocketFactory: (u) => new WebSocket(u) });
+```
+
+## Runtime validation (optional, Node-only)
+
+```ts
+import { ProtocolValidator } from '@smooai/smooth-operator';
+const v = await ProtocolValidator.load();
+v.validateEvent(incomingEvent); // { valid, errors } — ajv-compiled from the spec schemas
+```
+
+---
+
+## Polyglot — one spec, five clients
+
+This is one of five native clients generated from the same protocol. Need C# / Microsoft.Extensions.AI? The **`IChatClient` facade** lives in the [.NET client](../dotnet/README.md) (it's a .NET-ecosystem feature). This TypeScript package is the native streaming client.
+
+```mermaid
+flowchart LR
+  SPEC["spec/ (JSON Schema)"] --> TS["TypeScript<br/>@smooai/smooth-operator"]
+  SPEC --> GO["Go"]
+  SPEC --> NET[".NET (+ MEAI IChatClient facade)"]
+  SPEC --> PY["Python"]
+  SPEC --> RS["Rust"]
+```
+
+---
+
+## Test-driven by default
+
+> **Nothing here is vibe-coded — it's verified against a real LLM gateway.**
+
+```mermaid
+flowchart TD
+  J["🎯 LLM-as-judge quality evals (Rust harness)"]
+  E["🌐 Live cross-language E2E — this client boots the real server + drives a real claude-haiku-4-5 turn"]
+  C["🧪 Conformance fixtures (shared across all 5 clients)"]
+  U["⚡ Unit + type-level tests (discrimination, guards, correlation)"]
+  J --> E --> C --> U
+```
+
+**16 tests** cover the conformance fixtures, the client (with a mock transport so real parsing/correlation/HITL run), and type-level checks. In the **live cross-language E2E**, this client boots a real `smooth-operator-server` subprocess (KB seeded), drives a real `claude-haiku-4-5` turn over WebSocket, and asserts ≥1 streamed event, a knowledge-grounded "17", and per-session memory.
+
+**The proof story:** an LLM-as-judge scored a multi-turn answer **1/5** (the runtime forgot turn 1's context); the failing eval drove a per-session-memory fix; **it now scores 5/5** — a regression a substring test would have missed. See [`docs/EVALS.md`](../docs/EVALS.md).
+
+Live tests are **gated, never silently skipped**: they run with `SMOOTH_AGENT_E2E=1` + `SMOOAI_GATEWAY_KEY` and skip cleanly otherwise.
+
+```bash
+pnpm test          # conformance + client + type-level — no creds
+pnpm test:e2e      # live cross-language E2E (needs gateway key)
+```
+
+## Scripts
+
+| Script | Purpose |
+| --- | --- |
+| `pnpm generate` | Regenerate `src/generated/types.ts` from `../spec`. |
+| `pnpm build` | `tsc` → `dist/`. |
+| `pnpm typecheck` | Type-check `src/` + `test/` without emitting. |
+| `pnpm test` | Vitest (conformance + client + type-level). |
+
+The generated types are committed; CI runs `pnpm generate` + `git diff --exit-code` to catch schemas that changed without a regenerate.
+
+## Smoo-powered or bring-your-own
+
+Point the client at the hosted **[lom.smoo.ai](https://lom.smoo.ai)** endpoint, or at your own self-hosted `smooth-operator-server` (AWS Lambda or k8s) — same protocol, same client, same code.
+
+## License
+
+MIT © 2026 Smoo AI

package/dist/client.d.ts

@@ -0,0 +1,148 @@
+/**
+ * SmoothAgentClient — a minimal, idiomatic, transport-agnostic client for the
+ * smooth-operator WebSocket protocol.
+ *
+ * Design goals
+ * ------------
+ *  - **Transport-agnostic.** The client never touches a real socket directly; it
+ *    talks to an injectable {@link Transport}. The default ({@link WebSocketTransport})
+ *    uses the global `WebSocket`, but tests inject a mock and Node can inject `ws`.
+ *  - **Request/response correlation by `requestId`.** Every action gets a generated
+ *    `requestId`; the client routes incoming events back to the originating call.
+ *  - **Streaming as an async iterator.** `sendMessage` returns a {@link MessageTurn}
+ *    that is both awaitable (resolves with the terminal `eventual_response`) and
+ *    async-iterable (yields each `stream_token` / `stream_chunk` / HITL event in
+ *    order). This models the `stream_token`/`stream_chunk` → `eventual_response`
+ *    flow without forcing a callback style on the caller.
+ *  - **No live server required.** Correctness is fully unit-testable with a mock
+ *    transport (see `test/client.test.ts`).
+ */
+import { type Transport, type WebSocketFactory } from './transport.js';
+import type { CreateConversationSessionRequest, CreateConversationSessionResponse, EventualResponse, GetMessagesRequest, GetMessagesResponse, GetSessionRequest, GetSessionResponse, SendMessageRequest, ServerEvent } from './types.js';
+export interface SmoothAgentClientOptions {
+    /** WebSocket URL, e.g. `wss://realtime.prod.smooth-agent.dev`. */
+    url: string;
+    /** Inject a transport (for tests / non-browser runtimes). Defaults to a WebSocket transport. */
+    transport?: Transport;
+    /** Inject a WebSocket factory used by the default transport (e.g. the `ws` package on Node). */
+    webSocketFactory?: WebSocketFactory;
+    /** Generate request IDs. Defaults to `crypto.randomUUID()` with a `req-` prefix. */
+    generateRequestId?: () => string;
+    /** Per-request timeout in ms for non-streaming actions. Default 30000. */
+    requestTimeout?: number;
+    /**
+     * Overall timeout in ms for a streaming `sendMessage` turn: if the server accepts
+     * the message but never emits a terminal `eventual_response` / `error`, the turn
+     * rejects with a {@link TurnTimeoutError} instead of hanging forever. Default
+     * 120000. Set to 0 (or a negative number) to disable.
+     */
+    turnTimeout?: number;
+}
+/**
+ * A streaming turn that received no terminal `eventual_response` / `error` within the
+ * configured {@link SmoothAgentClientOptions.turnTimeout}. The turn rejects with this
+ * and its async iteration throws it, so a stuck server can never hang the caller.
+ */
+export declare class TurnTimeoutError extends Error {
+    readonly requestId: string;
+    constructor(requestId: string, ms: number);
+}
+/** A protocol-level error event surfaced as a throwable. */
+export declare class ProtocolError extends Error {
+    readonly code: string;
+    readonly requestId?: string;
+    constructor(code: string, message: string, requestId?: string);
+}
+/**
+ * A streaming message turn. Await it for the terminal {@link EventualResponse},
+ * or async-iterate it to receive every intermediate event in arrival order.
+ *
+ * ```ts
+ * const turn = client.sendMessage({ sessionId, message: 'hi' });
+ * for await (const ev of turn) {
+ *   if (ev.type === 'stream_token') process.stdout.write(ev.token ?? '');
+ * }
+ * const final = await turn; // EventualResponse
+ * ```
+ */
+export declare class MessageTurn implements AsyncIterable<ServerEvent>, PromiseLike<EventualResponse> {
+    /** The requestId this turn is correlated on. */
+    readonly requestId: string;
+    private readonly queue;
+    private waiter;
+    private done;
+    private finalEvent;
+    private error;
+    private readonly settled;
+    private settle;
+    private fail;
+    private readonly onClose;
+    private timeoutTimer;
+    constructor(requestId: string, onClose: () => void, turnTimeout?: number);
+    /** Feed an event into the turn (called by the client's dispatcher). */
+    push(event: ServerEvent): void;
+    /** Force-close the turn (e.g. on disconnect) with an error. */
+    abort(err: unknown): void;
+    private deliver;
+    private finish;
+    [Symbol.asyncIterator](): AsyncIterator<ServerEvent>;
+    then<TResult1 = EventualResponse, TResult2 = never>(onfulfilled?: ((value: EventualResponse) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+export declare class SmoothAgentClient {
+    private readonly transport;
+    private readonly generateRequestId;
+    private readonly requestTimeout;
+    private readonly turnTimeout;
+    /** requestId → single-response waiter (create_session, get_session, ping, …). */
+    private readonly pending;
+    /** requestId → active streaming turn (send_message, and HITL resumes). */
+    private readonly turns;
+    /** Unsolicited-event listeners (keepalive, server-push). */
+    private readonly listeners;
+    private unsubscribe;
+    constructor(options: SmoothAgentClientOptions);
+    /** Open the underlying transport. */
+    connect(): Promise<void>;
+    /** Close the transport and reject all in-flight work. */
+    disconnect(reason?: string): void;
+    /** Subscribe to unsolicited / uncorrelated server events (e.g. keepalive). */
+    onEvent(listener: (event: ServerEvent) => void): () => void;
+    /** Start a new conversation session. Resolves with the session descriptor. */
+    createConversationSession(req: Omit<CreateConversationSessionRequest, 'action' | 'requestId'>): Promise<CreateConversationSessionResponse>;
+    /** Fetch a session snapshot by ID. */
+    getSession(req: Omit<GetSessionRequest, 'action' | 'requestId'>): Promise<GetSessionResponse>;
+    /** Fetch a page of conversation messages. */
+    getMessages(req: Omit<GetMessagesRequest, 'action' | 'requestId'>): Promise<GetMessagesResponse>;
+    /** Keepalive ping. Resolves with the server timestamp from the `pong` event. */
+    ping(): Promise<number>;
+    /**
+     * Submit a user message and return a {@link MessageTurn}: await it for the
+     * terminal `eventual_response`, or async-iterate it for the streaming events.
+     */
+    sendMessage(req: Omit<SendMessageRequest, 'action' | 'requestId'>): MessageTurn;
+    /**
+     * Approve or reject a pending tool write, resuming the paused turn identified
+     * by `requestId`. The resumed streaming events flow back into the original
+     * {@link MessageTurn} for that `requestId`.
+     */
+    confirmToolAction(req: {
+        sessionId: string;
+        requestId: string;
+        approved: boolean;
+    }): void;
+    /**
+     * Submit an OTP code, resuming the paused turn identified by `requestId`.
+     * The resumed streaming events flow back into the original {@link MessageTurn}.
+     */
+    verifyOtp(req: {
+        sessionId: string;
+        requestId: string;
+        code: string;
+    }): void;
+    /** Send an action that expects a single correlated response event. */
+    private request;
+    /** Parse and route an incoming frame to the right consumer. */
+    private handleFrame;
+    private failAll;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}