branch: externals/ellama
commit 84199019822ea7f8f4b1703bf5f44e88be8de2fb
Author: Sergey Kostyaev <[email protected]>
Commit: Sergey Kostyaev <[email protected]>
Document agent loop and DLP updates
Updated user documentation for agent error recovery, asynchronous edit
hooks, trusted read-file DLP bypasses, undo-on-error behavior, and
warning-failing Elisp checks. Regenerated the Info manual from README.org.
---
README.org | 64 +++++++++++++++++++-
docs/dlp_rollout_guide.md | 22 +++++++
ellama.info | 147 +++++++++++++++++++++++++++++++++-------------
3 files changed, 190 insertions(+), 43 deletions(-)
diff --git a/README.org b/README.org
index c058d4d989..686903646d 100644
--- a/README.org
+++ b/README.org
@@ -433,6 +433,9 @@ generated text string.
~*ellama-debug*~ buffer with a separator for easier tracking of debug
information. The debug output includes the raw text being processed and is
appended to the end of the debug buffer each time.
+- ~ellama-undo-on-error~: Undo partial buffer insertions when an LLM request
+ fails. Disabled by default; when nil, Ellama keeps partial output inserted
+ before the error.
- ~ellama-tools-allow-all~: Allow ~ellama~ using all the tools without user
confirmation. Dangerous. Use at your own risk.
- ~ellama-tools-allowed~: List of allowed ~ellama~ tools. Tools from this list
@@ -442,10 +445,18 @@ generated text string.
- ~ellama-tools-read-file-default-mode~: Default mode for the ~read_file~
tool. Use ~auto~ to read text files as text and supported image files as
media, ~text~ to force text reading, or ~image~ to force image handling.
+- ~ellama-tools-dlp-safe-read-file-regexps~: Canonical file-name regexps whose
+ ~read_file~-style outputs skip output DLP scans. Defaults to Ellama source
+ files in the loaded Ellama directory. Input DLP, other tool outputs, access
+ checks and output line budgets still apply.
- ~ellama-tools-edit-before-shell-commands~: Shell hook plists to run before
- mutating edit tools write files.
+ mutating edit tools write files. Hooks run asynchronously from Emacs' UI, but
+ the edit tool result is returned to the agent only after hook processing
+ finishes.
- ~ellama-tools-edit-after-shell-commands~: Shell hook plists to run after
- mutating edit tools write files.
+ mutating edit tools write files. Hooks run asynchronously from Emacs' UI, but
+ the edit tool result is returned to the agent only after hook processing
+ finishes.
- ~ellama-tools-use-srt~: Run shell-based tools (~shell_command~, ~grep~ and
~grep_in_file~) via the external ~srt~ sandbox runtime. Disabled by default.
If enabled, non-shell file tools also perform local filesystem checks derived
@@ -478,6 +489,8 @@ generated text string.
Skills.
- ~ellama-skills-local-path~: Project-relative path for local Agent Skills.
Default value is ~"skills"~.
+- ~ellama-tools-agent-default-max-steps~: Default maximum number of automatic
+ continuation steps for ~ellama-plan-and-act~. Default value is 40.
- ~ellama-tools-subagent-default-max-steps~: Default maximum number of
auto-continue steps for a sub-agent. Default value is 30.
- ~ellama-tools-subagent-loop-detection-enabled~: Detect repeated identical
tool
@@ -649,6 +662,13 @@ Ellama finishes the subtask with a loop-detected result. A
later repeated call
after a different tool call is treated as a new recovery opportunity, not as an
immediate hard loop.
+If a sub-agent LLM request fails before producing a tool result, Ellama keeps
+the sub-agent loop alive. The first consecutive request error records the
+failure and immediately continues the sub-agent. The second consecutive request
+error resets the counter, compacts the sub-agent session automatically, and
+continues the loop after compaction finishes or is skipped. Any successful
+sub-agent response resets the consecutive error counter.
+
The tool accepts either a free-form ~description~ or a prompt template:
#+begin_src json
@@ -687,6 +707,12 @@ continues automatically through the checklist until the
agent reports a result,
marks the plan complete, becomes blocked, or reaches
~ellama-tools-agent-default-max-steps~.
+If the LLM request fails before the loop receives a usable response, Ellama
+continues the same agent loop instead of stopping it. The first consecutive
+request error is recorded and the loop continues. The second consecutive
request
+error triggers automatic session compaction, resets the error counter, and then
+continues the loop. A successful response resets the consecutive error counter.
+
The loop adds temporary controller tools to the session:
- ~agent_submit_plan~ records the initial checklist before acting starts
@@ -731,6 +757,11 @@ is written. A failing before hook blocks the edit. After
hooks run after a
successful write; failure is reported to the agent and does not roll back the
edit.
+Hook processes are started asynchronously, so long-running hooks do not block
+the Emacs UI. They are still blocking from the agent's point of view: the edit
+tool callback runs only after all relevant before/after hooks finish, and the
+agent receives the final hook status together with the edit result.
+
Example project-local configuration:
#+BEGIN_SRC emacs-lisp
@@ -815,6 +846,11 @@ Key settings:
in ~enforce~ mode (~allow~, ~warn~, ~block~, ~redact~).
- ~ellama-tools-dlp-output-warn-behavior~: Handling for output ~warn~ verdicts
(~allow~, ~confirm~, or ~block~).
+- ~ellama-tools-dlp-safe-read-file-regexps~: Canonical file-name regexps whose
+ file-reading outputs skip output DLP scans. This is for trusted source files
+ that should not prompt on every agent read. It does not bypass input DLP,
+ non-read tool output DLP, irreversible checks, ~srt~ checks, or line-budget
+ truncation.
- ~ellama-tools-dlp-policy-overrides~: Per-tool/per-arg overrides and
exceptions. For structured input args, nested string values are scanned with
path-like arg names (for example ~payload.items[0].token~). Override ~:arg~
@@ -850,6 +886,25 @@ Key settings:
- ~ellama-tools-output-line-budget-save-overflow-file~: Save full overflowing
output to a temp file when the output source file is unknown (default ~t~).
+Trusted read-file outputs:
+
+~ellama-tools-dlp-safe-read-file-regexps~ lets users mark known source files as
+safe for output DLP. By default, Ellama marks its own loaded ~ellama*.el~
source
+files safe, so autonomous agents can inspect Ellama internals without repeated
+DLP approval prompts. The match is performed against the canonical file name.
+Only output scans for file-reading tools are skipped; DLP still scans tool
+inputs and outputs from other tools.
+
+Example:
+
+#+BEGIN_SRC emacs-lisp
+ (setopt ellama-tools-dlp-safe-read-file-regexps
+ (list (concat "\\`"
+ (regexp-quote
+ (file-truename "/path/to/ellama/"))
+ "ellama\\(?:-[[:alnum:]-]+\\)?\\.el\\'")))
+#+END_SRC
+
Enforcement behavior (v1):
- input ~block~ prevents tool execution
@@ -1646,6 +1701,11 @@ GNU ELPA; major contributions must be from someone with
FSF
papers. Alternatively, you can write a module and share it on a different
archive like MELPA.
+For local validation, run ~make check-elisp~ before pushing Elisp changes. It
+formats Elisp files, byte-compiles, runs the ERT suite, native-compiles, and
+runs checkdoc. Byte and native compilation warnings are treated as failures, so
+warnings block the same way test failures do.
+
* GNU Free Documentation License
:PROPERTIES:
:APPENDIX: t
diff --git a/docs/dlp_rollout_guide.md b/docs/dlp_rollout_guide.md
index 342aaaf2ec..46c14468f9 100644
--- a/docs/dlp_rollout_guide.md
+++ b/docs/dlp_rollout_guide.md
@@ -87,6 +87,28 @@ Block output for a specific tool in enforce mode:
:action block)))
```
+## Trusted Read-File Outputs
+
+Use `ellama-tools-dlp-safe-read-file-regexps` for source files whose
+`read_file` output is trusted and should not prompt on every autonomous-agent
+read. The setting matches canonical file names and skips only output DLP for
+file-reading tools. Input DLP, outputs from other tools, irreversible checks,
+`srt` filesystem checks, and output line-budget truncation still apply.
+
+By default, Ellama marks the loaded Ellama source files safe:
+`ellama.el`, `ellama-tools.el`, and other top-level `ellama-*.el` files in the
+same directory.
+
+Example for a source checkout:
+
+```elisp
+(setq ellama-tools-dlp-safe-read-file-regexps
+ (list (concat "\\`"
+ (regexp-quote
+ (file-truename "/path/to/ellama/"))
+ "ellama\\(?:-[[:alnum:]-]+\\)?\\.el\\'")))
+```
+
## Suggested Enforcement Progression
1. `monitor` globally with logging enabled.
diff --git a/ellama.info b/ellama.info
index de5307f386..79873f7f71 100644
--- a/ellama.info
+++ b/ellama.info
@@ -585,6 +585,9 @@ argument generated text string.
tracking of debug information. The debug output includes the raw
text being processed and is appended to the end of the debug buffer
each time.
+ • ‘ellama-undo-on-error’: Undo partial buffer insertions when an LLM
+ request fails. Disabled by default; when nil, Ellama keeps partial
+ output inserted before the error.
• ‘ellama-tools-allow-all’: Allow ‘ellama’ using all the tools
without user confirmation. Dangerous. Use at your own risk.
• ‘ellama-tools-allowed’: List of allowed ‘ellama’ tools. Tools from
@@ -595,10 +598,19 @@ argument generated text string.
‘read_file’ tool. Use ‘auto’ to read text files as text and
supported image files as media, ‘text’ to force text reading, or
‘image’ to force image handling.
+ • ‘ellama-tools-dlp-safe-read-file-regexps’: Canonical file-name
+ regexps whose ‘read_file’-style outputs skip output DLP scans.
+ Defaults to Ellama source files in the loaded Ellama directory.
+ Input DLP, other tool outputs, access checks and output line
+ budgets still apply.
• ‘ellama-tools-edit-before-shell-commands’: Shell hook plists to run
- before mutating edit tools write files.
+ before mutating edit tools write files. Hooks run asynchronously
+ from Emacs' UI, but the edit tool result is returned to the agent
+ only after hook processing finishes.
• ‘ellama-tools-edit-after-shell-commands’: Shell hook plists to run
- after mutating edit tools write files.
+ after mutating edit tools write files. Hooks run asynchronously
+ from Emacs' UI, but the edit tool result is returned to the agent
+ only after hook processing finishes.
• ‘ellama-tools-use-srt’: Run shell-based tools (‘shell_command’,
‘grep’ and ‘grep_in_file’) via the external ‘srt’ sandbox runtime.
Disabled by default. If enabled, non-shell file tools also perform
@@ -637,6 +649,9 @@ argument generated text string.
containing Agent Skills.
• ‘ellama-skills-local-path’: Project-relative path for local Agent
Skills. Default value is ‘"skills"’.
+ • ‘ellama-tools-agent-default-max-steps’: Default maximum number of
+ automatic continuation steps for ‘ellama-plan-and-act’. Default
+ value is 40.
• ‘ellama-tools-subagent-default-max-steps’: Default maximum number
of auto-continue steps for a sub-agent. Default value is 30.
• ‘ellama-tools-subagent-loop-detection-enabled’: Detect repeated
@@ -837,6 +852,14 @@ finishes the subtask with a loop-detected result. A later
repeated call
after a different tool call is treated as a new recovery opportunity,
not as an immediate hard loop.
+If a sub-agent LLM request fails before producing a tool result, Ellama
+keeps the sub-agent loop alive. The first consecutive request error
+records the failure and immediately continues the sub-agent. The second
+consecutive request error resets the counter, compacts the sub-agent
+session automatically, and continues the loop after compaction finishes
+or is skipped. Any successful sub-agent response resets the consecutive
+error counter.
+
The tool accepts either a free-form ‘description’ or a prompt template:
{
@@ -881,6 +904,13 @@ checklist, and then continues automatically through the
checklist until
the agent reports a result, marks the plan complete, becomes blocked, or
reaches ‘ellama-tools-agent-default-max-steps’.
+If the LLM request fails before the loop receives a usable response,
+Ellama continues the same agent loop instead of stopping it. The first
+consecutive request error is recorded and the loop continues. The
+second consecutive request error triggers automatic session compaction,
+resets the error counter, and then continues the loop. A successful
+response resets the consecutive error counter.
+
The loop adds temporary controller tools to the session:
• ‘agent_submit_plan’ records the initial checklist before acting
@@ -934,6 +964,12 @@ the file is written. A failing before hook blocks the
edit. After
hooks run after a successful write; failure is reported to the agent and
does not roll back the edit.
+Hook processes are started asynchronously, so long-running hooks do not
+block the Emacs UI. They are still blocking from the agent's point of
+view: the edit tool callback runs only after all relevant before/after
+hooks finish, and the agent receives the final hook status together with
+the edit result.
+
Example project-local configuration:
((nil . ((ellama-tools-edit-before-shell-commands
@@ -1022,6 +1058,11 @@ Key settings:
findings in ‘enforce’ mode (‘allow’, ‘warn’, ‘block’, ‘redact’).
• ‘ellama-tools-dlp-output-warn-behavior’: Handling for output ‘warn’
verdicts (‘allow’, ‘confirm’, or ‘block’).
+ • ‘ellama-tools-dlp-safe-read-file-regexps’: Canonical file-name
+ regexps whose file-reading outputs skip output DLP scans. This is
+ for trusted source files that should not prompt on every agent
+ read. It does not bypass input DLP, non-read tool output DLP,
+ irreversible checks, ‘srt’ checks, or line-budget truncation.
• ‘ellama-tools-dlp-policy-overrides’: Per-tool/per-arg overrides and
exceptions. For structured input args, nested string values are
scanned with path-like arg names (for example
@@ -1066,6 +1107,24 @@ Key settings:
overflowing output to a temp file when the output source file is
unknown (default ‘t’).
+Trusted read-file outputs:
+
+‘ellama-tools-dlp-safe-read-file-regexps’ lets users mark known source
+files as safe for output DLP. By default, Ellama marks its own loaded
+‘ellama*.el’ source files safe, so autonomous agents can inspect Ellama
+internals without repeated DLP approval prompts. The match is performed
+against the canonical file name. Only output scans for file-reading
+tools are skipped; DLP still scans tool inputs and outputs from other
+tools.
+
+Example:
+
+ (setopt ellama-tools-dlp-safe-read-file-regexps
+ (list (concat "\\`"
+ (regexp-quote
+ (file-truename "/path/to/ellama/"))
+ "ellama\\(?:-[[:alnum:]-]+\\)?\\.el\\'")))
+
Enforcement behavior (v1):
• input ‘block’ prevents tool execution
@@ -2039,6 +2098,12 @@ part of GNU ELPA; major contributions must be from
someone with FSF
papers. Alternatively, you can write a module and share it on a
different archive like MELPA.
+For local validation, run ‘make check-elisp’ before pushing Elisp
+changes. It formats Elisp files, byte-compiles, runs the ERT suite,
+native-compiles, and runs checkdoc. Byte and native compilation
+warnings are treated as failures, so warnings block the same way test
+failures do.
+
File: ellama.info, Node: GNU Free Documentation License, Prev:
Contributions, Up: Top
@@ -2529,45 +2594,45 @@ Node: Installation3973
Node: Commands8987
Node: Keymap17925
Node: Configuration20812
-Node: Session Provider Keys33634
-Node: Session Compaction35495
-Node: Image Input37789
-Node: Task Tool Subagents39934
-Node: Plan-and-Act Agent Loop42664
-Node: Edit Tool Shell Hooks44848
-Node: DLP for Tool Input/Output46836
-Node: SRT Filesystem Policy for Tools61740
-Node: Context Management67409
-Node: Transient Menus for Context Management68477
-Node: Managing the Context70156
-Node: Considerations70931
-Node: Minor modes71524
-Node: ellama-context-header-line-mode73512
-Node: ellama-context-header-line-global-mode74337
-Node: ellama-context-mode-line-mode75057
-Node: ellama-context-mode-line-global-mode75905
-Node: Ellama Session Header Line Mode76609
-Node: Enabling and Disabling77178
-Node: Customization77625
-Node: Ellama Session Mode Line Mode77913
-Node: Enabling and Disabling (1)78498
-Node: Customization (1)78945
-Node: Using Blueprints79239
-Node: Key Components of Ellama Blueprints79879
-Node: Creating and Managing Blueprints80486
-Node: Blueprints files81464
-Node: Variable Management81885
-Node: Keymap and Mode82338
-Node: Transient Menus83274
-Node: Running Blueprints programmatically83820
-Node: MCP Integration84407
-Node: Agent Skills85642
-Node: Directory Structure86005
-Node: Creating a Skill87032
-Node: How it works87407
-Node: Acknowledgments87798
-Node: Contributions88509
-Node: GNU Free Documentation License88895
+Node: Session Provider Keys34578
+Node: Session Compaction36439
+Node: Image Input38733
+Node: Task Tool Subagents40878
+Node: Plan-and-Act Agent Loop44052
+Node: Edit Tool Shell Hooks46633
+Node: DLP for Tool Input/Output48926
+Node: SRT Filesystem Policy for Tools64925
+Node: Context Management70594
+Node: Transient Menus for Context Management71662
+Node: Managing the Context73341
+Node: Considerations74116
+Node: Minor modes74709
+Node: ellama-context-header-line-mode76697
+Node: ellama-context-header-line-global-mode77522
+Node: ellama-context-mode-line-mode78242
+Node: ellama-context-mode-line-global-mode79090
+Node: Ellama Session Header Line Mode79794
+Node: Enabling and Disabling80363
+Node: Customization80810
+Node: Ellama Session Mode Line Mode81098
+Node: Enabling and Disabling (1)81683
+Node: Customization (1)82130
+Node: Using Blueprints82424
+Node: Key Components of Ellama Blueprints83064
+Node: Creating and Managing Blueprints83671
+Node: Blueprints files84649
+Node: Variable Management85070
+Node: Keymap and Mode85523
+Node: Transient Menus86459
+Node: Running Blueprints programmatically87005
+Node: MCP Integration87592
+Node: Agent Skills88827
+Node: Directory Structure89190
+Node: Creating a Skill90217
+Node: How it works90592
+Node: Acknowledgments90983
+Node: Contributions91694
+Node: GNU Free Documentation License92368
End Tag Table
