agent-llm

agent-llm is the LLM/model provider plugin for the agent system.

It talks to model providers and returns structured planning/model outputs. It does not own action authority.

Purpose

agent-llm owns model-provider integration:

• provider API adapters such as OpenAI, Anthropic, local model gateways, or future model services
• prompt/message formatting
• response parsing
• model/tool-call normalization into planning results
• token/accounting metadata
• provider retry/rate-limit behavior
• model streaming transport, when supported
• provider-specific errors and degradation behavior

Authority boundaries

agent-llm is not the action authority and not the credential authority.

• agent-core-system owns action admission, approval, policy, audit, and execution envelopes.
• rpc-plugin-system owns substrate runtime, transport, lifecycle, and plugin supervision.
• agent-keyring owns model-provider credentials, API keys, OAuth/OIDC, service credentials, scoped leases, refresh, rotation, revocation, and credential audit metadata.
• agent-network may own generic HTTP/transport adapters if that layer is used.
• agent-llm owns model-provider semantics and model response normalization.

Model output is proposer data. Returned candidates remain untrusted until agent-core-system admits them.

LLM session model

agent-llm may own provider-native model session mechanics:

• provider conversation/thread/response ids
• model cache/session handles
• streaming ids
• provider-specific message context
• token/accounting continuity

These are implementation details. agent-core-system owns canonical agent task/session state. Provider-native LLM session ids must be exposed to core only as opaque references when needed.

agent-keyring owns credential/session secrets, not model conversation state.

Non-goals

• Do not store model API keys here.
• Do not bypass agent-core-system admission.
• Do not execute tools or provider operations directly.
• Do not mint approval grants.
• Do not treat model tool calls as executable authority.
• Do not leak credentials into prompts, logs, responses, candidate payloads, or workflow evidence.

Current implementation status

The V1 runtime implements:

• llm.plan request/response/candidate contracts and fail-closed validation
• redaction, audit-safe accounting, fake authority mediation, provider sessions, streaming, retry/rate-limit handling
• deterministic fake provider, CLI smoke wiring, and rpc-plugin-system substrate lifecycle service
• OpenAI-compatible adapter behind mediated credential/network seams, with fake transport tests only
• core-emitted tool/capability ingestion as bounded context packets, not executable authority

Verify the repo with:

python3 scripts/workflow-check.py
git diff --check
go test ./...
go test -cover ./...
go build ./...
go vet ./...