Repository navigation
v5.6.0
Added
-
on_request/on_responseon the HTTP-backed OCI models.
OCIResponsesModelandOCIChatCompletionsModel(and their configs)
take a pair of sync callables that see each outgoinghttpx.Request
after 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 asCheckpointInfo
records (id, write time, the state's iteration, the checkpoint's size
as that backend stores it, the checkpoint it descends from —None
only for a thread's first — and, for a fork, the thread it came from);
checkpointer.fork(thread_id, checkpoint_id)starts a new thread from
any of them, with the thread's tool-effect ledger copied up to that
step and no further, so a run on the fork never replays what the
parent did past the fork point;agent.run(..., from_checkpoint=...),
arun,run_syncandagent.resume(..., from_checkpoint=...)
continue a thread from a past checkpoint, the run's first lasting save
recording it as its parent and the rest following on, so the thread's
history shows the branch as a chain; the checkpoint run from is never
deleted.Agent.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 and
PgCheckpointerbackends 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 (FileCheckpointerand
PgCheckpointeralready had one); no bound ever trims a ledger
sidecar, and the object-store backends order checkpoints saved within
one second by the write time in their own metadata, not the listing's
coarse modification time.draw_mermaid_history(checkpointer, *thread_ids)andStateGraph.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), declared
ResourceLimits(amax_exec_sis enforced by clamping everyexec
timeout), 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.harness.testing.assert_backend_conformance(factory)
is the conformance kit: the file, shell, deadline, background-command and
protocol checks the tools assume, run on a backend and reported together;
run_conformance(backend)does the same without closing it. -
SSHSandboxBackend. Any host withsshdas a workspace (thessh
extra,paramiko): commands run under a watchdog on the host so a deadline
kills the process group where it runs, both streams come back in order,
files move over SFTP with 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 unless
known_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-container" | "oci-sandbox" | "openshell" | "e2b" | "daytona" | "memory"plusroot,env,limits, a
WarmPoolHintand 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)keep
warm_pool.readysandboxes created ahead of need, and the hint'sname
reaches a service-side pool (OCI GenAI Sandbox warm pools). The new
sandbox backends page documents the protocol,
the kit and each backend's prerequisites. -
Durability modes.
Agent(durability=...), anddurability=on
run,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"(or
Agent(tool_ledger=True)in any mode) the executor records every
executed tool call in the thread's checkpointer the moment it returns,
keyed by(thread id, step, tool name, canonical arguments), as
checkpoints of the sidecar thread<thread_id>~ledger. A run that
continues the turn after a crash —Agent.continue_turn(thread_id),
the newAgent.resume(invocation_id=..., thread_id=...), or
Agent.run(..., invocation_id=...)under the id the crashed run was
started with — replays a recorded call instead of running the tool
again and runs only the calls with no record;ToolResult.replayed
marks a replayed result.continue_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_idempotent_on_replay= True)letsidempotent=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's
supportedInterfaceslists 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_notifications= PushNotificationSettings(...))delivers every status and artifact change
to the webhooks a task registers (inSendMessage's configuration or with
the*TaskPushNotificationConfigmethods), with the token and
Authorizationthe 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_message(..., push_notification_config=..., blocking=False)returns the task at once and runs it in the background. -
A2A interrupt mapping. A run that pauses for a person —
ask_user, or
an approval hold 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 through
Agent.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 task
rejected. -
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 withTAG
filters on declared metadata keys),MongoDBAtlasVectorStore
($vectorSearch,ensure_index()creates the Atlas index) and
PineconeVectorStore(serverless indexes). Each sits behind the existing
VectorStoreprotocol 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 over
httpxwithJINA_API_KEY/VOYAGE_API_KEY. -
Hybrid search, one switch.
RAGRetriever(hybrid=True, hybrid_alpha=…)
callsstore.hybrid_search(query_text, query_embedding, alpha=…)on
stores implementing the newHybridSearchableprotocol — 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 and
hybrid_kwargspasses store-specific options such as Oracle's
use_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, andexamples/config.get_embedder()builds
OCIEmbeddingswhenLOCUS_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 anEvalCaseunder
evaluators, is one check named by its label, loads from a case file by
kind, enters the suite fingerprint, and leaves a typed
EvaluatorVerdictwith 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_user= SimulatedUser(persona=..., goal=..., max_turns=..., stop_on=[...]))has a
model play that user against the agent inarun(), 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 an
OnlineBudget(total, per minute, in flight), and grades them in the
background with the same checks and judge as a suite through the new
EvalRunner.agrade(case, result).attach(run_id, prompt=, output=, arguments=)supplies what the bus does not carry;submit(prompt, result)
grades a result the application holds.report()is 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 a
ReportStore: a directory, an Oracle AI Database table
(OracleReportStore, headline figures in columns and the report as JSON),
an OCI Object Storage bucket (OCIBucketReportStore) or an S3-compatible
bucket (S3ReportStore), 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 --store <spec> --suite <name>keeps the report after a run
andlocus eval trend --store <spec> --suite <name>prints the trend,
exiting 1 when the newest report is worse than the one before it. Notebook
56 gains a trajectory case and a simulated-user case. -
locus deploy: the agent server on OCI.locus deploy 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,apply
anddestroytake--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 with
python -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-legacy")keeps the previous
agent.invocation/agent.iteration.<n>/tool.<name>spans and
locus.*metrics.locus.observability.semconvholds the names and a
validate_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.observability.exporters.oci_apm(endpoint, private_data_key)builds
the OTLP/HTTP span and metric exporters for an APM domain (data upload
endpoint,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=…)and
governed_agent(audit_trail=…)take it unchanged;record()commits the
row before it returns, several processes can share one trail (a stale
writer reloads and continues the chain instead of forking it), and
verify()re-reads the rows and recomputes every hash. On a blockchain
table it also checks that every row carries its database-side hash
(ORABCTAB_HASH$) and 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_trail(trail, store, every=…)writes the current head (record count, sequence number, hash,
timestamp) as a small JSON object into an OCI Object Storage bucket
(OCIBucketAnchorStore) or any S3-compatible bucket (S3AnchorStore);
verify_anchor(trail, store)checks the chain still reaches the latest
anchor, so a trail cut short of it fails.require_retention_rule=True
refuses to anchor into a bucket without a retention rule (OCI) or Object
Lock (S3).anchor_periodically()is the loop a server or runner calls.
The observability, control-layer and guarantees pages describe when to use
each backend. -
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 a
PolicyFileErrorthat names the key and its path
(require_human_for[2]). Reading YAML needs the optionalpyyaml
package; JSON and writing need nothing.policy.content_hash()is the
SHA-256 of the rules, equal for equal policies however they were built. -
The policy hash on the audit trail.
admit()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/--kinds
declare. 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> --action '{...}'prints every rule,
fired or not, the outcome and whether a person can approve it;
--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 evaluation
approve()andexplain()share;lint_policy(),explain()and
PolicyDocumentare the same from Python. -
Notebook 71 loads its policy from
examples/notebook_71_refund_policy.yaml;
the policy authoring guide shows the file form first and a CI lint job. -
A model-based tool-call judge that feeds the gate.
locus.control.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 under
judge(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 typed
ToolCallIntegrityError, an entry on the agent'sAuditTrail(the signed
and received digests, and the hook the change is attributed to), a
tool.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="...")or
ToolCallSigner.resign, so the chain of custody names them; the built-in
GuardrailsHookredaction 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,RedisApprovals
andOracleApprovalsimplementApprovalStorewith 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_holds(checkpointer, thread_id)reads it back in another process,PendingHold.state(store)
re-checks it, and the hold leaves the checkpoint when the call is answered.
Checkpoints written before this carry no holds and resume as before. The
gate's interrupt metadata gains astorekey. -
locus approvalsagainst any store.--storetakes a spec (or
LOCUS_APPROVALS_STORE), a bare path still means aFileApprovalsfile,
--byfalls back toLOCUS_APPROVER, andapprove/rejecttake
--reason, recorded on the decision.ApprovalStore.decide()accepts
reason=""for the same purpose. -
Notebook 73 (support account gate) now ends with the hold parked in a
file-backed store, approved from another process throughlocus 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 as
ModelResponse.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.encrypted_content"];
the reasoning items that come back stay on the assistant message under
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_compaction=True), or
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, the
CompactionEventcarriesstage="native"(new value), the compaction
call's tokens count against the run's budgets, and a failed call falls
back to the client-side summary. Opt-in; off by default. -
Zero Data Retention detection on
OCIResponsesModel. A tenancy with
Zero Data Retention (ZDR) answers every request that carries
previous_response_idwith a 400 saying so. That reply now raises
OCIResponsesZeroDataRetentionError, a subclass of
OCIResponsesStateLostErrorso existing handlers keep working.store
accepts"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 a
CustomEventnamedserver_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/resume
semantics, as a run of its own) and answers at once with a run id while
the agent runs in the background;GET /runs/{id}reports its status and
outcome;GET /runs/{id}/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}/cancel
asks 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_per_run=500, max_runs=200, ttl_seconds=3600), passed asAgentServer(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-ui
takes aRunAgentInputand streamsRUN_STARTED,TEXT_MESSAGE_*,
TOOL_CALL_*,STATE_SNAPSHOT/STATE_DELTA,CUSTOMand
RUN_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 as
GET /runs/{id}/events?protocol=ag-ui|vercel-ai, resume included. The
conservative readings of the two protocols are recorded on the server
page.examples/server_ui/holds two plain HTML pages (resumable SSE, and
an AG-UI client); notebook 65 follows, drops and resumes a run. -
GET /threads/{id}now adds the thread'srunsand asourcefield,
answers from the registry when no checkpointer is configured, and no
longer fails with a 500 for a runnable withoutconfig(a
GraphRunnable);DELETE /threads/{id}forgets the thread's finished
runs as well. -
Tiered compaction.
TieredCompaction([ClearToolResults, SlidingWindow, Summarize, Relevance])(locus.memory.tiers) runs compaction tiers in
order, each at its own trigger as a fraction of the usable window (0.5,
0.7, 0.85 and 0.95 by default): stale tool outputs become stubs, the
oldest turns past a turn window are dropped, older history is summarised
by the existing summariser and, as a last resort, only the turns relevant
to the current task stay (by embeddings with 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_manager=TieredCompaction(...)
orCompactionConfig(tiers=True | [...]); the agent binds the pipeline to
its model and window. OneCompactionEventper tier that ran, withtier
and the tokens before and after it;stagegains"window"and
"relevance". -
Pinned messages.
pin(message)(ormetadata={"pin": True}) and a
pins=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_result_offload=...), orTrue
for an in-memory store. The coding harness includes the same
fetch_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 with
TelemetryHook(semconv="locus-legacy"). Tool spans are now keyed by
tool_call_id, so parallel calls to one tool each get their own span.
The hook keeps its state per run: concurrentarun()calls on one
Agentare 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 was
store=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. Pass
store=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(a
0600file under the user's config directory) orKeyringTokenStore
(the optionalkeyringpackage). No token value is logged. An
Authorizationheader 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: anInterruptEventwhose
fieldsdescribe the requested schema and whosemetadatacarries
mcp_elicitation.client.answer_elicitation(event, answer)then
agent.resume(answer, perform_dangling=True)re-issues the call with the
answer.elicitation_handler=answers without pausing (and outside a run);
with neither, a question outside a run is declined.MCPElicitationand
ElicitationAnswerare the types. An agent served byLocusMCPServer
has 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 through
current_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_tracingholds
trace_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/(what
locus 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_after
of a native compaction could shrink while the replayed request grew, as
the item's few KB were counted as a one-line placeholder; the report and
the request now move together. Other metadata stays free. tool.integrity.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 aRuntimeError
naming the client and the fix (await agent.arun(...)), and the MCP
getting-started page uses the async form.- A stdio MCP server starts with this process's environment.
MCPClient(server_command=...)passed 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 inherits
os.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=Noneand
AgentResult.message == "", soLocusMCPServer'srun_agentand
run_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 in
completion_mode="explicit", that such a reply ends nothing and
task_complete(summary=...)does — before, the same context went back
unchanged until the budget warning, which cost a dozen iterations for a
one-line answer. auth_type="api_key"is accepted byOCIChatCompletionsModeland
OCIResponsesModel. 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 through
run_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()and
shutdown()visit only constructor-time readers, so the documented
meter_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 with
atexit.validate_spansignores foreign-scope spans. With FastAPI's native
POST /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 with
locus.harness.ssh.learn_host_keyand pinned for the session (anINFO
line says so); the container's keys are still pinned from its log, and
known_hosts="accept-unknown"stays the explicit unverified opt-in. The
unit stand-in for the bastion now reports no key, as the service does.- A key the bastion or the container refuses is reported as such, in time,
with the container log.create()retried anAuthenticationException
until 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 with
AttributeError: '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=..., report_id="build-42")on the file, OCI Object Storage and S3
stores wrote the object and thenget(),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 aTieredCompactionwhoseSummarizetier sat before
ClearToolResultsorSlidingWindow, a summary needed again within
min_iterations_between_summariesiterations ended the turn
context_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 returned
None, 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. Its
CheckpointInfo.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, and
parse_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: ... has no attribute 'load'. The agent now raises
TypeErrorwhen the checkpointer has noload/save, naming
BaseCheckpointerand, 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 a
locus-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 and
PostureReportgrounding, 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 an
ImportErrorthat says so. The release workflow no longer builds the
package.