diff options
| -rw-r--r-- | docs/design/2026-05-28-generic-agent-runtime-spec.org | 63 | ||||
| -rw-r--r-- | todo.org | 2 |
2 files changed, 41 insertions, 24 deletions
diff --git a/docs/design/2026-05-28-generic-agent-runtime-spec.org b/docs/design/2026-05-28-generic-agent-runtime-spec.org index 9b6d535..2172ef3 100644 --- a/docs/design/2026-05-28-generic-agent-runtime-spec.org +++ b/docs/design/2026-05-28-generic-agent-runtime-spec.org @@ -542,29 +542,46 @@ collide; helper-originated sends include the agent id in the slug. *** Open issue: the Emacs launch surface — unresolved, blocks readiness -Craig works primarily inside Emacs, and sessions are born from more surfaces -than the =ai= script: an Emacs terminal buffer (eat/vterm — these run their -shells as children of the =emacs= process, with no separate emulator -process), a tmux pane viewed through Emacs, or a raw shell. Verified -2026-06-11: roster /detection/ is parent-agnostic — it matches on process -cwd, not ancestry, so an agent started inside an Emacs terminal is fully -visible to the scan. What's missing is the /deterministic spawn path/ on the -Emacs surface: the tmux-window mechanics of =ai --helper= don't apply inside -an Emacs buffer. - -To design before this spec is implementation-ready: - -- An elisp launch command (working name =ai-helper=) that does the same - (a) roster check, (b) id assignment + env export, (c) launch with the - helper-mode opener — inside an eat/vterm buffer, with a buffer-naming - convention standing in for tmux window names - (e.g. =*helper:rulesets:7f3a*=). -- Whether the existing Emacs entry points Craig actually uses to start - agents should call the =ai= script underneath (one implementation, two - surfaces) or reimplement the three steps in elisp (no tmux dependency - inside Emacs). Leaning toward shelling out to =ai= with a =--no-tmux= - mode so the roster/id/instruction logic lives in exactly one place. -- The =emacs.md= live-reload discipline applies to whatever elisp ships. +Corrected 2026-06-12 after reading the actual config (the first draft of +this subsection assumed eat/vterm and was wrong). The facts, verified in +=~/.emacs.d/modules/=: + +- The Emacs terminal is *ghostel* (a native Emacs emulator over + libghostty-vt, the Ghostty engine) — =term-config.el=. Generic ghostel + buffers auto-launch tmux inside themselves (=cj/term-launch-tmux=). +- The Emacs AI launch surface already exists: *ai-term.el* (the F9 flow). + It picks a project by the same =.ai/protocols.org= fingerprint, creates a + project-named tmux session (=aiv-<basename>=), attaches a ghostel buffer + to it, and sends the agent's startup instruction. Its picker already + tracks session liveness (=[running]= / =[detached]= badges, crash + recovery by matching surviving =aiv-= tmux sessions back to projects). + +So Emacs-born agents are /tmux/ sessions viewed through ghostel — the same +process shape as shell-launched =ai= sessions, which makes roster detection +uniform across both surfaces (claude is a child of the tmux server either +way, and the scan matches on cwd regardless). The earlier idea of an +=ai --no-tmux= mode is retired: there is no tmux-less Emacs path to serve. + +What remains to design — the integration, not a new surface: + +- =ai-term.el='s session-create step learns the same three-step spawn: + run =agent-roster= for the picked project, export =AI_AGENT_ID= / + =AI_HELPER= into the tmux session when a live agent exists, and send the + helper-mode opener instead of the primary startup instruction. +- The picker badges grow a =[helper]= state alongside =[running]= / + =[detached]=, so picking a project that already has a live agent shows + what the new session will become before it's created. +- Division of labor: =agent-roster= (the shared script) is the single + detection implementation; =ai-term.el= and =bin/ai= each do their own + id/export/opener wiring on top of it. Whether =ai-term.el= shells out to + =bin/ai= wholesale or just to =agent-roster= is the remaining call — + ai-term owns tmux session naming (=aiv-= prefix) and window placement + that =bin/ai= knows nothing about, which argues for sharing only the + roster. +- The =emacs.md= live-reload discipline applies to the ai-term.el changes, + and the change lands in the =~/.emacs.d= project (its own repo and + session scope — a cross-project handoff from rulesets, not a rulesets + edit). *** Helper startup and wrap-up @@ -45,7 +45,7 @@ Cancelled 2026-06-11: Craig confirmed the decision — one todo queue with a sin :CREATED: [2026-06-11 Thu] :LAST_REVIEWED: 2026-06-11 :END: -BLOCKED ON SPEC READINESS (Craig, 2026-06-11): the spec is marked NOT IMPLEMENTATION-READY after four same-day design revisions. Before any build — design the Emacs launch surface (elisp launch command or ai --no-tmux; detection already covers Emacs-born agents, spawn does not), write the three-ring test gating into the implementation plan (bats → sandbox drills → pilot project, dormant-by-construction so template sync can't put it live early), and re-read the whole helper section for seams. Then implement. +BLOCKED ON SPEC READINESS (Craig, 2026-06-11): the spec is marked NOT IMPLEMENTATION-READY after four same-day design revisions. Before any build — finish the Emacs integration design (corrected 2026-06-12: the surface is ghostel + ai-term.el's F9 flow, which already creates project-named aiv- tmux sessions; integration = teach ai-term.el's session-create the roster→export→opener steps and add a [helper] picker badge; the ai-term.el change is a cross-project handoff to ~/.emacs.d, not a rulesets edit), write the three-ring test gating into the implementation plan (bats → sandbox drills → pilot project, dormant-by-construction so template sync can't put it live early), and re-read the whole helper section for seams. Then implement. Implement Phase 1.5 of the generic-agent-runtime spec ([[file:docs/design/2026-05-28-generic-agent-runtime-spec.org][spec]], amended 2026-06-11 with the "Concurrent same-project agents" section). Craig's case: spawn a second Claude in the same project to look things up or update tasks safely while the primary works. The session-context split (AI_AGENT_ID + session-context.d/) already shipped; this builds the rest: |