Skip to content

AGENTS.md

Latest commit

 

History

History
104 lines (91 loc) · 5.92 KB

AGENTS.md

File metadata and controls

104 lines (91 loc) · 5.92 KB
Raw

agent-runtime Agent Guide

Scope: this guide applies to src/crates/execution/agent-runtime.

bitfun-agent-runtime owns portable agent runtime decisions, session/config/context facts, lifecycle helper state, and the narrow port-backed sdk / AgentRuntime facade that can be built and tested without bitfun-core.

Guardrails

  • Do not depend on bitfun-core, app crates, Tauri, ACP protocol, web UI, concrete service crates, or product-domain implementations.
  • The sdk module may re-export only stable runtime request/response types, runtime-port contracts, and the service/tool/harness registry types needed for dependency injection. It must not re-export raw PluginRuntimeClient types such as plugin runtime bindings, dispatch/read request types, status snapshots, plugin fault diagnostics, or host clients; Product Assembly uses the internal runtime builder when it needs to inject a plugin runtime.
  • AgentRuntime may depend on stable ports plus injected RuntimeServices, tool registry, harness registry, and hook registry. Product assembly owns concrete registration; this crate must not create concrete managers, app state, filesystem, terminal, MCP, remote, or AI clients.
  • The runtime module is internal / Product Assembly facing. Do not route client-facing SDK, Server/API, app, Web, mobile, or installer entrypoints through bitfun_agent_runtime::runtime; those surfaces must use sdk or projected Server/API DTOs.
  • Keep concrete scheduler/session lifecycle execution, session metadata IO, event emitter wiring, workspace/remote permission-scope projection, native permission Hook ordering, permission UI presentation, and product Tool adapter execution in bitfun-core until a reviewed owner migration proves behavior equivalence. Provider-neutral permission policy/grant planning, confirmation gate/wait-channel, and user-question state may live here.
  • Prefer pure facts and decisions first: queue policy, background delivery, dialog-turn queue state, active-turn facts, cancellation routing and suppression state, background running-turn injection construction, steering action planning, agent-session reply planning, thread-goal accounting/mutation/continuation decisions, scheduled-job lifecycle state transitions, runtime event facts, registry visibility/availability, custom subagent schema/default decisions, builtin agent definition catalog, skill catalog/root/mode/selection facts, thread-goal metadata / event payload / token usage / scheduler delivery plans, thread-goal tool wire contracts, session config/defaults/summary and persisted session-state sidecar shape, user-question validation/result/channel contracts, SessionControl input/cancel-route/result contracts, DeepReview policy/manifest/budget/queue/report/cache/shared-context/task-execution shaping decisions, DeepResearch citation renumbering, custom subagent markdown front-matter IO, custom subagent discovery/loading, post-call hook routing/executor orchestration, tool confirmation gate/planning/failure/wait-result/channel mapping, light checkpoint summary policy, dialog-turn cancellation token state, round-boundary yield/injection state, turn-outcome queue decisions, registry source/profile facts, prompt-loop user-context policy, prompt listing reminder ordering, prompt-cache policy/identity/store, prompt runtime/workspace/user-context rendering, turn skill/agent snapshot state, file-read session state, session evidence ledger projection, finish-reason labels, session-state event labels, and turn-outcome event facts.
  • Keep concrete prompt fact collection, workspace context IO, prompt-cache persistence wiring, dynamic environment collection, concrete hook side effects, DeepReview task launch/provider wait/report persistence, DeepResearch storage IO/post-turn hook and concrete product tool execution outside this crate until a reviewed migration proves behavior equivalence.
  • Add focused tests before moving any runtime decision into this crate.

Test Target Layout

Integration contracts use five explicit Cargo targets so package-level checks do not relink the same feature-free dependency closure for every source file, while platform-specific process tests retain executable-level isolation:

Target Owns
agent_definition_contracts Agent definitions, discovery, prompts, prompt cache, and skills
agent_session_contracts Events, scheduling, sessions, SDK behavior, and workspace-reference ports
agent_interaction_contracts Permissions, questions, and hook execution
agent_long_horizon_contracts DeepResearch, DeepReview, and long-running thread-goal behavior
native_hook_execution_contracts Unix-only native process execution, timeout, and cleanup behavior

Add a contract to the nearest existing target. Do not add another top-level integration target unless it requires a genuinely different feature, platform, process, or dependency boundary. Use --lib <filter> for a focused library test, or --test <target> <module>::<filter> for a focused public contract test.

Grouped target roots stay flat: apart from module documentation, they contain only direct #[path = "..."] / mod ...; pairs, and every leaf .rs file is referenced exactly once. Isolated platform or process targets keep their test implementation in the root file. The core-boundary check enforces this shape so autotests = false cannot silently omit a new contract.

Verification

Use the focused contract form by default. Run the package-wide form only when a change crosses several runtime targets:

cargo test --locked -p bitfun-agent-runtime --test <target> <module>::<test>
cargo test --locked -p bitfun-agent-runtime

Run pnpm run check:core-boundaries only when Cargo dependencies, explicit test targets, or grouped-root layout changed. Core product assembly and product-full verification belong to Core or the consuming product guide, not to this module's default checklist.