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

domain	last_rule_review_commit	last_rule_updated_at
agent	4695bcbc60	2026-07-30

agent

Purpose / Responsibility

Reserve the standalone, device-local iop-agent application boundary. The current repository has no concrete apps/agent/ implementation; shared Agent Runtime foundations remain in platform-common until a host application is added.

Included Paths

• None — the current tree has no standalone agent application path

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

• No concrete application component yet — implemented runtime configuration, state, policy, provider, task, and workspace foundations are shared packages owned by platform-common

Patterns to Preserve

• When the standalone host is introduced, 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.