Skip to content

DESIGN.md

Latest commit

 

History

History
73 lines (50 loc) · 4.93 KB

DESIGN.md

File metadata and controls

73 lines (50 loc) · 4.93 KB
Raw

agrun Design Overview

Governance view. Committed source and tests define implemented behavior. Detailed contracts live under agrun_docs/.

中文摘要： agrun 是 browser-first、同时支持 Node.js host 的通用 Agent Runtime。4.x 默认保持 legacy；宿主可显式启用 minimal profile、Plugin Manifest 和 capability 级组合。

Current system

agrun ships one environment-neutral runtime bundle. Browser hosts can load the same core through a script tag or bundler; Node.js hosts use that core plus opt-in adapters under node/. The core must not require filesystem, process, or other Node-only APIs.

The execution shape is:

host input
  -> session and context assembly
  -> provider-backed planner
  -> policy/approval gate
  -> action or Agent Skill tool execution
  -> structured observation and state update
  -> final answer or explicit continuation

The runtime owns mechanism: lifecycle, state, budgets, abort, approval, action dispatch, evidence identity, result assembly, and observability. The model and portable Agent Skills own task policy, tool choice, reasoning, and user-facing prose.

Current extension seams

The implemented extension surfaces are separate:

Surface Current host entry point Purpose
LLM providers providers and the existing provider adapter path Model transport and normalization
Host actions customActions with defineAction() Host-owned executable tools
Agent Skills agentSkills / agentSkillIndexProvider Portable instructions and optional browser-safe tools
Prompt sections prompts and plannerDirectives Host prompt replacement or extension
Policy and lifecycle Runtime configuration, action/skill policy, callbacks Safety and host integration

These seams remain independently usable. AGRUN-646 also adds definePlugin() as a bounded composition layer over them; it does not expose runtime-internal mutation hooks. The generated Runtime Surface Index inventories static capability, prompt, action, and skill definitions. runtime.describeComposition() and runtime.inspectPrompt(...) expose one instance's resolved actions, Agent Skills, capabilities, prompt sections, provider/profile context, origins, and size estimates without calling a provider.

Current configurability

Hosts can disable exact actions with disabledActions, or use disabledCapabilities to atomically remove a declared capability's actions, prompt contribution, and supported policy defaults. profile: "minimal" is opt-in; omitted/legacy keeps the 4.x surface.

plannerMode: "auto" currently resolves to native_tools; envelope remains an explicit override and the default native failure fallback.

Implemented composition architecture

AGRUN-645 and AGRUN-646 implement the logical composition and inspection surface:

createRuntime({
  profile: "minimal",
  plugins: [],
  disabledCapabilities: []
});

A browser-safe plugin manifest may compose actions, agentSkills, promptSections, policy data, JSON-safe diagnostics, and built-in capability declarations. Node-only behavior remains behind declared host adapters, not imported into the browser core.

The 4.x line keeps this model additive and opt-in. AGRUN-648 rejected default promotion after the repeated three-provider matrix regressed wall time, provider calls, and uncached input at the matrix median. Physical bundle splitting and any future default proposal require a new evidence-backed task; they are not implied by the implemented composition API.

Design invariants

  • No model-name branches or prompt-regex intent classifiers in the runtime kernel.
  • Host composition describes available deployment capability; the model decides how to use the enabled capability.
  • Existing integrations keep their 4.x defaults.
  • Prompt and tool surfaces should include only active capability without hiding runtime truth.
  • Long-form research is a demanding skill/task benchmark, not a separate runtime architecture.
  • Historical audits remain evidence for their date, not current contract authority.
  • Exactly one terminal door stamps final-text normalization as done per run; every other path must check that stamp rather than re-applying the same non-idempotent transform (a repeated citation-loss root cause across AGRUN-664/666/673).

Recent architecture-relevant decisions

  • ADR-0061 (AGRUN-662, 2026-07-31). The delivered-citation quality gate stays non-blocking by default. A host-declared minimum (requestedCitations.minUrlCount) may request a bounded, host-configurable number of terminal review attempts (maxReviews, default 2); once the budget is spent, the runtime discloses any remaining gap in the delivered text rather than blocking, forcing another cycle, or shipping silently. Hard enforcement stays an explicit host opt-in (candidateQuality.sourceIssueSeverity).