AGENTS.md

中文 | English

Core Agent Guide

Scope

This file applies to src/crates/assembly/core. Use the top-level AGENTS.md for repository-wide rules and the nearest narrower guide when one exists.

Role

openbitfun-core is the shared product runtime facade. It still owns compatibility paths and the product-full assembly boundary, but new decomposition work should prefer the owner crates described in docs/architecture/product-architecture.md and docs/architecture/agent-runtime-services-design.md.

Main areas:

• src/agentic/: agents, prompts, tools, sessions, execution, persistence
• src/service/: config, filesystem, terminal, git, MCP, remote connect, AI memory
• src/infrastructure/: AI clients, app paths, event system, storage, debug log server
• src/product_runtime/: Core Agent Runtime compatibility adapters and runtime service provider wiring

Agent runtime mental model:

SessionManager -> Session -> DialogTurn -> ModelRound

Boundary Rules

• Keep shared core platform-agnostic. Avoid host-specific APIs such as tauri::AppHandle; use shared abstractions such as openbitfun_events::EventEmitter.
• Desktop-only host adapters belong in src/apps/desktop, then flow through typed capability interfaces; use the production transport adapter when event delivery is needed.
• Do not add new cross-layer references from service to agentic without a narrow port/interface boundary.
• Do not move platform-specific logic, build-script behavior, product capability selection, or provider-specific AI serialization into shared core.
• When moving ownership out of core, preserve old import paths with facade or re-export code until downstream call sites are intentionally migrated.

Decomposition Rules

• Treat openbitfun-core as a compatibility facade plus full product assembly point, not as the preferred home for new stable contracts.
• Put stable DTOs, facts, ports, and pure decisions in the matching owner crate where a clear owner exists. Keep concrete managers, IO, platform adapters, and product execution in core until a reviewed port/adapter/service design and behavior equivalence tests exist.
• Tool changes must preserve expanded/collapsed exposure, prompt-visible manifests, GetToolSpec, permission behavior, ToolUseContext semantics, and desktop/MCP/ACP catalog behavior.
• Workspace file tools select IO through ToolUseContext::file_system_for_path. Read/Write/Edit/Delete/LS must not add per-tool SSH branches. Shared algorithms belong in tool-execution; concrete filesystem/stream handling belongs in Services providers. Session artifacts stay host-local. A missing remote provider must fail without falling back to the controller filesystem.
• Snapshot preparation/completion may fail independently of the file tool. Never replay a mutation to repair tracking. A recorded operation is not proof of complete Session coverage; remote Session Undo retains its coverage gate.
• Runtime-owner migrations must keep concrete lifecycle, IO, event delivery, permission orchestration, and remote/platform implementations in core until the target owner has a reviewed port/adapter/service design plus behavior-equivalence tests.
• Product-domain changes may move pure product-domain plans with equivalence coverage, but filesystem writes, worker/host side effects, Git/AI concrete calls, marker IO, and path-manager integration stay in core unless a reviewed owner design says otherwise.
• plugin_source may inject product-owned paths and keep compatibility exports; concrete managed-package discovery and trust persistence stay in services-integrations, while ecosystem parsing and PluginRuntimeClient behavior remain in their adapter and execution owners.
• plugin_runtime, external_sources, and instruction_sources are the reviewed owner-feature composition files allowed to select ecosystem adapters for their respective capability contracts. Product surfaces consume product-level views and must not import adapter or raw plugin runtime client types.
• The managed OpenCode Plugin Host is an adapter/service resource. Core may assemble its launch, retain opaque logical instance and PTY scope bindings, and bridge matched requests to existing product owners. OpenCode route matching, wire DTOs, serialization/error mapping, and physical process-tree supervision stay in opencode-plugin-host and services-core; Core route projections must not invent provider connectivity, VCS, permission, or other owner state.
• External-source Desktop, TUI, Peer, and Server surfaces share the versioned product-domain control DTO and closed generic actions. Capability-specific approvals and conflict choices remain typed owner operations; do not add a second surface-specific lifecycle model or arbitrary control payload.
• Remote/service changes must keep external protocol lifecycle, workspace projection, scheduler/session restore, terminal pre-warm, and product execution boundaries explicit.
• Feature work must keep product-full as the compatibility product assembly boundary unless a separate product matrix review changes default capability selection.
• agent-runtime owns the Core Agent lifecycle baseline, native Hook runtime, basic filesystem/process tools, and Agent-control tools, including scheduled job execution. Concrete network and product capabilities stay explicitly selectable: model-catalog, mcp-runtime, remote-connect, workspace-search, browser-control, web-tools, deep-research, and script-tool-runtime. model-catalog composes runtime services for catalog update events; mcp-runtime layers the Core MCP tool bridge on the Agent lifecycle; and remote-connect layers its phone relay on the Agent lifecycle and model catalog. None of these relationships may be hidden in the agent-runtime baseline. scheduled-jobs, document-read, and subscription-auth are additive dependency/source modifiers, not standalone runtime profiles. The latter two use Cargo weak dependency forwarding so they refine an already selected tool or adapter owner without activating that owner by themselves. Product-owned managed worktree lifecycle is available only when the Agent lifecycle and Git service owners are both selected; it is not a tool-pack owner. Function Agent adapters use the independent function-agents owner; MiniApp domain/runtime/market dependencies belong only to tools-miniapp. Tool implementation groups use the matching tools-* owner feature. Product Assembly supplies the exact ProductToolPlan; Core materialization validates that requested owners were compiled and must not infer product capability from Cargo's feature union. The Agent Runtime baseline plan is exactly Basic plus AgentControl, not a hidden delivery profile. external-sources adds third-party discovery/import adapters, plugin-runtime adds executable plugin-client wiring, opencode-plugin-host composes the managed Host and its reviewed route owners. None may enable product-full.
• CLI/ACP closure checks keep Cargo resolver-v2 normal and host (build/proc-macro) feature contexts separate, while treating all target-specific declarations within each context as one reviewed architecture boundary. Split a package/module owner when platforms genuinely differ; do not hide an unreviewed Core capability behind mutually exclusive Cargo cfg branches.
• Keep the light compatibility features independently compilable. Local service profiles are dispatch-store, terminal, workspace-runtime, and workspace-watch; remote-workspace adds only the remote workspace facade, while ssh-remote adds concrete SSH transport. Integration facades announcement, file-watch, git, and review-platform remain independent, with service-integrations only their compatibility aggregate. None of these narrow features may enable product-full directly or transitively.
• product-full must explicitly compose every capability it consumes, including product-only services-core features such as permission, session-git, and runtime-ownership, every concrete service owner, and every tools-* group. Do not put those features on the dependency declaration, because Cargo feature union would force them into every core consumer.
• Core's default feature set is empty. product-full is an explicit compatibility assembly selected by real product entrypoints, never the library's implicit default. Capability-local utility dependencies remain optional and are activated by their owner features; in particular, base64, futures, regex, tokio-util, and openbitfun-agent-tools belong to the Agent Runtime, local-storage, or dispatch-store closures that use them. Core's direct feature-free Tokio edge keeps only filesystem and synchronization support required by config and app-path state; the selected Services Core json-io owner separately carries the runtime/time capabilities required for bounded atomic JSON writes.
• Backend Fluent bundles and mutable translation state are owned by i18n-runtime; locale ids, aliases, fallback facts, metadata, and model-facing language copy remain feature-free contracts. Hosts that call I18nService must select i18n-runtime explicitly.
• Reusable diagnostic redaction and local Diff implementations remain compatibility facades under the exact diagnostics and diff features. Agent Runtime selects openbitfun-services-core/workspace-text-runtime for bounded asynchronous workspace reads; synchronous path normalization stays available to contract-only consumers without Tokio.
• Platform transport emitters are host adapters. Desktop imports openbitfun_transport::TransportEmitter directly; Core exposes only the stable openbitfun_events::EventEmitter contract and must not re-export a host adapter.
• Keep cargo check -p openbitfun-core --no-default-features viable. Gate product-only modules at their owner feature; if a light facade operation cannot safely complete without a product owner, fail closed and preserve any durable recovery state instead of enabling product-full implicitly.

Owner References

Use these files for ownership details instead of expanding this guide:

• docs/architecture/product-architecture.md
• docs/architecture/agent-runtime-services-design.md
• src/crates/execution/agent-runtime/AGENTS.md
• src/crates/execution/tool-contracts/AGENTS.md
• src/crates/execution/agent-workflows/AGENTS.md
• src/crates/contracts/product-domains/AGENTS.md
• src/crates/contracts/runtime-ports/ and src/crates/execution/runtime-services/ source docs
• src/crates/services/services-core/AGENTS.md
• src/crates/services/services-integrations/AGENTS.md
• src/crates/execution/tool-provider-groups/AGENTS.md

Narrower local guides already exist for some subtrees:

• src/crates/adapters/ai-adapters/AGENTS.md
• src/crates/assembly/core/src/agentic/execution/AGENTS.md
• src/crates/assembly/core/src/agentic/deep_review/AGENTS.md

Verification

For config-backed product-control option defaults, typed binding, and persisted readback:

cargo test -p openbitfun-core --no-default-features --features agent-runtime,git --lib every_catalog_config_option

AI client construction and subscription credential compatibility:

cargo test -p openbitfun-core --no-default-features --features ai-adapter-runtime,subscription-auth --lib infrastructure::ai::client_factory::tests

This guide owns Core verification. Select one command pattern that matches the change; do not run every feature variant:

cargo check -p openbitfun-core --no-default-features
cargo check -p openbitfun-core --no-default-features --features <touched-owner-feature>
cargo test -p openbitfun-core --no-default-features --features <minimal-features> --lib <module>::<test>

Use the first command when the feature-free facade changed, the second when one feature boundary changed, and the third for behavior. Run pnpm run check:core-boundaries only for Cargo features, dependency direction, or test-target layout. Workspace checks and product-wide tests are CI-backed and are not the default Core precheck. For documentation-only changes, run git diff --check.

For assistant discovery, opened-state persistence, and reopening by workspace ID: cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib service::workspace::service::tests::assistant_.

For local/SSH workspace identity collisions, SSH connection rebinding, committed session storage, legacy path compatibility, and queue admission, use the matching owner filter:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,remote-workspace --lib service::workspace::
cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,remote-workspace --lib agentic::session::
cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,remote-workspace --lib agentic::coordination::

The coordination filter includes the scheduler admission tests. These catalog and storage fixtures do not require or validate a live SSH connection. CI also runs them under product-full. PathManager::with_user_root_for_tests derives product home from the user root's parent, so a fixture that relocates managed paths must place its user root below the directory it means to exercise.

For disk-backed history paging and legacy sessions without a catalog: cargo test --locked -p openbitfun-core --no-default-features --features remote-connect,git --lib history_page_. Also run the staged_revert_catalog_projection and load_relay_session_turns_ filters for the same target when changing visibility. Paging must not parse unrelated turn bodies or rewrite history. To compare real-file first-page work against full materialization locally, use the same target with history_page_benchmark -- --ignored --nocapture; it checks content equivalence and reports timings without asserting a machine-dependent latency in CI.

For host-stream history reads and abandoned execution after a runtime restart: cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib load_relay_session_turns_. The observer must preserve terminal history and another process's writer lease; absence from one coordinator's memory alone never proves execution stopped.

For built-in provider overlay, trusted endpoint validation, and reasoning catalog changes:

cargo test -p openbitfun-core --no-default-features --features ai-adapter-runtime --lib infrastructure::ai::

Configuration persistence, account settings import, backup restore, legacy field/deletion compatibility, local-change notifications, and save/reload/model concurrency regressions have feature-free fixtures:

cargo test -p openbitfun-core --no-default-features --lib service::config::

The account sync adapter requires remote-connect, which also covers Agent-profile canonicalization in the focused configuration suite:

cargo test -p openbitfun-core --no-default-features --features remote-connect --lib service::config::
cargo test -p openbitfun-core --no-default-features --features remote-connect --lib service::remote_connect::settings_sync::tests
cargo test --locked -p openbitfun-core --no-default-features --features remote-connect --lib service::remote_connect::permission_publication::tests
cargo test --locked -p openbitfun-core --no-default-features --features remote-connect --lib service_agent_runtime::tests::local_workspace_marker_is_not_remote_routing_authority
cargo test --locked -p openbitfun-core --no-default-features --features remote-connect --lib service_agent_runtime::tests::remote_workspace_catalog_tracks_opened_rows_and_assistant_identity

Focused workspace-IO and snapshot regression entry points (use the matching filter rather than a product-wide build):

cargo test -p openbitfun-core --no-default-features --features agent-runtime,git,document-read --lib file_read_tool::tests
cargo test -p openbitfun-core --no-default-features --features agent-runtime,git --lib file_write_tool::tests
cargo test -p openbitfun-core --no-default-features --features agent-runtime,git --lib file_edit_tool::tests
cargo test -p openbitfun-core --no-default-features --features agent-runtime,git --lib classified_edit
cargo test -p openbitfun-core --no-default-features --features agent-runtime,git --lib delete_file_tool::tests
cargo test -p openbitfun-core --no-default-features --features agent-runtime,remote-workspace,git --lib service::snapshot::

MCP chat discovery and deferred-tool manifest contracts (Git is needed by the existing Agent tool test assembly):

cargo test --locked -p openbitfun-core --no-default-features --features mcp-runtime,git --lib agentic::tools::product_runtime::

User Agent directory watching and registry regressions (omit file-watch to exercise query-time discovery fallback):

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,file-watch --lib agentic::agents::registry::

Skill discovery, installation provenance, and local/remote registry regressions:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib agentic::tools::implementations::skills::

SessionControl workspace selection, remote routing, and session-targeted actions:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib session_control_tool::tests
cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib list_workspaces

MiniApp Agent appdata workspace registration and pre-ID session compatibility:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,tools-miniapp --lib miniapp::agent_workspace::tests

Workspace history upgrade compatibility and MiniApp record preservation:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib legacy_miniapp_history

Skill hook activation, session cleanup, and tool preflight/permission ordering:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib native_hooks
cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib agentic::tools::pipeline::tool_pipeline::tests

For configured OpenCode discovery and explicit skill loading, include their owner feature and tool tests:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,external-sources --lib agentic::tools::implementations::skill

Detached Dispatch controller, target query compatibility, and managed-baseline checks:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,dispatch-store,ssh-remote,git --lib service::dispatch::

IM bot reply routing, account-device observation, and interaction delivery:

cargo test --locked -p openbitfun-core --no-default-features --features remote-connect --lib service::remote_connect::bot::
cargo test --locked -p openbitfun-core --no-default-features --features remote-connect --lib service::remote_connect::bot::weixin::tests

Pages account publication and tool gates (including remote directory rejection):

cargo test -p openbitfun-core --no-default-features --features remote-connect,tools-pages,git,ssh-remote --lib page_

tools-pages selects only the Pages tool group. Account host wiring additionally requires remote-connect; CLI and Desktop select both explicitly. Pages does not select MiniApp runtime or market dependencies.

Scheduled-job workspace identity and the temporary 1.0.0 target upgrade boundary:

cargo test -p openbitfun-core --no-default-features --features agent-runtime,scheduled-jobs,git --lib service::cron::service::tests
cargo test -p openbitfun-core --no-default-features --features agent-runtime,scheduled-jobs,git --lib cron_100_target_upgrades_once

For workspace-ID fork ownership and pre-ID session-directory upgrade coverage:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git --lib session_fork_

For remote search ID binding without a live SSH connection:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,ssh-remote --lib service::search::remote::identity_tests

For host-owned user queue admission, cancellation, steering receipts and client disconnects:

cargo test --locked -p openbitfun-core --no-default-features --features remote-connect,git --lib host_queue_

For Computer Use control host admission, cancellation leases, control entrypoints, permission projection and provider-neutral tool contracts:

cargo test -p openbitfun-core --no-default-features --features agent-runtime,git,tools-computer-use --lib computer_use_tool::tests

These mock-host tests do not validate native capture, background input or remote GUI behavior; native fixtures remain owned by the Desktop Computer Use guide.

For plain-prompt goal activation and remote goal storage routing:

cargo test --locked -p openbitfun-core --no-default-features --features agent-runtime,git,remote-workspace --lib thread_goal_