READMEcolmugx/posoco/runtime does not have a README file
#CatalogSource
CatalogSource — a host-owned, versioned tool catalog (experimental
runtime seam). Advanced hosts whose tool set changes over the Agent's
lifetime (dynamic registration, trust/capability gates, remote tool
protocols) supply one via Agent::with_runtime(catalog_source~); plain
extension authors declare tools through ToolProvider and never need
this.
Read protocol — Posoco reads the source only at well-defined points:
- once at Agent construction (the initial snapshot), and
- at each prompt boundary (start of every run_turn, before the run begins) when revision() differs from the last read.
Each revision change triggers exactly one rebuild attempt. When the
rebuilt definitions fail catalog validation (name collision, malformed
schema), the previous snapshot stays in effect and the failure is
surfaced as a secondary_failure observer event — the turn is never
aborted. To retry, change revision() again.
An in-flight run always keeps the snapshot (and catalog version) it
started with; refreshes only affect subsequent runs. Posoco pins the
catalog version monotonically — the source's revision is an opaque
change signal and is never used as the catalog version itself.
#Runtime
pub(open) trait Runtime {
async fn call_model(Self, scope : InvocationScope, messages : Array[Message], tool_definitions : Array[ToolDef], call_options : Json, on_chunk : (Json) -> Unit?) -> Result[ModelCallResult, ModelFailure]
async fn execute_tool(Self, ctx : EffectContext) -> ToolOutcome
async fn cancel_effects(Self, effect_ids : Array[EffectId], reason : CancelReason) -> Array[(EffectId, CancelDisposition)]
async fn compact(Self, scope : InvocationScope, messages : Array[Message], call_options : Json, trigger : CompactTrigger) -> Result[CompactResult, ModelFailure]
}The public effect-execution contract. Mirrors the internal boundary 1:1;
Posoco adapts it mechanically (a thin shim packs/unpacks EffectContext),
so this trait never grows semantics the internal loop does not have.
Implementors usually wrap PortRuntime and override only the methods
they need (typically execute_tool + cancel_effects); see
docs/RUNTIME.md.
#EffectContext
Stable execution context for a single tool effect. effect_id is the
reducer-allocated identity of the ExecuteTool effect — the same id the
runtime later receives in cancel_effects. Runtimes that propagate
cancellation MUST key their in-flight execution state (e.g. an
AbortController) by effect_id, not by execution order or call content.
#PortRuntime
pub struct PortRuntime {
// private fields
}The default runtime, built from the composed extension ports.
impl Runtime for PortRuntime
async fn call_model(self : PortRuntime, scope : InvocationScope, messages : Array[Message], tool_definitions : Array[ToolDef], call_options : Json, on_chunk : (Json) -> Unit?) -> Result[ModelCallResult, ModelFailure]async fn cancel_effects(self : PortRuntime, effect_ids : Array[EffectId], _reason : CancelReason) -> Array[(EffectId, CancelDisposition)]Plain ToolProviders receive no cancel signal, so the default runtime
reports NotPropagated for every effect. Runtimes with real cancellation
wrap this method.
async fn compact(self : PortRuntime, scope : InvocationScope, messages : Array[Message], call_options : Json, trigger : CompactTrigger) -> Result[CompactResult, ModelFailure]Forward compact to ModelPort::compact.
#PortRuntime::new
#RuntimeControl
pub struct RuntimeControl {
// private fields
}The control handle. One instance per Agent; obtained via
Agent::control(). Holds a borrowed internal mailbox for identity
checks and abort signalling, plus its own follow-up queue drained by the
Agent at turn boundaries.
#RuntimeControl::abort_active
Abort the active run. Idempotent: the first call is accepted and the
loop observes it at its next safe point (in-flight effects receive a
best-effort cancel_effects); subsequent calls return
AbortAlreadyRequested. Rejected with RejectedStale when no run is
active.
#RuntimeControl::active_run_id
Currently-active run id, None when the Agent is idle. Hosts use this
(with active_turn_id) to target submissions and to detect staleness.
#RuntimeControl::active_turn_id
Currently-active turn id, None when the Agent is idle.
#RuntimeControl::enqueue_follow_up
Submit a follow-up message. The Agent consumes queued follow-ups one at
a time at turn boundaries (OneAtATime, matching the internal follow-up
mailbox policy) and drives a subsequent turn with each as a new user
message. Rejected with RejectedStale when no run is active — a
background task that finishes after its turn ended cannot sneak a
message into a later run.
#RuntimeControl::new
Construct the control handle over the Agent's shared mailbox. Framework
entry point — hosts obtain the handle from Agent::control(), they do
not construct it.
#RuntimeControl::pending_follow_ups
Number of follow-ups currently queued.
#RuntimeControl::take_follow_up
Take the oldest queued follow-up (OneAtATime). Consumed by the Agent at
turn boundaries; hosts observe depth via pending_follow_ups instead.
LLM Agent framework with hexagonal (ports-and-adapters) architecture. Defines 9 traits + Agent loop. Depends on moonbitlang/async.
llmagentframeworkports-and-adaptersai-runtime
0.10.1
Apache-2.0
Updated 9 days ago
115 downloadsDependencies
- moonbitlang/async0.20.4