Use context utilities with external harnesses¶
Choose an integration boundary that the host exposes: a provider endpoint, a callable/command utility, a completed-result hook, or a history replacement API. Each path uses the same context transforms. The harness retains its own agent loop, tool permissions, and session persistence.
To prepare model context before choosing a provider, use portable Interaction views. Proposal generation, owner acceptance, and replay are separate calls. The same accepted checkpoint works with compatible backends and through programmatic host callbacks or utility RPC.
Integrate through host APIs¶
Python host plugins can call compress_content, project_messages,
compact_history, and compact_host_history directly. These calls require no
shell process, HTTP listener, or A11 agent. A request callback can project an
editable message list before the host calls its existing provider client:
from a11.sdk.llm_context import LlmContextConfig, project_messages
policy = LlmContextConfig(input_content="lossless", tool_results="lossless")
projected = await project_messages(provider_messages, policy)
For a host that supports checkpoint installation, bind two callbacks:
from a11.sdk.llm_context import compact_host_history
result = await compact_host_history(
read_history=host_snapshot,
replace_history=host_replace_checkpoint,
config=checkpoint_policy,
summarizer=summarize_prefix,
)
host_snapshot() returns {"history": [...], "revision": ...}. The installer
accepts (proposal, *, expected_revision, source_digest), checks those values
atomically in the host, replaces the covered prefix, and acknowledges
{"installed": true, "revision": ...}. Both callbacks support synchronous or
asynchronous implementations. A11 rechecks the snapshot after summarization;
the host's atomic check closes the remaining race. Explicit revisions work
across processes and machines. A changed source returns ABORTED. An uncertain
installation receives no implicit retry.
A plugin in another language calls the ordinary utility actions through its A11 client. This is utility RPC over an existing A11 transport, independently of the host's model connection. TypeScript and Kotlin clients use the same JSON request/result contracts and context headers as Python. Ordinary action discovery supplies the utility schema. Source validation and host installation remain explicit after the call.
| Host integration | Programmatic path | Host responsibility |
|---|---|---|
| Python harness/plugin | Import the utilities and register request/result or checkpoint callbacks. | Map native records into editable spans and acknowledge any history replacement. |
| TypeScript harness/plugin | Call utility actions with the A11 TypeScript client; use the native host event API for installation. | Keep the host's inference client and persist accepted checkpoints in its session. |
| JVM/Junie plugin | Call the same actions with the existing Kotlin A11 client from its plugin service. | Map editor/harness records and use a supported host result/history update API. |
| Codex or Claude Code integration | A host application can call the library or utility RPC from its own SDK/event callbacks. | Check the installed host's supported mutation APIs; lifecycle notifications alone do not supply history replacement. |
| Pi extension | Request a proposal from a utility client and return it through session_before_compact. |
Preserve Pi's prepared boundary and active branch identity. |
The shared transform layer contains no harness event names. Its public message views,
reports, source IDs, proposals, and explicit installation acknowledgements let
an adapter use selected capabilities. Where replacement is unavailable, use
compact_history to obtain a proposal for a handoff or use deterministic
request/result projection at the host's editable boundary.
Intercept provider requests¶
Start a proxy for a provider's wire format:
a11 llm-context proxy --upstream https://api.anthropic.com \
--profile anthropic --port 8013 \
--config '{"input_content":"lossless","tool_results":"lossless","strategy":"json"}' \
--record /tmp/context-proxy.jsonl
Configure the host's supported provider base URL to point at
http://127.0.0.1:8013. The listener preserves incoming paths; use an upstream
origin when the client already sends /v1/.... An optional upstream path prefix
is prepended literally. Credentials stay in request headers and pass through to
the configured upstream. Caller x-a11-* headers are removed before forwarding
and cannot select proxy policy.
The available profiles are chat (/chat/completions), responses
(/responses), and anthropic (/messages). Only POST JSON requests in those
formats receive projections. Unknown endpoints and content encodings pass
through. Request bodies use configured byte limits. Proxy responses stream
through the native HTTP stack, including SSE, error bodies, duplicate headers,
and trailers. Admission, buffering, and deadlines are bounded.
An embedded host can call create_proxy(...), supplying LlmContextServices and
native HTTP transport/TLS options. Call stop() on the returned native server
to close its listener. Bind authenticated remote listeners through the host's
existing HTTP deployment configuration.
An endpoint setting establishes wire routing only. Verify the installed host's
authentication mode and API support separately, especially for subscription or
login-specific endpoints. The proxy applies deterministic content transforms.
It rejects summary and native compaction because it cannot install the shorter
history in the host. Recomputing a checkpoint on every request changes the
prompt prefix and can discard cache reuse. Use compact_host_history with an
atomic host installer, an accepted Interaction view, or a native session
coordinator for compaction. The proxy recorder observes projection/relay
metadata and bounded JSON/SSE provider usage. Missing or partial usage retains
its coverage limits. Automatic owner-backed retention uses host scope resolution
and authorization callbacks; the standalone CLI requires an embedded host for
those bindings.
Choose one compression owner for a request path. When a proxy projects content, disable the corresponding A11 action-side transform. Provenance comes from the configured boundary or explicit source metadata; arbitrary output markers do not establish that content has already been processed.
Call utilities without proxying inference¶
printf '{ "rows": [1, 2, 3] }' | \
a11 llm-context compress --config '{"strategy":"json","min_gain":0}'
The JSON result contains the view and report. A host can use the Python library in-process, invoke the CLI over stdin/stdout, or call ordinary context actions through an existing A11 connection. None of these paths requires an A11 agent.
For a checkpoint proposal, send JSON history to the standalone utility:
a11 llm-context compact \
--config '{"max_tokens":12000,"reserve_tokens":2000,"retain_recent":4}' \
--summarizer my_host.summaries:checkpoint < history.json
The explicitly selected host callable accepts the prefix and returns summary
text. A checkpoint already generated by the host can instead be supplied as
checkpoint in stdin JSON. A host installing the proposal validates its source
digest and covered IDs against the active branch before replacing history.
Appending a summary while retaining the covered prefix is a handoff aid; it
does not reclaim that prefix's context space.
Integrate a Pi compaction callback¶
Map Pi's session_before_compact preparation into an ordinary compaction
utility call. Preserve its selected prefix and retained-entry boundary, validate
the proposal's source digest and active leaf, and return the accepted checkpoint
through Pi's event API. The host owns cancellation, opt-in configuration,
inference, and session persistence.
Use the Pi extension contract for the installed version. The shared A11 utilities provide the proposal; the host plugin supplies the Pi event mapping.
Intercept completed shell results¶
from a11.sdk.llm_context import LlmContextConfig, intercept_shell_result
policy = LlmContextConfig(shell={"mode": "compress"})
projection = intercept_shell_result(
{"stdout": captured_stdout, "stderr": captured_stderr, "exit_code": 0},
policy,
)
model_result = projection["view"]
original_result = projection["original"]
off returns original presentation. observe records counts with unchanged
presentation. compress applies the shared transforms. Command failures,
signals, binary/unknown encodings, interactive sessions, incomplete streams,
truncation, bypasses, and transform failures pass through. The command executes
once in its existing host. stdout/stderr stay separate.
The shared model-tool bridge recognizes completed spawn_process and run_command results and
applies shell.mode at result presentation. A compressed line-array field is
a {representation: "application/json", view: ...} envelope; expanding the view
and parsing its JSON recovers the original array. Native byte ports retain
their encoded presentation. Raw typed process ports remain
available to Flow. External hooks map their completed result into the same
contract. A host-specific hook can invoke:
Its stdin envelope is:
{
"schema": "a11.llm-context.shell-result/v1",
"result": {"stdout": "captured output", "stderr": "", "exit_code": 0},
"source": {"command": "host-provided hint"},
"bypass": false
}
Map the returned event.result into the host's replacement-output API. The
returned reports remain outside model-visible output. Unsupported event
contracts pass through with supported=false; the utility implements no
pre-execution shell grammar or command rewrite.
a11 llm-context shell-filter provides raw stdin/stdout projection for an explicit
filter boundary. Enable it with --config '{"shell":{"mode":"compress"}}'.
On capture overflow it forwards the original stream. Pipeline exit-status and
approval behavior belong to the caller's shell/harness; completed-result hooks
retain those responsibilities in their existing host.
For Codex, Claude Code, and Junie, select a verified endpoint or result-hook API from the installed version. Generic lifecycle notifications alone do not grant custom history replacement. Claude Code's PostToolUse documentation describes its output replacement contract. A11 adds no context MCP server or tool catalog.
Coordinate native session compaction¶
Select compaction="native" for resumed interact_with_codex and
interact_with_claude_code actions. The same action header works through Flow.
The action awaits native completion before submitting pending user input.
Fresh sessions have no prior history to compact. Shadow mode leaves the native
session unchanged. Other provider/proxy boundaries reject native compaction
without a coordinator; they do not append a synthetic replacement summary.
An application using an existing Codex app-server connection can call:
from a11.sdk.llm_context import compact_codex_thread
await compact_codex_thread(rpc.request, compact_events.get, thread_id)
Subscribe before calling and keep the host's ordinary event reader running.
The coordinator requires both a matching contextCompaction completion item
and successful completion of that item's turn. Notifications from child threads
supply no completion evidence for the requested thread. Timeout or disconnect
leaves an indeterminate result; inspect host state before another attempt.
See the Codex app-server protocol.
For an already connected Claude Agent SDK client:
from a11.sdk.llm_context import compact_claude_session
await compact_claude_session(client, on_message=observe_compaction)
await client.query(next_prompt)
The application serializes access to receive_response. The coordinator sends
/compact and requires a compaction boundary and successful result. Optional
instructions identify facts the native summary must preserve. An explicit
structured insufficient-history response returns an acknowledged no-op. The
observer receives all messages for usage attribution. The action integration
records compaction usage separately from the following generation.
See Claude Agent SDK commands.
Junie ACP clients can call compact_acp_session(request, session_id, commands)
when that session advertises compress. The adapter submits /compress through
session/prompt and returns its acknowledgement. project_acp_prompt projects
text blocks in a user prompt while preserving resource/image blocks. Filesystem
read responses remain canonical inputs for editing operations.
See Junie commands and
ACP commands.
| Installed harness | Checked boundary | Runtime capability requirement |
|---|---|---|
| Codex 0.164.0 | Live SDK paired requests and native compaction continuation | Native thread/compact/start and matching completion notifications. |
| Claude Code 2.1.266 / Python SDK 0.2.148 | Live SDK paired requests; native default and focused summary checks | /compact, compact_boundary, and successful result; output replacement support depends on the installed CLI. |
| Junie 26.8.24 | Installed CLI ACP availability and documented command contract | Session-advertised compress; absent advertisement raises a capability error. |
Live validation covers Codex and Claude Code compaction and small paired input-compression workloads. Junie checks cover its stated adapter contract; the cross-version deployment matrix remains open.
Use programmatic result hooks¶
codex_tool_hook(event, policy) maps a documented Codex PostToolUse event to
continue=false and stopReason when a successful completed result changes.
Unknown result shapes pass through. The event must carry a structured
tool_response with an integer exit_code. This conservative mapping preserves
failures and avoids changing code-mode promise failure behavior. See
Codex hooks.
claude_code_hooks(policy) supplies a Python Claude Agent SDK hook mapping for
ClaudeAgentOptions(hooks=...). It uses updatedToolOutput, preserving original
result fields. Bash results without a known integer exit_code or exitCode
pass through; an SDK/CLI combination that omits this evidence requires a
host-owned completed-result adapter. No exit status is inferred from stdout.
See Claude hooks.
Retain proxy views with host identity¶
Embed create_proxy with LlmContextServices(resolve_scope=...,
authorize_scope=..., retention=...). The resolver receives the HTTP request and
returns an explicit owner/conversation/branch/revision/operation scope after
host authentication. The authorizer separately grants access to that scope.
Incoming private A11 headers are removed before upstream forwarding. Caller
policy does not choose the host's storage path or service callbacks.
project_view provides the same storage orchestration to programmatic callers
with an already authorized scope. Its result contains messages, updated scope,
and an owner-backed descriptor. The proxy publishes descriptors through its
recorder; provider response envelopes remain unchanged. Owner utilities expose
retained originals and accepted views through ordinary A11 sessions.