Tasks

Every time Sophon does real work — a chat message, a workflow run, a cron trigger, a discussion, a background agent — it shows up in the Tasks ledger. Tasks give you one place to watch what's running, cancel what's stuck, and drill into what happened.

What counts as a task

A task is any unit of agent work the Gateway tracks:

• Chat messages being processed by the orchestration pipeline
• Background agent tasks spawned by chat (the default since chat is fire-and-forget)
• Workflow runs (trigger → DAG execution → completion)
• Cron job executions
• Discussion runs (each round / turn is a nested child task)
• Manual sophon tasks run invocations

Tasks have a status: Queued, Running, Completed, Failed, Cancelled.

The Tasks page

Open Tasks in the Dashboard.

Active tab — tasks currently running. Updates live via SignalR. Columns:

• Task ID
• Session (if chat-originated)
• Agent
• User (in multi-tenant)
• Description (first 100 chars of the originating message, workflow name, etc.)
• Started
• Elapsed
• Status chip

Click a row → detail view with live log, plan (if one was generated), tool calls with inputs/outputs, and token usage.

History tab — completed / failed / cancelled tasks. Filterable by status, agent, date range, and free-text search. Same detail view on click.

Cancel button is visible on running tasks — clicking it sends a cooperative cancellation. The agent observes the token at its next cancellation point and stops cleanly. In-flight tool calls are allowed to finish (so you don't leave a half-sent email); queued tool calls are skipped.

Nested tasks

Some tasks spawn children. The ledger preserves the parent-child relationship:

• A discussion run is a parent; each turn and the judge evaluation are children.
• A workflow with a sub-workflow node is a parent; the sub-workflow run is a child.
• A multi-agent chat where one agent calls session.spawn is a parent; the child session is a separate child task.

In the detail view, children are shown inline with their own status and elapsed time. You can cancel a parent to cancel all its descendants.

Live status

The Gateway emits SignalR events throughout a task's lifecycle:

• TaskQueued — accepted into the queue
• TaskStarted — picked up by a worker
• AgentStatus — checkpoint updates (every ~10 tool iterations)
• StreamChunk — token-by-token streaming if enabled
• TaskCompleted — final response ready
• TaskFailed — error with message

The Dashboard, Mobile app, and any custom SignalR client can subscribe — the Mobile app's home-feed Active tasks card is built on this.

Cancellation

Two paths:

sophon tasks cancel <id>

Or click Cancel in the Dashboard. The cancellation:

1. Sets the task's CancellationTokenSource.
2. Current LLM call finishes (no way to interrupt an in-flight HTTP request).
3. When the LLM returns, the pipeline observes the token and short-circuits.
4. Any queued tool calls are skipped.
5. In-flight tool calls finish naturally — this is deliberate. A gmail.send mid-send will complete rather than leave a partial email.
6. Task transitions to Cancelled.

Background agent tasks also have a wall-clock timeout (MaxExecutionTime, default 2 hours). If a task runs past that, it's force-cancelled.

Crash recovery

If the Gateway crashes while tasks are in flight, the BackgroundAgentService recovers on startup:

• Queries for tasks stuck in Running status.
• Marks each one Failed with message: "Server restarted during execution".
• Tasks in Queued status stay queued — they'll pick up when the worker starts.

No data is lost; partial responses are preserved in the task log.

CLI

sophon tasks active             # currently running
sophon tasks recent              # last N completed
sophon tasks watch               # streams TaskStarted / Completed / Failed events
sophon tasks cancel <id>         # cancel a running task
sophon tasks describe <id>       # full detail including plan + tool calls

Insights into task history

The Insights engine aggregates task history — see Insights. Metrics include:

• Tasks per day / week / month
• Success vs failure rate
• Average duration by agent
• Top tools by invocation count
• Token usage by provider

This feeds the mobile Home feed and the Dashboard summary.

Limits

• Active tasks (Personal tier): capacity 100 in-memory queue. Over capacity blocks new submissions with HTTP 429.
• MaxConcurrentTasks (default 3) — concurrent running tasks per Gateway instance.
• MaxExecutionTime (default 2h) — wall-clock per task.
• Task history retention: 30 days by default (configurable via AuditRetention setting on Enterprise).

Where to go next

• Orchestration Pipeline — what runs inside each chat task
• Workflows — workflow runs are tasks
• Cron & Scheduled Jobs — cron triggers become tasks
• Insights — aggregated task analytics