---
domain: agent
last_rule_review_commit: 521fee23bb701ace0de1678485997f7ca9df1338
last_rule_updated_at: 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.