iop/agent-ops/rules/project/domain/agent/rules.md

domain	last_rule_review_commit	last_rule_updated_at
agent	521fee23bb	2026-07-30

agent

Purpose / Responsibility

Own the standalone, device-local iop-agent application boundary. This domain composes shared Agent Runtime capabilities into one daemon lifecycle for the current OS user while keeping provider execution and Agent Task workflow semantics in their shared packages.

Included Paths

• apps/agent/ — standalone application lifecycle, dependency composition, commands, and host-local adapters

Excluded Paths

• packages/go/agenttask/ — shared AgentTaskManager state transitions and orchestration
• packages/go/agentruntime/ and packages/go/agentprovider/ — shared provider execution, session, stream, status, and failure behavior
• packages/go/agentconfig/, packages/go/agentstate/, and packages/go/agentworkspace/ — shared configuration, durable state, and workspace isolation contracts
• apps/node/ — Edge-connected Node host and protobuf translation boundary
• apps/edge/, apps/control-plane/, and apps/client/ — distributed control and client application responsibilities

Major Components

• apps/agent/ — application root for the standalone daemon; application components are added behind host-owned lifecycle interfaces

Patterns to Preserve

• Keep daemon lifecycle and dependency composition application-owned under apps/agent/.
• Consume packages/go/agenttask.AgentTaskManager and other shared runtime contracts through narrow application ports.
• Start application components in declared dependency order, roll back partial startup deterministically, and stop them in reverse order.
• Keep construction side-effect free; process, socket, provider, and watcher activity begins only through explicit lifecycle methods.
• Keep repo-global configuration read-only. Device paths, checkpoints, leases, and client process state belong to user-local storage.
• Treat local control as a same-OS-user boundary. Concrete socket authorization and protocol behavior remain subject to the matching inner contract.
• Add focused application tests for lifecycle ordering, cancellation, rollback, idempotent shutdown, and error identity.

Boundaries with Other Domains

• platform-common: the agent application consumes shared configuration, state, workspace, provider, and AgentTaskManager packages without moving application lifecycle policy into those packages.
• node: both hosts may consume the same shared runtime, but apps/agent/ does not import Node internals or duplicate the Edge-Node transport boundary.
• testing: changes to bootstrap, commands, process ownership, sockets, or other user execution paths require the testing domain's execution-pipeline verification.
• client: Flutter and Unity processes are clients of the standalone daemon; they do not own daemon lifecycle or shared runtime decisions.

Prohibitions

• Do not copy or reimplement agenttask.Manager, provider selection, retry/failover, review, integration, session, stream, quota, or failure algorithms under apps/agent/.
• Do not import apps/node/internal/** or reuse Node protobuf transport as the standalone host boundary.
• Do not start providers, local-control sockets, project-log writers, or client subprocesses during dependency construction.
• Do not store credentials, device-local paths, checkpoints, leases, or client process records in repo-global configuration or project task artifacts.
• Do not let a client process own, stop, or replace the standalone daemon.
• Do not add Edge, Control Plane, remote terminal, or UI implementation responsibilities to this domain.