Skip to content

Release notes

What changed in each release of locus-sdk, newest first. The page is generated from the repository's CHANGELOG.md when the site is built, so it follows every release. Changes merged since the latest release appear under Unreleased and ship with the next version.

Upgrade with:

python -m pip install -U locus-sdk

Before upgrading a production deployment, read the compatibility and release policy and the deprecation policy, and run your policy, approval, idempotency and persistence tests against the new version. Releases are tagged on GitHub and published to PyPI.

6.0.0 2026-11-17

Added

  • Router benchmark harness. The routing corpus is a file of EvalCase objects (benchmarks/router/cases.json, tagged labelled, shape:<id>, trap, injection, ambiguous) and locus.router.benchmark adapts selection to EvalRunner's contract: a typed target that takes any RequestClassifier in the router's front seam, a free-form baseline that may name an unregistered id, and router_gate, which holds the typed router to the baseline on the whole corpus and on the traps, to 100% bounded under injection and, for a classifier under test, to no per-case regression (regressions lists the cases either way). Every target answers a protocol id, unbounded or refused, and retries a transient provider error before refusing; nothing is built or run. scripts/router_benchmark.py runs it against a model and stores the reports; tests/integration/test_router_classifier_gate.py is the same gate behind RUN_ROUTER_BENCHMARK=1, and the routing benchmark beside it reads the same file. (#342)
  • Checkpoint TTL. Every checkpointer takes ttl= (seconds or a timedelta): a checkpoint expires that long after its save and is then neither loaded, listed nor forked, and await cp.expire() removes what has expired and returns the count. Redis gets its own EXPIRE on every key a thread writes (the index hash and the tool-effect ledger's sidecar included; the index's expiry only ever lengthens, so a shorter-lived save never hides the longer-lived checkpoints); PostgreSQL, MySQL and PgCheckpointer keep an expires_at column, added to an existing table by the first save made with a ttl — a checkpointer without one issues no DDL and filters on the column only where it exists; the in-memory, file, S3, OCI Object Storage and HTTP checkpointers record it beside the checkpoint, and a load of a thread's latest falls back to its newest live checkpoint when the pointer names an expired one. (#298)
  • Checkpoint encryption at rest. EncryptedSerializer (AES-256-GCM via cryptography, pip install "locus-sdk[encryption]") seals the state before any backend stores it: encryption= on every checkpointer, a key or a key_provider callable for a vault fetch, previous_keys for rotation, and a versioned envelope that keeps the iteration readable and is bound to its place — the stored thread id, the checkpoint id and the iteration are the cipher's associated data, so a ciphertext moved to another thread or checkpoint, or an envelope whose iteration was edited, is refused. With encryption configured a plaintext checkpoint is refused too; EncryptedSerializer(..., allow_plaintext=True) loads it with a warning, for migrating a store written before encryption was turned on. The listing fields — ids, times, iteration, size, parent and the metadata passed to save() — stay in the clear so list() works without the key. (#298)
  • Per-application and per-user scoping. CheckpointScope(app_id=, user_id=) on every checkpointer (scope=) or per run (agent.run(…, scope=…), also arun, run_sync, resume, continue_turn) stores a thread under app=<app_id>/user=<user_id>/<thread_id> — a key, directory or object prefix, the thread_id column's prefix on SQL — so the same thread_id under another scope is a miss, not another tenant's thread. Each segment of the stored id is percent-encoded, so no thread id can spell a scope marker, an app-only scope sees app-level threads only, and an unscoped checkpointer never resolves a scoped id; a run's scope is resolved once and carried by a view of the checkpointer (cp.with_scope(scope)), never a context variable, with scope=None inheriting the checkpointer's scope and CheckpointScope() explicitly unscoped; list_threads(scope=) lists one scope, and unscoped data stays reachable with no scope. (#298)
  • python -m locus.runner takes its workspace from LOCUS_WORKSPACE when set, for a runner started outside an OpenShell sandbox (a gateway's local box driver, a CI job); unset, it works on /sandbox as before.
  • locus audit verify --format json. The verification of an exported audit trail as data: {"file", "verified", "records", "keys", "head_checked"} on stdout for both outcomes, where the command printed prose only and a job archiving its results had to scrape it. Exit codes are unchanged: 0 when the trail verifies, 1 when it does not. (#483)
  • locus eval gate --markdown and GateResult.to_markdown(). The gate's verdict as Markdown with one table row per failed check, for a pull-request comment, the way eval diff and eval summary already render with --markdown. The exit code is still the gate's verdict. (#484)
  • HeatWaveVectorStore — MySQL HeatWave vector store (#299). Documents live in one InnoDB table with a VECTOR(n) column, a JSON metadata column and a FULLTEXT index on the content; the store mirrors OracleVectorStore's surface (add, add_batch, get, delete, search, count, clear, close) plus hybrid_search, which blends DISTANCE() similarity with MATCH ... AGAINST relevance client-side the way the Elasticsearch store does. It probes the server once: HeatWave MySQL computes and orders by DISTANCE() on the server (server_side_distance=True); community MySQL 9+ has the VECTOR type but no DISTANCE(), so the store fetches up to candidate_limit rows and ranks them here. Metadata filters are JSON_EXTRACT equality predicates with the path and the value bound as parameters. Blocking driver calls run on worker threads (asyncio.to_thread), so the pooled connections never bind to an event loop. New heatwave extra (the same mysql-connector-python the mysql checkpoint extra installs), lazy export from locus.rag.stores, docs rows and a HeatWave vs community MySQL section, and the shared conformance suite behind HEATWAVE_DSN.
  • Control-layer conformance fixtures. conformance/v1/ holds the test vectors a port of the governance core proves parity against: canonical JSON digests in both escaping modes, unsigned, signed and rotated-key audit trails with a file per tamper class and the AuditReport each yields, policy documents with their hash, lint findings and decisions, malformed documents with the error key, approval digests, ids and decision sequences, and the exact action-admission line an admission writes. scripts/conformance_export.py regenerates them from a fixed clock and fixture keys; a unit test fails on any difference, so a format change is a deliberate v2. A dependency-free Node script under conformance/v1/tools/ recomputes the digests and verifies the signatures from the other side. (#343)
  • TLS-only Autonomous Database connections, and a config_dir of their own. Every Oracle backend — OracleBackend behind oracle_checkpointer(), OracleCheckpointSaver, OracleStore, OracleVectorStore, OracleADBLoader, OracleInDBChunker, OracleInDBEmbeddings, OracleApprovals, OracleAuditTrail, OracleReportStore and the sync twins — takes an optional config_dir, the directory holding tnsnames.ora, and passes wallet_location to python- oracledb only when a wallet is given. A database created without mutual TLS has no wallet, and naming its TNS directory as wallet_location (the only way to resolve an alias before) made the driver look for a wallet file there and fail with DPY-6005. wallet_location alone still doubles as the TNS directory, so wallet users see no change. The oracle:// approval-store and report-store specs take config_dir= and a bare one reads ORACLE_CONFIG_DIR (else TNS_ADMIN) from the environment; the Oracle notebooks require ORACLE_WALLET only for an alias that nothing else resolves. The Oracle Database 26ai page describes the TLS-only path. (#347) A wallet named by the spec or ORACLE_WALLET keeps its own TNS directory: neither variable is applied over it. The spec a store reports carries its config_dir= and wallet= percent-encoded, and OracleReportStore.spec now carries them at all, so a store built with a TNS directory reopens from its own spec.

Changed

  • Changed in 6.0: Agent(tool_call_integrity=...) defaults to True. Every tool call is signed as the model's response is parsed and verified before it runs, so a hook that rewrites event.arguments must call event.resign(by="MyHook") or the call is refused with a ToolCallIntegrityError; the built-in GuardrailsHook redaction and ExternalHooks rewrites already do. Pass Agent(tool_call_integrity=False) to keep the 5.x behaviour. (#450)
  • Unscoped thread ids that spell a scope marker are stored encoded. A thread id of the form app=… or user=… (or beginning app% / user%) on a checkpointer with no scope= is now stored percent-encoded (user=alice/chat as user%3Dalice%2Fchat), so the bare stored id can only ever be another tenant's scoped thread. A thread of that exact shape written by an earlier release is no longer found under its bare id: load it through CheckpointScope(user_id="alice") (the bare id parses as that scope's thread chat) or rename it before upgrading. Every other unscoped id keeps its bare stored form. The adapter's exists() now reads the document to honour a recorded expiry (one extra round trip), and a file checkpointer names its directories by percent-encoding the characters outside [A-Za-z0-9_-], reading a directory an earlier release named lossily while its files record the thread. (#298)
  • LiteLLM gateway example: the platform pieces the how-to promised are wired (#269). examples/litellm-gateway/ gains config.platform.yaml — the gateway of config.yaml plus the OpenTelemetry callback and the Redis response cache; docker-compose.yml selects it when REDIS_URL is set and starts a redis sidecar under the cache profile, with the Langfuse variables passed through for the alternative callback. Both configs carry an in-process PII guardrail (LiteLLM's content filter masks US SSNs and card numbers before the upstream call; Presidio is documented as the alternative). helm-values.yaml now uses the keys the chart reads (environmentSecrets instead of the ignored envFrom, the master key from the same Secret, an external Postgres without the bundled StatefulSet). The how-to gains Observability, Caching and Guardrails sections and the sequence to verify the Helm install on a cluster, which the maintainers have not run. tests/unit/test_litellm_gateway_example.py keeps the two configs in step; tests/integration/test_litellm_gateway_platform.py drives the guardrail and the cache against a live gateway.
  • RequestClassifier and ProtocolPicker, the router's two seams. Router(classifier=...) takes any async classify(text) -> GoalFrame in place of the extractor agent, which is now wrapped in AgentFrameExtractor, the default implementation of the same protocol; CognitiveCompiler(protocol_picker=...) takes any ProtocolPicker, of which LLMProtocolPicker is the one that ships. Behaviour is unchanged by default. (#342)
  • Router: LOW-complexity requests go to direct_response before any goal gate. A frame at Complexity.LOW whose risk is within direct_response's risk_max compiles to direct_response whatever its primary_goal; router.protocol.selected reports method="low_complexity_direct" and explain() mirrors it. The PolicyGate still runs, a direct_response the gate denies sends the frame down the ordinary filter-and-rank path, and CognitiveCompiler(low_complexity_direct=None) turns the rule off. direct_response also handles DIAGNOSE now, so a LOW-complexity diagnosis ranks the direct answer first by rule while MEDIUM and HIGH stay on specialist_fanout. (#342)
  • Docs: notebook 78's captured output, concept pages that link their notebooks, the environment-variable reference completed from the source, and Example: sections on BaseStore, InMemoryStore, register_provider and list_checkpointers. The concession-approval page shows the offline run (#485); the OCI Responses, multi-modal providers, events, SSE catalogue and control-layer pages link the notebooks that exercise them (#486); the variables the SDK reads but the page omitted are listed (#487); the four docstrings carry an example a test executes (#488, #489).

Deprecated

  • Reading a Redis checkpoint index written by a release before this one. redis_checkpointer() still reads the <thread_id>:_checkpoints JSON string an earlier release kept and moves it into the index hash on the thread's next save or removal, with a LocusDeprecationWarning when it does; that read ends in 7.0.0. Upgrade the processes that share one Redis store together: one still on the earlier release lists only the checkpoints it wrote itself after the move, and nothing else is lost.

Removed

  • Removed in 6.0: the locus.security compatibility shim. The old import path no longer resolves; locus.control is the import path for the names it forwarded (Evidence, Severity, ground_finding, verify, the taxonomy enums, …). The security-domain names it used to forward left Locus with the locus-sdk-security package in 5.6.0. (#464)
  • Removed in 6.0: the locus.loop package. ReActLoop, ReActLoopConfig, create_react_loop, LoopRunner, BatchRunner, StreamingCollector, create_runner, the nodes and the router no longer import; Agent (agent.run, agent.arun), EvalRunner and StateGraph conditional edges are the supported forms, as the 5.x deprecation warning said.
  • Removed in 6.0: FallbackChain.last_tier. The attribute was shared by every call on the chain; read the per-call response.metadata["fallback"] or locus.models.fallback.served_tier() instead.
  • Removed in 6.0: the tool key on the tool.integrity.refused payload (event bus and agent.tool.integrity.refused audit entries). Read tool_name, the key ToolCallIntegrityError.tool_name and the audit entries use.

Fixed

  • Two processes creating the PostgreSQL checkpoint table at the same instant no longer fail. postgresql_checkpointer() and PgCheckpointer took CREATE TABLE IF NOT EXISTS for atomic; the loser hit the pg_type unique index. The first-time DDL now runs under a transaction-scoped advisory lock on the table name and re-probes before creating.
  • LOCUS_FRONTIER_MODEL turns the knob it names. The rogue-agent challenge showed the variable in its banner but ran a pinned model; build_agent() now uses it, and the default is the model it pinned.
  • python -m locus.runner reports every command the harness ran as a harness.exec record. The runtime drained its exec records by replacing the list the harness appends to, so only commands before the first tool completion ever reached the gateway.
  • Two processes saving to one thread no longer lose checkpoint-index entries (redis_checkpointer(), postgresql_checkpointer(), mysql_checkpointer(), opensearch_checkpointer()). The adapter's <thread_id>:_checkpoints index was a read-modify-write that only a per-process lock serialised, so two adapter instances over one store dropped entries (19 of 20 in the model of #301, far fewer on a live store). Each backend now keeps the index in an operation its store makes atomic — a Redis hash (HSET / HDEL), a single UPDATE of the index row's JSON array on PostgreSQL and MySQL, a scripted _update on OpenSearch — behind the new CheckpointIndexStore protocol (locus.memory.backends), which StorageBackendAdapter uses when the store provides it and falls back to the locked read-modify-write otherwise. Ordering, max_checkpoints_per_thread, fork, list and the tool-effect ledger behave as before; a Redis index written by an earlier release is read as before and moved into the hash on the thread's next save. (#301)
  • Index follow-ups to the fix above. opensearch_checkpointer() answers False from an index removal only when the index document does not exist; a version conflict, an authorisation failure or a script error propagates instead of leaving the deleted checkpoint listed. redis_checkpointer() moves a legacy index string into the hash under a WATCH, so the process that loses the migration race no longer puts back an entry the winner had just removed, and the migrated hash carries the configured ttl_seconds even when a removal is what migrates it. StorageBackendAdapter.delete(thread_id, checkpoint_id) is True when it removed an index entry whose checkpoint was already gone.
  • oracle_checkpointer() keeps the checkpoint index atomically too. The Oracle backend was the one shipped store still on the adapter's locked read-modify-write, so two processes saving to one thread through it could lose index entries (#301). OracleBackend now implements CheckpointIndexStore: each save or removal reads the <thread_id>:_checkpoints row under SELECT ... FOR UPDATE and rewrites it in the same transaction, so concurrent writers queue on the row lock and each sees what the previous one committed; two first writers racing on the row's insert meet the primary key, and the loser retries against the winner's row. OracleSyncBackend mirrors the four methods, and the backend reads its JSON columns through one helper that accepts every shape the driver returns (dict, string, sync or async LOB).
  • Two writers saving the same key through OracleBackend at once no longer fail. save() is a MERGE, and for a key neither writer has seen both take its INSERT branch; the loser met the primary key (ORA-00001) on the shared <thread_id>:latest row and the save raised. save() now repeats the MERGE once in that case, and the row the winner committed takes the UPDATE branch. The first-time DDL raced the same way, worse: every concurrent first save ran CREATE TABLE and CREATE INDEX, and the losers failed with ORA-00955, ORA-00054 or ORA-04020. A backend now provisions once per process under a lock, a CREATE another process won reads as created, and a lock collision with that process's DDL or first writes is retried a few times, the way the PostgreSQL backend serialises its own first-time DDL.
  • Every other Oracle backend provisions its table the same way. OracleCheckpointSaver, OracleStore, OracleVectorStore, OracleApprovals, OracleAuditTrail and the evaluation OracleReportStore had the same first-time DDL: every concurrent first operation on a fresh table ran the CREATE statements, and two processes starting together failed with ORA-00955, ORA-00054 or ORA-04020. They now share one provisioning helper: one pass per instance under a lock, a CREATE another process won reads as created, a lock collision with that process is retried a few times.
  • A burst of writers on one OracleAuditTrail no longer deadlocks. record() held the trail's lock while waiting for a pooled connection, and reloading the chain held a connection while waiting for the lock; with the default two-connection pool, eight threads recording at once stopped for good. The reload now takes the lock before the connection, the order record() uses.
  • A backend with only some of the CheckpointIndexStore methods is no longer taken for one without any. StorageBackendAdapter fell back silently to its locked read-modify-write when a store defined one, two or three of the four methods, so a typo in a backend's method name put it on the racy path with no signal. The adapter now warns (LocusWarning), naming the methods present and missing, and index_methods_present() in locus.memory.backends.checkpoint_index lists what a store implements.

5.6.0 2026-11-17

Added

  • on_request / on_response on the HTTP-backed OCI models. OCIResponsesModel and OCIChatCompletionsModel (and their configs) take a pair of sync callables that see each outgoing httpx.Request after signing and each httpx.Response as its headers arrive — the seam for request-shape tests and for seeing what goes on the wire when debugging, where reaching into model._http_client() to attach httpx event hooks was the only way. Both are None by default and install nothing; model_kwargs carries them through the oci: factory.
  • Time travel on every checkpointer. checkpointer.list(thread_id) describes a thread's checkpoints newest first as CheckpointInfo records (id, write time, the state's iteration, the checkpoint's size as that backend stores it, the checkpoint it descends from — None only for a thread's first — and, for a fork, the thread it came from); checkpointer.fork(thread_id, checkpoint_id) starts a new thread from any of them, with the thread's tool-effect ledger copied up to that step and no further, so a run on the fork never replays what the parent did past the fork point; agent.run(..., from_checkpoint=...), arun, run_sync and agent.resume(..., from_checkpoint=...) continue a thread from a past checkpoint, the run's first lasting save recording it as its parent and the rest following on, so the thread's history shows the branch as a chain; the checkpoint run from is never deleted. Agent.fork and StateGraph.afork go through the checkpointer's fork. Every BaseCheckpointer has the surface through the base defaults; the in-memory, file, adapter-wrapped (Redis, PostgreSQL, MySQL, OpenSearch, Oracle), S3, OCI Object Storage and PgCheckpointer backends read the step fields without loading the state, and the versioned OracleCheckpointSaver (the reference, one row per checkpoint with a parent link) gains fork and list too. max_checkpoints_per_thread on MemoryCheckpointer, S3Backend, OCIBucketBackend, StorageBackendAdapter and the *_checkpointer() factories bounds a thread's history (FileCheckpointer and PgCheckpointer already had one); no bound ever trims a ledger sidecar, and the object-store backends order checkpoints saved within one second by the write time in their own metadata, not the listing's coarse modification time. draw_mermaid_history(checkpointer, *thread_ids) and StateGraph.adraw_mermaid_history draw the histories with a fork as a branch of its parent (node ids stay distinct for thread ids that differ only in punctuation; labels escape Mermaid's specials). The checkpointers page has the per-backend table; notebook 50 forks a thread on the in-memory checkpointer. (locus.memory.time_travel; #454)
  • SandboxBackend: the harness workspace as a documented protocol. Every harness backend now implements it over WorkspaceBackend: a lifecycle (state, start(), stop(), close(), each idempotent), declared ResourceLimits (a max_exec_s is enforced by clamping every exec timeout), and add_exec_hook(), which hands an ExecRecord of every command the backend runs to whoever holds it — after the command, so a hook that raises is logged and the result still reaches the caller. SandboxMixin gives a backend of your own all of it by overriding _start, _stop and _destroy. locus.harness.testing.assert_backend_conformance(factory) is the conformance kit: the file, shell, deadline, background-command and protocol checks the tools assume, run on a backend and reported together; run_conformance(backend) does the same without closing it.
  • SSHSandboxBackend. Any host with sshd as a workspace (the ssh extra, paramiko): commands run under a watchdog on the host so a deadline kills the process group where it runs, both streams come back in order, files move over SFTP with a cat fallback that checks the byte count, host keys are checked against known_hosts or a pinned host_key= (a key accepted under known_hosts="accept-unknown" stays in memory; the user's file is never written), and via=SSHJump(...) connects through a bastion.
  • OCIContainerInstanceBackend. An OCI Container Instance as the Oracle-native remote sandbox (the oci-container extra): create() provisions the instance from an image with sshd or a package manager, bootstraps sshd with a key pair generated for the backend, reads the container's host keys from its log and connects with them pinned, directly or through an OCI Bastion port-forwarding session for a private subnet (bastion_session_ttl= sets its lifetime; a restart past it makes a new one). A container or bastion that reports no host key is refused unless known_hosts="accept-unknown" is passed. stop()/start() restart the instance and close() deletes it and the session.
  • E2BBackend and DaytonaBackend. Thin adapters over the two hosted sandbox services' Python clients (the e2b and daytona extras), checked with stand-ins; the live tests run when the service's API key is set.
  • SandboxSpec and open_sandbox(). A sandbox named in configuration: backend="local" | "ssh" | "oci-container" | "oci-sandbox" | "openshell" | "e2b" | "daytona" | "memory" plus root, env, limits, a WarmPoolHint and the backend's options; from_mapping() reads it from a parsed YAML or JSON document and refuses unknown keys; register_backend() adds a name. SandboxPool / open_pool(spec) keep warm_pool.ready sandboxes created ahead of need, and the hint's name reaches a service-side pool (OCI GenAI Sandbox warm pools). The new sandbox backends page documents the protocol, the kit and each backend's prerequisites.
  • Durability modes. Agent(durability=...), and durability= on run, arun and run_sync, say when a run writes its iteration checkpoints: "sync" (the default, and what every earlier release did) awaits each one before the next model call; "async" schedules it and awaits every pending write before the run's final save; "exit" writes once at the end of the run. The final save and the save before an interrupt are awaited in every mode. GraphConfig.durability does the same for a StateGraph's per-step saves. Every checkpointer gets the modes through the protocol; none needed code of its own. (locus.agent.durability)
  • Tool-effect ledger. With durability="async" or "exit" (or Agent(tool_ledger=True) in any mode) the executor records every executed tool call in the thread's checkpointer the moment it returns, keyed by (thread id, step, tool name, canonical arguments), as checkpoints of the sidecar thread <thread_id>~ledger. A run that continues the turn after a crash — Agent.continue_turn(thread_id), the new Agent.resume(invocation_id=..., thread_id=...), or Agent.run(..., invocation_id=...) under the id the crashed run was started with — replays a recorded call instead of running the tool again and runs only the calls with no record; ToolResult.replayed marks a replayed result. continue_turn now also picks up a turn none of whose checkpoints landed, from the ledger's manifest. Tools not marked idempotent run at least once; Agent(rerun_idempotent_on_replay= True) lets idempotent=True tools run again on replay instead. The turn's final save clears the ledger. Temporal and DBOS segments record into the same ledger, and run_agent_segment(kind="continue") finishes an interrupted segment by replaying it. The checkpointers page has an overhead table for each mode on the in-memory and PostgreSQL checkpointers. (locus.memory.ledger; #453)
  • A2A: every binding the specification defines. Next to JSON-RPC, A2AServer serves the HTTP+JSON binding (POST /message:send, GET /tasks/{id}, POST /tasks/{id}:cancel, the push-config resources, server-sent events for message:stream and tasks/{id}:subscribe) on the same app, and the gRPC binding (lf.a2a.v1.A2AService, all eleven RPCs) on grpc_port, behind the new a2a-grpc extra. The card's supportedInterfaces lists what is on (transports=); every binding lands in one set of handlers and reports the same ErrorInfo reason on a failure. A2AClient.connect(url, prefer=[...]) / from_card(card, ...) pick a binding from the card in preference order and move to the next one when an interface is unreachable; binding= selects one outright. SubscribeToTask now streams a task's live events after the snapshot.
  • A2A push notifications. A2AServer(push_notifications= PushNotificationSettings(...)) delivers every status and artifact change to the webhooks a task registers (in SendMessage's configuration or with the *TaskPushNotificationConfig methods), with the token and Authorization the config asks for, retries, and a URL policy that refuses private addresses unless told otherwise. PushNotificationSigner signs each body (Ed25519) and publishes the key at /.well-known/jwks.json; PushNotificationReceiver is the client-side webhook that checks the token and the signature. send_message(..., push_notification_config=..., blocking=False) returns the task at once and runs it in the background.
  • A2A interrupt mapping. A run that pauses for a person — ask_user, or an approval hold from gate_tool(on_refusal="interrupt") — surfaces as the task state input-required with the question (or the hold summary) as the status message. The peer's next message on the task resumes the run through Agent.resume(); for a hold its first word decides (approve / deny), recorded on the approval store passed as A2AServer(approvals=...). An approved hold performs the call once; a denied hold ends the task rejected.
  • locus a2a card AGENT writes a v1.0 agent card from the agent's tools, skills, streaming capability and the transports named (--transport, --grpc-port, --push); --serve runs the server with that card. card_from_agent() is the same in code.
  • Six more vector stores. MilvusVectorStore (Milvus server, Zilliz Cloud, or embedded Milvus Lite from a local file), WeaviateVectorStore (local, Weaviate Cloud or embedded), ElasticsearchVectorStore (dense_vector k-NN with a flattened metadata field), RedisVectorStore (Redis Query Engine VECTOR fields with TAG filters on declared metadata keys), MongoDBAtlasVectorStore ($vectorSearch, ensure_index() creates the Atlas index) and PineconeVectorStore (serverless indexes). Each sits behind the existing VectorStore protocol with metadata_filter and has its own extra: [milvus], [weaviate], [elasticsearch], [redis-vector], [mongodb], [pinecone]; [rag] includes them all. The shared conformance suite (tests/unit/rag/store_conformance.py) runs unconditionally against the in-process stores — in-memory, Qdrant, Chroma and Milvus Lite — and against the served ones (Weaviate, Elasticsearch, Redis, MongoDB Atlas, Pinecone) only when the environment points at a running service. Closes #460.
  • Three more rerankers. LLMReranker has any registered chat model ("oci:openai.gpt-4.1", or a model object) grade the candidates in batches from a fenced prompt, so reranking needs no dedicated endpoint; JinaReranker and VoyageReranker call the hosted rerank APIs over httpx with JINA_API_KEY / VOYAGE_API_KEY.
  • Hybrid search, one switch. RAGRetriever(hybrid=True, hybrid_alpha=…) calls store.hybrid_search(query_text, query_embedding, alpha=…) on stores implementing the new HybridSearchable protocol — Oracle Database 26ai, OpenSearch, Elasticsearch, Weaviate and Milvus (enable_hybrid=True) — with the same alpha meaning everywhere (1.0 vector only, 0.0 lexical only). Stores without hybrid search fall back to vector-only search with one logged warning; supports_hybrid_search(store) and retriever.hybrid_supported report the capability, retrieve(..., hybrid=…) overrides it per call and hybrid_kwargs passes store-specific options such as Oracle's use_text_index. OpenSearchVectorStore gains hybrid_search (k-NN and BM25 legs blended client-side, no search pipeline needed).
  • Notebook 52 adds the keyless Milvus Lite path with hybrid search and the LLM reranker, and examples/config.get_embedder() builds OCIEmbeddings when LOCUS_EMBEDDING_PROVIDER=oci (or when only an OCI profile is configured), so the RAG notebooks run on OCI Generative AI without an OpenAI key.

  • Evaluators over the run's path. TrajectoryMatch (strict, unordered or subset), ToolSelection (recall and precision over the tools chosen, with forbidden tools) and ArgumentCorrectness (one tool's arguments against the expected ones, compared under the tool's parameter schema with absolute, per-argument and relative tolerances) read the evidence ledger with no model call. Each lives on an EvalCase under evaluators, is one check named by its label, loads from a case file by kind, enters the suite fingerprint, and leaves a typed EvaluatorVerdict with its provenance in EvalResult.evaluations. The runner fills an ArgumentCorrectness schema in from the tool on the agent under test.

  • A simulated user for multi-turn cases. EvalCase(simulated_user= SimulatedUser(persona=..., goal=..., max_turns=..., stop_on=[...])) has a model play that user against the agent in arun(), opening with the case prompt, until the goal is met, a stop phrase appears or the turn budget runs out. EvalRunner(simulator=UserSimulator(model)) names the model; the judge's is used otherwise. The whole conversation is graded: every reply and tool call for the checks and evaluators, the full transcript for the judge; EvalResult.transcript and stopped_by keep what happened, and a conversation that hit the budget fails simulated_user:goal_met. With a checkpointer on the agent each turn continues one thread; without one the transcript is carried in the prompt.
  • Online evaluation. OnlineEvaluator(template, judge=, sampler=, budget=) subscribes to the event bus, rebuilds each run from its agent.* events, keeps the runs every_nth(n) or fraction(share) pick within an OnlineBudget (total, per minute, in flight), and grades them in the background with the same checks and judge as a suite through the new EvalRunner.agrade(case, result). attach(run_id, prompt=, output=, arguments=) supplies what the bus does not carry; submit(prompt, result) grades a result the application holds. report() is an EvalReport whose fingerprint is the template's, so online reports diff and trend as one suite.
  • Persisted reports and locus eval trend. report_store(spec) opens a ReportStore: a directory, an Oracle AI Database table (OracleReportStore, headline figures in columns and the report as JSON), an OCI Object Storage bucket (OCIBucketReportStore) or an S3-compatible bucket (S3ReportStore), from file://, oracle://, oci:// and s3:// specs or LOCUS_EVAL_STORE. trend(store, suite=, last=) reads the last reports of a suite back with the pass and average deltas between them and marks a fingerprint change rather than reading it as a regression. locus eval run --store <spec> --suite <name> keeps the report after a run and locus eval trend --store <spec> --suite <name> prints the trend, exiting 1 when the newest report is worse than the one before it. Notebook 56 gains a trajectory case and a simulated-user case.
  • locus deploy: the agent server on OCI. locus deploy init writes a deployment directory: Terraform roots for OCI Container Instances, OKE (a bundled Helm chart installed through the Helm provider) and OCI Functions, a registry root for the OCIR repository, a Dockerfile per image shape (Oracle Linux 9, Python 3.12, non-root) and locus-deploy.yaml, the one file a person edits. plan, apply and destroy run Terraform for the chosen target; apply builds the image for the chosen architecture and pushes it between the registry root and the target root; plan, apply and destroy take --dry-run to print every command. init never replaces an existing Dockerfile or .dockerignore without --force, only appends to a .gitignore, writes a .dockerignore that keeps Terraform state and tfvars out of the image, and takes --sdk-wheel to ship a locus-sdk build that is not on PyPI. The roots share one set of variables for the Oracle AI Database checkpointer, OCI Cache, OCI Object Storage and OCI Application Performance Monitoring, authenticate the container with its own principal (resource principal, instance principal or OKE workload identity, the new oke_workload_identity auth type that every OCI auth switch in the SDK accepts and that resource_principal detects on a pod) and take secrets as OCI Vault secret OCIDs: the image starts with python -m locus.deploy.entrypoint, which resolves every <VAR>_SECRET_OCID into <VAR> before uvicorn. The generated server refuses to start without its bearer key unless allow_unauthenticated is set, and a public Container Instance needs server_api_key_secret_id or that opt-out. locus.deploy.functions runs the AgentServer app behind the Fn FDK, so the same server answers oci fn function invoke and API Gateway requests. New extras: deploy (PyYAML) and functions (the Fn FDK). The guide is Deploy to OCI, with sizing and cost notes and a deploy-on-tag workflow.
  • OpenTelemetry GenAI semantic conventions. TelemetryHook now files a run as one invoke_agent span, each model call as a chat span (CLIENT) and each tool call as an execute_tool span, with the gen_ai.* attributes (gen_ai.operation.name, gen_ai.provider.name, gen_ai.request.model, gen_ai.usage.input_tokens / output_tokens, gen_ai.response.finish_reasons, gen_ai.response.id, gen_ai.tool.name, gen_ai.tool.call.id, gen_ai.conversation.id, error.type) and the conventions' metrics (gen_ai.client.inference.usage.input_tokens / output_tokens, gen_ai.client.inference.duration, gen_ai.invoke_agent.duration / inference_calls / tool_calls, gen_ai.execute_tool.duration, in seconds with the recommended buckets). The agent lends the hook its model and tools, so the model, provider and tool descriptions need no configuration; model=, provider_name= and agent_name= override. TelemetryHook(semconv="locus-legacy") keeps the previous agent.invocation / agent.iteration.<n> / tool.<name> spans and locus.* metrics. locus.observability.semconv holds the names and a validate_spans() check for recorded traces.
  • W3C trace context across A2A. A2AClient sends traceparent (the agent's tool span when called from a tool) on every request over every binding — JSON-RPC, HTTP+JSON, gRPC metadata — and A2AServer runs a served request under the caller's trace on each of them, so a multi-agent call is one trace end to end. locus.observability.propagation (inject_trace_headers, trace_scope, current_traceparent) does the same for any other carrier; MCP _meta already carried it.
  • OCI Application Performance Monitoring exporter. locus.observability.exporters.oci_apm(endpoint, private_data_key) builds the OTLP/HTTP span and metric exporters for an APM domain (data upload endpoint, dataKey authorization) and install() sets the global providers, or adds the domain's span processor and metric reader to the providers an application has already set (once per domain); examples/observability/ carries an importable APM dashboard for agent runs, tool latency and token spend. The observability page gains an "Export" section with recipes for OCI APM and three open-source backends, and the SSE catalogue maps every bus event to the span it belongs to.
  • OracleAuditTrail. The audit trail on an Oracle AI Database immutable table (CREATE IMMUTABLE TABLE … NO DROP UNTIL n DAYS IDLE NO DELETE UNTIL n DAYS AFTER INSERT), or a blockchain table with table_kind="blockchain". Same API as AuditTrail, so admit(trail=…), gate_tool(trail=…) and governed_agent(audit_trail=…) take it unchanged; record() commits the row before it returns, several processes can share one trail (a stale writer reloads and continues the chain instead of forking it), and verify() re-reads the rows and recomputes every hash. On a blockchain table it also checks that every row carries its database-side hash (ORABCTAB_HASH$) and that DBMS_BLOCKCHAIN_TABLE.VERIFY_ROWS verifies them all. arecord() / acheck() / averify() run the same work on a worker thread for async code.
  • Chain-head anchoring in object storage. anchor_trail(trail, store, every=…) writes the current head (record count, sequence number, hash, timestamp) as a small JSON object into an OCI Object Storage bucket (OCIBucketAnchorStore) or any S3-compatible bucket (S3AnchorStore); verify_anchor(trail, store) checks the chain still reaches the latest anchor, so a trail cut short of it fails. require_retention_rule=True refuses to anchor into a bucket without a retention rule (OCI) or Object Lock (S3). anchor_periodically() is the loop a server or runner calls. The observability, control-layer and guarantees pages describe when to use each backend.
  • ControlPolicy as data. ControlPolicy.load(path_or_text) reads a policy from a YAML or JSON document and policy.dump(path, format=...) writes one; every key is a field of the same name, type and default, so the file form and the Python form round-trip and a file can never say what the API cannot. An unknown key, a wrong type or a bad value is a PolicyFileError that names the key and its path (require_human_for[2]). Reading YAML needs the optional pyyaml package; JSON and writing need nothing. policy.content_hash() is the SHA-256 of the rules, equal for equal policies however they were built.
  • The policy hash on the audit trail. admit() and admit_sync() record policy_hash on every action-admission entry, so a reader knows which rules each decision was made under. The key lives in the entry's payload: trails written before it exists verify unchanged, and readers that do not know it are unaffected.
  • Hot reload. PolicyWatcher(path, interval=...) follows a policy file by modification time and is accepted wherever admit(), admit_sync() and gate_tool() take a policy (any PolicySource with a current() method is). Each decision asks it once, so the swap is atomic between admissions; a rewrite that no longer parses keeps the last good policy in force and reports why on last_error; on_reload is called with the old and new policy when the rules change.
  • locus policy lint <file> reports unreachable-rule (a hold label that deny_for pre-empts, a cost hold at or above the spend limit, a verification bar above 1.0, a denied sandboxed tag, a zero blast-radius cap), uncovered-environment and kind-never-held for the environments and kinds the file's governs: block or --environments / --kinds declare. Exit 1 on a finding; --format json for CI. The last two are found by weighing probe actions with approve(), so lint agrees with the gate by construction.
  • locus policy explain <file> --action '{...}' prints every rule, fired or not, the outcome and whether a person can approve it; --expect allow|require_human|deny turns it into a check with the exit code, --spent-usd and --verification supply what the gate would read from a ledger and a verdict. evaluate_rules() is the one evaluation approve() and explain() share; lint_policy(), explain() and PolicyDocument are the same from Python.
  • Notebook 71 loads its policy from examples/notebook_71_refund_policy.yaml; the policy authoring guide shows the file form first and a CI lint job.
  • A model-based tool-call judge that feeds the gate. locus.control.ToolCallJudge shows a model the proposed tool call, name and arguments, with the policy's intent and optional per-tool guidance, and returns a typed allow / hold / deny verdict with a one-line reason, parsed through the structured-output path. gate_tool(judge=...) hands the verdict to admit(judgement=...), where tighten() keeps the stricter of the policy's outcome and the judge's: an allow can become a hold or a deny, never the reverse. The verdict is on the audit entry under judge (model, verdict, reason, cache hit, and the error when it failed closed) and emitted as control.judge.decided. Installed as a hook it judges every call and cancels a held or denied one; with no model of its own it borrows the agent's. Read-only tools are skipped, verdicts are cached per (tool, canonical arguments) within a run, and budget= caps model calls per run; a model error, an off-schema reply or a spent budget is a hold. (#448)
  • @tool(read_only=True). Declares a tool that only observes, so the judge does not spend a model call on it. Off by default.
  • Notebook 72 gains the judge as an optional step on the scripted test double: a staging rollout to an unpinned image, which the policy allows, is held by the judge, and the page shows the audit entry that records both.
  • Tool-call integrity (Agent(tool_call_integrity=True)). The runtime signs every tool call as the model's response is parsed, the streaming path included, over a canonical form of its id, name and arguments with HMAC-SHA256 under a random per-run key, and the executor verifies the call before it runs. A call changed in between is refused with a typed ToolCallIntegrityError, an entry on the agent's AuditTrail (the signed and received digests, and the hook the change is attributed to), a tool.integrity.refused event, and a tool error the model reads so the run continues; "abort" ends the run instead. Hooks that rewrite arguments re-sign through event.resign(by="...") or ToolCallSigner.resign, so the chain of custody names them; the built-in GuardrailsHook redaction and ExternalHooks rewrites do. The signature lives on the run, not on ToolCall, so messages and checkpoints are unchanged. Off by default in 5.x, on by default in 6.0. (#450)
  • Database-backed approval stores. PostgresApprovals, RedisApprovals and OracleApprovals implement ApprovalStore with the semantics of the in-memory store (one-use consumption, approver rules, quorums, delegations) over one row or key per held call, decided under the database's own lock, so replicas that share the store never both redeem one approval. They follow the connection conventions of the matching checkpointer backend and create their table on first use only when it is missing. Each store owns one event loop on a background thread; the ApprovalStore methods block on it and asubmit / aget / adecide / aconsume / apending await it. Every store has a password-free spec (file://…, postgresql://…, redis://…, oracle://…) and approval_store(spec) opens one; a bare database scheme reads POSTGRES_*, REDIS_URL or ORACLE_* from the environment.
  • Pending holds in the checkpoint. When a gated tool holds a call in interrupt mode during a run with a checkpointer, the hold (approval id, tool, action, asset, principal, reason, arguments, approvers so far, context, store spec) is written into the thread's checkpoint under state.metadata["_locus_pending_holds"]. pending_holds(checkpointer, thread_id) reads it back in another process, PendingHold.state(store) re-checks it, and the hold leaves the checkpoint when the call is answered. Checkpoints written before this carry no holds and resume as before. The gate's interrupt metadata gains a store key.
  • locus approvals against any store. --store takes a spec (or LOCUS_APPROVALS_STORE), a bare path still means a FileApprovals file, --by falls back to LOCUS_APPROVER, and approve / reject take --reason, recorded on the decision. ApprovalStore.decide() accepts reason="" for the same purpose.
  • Notebook 73 (support account gate) now ends with the hold parked in a file-backed store, approved from another process through locus approvals, and performed by a fresh agent resuming the thread.
  • Full reasoning control on OCIResponsesModel. reasoning takes the Responses-native object (effort, summary, ...) on OCIResponsesConfig, the constructor and as a call kwarg such as an agent's model_kwargs, and is sent as given; with reasoning_effort set too the dict wins and the effort only fills effort when the dict lacks it. Nothing is sent when both are unset. Reasoning summaries the endpoint returns surface as ModelResponse.reasoning. Before, a reasoning dict was dropped.
  • Reasoning items replayed across tool calls on the stateless path. With store=False (or after the Zero Data Retention switch) and a reasoning control set, the request asks for include=["reasoning.encrypted_content"]; the reasoning items that come back stay on the assistant message under metadata["oci_responses_items"] with the turn's function_call items, and the next request replays them verbatim ahead of the tool result, so a tool-calling turn keeps its reasoning. Turns without such items, and streamed turns, are reconstructed as before.
  • Native compaction on the OCI Responses transport. OCIResponsesModel.compact_history() posts a history to /responses/compact and returns the compacted messages: the ones the endpoint kept plus an encrypted compaction item the model replays on later requests. ContextCompactor(native_compaction=True), or CompactionConfig(native=True) on the agent, hands the summary stage to a model that offers compact_history() instead of writing a client-side summary; the system prompt and the task message stay verbatim, the CompactionEvent carries stage="native" (new value), the compaction call's tokens count against the run's budgets, and a failed call falls back to the client-side summary. Opt-in; off by default.
  • Zero Data Retention detection on OCIResponsesModel. A tenancy with Zero Data Retention (ZDR) answers every request that carries previous_response_id with a 400 saying so. That reply now raises OCIResponsesZeroDataRetentionError, a subclass of OCIResponsesStateLostError so existing handlers keep working. store accepts "auto" besides True and False: under "auto" the model starts stateful and, on that error, switches itself to the stateless path for the rest of its lifetime (store: false, full history on every request), warns once with a LocusWarning, and the agent runtime replays the interrupted turn from the history it holds, so the run completes with the same result. model.zdr_detected reports the switch and the run's event stream carries a CustomEvent named server_state_fallback. store=True still raises; store=False is unchanged.
  • Release notes on the documentation site. docs/release-notes.md is generated from this file when the site is built (hooks/release_notes.py, the {{ locus_release_notes }} token): Unreleased first, then every release from 3.0.0 onward with its date, each version anchored by its tag (#v5.5.0). Linked from the site footer, the compatibility and about pages, and the README. (#465)

  • Threads and runs on AgentServer, with a resumable event stream. POST /threads creates a thread, POST /threads/{id}/runs starts a turn (or continues a paused one with a resume payload: the /resume semantics, as a run of its own) and answers at once with a run id while the agent runs in the background; GET /runs/{id} reports its status and outcome; GET /runs/{id}/events streams it as SSE with an id: line per event and honours Last-Event-ID, replaying exactly the events a dropped client missed from the run's EventBus history; POST /runs/{id}/cancel asks the agent to stop through agent.cancel(thread_id=...) and falls back to cancelling the task. Thread state comes from the agent's checkpointer when one is configured; the threads-and-runs registry itself is in memory and bounded (RunRegistry(history_per_run=500, max_runs=200, ttl_seconds=3600), passed as AgentServer(run_registry=...)); a resume past the retained window gets a replay_gap frame. (#456)

  • WS /runs/live. One WebSocket for user turns, approval answers (resume, through the existing decision_handler and agent.resume), cancel, subscribe (follow a run from a sequence number) and the events of every run started or subscribed on it. Bearer header or ?token=. Voice frames are not carried: locus.voice sessions remain application-driven.
  • AG-UI and Vercel AI SDK UI message stream adapters. POST /ag-ui takes a RunAgentInput and streams RUN_STARTED, TEXT_MESSAGE_*, TOOL_CALL_*, STATE_SNAPSHOT / STATE_DELTA, CUSTOM and RUN_FINISHED / RUN_ERROR; POST /vercel-ai takes a UI message request and answers an x-vercel-ai-ui-message-stream: v1 stream (start, text-*, reasoning-*, tool-input-*, tool-output-available, data-*, finish). Both are also available for any run as GET /runs/{id}/events?protocol=ag-ui|vercel-ai, resume included. The conservative readings of the two protocols are recorded on the server page. examples/server_ui/ holds two plain HTML pages (resumable SSE, and an AG-UI client); notebook 65 follows, drops and resumes a run.
  • GET /threads/{id} now adds the thread's runs and a source field, answers from the registry when no checkpointer is configured, and no longer fails with a 500 for a runnable without config (a GraphRunnable); DELETE /threads/{id} forgets the thread's finished runs as well.
  • Tiered compaction. TieredCompaction([ClearToolResults, SlidingWindow, Summarize, Relevance]) (locus.memory.tiers) runs compaction tiers in order, each at its own trigger as a fraction of the usable window (0.5, 0.7, 0.85 and 0.95 by default): stale tool outputs become stubs, the oldest turns past a turn window are dropped, older history is summarised by the existing summariser and, as a last resort, only the turns relevant to the current task stay (by embeddings with an embedder=, by recency without one). A Native tier hands the stage to a model's own compaction endpoint (default_tiers(native=True)). The window comes from the model's metadata, or context_length=. Pass conversation_manager=TieredCompaction(...) or CompactionConfig(tiers=True | [...]); the agent binds the pipeline to its model and window. One CompactionEvent per tier that ran, with tier and the tokens before and after it; stage gains "window" and "relevance".
  • Pinned messages. pin(message) (or metadata={"pin": True}) and a pins= predicate on TieredCompaction keep a message verbatim through every compaction stage and tier, in ContextCompactor too; a pinned tool result keeps the call that produced it.
  • ToolResultOffload. A tool result over threshold_chars (16,000) goes to a ToolResultStore the moment it is produced; the message keeps a handle and a preview, and the fetch_tool_result tool, registered with the offload, reads the stored text back a page at a time. The handle travels in the message text, so it survives checkpoints and compaction (a cleared stub names it). AgentConfig(tool_result_offload=...), or True for an in-memory store. The coding harness includes the same fetch_tool_result whenever its HarnessConfig names a result_store, and the bash note says so. ToolResultStore.put() stores a result whatever its size and returns its key.

Changed

  • TelemetryHook default span and metric names. The GenAI conventions are the default; dashboards and alerts built on agent.invocation, tool.<name> or the locus.* metrics keep working with TelemetryHook(semconv="locus-legacy"). Tool spans are now keyed by tool_call_id, so parallel calls to one tool each get their own span. The hook keeps its state per run: concurrent arun() calls on one Agent are one trace each, a sub-agent run from inside a tool files under that call's execute_tool span, a hook-requested model retry gives every attempt its own chat span, and a run that fails closes the model, tool and iteration spans it left open with error.type. gen_ai.token.modality on the token counters is unknown unless the provider's usage breaks the count down by modality.

  • OCIResponsesModel defaults to store="auto". Before, the default was store=True and the first tool-call continuation on a ZDR tenancy failed the run with OCIResponsesStateLostError. The first request of a run is unchanged; only the ZDR case now completes instead of failing. Pass store=True to keep the old behaviour, or store=False on a tenancy known to be ZDR to skip the one stateful attempt.

  • OAuth 2.1 for remote MCP servers. MCPClient(oauth=MCPOAuth(...)) signs in to a Streamable HTTP server that answers 401: authorization code with PKCE, discovery of the protected-resource and authorization-server metadata, dynamic client registration (or a hosted client-metadata document via client_metadata_url), token refresh, and a browser hand-off with a loopback listener that a headless process replaces with its own redirect_handler / callback_handler. Tokens live in a pluggable store: InMemoryTokenStore (default), FileTokenStore (a 0600 file under the user's config directory) or KeyringTokenStore (the optional keyring package). No token value is logged. An Authorization header or a static access_token still wins over OAuth.
  • Toolset shaping on MCPClient. include= and exclude= take server tool names or globs, prefix= renames what is imported, so two servers mount without name clashes. Order: allowed_tools and include narrow, exclude removes (and wins over include), tool_filter decides last, prefix is applied after matching. Calls through either name land; a shaped-out tool raises MCPToolNotAllowedError.
  • Elicitation. A server that asks the person a question mid-call pauses the agent run through the interrupt mechanism: an InterruptEvent whose fields describe the requested schema and whose metadata carries mcp_elicitation. client.answer_elicitation(event, answer) then agent.resume(answer, perform_dangling=True) re-issues the call with the answer. elicitation_handler= answers without pausing (and outside a run); with neither, a question outside a run is declined. MCPElicitation and ElicitationAnswer are the types. An agent served by LocusMCPServer has its own ask_user questions relayed to the MCP client as elicitations through run_agent_stream.
  • W3C trace context in MCP _meta. Every tools/call the agent makes carries traceparent / tracestate parented to the telemetry hook's span for that tool call (TelemetryHook now exposes it through current_tool_span()), and every call LocusMCPServer serves runs under the context its _meta carries, so an MCP hop stays inside one trace. propagate_trace=False opts out; locus.integrations.mcp_tracing holds trace_meta() and trace_scope() for other servers.
  • locus mcp serve <target> exposes an agent (MODULE:ATTR / FILE.py:ATTR, an Agent, a factory, a Tool or a list of tools) or a bare module of @tool functions as an MCP server over stdio (default) or Streamable HTTP (--transport http --host --port --path). create_tool_server(tools) and LocusMCPServer.build() are the same from Python. The MCP concept page covers the auth flow, shaping precedence, elicitation, tracing and the command. (#457)
  • The Codex skill covers the new surface. .agents/skills/locus/ (what locus codex init places) teaches the policy file form with locus policy lint / explain and PolicyWatcher, the tool-call judge and @tool(read_only=True), tool-call integrity, the database approval stores, approval_store() and pending_holds(), OracleAuditTrail and the object-storage anchors, the OCI Responses store="auto", Zero Data Retention, reasoning and native-compaction controls, the server's threads and runs, Last-Event-ID resume, WS /runs/live and the AG-UI and Vercel AI SDK adapters, and the evaluation primitives (rubrics, evidence receipts and claims, reliability, report diffs and EvalGate), each with a snippet that runs against the installed SDK. The skill test's wire-type exclusion now also covers the A2A JSON-RPC envelope, parameter and push-notification types. (#492)

Fixed

  • Compaction token accounting counts what is replayed. The default token counter (ContextCompactor, TieredCompaction, LLMCompactor) charges for the metadata items a transport replays on the wire — the encrypted compaction item native compaction leaves on an assistant message and the replayed reasoning items of the OCI and OpenAI Responses paths (locus.memory.compactor.REPLAYED_METADATA_KEYS). tokens_after of a native compaction could shrink while the replayed request grew, as the item's few KB were counted as a one-line placeholder; the report and the request now move together. Other metadata stays free.
  • tool.integrity.refused carries tool_name. The event named the tool under tool while control.judge.decided and the agent's tool events use tool_name; both control events now share the key, and the audit-trail record of a refusal carries it too.
  • Agent.run_sync() inside a running event loop no longer hangs on MCP tools connected on that loop. The run is driven on a worker thread's own loop, which cannot reach an MCPClient session bound to the caller's; the first tool call waited forever. run_sync now raises a RuntimeError naming the client and the fix (await agent.arun(...)), and the MCP getting-started page uses the async form.
  • A stdio MCP server starts with this process's environment. MCPClient(server_command=...) passed no env, so the mcp SDK started the server with a stripped environment (PATH, HOME, USER …) and a server needing PYTHONPATH, an OCI profile or an API key died during the handshake with a bare Connection closed. The server now inherits os.environ (inherit_env=False for the SDK's minimal one), env= adds variables, and a server that exits during setup is reported with the last lines it wrote to stderr.
  • Explicit-completion runs carry their answer. A run that ended through task_complete had TerminateEvent.final_message=None and AgentResult.message == "", so LocusMCPServer's run_agent and run_agent_stream returned "Agent completed without response" after a relayed ask_user. The final message is now the terminal tool's result / summary argument, else the assistant text of the turn around the call. The loop also tells the model once, after a reply with no tool call in completion_mode="explicit", that such a reply ends nothing and task_complete(summary=...) does — before, the same context went back unchanged until the budget warning, which cost a dozen iterations for a one-line answer.
  • auth_type="api_key" is accepted by OCIChatCompletionsModel and OCIResponsesModel. The value every other OCI auth switch in the SDK — and LOCUS_OCI_AUTH_TYPE — takes as its default was rejected by the V1 transports, so the image locus deploy builds could not run locally with a profile. api_key (and security_token) now mean the profile path: profile= when given, else OCI_PROFILE, else DEFAULT.
  • Agent.run_sync() inside a running loop keeps the caller's context variables. The worker thread ran without contextvars.copy_context(), so the OpenTelemetry context was lost: an agent served over MCP through run_agent filed its invoke_agent span in a fresh trace with no parent, although LocusMCPServer had set the caller's trace from _meta. The thread now runs the coroutine inside a copy of the caller's context.
  • oci_apm().install() on a MeterProvider already in place flushes the reader it adds. OpenTelemetry's MeterProvider.force_flush() and shutdown() visit only constructor-time readers, so the documented meter_provider.shutdown() exported nothing from the reader install() had added and the last interval's metrics were lost. install() now returns an OCIAPMInstallation — still the (tracer_provider, meter_provider) pair — whose force_flush() and shutdown() reach what it added; when it joined existing providers that shutdown() is also registered with atexit.
  • validate_spans ignores foreign-scope spans. With FastAPI's native POST / or the mcp package's MCP send … spans in the same exporter the checker reported "root span 'POST /' is not an invoke_agent span" and "spans belong to 3 traces". When spans come from more than one instrumentation scope, only the telemetry hook's (scope= "locus.hooks.telemetry", the default) are checked; scope=None checks everything. SpanRecord records the scope.
  • OCIContainerInstanceBackend connects through an OCI Bastion with the default known_hosts="strict". The service reports no host key for a port-forwarding session (bastion_public_host_key_info is empty), so the strict default refused every bastion path with "reports no host key". The bastion's key is now the one in known_hosts or, failing that, the key the endpoint presents at the first connection, read once with locus.harness.ssh.learn_host_key and pinned for the session (an INFO line says so); the container's keys are still pinned from its log, and known_hosts="accept-unknown" stays the explicit unverified opt-in. The unit stand-in for the bastion now reports no key, as the service does.
  • A key the bastion or the container refuses is reported as such, in time, with the container log. create() retried an AuthenticationException until the whole ready_timeout ran out, then deleted the instance and the log that said why, and the error could not say whether the bastion or the container's sshd had closed the connection. A failure at the jump is now an SSHJumpError (new, exported from locus.harness) that records whether the jump had accepted the key; a refused key, or a bastion that accepts the key and then closes the connection — what an OCI Bastion does when the client's address is not in its client CIDR allow-list, which it checks after authentication — is retried for AUTH_GRACE (90 s) and then raised, naming the bastion or the container's sshd and carrying the last 30 lines of the container log with key material redacted, before the instance is deleted. Transport failures are retried to the deadline as before; a host key that does not match is still raised at once.
  • SandboxSpec refuses a field of the wrong type when it is built. SandboxSpec(limits=5) was accepted and the first exec failed with AttributeError: 'int' object has no attribute 'bound'; backend, limits, warm_pool, env and options are now checked in __post_init__ (TypeError), as from_mapping already did for mappings.
  • Streamed tool calls on the OCI Responses transport keep their name and call id. stream() only read the argument deltas, which carry the stream item id and no function name, so a streamed tool call came back as name="" keyed by the item id while complete() returned the real name and call_id. The parser now reads response.output_item.added and .done for function_call items and the accumulator keys by the call id, so streamed and non-streamed turns are identical and a streaming agent on the stateless path executes its tools.
  • Report stores read back a report stored under a caller's id. put(report, suite=..., report_id="build-42") on the file, OCI Object Storage and S3 stores wrote the object and then get(), list() and trend() never found it, because the object-name parser accepted only the generated 32-hex ids. The id is now encoded in the object name and read back exactly, whatever the string, and reports already stored under generated ids read as before.
  • A held-back summary tier no longer ends the run before the cheaper tiers run. With a TieredCompaction whose Summarize tier sat before ClearToolResults or SlidingWindow, a summary needed again within min_iterations_between_summaries iterations ended the turn context_exhausted with most of the window still free and the turn's task lost. The guard now holds that tier back for the pass and the tiers after it still run; the pass is exhausted only when the context is still over the highest trigger after the last tier.
  • OCI model ids have a context window. metadata_for("oci:openai.gpt-4.1") and the bare openai.gpt-4.1 an OCIChatCompletionsModel carries returned None, so every agent on an oci: model logged "No context window known" and fell back to a message window instead of the default ContextCompactor. An OCI <vendor>.<model> id now resolves the entry of the model it serves, the oci: prefix is recognised, and the models only OCI serves this way (meta.llama-3.3-70b-instruct, meta.llama-4-maverick-17b-128e-instruct-fp8, cohere.command-a-03-2025, cohere.command-r-plus-08-2024, google.gemini-2.5-pro, google.gemini-2.5-flash, xai.grok-4) and gpt-5.1 have entries with the windows their documentation states.
  • OracleCheckpointSaver.list() returns aware UTC times. Its CheckpointInfo.created_at came back timezone-naive (the driver drops the zone of the TIMESTAMP WITH TIME ZONE column), while the adapter, PostgreSQL and object-store backends return aware UTC datetimes, so comparing or sorting infos across backends raised TypeError. The saver attaches UTC, and parse_time reads a naive value as UTC wall-clock time, so every backend agrees.
  • Agent(checkpointer=OracleCheckpointSaver(...)) is refused at construction. It was accepted and failed on the first run with AttributeError: ... has no attribute 'load'. The agent now raises TypeError when the checkpointer has no load / save, naming BaseCheckpointer and, for the saver, oracle_checkpointer() as the Oracle checkpointer an agent takes; the saver stays the versioned history your code drives.
  • MilvusVectorStore.close() stops the embedded Milvus Lite server. MilvusClient.close() only drops the connection; the in-process server kept running until interpreter exit, flushed then, and recreated the database directory a caller had removed after close() (notebook 52 Part 5 left a locus-nb52-* directory behind). close() on a local .db uri now releases the server for that file, so the directory stays removed, and the store loads an existing collection when it opens one, so a file reopened after close() or in a new process is searchable.

Deprecated

  • The tool key of tool.integrity.refused. It repeats tool_name for this release and goes away in the next; read tool_name.
  • The locus.security compatibility shim is removed in 6.0. It keeps forwarding the control-layer names to locus.control until then; its warning named a release that has long passed and now says 6.0. Import from locus.control.

Removed

  • The locus-sdk-security package. The security-domain tooling (red-team probes and jobs, Target, SecurityContext, the SOC analyst and PostureReport grounding, the intel / SIEM / EDR / scanner / fingerprint adapters, the IR playbooks, notebooks 81–89 and their documentation pages) is no longer part of this repository. It last shipped at the v5.5.0 tag. The locus.security compatibility shim keeps forwarding the control-layer names to locus.control; its security-domain names now raise an ImportError that says so. The release workflow no longer builds the package.

5.5.0 2026-11-16

Added

  • Reasoning effort on OCIResponsesModel. OCIResponsesConfig takes reasoning_effort (also a constructor argument), sent as reasoning={"effort": ...} on both complete() and stream(). A reasoning_effort call kwarg, such as an agent's model_kwargs, overrides it for that call. Unset, no reasoning field is sent, so the request body is unchanged. Before, reasoning_effort passed to the constructor or in model_kwargs was dropped without a warning.

Fixed

  • OCIResponsesModel.stream() error bodies. A non-2xx on the streaming path was raised as httpx.ResponseNotRead, because the error body had not been read when it was classified. The body is read first now, so the typed exceptions and the server's message surface exactly as on complete(). Classification also reads the error's param field, so an envelope that names previous_response_id there rather than in the message still maps to OCIResponsesStateLostError.
  • OCIProjectRequiredError on a 400. The Responses endpoint signals the project requirement for non-OpenAI models with a 400 naming the OpenAI-Project / opc-conversation-store-id header. That is now mapped to OCIProjectRequiredError instead of a plain RuntimeError.
  • project_ocid reaches the Responses endpoint. It was sent only as opc-project-id, which the endpoint does not read for this requirement, so following the exception's advice changed nothing. The OCID now also goes out as OpenAI-Project; with it a non-OpenAI model answers on /responses.

5.4.0 2026-11-10

Added

  • The rubric as data. locus.evaluation.Rubric names the dimensions a judge scores 0-100, each with a weight and a line of guidance, plus optional letter bands (Rubric.default_grades() offers A 90 / B 75 / C 60 / D 45 / F 0) and a pass_score. The weighted composite, the letter and the pass are computed by code; missing dimensions count as zero rather than vanishing from the average. Rubric.revision() hashes the rubric and the judge prompt so two reports are comparable only when it matches. Rubrics load from JSON or YAML (Rubric.load). An EvalCase.rubric may be a string, as before, or a Rubric.
  • Typed verdicts with provenance. Verdict carries grade, dimensions, issues, the judge's advisory judge_reported_passed / judge_reported_score, and a JudgeProvenance (judge model id, rubric revision, prompt hash, temperature, seed, channel, token usage, self_graded). EvalResult exposes grade and the full verdict; EvalReport adds grade_distribution.
  • A structured judge channel with pinned sampling. LLMJudge sends temperature=0.0 by default, takes an optional seed and timeout_s, and receives the verdict through a submit_verdict tool call where the model takes tools (channel="auto"), falling back to a plain-JSON reply; channel="text" never offers the tool. The response under grading is delimited and declared as data in the prompt.
  • The run's own evidence as checks. EvidenceLedger lays the run's tool executions out as rows with stable ids (E0, E1, ..., P for the prompt). EvalCase.require_receipts fails when a figure, identifier, date or quoted string in the answer appears in no row; EvalCase.claims are confirmed by code when the evidence carries their figures and settled by the judge otherwise, through a submit_claim_checks tool call whose citations are verified against the rows (a quote not in the cited row downgrades the check to unverifiable); EvalCase.grounding runs the GSAR audit over the answer and the ledger with the judge model. Results carry receipts, claim_checks and grounding_score.
  • Control-layer assertions. EvalCase.forbidden_tools passes when the tool never executed, where a call the gate refused did not execute; EvalCase.expected_refusals passes when the gate answered denied or held_for_approval at least once. EvalCase.expected_tool_calls matches a call on its arguments (ToolCallExpectation).
  • Budgets. EvalCase.max_total_tokens and max_cost_usd read the run's metrics; a target that reports none fails the check.
  • Rubric caps. Rubric.caps drop the grade to a ceiling when a contradicted claim, a missing receipt or an ungrounded answer is found; the runner applies them after the verdict and records caps_applied.
  • Repeats. EvalRunner(repeats=) or arun(cases, repeats=) reads every case several times. A case passes only when every graded reading passed (pass^k), the reading shown is the most pessimistic, EvalResult.samples keeps them all, and EvalResult.consistency flags a case whose readings disagreed by more than the gate; the report counts unstable cases and the summary prints pass k/n.
  • Judge panels and second opinions. EvalRunner(judges=[...]) grades every judged answer with each judge; the first scores the case, EvalResult.panel records the panel's agreement and EvalResult.trust the decision between the first two judges (trusted, calibration_required, rejected), which the summary prints.
  • Pairwise comparison in both orders. LLMJudge.compare asks which of two answers better satisfies the rubric, once in each order; a preference that flips with the position is a tie with consistent=False.
  • locus.evaluation.reliability. Pure functions over verdicts and grade pairs: consistency, panel_agreement, trust_decision, cohen_kappa, calibration_drift, wilson_interval, bootstrap_ci and publication_gates.
  • Comparable reports. Every EvalReport carries a fingerprint of the cases it measured (suite_fingerprint), by_tag counts, check_failures, the judge models and rubric revisions seen, and save / load / to_markdown. diff_reports compares two reports case by case (regressed, improved, added, removed, score and dimension deltas, newly failing checks) and refuses two different suites unless forced. EvalGate is the rule a build applies (pass rate, average, not graded, unstable, and against a baseline no regressions or a bounded average drop), reporting every reason it failed.
  • Cases as data. load_cases reads a JSON, JSONL or YAML file of cases, with a top-level rubric applied to cases that name none; dump_cases writes one back.
  • locus eval. run loads cases and an agent (and optionally a judge and a rubric), prints the report, saves it and exits with the gate's verdict; diff, gate and summary work on saved reports, with --markdown tables for pull-request comments. How-to: Evaluate an agent in CI.
  • Notebook 56 now covers the rubric with a judge, receipts, repeats and a saved, diffed, gated pair of reports.

Changed

  • A judge that returns no verdict leaves the case not graded. An empty reply, prose without JSON, a call to another tool or no scored dimension is Verdict(abstained=True). The result carries not_graded_reason, the report counts it under EvalReport.not_graded and leaves it out of failed and avg_score, and the summary prints [NOT GRADED] with the reason. The judge_unparseable:... check is still recorded, so nothing that used to be visible is hidden.
  • Self-graded suites are named. When the judge model id equals the model under test, provenance.self_graded is stamped and the report summary ends with a warning. The case is not failed for it.

5.3.2 2026-11-02

Fixed

  • The locus.testing doubles report a context window, so an agent built on ScriptedModel, FunctionModel or CompromisedModel counts tokens as it does for a provider instead of warning that no window is known for model <unnamed>. context_window= shrinks it for a compaction test; None keeps the message-window path.

5.3.1 2026-11-02

Fixed

  • locus codex run passes the arguments after -- to Codex in the order typed, whichever side of -- the prompt is on; -- -m <model> "task" used to reach Codex scrambled. --help names the Codex profile file (~/.codex/<name>.config.toml) correctly.
  • The retrieval scenario's check in codex/scenarios/ accepts make_retriever() as a plain function or as a coroutine.

5.3.0 2026-10-30

Added

  • Codex scenarios. codex/scenarios/ is a series of twelve tasks Codex builds from the Locus skill alone, each with a PROMPT.md and a check.sh that runs in the project Codex built: a gated refund with its audit trail, a hold a person approves and a resumed run, a StateGraph fan-out, a retrieval tool, the coding harness behind the gate, a checkpointed conversation, an agent served over HTTP, an orchestrator with specialists, a typed answer with a termination rule and an evaluation, an agent on OCI Generative AI, the permission rules of a coding agent, and a playbook with a custom hook. python codex/scenarios/run.py runs them in empty directories through locus codex run --exec and prints a summary table; --locus-install points Codex at a checkout, so a change to the SDK or the skill is tried the way an application would use it. The skill gains a fifth reference, extending-and-advanced.md (subagents, voice sessions, external hooks, tool sandboxes, custom model providers, the ReAct loop, core protocols and settings, DeepAgent internals, graph evaluation, the remaining router, memory and observability surface), the four existing references name the rest of each package's public surface, and tests/docs/test_codex_skill.py measures that coverage against every package's __all__ so it cannot regress.
  • Codex builds on Locus. The repository ships a Codex skill, .agents/skills/locus/: a SKILL.md that gives a coding agent the shape of the SDK (the agent and its tools, the admission gate, the shapes, memory and RAG, the harness, the providers, offline tests) and four reference files with every option, each snippet checked against the installed SDK by tests/docs/test_codex_skill.py. The wheel carries the skill, and locus codex places and uses it: init puts it in a project's .agents/skills/locus with a Locus section in AGENTS.md, or in ~/.agents/skills with --home; run installs it where it is missing and starts Codex with the sandbox settings its recipes need (--exec, --codex-profile, and anything after -- go to Codex); path prints the bundled copy. examples/codex-on-oci/ is a loopback LiteLLM gateway that signs Codex's own model calls with an OCI profile, so Codex runs on OCI Generative AI and needs no account elsewhere. The how-to page and the README section describe all three.

Fixed

  • OCI_REGION selects the region for oci: model strings. The provider guide and the environment-variables page said so; the factory behind Agent(model="oci:...") only read OCI_PROFILE and sent every request to the default region. It now takes LOCUS_OCI_REGION, then OCI_REGION, when neither region= nor base_url= is given; the default stays us-chicago-1.

  • The harness examples decide by label. The ControlPolicy shown with build_harness(..., wrap=gate_tool) on the README, the landing page and the harness pages now sets require_verification_score=0.0; with the default score every harness call, reads included, was held for a person because no verification verdict accompanies a workspace tool call.

5.2.0 2026-10-29

Added

  • OCI GenAI Sandboxes as a coding-harness workspace. locus.harness.OCISandboxBackend runs the harness tools in an OCI Enterprise AI sandbox (pip install "locus-sdk[oci-sandbox]", oci 2.189.0+). create(project_id, ...) makes a sandbox and deletes it on close(); connect(sandbox_id, ...) attaches to one; extend() adds lifetime. Commands stream with their output order kept, run under an in-sandbox deadline, and return at most 900 kB of output, because the service loses larger output. Background state lives in /workspace/.locus-harness (/tmp is read-only there), now in SKIP_DIRS.

Changed

  • locus-sdk-security ships from the repository, not from PyPI. The 5.1.0 notes said the release workflow publishes it; the upload needs a PyPI project that does not exist, and the package is one install line from the repository at the matching tag, so the workflow publishes locus-sdk alone again and the install instructions say so.

  • Documentation site: the coding harness has its own section, and the site reads on a phone. Concepts gains a "The coding harness" group with an overview and one page each for OCI GenAI Sandboxes and NVIDIA OpenShell; the home page names the sandbox in its hero, in the Oracle Cloud grid and in the harness grid with an end-to-end snippet. Every page was re-laid for 360 to 768 px: the title gets the full column with the page actions on their own row, diagrams fit the column and expand full-screen at their design width, tables that cannot be read at phone width render as cards, filter inputs are 16 px so iPhone Safari does not zoom, and touch targets are finger-sized. The header shows the released version from the build instead of a badge image that could be served stale from a cache.

Fixed

  • OCI Generative AI, OpenAI-compatible transport: a tool-call-only assistant turn no longer breaks the conversation. Such a turn has no text; OpenAI accepts "content": null for it, OCI's endpoint answers 400 Invalid type for 'messages[n].content': expected an object, but got null, and since the history is replayed on every later turn one tool call ended the run. The transport now sends "" for every vendor on OCI.
  • Cognitive router: a capability listed twice compiles once. An extractor that repeats a capability id made the compiler bind the same tool twice and the agent's registry rejected it (Tool already registered). Ids are de-duplicated before binding.
  • The a2a-mesh example routed no requests, and spoke only the pre-v1.0 surface. A2AClient.get_agent_card() returns v1.0 cards whose skills are AgentSkill objects, but the orchestrator matched them as strings, so every query failed with "No peer advertises skill". The orchestrator now routes on skill ids, prints each peer's protocolVersion and supportedInterfaces, and talks A2A v1.0 JSON-RPC: SendMessage, with the reply read from the task's artifacts, and SendStreamingMessage for --stream. --legacy keeps the flat /a2a/invoke and /a2a/stream endpoints to show backwards compatibility. The web console does the same: it discovers peers from /.well-known/agent-card.json, sends with SendMessage and renders the SendStreamingMessage task events. Tests cover the v1.0 card, both methods and routing on v1.0 skill ids (#274).

5.1.0 2026-10-29

Added

  • Intent meanings in the goal frame. GoalFrame.primary_goal carries one line per TaskType (TASK_TYPE_GUIDE), so an extractor model sees what separates plan from build or research from diagnose instead of thirteen bare names.
  • locus-sdk-security on PyPI. The release workflow publishes the security package next to locus-sdk, so pip install locus-sdk-security replaces the install-from-repository line; the two stay in lockstep.
  • Build it with Codex. codex/SPEC.md and codex/PROMPT.md drive a coding agent through the Quickstart and the first controlled action from a clone: a fresh environment, a first agent with a typed tool against the provider the operator names, the admission gate allowing, holding and denying, and the rogue-agent challenge, each step with its checkpoint. AGENTS.md at the repository root carries the rules a coding agent follows here. The site gains the how-to page and the README a section; tests/docs/test_codex_spec.py keeps the files the specification quotes identical to the guide pages.

Changed

  • Cognitive router: a request too risky for its shape is held, not refused. When every protocol that handles a frame's intent caps risk below the frame's, the compiler used to raise NoMatchingProtocolError: a HIGH-risk plan, diagnosis or question had nowhere to go. It now compiles onto approval_gated_execution and is always held for approval, whatever the gate's thresholds; router.explain() reports the choice as method="risk_fallback". CognitiveCompiler(risk_fallback=None) restores the error, and a goal no protocol handles still raises.
  • Cognitive router: canonical fit outranks cost distance when adjacent. The ranker put cost-to-complexity distance first, so a MEDIUM-complexity research request landed on handoff_chain (a coordination shape) and a HIGH-complexity coordination on specialist_fanout. A protocol that lists the goal in primary_for now wins whenever its cost is within one step of the frame's complexity; a LOW-complexity task still never gets a HIGH-cost shape for being canonical.
  • Cognitive router: debate accepts MEDIUM risk. A debate weighs options and recommends; it changes nothing. Capped at LOW, a comparison the extractor rated MEDIUM risk fell through to specialist_fanout; on the Frankfurt benchmark that was two of Llama 3.3 70B's seven misses.
  • Routing benchmark gates on what the router guarantees. The typed-frame-versus-free-form accuracy comparison is printed as data rather than asserted: on OCI Generative AI it goes both ways by model (Cohere Command A beats the free-form baseline, Llama 3.3 70B does not). The assertions are the structural ones: selections stay in the registered set, including under prompt injection.

Fixed

  • locus.testing.tool_call could not script the harness write tool. The helper reserved content for the assistant's text, so a tool argument of that name (write(path, content)) was silently dropped and the tool failed with a missing-argument error. tool_call(name, arguments={...}) now takes the arguments as a mapping, for any tool whose argument is named like one of the helper's own parameters; keywords still work and win on a repeated key.

5.0.0 2026-10-29

Added

  • Sandbox image and OpenShell providers from OpenShellBackend.create. image= picks the container image; providers= attaches OpenShell providers, whose credentials stay at the gateway while the sandbox sees a placeholder the sandbox proxy swaps in at the provider's endpoints. The live test exercises OpenShell's oci-genai profile: a sandboxed curl reaches OCI Generative AI without the key. examples/openshell-gateway/ provider.py imports a profile and creates a provider where the OpenShell CLI is not installed.
  • A local NVIDIA OpenShell gateway for the coding harness. examples/openshell-gateway/ starts the gateway with docker compose up -d (loopback, Docker-outside-of-Docker, adapted from NVIDIA's reference deployment) so OpenShellBackend and the live harness tests run on any machine with Docker; LOCUS_OPENSHELL_ENDPOINT=127.0.0.1:8080 points at it. The README lists the one host requirement (Landlock in the kernel's active LSM list). The live tests name their sandboxes within OpenShell's 19-character limit.

Changed

  • CloudSource.describe / events take a keyword-only client. OCI services expose several SDK clients (core alone has five), so the SecurityContext().cloud port names one; when omitted it resolves the service's only client and otherwise returns an error dict listing them. Third-party CloudSource providers should accept the new keyword.

  • Documentation site: diagrams instead of ASCII, and a Markdown twin of every page. The sixteen diagrams the site drew as text inside code blocks (the provider tree, the OCI transports, the memory layers, the admission gates in notebooks 72–75, the incident-response, concession and contract workflows, the EventBus, the audio pipelines, in-database embeddings and scatter-gather) are SVGs drawn from the SDK source, themed with the page, and checked against the code. The Memory page's five-column table that wrapped class names mid-token is a diagram plus a prose table, and identifiers in any table no longer break mid-token. Build facts and requirements show as a row of tiles rather than key/value tables. The colour scheme follows the operating system on first visit, with a three-way toggle; pages carry previous/next links, edit and view-source actions, and a Copy page button that copies the page as Markdown. Every page is also published as Markdown at <page>/index.md, with /llms.txt and /llms-full.txt for tools that read the site that way (hooks/llms_txt.py). The captured output on the cloud-resource gate, red-team and SOC-triage notebook pages is refreshed to what the examples print today, and the cloud-resource gate page now describes all three attempts its example runs.

  • Documentation site: a diagram on every concept page, provider tabs, and searchable catalogues. Nineteen concept pages gained a diagram drawn from the SDK source and reviewed against it: the hook lifecycle, the event taxonomy, the observability pipeline, state flow, checkpointer shapes, streaming paths, the termination algebra, the server request flow, interrupt and resume, the RAG pipeline, context strategies, idempotent execution, the fallback chain, structured output, Oracle Database 26ai primitives, the tool pipeline, skills disclosure, playbook enforcement and the evaluation flow; the older drawings now carry their status words and pass the same lint. The first generic code block on 31 pages renders as linked provider tabs (OCI, OpenAI, Anthropic, self-hosted) written once with {{ locus_model_tabs }}, and the generic example model is an OCI id. The event catalogues and the environment-variable reference have a filter box that hides rows and empty sections as you type. Several facts the reviews surfaced are corrected: the hook lifecycle has nine points, not eight, and on_before_compaction is in the table; HookRegistry orders providers and the agent's HookOrchestrator runs them; three rerankers ship, including OCICohereReranker; the /resume route's behaviour is described as the code implements it.

  • Documentation site: one template for the 89 notebook pages. Each page shows, in the same order, what the example builds, the diagram of its shape, the functions that carry the point, how to run it, what it prints where that is worth reading, and the full source collapsed at the end. A new build macro, {{ locus_source <file>::<symbol> }}, quotes a function or class by name so the excerpt follows the code and a renamed symbol fails the build; tests/docs/test_notebook_pages.py enforces the template; scripts/notebook_output.py captures the printed trail of every notebook whose offline run is deterministic and worth reading. Run blocks are fenced commands with the provider sentence that is true for each notebook.

  • Documentation site: home page. The three card grids (shapes, Oracle Cloud, harness) open with a small drawing of the pattern each card is about instead of a generic icon; a "What are you building?" section offers four tabs (support bot, incident response, contract review, SOC alert triage), each a short snippet linked to the notebook that runs it in full; "Your first agent" switches providers with the site's tabs while the hero keeps one literal OCI call; the notebook sidebar nests its topic groups so a notebook page fits the viewport; and the Markdown twins drop the glyph markup. Page copy is corrected where it had drifted from the code: the Responses transport is opt-in through OCIResponsesModel, not chosen by region, and product names are written in full.

Removed

  • AWS cloud-posture tools. locus_security.aws (describe_aws, use_aws and their @tool wrappers), the aws extra on both packages and the LOCUS_AWS_* variables are gone; Locus targets OCI first. The cloud-posture capability stays, on the core OCI tools: create_soc_analyst, SecurityControls, SecurityContext().cloud, the cloud_posture_audit playbook and security_toolset(oci=True) drive describe_oci / use_oci (read-only by default), and SecurityControls carries the OCI profile, auth_type, region and compartment_id the review runs as. S3-compatible object storage — S3Backend and the s3 extra — is unaffected: it is how OCI Object Storage is reached.

4.0.0 2026-10-28

Removed

  • Amazon Bedrock and Azure OpenAI providers. The bedrock: and azure: model prefixes, locus.models.native.bedrock / locus.models.native.azure, the bedrock extra and their documentation are gone; Locus targets OCI Generative AI first and keeps OpenAI, Anthropic and the OpenAI-compatible endpoints. The s3 and security aws extras (Object Storage on S3, the AWS posture audit) are unaffected.

Fixed

  • OpenAISearchPreviewProvider always failed against gpt-5-search-api. The provider asked the search model for a strict json_schema response_format, which that model answers with an HTTP 500 (json_object gets a 400). It now reads the url_citation annotations the search models attach to their reply — title, URL and the cited span as the snippet — and only falls back to a prompt-described JSON request when a model returns no citations.

  • OpenAI GPT-6 and -pro models could not call tools (or answer at all) through openai:. Chat-completions rejects function tools for the gpt-6 / gpt-6.1 families when reasoning is active and does not serve the gpt-5*-pro models at all. api="auto" now routes both to /v1/responses, as it already did for gpt-5.6; verified live on gpt-6-sol, gpt-6.1-sol, gpt-6.1-terra and gpt-5.5-pro.

  • OracleAgentMemoryManager could not use OCI Generative AI models with a profile or session token. litellm's oci/ driver, which Oracle's oracleagentmemory client uses for its embedder and extraction model, does not read ~/.oci/config, so the manager's own defaults (oci/cohere.embed-v4.0, oci/openai.gpt-4.1) failed with "Missing required parameters" unless litellm's OCI_USER / OCI_KEY_FILE variables were set. For oci/... specs the manager now builds the signer from the OCI profile (OCI_SESSION_PROFILE / OCI_PROFILE, API key or session token, instance and resource principals via OCI_AUTH_TYPE) and passes it with OCI_REGION and OCI_COMPARTMENT_ID; litellm_kwargs= overrides any of it and oci_litellm_auth() exposes the same derivation. The manager also uses MemoryExtractionConfig where oracleagentmemory provides it instead of the deprecated inline flag. Notebook 44 runs OCI-only by default.

  • OCIEmbeddings() and OracleAgentMemoryManager failed with their default embedding model. OCI retired the Cohere v3.0 embedding models from on-demand on 2026-09-30 (404 Entity with key cohere.embed-english-v3.0 not found). The default is now cohere.embed-v4.0, which is multilingual and 1536-dimensional (it was 1024): an index built with v3 has to be re-embedded either way, since v3 and v4 vectors are not comparable. Pass output_dimensions=1024 to keep 1024-wide columns. The v3 ids remain for dedicated AI clusters.

  • Session-token OCI profiles work on every OCI client, not only the V1 transport. oci session authenticate writes a profile with security_token_file and no user; OCIModel (the Cohere / SDK transport), OCIEmbeddings, OCICohereReranker and OCIBucketBackend defaulted to API-key signing for it and failed with InvalidConfig {'user': 'missing'} unless auth_type="security_token" was passed. They now detect the profile shape the way OCIChatCompletionsModel always did. Found running the suites against a Frankfurt tenancy with a session profile. OCIEmbeddings also gains the close() the other embedders have, so a store can shut any provider down the same way.

  • Gemini tool calls on OCI. OCI maps a tool message onto Gemini's function_response.response, which must be a JSON object; a tool that returned a number or a plain string made the next request fail with 400 Invalid value at 'contents[n].parts[0].function_response.response'. The V1 transport now wraps non-object tool results as {"result": …} for google.* models.
  • RAG tool returned nothing on OCI embeddings. create_rag_tool() / RAGRetriever.as_tool() applied a fixed similarity threshold of 0.5, which is calibrated for OpenAI embeddings; with Cohere embed-v4 on OCI a clearly relevant document scores about 0.4, so the agent's search tool came back empty. The default is now None (rank by similarity, bounded by limit, scores still returned) and as_tool() accepts limit= / threshold= so a deployment can set its own cut-off.
  • Gemini on OCI rejected schemas with enum and validation keywords. OCI's Gemini translation answers 400 Unsupported JSON Schema feature for Gemini: enum (also additionalProperties, title, pattern, minimum, …) for response_format schemas and tool parameters — the cognitive router's strict GoalFrame schema has both, so every dispatch failed on google.* models. The V1 transport now folds enum / const values into the property's description (Allowed values: "a", "b".), keeps the type, and drops the validation keywords for Gemini; other vendors receive the schema unchanged.
  • Cohere on OCI rejected turns that end with an instruction. The SDK transport sends the last user message as Cohere's message and everything before it as history, so a conversation ending in a system message — the planning prompt, grounding replan guidance, the "[Replan]" nudge — went out with an empty message and OCI answered 400 message must be at least 1 token long or tool results must be specified. Trailing system messages are now sent as the current turn (a turn ending on an assistant message asks the model to continue).
  • Harness session backend on macOS and BSDs. Background jobs were started through setsid, a util-linux command that does not exist there, so start_background() failed with "could not start … in the session workspace" (and tests/unit/harness had one permanent failure on a Mac). Without setsid the backend now enables POSIX job control (set -m), which gives each job its own process group — the unit the kill path signals.
  • max_completion_tokens for every GPT-5+ and o-series model. The family check was a fixed prefix list (o1, o3, gpt-5), so o4-mini, the gpt-5.6 and gpt-6 generations still received max_tokens and OCI answered 400 Unsupported parameter: 'max_tokens'. The check is now a pattern over the generation number.
  • Every Anthropic call failed with anthropic 2.3. The SDK pins API version 2026-10-21, which removed temperature for every model: messages.create() raised TypeError: unexpected keyword argument 'temperature', and the API answers temperature: Extra inputs are not permitted if it is sent anyway. AnthropicModel now omits temperature when the installed SDK does not declare it, as it already did for the models that reject it.
  • OpenAISearchPreviewProvider returned nothing. OpenAI retired gpt-4o-search-preview and gpt-4o-mini-search-preview (404 model_not_found); their successor, gpt-5-search-api, ignores a non-strict JSON schema and answers in a shape of its own, which parsed to no results. The provider now requests a strict schema, the docs and notebook 57 use gpt-5-search-api, and *-search-api models are treated as rejecting sampling parameters.
  • "Task exception was never retrieved … Event loop is closed" on every loop change. The openai and anthropic SDKs close their HTTP client from __del__ by scheduling aclose() on whichever loop is running; a client built under an earlier asyncio.run() was closed through a dead loop and printed a traceback. The native OpenAI and Anthropic models and the OpenAI image, speech and embedding providers now pass an HTTP client that closes only on the loop that built it (locus.core.loop_bound.own_loop_http_client).
  • OpenAIImageProvider() failed with its default model. OpenAI retired gpt-image-1 (400 The model 'gpt-image-1' does not exist); the default is now gpt-image-2.
  • A timed-out DockerSandbox call could leave its code running. With a single docker run, the timeout could fire before the daemon had created the container; the docker kill then found nothing, and the daemon went on to start the container and run the timed-out code to completion. The container is now created first and started under the timeout, so it always exists to be removed (docker rm --force).
  • Notebook 34 timed out on Claude. It printed which protocol each router picks, but called dispatch(), which also runs the protocol — ten full multi-agent runs for ten protocol ids. It now uses Router.compile() and hands both routers the same frame, so a difference comes from the picker alone; under the mock model, which cannot fill a GoalFrame, it explains that and exits instead of printing a table of errors.
  • Notebook 81 timed out on Claude. Its telemetry stubs ignored the rollback, so a careful model kept re-verifying a mitigation the simulated cluster never applied. The stubs now reflect the rollback.

  • Tool arguments are coerced to the declared parameter types. Models do not reliably honour the JSON types in a tool schema: Llama on OCI sends {"a": "17", "b": "25"} for two int parameters, and add("17", "25") returned "1725". Tool.execute() now validates each argument against the parameter annotation with pydantic in lax mode (numeric strings, "true", JSON strings for containers, dicts for BaseModel parameters, numbers for str parameters); values that still do not validate are passed through unchanged, and unannotated or Any parameters are left alone.

  • Oracle agent memory with a single connection crashed the driver. oracleagentmemory extracts memories on a background thread; sharing one sync oracledb.Connection between that thread and the agent's own queries segfaulted python-oracledb. Notebook 88 and the OracleAgentMemoryManager docs now hand the library a connection pool, and the manager gains aclose() / close() (and drain() now waits for the library's background extraction) so callers can shut it down before closing the pool.
  • Tool calls with Meta Llama on the OCI V1 transport. OCI's /openai/v1 rejects a tool-enabled request whose first message is a system message with 400 Tool calling for this Llama model requires the first message to be a user message — every agent with a system_prompt hit it. OCIChatCompletionsModel now folds the leading system text into the first user message for meta.llama* when tools are present.

  • oci:cohere.command-a-* reached the wrong transport. The string factory only sent cohere.command-r* to the SDK transport, so Command A went to /openai/v1 and failed with 400 Unsupported OpenAI operation. Every cohere.* id now routes to OCIModel.

  • OCIModel sent the generic chat request to Command A. OCI serves Command A through the Cohere chat API; the generic shape was rejected with 400 Chat request type does not match serving model. All cohere.command* models now use CohereProvider.

Changed

  • Notebooks 01–89 and the concept pages were reviewed for clean, didactic code. Every notebook now runs offline on the bundled mock model with the OCI GenAI auto-detect described accurately, one function per part with main() last, imports at the top, no private attributes, no unused imports or dead branches, and comments that explain a decision rather than restate the next line. Model calls that only asked the model to comment on a feature were removed; the remaining calls exercise the primitive being shown. Stale cross-references, old table names and wrong claims about the SDK (hook ordering, run_sync inside a running loop, checkpoint cadence, event payloads) were corrected, and two notebooks were renamed to match their content: notebook_20_map_reduce_support_triage.py and notebook_78_concession_approval.py. The concept pages' code blocks were checked against the SDK: snippets calling non-existent APIs (Orchestrator.run, EvalRunner(agent=graph), the KnowledgeProvider example, Agent.run used synchronously) were fixed, duplicated blocks were merged, and import paths were standardised on the public modules. The examples/ lint exemptions for unused imports, unused locals and placeholder-free f-strings were dropped.

  • Documentation site reorganised around the harness. The home page leads with the eight multi-agent shapes, then the harness (tools and MCP, memory, RAG, grounding, guardrails and the admission gate, observability, serving, skills, providers), a "Verified on OCI" section with the 27 October 2026 model matrix, a compact control-layer section, and a comparison with other agent SDKs (concepts/compare.md, since removed). The Concepts navigation follows the same order: start here, multi-agent shapes, the harness, control layer, providers. The OCI models page carries the verified matrix and corrects the Responses-API note (availability is per region).

Added

  • runpod: provider prefix. RunPod serverless and public endpoints (https://api.runpod.ai/v2/<endpoint-id>/openai/v1) behind one prefix: set RUNPOD_API_KEY and RUNPOD_ENDPOINT_ID (or RUNPOD_BASE_URL / LOCUS_RUNPOD_BASE_URL), then Agent(model="runpod:Qwen/Qwen3-32B-AWQ"). Verified against RunPod's public qwen3-32b-awq endpoint with a tool call. A live integration test (tests/integration/test_compatible_providers_live.py) covers OpenRouter, Together and RunPod whenever their keys are present.

  • The generic integration tests and the notebooks run against any provider. LOCUS_TEST_MODEL=provider:model points the shared model fixture at anything locus.models.get_model accepts (it only knew OpenAI, Anthropic and OCI), and LOCUS_MODEL_PROVIDER / LOCUS_MODEL_ID do the same for the notebooks (scripts/run_notebooks.py --provider <prefix> --model <id>). Notebooks whose prerequisites are missing exit with 77 and the runner reports them as SKIP instead of FAIL.

  • Embeddings examples use cohere.embed-v4.0 (1536-dim). OCI has deprecated the Cohere v3.0 embedding family and recently onboarded tenancies answer 404 Entity not found for it. The OCIEmbeddingModel enum gains COHERE_EMBED_V4 and COHERE_EMBED_MULTILINGUAL_V4; the OCIEmbeddings default is unchanged so existing 1024-dim tables keep working. The OCI embeddings integration tests assert against the model's dimension instead of a hard-coded 1024 and accept OCI_EMBED_MULTILINGUAL_MODEL.

  • Positioning. Locus is presented as the Oracle Generative AI Agentic Harness across the README, the documentation site (home page, site description, page titles, social card), the package metadata and the security policy. The social card now points at github.com/oracle/locus. The site header carries a slogan under the locus wordmark again ("OCI Agentic Harness SDK"; the line was dropped with the newer stylesheet), the logo SVG slogan matches, the social card no longer carries the old "Multi-Agent Reasoning Orchestrator SDK" line, and "Day 0 OCI" is the second card in the home page's "What Locus gives you" grid. The home page itself is cut to about half its length: a three-bullet hero with a governed_agent() example, six feature cards, one example per section, and a pill-badge eyebrow in place of the monospace kicker. Home page and README links labelled "admission gate" now land on the control-layer page (they pointed at the locus-sdk-security findings page), notebook links carry the notebook's own title, and the nav labels the security page as what it is.

3.0.1 2026-10-22

Fixed

  • pip install "locus-sdk[oci]" in a clean environment. The OCI request signer builds on requests.auth.AuthBase, but requests was never declared: the OCI SDK vendors its own copy, and development environments had it through other extras, so importing locus.models.providers.oci raised ModuleNotFoundError: No module named 'requests' only on a fresh install. The oci extra, and the llm, rag, checkpoints and sdk bundles that include it, now list requests>=2.31.

3.0.0 2026-10-22

Locus is back at Oracle. The project continued from 2026-06-08 to 2026-10-10 as tulip-agents under the tuliplabs-ai GitHub organisation (releases 1.0.0 → 2.28.0); this release brings that development line home to oracle/locus with its full history and restores the Oracle Cloud and Oracle Database integrations that were removed on the way out. tulip-agents is retired.

Changed

  • Renamed back to Locus. Distribution tulip-agents → locus-sdk, import root tulip → locus, security add-on tulip-agents-security → locus-sdk-security (import locus_security), CLI tulip / tulip-runner → locus / locus-runner, environment variables TULIP_* → LOCUS_*, TulipEvent / TulipError / TulipSettings / TulipDeprecationWarning / TulipMCPServer → the Locus* names. A search-and-replace of tulip → locus in your code and shell is the whole migration.
  • Licence. Returned to the Universal Permissive License v1.0, the licence the project carried before 1.0.0, under Oracle copyright. See PROVENANCE.md.
  • Docs site moved in-repo. docs/, mkdocs.yml, the theme overrides and build hooks live here again and publish to https://locusagents.ai/; the API reference imports this checkout.
  • CohereReranker is Cohere's direct rerank API; the OCI-served reranker is now OCICohereReranker (locus.rag.reranker.cohere_oci).

Added

  • OCI Generative AI — oci: model prefix with automatic transport routing: OCIChatCompletionsModel (OpenAI-compatible /openai/v1, SSE streaming, day-0 OpenAI / Meta / xAI / Mistral / Gemini models), OCIModel (OCI SDK transport for Cohere R-series and Dedicated AI Cluster endpoints) and the opt-in OCIResponsesModel. API-key, session-token, instance-principal and resource-principal auth with signer refresh.
  • Oracle Database 26ai — OracleVectorStore / OracleSyncVectorStore (native VECTOR(N, FLOAT32), VECTOR_DISTANCE, HNSW / IVF indexes, hybrid search, metadata filters), OracleInDBEmbeddings, OracleInDBChunker, OracleADBLoader, the oracle_checkpointer() / OracleBackend checkpointer, the versioned OracleCheckpointSaver, the OracleStore long-term memory store and OracleAgentMemoryManager over Oracle's official oracleagentmemory client, plus sync companions.
  • OCI Object Storage checkpointer (OCIBucketBackend, oci_bucket_checkpointer()), OCI embeddings (OCIEmbeddings), the use_oci / describe_oci built-in tools, and the sanitize_oci_tool_schema helper.
  • Extras: oci, oracledb, agentmemory; checkpoints, rag, llm and sdk include the Oracle dependencies again.
  • Notebooks 01-05, 10, 41-44, 53-54, 88 and 89 (OCI transports, DAC, Cohere reranker on OCI, Oracle 26ai RAG / loader / chunker / embeddings / checkpointers / store / agent memory, OCI tools) and their docs pages.
  • examples/config.py auto-detects OCI when ~/.oci/config has a usable profile (LOCUS_OCI_* with OCI_* fallbacks); set LOCUS_MODEL_PROVIDER=mock to opt out.

Removed

  • The Apache-2.0 NOTICE and LICENSES/ files that documented the tulip-agents relicensing; superseded by LICENSE (UPL-1.0) and PROVENANCE.md.

Releases before 3.0.0 are listed in CHANGELOG.md on GitHub.