Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs/content/docs/(core)/architecture.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -113,7 +113,7 @@ This split keeps high-volume memory writes off the control bus so channel contro

### Retriggering

When a branch or worker completes, the channel doesn't poll for results. The completion event **retriggers** the channel -- it runs another LLM turn with the result injected into its history. This keeps the channel reactive without polling loops.
When a branch or worker completes, the result destination doesn't poll. The completion event **retriggers** the requesting channel, which runs another LLM turn with the result injected into its history. An interactive worker can outlive its origin channel and return later operations to a different same-agent requester.

Retrigger events are debounced. If multiple branches complete within a short window, the channel batches them into a single turn. A retrigger limit (default: 3 per turn) prevents infinite cascades where a branch result triggers a new branch that triggers another retrigger.

Expand All @@ -132,7 +132,7 @@ Every turn, the channel receives a live snapshot of all active processes:
- **[search]** completed 30s ago — "Found 3 relevant files for the query."
```

Workers set their own status via the `set_status` tool. Short branches (< 3 seconds) are invisible in the status block to avoid noise. The status block is injected into the system prompt, giving the LLM awareness of concurrent activity.
Workers set their own status via the `set_status` tool. Their live state comes from the agent worker registry and is projected into each channel's status block. The status block presents activity but does not own worker controls. Short branches (< 3 seconds) are invisible to avoid noise.

## Data Layer

Expand Down
12 changes: 9 additions & 3 deletions docs/content/docs/(features)/autonomy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,8 @@ Autonomy gives an agent a durable operating model between conversations. Goals p

The autonomy channel is separate from a user-facing conversation. On wake, it receives the agent identity, active goals, task state, queued wake events, recent activity, and recent run summaries. It records a durable outcome before the run settles.

Worker liveness comes from the agent registry. Autonomy can route retained workers that originated in another channel, and each routed operation is tracked independently so an older result cannot settle the current run. Durable worker rows without live controls are shown as unavailable rather than actionable work.

## Authority Levels

Each agent has an autonomy level:
Expand All @@ -22,6 +24,12 @@ Each agent has an autonomy level:

The instance can apply a ceiling that limits every agent regardless of its individual setting.

## Commands

`/autonomy` reports the agent's configured level and the effective level after the instance ceiling is applied. `/autonomy-off` remembers the current non-off level and prevents new heartbeats, wake events, and epochs from being admitted. Work already active in the current epoch is allowed to settle. `/autonomy-on` restores the remembered level, or starts at `observe` when the agent has never been enabled. Pass a level to select it explicitly, such as `/autonomy-on act` (Telegram also accepts `/autonomy_on act`).

Changing the configured level does not raise the instance ceiling. Restoring `act` under a `suggest` ceiling leaves the configured level at `act` and reports `suggest` as the effective level. The status command is available to everyone; enabling and disabling autonomy require authority in the current binding.

## Goals and Tasks

Goals are standing direction. They remain active until an operator closes them. Tasks are the concrete units of work linked to those goals.
Expand Down Expand Up @@ -64,13 +72,11 @@ level = "off"
interval_secs = 1800
max_turns = 20
max_tasks_per_run = 2
timeout_secs = 600
warn_secs = 480
run_history_count = 5
claim_unowned = true
```

`interval_secs` must be at least 60 seconds. `timeout_secs` must not exceed the interval. `active_hours`, when configured, uses the agent's cron timezone.
`interval_secs` must be at least 60 seconds. `active_hours`, when configured, uses the agent's cron timezone.

## Related Documentation

Expand Down
5 changes: 4 additions & 1 deletion docs/content/docs/(features)/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -24,12 +24,15 @@ Spacebot handles built-in commands before normal LLM processing. The command set
| `/sethome` | Authority | Set the current chat as the agent's home channel. |
| `/pause [reason]` | Authority | Stop new work from starting. |
| `/pause off` | Authority | Resume new work. |
| `/autonomy` | Everyone | Show the configured level, effective level, ceiling, and current epoch state. |
| `/autonomy-on [observe\|suggest\|act]` | Authority | Enable autonomy at an explicit level, or restore the last level when omitted. |
| `/autonomy-off` | Authority | Stop new autonomy work while the current epoch settles. |

Commands that request task information are sent through the agent after classification. Control commands are applied atomically and do not need an LLM turn.

## Authority

Authority is configured per binding or adapter. Binding-level authority lists take precedence over adapter defaults. Everyone can use conversational and read-only commands. Only authority members can alter response mode, pause state, or the home channel.
Authority is configured per binding or adapter. Binding-level authority lists take precedence over adapter defaults. Everyone can use conversational and read-only commands. Only authority members can alter response mode, pause state, autonomy, or the home channel.

Run `/whoami` before using a control command to see the access available in the current chat.

Expand Down
8 changes: 5 additions & 3 deletions docs/content/docs/(features)/opencode.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -127,6 +127,8 @@ route: worker_id=abc, message="now add the database layer"

The OpenCode session accumulates context across follow-ups, so subsequent messages benefit from everything the agent learned during earlier work.

The session is registered to the agent rather than held by its origin channel. A follow-up from another channel uses the same OpenCode session and returns its result to that requester. Retained idle sessions reconnect directly during startup, so Spacebot does not need to recreate the origin channel to make them routable.

## Model Override

You can override the model used by OpenCode workers:
Expand Down Expand Up @@ -169,9 +171,9 @@ webfetch = "allow"
│ ProcessEvent::WorkerComplete │ (bash, edit, read, etc.)
↓ ↓
┌─────────────┐ ┌──────────────────┐
│ Channel │ │ Working Dir │
│ (status │ │ /code/myapp │
│ block) │ └──────────────────┘
│ Agent worker │ │ Working Dir │
│ registry │ │ /code/myapp │
│ │ └──────────────────┘
└─────────────┘
```

Expand Down
6 changes: 6 additions & 0 deletions docs/content/docs/(features)/workers.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -22,12 +22,18 @@ This preserves the user intent behind delegated work without turning the worker

Workers can be one-shot or interactive. Interactive workers retain their own working history and accept channel follow-up through `route`.

Workers belong to the agent that spawned them. The origin channel remains visible as provenance, but it does not own the task handle, cancellation, or interactive input path. Another channel for the same agent can route a follow-up to an idle worker, and that operation's result returns to the requesting channel.

## Lifecycle

Workers report progress through `set_status` and must signal a terminal outcome. Their lifecycle converges on one durable terminal record, which drives task settlement, channel retriggers, and live process displays.

The worker's own wall-clock timeout bounds a run. Cancellation and completion use the same terminal-state path so a late completion cannot overwrite a cancellation or failure.

Live controls sit in one agent-scoped registry. Runtime registration IDs fence delayed status, result, and cleanup callbacks, while operation IDs prevent an earlier interactive result from settling a later follow-up. Durable worker rows without live controls appear unavailable rather than running.

Stopping an origin channel leaves its workers reachable. After restart, retained idle built-in and OpenCode workers reconnect directly to the agent registry with their conversation-level worker settings. Running work still follows the configured interrupted-worker recovery policy.

## Task Execution

Tasks can declare an execution plan:
Expand Down
6 changes: 6 additions & 0 deletions docs/content/docs/(messaging)/messaging.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,12 @@ You can connect multiple platforms at the same time. An agent on Discord and Sla

For Email specifically, Spacebot treats inbound mail as intake-first by default: triage, memory capture for meaningful non-spam messages, and escalation to other channels for urgent items. Inbound email channels do not auto-reply. When the Email adapter is configured, intentional outbound email can still be initiated from other channels using an explicit target such as `email:alice@example.com`.

## Delivery

Replies, questions, and files count as delivered only after the messaging adapter confirms the send. Unsupported payloads return an error instead of reporting a successful delivery. For example, Twitch and Webchat cannot accept file attachments from `send_file`.

When background work finishes, the channel retries a failed result relay once. If delivery still fails, Spacebot sends a short notice and keeps the result pending. The next user message starts another bounded relay attempt, so the result is not lost or written into conversation history as internal control text.

## Bindings

Bindings route messages from a platform to a specific agent. A binding says "messages from this place go to this agent."
Expand Down
Loading
Loading