From 6256b5fcfa45d4bf76534b8c05f502855fb1d2ef Mon Sep 17 00:00:00 2001 From: Alex Clarke Date: Tue, 25 Aug 2026 18:16:31 -0600 Subject: [PATCH] docs: document background jobs across prompts, config example, and README - Extend the injected Background Jobs prompt guidance: system_notifications push on completion, collect-only-when-idle wait protocol, and the graph LLM-node collect-before-final-turn rule - Mention the system_notifications push in the agent spawning guidance and in the sisyphus/architect wait-protocol text (agent completions push notifications too) - config.example.yaml: max_concurrent_jobs (default 5, 0 = disabled) - README: features-list entry pointing at the Background-Jobs wiki page --- README.md | 1 + assets/agents/architect/config.yaml | 2 +- assets/agents/sisyphus/config.yaml | 2 +- config.example.yaml | 1 + src/config/prompts.rs | 19 ++++++++++++------- 5 files changed, 16 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index 0d32e56..dda5ec7 100644 --- a/README.md +++ b/README.md @@ -51,6 +51,7 @@ Coming from [AIChat](https://github.com/sigoden/aichat)? Follow the [migration g * [Skills](https://github.com/Dark-Alex-17/coyote/wiki/Skills): Modular knowledge or capability packs the LLM can load and unload mid-conversation. Multiple skills compose; instructions stack, tools and MCPs union. * [Agents](https://github.com/Dark-Alex-17/coyote/wiki/Agents): Leverage AI agents to perform complex tasks and workflows, including sub-agent spawning, teammate messaging, and user interaction tools. * [Graph Agents](https://github.com/Dark-Alex-17/coyote/wiki/Graph-Agents): Define an agent as a declarative, YAML-driven workflow. A directed graph of typed nodes (LLM calls, scripts, approvals, user input, RAG retrieval, sub-agent spawns). +* [Background Jobs](https://github.com/Dark-Alex-17/coyote/wiki/Background-Jobs): Run long tool calls (builds, test suites, slow MCP calls) in the background with the `job__*` tools while the model keeps working — completion arrives as a push notification. * [Todo System](https://github.com/Dark-Alex-17/coyote/wiki/TODO-System): Built-in task tracking for improved LLM reliability with smaller models. * [Environment Variables](https://github.com/Dark-Alex-17/coyote/wiki/Environment-Variables): Override and customize your Coyote configuration at runtime with environment variables. * [Client Configurations](https://github.com/Dark-Alex-17/coyote/wiki/Clients): Configuration instructions for various LLM providers. diff --git a/assets/agents/architect/config.yaml b/assets/agents/architect/config.yaml index b4b365d..3cc1fab 100644 --- a/assets/agents/architect/config.yaml +++ b/assets/agents/architect/config.yaml @@ -261,7 +261,7 @@ instructions: | 3. **Wait for Sisyphus.** Do not poll `agent__collect` on a running agent — do non-overlapping work (e.g. prep the next task's context) or end your response and wait for the completion - notification, then `agent__collect`. + notification (a `system_notifications` entry on your next tool result), then `agent__collect`. 4. **Verify against the plan (divergence check).** When Sisyphus returns, do NOT trust its self-report — get an INDEPENDENT conformance verdict: diff --git a/assets/agents/sisyphus/config.yaml b/assets/agents/sisyphus/config.yaml index dbbd2b7..05dc267 100644 --- a/assets/agents/sisyphus/config.yaml +++ b/assets/agents/sisyphus/config.yaml @@ -233,7 +233,7 @@ instructions: | 1. Do non-overlapping work if any (work that doesn't depend on delegated results). 2. If none → **end your response.** Do not call `agent__collect` immediately. - 3. The system notifies you on completion. + 3. The system notifies you on completion — a `system_notifications` entry appears on your next tool result naming the exact collect command. 4. On notification, call `agent__collect` to retrieve results. ### Anti-duplication rule (BLOCKING) diff --git a/config.example.yaml b/config.example.yaml index 247333a..40ab1c5 100644 --- a/config.example.yaml +++ b/config.example.yaml @@ -204,6 +204,7 @@ summary_context_prompt: > # The text prompt used for including the summar 'This is a summary of the chat history as a recap: ' compression_keep_last: 0 # Number of most-recent messages to keep visible after compression (0 = compress all messages) max_tool_result_chars: null # Cap on tool result characters forwarded to the model per call (null = no cap) +max_concurrent_jobs: 5 # Max background jobs (`job__*` tools) running at once per context (default: 5; 0 disables background jobs entirely) # ---- Memory ---- # See the [Memory documentation](https://github.com/Dark-Alex-17/coyote/wiki/Memory) for more information. diff --git a/src/config/prompts.rs b/src/config/prompts.rs index 556bc26..58ac50e 100644 --- a/src/config/prompts.rs +++ b/src/config/prompts.rs @@ -112,9 +112,10 @@ pub(in crate::config) const DEFAULT_SPAWN_INSTRUCTIONS: &str = indoc! {" ### CRITICAL: Never end your turn with pending agents - Spawned agents do NOT report back on their own. They run in the background until you - actively reclaim them with `agent__collect` (to get their output) or `agent__cancel` - (to discard them). If you spawn agents and then emit a final message without reclaiming + Spawned agents do NOT deliver their results on their own. When one finishes, a + `system_notifications` entry appears on your next tool result naming the exact collect + command — but the output is only retrieved when you actively reclaim it with `agent__collect` + (or discard it with `agent__cancel`). If you spawn agents and then emit a final message without reclaiming them, the system will detect the unreclaimed agents and reject the turn-end, injecting a reminder forcing you to handle them. After several such reminders, the system will auto-cancel them and warn you that work was lost. @@ -194,10 +195,14 @@ pub(in crate::config) const DEFAULT_JOB_INSTRUCTIONS: &str = indoc! {" ## Background Jobs For long-running tool calls (builds, test suites, slow commands), call `job__start` and keep - working instead of blocking. Check progress with `job__check` (sparingly), block on the result - with `job__collect`, cancel with `job__cancel`, and list jobs with `job__list`. Collect or - cancel every job you started before ending your turn. Jobs run against a snapshot of the - current config/environment and do not survive coyote exiting. + working instead of blocking — completion arrives as a `system_notifications` entry on your + next tool result. Check progress with `job__check` (sparingly), block on the result with + `job__collect` (only when you have nothing else to do), cancel with `job__cancel`, and list + jobs with `job__list`. Collect or cancel every job you started before ending your turn. In + graph LLM nodes, collect or cancel your jobs before ending your final node turn — an + uncollected job at node turn-end burns node iterations via the guardrail and can fail the + node. Jobs run against a snapshot of the current config/environment and do not survive + coyote exiting. " };