Troubleshooting Guide

Problem: The melpazoid job fails with errors like:

Opening input file: No such file or directory, /workspace/pkg/prompts/system.org

Cause: MELPA-style packaging copies only files matched by the recipe. Magent needs every production library plus bundled runtime data after packaging.

Solution: Keep .github/workflows/melpazoid.yml aligned with this recipe shape:

(magent :fetcher github :repo "Jamie-Cui/magent"
        :files ("lisp/magent*.el" "prompts" "skills" "capabilities"))

The explicit glob supplies every production Elisp file. The explicit directories supply runtime data that the package loads by relative path. Keep ERT sources under test/ so they remain outside the production package, and keep the recipe aligned with source-files.txt and prompts/manifest.txt.

Problem: melpazoid reports:

Package-Requires outside the main file have no effect.

Solution: Keep Package-Requires only in magent.el and mirror it in magent-pkg.el. Secondary modules should declare normal (require ...) dependencies in code, but not package headers.

Problem: melpazoid reports license unknown for module files.

Solution: Ensure every Elisp source has a formal license header or an SPDX line, for example:

;; SPDX-License-Identifier: GPL-3.0-or-later

Problem: test.yml fails in Run live smoke tests with:

Magent live loop tool turn did not finish

Cause: CI runners can be slower than a local daemon when timers, tool callbacks, and UI rendering all run in one live Emacs process.

Solution: Keep deterministic live smoke waits long enough for CI and avoid hard-coding local-machine timing assumptions. Reproduce with:

emacs --daemon=magent-ci
EMACSCLIENT="emacsclient -s magent-ci" make test-live-smoke
emacsclient -s magent-ci --eval '(kill-emacs)'

Problem: Magent requires gptel as a dependency.

Solution:

;; Install gptel from MELPA
(package-install 'gptel)

Problem: Warnings about undefined functions during compilation.

Solution: Ensure all dependencies are installed and in load-path:

make compile  # Auto-detects dependencies in ~/.emacs.d/elpa/

If dependencies live outside ~/.emacs.d/elpa/, pass the relevant Makefile variables explicitly, such as GPTEL_DIR, COMPAT_DIR, or YAML_DIR.

Problem: make test-live fails, times out, or reports an async timer error while using the real configured gptel provider.

Live debugging playbook:

1. Use an isolated Emacs server for Magent live tests. Do not debug against your main editing Emacs when a hang is possible.

   emacs --daemon=magent-live-test
   

2. Always point emacsclient or make at the isolated server:

   emacsclient -s magent-live-test --eval '(emacs-pid)'
   make EMACSCLIENT="emacsclient -s magent-live-test" test-live-smoke
   

3. Before every live run, force this checkout’s source to load and assert that ELPA Magent was not used:

   emacsclient -s magent-live-test --eval \
     '(progn
        (setq debug-on-error t)
        (load-file "/path/to/magent/test/magent-live-test.el")
        (magent-live-test-reload-source)
        (list :repo-source (magent-live-test--repo-source-summary)))'
   

   Every path in :repo-source must be under the checkout, for example /path/to/magent/lisp/magent.el, not under ~/.emacs.d/elpa/magent/.

4. Clear stale bytecode before batch or live verification. A warning like Source file ... newer than byte-compiled file; using older file means Emacs tested old code.

   make clean
   

5. Prefer async status files for real provider runs. They keep emacsclient responsive and preserve a compact state snapshot while the provider request continues:

   emacsclient -s magent-live-test --eval \
     '(progn
        (setq debug-on-error t)
        (load-file "/path/to/magent/test/magent-live-test.el")
        (magent-live-test-reload-source)
        (magent-live-test-install-trace "/tmp/magent-live-trace.el")
        (magent-live-test-run-async
         (quote magent-live-test-real-emacs-eval-tool)
         "/tmp/magent-live-tool-final.el"))'
   
   cat /tmp/magent-live-tool-final.el
   tail -n 80 /tmp/magent-live-trace.el
   

6. Check the diagnostic buffers in the isolated server while the test is running and after it finishes:

   • *Messages*
   • *Backtrace*
   • *magent-live-test-log*
   • *gptel-log*

   Treat *gptel-log* as sensitive. Redact API keys, bearer tokens, request headers, and provider-specific secrets before sharing or committing any excerpts.

7. If the isolated Emacs server becomes unresponsive, interrupt or kill only that server. Do not kill the main Emacs process.

   emacsclient -s magent-live-test --eval '(kill-emacs 0)'
   

   If the client cannot connect, identify the emacs --daemon=magent-live-test PID and kill that PID only.

Diagnosis:

1. Enable backtraces in the live Emacs session before reproducing:

   (setq debug-on-error t)
   

2. Re-run the failing live test from emacsclient or make test-live.
3. While the run is active and immediately after it finishes, inspect:
   • *Messages* for timer, process filter, and byte-code errors
   • *Backtrace* when debug-on-error opens one
   • *magent-log* or the test-local *magent-live-test-log*
   • *gptel-log* for provider/request failures; redact API keys or headers before sharing

4. For a single real tool test, reload the live suite and run:

   (progn
     (load-file "/path/to/magent/test/magent-live-test.el")
     (setq debug-on-error t)
     (magent-live-test-run 'magent-live-test-real-emacs-eval-tool))
   

Solution:

• Fix the first concrete error in *Backtrace* or *Messages*, then re-run the single failing live test before running the whole live suite.
• Treat *gptel-log* as sensitive diagnostic material; summarize it or share only redacted snippets.

Failure signatures from prior live debugging:

• If a tool continuation hangs after the first tool result, inspect /tmp/magent-live-trace.el. A gptel-curl-get-args :event enter with no matching :event leave usually means gptel hit a serialization error before curl started. Check tool-call names, tool args, and assistant tool_calls history for Lisp symbols or non-JSON-safe values.
• If the first provider request emits a tool call but the second request never starts, check whether Magent recorded the tool result in the session and rebuilt the continuation prompt via magent-agent-loop-request-for-current-session.
• If the continuation completes without assistant text, inspect the turn result for (:reason empty-completion). Magent does not issue a recovery request; reasoning-only content remains separate from assistant text.
• If the second request completes but agent-shell omits the final assistant text, remember that tool-enabled requests may be non-streaming. A non-streaming string callback can be the final completion, not a text delta; verify the ACP observer emitted the corresponding agent-shell update.
• If a live smoke test passes in direct emacsclient but make test-live-smoke fails, confirm EMACSCLIENT="emacsclient -s magent-live-test" is set. The Makefile default may target the main Emacs server.
• If a test unexpectedly loads an older Magent, check load-history, load-path ordering, and .elc files. test/magent-live-test.el uses source loading with nosuffix; keep that behavior when adding files to the live reload list.

Known-good verification sequence after fixing live gptel/tool bugs:

make clean
make test-unit
make compile
make clean
make EMACSCLIENT="emacsclient -s magent-live-test" test-live-smoke

Then run both real async diagnostics in the isolated daemon:

(magent-live-test-run-async 'magent-live-test-real-simple-prompt
                            "/tmp/magent-live-simple-final.el")
(magent-live-test-run-async 'magent-live-test-real-emacs-eval-tool
                            "/tmp/magent-live-tool-final.el")

Expected final status files include :status passed, :repo-source paths under the checkout, and for the tool test a tool state like (:name "emacs_eval" :result "42") plus final assistant text MAGENT_TOOL_OK=42.

Problem: Request hangs or times out.

Diagnosis:

1. Open *magent-log* directly with C-x b and inspect the latest entries.

2. Verify gptel configuration:

   gptel-model      ; Should show your model
   gptel-api-key    ; Should show your key
   

3. Test gptel directly: M-x gptel

Solution:

• Increase timeout: (setq magent-request-timeout 300)
• Check network/proxy settings
• Verify API key is valid

Problem: Tool calls return errors.

Diagnosis:

1. Check *magent-log* for error details
2. Verify tool is enabled: magent-enable-tools
3. Run M-x magent-list-agents and verify the current agent-shell session mode.

Solution:

• For bash: Verify Bash is installed and magent-bash-program resolves to it. Commands run without errexit and with pipefail. Use && or explicit set -e when fail-fast sequencing is required. Output-limiting pipelines such as rg ... | head can fail on SIGPIPE; prefer native limit options.
• For emacs_eval: Check for syntax errors
• For grep: Verify ripgrep is installed: which rg

Problem: A child-agent task does not behave like a durable job that can be messaged, waited on, listed, or closed.

Diagnosis:

1. Check whether the code path uses the lifecycle tools: spawn_agent, send_agent_message, wait_agent, list_agents, and close_agent.
2. Review docs/AGENT_JOBS.org for the child-agent/job lifecycle contract.
3. Inspect compact child-agent updates in the agent-shell buffer and verify the persisted agent-jobs data in the parent session.
4. Check *magent-log* for nested request or tool-call errors.
5. After resume, confirm the parent session still has the expected job metadata in agent-jobs.

Solution:

• Add or update tests around job status, transcript/result storage, parent/child session links, and resume restoration.
• Do not add sandbox-specific checks as part of this workflow fix.

Problem: Tool execution blocked by permissions.

Diagnosis: Run M-x magent-list-agents to inspect agent profiles and verify the current agent-shell session mode.

Solution:

• Temporarily bypass: M-x magent-toggle-bypass-permission
• Or customize: (setq magent-bypass-permission t)
• Or switch agent with M-x agent-shell-set-session-mode in the agent-shell buffer and select one with appropriate permissions.

Problem: Session state lost between Emacs restarts.

Diagnosis: Check session directory exists and is writable:

magent-session-directory  ; Default: ~/.emacs.d/magent/sessions/

Solution:

;; Ensure directory exists
(make-directory magent-session-directory t)

Problem: Streaming appears stuck.

Diagnosis:

1. Check the request status in the agent-shell buffer.
2. Check *Messages* buffer for errors
3. Press C-c C-c in the agent-shell buffer and confirm the interrupt

Solution:

• Start a fresh session with M-x magent-agent-shell-start.
• Restart Emacs if issue persists

Problem: Response appears character-by-character.

Solution:

• Confirm that the installed agent-shell version satisfies README requirements.
• Reproduce in a fresh M-x magent-agent-shell-start buffer and inspect *Messages* and *magent-log* for update or rendering errors.

Problem: Emacs memory grows over time.

Solution:

;; Reduce history size
(setq magent-max-history 50)

Start a fresh conversation with M-x magent-agent-shell-start when the current session no longer needs to be retained in the active buffer.