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:
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
EvalCaseobjects (benchmarks/router/cases.json, taggedlabelled,shape:<id>,trap,injection,ambiguous) andlocus.router.benchmarkadapts selection toEvalRunner's contract: a typed target that takes anyRequestClassifierin the router's front seam, a free-form baseline that may name an unregistered id, androuter_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 (regressionslists the cases either way). Every target answers a protocol id,unboundedorrefused, and retries a transient provider error before refusing; nothing is built or run.scripts/router_benchmark.pyruns it against a model and stores the reports;tests/is the same gate behindintegration/ test_ router_ classifier_ gate. py RUN_ROUTER_BENCHMARK=1, and the routing benchmark beside it reads the same file. (#342) - Checkpoint TTL. Every checkpointer takes
ttl=(seconds or atimedelta): a checkpoint expires that long after its save and is then neither loaded, listed nor forked, andawait cp.expire()removes what has expired and returns the count. Redis gets its ownEXPIREon 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 andPgCheckpointerkeep anexpires_atcolumn, added to an existing table by the first save made with attl— 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 viacryptography,pip install "locus-sdk[encryption]") seals the state before any backend stores it:encryption=on every checkpointer, a key or akey_providercallable for a vault fetch,previous_keysfor 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(.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. . , allow_ plaintext=True) save()— stay in the clear solist()works without the key. (#298) - Per-application and per-user scoping.
CheckpointScope(app_on every checkpointer (id=, user_ id=) scope=) or per run (agent.run(…, scope=…), alsoarun,run_sync,resume,continue_turn) stores a thread underapp=<app_— a key, directory or object prefix, theid>/ user=<user_ id>/ <thread_ id> thread_idcolumn's prefix on SQL — so the samethread_idunder 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, withscope=Noneinheriting the checkpointer's scope andCheckpointScope()explicitly unscoped;list_threads(scope=)lists one scope, and unscoped data stays reachable with no scope. (#298) python -m locus.runnertakes its workspace fromLOCUS_WORKSPACEwhen set, for a runner started outside an OpenShell sandbox (a gateway's local box driver, a CI job); unset, it works on/sandboxas before.locus audit verify --format json. The verification of an exported audit trail as data:{"file", "verified", "records", "keys", "head_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)checked"} locus eval gate --markdownandGateResult.to_markdown(). The gate's verdict as Markdown with one table row per failed check, for a pull-request comment, the wayeval diffandeval summaryalready 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 aVECTOR(n)column, aJSONmetadata column and aFULLTEXTindex on the content; the store mirrorsOracleVectorStore's surface (add,add_batch,get,delete,search,count,clear,close) plushybrid_search, which blendsDISTANCE()similarity withMATCH ... AGAINSTrelevance client-side the way the Elasticsearch store does. It probes the server once: HeatWave MySQL computes and orders byDISTANCE()on the server (server_side_distance=True); community MySQL 9+ has theVECTORtype but noDISTANCE(), so the store fetches up tocandidate_limitrows and ranks them here. Metadata filters areJSON_EXTRACTequality 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. Newheatwaveextra (the samemysql-connector-pythonthemysqlcheckpoint extra installs), lazy export fromlocus.rag.stores, docs rows and a HeatWave vs community MySQL section, and the shared conformance suite behindHEATWAVE_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 theAuditReporteach yields, policy documents with their hash, lint findings and decisions, malformed documents with the error key, approval digests, ids and decision sequences, and the exactaction-admissionline an admission writes.scripts/conformance_export.pyregenerates them from a fixed clock and fixture keys; a unit test fails on any difference, so a format change is a deliberatev2. A dependency-free Node script underconformance/v1/tools/recomputes the digests and verifies the signatures from the other side. (#343) - TLS-only Autonomous Database connections, and a
config_dirof their own. Every Oracle backend —OracleBackendbehindoracle_checkpointer(),OracleCheckpointSaver,OracleStore,OracleVectorStore,OracleADBLoader,OracleInDBChunker,OracleInDBEmbeddings,OracleApprovals,OracleAuditTrail,OracleReportStoreand the sync twins — takes an optionalconfig_dir, the directory holdingtnsnames.ora, and passeswallet_locationto python- oracledb only when a wallet is given. A database created without mutual TLS has no wallet, and naming its TNS directory aswallet_location(the only way to resolve an alias before) made the driver look for a wallet file there and fail withDPY-6005.wallet_locationalone still doubles as the TNS directory, so wallet users see no change. Theoracle://approval-store and report-store specs takeconfig_dir=and a bare one readsORACLE_CONFIG_DIR(elseTNS_ADMIN) from the environment; the Oracle notebooks requireORACLE_WALLETonly for an alias that nothing else resolves. The Oracle Database 26ai page describes the TLS-only path. (#347) A wallet named by the spec orORACLE_WALLETkeeps its own TNS directory: neither variable is applied over it. The spec a store reports carries itsconfig_dir=andwallet=percent-encoded, andOracleReportStore.specnow 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 toTrue. Every tool call is signed as the model's response is parsed and verified before it runs, so a hook that rewritesevent.argumentsmust callevent.resign(by="MyHook")or the call is refused with aToolCallIntegrityError; the built-inGuardrailsHookredaction andExternalHooksrewrites already do. PassAgent(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=…oruser=…(or beginningapp%/user%) on a checkpointer with noscope=is now stored percent-encoded (user=alice/chatasuser%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 throughCheckpointScope(user_id="alice")(the bare id parses as that scope's threadchat) or rename it before upgrading. Every other unscoped id keeps its bare stored form. The adapter'sexists()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/gainsconfig.platform.yaml— the gateway ofconfig.yamlplus the OpenTelemetry callback and the Redis response cache;docker-compose.ymlselects it whenREDIS_URLis set and starts a redis sidecar under thecacheprofile, 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.yamlnow uses the keys the chart reads (environmentSecretsinstead of the ignoredenvFrom, 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/keeps the two configs in step;unit/ test_ litellm_ gateway_ example. py tests/drives the guardrail and the cache against a live gateway.integration/ test_ litellm_ gateway_ platform. py RequestClassifierandProtocolPicker, the router's two seams.Router(classifier=...)takes anyasync classify(text) -in place of the extractor agent, which is now wrapped in> GoalFrame AgentFrameExtractor, the default implementation of the same protocol;CognitiveCompiler(protocol_takes anypicker=. . . ) ProtocolPicker, of whichLLMProtocolPickeris the one that ships. Behaviour is unchanged by default. (#342)- Router: LOW-complexity requests go to
direct_responsebefore any goal gate. A frame atComplexity.LOWwhose risk is withindirect_response'srisk_maxcompiles todirect_responsewhatever itsprimary_goal;router.protocol.selectedreportsmethod="low_complexity_direct"andexplain()mirrors it. ThePolicyGatestill runs, adirect_responsethe gate denies sends the frame down the ordinary filter-and-rank path, andCognitiveCompiler(low_turns the rule off.complexity_ direct=None) direct_responsealso handlesDIAGNOSEnow, so a LOW-complexity diagnosis ranks the direct answer first by rule while MEDIUM and HIGH stay onspecialist_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 onBaseStore,InMemoryStore,register_providerandlist_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>:_checkpointsJSON string an earlier release kept and moves it into the index hash on the thread's next save or removal, with aLocusDeprecationWarningwhen 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.securitycompatibility shim. The old import path no longer resolves;locus.controlis 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 thelocus-sdk-securitypackage in 5.6.0. (#464) - Removed in 6.0: the
locus.looppackage.ReActLoop,ReActLoopConfig,create_react_loop,LoopRunner,BatchRunner,StreamingCollector,create_runner, the nodes and the router no longer import;Agent(agent.run,agent.arun),EvalRunnerandStateGraphconditional 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-callresponse.metadata["fallback"]orlocus.models.fallback.served_tier()instead. - Removed in 6.0: the
toolkey on thetool.integrity.refusedpayload (event bus andagent.tool.integrity.refusedaudit entries). Readtool_name, the keyToolCallIntegrityError.tool_nameand the audit entries use.
Fixed¶
- Two processes creating the PostgreSQL checkpoint table at the same instant
no longer fail.
postgresql_checkpointer()andPgCheckpointertookCREATE TABLE IF NOT EXISTSfor atomic; the loser hit thepg_typeunique index. The first-time DDL now runs under a transaction-scoped advisory lock on the table name and re-probes before creating. LOCUS_FRONTIER_MODELturns 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.runnerreports every command the harness ran as aharness.execrecord. 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>:_checkpointsindex 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 singleUPDATEof the index row's JSON array on PostgreSQL and MySQL, a scripted_updateon OpenSearch — behind the newCheckpointIndexStoreprotocol (locus.memory.backends), whichStorageBackendAdapteruses when the store provides it and falls back to the locked read-modify-write otherwise. Ordering,max_checkpoints_per_thread,fork,listand 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()answersFalsefrom 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 aWATCH, 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 configuredttl_secondseven when a removal is what migrates it.StorageBackendAdapter.isdelete(thread_ id, checkpoint_ id) Truewhen 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).OracleBackendnow implementsCheckpointIndexStore: each save or removal reads the<thread_id>:_checkpointsrow underSELECT ... FOR UPDATEand 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.OracleSyncBackendmirrors 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
OracleBackendat once no longer fail.save()is aMERGE, and for a key neither writer has seen both take itsINSERTbranch; the loser met the primary key (ORA-00001) on the shared<thread_id>:latestrow and the save raised.save()now repeats theMERGEonce in that case, and the row the winner committed takes theUPDATEbranch. The first-time DDL raced the same way, worse: every concurrent first save ranCREATE TABLEandCREATE INDEX, and the losers failed withORA-00955,ORA-00054orORA-04020. A backend now provisions once per process under a lock, aCREATEanother 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,OracleAuditTrailand the evaluationOracleReportStorehad the same first-time DDL: every concurrent first operation on a fresh table ran theCREATEstatements, and two processes starting together failed withORA-00955,ORA-00054orORA-04020. They now share one provisioning helper: one pass per instance under a lock, aCREATEanother process won reads as created, a lock collision with that process is retried a few times. - A burst of writers on one
OracleAuditTrailno 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 orderrecord()uses. - A backend with only some of the
CheckpointIndexStoremethods is no longer taken for one without any.StorageBackendAdapterfell 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, andindex_methods_present()inlocus.lists what a store implements.memory. backends. checkpoint_ index
5.6.0 2026-11-17¶
Added¶
on_request/on_responseon the HTTP-backed OCI models.OCIResponsesModelandOCIChatCompletionsModel(and their configs) take a pair of sync callables that see each outgoinghttpx.Requestafter signing and eachhttpx.Responseas its headers arrive — the seam for request-shape tests and for seeing what goes on the wire when debugging, where reaching intomodel._http_client()to attach httpx event hooks was the only way. Both areNoneby default and install nothing;model_kwargscarries them through theoci:factory.- Time travel on every checkpointer.
checkpointer.list(thread_id)describes a thread's checkpoints newest first asCheckpointInforecords (id, write time, the state's iteration, the checkpoint's size as that backend stores it, the checkpoint it descends from —Noneonly for a thread's first — and, for a fork, the thread it came from);checkpointer.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;fork(thread_ id, checkpoint_ id) agent.run(..., from_checkpoint=...),arun,run_syncandagent.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.resume(. . . , from_ checkpoint=. . . ) Agent.forkandStateGraph.aforkgo through the checkpointer'sfork. EveryBaseCheckpointerhas the surface through the base defaults; the in-memory, file, adapter-wrapped (Redis, PostgreSQL, MySQL, OpenSearch, Oracle), S3, OCI Object Storage andPgCheckpointerbackends read the step fields without loading the state, and the versionedOracleCheckpointSaver(the reference, one row per checkpoint with a parent link) gainsforkandlisttoo.max_checkpoints_per_threadonMemoryCheckpointer,S3Backend,OCIBucketBackend,StorageBackendAdapterand the*_checkpointer()factories bounds a thread's history (FileCheckpointerandPgCheckpointeralready 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_andmermaid_ history(checkpointer, *thread_ ids) StateGraph.adraw_mermaid_historydraw 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 overWorkspaceBackend: a lifecycle (state,start(),stop(),close(), each idempotent), declaredResourceLimits(amax_exec_sis enforced by clamping everyexectimeout), andadd_exec_hook(), which hands anExecRecordof 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.SandboxMixingives a backend of your own all of it by overriding_start,_stopand_destroy.locus.is the conformance kit: the file, shell, deadline, background-command and protocol checks the tools assume, run on a backend and reported together;harness. testing. assert_ backend_ conformance(factory) run_conformance(backend)does the same without closing it.SSHSandboxBackend. Any host withsshdas a workspace (thesshextra,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 acatfallback that checks the byte count, host keys are checked againstknown_hostsor a pinnedhost_key=(a key accepted underknown_hosts="accept-unknown"stays in memory; the user's file is never written), andvia=SSHJump(...)connects through a bastion.OCIContainerInstanceBackend. An OCI Container Instance as the Oracle-native remote sandbox (theoci-containerextra):create()provisions the instance from an image withsshdor a package manager, bootstrapssshdwith 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 unlessknown_hosts="accept-unknown"is passed.stop()/start()restart the instance andclose()deletes it and the session.E2BBackendandDaytonaBackend. Thin adapters over the two hosted sandbox services' Python clients (thee2banddaytonaextras), checked with stand-ins; the live tests run when the service's API key is set.SandboxSpecandopen_sandbox(). A sandbox named in configuration:backend="local" | "ssh" | "oci-pluscontainer" | "oci- sandbox" | "openshell" | "e2b" | "daytona" | "memory" root,env,limits, aWarmPoolHintand the backend'soptions;from_mapping()reads it from a parsed YAML or JSON document and refuses unknown keys;register_backend()adds a name.SandboxPool/open_pool(spec)keepwarm_pool.readysandboxes created ahead of need, and the hint'snamereaches 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=...), anddurability=onrun,arunandrun_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.durabilitydoes the same for aStateGraph'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"(orAgent(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 newAgent., orresume(invocation_ id=. . . , thread_ id=. . . ) 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.replayedmarks a replayed result.continue_turnnow 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_letsidempotent_ on_ replay= True) idempotent=Truetools run again on replay instead. The turn's final save clears the ledger. Temporal and DBOS segments record into the same ledger, andrun_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,
A2AServerserves the HTTP+JSON binding (POST /message:send,GET /tasks/{id},POST /tasks/{id}:cancel, the push-config resources, server-sent events formessage:streamandtasks/{id}:subscribe) on the same app, and the gRPC binding (lf.a2a.v1.A2AService, all eleven RPCs) ongrpc_port, behind the newa2a-grpcextra. The card'ssupportedInterfaceslists what is on (transports=); every binding lands in one set of handlers and reports the sameErrorInforeason 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.SubscribeToTasknow streams a task's live events after the snapshot. - A2A push notifications.
A2AServer(push_delivers every status and artifact change to the webhooks a task registers (innotifications= PushNotificationSettings(. . . )) SendMessage's configuration or with the*TaskPushNotificationConfigmethods), with the token andAuthorizationthe config asks for, retries, and a URL policy that refuses private addresses unless told otherwise.PushNotificationSignersigns each body (Ed25519) and publishes the key at/.well-known/jwks.json;PushNotificationReceiveris the client-side webhook that checks the token and the signature.send_returns the task at once and runs it in the background.message(. . . , push_ notification_ config=. . . , blocking=False) - A2A interrupt mapping. A run that pauses for a person —
ask_user, or an approval hold fromgate_tool(on_refusal="interrupt")— surfaces as the task stateinput-requiredwith the question (or the hold summary) as the status message. The peer's next message on the task resumes the run throughAgent.resume(); for a hold its first word decides (approve/deny), recorded on the approval store passed asA2AServer(approvals=...). An approved hold performs the call once; a denied hold ends the taskrejected. locus a2a card AGENTwrites a v1.0 agent card from the agent's tools, skills, streaming capability and the transports named (--transport,--grpc-port,--push);--serveruns 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_vectork-NN with aflattenedmetadata field),RedisVectorStore(Redis Query EngineVECTORfields withTAGfilters on declared metadata keys),MongoDBAtlasVectorStore($vectorSearch,ensure_index()creates the Atlas index) andPineconeVectorStore(serverless indexes). Each sits behind the existingVectorStoreprotocol withmetadata_filterand 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.
LLMRerankerhas 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;JinaRerankerandVoyageRerankercall the hosted rerank APIs overhttpxwithJINA_API_KEY/VOYAGE_API_KEY. - Hybrid search, one switch.
RAGRetriever(hybrid=True, hybrid_callsalpha=…) store.on stores implementing the newhybrid_ search(query_ text, query_ embedding, alpha=…) HybridSearchableprotocol — Oracle Database 26ai, OpenSearch, Elasticsearch, Weaviate and Milvus (enable_hybrid=True) — with the samealphameaning everywhere (1.0vector only,0.0lexical only). Stores without hybrid search fall back to vector-only search with one logged warning;supports_hybrid_search(store)andretriever.hybrid_supportedreport the capability,retrieve(..., hybrid=…)overrides it per call andhybrid_kwargspasses store-specific options such as Oracle'suse_text_index.OpenSearchVectorStoregainshybrid_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()buildsOCIEmbeddingswhenLOCUS_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,unorderedorsubset),ToolSelection(recall and precision over the tools chosen, withforbiddentools) andArgumentCorrectness(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 anEvalCaseunderevaluators, is one check named by its label, loads from a case file bykind, enters the suite fingerprint, and leaves a typedEvaluatorVerdictwith its provenance inEvalResult.evaluations. The runner fills anArgumentCorrectnessschema in from the tool on the agent under test. - A simulated user for multi-turn cases.
EvalCase(simulated_has a model play that user against the agent inuser= SimulatedUser(persona=. . . , goal=. . . , max_ turns=. . . , stop_ on=[. . . ])) 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.transcriptandstopped_bykeep what happened, and a conversation that hit the budget failssimulated_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 itsagent.*events, keeps the runsevery_nth(n)orfraction(share)pick within anOnlineBudget(total, per minute, in flight), and grades them in the background with the same checks and judge as a suite through the newEvalRunner.agrade(case, result).attach(run_supplies what the bus does not carry;id, prompt=, output=, arguments=) submit(prompt, result)grades a result the application holds.report()is anEvalReportwhose fingerprint is the template's, so online reports diff and trend as one suite. - Persisted reports and
locus eval trend.report_store(spec)opens aReportStore: 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), fromfile://,oracle://,oci://ands3://specs orLOCUS_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 -keeps the report after a run and- store <spec> - - suite <name> locus eval trend -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.- store <spec> - - suite <name> locus deploy: the agent server on OCI.locus deploy initwrites 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) andlocus-deploy.yaml, the one file a person edits.plan,applyanddestroyrun Terraform for the chosen target;applybuilds the image for the chosen architecture and pushes it between the registry root and the target root;plan,applyanddestroytake--dry-runto print every command.initnever replaces an existing Dockerfile or.dockerignorewithout--force, only appends to a.gitignore, writes a.dockerignorethat keeps Terraform state and tfvars out of the image, and takes--sdk-wheelto 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 newoke_workload_identityauth type that every OCI auth switch in the SDK accepts and thatresource_principaldetects on a pod) and take secrets as OCI Vault secret OCIDs: the image starts withpython -m locus.deploy.entrypoint, which resolves every<VAR>_SECRET_OCIDinto<VAR>before uvicorn. The generated server refuses to start without its bearer key unlessallow_unauthenticatedis set, and a public Container Instance needsserver_api_key_secret_idor that opt-out.locus.deploy.functionsruns theAgentServerapp behind the Fn FDK, so the same server answersoci fn function invokeand API Gateway requests. New extras:deploy(PyYAML) andfunctions(the Fn FDK). The guide is Deploy to OCI, with sizing and cost notes and a deploy-on-tag workflow.- OpenTelemetry GenAI semantic conventions.
TelemetryHooknow files a run as oneinvoke_agentspan, each model call as achatspan (CLIENT) and each tool call as anexecute_toolspan, with thegen_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=andagent_name=override.TelemetryHook(semconv="locus-keeps the previouslegacy") agent.invocation/agent.iteration.<n>/tool.<name>spans andlocus.*metrics.locus.observability.semconvholds the names and avalidate_spans()check for recorded traces. - W3C trace context across A2A.
A2AClientsendstraceparent(the agent's tool span when called from a tool) on every request over every binding — JSON-RPC, HTTP+JSON, gRPC metadata — andA2AServerruns 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_metaalready carried it. - OCI Application Performance Monitoring exporter.
locus.builds the OTLP/HTTP span and metric exporters for an APM domain (data upload endpoint,observability. exporters. oci_ apm(endpoint, private_ data_ key) dataKeyauthorization) andinstall()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 withtable_kind="blockchain". Same API asAuditTrail, soadmit(trail=…),gate_tool(trail=…)andgoverned_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), andverify()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 thatDBMS_BLOCKCHAIN_TABLE.VERIFY_ROWSverifies them all.arecord()/acheck()/averify()run the same work on a worker thread for async code.- Chain-head anchoring in object storage.
anchor_writes the current head (record count, sequence number, hash, timestamp) as a small JSON object into an OCI Object Storage bucket (trail(trail, store, every=…) 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=Truerefuses 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. ControlPolicyas data.ControlPolicy.load(path_or_text)reads a policy from a YAML or JSON document andpolicy.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 aPolicyFileErrorthat names the key and its path (require_human_for[2]). Reading YAML needs the optionalpyyamlpackage; 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()andadmit_sync()recordpolicy_hashon everyaction-admissionentry, 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 whereveradmit(),admit_sync()andgate_tool()take apolicy(anyPolicySourcewith acurrent()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 onlast_error;on_reloadis called with the old and new policy when the rules change. locus policy lint <file>reportsunreachable-rule(a hold label thatdeny_forpre-empts, a cost hold at or above the spend limit, a verification bar above 1.0, a deniedsandboxedtag, a zero blast-radius cap),uncovered-environmentandkind-never-heldfor the environments and kinds the file'sgoverns:block or--environments/--kindsdeclare. Exit 1 on a finding;--format jsonfor CI. The last two are found by weighing probe actions withapprove(), so lint agrees with the gate by construction.locus policy explain <file> -prints every rule, fired or not, the outcome and whether a person can approve it;- action '{. . . }' --expect allow|require_human|denyturns it into a check with the exit code,--spent-usdand--verificationsupply what the gate would read from a ledger and a verdict.evaluate_rules()is the one evaluationapprove()andexplain()share;lint_policy(),explain()andPolicyDocumentare the same from Python.- Notebook 71 loads its policy from
examples/; the policy authoring guide shows the file form first and a CI lint job.notebook_ 71_ refund_ policy. yaml - A model-based tool-call judge that feeds the gate.
locus.control.ToolCallJudgeshows a model the proposed tool call, name and arguments, with the policy's intent and optional per-tool guidance, and returns a typedallow/hold/denyverdict with a one-line reason, parsed through the structured-output path.gate_tool(judge=...)hands the verdict toadmit(judgement=...), wheretighten()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 underjudge(model, verdict, reason, cache hit, and the error when it failed closed) and emitted ascontrol.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, andbudget=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 typedToolCallIntegrityError, an entry on the agent'sAuditTrail(the signed and received digests, and the hook the change is attributed to), atool.integrity.refusedevent, and a tool error the model reads so the run continues;"abort"ends the run instead. Hooks that rewrite arguments re-sign throughevent.resign(by="...")orToolCallSigner.resign, so the chain of custody names them; the built-inGuardrailsHookredaction andExternalHooksrewrites do. The signature lives on the run, not onToolCall, so messages and checkpoints are unchanged. Off by default in 5.x, on by default in 6.0. (#450) - Database-backed approval stores.
PostgresApprovals,RedisApprovalsandOracleApprovalsimplementApprovalStorewith 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; theApprovalStoremethods block on it andasubmit/aget/adecide/aconsume/apendingawait it. Every store has a password-freespec(file://…,postgresql://…,redis://…,oracle://…) andapproval_store(spec)opens one; a bare database scheme readsPOSTGRES_*,REDIS_URLorORACLE_*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_reads it back in another process,holds(checkpointer, thread_ id) 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 astorekey. locus approvalsagainst any store.--storetakes a spec (orLOCUS_APPROVALS_STORE), a bare path still means aFileApprovalsfile,--byfalls back toLOCUS_APPROVER, andapprove/rejecttake--reason, recorded on the decision.ApprovalStore.decide()acceptsreason=""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
reasoningcontrol onOCIResponsesModel.reasoningtakes the Responses-native object (effort,summary, ...) onOCIResponsesConfig, the constructor and as a call kwarg such as an agent'smodel_kwargs, and is sent as given; withreasoning_effortset too the dict wins and the effort only fillseffortwhen the dict lacks it. Nothing is sent when both are unset. Reasoning summaries the endpoint returns surface asModelResponse.reasoning. Before, areasoningdict 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 forinclude=["reasoning.; the reasoning items that come back stay on the assistant message underencrypted_ content"] metadata["oci_responses_items"]with the turn'sfunction_callitems, 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/compactand returns the compacted messages: the ones the endpoint kept plus an encryptedcompactionitem the model replays on later requests.ContextCompactor(native_, orcompaction=True) CompactionConfig(native=True)on the agent, hands the summary stage to a model that offerscompact_history()instead of writing a client-side summary; the system prompt and the task message stay verbatim, theCompactionEventcarriesstage="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 carriesprevious_response_idwith a 400 saying so. That reply now raisesOCIResponsesZeroDataRetentionError, a subclass ofOCIResponsesStateLostErrorso existing handlers keep working.storeaccepts"auto"besidesTrueandFalse: 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 aLocusWarning, and the agent runtime replays the interrupted turn from the history it holds, so the run completes with the same result.model.zdr_detectedreports the switch and the run's event stream carries aCustomEventnamedserver_state_fallback.store=Truestill raises;store=Falseis unchanged. -
Release notes on the documentation site.
docs/release-notes.mdis generated from this file when the site is built (hooks/release_notes.py, the{{ locus_release_notes }}token):Unreleasedfirst, 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 /threadscreates a thread,POST /threads/{id}/runsstarts a turn (or continues a paused one with aresumepayload: the/resumesemantics, 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}/eventsstreams it as SSE with anid:line per event and honoursLast-Event-ID, replaying exactly the events a dropped client missed from the run's EventBus history;POST /runs/{id}/cancelasks the agent to stop throughagent.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_, passed asper_ run=500, max_ runs=200, ttl_ seconds=3600) AgentServer(run_registry=...)); a resume past the retained window gets areplay_gapframe. (#456) WS /runs/live. One WebSocket for user turns, approval answers (resume, through the existingdecision_handlerandagent.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.voicesessions remain application-driven.- AG-UI and Vercel AI SDK UI message stream adapters.
POST /ag-uitakes aRunAgentInputand streamsRUN_STARTED,TEXT_MESSAGE_*,TOOL_CALL_*,STATE_SNAPSHOT/STATE_DELTA,CUSTOMandRUN_FINISHED/RUN_ERROR;POST /vercel-aitakes a UI message request and answers anx-vercel-ai-ui-message-stream: v1stream (start,text-*,reasoning-*,tool-input-*,tool-output-available,data-*,finish). Both are also available for any run asGET /, resume included. The conservative readings of the two protocols are recorded on the server page.runs/ {id}/ events?protocol=ag- ui|vercel- ai 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'srunsand asourcefield, answers from the registry when no checkpointer is configured, and no longer fails with a 500 for a runnable withoutconfig(aGraphRunnable);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 anembedder=, by recency without one). ANativetier hands the stage to a model's own compaction endpoint (default_tiers(native=True)). The window comes from the model's metadata, orcontext_length=. Passconversation_ormanager=TieredCompaction(. . . ) CompactionConfig(tiers=True | [.; the agent binds the pipeline to its model and window. One. . ]) CompactionEventper tier that ran, withtierand the tokens before and after it;stagegains"window"and"relevance". - Pinned messages.
pin(message)(ormetadata={"pin": True}) and apins=predicate onTieredCompactionkeep a message verbatim through every compaction stage and tier, inContextCompactortoo; a pinned tool result keeps the call that produced it. ToolResultOffload. A tool result overthreshold_chars(16,000) goes to aToolResultStorethe moment it is produced; the message keeps a handle and a preview, and thefetch_tool_resulttool, 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_, orresult_ offload=. . . ) Truefor an in-memory store. The coding harness includes the samefetch_tool_resultwhenever itsHarnessConfignames aresult_store, and thebashnote says so.ToolResultStore.put()stores a result whatever its size and returns its key.
Changed¶
-
TelemetryHookdefault span and metric names. The GenAI conventions are the default; dashboards and alerts built onagent.invocation,tool.<name>or thelocus.*metrics keep working withTelemetryHook(semconv="locus-. Tool spans are now keyed bylegacy") tool_call_id, so parallel calls to one tool each get their own span. The hook keeps its state per run: concurrentarun()calls on oneAgentare one trace each, a sub-agent run from inside a tool files under that call'sexecute_toolspan, a hook-requested model retry gives every attempt its ownchatspan, and a run that fails closes the model, tool and iteration spans it left open witherror.type.gen_ai.token.modalityon the token counters isunknownunless the provider's usage breaks the count down by modality. -
OCIResponsesModeldefaults tostore="auto". Before, the default wasstore=Trueand the first tool-call continuation on a ZDR tenancy failed the run withOCIResponsesStateLostError. The first request of a run is unchanged; only the ZDR case now completes instead of failing. Passstore=Trueto keep the old behaviour, orstore=Falseon 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 answers401: authorization code with PKCE, discovery of the protected-resource and authorization-server metadata, dynamic client registration (or a hosted client-metadata document viaclient_metadata_url), token refresh, and a browser hand-off with a loopback listener that a headless process replaces with its ownredirect_handler/callback_handler. Tokens live in a pluggable store:InMemoryTokenStore(default),FileTokenStore(a0600file under the user's config directory) orKeyringTokenStore(the optionalkeyringpackage). No token value is logged. AnAuthorizationheader or a staticaccess_tokenstill wins over OAuth. - Toolset shaping on
MCPClient.include=andexclude=take server tool names or globs,prefix=renames what is imported, so two servers mount without name clashes. Order:allowed_toolsandincludenarrow,excluderemoves (and wins overinclude),tool_filterdecides last,prefixis applied after matching. Calls through either name land; a shaped-out tool raisesMCPToolNotAllowedError. - Elicitation. A server that asks the person a question mid-call pauses
the agent run through the interrupt mechanism: an
InterruptEventwhosefieldsdescribe the requested schema and whosemetadatacarriesmcp_elicitation.client.thenanswer_ elicitation(event, answer) agent.re-issues the call with the answer.resume(answer, perform_ dangling=True) elicitation_handler=answers without pausing (and outside a run); with neither, a question outside a run is declined.MCPElicitationandElicitationAnswerare the types. An agent served byLocusMCPServerhas its ownask_userquestions relayed to the MCP client as elicitations throughrun_agent_stream. - W3C trace context in MCP
_meta. Everytools/callthe agent makes carriestraceparent/tracestateparented to the telemetry hook's span for that tool call (TelemetryHooknow exposes it throughcurrent_tool_span()), and every callLocusMCPServerserves runs under the context its_metacarries, so an MCP hop stays inside one trace.propagate_trace=Falseopts out;locus.integrations.mcp_tracingholdstrace_meta()andtrace_scope()for other servers. locus mcp serve <target>exposes an agent (MODULE:ATTR/FILE.py:ATTR, anAgent, a factory, aToolor a list of tools) or a bare module of@toolfunctions as an MCP server over stdio (default) or Streamable HTTP (-).- transport http - - host - - port - - path create_tool_server(tools)andLocusMCPServer.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/(whatlocus codex initplaces) teaches the policy file form withlocus policy lint/explainandPolicyWatcher, the tool-call judge and@tool(read_only=True), tool-call integrity, the database approval stores,approval_store()andpending_holds(),OracleAuditTrailand the object-storage anchors, the OCI Responsesstore="auto", Zero Data Retention,reasoningand native-compaction controls, the server's threads and runs,Last-Event-IDresume,WS /runs/liveand the AG-UI and Vercel AI SDK adapters, and the evaluation primitives (rubrics, evidence receipts and claims, reliability, report diffs andEvalGate), 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 encryptedcompactionitem 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_afterof 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.refusedcarriestool_name. The event named the tool undertoolwhilecontrol.judge.decidedand the agent's tool events usetool_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 anMCPClientsession bound to the caller's; the first tool call waited forever.run_syncnow raises aRuntimeErrornaming 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 noenv, so themcpSDK started the server with a stripped environment (PATH,HOME,USER…) and a server needingPYTHONPATH, an OCI profile or an API key died during the handshake with a bareConnection closed. The server now inheritsos.environ(inherit_env=Falsefor 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_completehadTerminateEvent.final_message=NoneandAgentResult.message == "", soLocusMCPServer'srun_agentandrun_agent_streamreturned "Agent completed without response" after a relayedask_user. The final message is now the terminal tool'sresult/summaryargument, else the assistant text of the turn around the call. The loop also tells the model once, after a reply with no tool call incompletion_mode="explicit", that such a reply ends nothing andtask_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 byOCIChatCompletionsModelandOCIResponsesModel. The value every other OCI auth switch in the SDK — andLOCUS_OCI_AUTH_TYPE— takes as its default was rejected by the V1 transports, so the imagelocus deploybuilds could not run locally with a profile.api_key(andsecurity_token) now mean the profile path:profile=when given, elseOCI_PROFILE, elseDEFAULT.Agent.run_sync()inside a running loop keeps the caller's context variables. The worker thread ran withoutcontextvars.copy_context(), so the OpenTelemetry context was lost: an agent served over MCP throughrun_agentfiled itsinvoke_agentspan in a fresh trace with no parent, althoughLocusMCPServerhad 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 aMeterProvideralready in place flushes the reader it adds. OpenTelemetry'sMeterProvider.force_flush()andshutdown()visit only constructor-time readers, so the documentedmeter_provider.shutdown()exported nothing from the readerinstall()had added and the last interval's metrics were lost.install()now returns anOCIAPMInstallation— still the(tracer_provider, meter_provider)pair — whoseforce_flush()andshutdown()reach what it added; when it joined existing providers thatshutdown()is also registered withatexit.validate_spansignores foreign-scope spans. With FastAPI's nativePOST /or themcppackage'sMCP 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=Nonechecks everything.SpanRecordrecords the scope.OCIContainerInstanceBackendconnects through an OCI Bastion with the defaultknown_hosts="strict". The service reports no host key for a port-forwarding session (bastion_public_host_key_infois empty), so the strict default refused every bastion path with "reports no host key". The bastion's key is now the one inknown_hostsor, failing that, the key the endpoint presents at the first connection, read once withlocus.harness.ssh.learn_host_keyand pinned for the session (anINFOline says so); the container's keys are still pinned from its log, andknown_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 anAuthenticationExceptionuntil the wholeready_timeoutran out, then deleted the instance and the log that said why, and the error could not say whether the bastion or the container'ssshdhad closed the connection. A failure at the jump is now anSSHJumpError(new, exported fromlocus.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 forAUTH_GRACE(90 s) and then raised, naming the bastion or the container'ssshdand 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. SandboxSpecrefuses a field of the wrong type when it is built.SandboxSpec(limits=5)was accepted and the firstexecfailed withAttributeError: 'int' object has no attribute 'bound';backend,limits,warm_pool,envandoptionsare now checked in__post_init__(TypeError), asfrom_mappingalready 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 asname=""keyed by the item id whilecomplete()returned the real name andcall_id. The parser now readsresponse.output_item.addedand.doneforfunction_callitems 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=.on the file, OCI Object Storage and S3 stores wrote the object and then. . , report_ id="build- 42") get(),list()andtrend()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
TieredCompactionwhoseSummarizetier sat beforeClearToolResultsorSlidingWindow, a summary needed again withinmin_iterations_between_summariesiterations ended the turncontext_exhaustedwith 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 bareopenai.gpt-4.1anOCIChatCompletionsModelcarries returnedNone, so every agent on anoci:model logged "No context window known" and fell back to a message window instead of the defaultContextCompactor. An OCI<vendor>.<model>id now resolves the entry of the model it serves, theoci: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) andgpt-5.1have entries with the windows their documentation states. OracleCheckpointSaver.list()returns aware UTC times. ItsCheckpointInfo.created_atcame back timezone-naive (the driver drops the zone of theTIMESTAMP WITH TIME ZONEcolumn), while the adapter, PostgreSQL and object-store backends return aware UTC datetimes, so comparing or sorting infos across backends raisedTypeError. The saver attaches UTC, andparse_timereads 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: .. The agent now raises. . has no attribute 'load' TypeErrorwhen the checkpointer has noload/save, namingBaseCheckpointerand, 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 afterclose()(notebook 52 Part 5 left alocus-nb52-*directory behind).close()on a local.dburi 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 afterclose()or in a new process is searchable.
Deprecated¶
- The
toolkey oftool.integrity.refused. It repeatstool_namefor this release and goes away in the next; readtool_name. - The
locus.securitycompatibility shim is removed in 6.0. It keeps forwarding the control-layer names tolocus.controluntil then; its warning named a release that has long passed and now says 6.0. Import fromlocus.control.
Removed¶
- The
locus-sdk-securitypackage. The security-domain tooling (red-team probes and jobs,Target,SecurityContext, the SOC analyst andPostureReportgrounding, 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 thev5.5.0tag. Thelocus.securitycompatibility shim keeps forwarding the control-layer names tolocus.control; its security-domain names now raise anImportErrorthat says so. The release workflow no longer builds the package.
5.5.0 2026-11-16¶
Added¶
- Reasoning effort on
OCIResponsesModel.OCIResponsesConfigtakesreasoning_effort(also a constructor argument), sent asreasoning={"effort": ...}on bothcomplete()andstream(). Areasoning_effortcall kwarg, such as an agent'smodel_kwargs, overrides it for that call. Unset, noreasoningfield is sent, so the request body is unchanged. Before,reasoning_effortpassed to the constructor or inmodel_kwargswas dropped without a warning.
Fixed¶
OCIResponsesModel.stream()error bodies. A non-2xx on the streaming path was raised ashttpx.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 oncomplete(). Classification also reads the error'sparamfield, so an envelope that namesprevious_response_idthere rather than in the message still maps toOCIResponsesStateLostError.OCIProjectRequiredErroron a 400. The Responses endpoint signals the project requirement for non-OpenAI models with a 400 naming theOpenAI-Project/opc-conversation-store-idheader. That is now mapped toOCIProjectRequiredErrorinstead of a plainRuntimeError.project_ocidreaches the Responses endpoint. It was sent only asopc-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 asOpenAI-Project; with it a non-OpenAI model answers on/responses.
5.4.0 2026-11-10¶
Added¶
- The rubric as data.
locus.evaluation.Rubricnames 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 apass_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). AnEvalCase.rubricmay be a string, as before, or aRubric. - Typed verdicts with provenance.
Verdictcarriesgrade,dimensions,issues, the judge's advisoryjudge_reported_passed/judge_reported_score, and aJudgeProvenance(judge model id, rubric revision, prompt hash, temperature, seed, channel, token usage,self_graded).EvalResultexposesgradeand the fullverdict;EvalReportaddsgrade_distribution. - A structured judge channel with pinned sampling.
LLMJudgesendstemperature=0.0by default, takes an optionalseedandtimeout_s, and receives the verdict through asubmit_verdicttool 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.
EvidenceLedgerlays the run's tool executions out as rows with stable ids (E0,E1, ...,Pfor the prompt).EvalCase.require_receiptsfails when a figure, identifier, date or quoted string in the answer appears in no row;EvalCase.claimsare confirmed by code when the evidence carries their figures and settled by the judge otherwise, through asubmit_claim_checkstool call whose citations are verified against the rows (a quote not in the cited row downgrades the check tounverifiable);EvalCase.groundingruns the GSAR audit over the answer and the ledger with the judge model. Results carryreceipts,claim_checksandgrounding_score. - Control-layer assertions.
EvalCase.forbidden_toolspasses when the tool never executed, where a call the gate refused did not execute;EvalCase.expected_refusalspasses when the gate answereddeniedorheld_for_approvalat least once.EvalCase.expected_tool_callsmatches a call on its arguments (ToolCallExpectation). - Budgets.
EvalCase.max_total_tokensandmax_cost_usdread the run's metrics; a target that reports none fails the check. - Rubric caps.
Rubric.capsdrop 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 recordscaps_applied. - Repeats.
EvalRunner(repeats=)orarun(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.sampleskeeps them all, andEvalResult.consistencyflags a case whose readings disagreed by more than the gate; the report countsunstablecases and the summary printspass k/n. - Judge panels and second opinions.
EvalRunner(judges=[...])grades every judged answer with each judge; the first scores the case,EvalResult.panelrecords the panel's agreement andEvalResult.trustthe decision between the first two judges (trusted,calibration_required,rejected), which the summary prints. - Pairwise comparison in both orders.
LLMJudge.compareasks which of two answers better satisfies the rubric, once in each order; a preference that flips with the position is atiewithconsistent=False. locus.evaluation.reliability. Pure functions over verdicts and grade pairs:consistency,panel_agreement,trust_decision,cohen_kappa,calibration_drift,wilson_interval,bootstrap_ciandpublication_gates.- Comparable reports. Every
EvalReportcarries afingerprintof the cases it measured (suite_fingerprint),by_tagcounts,check_failures, the judge models and rubric revisions seen, andsave/load/to_markdown.diff_reportscompares two reports case by case (regressed, improved, added, removed, score and dimension deltas, newly failing checks) and refuses two different suites unless forced.EvalGateis 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_casesreads a JSON, JSONL or YAML file of cases, with a top-level rubric applied to cases that name none;dump_caseswrites one back. locus eval.runloads cases and an agent (and optionally a judge and a rubric), prints the report, saves it and exits with the gate's verdict;diff,gateandsummarywork on saved reports, with--markdowntables 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 carriesnot_graded_reason, the report counts it underEvalReport.not_gradedand leaves it out offailedandavg_score, and the summary prints[NOT GRADED]with the reason. Thejudge_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_gradedis 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.testingdoubles report a context window, so an agent built onScriptedModel,FunctionModelorCompromisedModelcounts 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;Nonekeeps the message-window path.
5.3.1 2026-11-02¶
Fixed¶
locus codex runpasses the arguments after--to Codex in the order typed, whichever side of--the prompt is on;-- -m <model> "task"used to reach Codex scrambled.--helpnames the Codex profile file (~/.codex/<name>.config.toml) correctly.- The retrieval scenario's check in
codex/scenarios/acceptsmake_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 aPROMPT.mdand acheck.shthat runs in the project Codex built: a gated refund with its audit trail, a hold a person approves and a resumed run, aStateGraphfan-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.pyruns them in empty directories throughlocus codex run --execand prints a summary table;--locus-installpoints 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, andtests/docs/test_codex_skill.pymeasures that coverage against every package's__all__so it cannot regress. - Codex builds on Locus. The repository ships a Codex skill,
.agents/skills/locus/: aSKILL.mdthat 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 bytests/docs/test_codex_skill.py. The wheel carries the skill, andlocus codexplaces and uses it:initputs it in a project's.agents/skills/locuswith a Locus section inAGENTS.md, or in~/.agents/skillswith--home;runinstalls it where it is missing and starts Codex with the sandbox settings its recipes need (--exec,--codex-profile, and anything after--go to Codex);pathprints 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_REGIONselects the region foroci:model strings. The provider guide and the environment-variables page said so; the factory behindAgent(model="oci:...")only readOCI_PROFILEand sent every request to the default region. It now takesLOCUS_OCI_REGION, thenOCI_REGION, when neitherregion=norbase_url=is given; the default staysus-chicago-1. -
The harness examples decide by label. The
ControlPolicyshown withbuild_harness(..., wrap=gate_tool)on the README, the landing page and the harness pages now setsrequire_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.OCISandboxBackendruns the harness tools in an OCI Enterprise AI sandbox (pip install "locus-,sdk[oci- sandbox]" oci2.189.0+).create(project_id, ...)makes a sandbox and deletes it onclose();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(/tmpis read-only there), now inSKIP_DIRS.
Changed¶
-
locus-sdk-securityships 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 publisheslocus-sdkalone 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": nullfor it, OCI's endpoint answers400 Invalid type for 'messages[n]., and since the history is replayed on every later turn one tool call ended the run. The transport now sendscontent': expected an object, but got null ""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-meshexample routed no requests, and spoke only the pre-v1.0 surface.A2AClient.get_agent_card()returns v1.0 cards whose skills areAgentSkillobjects, 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'sprotocolVersionandsupportedInterfaces, and talks A2A v1.0 JSON-RPC:SendMessage, with the reply read from the task's artifacts, andSendStreamingMessagefor--stream.--legacykeeps the flat/a2a/invokeand/a2a/streamendpoints to show backwards compatibility. The web console does the same: it discovers peers from/.well-known/agent-card.json, sends withSendMessageand renders theSendStreamingMessagetask 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_goalcarries one line perTaskType(TASK_TYPE_GUIDE), so an extractor model sees what separatesplanfrombuildorresearchfromdiagnoseinstead of thirteen bare names. locus-sdk-securityon PyPI. The release workflow publishes the security package next tolocus-sdk, sopip install locus-sdk-securityreplaces the install-from-repository line; the two stay in lockstep.- Build it with Codex.
codex/SPEC.mdandcodex/PROMPT.mddrive 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.mdat 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.pykeeps 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 ontoapproval_gated_executionand is always held for approval, whatever the gate's thresholds;router.explain()reports the choice asmethod="risk_fallback".CognitiveCompiler(risk_restores the error, and a goal no protocol handles still raises.fallback=None) - 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 onspecialist_fanout. A protocol that lists the goal inprimary_fornow 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:
debateaccepts MEDIUM risk. A debate weighs options and recommends; it changes nothing. Capped at LOW, a comparison the extractor rated MEDIUM risk fell through tospecialist_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_callcould not script the harnesswritetool. The helper reservedcontentfor 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'soci-genaiprofile: a sandboxedcurlreaches OCI Generative AI without the key.examples/imports a profile and creates a provider where the OpenShell CLI is not installed.openshell- gateway/ provider. py - A local NVIDIA OpenShell gateway for the coding harness.
examples/openshell-gateway/starts the gateway withdocker compose up -d(loopback, Docker-outside-of-Docker, adapted from NVIDIA's reference deployment) soOpenShellBackendand the live harness tests run on any machine with Docker;LOCUS_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.OPENSHELL_ ENDPOINT=127. 0. 0. 1:8080
Changed¶
-
CloudSource.describe/eventstake a keyword-onlyclient. OCI services expose several SDK clients (corealone has five), so theSecurityContext().cloudport names one; when omitted it resolves the service's only client and otherwise returns anerrordict listing them. Third-partyCloudSourceproviders 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.txtand/llms-full.txtfor 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, andon_before_compactionis in the table;HookRegistryorders providers and the agent'sHookOrchestratorruns them; three rerankers ship, includingOCICohereReranker; the/resumeroute'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_, quotes a function or class by name so the excerpt follows the code and a renamed symbol fails the build;source <file>::<symbol> }} tests/docs/test_notebook_pages.pyenforces the template;scripts/notebook_output.pycaptures 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_awsand their@toolwrappers), theawsextra on both packages and theLOCUS_AWS_*variables are gone; Locus targets OCI first. The cloud-posture capability stays, on the core OCI tools:create_soc_analyst,SecurityControls,SecurityContext().cloud, thecloud_posture_auditplaybook andsecurity_toolset(oci=True)drivedescribe_oci/use_oci(read-only by default), andSecurityControlscarries the OCIprofile,auth_type,regionandcompartment_idthe review runs as. S3-compatible object storage —S3Backendand thes3extra — 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:andazure:model prefixes,locus.models.native.bedrock/locus.models.native.azure, thebedrockextra and their documentation are gone; Locus targets OCI Generative AI first and keeps OpenAI, Anthropic and the OpenAI-compatible endpoints. Thes3and securityawsextras (Object Storage on S3, the AWS posture audit) are unaffected.
Fixed¶
-
OpenAISearchPreviewProvideralways failed againstgpt-5-search-api. The provider asked the search model for a strictjson_schemaresponse_format, which that model answers with an HTTP 500 (json_objectgets a 400). It now reads theurl_citationannotations 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
-promodels could not call tools (or answer at all) throughopenai:. Chat-completions rejects function tools for the gpt-6 / gpt-6.1 families when reasoning is active and does not serve thegpt-5*-promodels 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. -
OracleAgentMemoryManagercould not use OCI Generative AI models with a profile or session token. litellm'soci/driver, which Oracle'soracleagentmemoryclient 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'sOCI_USER/OCI_KEY_FILEvariables were set. Foroci/...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 viaOCI_AUTH_TYPE) and passes it withOCI_REGIONandOCI_COMPARTMENT_ID;litellm_kwargs=overrides any of it andoci_litellm_auth()exposes the same derivation. The manager also usesMemoryExtractionConfigwhereoracleagentmemoryprovides it instead of the deprecated inline flag. Notebook 44 runs OCI-only by default. -
OCIEmbeddings()andOracleAgentMemoryManagerfailed 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.). The default is nowembed- english- v3. 0 not found 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. Passoutput_dimensions=1024to 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 authenticatewrites a profile withsecurity_token_fileand nouser;OCIModel(the Cohere / SDK transport),OCIEmbeddings,OCICohereRerankerandOCIBucketBackenddefaulted to API-key signing for it and failed withInvalidConfig {'user': 'missing'}unlessauth_type="security_token"was passed. They now detect the profile shape the wayOCIChatCompletionsModelalways did. Found running the suites against a Frankfurt tenancy with a session profile.OCIEmbeddingsalso gains theclose()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 with400 Invalid value at 'contents[n].. The V1 transport now wraps non-object tool results asparts[0]. function_ response. response' {"result": …}forgoogle.*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 nowNone(rank by similarity, bounded bylimit, scores still returned) andas_tool()acceptslimit=/threshold=so a deployment can set its own cut-off. - Gemini on OCI rejected schemas with
enumand validation keywords. OCI's Gemini translation answers400 Unsupported JSON Schema feature for Gemini: enum(alsoadditionalProperties,title,pattern,minimum, …) forresponse_formatschemas and tool parameters — the cognitive router's strictGoalFrameschema has both, so every dispatch failed ongoogle.*models. The V1 transport now foldsenum/constvalues 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
messageand 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 emptymessageand OCI answered400 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, sostart_background()failed with "could not start … in the session workspace" (andtests/unit/harnesshad one permanent failure on a Mac). Withoutsetsidthe backend now enables POSIX job control (set -m), which gives each job its own process group — the unit the kill path signals. max_completion_tokensfor every GPT-5+ and o-series model. The family check was a fixed prefix list (o1,o3,gpt-5), soo4-mini, thegpt-5.6andgpt-6generations still receivedmax_tokensand OCI answered400 Unsupported parameter: 'max_. The check is now a pattern over the generation number.tokens' - Every Anthropic call failed with anthropic 2.3. The SDK pins API
version
2026-10-21, which removedtemperaturefor every model:messages.create()raisedTypeError: unexpected keyword argument 'temperature', and the API answerstemperature: Extra inputs are not permittedif it is sent anyway.AnthropicModelnow omitstemperaturewhen the installed SDK does not declare it, as it already did for the models that reject it. OpenAISearchPreviewProviderreturned nothing. OpenAI retiredgpt-4o-search-previewandgpt-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 usegpt-5-search-api, and*-search-apimodels 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 schedulingaclose()on whichever loop is running; a client built under an earlierasyncio.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 retiredgpt-image-1(400 The model 'gpt-); the default is nowimage- 1' does not exist gpt-image-2.- A timed-out
DockerSandboxcall could leave its code running. With a singledocker run, the timeout could fire before the daemon had created the container; thedocker killthen 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 usesRouter.compile()and hands both routers the same frame, so a difference comes from the picker alone; under the mock model, which cannot fill aGoalFrame, 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 twointparameters, andadd("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 forBaseModelparameters, numbers forstrparameters); values that still do not validate are passed through unchanged, and unannotated orAnyparameters are left alone. - Oracle agent memory with a single connection crashed the driver.
oracleagentmemoryextracts memories on a background thread; sharing one syncoracledb.Connectionbetween that thread and the agent's own queries segfaulted python-oracledb. Notebook 88 and theOracleAgentMemoryManagerdocs now hand the library a connection pool, and the manager gainsaclose()/close()(anddrain()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/v1rejects a tool-enabled request whose first message is a system message with400 Tool calling for this Llama model requires the first message to be a user message— every agent with asystem_prompthit it.OCIChatCompletionsModelnow folds the leading system text into the first user message formeta.llama*when tools are present. -
oci:cohere.command-a-*reached the wrong transport. The string factory only sentcohere.command-r*to the SDK transport, so Command A went to/openai/v1and failed with400 Unsupported OpenAI operation. Everycohere.*id now routes toOCIModel. OCIModelsent the generic chat request to Command A. OCI serves Command A through the Cohere chat API; the generic shape was rejected with400 Chat request type does not match serving model. Allcohere.command*models now useCohereProvider.
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_syncinside a running loop, checkpoint cadence, event payloads) were corrected, and two notebooks were renamed to match their content:notebook_and20_ map_ reduce_ support_ triage. py 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), theKnowledgeProviderexample,Agent.runused synchronously) were fixed, duplicated blocks were merged, and import paths were standardised on the public modules. Theexamples/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:/) behind one prefix: set/ api. runpod. ai/ v2/ <endpoint- id>/ openai/ v1 RUNPOD_API_KEYandRUNPOD_ENDPOINT_ID(orRUNPOD_BASE_URL/LOCUS_RUNPOD_BASE_URL), thenAgent(model="runpod:Qwen/. Verified against RunPod's publicQwen3- 32B- AWQ") qwen3-32b-awqendpoint with a tool call. A live integration test (tests/) covers OpenRouter, Together and RunPod whenever their keys are present.integration/ test_ compatible_ providers_ live. py -
The generic integration tests and the notebooks run against any provider.
LOCUS_TEST_MODEL=provider:modelpoints the sharedmodelfixture at anythinglocus.models.get_modelaccepts (it only knew OpenAI, Anthropic and OCI), andLOCUS_MODEL_PROVIDER/LOCUS_MODEL_IDdo the same for the notebooks (scripts/). Notebooks whose prerequisites are missing exit with 77 and the runner reports them as SKIP instead of FAIL.run_ notebooks. py - - provider <prefix> - - model <id> -
Embeddings examples use
cohere.embed-v4.0(1536-dim). OCI has deprecated the Cohere v3.0 embedding family and recently onboarded tenancies answer404 Entity not foundfor it. TheOCIEmbeddingModelenum gainsCOHERE_EMBED_V4andCOHERE_EMBED_MULTILINGUAL_V4; theOCIEmbeddingsdefault 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 acceptOCI_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 thelocuswordmark 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 agoverned_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 thelocus-sdk-securityfindings 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 onrequests.auth.AuthBase, butrequestswas never declared: the OCI SDK vendors its own copy, and development environments had it through other extras, so importinglocus.models.providers.ociraisedModuleNotFoundError: No module named 'requests'only on a fresh install. Theociextra, and thellm,rag,checkpointsandsdkbundles that include it, now listrequests>=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 roottulip→locus, security add-ontulip-agents-security→locus-sdk-security(importlocus_security), CLItulip/tulip-runner→locus/locus-runner, environment variablesTULIP_*→LOCUS_*,TulipEvent/TulipError/TulipSettings/TulipDeprecationWarning/TulipMCPServer→ theLocus*names. A search-and-replace oftulip→locusin 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. CohereRerankeris Cohere's direct rerank API; the OCI-served reranker is nowOCICohereReranker(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-inOCIResponsesModel. API-key, session-token, instance-principal and resource-principal auth with signer refresh. - Oracle Database 26ai —
OracleVectorStore/OracleSyncVectorStore(nativeVECTOR(N, FLOAT32),VECTOR_DISTANCE, HNSW / IVF indexes, hybrid search, metadata filters),OracleInDBEmbeddings,OracleInDBChunker,OracleADBLoader, theoracle_checkpointer()/OracleBackendcheckpointer, the versionedOracleCheckpointSaver, theOracleStorelong-term memory store andOracleAgentMemoryManagerover Oracle's officialoracleagentmemoryclient, plus sync companions. - OCI Object Storage checkpointer (
OCIBucketBackend,oci_bucket_checkpointer()), OCI embeddings (OCIEmbeddings), theuse_oci/describe_ocibuilt-in tools, and thesanitize_oci_tool_schemahelper. - Extras:
oci,oracledb,agentmemory;checkpoints,rag,llmandsdkinclude 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.pyauto-detects OCI when~/.oci/confighas a usable profile (LOCUS_OCI_*withOCI_*fallbacks); setLOCUS_MODEL_PROVIDER=mockto opt out.
Removed¶
- The Apache-2.0
NOTICEandLICENSES/files that documented the tulip-agents relicensing; superseded byLICENSE(UPL-1.0) andPROVENANCE.md.
Releases before 3.0.0 are listed in CHANGELOG.md on GitHub.