10xgraph-client 0.6.0 → 1.0.0-rc.2

package/CHANGELOG.md

@@ -16,6 +16,211 @@ project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - **Breaking changes are documented under a `### Breaking` heading**, with migration steps.
 - The package entry points (`main`, `module`, `types`, `exports`) are part of the contract.
   Changing them is a breaking change.
+- **From 1.0, `major.minor` is identical across `10xgraph`, `10xgraph-api` and
+  `10xgraph-client`.** Use the client with a `10xgraph-api` of the same `major.minor`.
+- **Patch numbers move independently.** A patch release contains only bug or security fixes.
+- **Any new feature means all three packages release the next `X.Y.0` together.** A package with
+  no changes in that release ships a "version alignment, no changes" entry.
+- **Breaking changes need a new major version** (2.0), after a deprecation that lasted at least
+  one minor release. The deprecated `AgentFlow*` aliases in `src/compat.ts` are removed in 2.0.
+
+---
+
+## [1.0.0-rc.2] - 2026-10-30
+
+The second release candidate of `10xgraph-client` 1.0, aligned with `10xgraph` and `10xgraph-api`
+1.0.0rc2. It is `1.0.0-rc.1` below plus the changes here. Use it with `10xgraph-api` 1.0.0rc2. New
+response fields are typed optional, so the client still works against older servers. The client
+API is source compatible with 0.6.0; the one hard requirement change is Node.js 20.
+
+### Breaking
+
+- **Node.js 18 is no longer supported.** `engines` is `node >= 20.0.0` and Node 18 is removed
+  from CI (CI runs Node 20 and 22). Node 18 is past end of life.
+
+### Upgrade notes
+
+- With `10xgraph-api` 1.0 a client that invents a thread id for a new conversation gets HTTP 403. Omit `thread_id` on the first request and reuse the id the server returns (see
+  `1.0.0-rc.1` below).
+- Behaviour you may notice, none of it a signature change:
+  - `stream()` and `wsStream()` now throw (`StreamError`, `WebSocketError`) when a stream is cut
+    or the server closes the socket mid-run. Before, they ended as if the run had succeeded.
+  - The `timeout` option is an idle timeout on `stream()` and `wsStream()`: it limits how long the
+    client waits on the network, not how long the whole run takes.
+  - A `baseUrl` with a trailing slash is accepted; the slashes are stripped.
+  - Errors from timeouts and network failures are `RequestTimeoutError` and `NetworkError`, not
+    plain `Error`. Code that matched on message text should check the class.
+
+### Added
+
+- `Interrupt` type, `getInterrupt(chunk)`, `approveInterrupt(interrupt, value?)` and
+  `rejectInterrupt(interrupt)`. `getInterrupt` reads the pending interrupt from an `updates`
+  chunk; the helpers return `{ resume, interrupt_id }` to spread into the options of
+  `invoke()`, `stream()` or `wsStream()`.
+- `authToken` accepts a function `() => string | null | undefined`, called on every request and
+  on every realtime reconnect, so short-lived tokens refresh without rebuilding the client.
+  `setAuthToken(token)` replaces it, and `clearAuth()` drops the bearer token and `auth`
+  credentials.
+- Every method that makes a request takes a `signal` option (`RequestOptions`), not only
+  `invoke()`, `stream()` and `wsStream()`.
+- New error classes and fields: `RequestTimeoutError`, `NetworkError`, `WebSocketError`,
+  `StreamError` and `RateLimitError`. `RateLimitError` carries `retryAfterSeconds` from the
+  `Retry-After` header or the body. Errors carry `cause`, `endpoint` and `method`, and
+  `requestId` reads the `x-request-id` header.
+- Remote tool registrations take `validate(args)` (throw or return `false` to refuse the call)
+  and `maxArgsBytes` (default 1 MiB). The declared `parameters` are checked against the
+  server-sent arguments before the handler runs, and a repeated call id is rejected.
+- `listMemories` takes `offset`, and its response has `has_more` and `next_offset`, so a user with
+  many memories can page. Needs `10xgraph-api` 1.0.
+- CommonJS consumers get their own type declarations (`dist/cjs/index.d.ts`) through the
+  `exports` map, so `require` works with `nodenext` type checking.
+- `signal?: AbortSignal` option on `invoke()`, `stream()` and `wsStream()`. Aborting it cancels the
+  in-flight request (and the open stream body or WebSocket). The call rejects with the abort error
+  (`name === 'AbortError'`), not the "Request timeout" error. A signal that is already aborted
+  rejects before any request is sent.
+- `listFiles(params?)` for `GET /v1/files` (`{ limit?, offset? }`), with `ListFilesRequest`,
+  `ListFilesResponse`, `FileListItem`. A media store that cannot enumerate files answers 501,
+  thrown as a `TenxGraphError`.
+- `has_more`, `offset` and `limit` on the `threads()` and `threadMessages()` response data.
+- Observability types for the run trace: per-span `status`, `error`, `inputs`, `outputs`, `step`,
+  `visit`, `total_tokens`, `reasoning_tokens`, `tool_name`, `tool_call_id`; run-level `error`,
+  `model`, `models`, `notes`; payload-level `enabled` and `reason` (`ObsEmptyReason`), so a UI can
+  tell "tracing is off" from "no runs yet". New `ObsMessageSummary` type.
+- `GraphInfo.realtime_options` (`GraphRealtimeOptions`): the Live init options the server honors, null
+  for non-realtime graphs.
+- Eval report types for the extended report: case `error` and `error` status, rubric
+  `kind`, `passed`, `threshold`, `details`, `error`, case `expected_detail`, run `counts`, and
+  `errors` on run summaries.
+
+### Changed
+
+- Live sessions without a `thread_id` now use the server-created id. The client no longer invents one: it sends none, reads the id from the new `session_started` event (`{ type: 'session_started', thread_id }`, the first server event) into `session.threadId` (`string | null`, set once the event arrives), and sends it back on reconnect so the same thread continues. A caller-supplied `thread_id` works as before. Needs `10xgraph-api` 1.0, where an invented id gets 403.
+- **Typed change:** `RealtimeSession.threadId` is `string | null`. It is `null` until the
+  `session_started` event arrives when you passed no `thread_id`, so code that read it as a
+  `string` right after `realtime()` must handle `null` (or wait for `session_started`).
+  `session.ready` still resolves when the socket opens, not on `session_started`, and the event is
+  part of the `RealtimeEvent` union.
+- The `timeout` is an idle timeout on `stream()` and `wsStream()`: it runs while the client waits
+  for headers or the next piece of data and is paused while your code handles a chunk.
+- `invoke()` and the other REST methods apply the timeout and your `signal` to the response body
+  as well, not only to the response headers.
+- Realtime reconnects use jittered backoff, restore the attempt budget only after a connection
+  stayed open for 10 s, go straight to the longest delay on close code 1013, and stop with a fatal
+  `policy_violation` error on close code 1008 (an expired or rejected token).
+- Path ids (thread, message, memory) are percent-encoded in every endpoint.
+- Header-type credentials other than `Authorization` (for example `X-API-Key`) are not forwarded
+  on a cross-origin redirect; the call fails instead.
+- The HTTP error mapping covers every JSON error body, including the real server's 409
+  `state_conflict` body, and maps the server's codes (`RECURSION_001`, `STORAGE_TRANSIENT_000`,
+  `STORAGE_SCHEMA_000`, `STORAGE_SERIALIZATION_000`) to `GraphRecursionError`,
+  `TransientStorageError`, `SchemaVersionError` and `SerializationError`.
+- Response and request types match what the server sends: fields the server never sends were
+  removed from `AgentState` and `StopGraphResponse`, nullable fields are typed nullable, and
+  `updateThreadState` no longer accepts keys the server rejects.
+- `stream()` and `wsStream()` stop a client-tool loop at `recursion_limit`; `recursion_limit: 0`
+  is honoured and not turned into 25.
+
+### Fixed
+
+- Leaving a `for await` loop over `stream()` early (`break`, `return` or a throw) cancels the
+  request. Before, the connection and the server run stayed open and the thread answered 409.
+- `wsStream()` no longer hangs when the server answers a frame with an error chunk, and it
+  throws when the server closes the socket before the run finishes (1012, 1008, 1011).
+- A truncated or unparseable stream line throws `StreamError` and a reset connection throws a
+  `StreamError` with code `STREAM_INTERRUPTED`, not a raw `TypeError: terminated`.
+- A conflict (HTTP 409) throws `ConflictError` against the real server. It used to throw a
+  `TypeError`.
+- `client.realtime()` no longer crashes the Node process with an unhandled rejection when the
+  connection fails and `session.ready` was not awaited.
+- Realtime: `close()` during a pending reconnect no longer reopens the session, `send*` before
+  the socket is open is dropped and does not throw, and a failing reconnect does not end the
+  process.
+- Failed requests no longer leave the timeout timer running, so a script that catches a
+  `ping()` error exits at once instead of after the timeout.
+- Empty arrays are no longer stripped from messages and tool results, so a tool result with
+  `output: []` reaches the model as an empty list.
+- `recursion_limit_reached` is true only when the limit stopped the run, and a limit stop is
+  reported to the caller instead of ending silently.
+- Endpoint calls that time out throw `RequestTimeoutError`, not a raw `AbortError`, and
+  `forgetMemories()` throws a typed error, not a plain `Error`.
+- `searchMemory()` no longer sends `memory_type: 'episodic'`, `category: ''` and
+  `score_threshold: 0` when you leave them unset. They are omitted so the server applies no filter,
+  and a search without a type now covers all memory types. Pass `memory_type` explicitly to keep
+  the old episodic-only behavior.
+
+---
+
+## [1.0.0-rc.1] - 2026-10-28
+
+Release candidate for 1.0. The version is aligned with `10xgraph` and `10xgraph-api` 1.0, which
+ship as `1.0.0rc1` on PyPI; this package ships as `1.0.0-rc.1` on npm under the `next` tag, so
+`npm install 10xgraph-client` still installs 0.6.0 until 1.0.0 is released. The client itself has
+no breaking change in this release: the public API is the one listed under Added and Deprecated
+below, on top of 0.6.0.
+
+### Upgrading alongside 10xgraph-api 1.0
+
+`10xgraph-api` 1.0 defaults `runs.thread_ids` to `"server"`. The server now assigns thread ids,
+and a client that invents an id for a new thread gets HTTP 403 on `invoke()`, `stream()` and
+`wsStream()`. No client code change is needed if you already let the server choose:
+
+- On the first request of a conversation, omit `thread_id` from `config` (do not pass
+  `config: { thread_id: ... }`).
+- Read the id the server returns and reuse it in `config.thread_id` on every later request. For
+  `invoke()` it is `result.meta.thread_id` (`meta.is_new_thread` tells you it was just created).
+  For `stream()` it is `chunk.thread_id` or `chunk.metadata.thread_id` on the chunks. Over
+  `wsStream()` the client sends no id on the first request (logged as `thread_id=new`), tracks
+  the returned id itself and reuses it for its own resume requests; you still need to keep it
+  for your next `wsStream()` call.
+- Operators who want the old behavior set `"runs": {"thread_ids": "client"}` in `10xgraph.json`.
+
+Use the client with `10xgraph-api` of the same `major.minor` (see the README compatibility
+table).
+
+### Added
+
+- `on_busy?: 'wait' | 'cancel'` option on `invoke()`, `stream()` and `wsStream()`, sent as a
+  top-level request field (in the WebSocket input object next to `recursion_limit`). It tells
+  the server what to do when another run is active on the same thread: wait up to 30 s
+  (server default) or cancel the running run. Needs a `10xgraph-api` version that supports it.
+- `resume?: unknown` and `interrupt_id?: string` options on `invoke()`, `stream()` and
+  `wsStream()`. `interrupt_id` must be the id of the interrupt being answered. The client does
+  not track interrupt ids itself, so pass the id you got from the server. On `invoke()` and
+  `stream()` they are sent on the first request of a call only.
+- `ConflictError` (HTTP 409, `errorCode` `'CONFLICT'`), exported from the package root. The
+  server answers 409 when the thread stays busy or when `interrupt_id` does not match the
+  open interrupt. The client never retries it. Error bodies of the form `{"detail": "..."}`
+  (no envelope) now produce a typed error with that message instead of throwing a `TypeError`.
+- `deleteFile(fileId)` wraps the new `DELETE /v1/files/{file_id}` route (permission
+  `files:delete`, owner only). It resolves to `{ data: { file_id, deleted: true }, metadata }`.
+  The server returns 404 "File not found" when the file does not exist or belongs to someone
+  else. Types: `DeleteFileResponse`, `DeleteFileData`, `DeleteFileContext`.
+- `updateThreadMessageFeedback(threadId, messageId, feedback)` wraps the new
+  `PUT /v1/threads/{thread_id}/messages/{message_id}` route. It replaces
+  `message.metadata.feedback` with the given JSON object and changes nothing else on the
+  message. The server rejects feedback over 8192 serialized bytes or nested deeper than 10
+  levels (HTTP 422), returns 404 if the message is not in the thread and 501 if its core
+  library is too old. It returns the updated message in the same shape as `singleMessage`.
+  Types: `UpdateThreadMessageFeedbackRequest`, `UpdateThreadMessageFeedbackResponse`,
+  `UpdateThreadMessageFeedbackContext`.
+
+### Deprecated
+
+- `addThreadMessages` (`POST /v1/threads/{thread_id}/messages`) requires the
+  `checkpointer:import` scope (admin only) in 10xgraph-api releases after 0.9.0, so a normal user gets
+  403, and the server now rejects assistant and system role messages on normal client
+  paths. Use `updateThreadMessageFeedback` to attach feedback to a message. The method is
+  kept and still works for admin tokens.
+
+### Fixed
+
+- Client-side tool loop on `invoke()` and `stream()` lost a server-assigned thread id. When you
+  omitted `config.thread_id` on the first request, the requests that send tool results also
+  omitted it, so `10xgraph-api` 1.0 treated each one as a new thread and the tool round-trip
+  broke or the conversation split. The client now reuses the id the server returns
+  (`meta.thread_id` on `invoke()`; `thread_id` or `metadata.thread_id` on `stream()` chunks) for
+  the following requests of the same call. A `thread_id` you pass is never replaced, and your
+  `config` object is not modified.
 
 ---
 
@@ -269,6 +474,8 @@ Initial entry in this changelog. Releases before `0.2.0` were not tracked here.
 - Added the realtime audio client (`client.realtime(...)` returning `RealtimeSession`).
 - Added dual ESM/CJS exports.
 
+[Unreleased]: https://github.com/10xGraph/10xgraph-client/compare/v1.0.0-rc.1...HEAD
+[1.0.0-rc.1]: https://github.com/10xGraph/10xgraph-client/compare/v0.6.0...v1.0.0-rc.1
 [0.6.0]: https://github.com/10xGraph/10xgraph-client/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/10xHub/agentflow-client/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/10xHub/agentflow-client/compare/v0.3.0...v0.4.0

package/README.md

@@ -34,16 +34,18 @@ pnpm add 10xgraph-client
 
 ### Version compatibility
 
-The client versions independently of the Python packages. Pick versions by this table rather than
-by matching numbers:
+From 1.0, match `major.minor` across `10xgraph`, `10xgraph-api` and `10xgraph-client`; patch
+versions are independent (a patch is only a bug or security fix). Before 1.0, pick versions by
+this table:
 
 | `10xgraph-client` (npm)                | API server                                        | Core framework                 |
 | -------------------------------------- | ------------------------------------------------- | ------------------------------ |
+| 1.0.x                                  | `10xgraph-api` 1.0.x                              | `10xgraph` 1.0.x               |
 | 0.6.x                                  | `10xgraph-api` >= 0.7.0                           | `10xgraph` >= 0.10.0           |
 | `@10xscale/agentflow-client` 0.5.x     | `10xscale-agentflow-cli` >= 0.6.0, `10xgraph-api` | `10xscale-agentflow` >= 0.10.0 |
 | `@10xscale/agentflow-client` 0.3-0.4.x | `10xscale-agentflow-cli` >= 0.5.0                 | `10xscale-agentflow` >= 0.9.0  |
 
-The client tracks the **API server**, which is what it talks to. Client 0.6.x authenticates
+The client tracks the **API server**, which is what it talks to. Client 0.6.x and later authenticate
 WebSockets with the `10xgraph-bearer` subprotocol, which `10xgraph-api` 0.7.0 introduced. Against
 an older `10xscale-agentflow-cli` server, HTTP endpoints still work, but `wsStream()` and
 `realtime()` with bearer auth do not; stay on `@10xscale/agentflow-client@0.5.0` until the server
@@ -117,7 +119,7 @@ import { TenxGraphClient } from '10xgraph-client';
 const client = new TenxGraphClient({ baseUrl: 'http://localhost:8000', authToken });
 
 const session = client.realtime(
-  { model: 'gemini-2.5-flash-live', modalities: 'AUDIO' },
+  { model: 'gemini-3.8-live', modalities: 'AUDIO' },
   { reconnect: { maxAttempts: 5 } }
 );
 
@@ -226,6 +228,10 @@ const result = await client.invoke(messages, {
 });
 ```
 
+Optional: `on_busy: 'wait' | 'cancel'` controls what happens when the thread already has an active
+run, and `resume` with `interrupt_id` answers an open interrupt. A 409 throws `ConflictError`
+(not retried automatically).
+
 ### `stream()`: real-time streaming
 
 ```typescript
@@ -377,7 +383,7 @@ Your first pull request can be small. These are real, self-contained, and useful
 - **Sharpen a type or a doc comment.** If your editor's autocomplete misled you once, it will mislead the next person too.
 - **Turn a bug into a failing test.** Open it as a draft pull request; the fix can come later.
 
-From clone to a passing check (Node 18 or newer):
+From clone to a passing check (Node 20 or newer):
 
 ```bash
 git clone https://github.com/10xGraph/10xgraph-client.git

package/dist/agent.d.ts

@@ -1,16 +1,29 @@
 import { Message } from './message.js';
-interface ExecutionMeta {
+export interface ExecutionMeta {
     current_node: string;
     step: number;
+    /** Server execution status, e.g. 'running', 'interrupted_before', 'completed'. */
+    status?: string;
+    interrupted_node?: string | null;
+    interrupt_reason?: string | null;
+    interrupt_data?: Record<string, any> | null;
+    thread_id?: string | null;
+    run_id?: string | null;
+    stop_current_execution?: string;
+    internal_data?: Record<string, any>;
+    /** @deprecated The server never sends this field. Read `status` / `interrupted_node`. */
     interrupt?: {
         node: string;
         reason: string;
         status: string;
         data?: Record<string, any>;
     };
-    is_running: boolean;
-    is_interrupted: boolean;
-    is_stopped_requested: boolean;
+    /** @deprecated The server never sends this field. Read `status`. */
+    is_running?: boolean;
+    /** @deprecated The server never sends this field. Read `status`. */
+    is_interrupted?: boolean;
+    /** @deprecated The server never sends this field. Read `stop_current_execution`. */
+    is_stopped_requested?: boolean;
 }
 export declare class AgentState {
     context: Message[];
@@ -18,5 +31,4 @@ export declare class AgentState {
     execution_meta: ExecutionMeta;
     constructor(initialData?: Partial<Record<string, any>>);
 }
-export {};
 //# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,UAAU,aAAa;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC5B,CAAC;IACF,UAAU,EAAE,OAAO,CAAC;IACpB,cAAc,EAAE,OAAO,CAAC;IACxB,oBAAoB,EAAE,OAAO,CAAC;CAC/B;AAmBD,qBAAa,UAAU;IACrB,OAAO,EAAE,OAAO,EAAE,CAAM;IACxB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IACtC,cAAc,EAAE,aAAa,CAA8B;gBAE/C,WAAW,GAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;CAG3D"}
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAC5C,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IACpC,yFAAyF;IACzF,SAAS,CAAC,EAAE;QACV,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;KAC5B,CAAC;IACF,oEAAoE;IACpE,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,oEAAoE;IACpE,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,oFAAoF;IACpF,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAmBD,qBAAa,UAAU;IACrB,OAAO,EAAE,OAAO,EAAE,CAAM;IACxB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAQ;IACtC,cAAc,EAAE,aAAa,CAA8B;gBAE/C,WAAW,GAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAM;CAG3D"}

package/dist/cjs/agent.d.ts

@@ -0,0 +1,33 @@
+import { Message } from './message.js';
+export interface ExecutionMeta {
+    current_node: string;
+    step: number;
+    /** Server execution status, e.g. 'running', 'interrupted_before', 'completed'. */
+    status?: string;
+    interrupted_node?: string | null;
+    interrupt_reason?: string | null;
+    interrupt_data?: Record<string, any> | null;
+    thread_id?: string | null;
+    run_id?: string | null;
+    stop_current_execution?: string;
+    internal_data?: Record<string, any>;
+    /** @deprecated The server never sends this field. Read `status` / `interrupted_node`. */
+    interrupt?: {
+        node: string;
+        reason: string;
+        status: string;
+        data?: Record<string, any>;
+    };
+    /** @deprecated The server never sends this field. Read `status`. */
+    is_running?: boolean;
+    /** @deprecated The server never sends this field. Read `status`. */
+    is_interrupted?: boolean;
+    /** @deprecated The server never sends this field. Read `stop_current_execution`. */
+    is_stopped_requested?: boolean;
+}
+export declare class AgentState {
+    context: Message[];
+    context_summary: string | null;
+    execution_meta: ExecutionMeta;
+    constructor(initialData?: Partial<Record<string, any>>);
+}