Background Jobs
Background jobs are gateway-owned work records for activity that can outlive a single foreground reply. They let Anyy keep tracking work while the user keeps using the session.
The resident gateway owns job state, log access, outbox delivery, and completion notifications. A job is always scoped to a session; listing or controlling it requires the matching session scope.
Job Types
Anyy has three user-visible background-job paths:
| Type | How it starts | Typical use |
|---|---|---|
| Background child agent | background_job or /background <prompt> | Long-running agentic work that should notify on completion. |
| Managed process job | bash with background=true | Long shell commands, builds, tests, downloads, or servers. |
| Workflow job | Runtime workflow execution | Parent jobs that may show child job records. |
Cron can also create bridge records for scheduled runs. Those are runtime records used for delivery and observability, not a separate user-facing automation system.
Background Child Agents
For substantial async agentic work, Anyy uses the background_job tool in the
subagents toolset. It starts a child session, immediately returns a handle, and
marks the job to notify when the child completes or fails.
The accepted payload includes:
| Field | Meaning |
|---|---|
background_job_id | Handle used by background job views and RPC. |
subagent_run_id | Child-agent run id. |
child_session_id | Child session id. |
accepted_message | User-facing acceptance summary. |
In the TUI, use:
/background inspect the failing docs build and summarize what changed
/agents
/agents lists child runs for the current session.
Managed Process Jobs
For long-running shell work, the model-visible bash tool can start a managed
background process with background=true. The process tool then manages that job.
Normal process actions are:
| Action | Meaning |
|---|---|
list | List managed process jobs for the current session. |
poll | Read status for one managed job. |
log | Read job output. |
wait | Wait for completion with a timeout. |
kill | Stop the process with TERM. |
write, submit, close | Send stdin or control input to an interactive managed process. |
process is not a general host process inspector. It manages jobs created by Anyy's managed shell path.
Killing a process or sending input can change runtime state, so those actions follow the ChangePlan and approval policy for runtime-high process operations.
TUI And RPC Access
The TUI exposes current-session job views:
/jobs
/job <id>
/job kill <id>
The gateway RPC methods are:
| RPC | Purpose |
|---|---|
jobs.list | List background jobs for a session. |
jobs.status | Inspect one job; can include logs for process jobs. |
jobs.logs | Read process-job logs. |
jobs.wait | Wait for a process job. |
jobs.kill | Stop a process job. |
jobs.clear | Clear a process-job record after it is no longer needed. |
jobs.logs, jobs.wait, jobs.kill, and jobs.clear currently apply to process
jobs. Non-process jobs are inspected through jobs.status; workflow jobs may return
child job information.
Delivery And Notifications
Background child agents and cron bridge jobs can publish completion notifications
through the gateway event bus and channel delivery system. The event metadata uses
source: background_job and includes the background_job_id.
Delivery still follows the channel binding and outbox rules documented for messaging. If a channel is disconnected, completion can remain in outbox state until delivery is possible.
Troubleshooting
If a job is missing from /jobs, check that you are in the same session that started
it. Job control is session-scoped.
If a process log is unavailable, confirm the job is a managed process job. Child agent and workflow jobs are status records, not shell log streams.
If a background child is not useful, stop it with /job kill <id> for process jobs
or subagent_cancel / subagents.kill for child-agent runs.