lumea-labs Polpo Runtime
Keep execution lifetime, canonical conversation state, and the client transport distinct. A Session stores conversation history; a Run records one execution; a Project Loop is one possible execution mode; SSE is only a delivery transport.
Workflow
- Identify the surface and invocation source: direct chat, Channel, task, schedule, or Loop.
- Preserve
x-session-idwhen continuity is required. Do not rebuild canonical history from client guesses when a continuation API is available. - Use durable delivery for work that must survive disconnects. Reconnect to the Run event log; never repeat the creation request.
- Use direct chat for conversational turns and Project Loops for deterministic multi-step work.
- Validate response schemas, tool calls, tool results, and Loop bindings before they reach a provider or persisted history.
- Use idempotency keys for continuation, schedule triggers, and externally visible actions.
- Inspect terminal events and persisted state, not only the last SSE chunk, before declaring a run successful.
Invariants
- Every assistant tool call persisted into model history has exactly one valid result before a later model turn. Malformed calls are rejected or repaired at the runtime boundary.
- Request-scoped client tools are returned to the client and never executed by Polpo.
- Explicit Project Loop continuation preserves Session, trusted invocation context, and idempotency while recalculating Loop tool policy.
freshsandbox isolation means one fresh lease for the outer run, shared by root tools and nested Loop agent steps.- Steering is accepted only at safe boundaries and never interrupts a tool midway.
- Provider errors must become stable Polpo errors with the useful diagnostic preserved.
References
- references/completions-and-sessions.md
- references/durable-runs.md
- references/project-loops.md
- references/client-tools-and-interactions.md
- references/structured-and-parallel.md
- references/steering-and-runtime-plans.md
- references/context-trust-and-guardrails.md
- references/tasks-and-missions.md
- references/schedules.md
- references/contract-version.md