Agent work management
Paperclip treats an agent as a company-scoped worker with an identity, a role, a work policy, and a way to run work. The server decides when the agent may receive or start work, records each run and its lasting state, and the UI gives people a view of the roster, current activity, history, and controls.
Agent model
Agent identity and scope
An agent represents a named worker inside one company. Its profile gives people the context needed to choose it, while its work profile selects the adapter, run policy, execution environment, permissions, instructions, skills, and budget that shape its work. The agent also has a stable URL key so its detail page remains easy to reach after a name change.
The agent record is the shared contract between management, scheduling, work assignment, and execution. The server adds current spend, pause and error information, heartbeat time, and reporting-chain health so a profile shows both intended behavior and recent state. Company lists and organization views apply access and lifecycle filters before they reach a caller, and restricted readers receive a redacted view rather than sensitive configuration.
Agents can be resolved within their company by ID or by a unique normalized URL key. A URL-key lookup ignores terminated workers and reports ambiguity instead of choosing between duplicate matches.
An agent may use a local or managed execution target, a native Runner profile, or an externally hosted worker. These choices affect where Paperclip observes and controls work, but they do not remove the normal company, access, eligibility, or run rules. Built-in agents are managed workers that power Paperclip features through routines and schedules; they can be configured and paused but are not ordinary deletable workers.
References: server/…/agents.ts• L26-46 server/…/agents.ts• L217-289 server/…/agents.ts• L4021-4101 server/…/agents.ts• L4247-4278 server/…/agents.ts• L5522-5858 ui/…/AgentDetail.tsx• L803-971
Configuration editing
Agent configuration defines how a worker runs and what it may reach. The detail page separates runtime settings, secrets, permissions, instructions, skills, revisions, and advanced configuration so an operator can change one concern without losing sight of the whole agent.
The server returns redacted values and revision information. This lets a save preserve hidden secrets and reject a draft based on an old configuration. The page keeps unsaved work visible, blocks unsafe navigation, and offers save or discard actions. A change to the execution target clears related session state so later work does not reuse memory from the old target.
Environment checks apply the selected authentication model before work starts. An SSH environment that uses host authentication takes credentials from the remote machine instead of requiring an agent AI account. When host authentication is disabled, the agent must use a selected AI account or the environment test stops before execution.
Permission changes preserve protected interaction rights and keep task-assignment access aligned with the agent's effective permissions. Pending-approval agents remain configuration-frozen until approval.
Configuration changes can be reviewed and restored through revisions. Restore still passes the current access, provider, environment, and safety rules; a historical record is not an unconditional bypass of those rules.
References: server/…/agents.ts• L47-118 server/…/agents.ts• L3208-3400 server/…/agents.ts• L4280-4405 server/…/agents.ts• L5053-5132 server/…/agents.ts• L5522-5895 ui/…/AgentDetail.tsx• L388-422 ui/…/AgentDetail.tsx• L1175-1227 ui/…/AgentDetail.tsx• L1615-1787
Instruction bundles
An instruction bundle is the agent's persistent guidance. It has a root, an entry file, and optional supporting files. Paperclip can manage the files in the company's agent data area or use an external absolute directory.
The instruction view lets an operator select, read, edit, add, delete, and restore files. It protects edits with a revision or content hash and can preserve edits from an earlier run for review. Legacy inline prompt content remains readable while the agent moves to the bundle model. Saved instructions affect the next run; an active run keeps the instructions with which it started.
Managed entry-file changes use a current revision as their base. This keeps concurrent edits from silently replacing newer guidance. A saved working copy from a run can be resolved against the current revision, and restore creates a new current revision rather than changing history in place.
References: server/…/agents.ts• L5151-5214 server/…/agents.ts• L5233-5516 ui/…/AgentDetail.tsx• L1854-2355 ui/…/AgentDetail.tsx• L2613-2668
Organization hierarchy
Agents can report to other agents in the same company. This hierarchy provides an escalation path and lets the UI show managers, direct reports, and the full chain around a worker.
The server rejects self-reporting and cycles. A missing manager, a cycle, or a terminated ancestor makes the chain invalid and blocks work. A paused manager does not invalidate the worker, but the UI warns that escalation cannot reach an active manager. Terminating a manager also cancels invocations for affected descendants so the hierarchy does not leave work running under an invalid chain.
References: server/…/agents.ts• L217-253 server/…/agents.ts• L4104-4134 server/…/agents.ts• L5932-6114 ui/…/AgentDetail.tsx• L803-885 ui/…/AgentDetail.tsx• L1495-1507
Work eligibility
Assignment and invocation
Paperclip separates the right to receive work from the ability to start work. Assignable means an issue may name the agent as its assignee. Invokable means a scheduler, assignment signal, or manual request may start a run for the agent.
| Condition | Assignment | Invocation |
|---|---|---|
| Active or healthy working state | Allowed | Allowed |
| Paused | Allowed | Blocked until resumed |
| Pending approval | Blocked | Blocked |
| Terminated | Blocked | Blocked |
| Invalid reporting chain | Blocked | Blocked |
Approval moves a pending hire into the normal lifecycle. Pause, resume, clear-error, and terminate actions change what the scheduler may accept. Pausing cancels active work, while resuming requires a valid reporting chain. The detail page shows approval and reporting-chain problems before it enables normal work actions.
References: server/…/agents.ts• L5917-6114 server/…/agents.ts• L6462-6480 ui/…/AgentDetail.tsx• L803-885 ui/…/AgentDetail.tsx• L924-971
Assignment wakeups
An assignment wakeup connects a work item to the agent responsible for it. When an eligible issue receives an agent assignee, Paperclip sends a signal that can start work without waiting for the agent to poll.
The same wakeup model serves timers, manual requests, retries, and automation. A signal may start a new run, merge into active work, wait behind a live run, or be skipped when eligibility, budget, capacity, or cooldown rules block it. The recorded outcome explains why work did not start. Idempotency and source details keep repeated requests from creating confusing duplicate work.
Wakeups also preserve the responsible actor and the request context needed for the run. An exact retry uses the server-selected failed run as its source, while a fresh request can ask for a new session. This keeps retry authority and task context tied to a recorded server action instead of to caller-supplied markers.
This relationship is the entry point to issue execution, which explains how assigned issues become controlled work and how results return to issue state.
References: server/…/agents.ts• L6355-6455 server/…/agents.ts• L6495-6617 server/…/agents.ts• L7180-7189 ui/…/AgentDetail.tsx• L2997-3073
Agent self-service
An authenticated agent can read its own profile and a compact inbox of assigned, open work. The server applies the agent's access rules and returns dependency readiness and active recovery state so the worker can choose work that is ready to proceed.
Agent self-service does not grant broad operator access. Sensitive profile data and run telemetry remain subject to trust, company, and resource checks. This keeps work intake useful without making an agent's own identity endpoint a way to bypass management controls.
References: server/…/agents.ts• L4143-4257
Agent execution state
Run lifecycle
A heartbeat run is one recorded attempt to process a wakeup. It moves from queued to running when the scheduler grants capacity, then ends in a terminal state such as succeeded, failed, cancelled, interrupted, or timed out.
The scheduler checks eligibility, budget, issue readiness, and concurrency before it starts queued work. The run keeps its source, issue context, result or error, usage, session transition, and output links. This gives the server and UI one durable record for both successful work and blocked or cancelled work.
The following diagram shows how a work signal becomes visible agent activity.
flowchart LR
A[Timer, assignment, manual request, retry, or automation] --> B[Agent wakeup]
B --> C{Eligible and capacity available?}
C -- No --> D[Skipped, deferred, or cancelled]
C -- Yes --> E[Queued heartbeat run]
E --> F[Running agent execution]
F --> G[Result, error, retry, or cancellation]
G --> H[Run history and activity views]
References: server/…/agents.ts• L6422-6493 server/…/agents.ts• L7153-7168 server/…/agents.ts• L7358-7395 ui/…/AgentDetail.tsx• L2767-2906
Runtime state and sessions
Runtime state is the durable memory of an agent's execution activity. It records the last run, adapter session information, token and cost totals, task sessions, and the last error. A task session keeps context separate for separate work items.
The detail page can reset all sessions or one task session. Resetting removes continuity and error state without changing the agent's identity or assignment. Current status text, tool activity, and recent output are live run signals; they are not a replacement for the durable run record.
Native runs can pause for a runtime request that needs an authorized response. Paperclip checks that the request is still pending and that the responder has the required authority before it sends the response to the active session. A stale request therefore cannot change a later turn.
For an external worker, the runtime state describes Paperclip's side of the relationship. Paperclip can show observed progress and task links, but it does not claim complete remote usage, transcript, or process termination.
The execution environments page explains where work runs. The adapter integrations page explains how provider-specific execution connects to this state. The native runner execution page explains the native Runner path.
References: server/…/agents.ts• L4422-4472 server/…/agents.ts• L7397-7605 ui/…/AgentDetail.tsx• L526-536 ui/…/AgentDetail.tsx• L2945-3152
Live run selection
Paperclip keeps live activity distinct from history. The live-run server view returns queued and running runs by default. A caller may request a bounded amount of recent finished work for a compact card, or request distinct task representatives so repeated runs for one task do not crowd out other work.
Historical padding is explicit. Without a minimum-count request, a live-runs view contains only queued and running work, so an empty live set is not filled with finished runs by default. Dashboard selection can instead choose representatives across tasks when the view needs a broader activity summary.
Each row can include execution health, liveness, output-silence data, and redacted fields based on the reader's access. This lets dashboards show current work without counting historical runs as active work.
References: server/…/agents.ts• L7211-7327 ui/…/AgentDetail.tsx• L598-600 ui/…/AgentDetail.tsx• L1280-1421
Agent activity views
Roster and detail views
The company agent view is the roster. It exposes workers, organization relationships, status, adapter, environment, heartbeat time, and current work. The detail page is the main management and observation surface for one agent.
The overview joins identity, manager and direct reports, skills, recent tasks, weekly activity, runs, month-to-date cost, and budget use. Separate views cover instructions, runtime settings, secrets, permissions, skills, tools, channels, API keys, revisions, audit activity, costs, budgets, and runs. Built-in agents show their owning feature and routine controls instead of ordinary delete controls.
The page also keeps lifecycle state beside the agent identity. It can show pending approval, an invalid reporting chain, a paused escalation path, or a resource operation that still needs preparation or cleanup. A lifecycle refresh must not replace an operator's unsaved configuration draft.
References: server/…/agents.ts• L4021-4134 server/…/agents.ts• L4265-4420 ui/…/Agents.tsx• L1-220 ui/…/AgentDetail.tsx• L803-1227 ui/…/AgentDetail.tsx• L1423-1545
Run history and inspection
The Runs view connects each execution to its source and issue when possible. It presents status, timing, result or error, usage, cost, session changes, workspace activity, logs, events, recovery state, and provider-trace state subject to access and redaction rules.
Operators can cancel active work, resume a process-lost run, retry eligible failures, inspect a run, resolve pending runtime requests, and load the durable records behind live progress. Streamed events are a fast path; durable event and log records allow the page to recover after a reconnect or sequence gap.
The run view keeps external activity separate from local execution. Stopping an external run revokes Paperclip authority for that session, but it does not prove that the remote process stopped.
The runner evaluation and conformance page explains how Runner behavior is assessed against its required contract.
References: server/…/agents.ts• L7153-7197 server/…/agents.ts• L7339-7605 server/…/agents.ts• L7831-7903 ui/…/AgentDetail.tsx• L2767-2906 ui/…/AgentDetail.tsx• L2945-3449
Activity and membership views
The activity view records actions taken on the agent and work associated with it. Chat and work panels connect an agent to conversations, participated issues, and produced artifacts without changing the company agent record.
Personal membership controls let a person join, leave, or star an agent in their own workspace view. A saved conversation can still resolve a terminated agent so historical context remains reachable, while the normal active roster omits workers the person left or the company terminated.
References: ui/…/AgentDetail.tsx• L707-715 ui/…/AgentDetail.tsx• L811-854 ui/…/AgentDetail.tsx• L1425-1545 ui/…/AgentConversationsSidebar.tsx• L11-59 ui/…/AgentWorkPanels.tsx• L24-307
Related systems
Work management crosses eight neighboring systems:
- Issue execution covers how assigned issues become controlled work and how results return to issue state.
- Case handoffs and continuity covers how work context moves between agents and how continuity is kept across handoffs.
- Reusable workflows covers repeatable work patterns that create or coordinate agent work.
- Execution environments covers local, remote, and managed places where agent work runs.
- Agent instructions covers the guidance bundle and its editing lifecycle.
- Adapter integrations covers the provider interface that launches an agent and reports progress.
- Native runner execution covers the native Runner path used by supported execution modes.
- Runner evaluation and conformance covers how Runner behavior is assessed against its required contract.
Change checklist
When these files or sections are changed, remember to consider these:
- When agent statuses or reporting-chain rules change, update assignment eligibility, invocation eligibility, queued-run handling, roster filters, and repair warnings together.
- When hire approval rules change, keep the frozen pre-approval configuration and approval-time application consistent.
- When runtime configuration or execution-target rules change, keep validation, environment tests, model choices, SSH host-auth and AI-account selection, session reset, Runner admission, and real-run behavior aligned.
- When instruction bundle rules change, keep root recovery, entry-file selection, legacy prompt migration, preserved edits, and revision or hash checks aligned.
- When wakeup sources or context fields change, preserve the issue link and source labels used by run history, active-run cards, and assignment recovery.
- When live-run defaults, task de-duplication, or historical padding change, keep live counts, active labels, and dashboard cards aligned about which terminal runs are included.
- When run events, logs, or liveness fields change, keep stream recovery, durable cursors, run detail polling, recovery controls, and redaction aligned.
- When external Runner behavior changes, keep observed activity, Paperclip authority, provider setup, and stop semantics distinct from local execution.
- When permissions or consent rules change, keep self access, configuration access, protected profile changes, task-assignment access, and UI redaction fail-closed.
- When personal membership or chat rules change, preserve saved conversation access while keeping left and terminated agents out of the normal contact list.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Agent remains pending approval | It cannot receive or start work, and its requested work configuration stays frozen. | Approve the hire before assigning or invoking it. |
| Reporting chain is missing, cyclic, or terminated above the agent | Assignment and invocation are blocked. | Repair the chain or explicitly pause or terminate the affected subtree. |
| Agent is paused | New invocation is blocked and active work is cancelled. | Resume it after checking its purpose and budget. |
| No execution capacity is available | A wakeup waits, merges, or is skipped instead of starting competing work. | Inspect the live run and concurrency state before forcing another request. |
| Required environment, connection, model, or credential is missing | Setup or dispatch stops as a clear configuration blocker. | Bind a valid value at the scope named by the blocker. |
| SSH host authentication is disabled without an agent AI account | Environment testing stops before execution can verify the selected setup. | Select an AI account or enable authentication configured on the remote machine. |
| Execution target changes while sessions remain active | Old session state can describe the wrong target. | Use the managed update path so affected sessions and adapter state are reset. |
| Configuration or instruction draft is based on an old revision or hash | The save is rejected rather than overwriting newer work. | Reload the current record, review the change, and save again. |
| Instruction root or entry file is missing | The next run may receive no resolved guidance from the configured bundle. | Repair the root or entry file, or select a valid managed bundle. |
| Live event delivery loses a connection or sequence | The run view can miss recent output until durable records recover it. | Retry or load more events and treat the stream as a fast path. |
| External activity is stopped from Paperclip | Paperclip authority ends, but the remote worker may continue. | Inspect the external provider and do not treat the Paperclip run as remote process control. |
| A permission update changes visible rights without updating task-assignment access | The agent's displayed controls and its ability to assign work can disagree. | Apply permission and access changes through the managed agent update path. |
| A runtime request is stale or already resolved | The runner rejects the response and the UI must refresh its pending request. | Re-read the current request and resolve it only while the run is active. |
Key files
| File | Why to read it |
|---|---|
| packages/…/agent.ts | Defines the agent profile, configuration, permissions, revisions, and detail contracts shared by server and UI. |
| packages/…/agent-eligibility.ts | Defines assignability, invocability, and reporting-chain health. |
| packages/…/heartbeat.ts | Defines wakeup, run, runtime-state, session, and activity data. |
| server/…/agents.ts | Shows agent lookup, hierarchy, lifecycle, revisions, permissions, and management behavior. |
| server/…/heartbeat.ts | Shows how wakeups become queued runs and how eligibility and capacity are applied. |
| server/…/agent-instructions.ts | Shows how instruction bundles are resolved and migrated. |
| server/…/agents.ts | Defines the server surface for agent management, assignment, runtime state, instructions, runs, live activity, lifecycle controls, and environment validation. |
| ui/…/Agents.tsx | Shows the company roster, organization view, filters, and live-run indicators. |
| ui/…/AgentDetail.tsx | Shows the agent overview, configuration and instruction surfaces, lifecycle state, run history, run inspection, membership, and navigation guards. |
| ui/…/AgentLifecycleStatus.tsx | Shows how pending lifecycle phases and retry actions appear beside editable agent data. |
| ui/…/ActiveAgentsPanel.tsx | Shows the compact dashboard presentation for current and recent agent work. |
| ui/…/AgentConversationsSidebar.tsx | Shows how active agents, saved conversations, and membership visibility form the chat roster. |
| ui/…/AgentWorkPanels.tsx | Shows the agent-scoped task and artifact activity beside chat. |