Merge branch 'bg-jobs'

Author: ericdallo

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - Refresh auth token before each LLM API call, preventing stale tokens during long-running tool calls.
+- Add background shell command support via `background` parameter on `shell_command` tool and new `bg_job` tool for managing long-running processes. #77
 
 ## 0.124.5
 

docs/protocol.md

@@ -2629,6 +2629,119 @@ _Notification:_
 * method: `providers/updated`
 * params: `ProviderStatus` (see `providers/list` response above)
 
+## Background Jobs
+
+### List Jobs (↩️)
+
+Returns all active (non-evicted) background jobs across all chats.
+
+_Request:_
+
+* method: `jobs/list`
+* params: `{}` (none)
+
+_Response:_
+
+* result: `JobsListResult` defined as follows:
+
+```typescript
+interface JobsListResult {
+    jobs: JobSummary[];
+}
+
+interface JobSummary {
+    /** Unique job identifier (e.g. "job-1"). */
+    id: string;
+    /** Job type (currently always "shell"). */
+    type: string;
+    /** Current status. */
+    status: "running" | "completed" | "failed" | "killed";
+    /** Human-readable label (the command string). */
+    label: string;
+    /** Brief description of the job purpose (e.g. "dev-server"), or null if not provided. */
+    summary: string | null;
+    /** ISO 8601 timestamp of when the job started. */
+    startedAt: string;
+    /** Human-readable elapsed time (e.g. "5m23s"). */
+    elapsed: string;
+    /** Process exit code, or null if still running. */
+    exitCode: number | null;
+    /** The chat that spawned this job. */
+    chatId: string;
+    /** Display label for the chat (title or chat-id fallback). */
+    chatLabel: string;
+}
+```
+
+### Kill Job (↩️)
+
+Terminates a running background job.
+
+_Request:_
+
+* method: `jobs/kill`
+* params: `JobsKillParams` defined as follows:
+
+```typescript
+interface JobsKillParams {
+    /** The job ID to kill. */
+    jobId: string;
+}
+```
+
+_Response:_
+
+* result: `{ killed: boolean }`
+
+### Read Job Output (↩️)
+
+Returns the currently buffered output lines for a background job. This is a snapshot read
+that does not affect the LLM's incremental read cursor.
+
+_Request:_
+
+* method: `jobs/readOutput`
+* params: `JobsReadOutputParams` defined as follows:
+
+```typescript
+interface JobsReadOutputParams {
+    /** The job ID to read output from. */
+    jobId: string;
+}
+```
+
+_Response:_
+
+* result: `JobsReadOutputResult` defined as follows:
+
+```typescript
+interface JobsReadOutputResult {
+    /** Buffered output lines (up to 2000 most recent), tagged with stream source. */
+    lines: OutputLine[];
+    /** Current job status. */
+    status: "running" | "completed" | "failed" | "killed";
+    /** Process exit code, or null if still running. */
+    exitCode: number | null;
+}
+
+interface OutputLine {
+    /** The text content of the line. */
+    text: string;
+    /** Which stream produced this line. */
+    stream: "stdout" | "stderr";
+}
+```
+
+### Jobs Updated (⬅️)
+
+A server notification sent when the background jobs list changes. Sent after a job is
+created, completes, fails, is killed, or is evicted. Contains the full list of active jobs.
+
+_Notification:_
+
+* method: `jobs/updated`
+* params: `JobsListResult` (see `jobs/list` response above)
+
 ## General features
 
 ### progress (⬅️)

integration-test/entrypoint.clj

@@ -20,6 +20,7 @@
     integration.chat.hooks-test
     integration.chat.commands-test
     integration.chat.mcp-remote-test
+    integration.chat.background-jobs-test
     integration.rewrite.openai-test])
 
 (defn timeout [timeout-ms callback]

integration-test/integration/chat/background_jobs_test.clj

@@ -0,0 +1,72 @@
+(ns integration.chat.background-jobs-test
+  (:require
+   [clojure.test :refer [deftest is testing]]
+   [integration.eca :as eca]
+   [integration.fixture :as fixture]
+   [llm-mock.mocks :as llm.mocks]
+   [matcher-combinators.matchers :as m]
+   [matcher-combinators.test :refer [match?]]))
+
+(eca/clean-after-test)
+
+(deftest background-job-lifecycle
+  (eca/start-process!)
+  (eca/request! (fixture/initialize-request))
+  (eca/notify! (fixture/initialized-notification))
+
+  (let [chat-id* (atom nil)
+        job-id* (atom nil)]
+
+    (testing "Prompt triggers a background shell command"
+      (llm.mocks/set-case! :bg-shell-0)
+      (let [resp (eca/request! (fixture/chat-prompt-request
+                                 {:model "anthropic/claude-sonnet-4-6"
+                                  :message "Run a background command"}))]
+        (reset! chat-id* (:chatId resp))
+        (is (match? {:chatId (m/pred string?)
+                     :status "prompting"}
+                    resp))))
+
+    (testing "Server sends jobs/updated notification when job starts"
+      (let [notification (eca/client-awaits-server-notification :jobs/updated)]
+        (is (match? {:jobs (m/pred #(pos? (count %)))}
+                    notification))
+        (let [job (first (:jobs notification))]
+          (reset! job-id* (:id job))
+          (is (match? {:id (m/pred string?)
+                       :type "shell"
+                       :status "running"
+                       :label (m/pred #(re-find #"echo bg-test-output" %))
+                       :summary "bg-test"}
+                      job)))))
+
+    (testing "jobs/list returns the running job"
+      (let [resp (eca/request! [:jobs/list {}])]
+        (is (match? {:jobs (m/embeds [{:id @job-id*
+                                       :status "running"}])}
+                    resp))))
+
+    (testing "jobs/readOutput returns captured output with stream tags"
+      (let [resp (eca/request! [:jobs/readOutput {:job-id @job-id*}])]
+        (is (match? {:lines (m/pred #(some (fn [l] (re-find #"bg-test-output" (:text l))) %))
+                     :status "running"}
+                    resp))
+        (is (every? #(contains? #{"stdout" "stderr"} (:stream %)) (:lines resp)))))
+
+    (testing "jobs/kill terminates the running job"
+      (let [resp (eca/request! [:jobs/kill {:job-id @job-id*}])]
+        (is (match? {:killed true} resp))))
+
+    (testing "Server sends jobs/updated notification after kill"
+      (let [notification (eca/client-awaits-server-notification :jobs/updated)]
+        (is (match? {:jobs (m/embeds [{:id @job-id*
+                                       :status "killed"}])}
+                    notification))))
+
+    (testing "jobs/kill on already-killed job returns false"
+      (let [resp (eca/request! [:jobs/kill {:job-id @job-id*}])]
+        (is (match? {:killed false} resp))))
+
+    (testing "jobs/readOutput on non-existent job returns empty"
+      (let [resp (eca/request! [:jobs/readOutput {:job-id "job-999"}])]
+        (is (match? {:lines [] :status nil} resp))))))

integration-test/llm_mock/anthropic.clj

@@ -298,6 +298,47 @@
         (sse-send! ch "message_stop" {:type "message_stop"})
         (hk/close ch)))))
 
+(defn ^:private bg-shell-0 [ch body]
+  (let [second-stage? (some (fn [{:keys [content]}]
+                              (some #(= "tool_result" (:type %)) content))
+                            (:messages body))]
+    (if-not second-stage?
+      (do
+        (sse-send! ch "content_block_delta"
+                   {:type "content_block_delta"
+                    :index 0
+                    :delta {:type "text_delta" :text "I will run a background command"}})
+        (sse-send! ch "content_block_start"
+                   {:type "content_block_start"
+                    :index 1
+                    :content_block {:type "tool_use"
+                                    :id "bg-tool-1"
+                                    :name "eca__shell_command"}})
+        (sse-send! ch "content_block_delta"
+                   {:type "content_block_delta"
+                    :index 1
+                    :delta {:type "input_json_delta"
+                            :partial_json "{\"command\":\"echo bg-test-output && sleep 30\",\"background\":\"bg-test\"}"}})
+        (sse-send! ch "message_delta"
+                   {:type "message_delta"
+                    :delta {:stop_reason "tool_use"}
+                    :usage {:input_tokens 10
+                            :output_tokens 20}})
+        (sse-send! ch "message_stop" {:type "message_stop"})
+        (hk/close ch))
+      (do
+        (sse-send! ch "content_block_delta"
+                   {:type "content_block_delta"
+                    :index 0
+                    :delta {:type "text_delta" :text "Background job started successfully"}})
+        (sse-send! ch "message_delta"
+                   {:type "message_delta"
+                    :delta {:stop_reason "end_turn"}
+                    :usage {:input_tokens 15
+                            :output_tokens 10}})
+        (sse-send! ch "message_stop" {:type "message_stop"})
+        (hk/close ch)))))
+
 (defn ^:private compact-0 [ch]
   ;; LLM calls eca__compact_chat with a summary — no text or reasoning
   (sse-send! ch "content_block_start"
@@ -349,5 +390,6 @@
                        :reasoning-1 (reasoning-1 ch)
                        :tool-calling-0 (tool-calling-0 ch body)
                        :mcp-tool-call-0 (mcp-tool-call-0 ch body)
-                       :mcp-add-tool-0 (mcp-add-tool-0 ch body)
-                       :compact-0 (compact-0 ch)))))})))
+                                             :mcp-add-tool-0 (mcp-add-tool-0 ch body)
+                                             :bg-shell-0 (bg-shell-0 ch body)
+                                             :compact-0 (compact-0 ch)))))})))

resources/prompts/tools/bg_job.md

@@ -0,0 +1,13 @@
+Manage background jobs (long-running shell processes).
+
+Actions:
+- `list`: Show all background jobs with their ID, status, elapsed time, and command.
+- `read_output`: Read new output from a background job since the last read. Requires `job_id`.
+- `kill`: Terminate a running background job. Requires `job_id`.
+
+Usage notes:
+- Background jobs are started via `eca__shell_command` with `background` set to a brief description (e.g., `"dev-server"`).
+- `read_output` returns only **new** output since your last read, so call it periodically to monitor.
+- Job IDs follow the pattern `job-1`, `job-2`, etc.
+- Use `list` to discover running jobs if you don't remember the ID.
+- All background jobs are automatically cleaned up when ECA exits.

resources/prompts/tools/shell_command.md

@@ -16,6 +16,12 @@ Before executing the command, please follow these steps:
   - After ensuring proper quoting, execute the command.
   - Capture the output of the command.
 
+Background execution:
+  - Set `background` to a brief description for long-running commands that don't terminate on their own
+    (e.g., `"dev-server"`, `"file-watcher"`, `"docker-compose"`).
+  - Background commands return immediately with a job ID.
+  - Use `eca__bg_job` with action `read_output` to check output, or `kill` to stop the process.
+
 Usage notes:
   - The `command` argument is required.
   - It is very helpful if you write a clear, concise description of what this command does in 5-10 words.