Support streaming tool output and deduplication

.agents/commands/live-validate.md

@@ -0,0 +1,68 @@
+# Live validation of agent-shell rendering
+
+Run a live agent-shell session in batch mode and verify the buffer output.
+This exercises the full rendering pipeline with real ACP traffic — the only
+way to catch ordering, marker, and streaming bugs that unit tests miss.
+
+## Prerequisites
+
+- `ANTHROPIC_API_KEY` must be available (via `op run` / 1Password)
+- `timvisher_emacs_agent_shell` must be on PATH
+- Dependencies (acp.el-plus, shell-maker) in sibling worktrees or
+  overridden via env vars
+
+## How to run
+
+```bash
+cd "$(git rev-parse --show-toplevel)"
+timvisher_agent_shell_checkout=. \
+  timvisher_emacs_agent_shell claude --batch \
+  1>/tmp/agent-shell-live-stdout.log \
+  2>/tmp/agent-shell-live-stderr.log
+```
+
+Stderr shows heartbeat lines every 30 seconds.  Stdout contains the
+full buffer dump once the agent turn completes.
+
+## What to check in the output
+
+1. **Fragment ordering**: tool call drawers should appear in
+   chronological order (the order the agent invoked them), not
+   reversed.  Look for `▶` lines — their sequence should match the
+   logical execution order.
+
+2. **No duplicate content**: each tool call output should appear
+   exactly once.  Watch for repeated blocks of identical text.
+
+3. **Prompt position**: the prompt line (`agent-shell>`) should
+   appear at the very end of the buffer, after all fragments.
+
+4. **Notices placement**: `[hook-trace]` and other notice lines
+   should appear in a `Notices` section, not interleaved with tool
+   call fragments.
+
+## Enabling invariant checking
+
+To run with runtime invariant assertions (catches corruption as it
+happens rather than after the fact):
+
+```elisp
+;; Add to your init or eval before the session starts:
+(setq agent-shell-invariants-enabled t)
+```
+
+When an invariant fires, a `*agent-shell invariant*` buffer pops up
+with a debug bundle and recommended analysis prompt.
+
+## Quick validation one-liner
+
+```bash
+cd "$(git rev-parse --show-toplevel)" && \
+  timvisher_agent_shell_checkout=. \
+  timvisher_emacs_agent_shell claude --batch \
+  1>/tmp/agent-shell-live.log 2>&1 && \
+  grep -n '▶' /tmp/agent-shell-live.log | head -20
+```
+
+If the `▶` lines are in logical order and the exit code is 0, the
+rendering pipeline is healthy.

.claude

@@ -0,0 +1 @@
+.agents

.codex

@@ -0,0 +1 @@
+.agents

.gemini

@@ -0,0 +1 @@
+.agents

.github/workflows/ci.yml

@@ -36,6 +36,101 @@ jobs:
             fi
           fi
 
+  agent-symlinks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify agent config symlinks
+        run: |
+          ok=true
+          for dir in .claude .codex .gemini; do
+            target=$(readlink "${dir}" 2>/dev/null)
+            if [[ "${target}" != ".agents" ]]; then
+              echo "::error::${dir} should symlink to .agents but points to '${target:-<missing>}'"
+              ok=false
+            fi
+          done
+          for md in CLAUDE.md CODEX.md GEMINI.md; do
+            target=$(readlink "${md}" 2>/dev/null)
+            if [[ "${target}" != "AGENTS.md" ]]; then
+              echo "::error::${md} should symlink to AGENTS.md but points to '${target:-<missing>}'"
+              ok=false
+            fi
+          done
+          if ! [[ -d .agents/commands ]]; then
+            echo "::error::.agents/commands/ directory missing"
+            ok=false
+          fi
+          if [[ "${ok}" != "true" ]]; then
+            exit 1
+          fi
+          echo "All agent config symlinks verified."
+
+  dependency-dag:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify require graph is a DAG (no cycles)
+        run: |
+          # Build the set of project-internal modules from *.el filenames.
+          declare -A project_modules
+          for f in *.el; do
+            mod="${f%.el}"
+            project_modules["${mod}"]=1
+          done
+
+          # Parse (require 'foo) from each file and build an adjacency list.
+          # Only track edges where both ends are project-internal.
+          declare -A edges  # edges["a"]="b c" means a requires b and c
+          for f in *.el; do
+            mod="${f%.el}"
+            deps=""
+            while IFS= read -r dep; do
+              if [[ -n "${project_modules[$dep]+x}" ]]; then
+                deps="${deps} ${dep}"
+              fi
+            done < <(sed -n "s/^.*(require '\\([a-zA-Z0-9_-]*\\)).*/\\1/p" "$f")
+            edges["${mod}"]="${deps}"
+          done
+
+          # DFS cycle detection.
+          declare -A color  # white=unvisited, gray=in-stack, black=done
+          found_cycle=""
+          cycle_path=""
+
+          dfs() {
+            local node="$1"
+            local path="$2"
+            color["${node}"]="gray"
+            for neighbor in ${edges["${node}"]}; do
+              if [[ "${color[$neighbor]:-white}" == "gray" ]]; then
+                found_cycle=1
+                cycle_path="${path} -> ${neighbor}"
+                return
+              fi
+              if [[ "${color[$neighbor]:-white}" == "white" ]]; then
+                dfs "${neighbor}" "${path} -> ${neighbor}"
+                if [[ -n "${found_cycle}" ]]; then
+                  return
+                fi
+              fi
+            done
+            color["${node}"]="black"
+          }
+
+          for mod in "${!project_modules[@]}"; do
+            if [[ "${color[$mod]:-white}" == "white" ]]; then
+              dfs "${mod}" "${mod}"
+              if [[ -n "${found_cycle}" ]]; then
+                echo "::error::Dependency cycle detected: ${cycle_path}"
+                exit 1
+              fi
+            fi
+          done
+          echo "Dependency graph is a DAG — no cycles found."
+
   test:
     runs-on: ubuntu-latest
     steps:

AGENTS.md

@@ -24,9 +24,18 @@ When adding or changing features:
 
 1. **Run `bin/test`.** Set `acp_root` and `shell_maker_root` if the
    deps aren't in sibling worktrees. This runs byte-compilation, ERT
-   tests, and checks that `README.org` was updated when code changed.
+   tests, dependency DAG check, and checks that `README.org` was
+   updated when code changed.
 2. **Keep the README features list current.** The "Features on top of
    agent-shell" section in `README.org` must be updated whenever code
    changes land. Both `bin/test` and CI enforce this — changes to `.el`
    or `tests/` files without a corresponding `README.org` update will
    fail.
+3. **Live-validate rendering changes.** For changes to the rendering
+   pipeline (fragment insertion, streaming, markers, UI), run a live
+   batch session to verify fragment ordering and buffer integrity.
+   See `.agents/commands/live-validate.md` for details. The key command:
+   ```bash
+   timvisher_agent_shell_checkout=. timvisher_emacs_agent_shell claude --batch \
+     1>/tmp/agent-shell-live.log 2>&1
+   ```

CODEX.md

@@ -0,0 +1 @@
+AGENTS.md

CONTRIBUTING.org

@@ -108,6 +108,20 @@ Overall, try to flatten things. Look out for unnecessarily nested blocks and fla
     buffer)
 #+end_src
 
+Similarly, flatten =when-let= + nested =when= by using boolean guard clauses as bindings in =when-let=.
+
+#+begin_src emacs-lisp :lexical no
+  ;; Avoid
+  (when-let ((filename (file-name-nondirectory filepath)))
+    (when (not (string-empty-p filename))
+      (do-something filename)))
+
+  ;; Prefer (use boolean binding as guard clause)
+  (when-let ((filename (file-name-nondirectory filepath))
+             ((not (string-empty-p filename))))
+    (do-something filename))
+#+end_src
+
 ** Prefer =let= and =when-let= over =let*= and =when-let*=
 
 Only use the =*= variants when bindings depend on each other. LLMs tend to default to =let*= and =when-let*= even when there are no dependencies between bindings.
@@ -231,3 +245,20 @@ Tests live under the tests directory:
 Opening any file under the =tests= directory will load the =agent-shell-run-all-tests= command.
 
 Run tests with =M-x agent-shell-run-all-tests=.
+
+*** From the command line
+
+=bin/test= runs the full ERT suite in batch mode.  By default it
+expects =acp.el= and =shell-maker= to be checked out as sibling
+worktrees (e.g. =…/acp.el/main= and =…/shell-maker/main= next to
+=…/agent-shell/main=).  Override the paths with environment variables
+if your layout differs:
+
+#+begin_src bash
+  acp_root=~/path/to/acp.el \
+  shell_maker_root=~/path/to/shell-maker \
+    bin/test
+#+end_src
+
+The script validates that both dependencies are readable and exits
+with a descriptive error if either is missing.

README.org

@@ -6,11 +6,18 @@ A soft fork of [[https://github.com/xenodium/agent-shell][agent-shell]] with ext
 * Features on top of agent-shell
 
 - CI workflow and local test runner ([[https://github.com/timvisher-dd/agent-shell-plus/pull/1][#1]], [[https://github.com/timvisher-dd/agent-shell-plus/pull/6][#6]], [[https://github.com/timvisher-dd/agent-shell-plus/pull/8][#8]])
+  - Byte-compilation of all =.el= files ([[https://github.com/timvisher-dd/agent-shell-plus/pull/1][#1]])
+  - ERT test suite ([[https://github.com/timvisher-dd/agent-shell-plus/pull/1][#1]])
+  - README update check when code changes ([[https://github.com/timvisher-dd/agent-shell-plus/pull/4][#4]])
+  - Dependency DAG check (=require= graph must be acyclic) ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
 - Desktop notifications when the prompt is idle and waiting for input ([[https://github.com/timvisher-dd/agent-shell-plus/pull/2][#2]], [[https://github.com/timvisher-dd/agent-shell-plus/pull/8][#8]])
 - Per-shell debug logging infrastructure ([[https://github.com/timvisher-dd/agent-shell-plus/pull/2][#2]])
 - Regression tests for shell buffer selection ordering ([[https://github.com/timvisher-dd/agent-shell-plus/pull/3][#3]])
 - CI check that README.org is updated when code changes ([[https://github.com/timvisher-dd/agent-shell-plus/pull/4][#4]])
 - Usage tests and defense against ACP =used > size= bug ([[https://github.com/timvisher-dd/agent-shell-plus/pull/5][#5]])
+- Streaming tool output with dedup: advertise =_meta.terminal_output= capability, handle incremental chunks from codex-acp and batch results from claude-agent-acp, strip =<persisted-output>= tags, fix O(n²) rendering, and partial-overlap thought dedup ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
+- DWIM context insertion: inserted context lands at the prompt and fragment updates no longer drag process-mark past it ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
+- Runtime buffer invariant checking with event tracing and violation debug bundles ([[https://github.com/timvisher-dd/agent-shell-plus/pull/7][#7]])
 
 -----
 
@@ -53,15 +60,18 @@ Watch on [[https://www.youtube.com/watch?v=R2Ucr3amgGg][YouTube]]
 
 We now have a handful of additional packages to extend the =agent-shell= experience:
 
-- [[https://github.com/nineluj/agent-review][agent-review]]: Code review interface for =agent-shell=.
-- [[https://github.com/ultronozm/agent-shell-attention.el][agent-shell-attention.el]]: Mode-line attention tracker for =agent-shell=.
-- [[https://github.com/jethrokuan/agent-shell-manager][agent-shell-manager]]: Tabulated view and management of =agent-shell= buffers.
+- [[https://github.com/xenodium/emacs-skills][emacs-skills]]: Claude Agent skills for Emacs.
+- [[https://github.com/ElleNajt/agent-shell-to-go][agent-shell-to-go]]: Interact with =agent-shell= sessions from your mobile or any other device via Slack.
+- [[https://github.com/Embedded-Focus/agent-circus][agent-circus]]: Run AI coding agents in sandboxed Docker containers.
 - [[https://github.com/cmacrae/agent-shell-sidebar][agent-shell-sidebar]]: A sidebar add-on for =agent-shell=.
+- [[https://github.com/dcluna/agent-shell-bookmark][agent-shell-bookmark]]: Bookmark support for agent-shell sessions.
 - [[https://github.com/gveres/agent-shell-workspace][agent-shell-workspace]]: Dedicated tab-bar workspace for managing multiple =agent-shell= sessions.
-- [[https://github.com/ElleNajt/agent-shell-to-go][agent-shell-to-go]]: Interact with =agent-shell= sessions from your mobile or any other device via Slack.
-- [[https://github.com/ElleNajt/meta-agent-shell][meta-agent-shell]]: Multi-agent coordination system for =agent-shell= with inter-agent communication, task tracking, and project-level dispatching.
+- [[https://github.com/jethrokuan/agent-shell-manager][agent-shell-manager]]: Tabulated view and management of =agent-shell= buffers.
+- [[https://github.com/nineluj/agent-review][agent-review]]: Code review interface for =agent-shell=.
+- [[https://github.com/ultronozm/agent-shell-attention.el][agent-shell-attention.el]]: Mode-line attention tracker for =agent-shell=.
 - [[https://github.com/xenodium/agent-shell-knockknock][agent-shell-knockknock]]: Notifications for =agent-shell= via [[https://github.com/konrad1977/knockknock][knockknock.el]].
-- [[https://github.com/xenodium/emacs-skills][emacs-skills]]: Claude Agent skills for Emacs.
+- [[https://github.com/zackattackz/agent-shell-notifications][agent-shell-notifications]]: Desktop notifications for =agent-shell= events.
+- [[https://github.com/ElleNajt/meta-agent-shell][meta-agent-shell]]: Multi-agent coordination system for =agent-shell= with inter-agent communication, task tracking, and project-level dispatching.
 
 * Icons
 
@@ -212,7 +222,7 @@ Pass environment variables to the spawned agent process by customizing the `agen
 #+begin_src emacs-lisp
 (setq agent-shell-anthropic-claude-environment
       (agent-shell-make-environment-variables
-       "ANTHROPIC_API_KEY" (auth-source-pass-get "secret" "anthropic-api-key")
+       "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key")
        "HTTPS_PROXY" "http://proxy.example.com:8080"))
 #+end_src
 
@@ -221,7 +231,7 @@ Pass environment variables to the spawned agent process by customizing the `agen
 By default, the agent process starts with a minimal environment. To inherit environment variables from the parent Emacs process, use the `:inherit-env t` parameter in `agent-shell-make-environment-variables`:
 
 #+begin_src emacs-lisp
-  (setenv "ANTHROPIC_API_KEY" (auth-source-pass-get "secret" "anthropic-api-key"))
+  (setenv "ANTHROPIC_API_KEY" (auth-source-pass-get 'secret "anthropic-api-key"))
 
   (setq agent-shell-anthropic-claude-environment
         (agent-shell-make-environment-variables :inherit-env t))
@@ -268,7 +278,20 @@ For API key authentication:
 ;; With function
 (setq agent-shell-anthropic-authentication
       (agent-shell-anthropic-make-authentication
-       :api-key (lambda () (auth-source-pass-get "secret" "anthropic-api-key"))))
+       :api-key (lambda () (auth-source-pass-get 'secret "anthropic-api-key"))))
+#+end_src
+
+For OAuth token authentication (the =CLAUDE_CODE_OAUTH_TOKEN= we get from =claude setup-token=):
+
+#+begin_src emacs-lisp
+;; With string
+(setq agent-shell-anthropic-authentication
+      (agent-shell-anthropic-make-authentication :oauth "your-oauth-token-here"))
+
+;; With function
+(setq agent-shell-anthropic-authentication
+      (agent-shell-anthropic-make-authentication
+       :oauth (lambda () (auth-source-pass-get "secret" "anthropic-oauth-token"))))
 #+end_src
 
 For alternative Anthropic-compatible API endpoints, configure via environment variables:
@@ -300,7 +323,7 @@ For API key authentication:
 ;; With function
 (setq agent-shell-google-authentication
       (agent-shell-google-make-authentication
-       :api-key (lambda () (auth-source-pass-get "secret" "google-api-key"))))
+       :api-key (lambda () (auth-source-pass-get 'secret "google-api-key"))))
 #+end_src
 
 For Vertex AI authentication:
@@ -329,7 +352,7 @@ For API key authentication:
 ;; With function
 (setq agent-shell-openai-authentication
       (agent-shell-openai-make-authentication
-       :api-key (lambda () (auth-source-pass-get "secret" "openai-api-key"))))
+       :api-key (lambda () (auth-source-pass-get 'secret "openai-api-key"))))
 #+end_src
 
 *** Goose
@@ -344,7 +367,7 @@ For OpenAI API key authentication:
 ;; With function
 (setq agent-shell-goose-authentication
       (agent-shell-make-goose-authentication
-       :openai-api-key (lambda () (auth-source-pass-get "secret" "openai-api-key"))))
+       :openai-api-key (lambda () (auth-source-pass-get 'secret "openai-api-key"))))
 #+end_src
 
 *** Qwen Code
@@ -513,6 +536,13 @@ For example, to store data under =user-emacs-directory= instead of the project t
 
 This stores data at a path like =~/.emacs.d/agent-shell/home-user-src-myproject/screenshots/=.
 
+*** Screenshots from clipboard
+
+You can send a screenshot from your clipboard to your shell with =agent-shell-send-clipboard-image=. Call with =C-u= to =agent-shell-send-clipboard-image-to= to select from your shells. agent-shell relies on external programs to write an image from clipboard to file as configured in =agent-shell-clipboard-image-handlers=. Preconfigured handlers are
+- =wl-paste= for Wayland desktops,
+- =xclip= for Xorg,
+- =pngpaste= for MacOS.
+
 *** Inhibiting minor modes during file writes
 
 Some minor modes (for example, =aggressive-indent-mode=) can interfere with an agent's edits.  Agent Shell can temporarily disable selected per-buffer minor modes while applying edits.
@@ -805,6 +835,13 @@ Please read through this section before filing issues or feature requests. I won
 - *Your agent-shell config*: Share any relevant =agent-shell= variable settings from your Emacs config.
 - *Profiling data* (for performance issues): Use =M-x profiler-start=, reproduce the issue, then =M-x profiler-report= (and =M-x profiler-stop=). Share the report.
 
+** Why doesn't =agent-shell= offer all slash commands available in CLI agent?
+
+=agent-shell= can only offer the slash commands advertised by the agent via [[https://agentclientprotocol.com][Agent Client Protocol]]. To view what's exposed by your agent, expand the "Available /commands" section. Is the command you're after missing? Please consider filing a feature-request with the respective agent (ie. Gemini CLI) or their ACP layer (claude-code-acp).
+
+[[file:slash-commands.png]]
+
+
 ** Can you add support for another agent?
 
 Does the agent support ACP ([[https://agentclientprotocol.com][Agent Client Protocol]])? If so, =agent-shell= can likely support this agent. Some agents have ACP support built-in (like [[https://github.com/google-gemini/gemini-cli][gemini-cli]]). Others require a separate ACP package (like [[https://github.com/zed-industries/claude-code-acp][claude-code-acp]] for [[https://github.com/anthropics/claude-code][claude-code]]). When filing a feature request to add a new agent, please include a link to the project supporting [[https://agentclientprotocol.com][Agent Client Protocol]] (built-in or otherwise).