Changelog

Release notes

Every published release of the framework, the API server and CLI, and the TypeScript client. Versions and dates match PyPI and npm. From 1.0 nothing public breaks before 2.0: see the stability and deprecation policy.

  1. Core framework

    v1.0.0

    Breaking changes

    The first stable release of the framework. The public API does not break before 2.0. Since rc7, Claude reasoning is readable by default and Gemini takes a base_url.

    The first stable release of 10xgraph. From 1.0 the public API does not break before 2.0, and anything removed is deprecated first: see Stability and deprecation policy.

    Terminal
    pip install -U 10xgraph 10xgraph-api

    Released with 10xgraph-api 1.0.0 and 10xgraph-client 1.0.0. Python 3.12 to 3.15. Coming from 0.10, read the upgrade guide: the breaking changes are listed in the release candidates below. Coming from 1.0.0rc7, nothing breaks.

    Added

    • base_url for the Google provider. Agent(provider="google", base_url=...) sets the base URL on the Gemini Developer API and Vertex AI clients, so Gemini calls can go through proxies, gateways such as LiteLLM, self-hosted endpoints or mock servers.

    Fixed

    • Claude reasoning is readable by default. Current Claude models default thinking.display to "omitted", so with reasoning_config=True (or unset) the reasoning block had an empty summary and only a signature. The default now sends display: "summarized"; thinking cost is unchanged. An explicit reasoning_config dict sends display only when it has a display key, and a thinking passed to the Agent is used as given.
    • A tool’s returned dict reaches the model unchanged. status, error, success and is_error were removed from a dict result before the model saw it; they are now only read to set is_error.
    • ReactAgent, StructuredOutputAgent and PlanActReflectAgent send reasoning parameters on Chat Completions only when reasoning_config is set, so non-reasoning models on vLLM, Ollama or Groq no longer answer 400.
    • InMemoryCheckpointer and SqliteCheckpointer report an existing thread as not new, so is_new_thread is correct and a thread name generator no longer renames the thread on every call.
    • A NUL character or lone surrogate no longer breaks a thread. In client input and caller state it is refused with a ValidationError (type invalid_character). In model and tool output it is cleaned, and a thread already stuck repairs itself on its next call.
    • CloudMediaStore recognises a missing object from the stdlib download fallback and deletes an owner’s index object with the owner’s last file.
  2. API server and CLI

    v1.0.0

    Breaking changes

    The first stable release of the API server and CLI. HTTP API, CLI and 10xgraph.json keys do not break before 2.0. Lists every change since rc6; there was no rc7.

    The first stable release of 10xgraph-api. From 1.0 the HTTP and WebSocket API, the CLI and the 10xgraph.json keys do not break before 2.0, and anything removed is deprecated first: see Stability and deprecation policy. The deprecated agentflow names keep working until 2.0.

    Terminal
    pip install -U 10xgraph 10xgraph-api

    Requires 10xgraph 1.0. There was no 1.0.0rc7 of this package, so these notes cover every change since 1.0.0rc6. Coming from 0.9, read the upgrade guide first.

    Breaking

    • thread_name_generator defaults to none. New threads are saved without a name. Set "random" to keep the old behaviour. The value must be none, random, first_message or module:attribute; AIThreadNameGenerator and DefaultThreadNameGenerator are replaced by RandomThreadNameGenerator.
    • runs.state_keys denies by default. Clients may set only the state keys it lists, in initial_state, PUT /v1/threads/{id}/state and AG-UI state; any other key is a 422. Migration: list every key your clients send, for example "runs": {"state_keys": ["preferences"]}.
    • BaseAuth.authenticate is async. Change def authenticate to async def authenticate in custom auth classes.
    • With cache_store.token_revocation on, every token needs a jti. A token without one answers 401 INVALID_TOKEN. Migration: issue tokens with a jti claim, or turn revocation off.

    Changed

    • MAX_NESTING_DEPTH setting (default 64, range 1 to 900) for client messages, initial_state, config, resume and filters.
    • The audit log has input and rate_limit events (422 and 413 refusals, 429 and limiter outages).
    • 10xgraph init writes >=1.0,<2.0 ranges, and the Full setup writes "thread_name_generator": "first_message". 10xgraph audit and 10xgraph config know the new values.

    Fixed

    • meta.is_new_thread is correct on a continued thread (with 10xgraph 1.0.0).
    • 10xgraph init Quick setup writes a requirements.txt, so 10xgraph build installs the provider SDK.
    • Auth errors are clean 401s. A missing tenant claim, a malformed roles or permissions claim, a reserved __system__ user id and a missing credential answer 401 INVALID_TOKEN. Expected 401s log one WARNING line.
    • Text the database refuses answers 422. A NUL character or lone surrogate in client input is refused before the run, and a StorageError from data Postgres refuses answers 422 INVALID_REQUEST_DATA instead of 500.
    • AG-UI refuses a client tool named like a server tool (422).
    • File uploads: the stored filename is cleaned, two file parts are refused, an upload without the media extra under extract_text answers 422, and GET /v1/files on a cloud store answers 501 for reach tenant or all.
    • MEDIA_STORAGE_TYPE=cloud imports from the right cloud-storage-manager modules.
    • 10xgraph dev falls back to agentflow.json again when 10xgraph.json is missing.
  3. TypeScript client

    v1.0.0

    Breaking changes

    The first stable release of the TypeScript client. Its exports do not break before 2.0. Server messages are real Message instances, and typed errors keep the server's error code.

    The first stable release of 10xgraph-client. From 1.0 everything exported from the package does not break before 2.0, and anything removed is deprecated first: see Stability and deprecation policy. The deprecated AgentFlow* aliases keep working until 2.0.

    Terminal
    npm install 10xgraph-client

    Node.js 20 or newer. Use it with 10xgraph-api 1.0. Coming from 0.6, read the upgrade guide. Coming from 1.0.0-rc.3, nothing breaks.

    Fixed

    • Server messages are real Message instances. result.messages.at(-1)?.text() threw “text is not a function” because responses were plain objects. Messages are now hydrated on invoke, stream and WebSocket chunks, threadMessages, singleMessage, threadState and updateThreadState. Every field the server sent is kept. New exports: hydrateMessage, hydrateStateContext, hydrateChunk.
    • Typed HTTP errors keep the server’s error code. errorCode on AuthenticationError, NotFoundError and the other HTTP errors now carries what the server sent (EXPIRED_TOKEN, INVALID_TOKEN, REVOKED_TOKEN, THREAD_NOT_FOUND, …), so an app can refresh on an expired token and log out on a revoked one. Without a code in the body, the class default is used as before.
  4. Core framework

    v1.0.0rc7

    Breaking changes

    The seventh 1.0 release candidate. The model can forget a memory by key, tracing produces one trace per run with standard span names, and multi-agent graphs on Claude no longer fail on thinking blocks.

    The seventh 1.0 release candidate. The model can forget a memory by key, tracing produces one trace per run with standard span names, Anthropic errors at stream open are retried, and multi-agent graphs on Claude no longer fail on thinking blocks. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc7"

    Use it with 10xgraph-api 1.0.0rc6 (there is no API rc7) and 10xgraph-client 1.0.0-rc.3.

    Changed

    • Tracing: one trace per run, with standard span names. Spans follow the OTEL GenAI conventions: the run is invoke_agent 10xgraph (was tenxgraph.graph), an LLM call chat {model} (was tenxgraph.llm), a tool call execute_tool {tool} (was tenxgraph.tool), and a node span carries the node’s name (was tenxgraph.node). A tool span is a child of the node that ran it, and spans from the provider SDK, fastmcp and mcp nest under the run. Migration: update dashboards and filters that match the old span names.
    • Failed LLM, tool and MCP events carry the exception (error_type, error_message, error_traceback), with secrets masked. The message and traceback go to observability publishers only; event streams get the error type.
    • Memory types are strict. An unknown memory_type is an error instead of silently episodic, in the model-facing tools and in UserMemoryConfig / AgentMemoryConfig.
    • Memory search no longer filters by the scope’s memory_type and category unless the model passes them, so a memory saved under another type or category is found. Preload mode follows the same rule and can now remember and forget.

    Added

    • forget and memory_key on user_memory_tool. forget deletes the memories saved under a key, and remember with a key replaces the earlier memory under it.
    • A warning for an unsupported retrieval strategy. PgVectorStore and QdrantStore declare which strategies they can run, and one warning is logged when a memory config asks for another.

    Fixed

    • Multi-agent graphs on Claude no longer fail with Invalid signature in thinking block. Each Agent node replays signed thinking only from its own replies; replies from other agent nodes keep their text and tool calls.
    • Anthropic errors at stream open are retried, and the stream is closed when the consumer stops early.
    • The Anthropic SDK no longer adds a second span for every request.
    • Error logs name the error when it has no message, for example TimeoutError() from a pool acquire.
  5. Core framework

    v1.0.0rc6

    Breaking changes

    The sixth 1.0 release candidate. Tools and MCP servers can call services as the signed-in user, tool ledger rows are cleaned after each run, and @tool takes the function name as the tool name.

    The sixth 1.0 release candidate. Tools and MCP servers can call services as the signed-in user, the tool results ledger is cleaned up after each completed run, and @tool takes the function name as the tool name. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc6"

    10xgraph-api 1.0.0rc6 and 10xgraph-client 1.0.0-rc.3 ship alongside it. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • @tool no longer takes name. A tool’s name is its Python function name. The old name= showed a different name to the model, but ToolNode routed calls by __name__, so calls to the renamed tool were never routed. @tool(name=...) and @tool("name") now fail. Migration: rename the function instead. get_tool_metadata() no longer returns a name key. The scoped factory tools (create_file_tools, create_fetch_url, create_google_web_search, create_vertex_ai_search) now have function names equal to their tool names.
    • The mcp extra needs fastmcp 4.1.7 and mcp 2.3 or later (was fastmcp 2.11.3 and mcp 1.30). Per-call MCP auth depends on mcp 2.x sending each request with the caller’s context. ToolNode itself still runs on fastmcp 3.x; only mcp_auth= refuses it.

    Added

    • Calling services as the user. UserCredential (tenxgraph.core.authz) holds the caller’s raw credential in config["credential"]: token: SecretStr and scheme (default "Bearer"). Its repr is redacted, json.dumps and pickling raise, and copies return the same object. get_credential(config) reads it and public_config(config) returns the config without it.
    • Local tools get the credential by name. A tool parameter named credential receives the UserCredential (or None), whatever its annotation, and is hidden from the model. An annotation other than UserCredential or UserCredential | None logs one warning when the tool is registered. Before and after-invoke callbacks never see it in their input data.
    • ToolNode(mcp_auth=...): per-call MCP headers. An async (MCPAuthContext) -> dict[str, str] runs before every MCP tool listing and tool call with the run’s identity, credential, tool_name (None for listing), server, thread_id and run_id. Its headers go on that request only, so one shared client serves many users without mixing their headers. forward_credential forwards the caller’s own token, only for a server that accepts that same token. It needs fastmcp 4; stdio and in-memory transports are refused. ReactAgent, PlanActReflectAgent, StructuredOutputAgent and AudioAgent pass mcp_auth through. The MCP tool list stays cached per node and shared by all users, so it must not depend on the user.
    • Tool ledger cleanup and opt-out. After a run completes, its tool ledger rows are deleted in the background (aclear_tool_results(config, origin_message_ids)). Only rows from the run’s own tool-calling messages go, so a newer run on the thread keeps its rows. Paused, stopped, failed and cancelled runs keep them. aprune_tool_results(older_than) deletes old rows of every thread; the library never calls it, so schedule it from a worker. On Postgres with row_level_security=True, a role that does not bypass RLS deletes nothing and a warning is logged. @tool(record_tool_result=False) turns the ledger off for one tool, and the record_tool_result=False kwarg of InMemoryCheckpointer, SqliteCheckpointer and PgCheckpointer turns it off for all of them (the checkpointer setting wins). PgCheckpointer schema v7 adds an index on tool_executions(created_at), built concurrently on an existing table. SQLite adds a created_at column to af_tool_executions.
    • ToolResultBlock.name: the tool that produced the result. ToolNode sets it on every result; it is None on results saved before. The provider wire format is unchanged.
    • Eval run config. ConversationScenario.config is merged into the run config of the simulated conversation (an explicit config passed to run wins), so tools that read config["user"] work in simulations. EvalSetBuilder.add_case, add_multi_turn and add_tool_test take session_input=.

    Changed

    • extra_messages are filled from the state. {field} in the text of an Agent’s extra_messages is filled from the agent state, the same way the system prompt is. They are sent after the history and never saved to state.context, so changing context at the end of the prompt keeps the cached prefix stable. A field that is not in the state stays as written. Existing extra_messages that contain {{, }} or {identifier} text are now formatted: use {{ and }} for literal braces.
    • System prompt fill is partial. A missing state field used to send the whole prompt unfilled. Now only that placeholder stays as written and the others are filled.
    • Tracing defaults to ObservabilityLevel.FULL. The OTEL, Phoenix, Logfire and LangSmith publishers and the exporter config ("level" unset) now send message content and graph state to the trace backend by default (was STANDARD). Set level=ObservabilityLevel.STANDARD (or "level": "standard") or SPANS to keep content out of traces.

    Fixed

    • The run config no longer leaves the run whole. The graph start event (metadata["config"]), GraphLifecycleContext.config and the config in AI, tool and MCP CallbackContext.metadata now carry public_config(config), so the credential never reaches publishers, OTEL, Phoenix or LangSmith spans, or callbacks that ship their context.
    • RabbitMQPublisher no longer retries forever or hangs shutdown. It uses a plain aio_pika.connect instead of connect_robust, whose reconnect task retried every 5 seconds forever and could keep the process from exiting. Refused credentials are logged once and later events are dropped without contacting the broker. After a network failure the next attempt waits reconnect_interval seconds (new config key, default 5), and a connection the broker closed is opened again by the next publish. close() no longer waits for a connection attempt in progress, and gives the broker at most connection_timeout seconds to confirm the close.
    • pass_user_info_to_mcp sends the full caller behind the API. An Identity (any pydantic model) is now sent as its JSON dump in meta={"user": ...}: user_id, kind, tenant, roles, permissions, reach and the token claims. Before, an MCP server received only {"user_id": ...}. A dict is still sent as is.
    • ToolNode works with fastmcp 4.x. It no longer pings the MCP server before listing tools or calling one. fastmcp 4.x negotiates MCP protocol 2026-07-28, which has no ping method, so every MCP call failed with “MCP Server not available. Ping failed.” A server that is down now fails the listing or the call as before, without the extra round trip.
  6. API server and CLI

    v1.0.0rc6

    Breaking changes

    The sixth 1.0 release candidate. Tools and MCP servers can call services as the signed-in user, and 10xgraph build generates the job worker and scheduler. Tracing now defaults to full and WebSocket ?token= is gone.

    The sixth 1.0 release candidate. Tools and MCP servers can call services as the signed-in user, and 10xgraph build generates the background job worker and scheduler. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph-api==1.0.0rc6"

    It requires 10xgraph 1.0.0rc6 and ships with 10xgraph-client 1.0.0-rc.3. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • Tracing defaults to full. OTEL_LEVEL, observability.level in 10xgraph.json and the fallback for an invalid value are now full (was standard), so message content and graph state reach the trace backend by default, also in production (the production warning for full is gone). Migration: set OTEL_LEVEL=standard or "level": "standard" (or spans) to keep content out. When the graph already has its own observability publisher (Phoenix, LangSmith, Logfire, OTel), the observability block is not applied, its level included, and a warning says so.
    • WebSocket routes no longer accept ?token=. /v1/graph/ws and /v1/graph/live take the bearer from the Authorization header or the 10xgraph-bearer subprotocol only. A token in the URL ended up in access logs, proxy logs and HTTP trace spans. Migration: 10xgraph-client already uses the subprotocol; other clients that put the token in the URL must switch.
    • BaseAuth.downstream_credential is async, so an override can call an identity provider. Migration: declare your override with async def and await it where you call it.

    Added

    • Tools can call services as the signed-in user. After a request authenticates, the API puts the caller’s credential into the run config as config["credential"] (a core UserCredential: redacted repr, refuses JSON and pickling) for invoke and stream (resume included), /v1/graph/ws, /v1/graph/live and AG-UI. A tool reads it through a parameter named credential, and ToolNode(mcp_auth=...) sees it. Needs 10xgraph 1.0.0rc6 or later.
    • New hook BaseAuth.downstream_credential(connection, credential, claims). The default returns the bearer token the request carried (header, or on a WebSocket the 10xgraph-bearer subprotocol). Override it when authenticate verifies a cookie or an API key, or return None for no credential. authenticate() is unchanged.
    • credential is a reserved config key: a client value is dropped, and runs.config_keys cannot admit it. It is never put in the identity, claims, audit events, logs, thread naming, stop or fix, and never in background tasks (/v1/tasks payloads, task status and results carry user data only).
    • 10xgraph build generates the background-job processes. With a non-memory worker key in 10xgraph.json, docker-compose.yml gets worker and scheduler services and k8s.yaml gets <service>-worker and <service>-scheduler Deployments (the scheduler has one replica and strategy: Recreate). At a terminal build asks where you deploy, whether to run the worker and the scheduler, and whether to overwrite. The flags --worker/--no-worker and --scheduler/--no-scheduler answer them. It warns when the jobs extra for the broker is missing.
    • 10xgraph skills adds always-on project instructions. The Claude target also writes a 10xGraph section into the project-root CLAUDE.md, and the Codex target into AGENTS.md. The section tells the agent, and every subagent it starts, to load the skill first, and sets the default shape (prebuilt ReactAgent, one agent, business rules in tools, MCP identity through request metadata). It sits between <!-- 10xgraph:start --> and <!-- 10xgraph:end -->; text outside the markers is never changed, an existing file does not need --force, symlinked files are refused, and the file is written atomically.

    Changed

    • 10xgraph init checks for existing files before writing. It used to fail on the first existing file and leave a partial scaffold. Now it asks once before overwriting (default No; No writes nothing), or without a terminal stops before any write and lists the files. --force skips the question; --dry-run marks existing files.
    • Bundled skill: smaller apps by default. The skill and the Copilot instructions describe 10xGraph as infrastructure for production AI agents (multi-agent is one feature), list prebuilt agents before hand-written StateGraph loops, add a “Default shape” section, and show how an MCP server reads the signed-in user from ctx.request_context.meta["user"]. New example: a support agent over MCP with ReactAgent.
    • Bundled skill: tool names and the tool results ledger. The skill and docs say a tool’s name is its function name (@tool no longer takes name, a breaking change in 10xgraph), and describe record_tool_result and the checkpointer’s tool results ledger.
    • Refresh a project’s copy of the skill with 10xgraph skills --agent claude --force (or --all --force).

    Fixed

    • Boot in 10xgraph build images with a worker key. The tasks router no longer imports the CLI (typer, rich), which the slim image removes. The server and jobs import without them.
    • No control-socket error on a read-only root. The generated gunicorn commands pass --no-control-socket, and the Dockerfile installs gunicorn>=25.1,<27 (the flag is new in 25.1).
    • An input validator rejection is a 422, not a 500. /v1/graph/invoke answers 422 VALIDATION_ERROR; stream and WebSocket send an error chunk with that code. Logged at WARNING.
    • A missing bearer token answers INVALID_TOKEN, not REVOKED_TOKEN.
  7. TypeScript client

    v1.0.0-rc.3

    Breaking changes

    The third 1.0 release candidate, under the next dist-tag. Adds me(), background task methods, filters on threads and memory, ToolResultBlock.name, and removes addThreadMessages.

    The third 1.0 release candidate of 10xgraph-client, published to npm under the next dist-tag:

    Terminal
    npm install 10xgraph-client@next

    Use it with 10xgraph-api 1.0.0rc6, which ships alongside 10xgraph 1.0.0rc6. New response fields are typed optional, so the client still works against older servers. A ToolResultBlock.name sent to an older server is ignored there. See the upgrade guide.

    Added

    • ToolResultBlock.name?: string: the name of the tool that produced the result. The server sets it on results from 10xgraph 1.0.0rc6 or later; older results have none. Results the client builds for client-side tools (ToolExecutor: success, thrown error, unknown tool, rejected arguments, duplicate call id) set it too.
    • me() for GET /v1/me: who the caller is and what they may do. data is { user_id, tenant, roles, permissions, reach } (reach is own, tenant or all; permissions is ['*'] for an unrestricted identity) or { auth: 'off' } when the server runs without auth. New exported types and helper: MeResponse, MeData, MeIdentity, MeAuthOff, MeReach, isAuthOff. Needs a 10xgraph-api with RBAC.
    • Background task methods for the /v1/tasks routes: runTask(name, { args, kwargs }), scheduleTask(name, { args, kwargs, schedule }), getTask(id), rescheduleTask(scheduleId, schedule) and cancelTask(id). schedule is exactly one of { cron }, { at } or { every } (seconds). The client does not validate it; the server answers 422. New exported types: TaskStatus, TaskSchedule, TaskRecord, ScheduleRecord, TaskCallOptions, RunTaskResponse, ScheduleTaskRequest, ScheduleTaskResponse, GetTaskResponse, RescheduleTaskResponse, CancelTaskResponse. Needs a 10xgraph-api with background tasks.
    • Filter support. threads() takes filters (sent as a JSON filters query parameter). searchMemory(), listMemories() and forgetMemories() take filters in the request body. A filter is { column: value } (equality) or { column: { op: value } } with the operators eq, ne, in, nin, like, ilike, is_null, gt, gte, lt, lte. New exported types: Filters, FilterCondition, FilterOperator, FilterScalar. The client does not validate columns; the server answers 422. Needs a 10xgraph-api with filter support.

    Changed

    • forgetMemories() now throws a TenxGraphError subclass on a failed request (ValidationError for 422, with the server message) instead of a plain Error. When the response has no JSON error body the message is still Forget memories failed: <status> <statusText>.

    Removed

    • addThreadMessages and its AddThreadMessages* types. The POST /v1/threads/{thread_id}/messages route was removed from 10xgraph-api, so the method had nothing to call. Migration: send messages through invoke or stream, and use updateThreadMessageFeedback for feedback.
  8. Core framework

    v1.0.0rc5

    Breaking changes

    The fifth 1.0 release candidate. Adds tenant isolation in storage, identity with reach, pgvector long-term memory, Phoenix and OTLP tracing, and SOC 2 and ISO 27001 control mapping.

    The fifth 1.0 release candidate. 10xGraph is open-source, self-hosted infrastructure for AI applications, and this release adds the core pieces for multi-tenant applications. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc5"

    10xgraph-api 1.0.0rc5 ships alongside it. The changelog for this release lists highlights only. Breaking changes since rc4 and the upgrade steps are in the upgrade guide.

    Highlights

    • Tenant isolation in storage. Declare tenant_columns (and data extra_columns) on PgCheckpointer and PgVectorStore. Values come only from the verified identity and filter every query. Native Postgres row-level security is opt-in with row_level_security=True. compile() checks that the checkpointer and the store declare the same tenant columns.
    • Identity with reach. The caller is an Identity in config["user"] with reach own, tenant or all. Reads widen with reach, writes always stay with the owner, and a thread outside the caller’s reach raises ThreadNotFoundError (404 in the API). This replaces the config["authz"] block.
    • Long-term memory in the same Postgres. PgVectorStore (extra pgvector) offers similarity, full-text and hybrid search, and safe filters on declared columns. Mem0Store is removed.
    • Tracing. A Phoenix publisher (OpenInference attributes) and OTLP export, next to OpenTelemetry, Logfire and LangSmith (extras phoenix, otlp, observability).
    • Built for teams going through SOC 2 and ISO 27001 audits. Together with 10xgraph-api (roles, tenant isolation, audit log, JSON logs), see the control mapping.
  9. API server and CLI

    v1.0.0rc5

    Breaking changes

    The fifth 1.0 release candidate. Roles with reach, tenant isolation, background jobs on TaskIQ, an audit log, JSON logs and Prometheus metrics make the API server ready for multi-tenant applications.

    The fifth 1.0 release candidate. 10xGraph is open-source, self-hosted infrastructure for AI applications, and this release makes the API server ready for multi-tenant applications. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph-api==1.0.0rc5"

    It requires 10xgraph 1.0.0rc5. Breaking changes since rc4 and the upgrade steps are in the upgrade guide.

    Breaking

    • The authorization key is removed. Authorization now lives in the single auth object (see Highlights below). Top-level authorization refuses to boot.

    Highlights

    • Roles with reach. One auth object: method (none, jwt, custom), roles with permissions and a reach of own, tenant or all, default_role and tenant_claims. Reads, lists, deletes and stop widen with reach; runs and writes stay with the owner. A thread, message, memory, file or run outside the caller’s reach answers 404.
    • Tenant isolation. tenant_claims must match the tenant columns declared on the checkpointer and the store (refused in production on a mismatch), and files are tenant-scoped.
    • Background jobs on TaskIQ. from tenxgraph_api.jobs import broker, 10xgraph worker, 10xgraph scheduler and the /v1/tasks routes. Jobs run as the caller and check tasks:trigger.
    • Audit log and JSON logs. A metadata-only audit log (audit key; sinks log, publisher or your own BaseAuditSink) and LOG_FORMAT=json. The production template turns the audit log on, and 10xgraph build sets LOG_FORMAT=json.
    • Prometheus metrics for the API and the job worker through the metrics block, by scrape or OTLP push.
    • Built for teams going through SOC 2 and ISO 27001 audits. See the control mapping.
  10. Core framework

    v1.0.0rc4

    Breaking changes

    The fourth 1.0 release candidate. Every checkpointer now implements aping(), a read-only connectivity check the API server uses for startup and readiness. Breaking for custom checkpointers.

    The fourth 1.0 release candidate. It is the 1.0.0rc3 code plus a required connectivity check on checkpointers. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc4"

    10xgraph-api 1.0.0rc4 ships alongside and requires it. 10xgraph-client stays at 1.0.0-rc.2. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • BaseCheckpointer.aping() is now abstract. A custom checkpointer must implement async def aping(self) -> None: return when its backends are reachable and usable, and raise when they are not. An in-process checkpointer just returns. Keep it read-only and cheap, because the API server calls it on every readiness probe and at startup. Migration: add the method to every custom BaseCheckpointer subclass. Without it the class raises TypeError when created.

    Added

    • InMemoryCheckpointer.aping(), SqliteCheckpointer.aping() (a SELECT 1) and PgCheckpointer.aping(). The Postgres version runs SELECT 1, raises RuntimeError when the recorded schema version is older than the code expects (the message names both), and pings its Redis cache directly, so an outage is reported and the Redis circuit breaker is left unchanged. It never creates the schema: the server runs asetup() at boot.
  11. API server and CLI

    v1.0.0rc4

    Breaking changes

    The fourth 1.0 release candidate. One cache_store object configures the BaseCacheStore behind locks, rate limiting and token revocation, and 10xgraph init asks only three questions. Breaking changes included.

    The fourth 1.0 release candidate. It is the 1.0.0rc3 code plus the changes below. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph-api==1.0.0rc4"

    It requires 10xgraph 1.0.0rc4 (checkpointers have aping()). 10xgraph-client stays at 1.0.0-rc.2. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • BaseCacheStore replaces three extension points. Removed with no aliases: ConcurrencyLimiter; TokenRevocationBackend (and its in-memory and Redis variants, and build_token_revocation); BaseRateLimitBackend, MemoryRateLimitBackend and RedisRateLimitBackend. Migration: implement BaseCacheStore if you wrote your own, and select it with "cache_store": {"type": "custom", "path": "module:attr"}.
    • cache_store is one object. It holds the store and what it backs: {"type": "memory" | "redis" | "custom", "url": "${REDIS_URL}", "path": "module:attr", "rate_limit": {...}, "token_revocation": true}. url goes with type redis (optional: empty reads the REDIS_URL environment variable; $VAR and ${VAR} are expanded) and path with type custom. No cache_store, or no type, is the in-memory store. Unknown keys are config errors that list the valid ones.
    • Top-level redis, rate_limit and token_revocation keys are config errors. The error says where each setting goes: inside cache_store. rate_limit inside cache_store has no backend or redis key, and token_revocation is true, false, null or {"enabled", "token_lifetime", "user_ttl"}; the strings "redis", "memory" and "module:attr" are config errors. Migration: see the mapping table in the upgrade guide.
    • REDIS_URL no longer selects the cache store. Write "cache_store": {"type": "redis"}; with no url it reads REDIS_URL. Type redis without the redis package refuses to boot with pip install "10xgraph-api[redis]".
    • /health/ready reports cache, not redis. The keys are checkpointer, store and cache. Migration: update monitors that read checks.redis.
    • Rate-limit counters reset once. The Redis keys moved to the 10xgraph:ratelimit2 namespace. Other Redis key layouts are unchanged, so old and new pods share locks during a rolling deploy.
    • 10xgraph init asks only the agent name, template and AI provider. Production writes the recommended setup: "auth": "jwt", "authorization": "ownership", "id_generator": "uuid" and "cache_store": {"type": "redis", "rate_limit": {...}, "token_revocation": true} (100 requests per 60 seconds by user, fail_open false; no url, so Redis reads REDIS_URL). WebSocket and AG-UI are off. Quick Start writes no cache_store. The flags --auth, --cache-store memory|redis, --rate-limit/--no-rate-limit, --token-revocation/--no-token-revocation and --websocket override parts of it for scripts.
    • thread_name_generator takes random (the default), first_message, none or module:attr. With the key unset, new threads are now named (randomly) and the name is saved; before, the default name was generated and dropped. Names are built from the user’s messages first, then the replies.

    Added

    • BaseCacheStore, RedisCacheStore (also Valkey, Dragonfly and KeyDB) and InMemoryCacheStore, importable from tenxgraph_api. One class holds the per-thread run lock, runs.max_concurrent_per_user, WebSocket caps, idempotency, the ownership cache (L2), token revocation and rate limiting. See Bring your own backend.
    • One INFO line at boot names the store and the config key it came from, for example Cache store: RedisCacheStore (cache_store.url, localhost:6379).
    • tenxgraph_api.testing.cache_store_contract: a CacheStoreContract pytest mixin and run_cache_store_contract(factory) that check an implementation against the contract.
    • id_generator in 10xgraph.json: uuid, hex, short, int, bigint, timestamp, snowflake (needs the snowflakekit extra and the SNOWFLAKE_* variables) or module:attr. New thread, message and memory ids all come from it. Boot refuses when the graph is also compiled with its own generator, and when a PgCheckpointer id_type cannot hold the ids.
    • thread_name_generator: "first_message": the user’s first message, whitespace collapsed, cut to at most 60 characters on a word boundary.
    • 10xgraph config edits token revocation as a section with enabled, token_lifetime and user_ttl, and has a Cache store page with type cards and Rate limiting and Token revocation tabs.
    • A warning at boot when token revocation uses an in-memory cache store in production or with WEB_CONCURRENCY above 1.

    Changed

    • The startup check and /health/ready only call aping(). The cache store stops the boot only when a fail-closed feature uses it: cache_store.token_revocation is on (with auth), or cache_store.rate_limit is on with fail_open set to false. Otherwise an unreachable cache store logs one warning and the server starts, and /health/ready reports cache: fail with status 200. Startup errors name each component’s class, the config key of the cache store and its endpoint, never credentials.
    • Failure behaviour is explicit: run locks, caps, idempotency and the ownership cache fail open; token revocation fails closed (503); rate limiting follows cache_store.rate_limit.fail_open.
    • 10xgraph revoke writes to the cache store cache_store selects (--redis-url still overrides) and refuses with a clear error when it is the in-memory store.
    • InMemoryCacheStore caps its memory at 50,000 slot keys and 10,000 plain values and evicts the least recently used entry, except live lease and revocation keys. It keeps expiries on the monotonic clock, so a wall clock jump does not expire a held thread lock early.
    • Shutdown closes the cache store once, after the graph and after pending lease releases.

    Fixed

    • A leftover REDIS_URL no longer stops the server from booting when nothing you configured needs Redis. In rc3 a setup with an in-memory checkpointer and an in-memory rate limiter refused to start because of it.
    • A rate-limit denial stays a 429 when reading the cache store clock for Retry-After fails.
    • revoke_user stores the cutoff rounded up to the microsecond, so a token issued at the cutoff itself is always revoked.
  12. Core framework

    v1.0.0rc3

    Breaking changes

    The third 1.0 release candidate. Every memory store now implements aping(), a connectivity check the API server uses for readiness and startup. Breaking for custom stores.

    The third 1.0 release candidate. It is the 1.0.0rc2 code plus a required connectivity check on memory stores. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc3"

    10xgraph-api 1.0.0rc3 ships alongside it. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • BaseStore.aping() is now abstract. A custom store must implement async def aping(self) -> None: return when its backend is reachable and raise when it is not. An in-process store just returns. 10xgraph-api calls it for /health/ready and at startup. Migration: add the method to every custom BaseStore subclass. Without it the class raises TypeError when created.

    Added

    • QdrantStore.aping(), Mem0Store.aping() and InMemoryStore.aping() check that the store’s backend is reachable. 10xgraph-api uses them for /health/ready and its startup check.
  13. Core framework

    v1.0.0rc2

    Breaking changes

    The second 1.0 release candidate. Lowest-effort default reasoning, OpenAI Responses by default, no default tool or node timeouts, typed tool arguments, and fixes for handoffs, streaming, shutdown and eval. Breaking changes included.

    The second 1.0 release candidate. It is the 1.0.0rc1 code plus the changes below. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc2"

    10xgraph-api 1.0.0rc2 and 10xgraph-client 1.0.0-rc.2 ship alongside. If you upgrade from 0.10.x, the rc1 breaking list applies to you as well. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • Default reasoning is each provider’s lowest effort. reasoning_config left unset or set to True used to mean {"effort": "medium"} (Google thinking_budget=8192). It now resolves per request to OpenAI "minimal", Anthropic "low" and Google "low" (thinking_budget=512), from DEFAULT_REASONING_EFFORT_BY_PROVIDER. Migration: pass {"effort": "medium"} to keep the old depth. None or False still turns reasoning off.
    • OpenAI Responses requests a reasoning summary by default. With reasoning on and no summary set, the request sends summary: "auto". If the reasoning came from the default and the model answers 400 naming the reasoning parameter (for example gpt-4o), the call is retried once without it. An explicit reasoning_config dict is never dropped.
    • A custom base_url switches to Chat Completions only when Responses is missing. Only 404, 405 and 501 switch it; other errors, such as a 429 or a timeout, are raised.
    • Agent uses the OpenAI Responses API by default. api_style defaults to "responses" (it was "chat"), except when base_url is set and api_style is not passed. Migration: pass api_style="chat" to keep the old behaviour. The openai extra is now openai>=1.93.1,<4; on openai 3.x an http_client in llm_kwargs must be an httpx2.AsyncClient.
    • Tool and node timeouts are off by default. DEFAULT_TOOL_TIMEOUT_SECONDS and DEFAULT_NODE_TIMEOUT_SECONDS are now None (they were 300 s and 900 s). Migration: set tool_timeout or node_timeout in the run config; a value you set now applies to both invoke and stream.
    • Tool arguments are checked against the types the tool declares. A value that converts cleanly is converted; one that cannot (a list for an int) gets a failed tool result.
    • Published events are snapshots. Each event is copied before it is queued, so Kafka, Redis, RabbitMQ and OTEL consumers see the values at the moment of the event.
    • pass_user_info_to_mcp=True sends the user info as request metadata (meta, {"user": {...}}), not as a user tool argument. A server that read user from the arguments must read it from the meta.
    • LiveAgent.arun() raises RuntimeError when the instance already runs a session. Migration: give each concurrent session its own LiveAgent.new_session().
    • A stop request is saved as StopRequestStatus.STOPPED. Code that checks for STOP_REQUESTED after a stop must also accept STOPPED.
    • Sync invoke(), stream(), stop() and sync checkpointer methods raise RuntimeError inside a running event loop. Migration: call ainvoke, astream, astop or aget_state.
    • Message.reasoning is removed. Migration: read the ReasoningBlocks (type == "reasoning") in Message.content. The Postgres messages.reasoning column is dropped (schema version 5): stop old pods, migrate, then start new ones.
    • mem0ai is bounded to >=2.0,<3. Other extras raise their floors: Pillow>=13.0.0, mcp>=1.30.0, opentelemetry-api and opentelemetry-sdk >=1.45.1.

    Added

    • await graph.aclose(grace, stop_timeout, timeout): graceful shutdown in phases, with GraphClosedError for new runs, the opt-in install_shutdown_signals, and compile(owns_resources=...).
    • User simulator progress events through on_event on UserSimulator.run and BatchSimulator.run_batch.
    • ToolNode options max_result_chars, mcp_include, mcp_exclude, mcp_prefix, mcp_max_result_chars, mcp_max_description_chars and mcp_connect_timeout, plus refresh_mcp_tools(). MCP tool lists are cached per ToolNode.
    • create_fetch_url, create_google_web_search and create_vertex_ai_search: tool factories that fix hosts, model or datastore in code.
    • RetryConfig.jitter, max_concurrent_calls and the opt-in cross-process cap distributed_max_concurrent_calls.
    • PgCheckpointer redis_key_prefix, safe default timeouts, aclear_state_cache, and aput_cache_value_if_absent on the checkpointers.
    • compile(node_aliases=...), StoredNodeMissingError, StateFormatVersionError, NothingToResumeError and InterruptPendingError.
    • GoogleEmbedding(document_task_type=..., query_task_type=...) and BaseEmbedding.aembed_query.
    • A redesigned self-contained HTML eval report (scorecard).

    Changed

    • PgCheckpointer skips Redis for a cool-down after a connection failure: new kwarg redis_breaker_cooldown (seconds, default 5.0, 0 disables).
    • GoogleEmbedding sends RETRIEVAL_DOCUMENT when storing and RETRIEVAL_QUERY when searching; set the task types to None to send none.
    • Large data["state"] in published events is replaced by a summary above state_snapshot_limit (default 65536).
    • Realtime tool calls run once per thread, and a cancelled, crashed or shut-down run leaves a usable thread.
    • Anthropic thinking blocks are stored with their signature and replayed unchanged.

    Fixed

    • Multi-agent handoffs no longer leave an unanswered tool call: SwarmAgent gets a <NAME>_HANDOFF node, and the handoff result tells the receiving agent it is in charge.
    • Streaming: each item gets its own chunk, so clients see the deltas instead of the final message repeated.
    • PlanActReflectAgent shows the planner’s reply, not the reflector’s review (reflector messages carry metadata["internal"] = True).
    • Cancel and shutdown edge cases: aclose() waits for late cancel saves and run-marker releases (reported as cleanup_tasks), and a late save cannot overwrite the final one.
    • Eval: a failing LLM judge reports an error with the real message instead of a 0.5 score.
    • A Redis outage no longer slows every run step.
  14. API server and CLI

    v1.0.0rc3

    The third 1.0 release candidate. The server refuses to start while a configured backend is unreachable, a rate-limiter outage answers 503, and the hosted playground can reach a local dev server.

    The third 1.0 release candidate. It is the 1.0.0rc2 code plus the changes below. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph-api==1.0.0rc3"

    It requires 10xgraph 1.0.0rc3 (stores have aping()). 10xgraph-client stays at 1.0.0-rc.2. See the upgrade guide for the move to 1.0.

    Added

    • Startup checks. The server refuses to start while a configured backend is unreachable: the checkpointer’s Postgres (query and schema version) and Redis, the store (when it has aping or ping), the API’s Redis (redis in 10xgraph.json or REDIS_URL) and the rate limiter’s own Redis.
    • It retries with a short backoff for STARTUP_CHECK_TIMEOUT_SECONDS (default 30), so services started together can come up in any order. Then it exits non-zero with each failed component, its host:port (no credentials) and the error.
    • This applies in production too, so a broken connection string fails the deploy instead of the first request. STARTUP_CHECKS=false skips it.
    • Before, the server started anyway and, with a fail-closed Redis rate limiter, answered every request except /ping with 429.

    Changed

    • A rate-limiter backend outage with fail_open: false answers 503 with error code RATE_LIMIT_UNAVAILABLE and Retry-After: 5, instead of 429 RATE_LIMIT_EXCEEDED. 429 is kept for a real limit hit. Clients that retried on 429 should now retry on 503 too.
    • A custom backend can signal the same with RateLimitDecision.backend_unavailable(). Backends that return only allow or deny work unchanged.
    • The Redis backend logs a traceback for the first error of an outage and one line per error after it, instead of a traceback per request.

    Fixed

    • The hosted playground can reach a local 10xgraph dev server: CORS answers the browser’s private-network preflight (Access-Control-Request-Private-Network) for origins in ORIGINS. Before, it answered 400 and the browser reported a CORS error.
  15. API server and CLI

    v1.0.0rc2

    Breaking changes

    The second 1.0 release candidate. Stricter ids, resume and write conflicts as 409, a JWT algorithm allowlist, shutdown settings, Redis and media limits, and a run trace. Breaking changes included.

    The second 1.0 release candidate. It is the 1.0.0rc1 code plus the changes below. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph-api==1.0.0rc2"

    It requires 10xgraph 1.0.0rc2 and is aligned with 10xgraph-client 1.0.0-rc.2. If you upgrade from 0.9.x, the rc1 breaking list applies to you as well. Read Breaking and the upgrade guide before upgrading.

    Breaking

    • Ids in paths and bodies must match ^[A-Za-z0-9._:@-]{1,128}$. A thread_id, message_id or memory id that is longer or has other characters gets 422 (VALIDATION_ERROR). Snowflake integers and UUIDs fit.
    • Nested initial_state, config and resume values deeper than 64 levels get 422.
    • Resume errors answer 409 or 422. A wrong interrupt id, a resume sent to a thread that is not paused, and a new message sent to a thread paused at interrupt() return 409 (before the stream starts on POST /v1/graph/stream). A value that fails the interrupt’s response_schema returns 422.
    • Writes during a run return 409. State and message writes, thread and message deletes, and POST /v1/graph/fix are refused while a run holds the thread. Migration: retry after the run ends or stop it first.
    • DELETE /v1/threads/{thread_id} can return success=false with data.cleanup_failed when file, trace or cache cleanup failed. The thread rows are deleted; retry the cleanup.
    • JWT_ALGORITHM must be on the allowlist (HS256, RS256, ES256, PS256, EdDSA and their variants). none or any other value stops startup, as does "auth": "jwt" without PyJWT. The auth value must be exactly "jwt".
    • The graph:setup scope is gone. Remove it from your authorization config.
    • A run that hits its recursion limit answers 422 (GRAPH_RECURSION_LIMIT), not 500. Graph validation errors use VALIDATION_ERROR only.
    • POST /v1/graph/stream is labelled application/x-ndjson and idle streams send a blank keep-alive line every 15 s. Migration: update proxy rules or clients that matched text/event-stream.
    • AG-UI and /v1/graph/live follow runs.thread_ids like REST. Frontends that make their own thread ids (CopilotKit does by default) must set "runs": {"thread_ids": "client"}.
    • 10xgraph build refuses --docker-compose together with --k8s. Run it once per target.
    • Uploads are checked against new limits: images over 50,000,000 pixels and PDFs over 10 MB or 500 pages get 413.
    • IS_DEBUG is removed. Debug follows MODE. The /v1/evals/runs endpoints are removed, and 10xgraph eval writes only the JSON report.

    Upgrade notes

    • Postgres: stop all old pods, run the schema migration with one new pod, then start the rest. /health/ready fails while the schema is behind.
    • The generated Gunicorn command uses TenxGraphUvicornWorker: regenerate Docker and Kubernetes files with 10xgraph build. Keep --graceful-timeout above the three SHUTDOWN_*_SECONDS settings.
    • Handled client errors log one WARNING line, not an ERROR with a traceback.

    Added

    • Shutdown settings SHUTDOWN_GRACE_SECONDS, SHUTDOWN_STOP_SECONDS and SHUTDOWN_TIMEOUT_SECONDS; 503 with Retry-After while closing; a final error chunk with data.interrupted: true on a cut stream; and a terminal done chunk on HTTP streams.
    • Typed server errors with the request id, 429 PROVIDER_RATE_LIMITED, and Retry-After on 429 and 409.
    • Redis settings REDIS_SOCKET_TIMEOUT, REDIS_CONNECT_TIMEOUT, REDIS_POOL_TIMEOUT, REDIS_MAX_CONNECTIONS, REDIS_HEALTH_CHECK_INTERVAL and REDIS_KEY_PREFIX.
    • Media limits MEDIA_MAX_FILES_PER_USER, MEDIA_MAX_USER_STORAGE_MB, MEDIA_MAX_IMAGE_PIXELS, MEDIA_MAX_PDF_MB, MEDIA_MAX_PDF_PAGES, MEDIA_INLINE_MAX_BYTES and MEDIA_SWEEP_INTERVAL_SECONDS, and GET /v1/files.
    • has_more, offset and limit on thread, message and memory lists.
    • A run trace span tree on the observability route (dev only), and realtime_options in the graph details.
    • 10xgraph revoke for tokens (--jti or --user) with Redis-backed revocation.

    Fixed

    • Stop and shutdown reach a REST stream after its first chunk, and a disconnected stream frees its thread only after the run is saved.
    • 10xgraph eval reports carry each case’s expectations, and the init eval templates check what they declare and can pass.
    • The template weather tool answers per city, and the default Gemini Live model name is current.
  16. TypeScript client

    v1.0.0-rc.2

    Breaking changes

    The second 1.0 release candidate, published under the next dist-tag. Drops Node.js 18, adds interrupt helpers, typed errors, abort signals and token functions, and fixes stream and realtime edge cases.

    The second 1.0 release candidate, published to npm under the next dist-tag:

    Terminal
    npm install 10xgraph-client@next

    npm install 10xgraph-client still installs 0.6.0 until 1.0.0 is released. Use this release with 10xgraph-api 1.0.0rc2. New response fields are typed optional, so the client still works against older servers. See the upgrade guide.

    Breaking

    • Node.js 18 is no longer supported. engines is node >= 20.0.0, and CI runs Node 20 and 22. Migration: run the client on Node.js 20 or later.
    • Typed change: RealtimeSession.threadId is string | null. It is null until the session_started event arrives when you passed no thread_id. Handle null or wait for the event.

    Behaviour changes

    • stream() and wsStream() 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.
    • timeout is an idle timeout on stream() and wsStream(): it limits the wait on the network, not the whole run.
    • Timeouts and network failures throw RequestTimeoutError and NetworkError. Check the class, not the message text.
    • A baseUrl with a trailing slash is accepted.

    Added

    • Interrupt type, getInterrupt(chunk), approveInterrupt() and rejectInterrupt() to answer a paused run.
    • authToken can be a function called on every request and realtime reconnect; setAuthToken() and clearAuth().
    • A signal option on every request method, not only invoke(), stream() and wsStream().
    • Error classes RequestTimeoutError, NetworkError, WebSocketError, StreamError and RateLimitError (with retryAfterSeconds). Errors carry cause, endpoint, method and requestId.
    • validate(args) and maxArgsBytes on remote tool registrations; declared parameters are checked before the handler runs.
    • listMemories takes offset and returns has_more and next_offset; listFiles(params?) for GET /v1/files; has_more, offset and limit on thread lists.
    • Run trace types, GraphInfo.realtime_options and extended eval report types.
    • Live sessions without a thread_id use the server-created id from the session_started event and send it back on reconnect.

    Fixed

    • Leaving a for await loop over stream() early now cancels the request instead of leaving the connection open and the thread answering 409.
    • wsStream() no longer hangs on an error chunk, and a truncated stream line throws StreamError.
    • A 409 throws ConflictError against the real server, not a TypeError.
    • client.realtime() no longer crashes Node with an unhandled rejection when the connection fails.
    • searchMemory() omits unset memory_type, category and score_threshold, so a search without a type covers all memory types.
  17. Core framework

    v1.0.0rc1

    Breaking changes

    The 1.0 release candidate. The public API is stable under a deprecation policy, with a security hardening round across tools, memory, media, checkpointers and handoffs. Breaking changes included.

    The 1.0 release candidate. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph==1.0.0rc1"

    10xgraph-api and 10xgraph-client ship 1.0 release candidates alongside. From 1.0 the three packages share major.minor, and patch numbers move independently. This release has breaking changes: read Breaking and the upgrade guide before upgrading.

    Breaking

    • The graph-level memory API is removed (MemoryIntegration, create_memory_preload_node, get_memory_system_prompt, memory_tool). Migration: pass Agent(memory=MemoryConfig(...)).
    • fetch_and_cache is removed from tenxgraph.storage.media.temp_cache. Migration: download through fetch_media_url with a MediaFetchPolicy.
    • Store operations with a missing or empty user_id raise ValueError (QdrantStore, Mem0Store). Migration: pass a concrete user_id, or system_user_id(name) for shared data, and re-index records written with an empty owner. RAGAgent searches as system_user_id("knowledge_base") unless store_config sets user_id, and store_config_builder output must include user_id.
    • Agent memory is owned by system_user_id(agent_id) (or app_id), not the current user. Agent(memory=...) raises ValueError if agent memory is on with neither id. Migration: set an agent_id or app_id and re-store memories written under a user.
    • A collection in the run config no longer overrides the memory scope’s collection. Migration: set collection on UserMemoryConfig or AgentMemoryConfig.
    • PRELOAD memories are no longer a system message. They arrive as a fenced block in the latest user message and are never saved to state.context. Agent._build_memory_prompts is replaced by Agent._build_memory_block. Migration: update prompts or tests that look for [Long-term Memory Context].
    • RAGAgent puts retrieved documents in a request-only block and no longer rewrites state.context. execution_meta.internal_data["rag_docs"] and _RAG_DOCS_KEY are gone. Migration: a custom agent passed to RAGAgent must accept the keyword-only request_blocks argument on execute, or RAGAgent raises TypeError.
    • Skill and memory text is no longer run through str.format. Only your own system_prompt is interpolated, and a bad placeholder is logged. Migration: remove reliance on {placeholder} expansion inside skill or memory text.
    • QdrantStore.aforget_memory applies memory_type, category and filters; Mem0Store.aforget_memory raises ValueError if any is passed. The qdrant extra needs qdrant-client>=1.10.0 and a Qdrant server 1.10 or newer.
    • Handoffs need a registered handoff tool. A transfer_to_<X> call only jumps if a tool made with create_handoff_tool is on that ToolNode. A Command.goto to an unknown node raises GraphError (GRAPH_007). SwarmAgent enforces can_handoff_to.
    • Tools hidden by tools_tags can no longer be called. Migration: add the tag or the tool if the call was intended.
    • An MCP tool with the same name as a local or remote tool raises ValueError. Migration: rename one of them.
    • Parallel tool calls are capped at 10 per turn. Migration: set max_parallel_tool_calls in the run config, or TENXGRAPH_MAX_PARALLEL_TOOL_CALLS.
    • Unexpected tool errors no longer reach the model verbatim. The model sees Tool '<name>' failed with an internal error (reference <ref>) and the full error is logged. Migration: to show a message to the model, return it as a string; a raised ValueError is no longer shown.
    • A tool call with invalid JSON arguments is answered with a tool error instead of running with empty arguments, and tool metrics label unknown tools as "unknown".
    • File tools refuse secret files (.env, keys, .ssh, .aws, .git and similar) for any root, and file_search stays inside the root. Migration: change the list with create_file_tools(root, deny=..., use_default_deny=False), and prefer create_file_tools(root=...) to the run-config root, which is deprecated and removed in 2.0.
    • fetch_url no longer follows redirects to internal addresses or uses HTTP_PROXY and HTTPS_PROXY. Fetches that relied on a proxy or an internal redirect now fail.
    • Multi-agent loop limits (max_rounds, max_iterations, max_attempts) are per turn and reset on each new turn.
    • Resume is checked. A resume_interrupt_id that is not the pending interrupt’s raises InterruptMismatchError, and a value that fails the interrupt’s response_schema raises ResumeValidationError.
    • PromptInjectionValidator behaves differently. Non-strict mode scans only the first max_length characters, strict mode raises on bad base64, and text in other languages is no longer rejected.
    • Client-supplied media URLs are fetched under a MediaFetchPolicy: http and https to public hosts only, 20 MB, 10 s, and image/* and application/pdf by default. Migration: audio and video links on Google graphs stop downloading until you allow those content types with compile(media_policy=MediaFetchPolicy(...)). The private _convert_to_google_format no longer downloads.
    • CloudMediaStore raises ValueError for storage keys that are not 32 lowercase hex characters. Objects stored under other keys by custom code are no longer reachable through the store.
    • Local media and the SQLite checkpointer create owner-only files (0o700 folders, 0o600 files). Widen the mode yourself if other users or services need access.
    • alist_messages and alist_threads raise ValueError for a negative limit or offset, and an explicit limit is lowered to MAX_LIST_LIMIT (1000).
    • PgCheckpointer schema version 4 changes the messages primary key to (thread_id, message_id). aget_message and adelete_message require thread_id in the config, and aget_tool_result is scoped to the thread owner. Migration: runs automatically on first setup. Back up first.
    • Checkpointers apply the owner rule to state-cache writes, and the in-memory checkpointer returns copies of state, so mutating a loaded state no longer changes the store until you save it.
    • The old example folders and the a2a_sdk example are removed. Use the reorganised examples/ folders.

    Added

    • MediaFetchPolicy, MediaURLError and fetch_media_url in tenxgraph.storage.media, plus compile(media_policy=...) and CompiledGraph.media_policy.
    • collection on UserMemoryConfig and AgentMemoryConfig: a name, or a function of the run config.
    • system_user_id, is_system_user_id and SYSTEM_USER_PREFIX for shared, ownerless data.
    • RAGAgent(store_config_builder=...) to scope the knowledge-base search per user or tenant.
    • user_id_mode ("raw", "hash", "mask") on the OTEL, Logfire and LangSmith setup, to control how the user id appears in traces.
    • Opt-in TLS and SASL for KafkaPublisher.
    • BaseCheckpointer.aupdate_message_metadata, BaseMediaStore.update_metadata, and run tracking with abegin_run, aend_run and aget_active_run.
    • InterruptMismatchError, ResumeValidationError and the resume_interrupt_id resume input.
    • The checkpointer:import scope constant (CHECKPOINT_IMPORT).
    • create_file_tools(root) returns file_read, file_write and file_search locked to a directory set in code.
    • Examples rewritten and reorganised by feature.

    Security

    • Handoffs, hidden tools, MCP name clashes and parallel tool calls are now enforced or bounded.
    • fetch_url and client-supplied media URLs go through a checked HTTP client: every redirect is verified, the connection is pinned to the checked address, and internal and cloud-metadata addresses are refused.
    • PromptInjectionValidator and the <think>, <reasoning> and <thought> parsers no longer backtrack on crafted input.
    • Tool failures, metrics labels and RedisPublisher connection errors no longer leak raw exception text, model-invented names or the Redis password.
    • Memory and skill text can no longer build oversized or state-leaking prompts, and PRELOAD and RAG context stay out of saved history.
    • Checkpointer reads, writes and paging are scoped to the owner and bounded, and local files are owner-only.

    Deprecated

    • The run-config file tool root. Use create_file_tools(root=...); the run-config root is removed in 2.0.
  18. API server and CLI

    v1.0.0rc1

    Breaking changes

    The 1.0 release candidate. Secure-by-default threads, production startup checks and error handling, plus resume, run-busy and file-lifecycle features. Breaking changes included.

    The 1.0 release candidate. Pip skips it unless you pass --pre:

    Terminal
    pip install -U --pre "10xgraph-api==1.0.0rc1"

    It requires 10xgraph 1.0 and pulls 10xgraph 1.0.0rc1. From 1.0 the three packages share major.minor, and patch numbers move independently. This release has breaking changes: read Breaking and the upgrade guide before upgrading.

    Breaking

    • runs.thread_ids defaults to "server" (was "client"). REST and WebSocket clients that invent a thread id for a new thread get 403 on /v1/graph/invoke, /v1/graph/stream, /v1/graph/ws and the checkpointer write routes. Migration: omit the id on the first request and use the meta.thread_id the server returns from then on ("new" over /v1/graph/ws), or set "runs": {"thread_ids": "client"} in 10xgraph.json. AG-UI and /v1/graph/live need no change.
    • Production deployments with the default or wildcard ALLOWED_HOST or ORIGINS refuse to start. Migration: set explicit values, or STRICT_PRODUCTION_CHECKS=false. A public, token-less API in production with ORIGINS=* and CORS_ALLOW_CREDENTIALS=false also needs the opt-out.
    • Production runs longer than 300 s are cancelled (invoke 504, stream and AG-UI error). Migration: raise runs.timeout, or set it to null.
    • An unknown MODE refuses to start, including in 10xgraph dev. Migration: use production, prod, development, dev or local (case-insensitive).
    • Requests over the size limits get 422: 500 messages, 100 blocks per message, 1,000,000 characters of text. On AG-UI the limits apply to the trailing turn, with a 10,000-message cap on history.
    • POST /v1/threads/{thread_id}/messages is admin-only. It needs the checkpointer:import scope held explicitly; an identity with no scopes gets 403. Migration: send normal messages through invoke or stream, and use the new PUT .../messages/{message_id} for feedback.
    • Assistant and system messages, and context_summary and execution_meta, are rejected with 422 on the client routes.
    • Custom authorization backends are isolated by default. A backend that implements only authorize() now gets per-owner storage isolation. Migration: if you relied on sharing, add def isolation_scope(self) -> str: return "none".
    • JWTs with an invalid user_id or scope claim are refused with 401. user_id must be a non-empty string or an integer. A scope or scopes claim must be a string or a list of strings, and a string scopes is split on spaces instead of matched by substring. Migration: fix the issuer.

    Added

    • observability.user_id_mode in 10xgraph.json ("raw" default, "hash", "mask") controls how the user id appears in traces.
    • on_busy request option ("wait" default, or "cancel") on invoke, stream and WS /v1/graph/ws. With "cancel", a run that finds its thread busy asks the running run to stop, then runs.
    • Uploaded files live and die with the messages that use them. Deleting the last message or the thread that uses a file deletes the file. media.delete_with_thread (default true) turns the automatic delete off.
    • DELETE /v1/files/{file_id} deletes a file you own, behind the new files:delete scope.
    • PUT /v1/threads/{thread_id}/messages/{message_id} sets feedback on a message.
    • interrupt_id on invoke, stream and WebSocket input, so a resume can name the interrupt it answers. WebSocket input also accepts resume again.
    • RequirePermission(..., explicit_scope=True) and the checkpointer:import scope.

    Security

    • Handled client errors log one WARNING line instead of an ERROR with a traceback, and Sentry no longer sends request bodies. Migration: alerts that matched ERROR for 4xx must match WARNING.
    • AG-UI context, tools and forwarded props are server config, and ag_ui is a reserved key that other routes drop.
    • Built-in state fields are never client-writable, client messages are user messages only, forged tool results are refused, and the server generates message ids on invoke, stream, WebSocket and PUT state (AG-UI keeps client ids).
    • Thread ids are server-made by default, so nobody can squat an id or probe whether one exists.
    • A client can no longer pick the vector store collection on a graph run: collection is a server-owned config key.
    • Clients can no longer set file_tool_root, workspace_root, tool_timeout or node_timeout in request config; set them in your graph.
    • /v1/graph/live re-checks the token during the session, and HTTP routes take the bearer token only from the Authorization header.
    • One run at a time per thread, and external media URLs, upload types and document text extraction are checked or bounded.
    • Production hides raw error text on state, stream, WebSocket and AG-UI, and OTEL no longer prints spans to stdout.
    • Generated deployment files are locked down by default, and 10xgraph init writes a .gitignore that keeps .env and credentials out of git.

    Fixed

    • Client mistakes on thread routes are a 404 or 422, not a 500, and state and message responses no longer carry provider or framework internals.
    • Development error responses for node and graph errors are no longer a 422 VALIDATION_ERROR.
    • POST /v1/graph/fix no longer deletes healthy tool-call messages.
  19. TypeScript client

    v1.0.0-rc.1

    The 1.0 release candidate, published under the next dist-tag. No breaking changes. Adds on_busy, resume, deleteFile and message feedback, and fixes thread id loss in the client-side tool loop.

    The 1.0 release candidate, published to npm under the next dist-tag:

    Terminal
    npm install 10xgraph-client@next

    npm install 10xgraph-client still installs 0.6.0 until 1.0.0 is released. The client has no breaking change in this release. From 1.0 the three packages share major.minor, so use the client with a 10xgraph-api of the same major.minor. See the upgrade guide.

    10xgraph-api 1.0 defaults runs.thread_ids to "server": a client that invents an id for a new thread gets HTTP 403 on invoke(), stream() and wsStream(). No code change is needed if you already let the server choose. Omit thread_id from config on the first request, then reuse the returned id (result.meta.thread_id for invoke(), chunk.thread_id or chunk.metadata.thread_id for stream()). Operators who want the old behaviour set "runs": {"thread_ids": "client"} in 10xgraph.json.

    Added

    • on_busy?: 'wait' | 'cancel' on invoke(), stream() and wsStream(): what the server does when another run is active on the same thread.
    • resume and interrupt_id options on invoke(), stream() and wsStream() to answer an open interrupt.
    • ConflictError (HTTP 409), exported from the package root.
    • deleteFile(fileId) for DELETE /v1/files/{file_id}.
    • updateThreadMessageFeedback(threadId, messageId, feedback) for PUT /v1/threads/{thread_id}/messages/{message_id}.

    Fixed

    • The client-side tool loop on invoke() and stream() lost a server-assigned thread id: the requests that send tool results omitted it, so the tool round-trip broke or the conversation split. The client now reuses the returned id. A thread_id you pass is never replaced, and your config object is not modified.

    Deprecated

    • addThreadMessages needs the checkpointer:import scope (admin only) on recent 10xgraph-api releases. Use updateThreadMessageFeedback to attach feedback to a message.
  20. Core framework

    v0.10.3

    Python 3.14 and 3.15 are officially supported, and injectq 0.5 is allowed. No API changes.

    Python 3.14 and 3.15 support. No API changes.

    Added

    • Python 3.14 and 3.15 are officially supported. The full test suite runs on 3.12, 3.13, 3.14 and 3.15 in CI, and the package classifiers list all four.

    Changed

    • injectq 0.5 is now allowed (injectq>=0.4.0,<0.6). 0.5.0 fixes a crash under Python 3.15 global lazy imports (PYTHON_LAZY_IMPORTS=all). 0.4.x keeps working.
    • Replaced asyncio.iscoroutinefunction and the event-loop policy API, both removed in Python 3.16. The sync CompiledGraph.stream() no longer changes the thread’s current event loop. No behaviour change otherwise.
  21. Core framework

    v0.10.2

    Pillow is now optional and moved to the images extra, which makes every install and Docker image about 20 MB smaller. No API changes.

    Smaller installs: Pillow is now optional. No API changes.

    Changed

    • Pillow is no longer a required dependency. It moved to the images extra, which cuts about 20 MB from every install and Docker image. Image resizing, EXIF orientation and format conversion in the media processor still work when Pillow is present. Without it, images pass through unchanged. To keep the old behaviour, install 10xgraph[images] (also included in 10xgraph[all]).
  22. API server and CLI

    v0.9.0

    Breaking changes

    10xgraph dev is now the only server command; 10xgraph api and 10xgraph play are removed. Adds a guided init, leaner production images and Python 3.14 and 3.15 support.

    One server command, a guided 10xgraph init, leaner production images and Python 3.14 and 3.15 support. This release has a breaking change: read the Breaking list before upgrading.

    Breaking

    • 10xgraph api and 10xgraph play are removed; 10xgraph dev is the only server command. All three ran the same local Uvicorn dev server. Migration: 10xgraph api becomes 10xgraph dev --no-open, and 10xgraph play becomes 10xgraph dev. Options are unchanged (--config, --host, --port, --reload/--no-reload). 10xgraph demo --style no longer accepts the play and api aliases. Production is unaffected: the image from 10xgraph build runs Gunicorn directly.

    Added

    • Python 3.14 and 3.15 are officially supported. The test suite runs on 3.12, 3.13, 3.14 and 3.15 in CI.
    • websocket.enabled in 10xgraph.json turns the WebSocket routes on or off. false leaves out /v1/graph/ws and /v1/graph/live, so the server needs no WebSocket library. true without one refuses to boot with the install hint. Unset keeps them mounted, as before, but now logs a warning when no library is installed. Previously a non-Google project silently answered 404 on both routes.
    • 10xgraph-api[websocket] extra (websockets) for those routes.
    • 10xgraph init asks whether to enable WebSocket streaming and realtime audio (--websocket/--no-websocket, default off).
    • 10xgraph init asks for the AI provider (Google Gemini, OpenAI or Anthropic Claude; --provider for non-interactive runs, default google). The scaffold’s model, provider, .env.example API key, test conftest and eval simulator model follow the answer.
    • 10xgraph-api[images] extra. Pillow is optional in core 10xgraph; this extra installs it for image resize, EXIF orientation and format conversion.

    Changed

    • Production scaffolds list only the dependencies the answers need. pyproject.toml depends on 10xgraph[<provider>] and 10xgraph-api[jwt,redis] as chosen, and drops the hardcoded google-genai. The generated Dockerfile installs this list, so JWT and Redis work in the image without a separate requirements.txt.
    • The generated Dockerfile removes pip and the CLI’s own libraries from the image (typer, rich, questionary and what only they pull in), unless another installed package still needs them. With pip, the image is about 38 MB smaller.
    • Replaced asyncio.iscoroutinefunction, which is removed in Python 3.16, with inspect.iscoroutinefunction. No behaviour change.

    Fixed

    • 10xgraph init generated a pyproject.toml claiming Python 3.10. It now says requires-python = ">=3.12", which 10xgraph needs.
    • Redis rate limiting from a URL crashed at startup with NameError: Redis.
    • A production scaffold with the Redis rate limiter did not start, because 10xgraph.json had no Redis URL. It now reads "redis": {"url": "${REDIS_URL}"} from .env.
    • A production scaffold did not start at all, because 10xgraph.json pointed at graph.agent:container, which the template never defined. graph/agent.py now exports it.
    • The production scaffold’s tests/test_graph_nodes.py failed on collection. It now tests the agent in graph/agent.py.
  23. Core framework

    v0.10.1

    Fixes the checkpointers' state cache. A state written between runs is now what the next run starts from, and clearing a thread also clears its cached state.

    Bug fixes for the checkpointers’ state cache. No API changes.

    Fixed

    • aput_state now refreshes the state cache (write-through) on every checkpointer. A run loads its state from the cache first (aget_state_cache), but aput_state wrote only the durable store, so a state written between runs was not what the next run started from. InMemoryCheckpointer and SqliteCheckpointer silently lost the update, because the next run wrote the old state back over it. PgCheckpointer also left the old checkpoint version in Redis, so the next run’s first write raised StaleStateError (STORAGE_CONFLICT_001) and the run failed. PgCheckpointer now refreshes Redis after the durable write succeeds, at the new version, version-guarded and best-effort like every cache write, so a Redis outage never fails the write. SqliteCheckpointer updates its cache row in the same transaction.
    • Clearing a thread’s state now also drops its cached state. aclear_state on InMemoryCheckpointer and SqliteCheckpointer deleted only the durable state, so the next run read the cleared state back from the cache and resumed from it. Both now delete the cache entry too (SQLite in the same transaction), as PgCheckpointer already did.
    • InMemoryCheckpointer.aclean_thread now removes the whole thread. It deleted only the thread record; it now also deletes the thread’s state, cached state and messages, like the SQLite and Postgres checkpointers.
  24. API server and CLI

    v0.8.0

    Breaking changes

    Security and scalability pass. Ownership checks fail closed, authorization defaults to ownership whenever auth is set, and production defaults are stricter. Read the breaking list before upgrading.

    Security and scalability pass over the API, following an external review. This release has breaking changes: read the Breaking list before upgrading.

    Breaking

    • Ownership checks fail closed. With auth on, an ownership or rbac authorization backend now refuses to start on a checkpointer that cannot resolve thread owners (aget_thread_owner not implemented), and denies thread requests if none is available at runtime. Implement aget_thread_owner, or set "authorization": "allow_all" or a custom backend.
    • An unowned thread only allows actions that create it (graph:invoke, graph:stream, checkpointer:write). Reading, deleting, stopping or fixing a thread that does not exist, or has no owner, now answers 403 instead of an empty result.
    • Authorization defaults to ownership whenever auth is configured, in every mode. It used to be allow_all unless MODE=production. Set "authorization": "allow_all" to keep the old development behaviour.
    • Realtime init frames can no longer replace the system prompt by default. Add "system_prompt" to websocket.realtime_client_overrides to allow it.
    • trusted_proxy_headers: true without trusted_proxies trusts only loopback and private networks, not every peer. List your proxy networks (or 0.0.0.0/0 and ::/0).
    • Production defaults: MEDIA_REQUIRE_OWNER is on, graph_introspection is scoped (graph structure, tools and state schema need the graph:read scope), and IS_DEBUG is forced off.
    • /v1/graph/invoke no longer returns meta.thread_name. The name is generated in the background and appears on the thread (GET /v1/threads).
    • Production 4xx responses keep their message. Only 5xx are made generic. A 422 built from an unexpected ValueError is still made generic.
    • gunicorn is no longer a dependency. The generated Dockerfile installs it, so 10xgraph build images are unaffected. If you run gunicorn yourself outside that image, install it alongside the API: pip install gunicorn uvicorn-worker.
    • Gunicorn’s worker class is now uvicorn_worker.UvicornWorker (from the uvicorn-worker package). uvicorn.workers.UvicornWorker is deprecated in uvicorn. Regenerate the Dockerfile and compose file with 10xgraph build --force, or change -k in your own command.
    • POST /v1/graph/fix returns state as a JSON object. It used to be a JSON-encoded string. Drop any JSON.parse or json.loads on that field. The TypeScript client already types it as an object.
    • Generated Dockerfiles install only the dependencies you list. The pyproject.toml path no longer adds 10xgraph-api on top of your list. 10xgraph build warns when the requirements file or pyproject.toml does not list 10xgraph-api.

    Added

    • runs key in 10xgraph.json: thread_ids (client or server), config_keys and state_keys allow-lists, max_concurrent_per_user (default 10) and timeout.
    • token_revocation key (redis, memory or module:attr) and the TokenRevocationBackend hook. Revoked tokens are refused before they expire, on HTTP and on every WebSocket run.
    • graph_introspection key (open or scoped).
    • websocket.realtime_client_overrides allow-list.
    • STRICT_PRODUCTION_CHECKS=true: production refuses to start on wildcard ALLOWED_HOST or ORIGINS, or enabled API docs.
    • GET /health/ready readiness probe (checkpointer, Redis, store). The Kubernetes manifest uses it.
    • Run and WebSocket connection caps are shared across workers through Redis when it is configured.

    Changed

    • 10xgraph play and 10xgraph dev open the hosted playground at its new address, https://play.10xgraph.com. The previous address, playground-463bd.web.app, still serves the same app for older releases.
    • Thread delete leaves a short tombstone so a deleted id cannot be handed to another user while other workers still cache the old owner.
    • Every thread the API saves records its owner, which fixes owner lookups on the in-memory and SQLite checkpointers.
    • WebSocket JSON frames over MAX_REQUEST_SIZE are refused (close 1009).
    • Request ID, security headers and rate limiting are pure ASGI middleware. CORS is now the outermost layer, so 429, 413 and Host rejections are readable by browsers.
    • Route-set security headers, such as the download sandbox CSP, are no longer overwritten.
    • The JWT is verified once per request when rate limiting by user.
    • Local-store downloads stream from disk. Uploads are read into memory once.
    • JSON responses are serialized by pydantic-core instead of orjson. The orjson and platformdirs dependencies are dropped, and the uvicorn floor is now 0.36.
    • Generated Dockerfiles build in two stages. Dependencies go into a virtualenv in a builder stage, and only that virtualenv and your code reach the runtime image, which has no compiler or curl.
    • A requirements file in a subfolder (for example requirements/base.txt) keeps its path in the generated Dockerfile.
    • license is an SPDX expression (MIT). Building from source needs setuptools 77 or later.

    Security

    • Log injection. Values a client controls (user and thread ids, file ids, rate-limit keys, request paths, run config and messages) are written to logs through log_safe(), which escapes CR and LF, so a request cannot forge extra log lines.
    • ReDoS in the log sanitizer. The JWT detection pattern backtracked polynomially on crafted input. It now matches in linear time.
    • Security examples. examples/security/ no longer prints any part of an API key or of the JWT secret. The API key example hashes keys with HMAC-SHA-256 and a server-side API_KEY_PEPPER. Hashes made with the previous example’s plain SHA-256 must be regenerated.
  25. Core framework

    v0.10.0

    Breaking changes

    First release as 10xgraph (import tenxgraph). Adds interrupt() for human approval, per-run client tools and Agent Skills spec support, and fixes remote tool pauses and checkpoint loading.

    Agentflow is now 10xGraph. This is the first release of the 10xgraph package. It contains everything since 0.9.2, including the changes that shipped in 10xscale-agentflow 0.10.0 and 0.10.1, the final releases under the old name.

    Breaking

    • The package is renamed. Install 10xgraph and import tenxgraph. Every canonical path is the old one with agentflow replaced by tenxgraph, for example tenxgraph.core.graph and tenxgraph.storage.checkpointer. The top level also exports StateGraph, Agent, ToolNode, AgentState, Message, START and END. Uninstall 10xscale-agentflow first: both packages ship an agentflow module.
    • Observable identifiers changed. The OpenTelemetry tracer and meter name and GEN_AI_SYSTEM are now 10xgraph, logger names are tenxgraph.*, and the prebuilt tools user-agent is 10xgraph-prebuilt-tools/1.0. Update dashboards, alerts and log filters that match the old values.
    • Skills API reworked around the Agent Skills specification. Migration:
      • The set_skill tool is replaced by activate_skill(skill_name) and read_skill_resource(skill_name, path). Prompts that mention set_skill or parse its ## SKILL: header must use the new names and the <skill_content name="..."> wrapper.
      • SkillConfig.inject_trigger_table is renamed inject_catalog, and SkillsRegistry.build_trigger_table() is replaced by build_catalog().
      • build_set_skill_tool() and load_resources() are removed. Use activation.make_activate_skill_tool() and SkillsRegistry.read_file().
      • The resources: frontmatter list is removed; every file in the skill directory is readable.
      • triggers, tags and priority are read only from metadata, as strings.
      • Skill names are no longer lowercased. Discovering the same name in two directories no longer raises: the first wins and the second is reported as shadowed.
    • One checkpointer instance serves one state class. compile() binds the graph’s state class to the checkpointer, and binding a different class raises ValueError. Migration: give each graph with its own state class its own checkpointer, and call checkpointer.bind_state_type(MyState) when reading threads outside a compiled graph.

    Added

    • interrupt() pauses a graph from inside a node or tool. from tenxgraph.utils import interrupt. The run saves the thread paused before that node; resume with ainvoke({"resume": value}, config) and interrupt() returns value. It supports message, reason and response_schema, several calls per node, and parallel tool calls, where finished siblings are served from the tool ledger instead of running again. GraphInterrupt derives from BaseException, so tool and node error handling cannot swallow it. tenxgraph.utils.pending_interrupt(state) returns the open request.
    • Per-run client tools. config["remote_tools"] lets one run bring its own client-executed tool schemas without changing the graph. The tool node offers them for that run and hands calls to them back to the client.
    • Agent Skills specification support (agentskills.io). Skills written for Claude Code, Codex or GitHub Copilot load unchanged. The system prompt gets an <available_skills> catalog, read_skill_resource reads any bundled file as text, and validate_skill() checks a skill against the spec. Loading is lenient: a spec violation is recorded as a diagnostic instead of dropping the skill.
    • Activated skills survive context trimming. If a context manager drops the tool result that carried a skill’s instructions, the agent re-injects them.
    • Skill tool calls fire InvocationType.SKILL callbacks instead of TOOL.
    • tenxgraph.utils.injection.fresh() resolves Inject[...] defaults per call.

    Changed

    • import agentflow keeps working as a deprecated alias until 2.0. It resolves to the same module objects as tenxgraph and emits one DeprecationWarning.
    • Media URI scheme is graph://media/. Old agentflow://media/ URIs are still read.
    • Default home directory is ~/.10xgraph, falling back to ~/.agentflow when only that exists. This sets the default SqliteCheckpointer path.
    • Cloud media prefix is 10xgraph-media. Objects under agentflow-media are still read.
    • The server config file is 10xgraph.json; the CLI falls back to agentflow.json.

    Fixed

    • Client-side (remote) tool calls now pause the graph. The check compared a class against block instances, so it was never true and the graph kept running. The graph now pauses after the tool node and resumes when the client sends the results on the same thread.
    • Messages a node appends to state.context are streamed and returned, instead of only being saved.
    • Inject[...] defaults no longer pin the first resolved dependency for the whole process. The first graph that ran used to decide which checkpointer every later graph used.
    • Parallel tool calls no longer lose execution_meta.internal_data writes.
    • Reading a non-UTF-8 skill resource no longer crashes the tool.
    • Checkpointers no longer import a class named by stored data. Rows now store the state as JSON plus a format header and are rebuilt into the state class bound at compile(). Old rows still load, and the stored class path is never imported.

    Migration

    Terminal
    pip uninstall 10xscale-agentflow
    pip install 10xgraph
    Python
    # before
    from agentflow.core.graph import StateGraph
    # after
    from tenxgraph import StateGraph

    See Coming from Agentflow for every renamed identifier.

  26. API server and CLI

    v0.7.0

    First release as 10xgraph-api. The command is 10xgraph, the config file is 10xgraph.json and the import is tenxgraph_api; the old names keep working until 2.0. Requires 10xgraph 0.10.0 or newer.

    Agentflow is now 10xGraph. This package replaces 10xscale-agentflow-cli. The server, the CLI and the HTTP API are unchanged apart from the names below, and every old name keeps working until 2.0.

    Changed

    • PyPI package is 10xgraph-api. Uninstall the old packages first, since the old core and the new one both ship an agentflow module:

      Terminal
      pip uninstall 10xscale-agentflow-cli 10xscale-agentflow
      pip install 10xgraph-api
    • The command is 10xgraph. agentflow still runs the same CLI and prints a one-line deprecation notice.

    • The config file is 10xgraph.json. agentflow.json is still read when no 10xgraph.json sits in the same directory; when both exist, 10xgraph.json wins. 10xgraph init writes 10xgraph.json, and 10xgraph config creates it from agentflow.json on first save without touching the old file.

    • The import package is tenxgraph_api (from tenxgraph_api import BaseAuth). agentflow_cli stays as a deprecated alias.

    • Core dependency is 10xgraph>=0.10.0,<2.0 (import tenxgraph), replacing 10xscale-agentflow.

    • CLI env vars use the TENXGRAPH_ prefix (TENXGRAPH_NO_FULLSCREEN, TENXGRAPH_NO_SPINNER, TENXGRAPH_ASCII). The AGENTFLOW_ names are read when the new one is unset.

    • Uploaded media is referenced as graph://media/<key>. agentflow://media/<key> still resolves, and both go through the same ownership check.

    • Default MEDIA_CLOUD_PREFIX is 10xgraph-media. With the default, objects under agentflow-media are still read.

    • The WebSocket bearer subprotocol is 10xgraph-bearer. agentflow-bearer is still accepted.

    • The bundled skill installs as 10xgraph, and the Copilot instructions file as 10xgraph.instructions.md. Delete old agentflow skill folders after installing the new one.

    • Logger names are tenxgraph_api.*. Update logging config that targets the old names.

    • The default Redis rate-limit key prefix is 10xgraph:rate-limit. Counters restart once on upgrade; a configured prefix is kept.

    • The config editor’s session header is X-10xGraph-Token.

    • 10xgraph build Dockerfiles ship only what the server runs. The image drops the CLI-only templates and config editor, and the generated .dockerignore leaves out tests/, evals/, .claude/, .agents/ and .github/. Regenerate with 10xgraph build --force.

    • Terminal look follows the brand. A shorter intro (0.9 s) in the logo’s colors shows the running versions and can be skipped with any key. Ctrl+C quits immediately, and the pinned full-screen frame is opt-in (--fullscreen or TENXGRAPH_FULLSCREEN=1).

    Unchanged on purpose

    • The error code AGENTFLOW_VALIDATION_ERROR, the agentflow.cli/v1 schema id in --format json output, and the AF-* CLI error codes, so scripts that match on them keep working.

    See Coming from Agentflow for the full migration.

  27. TypeScript client

    v0.6.0

    Breaking changes

    First release as 10xgraph-client. Classes are renamed TenxGraph*, the old AgentFlow* names stay as deprecated aliases, and WebSocket bearer auth needs 10xgraph-api 0.7.0 or newer.

    Agentflow is now 10xGraph. This package replaces @10xscale/agentflow-client, whose last version is 0.5.0. The client’s behavior is unchanged apart from the names below.

    Terminal
    npm uninstall @10xscale/agentflow-client
    npm install 10xgraph-client

    Breaking

    • WebSocket bearer auth uses the 10xgraph-bearer subprotocol (WS_BEARER_SUBPROTOCOL), replacing agentflow-bearer. 10xgraph-api 0.7.0 accepts both. An older 10xscale-agentflow-cli server knows only the old name, so wsStream() and realtime() with bearer auth fail against it. Migration: upgrade the server to 10xgraph-api 0.7.0 or newer. HTTP endpoints are unaffected.
    • TenxGraphError.name is 'TenxGraphError' (was 'AgentFlowError'). Code that compares error.name should use instanceof instead.

    Changed

    • The package is 10xgraph-client: import { TenxGraphClient } from '10xgraph-client'.
    • Exported names are renamed: TenxGraphClient, TenxGraphConfig, TenxGraphError, TenxGraphAuth, TenxGraphBearerAuth, TenxGraphBasicAuth and TenxGraphHeaderAuth.
    • The debug log prefix is TenxGraphClient:.

    Deprecated

    • AgentFlowClient, AgentFlowConfig, AgentFlowError, AgentFlowAuth, AgentFlowBearerAuth, AgentFlowBasicAuth and AgentFlowHeaderAuth are exported as aliases of the same classes and types, so existing code and instanceof checks keep working. They are removed in 2.0.

    See Coming from Agentflow for the full migration.

  28. TypeScript client

    v0.5.0

    Breaking changes

    Final release as @10xscale/agentflow-client. Removes client.setup(), since remote tool schemas are now declared on the server, and adds registerToolHandler() for their client-side code.

    This is the final release of the TypeScript client under the name @10xscale/agentflow-client. It continues as 10xgraph-client from 0.6.0.

    Breaking

    • client.setup() is removed, together with its endpoint module and the SetupGraphContext, SetupGraphRequest, SetupGraphResponse and RemoteTool types. The server removed POST /v1/graph/setup in API 0.6.0, so the call could no longer succeed.

      Migration: declare each client-executed tool (node, name, description, parameters) under remote_tools in the server config file, register only its handler on the client with client.registerToolHandler(name, handler), and delete any await client.setup() call. See Remote tools.

    Added

    • client.registerToolHandler(name, handler) registers the client-side code for a remote tool whose schema is declared on the server.

    Changed

    • ToolRegistration.node is optional. registerTool() still works, but its description and parameters are no longer sent.
    • RealtimeInit.model is optional. The server uses it only when the model is listed in websocket.realtime_models, and otherwise uses the agent’s own model.
    • MultimodalConfigResponse.data no longer declares media_storage_path; the server does not return it.

    Compatibility

    Requires API 0.6.0 or newer, the first server release with remote_tools in the config file. It works with 10xgraph-api 0.7.0, which still accepts the agentflow-bearer WebSocket subprotocol this client sends.

  29. API server and CLI

    v0.6.0

    Breaking changes

    Final release as 10xscale-agentflow-cli. Adds the AG-UI endpoint, interrupt resume over invoke and stream, server-declared remote tools, a browser config editor, and stricter handling of client-sent config.

    This was the final release of the API server and CLI under the name 10xscale-agentflow-cli. It continues as 10xgraph-api from 0.7.0. The names below (agentflow command, agentflow.json) are the ones this release shipped with.

    Breaking

    • POST /v1/graph/setup is removed. Declare client-executed tools under remote_tools in the config file instead; they are attached at startup.
    • agentflow config list|get|set|unset|path|validate are removed, and stored output.* preferences are no longer read. Pass --format, --color and --progress on the command line. agentflow config is now the browser editor below.

    Added

    • AG-UI endpoint (POST /v1/ag-ui) serves the graph over the AG-UI protocol, so AG-UI clients such as CopilotKit can use the agent. Off by default: set "ag_ui": {"enabled": true} and install the ag-ui extra. It uses the graph:stream permission, checks thread ownership when auth is configured, and streams text, reasoning, tool calls, node steps, state snapshots and interrupt() pauses. Browser tools the client sends are offered to the model for that run. See AG-UI.
    • resume on /v1/graph/invoke and /v1/graph/stream resumes a thread paused by interrupt().
    • remote_tools in the config file. Trusted schemas for client-executed tools, attached to the graph at startup. In request config, remote_tools is now server-owned: only protocol adapters such as AG-UI fill it.
    • agentflow skills --validate PATH checks skills against the Agent Skills specification and exits 1 when any is invalid.
    • The bundled skill conforms to the Agent Skills specification, and Codex, Claude and GitHub now receive one identical SKILL.md.
    • agentflow config opens a browser editor for the config file. Optional sections can be switched on, filled in, validated and saved. Saving is blocked while there are errors, writes are atomic, and the previous file is kept as a .bak.
    • websocket.max_connections_per_user caps concurrent WebSocket connections per verified user.
    • rate_limit.trusted_proxies honours X-Forwarded-For only from listed IPs or CIDR ranges.

    Changed

    • Requires 10xscale-agentflow>=0.10.0, the first core release with interrupt(), per-run remote_tools and validate_skill.
    • WebSocket connection limits default to finite values (max_connections 1000, max_connections_per_user 10). Set a key to 0 or null for unlimited. Graph runs over /v1/graph/ws count against the global rate limit.

    Security

    • Server-owned config keys are stripped from client requests. authz, user, user_id, remote_tools and _-prefixed keys in a request’s config are dropped on every route that forwards it.
    • Client messages can no longer carry tool calls. A client may send a tool result only as the answer to a remote tool call still waiting for one.
    • Document extraction is bounded. ZIP-based documents are inspected before parsing, extraction has a timeout, and extracted text is capped.
  30. Core framework

    v0.9.2

    Breaking changes

    Adds a native Anthropic provider with prompt caching, server tools and batches, token counting, an OpenAI batch helper, and several tool-node and background-task fixes. One breaking routing change.

    Breaking

    • anthropic/ and claude/ are now recognised model prefixes. Previously they were unknown prefixes that fell through to the OpenAI provider, which is how Claude behind an OpenAI-compatible proxy worked. Agent(model="anthropic/claude-3") now selects the native Anthropic provider and strips the prefix. Migration: pass provider="openai" explicitly to keep routing through an OpenAI-compatible endpoint, for example Agent(model="anthropic/claude-3", provider="openai", base_url=...).

    Added

    • Native Anthropic provider. model="claude-opus-5" (or "anthropic/...", "claude/...") now builds a real Anthropic client instead of constructing an AsyncOpenAI that failed at request time. It covers non-streaming and streaming, tool calling, multimodal input, reasoning, usage accounting and retry/fallback. Install with the anthropic, anthropic-vertex or anthropic-bedrock extra.
      • Three backends, selected with anthropic_backend: None (direct Claude API), "vertex" (AsyncAnthropicVertex) and "bedrock" (AsyncAnthropicBedrockMantle). Bedrock model ids keep their anthropic. prefix.
      • max_tokens is required by the API and is defaulted automatically (16000 non-streaming, 64000 streaming).
      • temperature, top_p and top_k are stripped per model for models that reject them with a 400.
      • reasoning_config={"effort": ...} maps to thinking={"type": "adaptive"} plus output_config.effort. budget_tokens is never emitted, because it returns a 400 on current Claude models.
      • A trailing assistant turn is dropped, since prefill returns a 400 on current models. This protects the injected context_summary.
      • A policy refusal is surfaced as a message with metadata["refusal"] instead of being treated as a transient failure that burns the model fallback list.
    • Agent.count_tokens(messages, tools) counts a request’s input tokens before sending it, using the provider’s own endpoint. For Anthropic it uses the exact payload the real call would send (system prompt, tool schemas, merged tool results). For Google it counts the converted contents only, so the system instruction and tool schemas are not included.
    • Anthropic prompt caching. anthropic_cache=True (or a dict such as {"type": "ephemeral", "ttl": "1h"}) places cache_control breakpoints at the end of the stable request prefix: the last tool and the last system block. It is skipped when the caller placed their own breakpoints. Verify hits with usage.cache_read_input_tokens; a prefix under about 1024 tokens silently does not cache.
    • Anthropic server tools. web_search_tool(), web_fetch_tool() and code_execution_tool() build correctly dated definitions. Server-tool result blocks are captured into metadata["server_tool_results"], and a server_tool_use block is recorded without being added to tools_calls, so the graph does not re-run work Anthropic already did. A server-tool error is surfaced as error_code, and stop_reason: "pause_turn" is flagged as metadata["pause_turn"].
    • AnthropicBatch and OpenAIBatch (tenxgraph.core.llm) for batch APIs, with a shared interface: build, submit, poll and collect. Results are keyed by custom_id, because batch results arrive in any order. BatchResult is exported alongside them.
    • call_llm supports Anthropic, so SummaryContextManager, the evaluation judge and UserSimulator work with Claude models.

    Changed

    • Tool-result serialization has explicit rules for datetime, UUID, Decimal, Enum, set and bytes values. Decimal renders as a string so money values keep their precision.
    • When a nested-object tool parameter fails validation and the model sent it as a JSON string, the string is decoded and validated as a fallback. Validation failures now return a readable message naming the tool and parameter.

    Fixed

    • use_vertex_ai=True hijacked Claude models. The flag short-circuited provider detection to "google", so Agent(model="claude-opus-5", use_vertex_ai=True) built a Google GenAI client with a Claude model name. It now acts as a backend selector for Anthropic (equivalent to anthropic_backend="vertex"), and an explicit anthropic_backend still wins. Behavior for non-Claude models is unchanged.
    • call_llm sent unrecognised model prefixes to the SDK verbatim, so call_llm("gemini/gemini-2.5-flash", ...) passed the full string as the model name. It now uses resolve_provider_and_model.
    • The Anthropic request builder could send an empty messages list when the context summary was the only turn. The lone trailing assistant turn is now sent as a user turn instead of being discarded.
    • AnthropicBatch skipped the trailing-assistant guard that the live request path applies, so the same input produced two different bodies. Both paths now agree.
    • A missing required tool argument failed the whole graph run (NODE_001). It is now a failed tool result that the model can correct, and on-error callbacks see the model’s raw arguments.
    • Tool results serialized Path values with backslashes on Windows. Paths, and resource uri values built from them, now use POSIX separators.
    • wait_for_all() returned before task cleanup callbacks ran, leaving finished tasks and their metadata in the manager. It now yields once so the callbacks run first.
  31. API server and CLI

    v0.5.1

    Reworks the CLI around a full-screen, animated terminal experience with new dev, audit, demo and config commands, guided prompts and machine-readable output modes.

    Added

    • agentflow dev, a goal-oriented local development command (config, host, port, --reload/--no-reload, --open/--no-open). api and play remain available.
    • agentflow audit runs six read-only checks: Python interpreter, installed 10xscale-agentflow-cli, installed 10xgraph, whether the installed core still exposes the evaluation API that agentflow eval imports, whether 10xgraph.json exists with a valid agent key, and whether the default port is free. It exits 1 on any failure and 0 otherwise (warnings do not fail the run), so it works as a CI gate.
    • agentflow demo previews the animation, timeline and progress states without touching project state (--style all|typing|network|init|build|eval).
    • agentflow config list|get|set|unset|path|validate manages cross-platform user preferences stored as JSON in the per-user config directory. output.format, output.color and output.progress are read at startup as defaults, and explicit flags still win.
    • Persistent full-screen surface on interactive terminals, with a pinned header and footer status bar and the command output scrolling between them. Opt out with --no-fullscreen or AGENTFLOW_NO_FULLSCREEN=1.
    • Animated command intros, live step timelines and determinate progress. Timelines are wired into play, dev, api, init, build, test and audit, and agentflow eval shows a progress bar with a running pass/fail tally.
    • Shared guided-prompt layer. Every interactive question uses one themed service with a clean Ctrl+C exit and a single non-interactive policy. agentflow skills now uses an arrow-key list where space toggles and enter confirms, and agentflow init explains each option inline.
    • Root options --format, --json, --color, --no-color, --progress, --animation/--no-animation, --fullscreen/--no-fullscreen, --cwd, --yes, --non-interactive, --debug and -V/--version.
    • Adaptive rendering with TTY and CI detection, plain and JSONL modes, NO_COLOR support, an ASCII fallback and quiet mode.
    • Reproducible agentflow init --non-interactive recipes and --dry-run previews.
    • Staged startup feedback, a pre-flight port check and connected-playground completion output for agentflow play and agentflow dev.
    • Stable CLI error codes and dependency recovery suggestions.

    Changed

    • Command implementations load lazily, so a broken optional feature no longer prevents root help, version, completion or unrelated commands from starting.
    • CLI logging uses one invocation-wide handler, so quiet and verbose levels apply consistently without duplicate records.
    • Project configuration discovery walks parent directories from the current working directory.
    • agentflow init no longer prints one line per scaffolded file. Files stream through the active timeline row instead.
    • The agentflow init template configures JWT with the bare "jwt" string, which is the form 10xgraph.json accepts for the built-in method.
    • The error for dynamic tool setup in production or multi-tenant mode now names which condition tripped (MODE or a configured auth backend) and points to CompiledGraph.attach_remote_tools() as the static alternative.

    Fixed

    • The full-screen session no longer erases the command’s output. Each line used to overwrite the last, and releasing the screen discarded everything drawn on it.
    • A terminal that cannot host a prompt no longer crashes the command. Under MSYS or Cygwin shells on Windows, stdin.isatty() is true but prompt-toolkit cannot attach, which surfaced as AF-INTERNAL-001. Such terminals are now treated as non-interactive.
    • Pinned chrome is repainted after each prompt, and one Rich Console is reused per stream so background output no longer collides with spinners and progress bars.
    • A console that reports itself as a terminal but refuses the alternate buffer (legacy Windows console) now aborts the frame before writing anything.
  32. Core framework

    v0.9.1

    Small fix release. The synchronous tool listing on ToolNode now includes remote tools, and AudioAgent is exported from tenxgraph.prebuilt.

    Added

    • AudioAgent is now exported from tenxgraph.prebuilt.

    Fixed

    • ToolNode.all_tools_sync() silently dropped remote tools. The async path (all_tools()) included them, so client-side tools were visible to the model in one path and invisible in the other. The sync path now returns the same set: local, MCP and remote tools.
    • UserSimulator now sets the per-simulation thread_id at the top level of the run config (it previously nested it under configurable), so each simulation gets its own thread.
    • The CompiledGraph.attach_remote_tools() docstring now documents the expected schema: OpenAI function-calling format, with the tool name read from function.name.
  33. TypeScript client

    v0.4.0

    Breaking changes

    Fixes tool parameter typing so all-optional tools typecheck, widens thread ID types, and changes WebSocket auth precedence so auth now wins over authToken when both are set.

    Breaking

    • WebSocket auth: auth now takes precedence over authToken. resolveBearerToken() previously checked authToken first and only fell back to auth. It now resolves auth first, matching buildHeaders() on the HTTP path, and returns null when auth is a non-bearer scheme instead of falling back to authToken. This affects wsStream() and realtime(), and only if you set both auth and authToken.
      • auth: { type: 'bearer', token: 'b' } with authToken: 'tok' now resolves to 'b' (it was 'tok').
      • auth of type basic or header with authToken now resolves to null (it was 'tok'). In a browser, basic auth then sends no credential on the socket. Header auth sends none in any runtime, because openWebSocket() never forwards a custom header name.
      • Migration: pass the socket credential as bearer with auth: { type: 'bearer', token }, or drop auth and keep authToken.

    Added

    • normalizeToolParameters(parameters?), exported from tools.ts, applies the JSON Schema defaults (type: 'object', properties: {}, required: []) to a partial tool schema.
    • A version-compatibility table in the README mapping client versions to 10xscale-agentflow-cli and 10xgraph versions.

    Changed

    • The three thread-state endpoints, threadState(), updateThreadState() and clearThreadState(), now accept string | number for threadId, matching the other thread methods. Existing calls passing a number keep compiling.
    • Tool registrations with no parameters now serialize to { type: 'object', properties: {}, required: [] } instead of a bare {}.

    Fixed

    • ToolParameter.required was mandatory, so all-optional tools did not typecheck (issue #12). required and properties are now optional, and ToolParameter accepts arbitrary JSON Schema keywords such as additionalProperties and $defs. The wire format is unchanged: client.setup() and ToolExecutor.all_tools() fill in the omitted keywords.
    • agent.ts broke type resolution under moduleResolution: nodenext. Its ./message import was the only extensionless relative import in src/, so node16 and nodenext consumers got TS2834. It now imports ./message.js.
  34. Core framework

    v0.9.0

    Breaking changes

    Production-hardening release covering optimistic concurrency, an idempotent tool ledger, real timeouts and cancellation, per-user isolation and new observability hooks. Includes three breaking changes.

    Breaking

    • injectq is pinned to >=0.4.0,<0.5. It is pre-1.0, so a 0.5 release could break the API. Without an upper bound it would have been picked up automatically and broken fresh installs.
    • The default user_id is now "anonymous" (it was "test-user-id"). With per-user isolation enabled, a run with no user_id previously filed itself under a placeholder that looked like a real account, which pooled every unauthenticated run into one identity.
    • A conditional edge whose condition raises now fails the run (GraphError, GRAPH_ROUTING_001). Previously the exception was swallowed and the graph fell through to the first static edge or END.

    Added

    • Optimistic concurrency control on durable state. states carries a version column with UNIQUE (thread_id, version), and writes take a per-thread row lock and compare-and-swap. A write based on a stale version raises the new StaleStateError (HTTP 409 at the API) instead of silently discarding another run’s update.
    • Durable tool-execution ledger (tool_executions, schema v3). A node replayed after a crash no longer re-fires tool calls that already completed. Entries are keyed by (thread_id, origin_message_id:tool_call_id), because a tool_call_id alone is not unique across turns.
    • Per-step durable checkpointing (durable_checkpoint_every_step, default on), so a crash replays one node rather than the whole run.
    • Node and tool timeouts (node_timeout, tool_timeout) that cancel the work, and stop requests now cancel a running node. Previously stop was only polled between nodes.
    • Real schema migrations, with a stepwise, idempotent runner guarded by pg_advisory_xact_lock so concurrent workers cannot race the DDL.
    • Per-user isolation in the checkpointer (enforce_user_isolation, default on) across state, messages and threads, plus global thread-ownership resolution. Owner-only isolation also covers the in-memory and SQLite checkpointers.
    • tenxgraph.core.authz, a module for authorization contracts and scopes, and user ID scoping in BaseStore and QdrantStore so stores honor authorization policies.
    • File ownership. Uploads record an owner, and reads by another user return 404.
    • Backpressure on background tasks (max_pending_tasks, default 1000). A slow or dead publisher sink previously grew an unbounded task set until memory ran out.
    • OpenTelemetry metrics via metrics.setup_otel_metrics(), with counters and histograms on node and tool execution and outcome dimensions.
    • Structured, correlated logging via logging.setup_structured_logging(). Every record carries run_id, thread_id and node.
    • agentflow build --k8s generates a Kubernetes manifest whose termination grace period is long enough that a rolling deploy does not kill in-flight runs.

    Changed

    • Durable storage migrates to schema v3 in place on first connect.

    Fixed

    • Lost updates on concurrent writes to one thread (see the compare-and-swap above). Reads were also non-deterministic, because ORDER BY created_at DESC had no tiebreak.
    • The realtime cache could be moved backwards, wedging a thread until its TTL expired. Cache writes are now an atomic, version-guarded compare-and-set, and a lost version check invalidates the cache so the thread self-heals.
    • Parallel tools clobbering each other’s state. Each tool now runs on its own branch copy, merged back field by field against a baseline, using a field’s reducer when it has one.
    • One failing tool orphaned its siblings, and malformed tool arguments raised JSONDecodeError through the whole node.
    • Retries on non-retryable errors. Status classification matched "500" as a substring, so max_tokens must be <= 500 was treated as a server error.
    • Cross-tenant reads and deletes of state, messages, threads and files.
    • Blocking urllib.urlopen inside async def in the cloud media store stalled the event loop for every concurrent run in the process.
    • Connection-pool and Qdrant-collection cold-start races (double creation).
    • Schema-version failures were swallowed instead of raised.

    Security

    • Rate limit bypass. The bucket key came from the leftmost X-Forwarded-For entry, which the caller controls, so a new value per request meant a new bucket and no limit at all. Proxy hops are now counted from the right.
    • Cross-tenant reads and deletes of state, messages, threads and files are closed off (see Fixed).
  35. API server and CLI

    v0.5.0

    Breaking changes

    Adds route protection, ownership and role-based authorization, observability and eval-report endpoints, and fixes a broken wheel that dropped the init templates. Production now refuses wildcard CORS with credentials.

    Breaking

    • Production refuses to start with wildcard CORS and credentials enabled. With MODE=production, ORIGINS='*' combined with credentials now raises InsecureCorsConfigError at startup. Set explicit ORIGINS, or set CORS_ALLOW_CREDENTIALS=false.
    • The authorization backend now defaults by run mode. When authorization is not set in 10xgraph.json, production now uses ownership (owner-only thread access) and development uses allow_all, instead of no backend being loaded.

    Added

    • Route guard. The server refuses to boot if any non-public route lacks a RequirePermission dependency, so a forgotten guard becomes a deploy-time error instead of an open endpoint.
    • Authorization backends. OwnershipAuthorizationBackend for owner-only isolation and RoleBasedAuthorizationBackend, which maps user roles to scopes. RequirePermission enforces the required "<resource>:<action>" scope. The authorization key accepts "ownership", "allow_all" or a "module:attribute" path to a custom backend.
    • File ownership. Media uploads record the uploader as owner, and other users cannot read the file.
    • Observability. A declarative observability block in 10xgraph.json (Logfire and LangSmith), telemetry recording for graph runs, and the /v1/graph/tools and /v1/observability/{thread_id} endpoints for tool listings and run traces.
    • Eval report endpoints /v1/evals/runs and /v1/evals/runs/{run_id} for reading local evaluation reports. These are treated as a development surface.
    • GraphInfoSchema reports is_realtime so clients can tell when a graph is a live agent.
    • py.typed marker, so type information reaches consumers (PEP 561).
    • A --integration pytest flag gates tests that need real Redis or Postgres.
    • mypy configuration and CI step, CodeQL scanning, Dependabot, and community health files (CONTRIBUTING.md, SECURITY.md, CODE_OF_CONDUCT.md, issue forms and a pull request template).

    Changed

    • Every runtime dependency now has a lower bound, and risky ones have an upper cap, including 10xgraph>=0.9.0,<2.0, fastapi>=0.116,<1.0 and pydantic>=2.13,<3. Environments that resolved older versions alongside this package may resolve differently.
    • The optional extras snowflakekit, redis and jwt gained version bounds.
    • CI runs on pushes to main and covers Python 3.12 and 3.13. The release workflow now depends on a passing test job.
    • The Documentation project URL points at the published docs site.
    • a2a.py and a2ui.py were removed from the wheel. Both were fully commented out and never mounted.

    Fixed

    • Scaffolding templates were missing from the wheel. The package-data globs dropped templates/dev/.env.example, templates/prod/.env.example, templates/prod/.python-version and templates/prod/pyproject.toml, so agentflow init failed for installs from PyPI. Packaging now ships the package tree wholesale.
    • agentflow version reported unknown when installed from a wheel. It now reads installed distribution metadata and also reports the core 10xgraph version.
    • The prod template shipped .pre-commot-config.yaml (typo), so pre-commit found no config in scaffolded projects. It is now .pre-commit-config.yaml.

    Security

    • Rate-limit bypass through X-Forwarded-For. The client IP was taken from the leftmost entry, which the caller controls, so a new value per request landed in a fresh bucket. The IP is now counted from the right using trusted_proxy_hops (default 1).
    • Cross-user access to threads and media is covered by the ownership checks above.
  36. TypeScript client

    v0.3.0

    Adds graphTools() and observability() endpoints and fixes packaging, sourcemap, typing and Node 18 issues. Dev tooling moves to vitest 3 and vite 7, clearing all reported vulnerabilities.

    Added

    • client.graphTools() lists the tools exposed by the graph’s tool nodes, grouped by node and tagged with their source (local, mcp or remote).
    • client.observability(threadId, runId?) returns the reconstructed trace (spans, events, cost) for a thread, defaulting to the latest run.
    • ESLint 9 (flat config) and Prettier, with lint, format, typecheck and check scripts.
    • CI covering lint, Prettier, tsc --noEmit, tests on Node 18, 20 and 22, and a packaging job that smoke tests the CJS and ESM entry points from a clean install. The release workflow is gated on CI, and CodeQL scanning and Dependabot were added.

    Changed

    • Upgraded vitest 1.x to 3.x and vite 5.x to 7.x, which cleared all 11 reported vulnerabilities. npm audit now reports zero.
    • tsconfig.json type-checks tests/ as well as src/, which surfaced and fixed six type errors in the test suite.
    • Twelve @ts-ignore comments became @ts-expect-error, and all of them turned out to be suppressing nothing, so they were removed.
    • Coverage thresholds were raised and pinned as a ratchet (72% lines and statements, 82% branches, 76% functions).

    Fixed

    • npm publish would have failed. Scoped packages default to restricted, so publishConfig.access: "public" was added, along with provenance: true.
    • uploadFile() threw on Node 18. File only became a global in Node 20, and the upload path did an unguarded file instanceof File, so every call failed with ReferenceError: File is not defined, including calls passing a plain Blob. The check is now guarded.
    • The build was not cross-platform. npm run build ended in cp -r dist-types/* dist/, which does not exist on Windows. tsc now emits declarations straight into dist/ through tsconfig.build.json.
    • Shipped sourcemaps did not resolve. The tarball contained 41 .map files but no sources. src/ is now included in files.
    • NodeJS.Timeout leaked into the public types, forcing browser-only consumers to install @types/node. forgetMemories now uses ReturnType<typeof setTimeout>, and Error.captureStackTrace is accessed structurally.
  37. API server and CLI

    v0.4.0

    Adds realtime audio sessions over WebSocket with connection limits and rate limiting, a global confeval.py for agentflow eval, and requires core 0.8.0 or newer.

    Added

    • Realtime audio sessions over WebSocket at /v1/graph/live, alongside the existing streaming socket at /v1/graph/ws. GraphService configures the realtime session.
    • WebSocket connection limits. A new websocket block in 10xgraph.json accepts max_connections, a per-process cap on concurrent WebSocket connections (null or 0 means unlimited).
    • WebSocket handshakes share the REST rate-limit bucket. Client key derivation is now shared between the HTTP rate-limit middleware and the WebSocket connection guard.
    • Global confeval.py discovery for agentflow eval. The nearest global confeval.py is found and used for criteria, and reports show where each case’s configuration came from.
    • Agent-skill reference docs for realtime audio agents.

    Changed

    • The minimum core dependency is now 10xgraph>=0.8.0.
    • Logging configuration and log sanitization were updated.

    Fixed

    • WebSocket error handling was improved, and GraphService now uses a consistent thread ID type for WebSocket sessions.
  38. Core framework

    v0.8.0

    Introduces the realtime audio-to-audio subsystem, with LiveAgent, AudioAgent and a Gemini Live client, plus an LLM circuit breaker, default request timeouts and secret redaction in logs.

    Added

    • Realtime (audio-to-audio) subsystem in tenxgraph.core.realtime. It includes provider-neutral contracts (RealtimeConfig, RealtimeClient and typed events such as AudioDeltaEvent, ToolCallEvent and TurnCompleteEvent), an upstream LiveInputQueue, and a GeminiLiveClient. Provider SDK imports are lazy.
    • LiveAgent and AudioAgent. LiveAgent runs the duplex session loop, dispatches tool calls through the existing ToolNode, persists finished transcripts as messages and reconnects on go_away or a dropped socket. CompiledGraph.arealtime is the entry point. AudioAgent builds and compiles a single realtime audio agent graph.
    • realtime optional extra (pip install "10xgraph[realtime]"), which pulls in google-genai.
    • LLM circuit breaker. RetryConfig gains circuit_breaker_enabled (default False), circuit_breaker_threshold (default 5) and circuit_breaker_reset_timeout (default 30.0 seconds). A failing (provider, model) pair is skipped and the call moves to the next fallback until the cooldown ends.
    • Default LLM request timeout of 600 seconds, applied to client construction for Google GenAI and OpenAI-style clients. Override it with the AGENTFLOW_LLM_TIMEOUT environment variable or set_default_llm_timeout(); read it with get_default_llm_timeout().
    • Secret redaction in logs. mask_secrets() masks common API key formats, Bearer tokens, key=value secrets and signed-URL credential parameters. This is best-effort, not a guarantee.
    • CompiledGraph can be used as an async context manager (async with graph:), which runs aclose() on exit. Calling aclose() more than once is a no-op.
    • A py.typed marker, so type information reaches consumers.

    Changed

    • Token usage is now calculated in the graph invoke and stream handlers.
    • ConsolePublisher accepts a logger.
    • Provider detection and model resolution in Agent was reworked around resolve_provider_and_model.