xtralab 0.15.0 → 0.15.2

package/lib/terminals/model.js

@@ -1,66 +1,19 @@
 import { Poll } from '@lumino/polling';
 import { Signal } from '@lumino/signaling';
 import { fetchRunningAgents } from './detection';
-/**
- * How often to ask the server which agent (if any) is running in each
- * terminal. Snappy enough that a manually-started agent's logo shows up
- * within a few seconds, light enough that walking the shells' process trees
- * stays negligible.
- */
 const DETECT_POLL_INTERVAL_MS = 3000;
-/**
- * Upper bound on the exponential backoff when detection fails repeatedly
- * (e.g. the endpoint is missing on an older server). Matches the rest of the
- * plugin's polls.
- */
 const DETECT_POLL_MAX_MS = 300000;
 /**
- * Grace window after a session first appears during which an optimistic
- * launch tag outranks a `null` detection result. It covers the gap between
- * issuing an agent's command and its process actually being spawnable, so the
- * freshly-launched logo doesn't blink off if a detection poll lands in that
- * sliver. Comfortably longer than a cold agent start; short enough that a tag
- * for an agent that never really started clears quickly.
+ * Window during which a fresh launch tag outranks a `null` detection result:
+ * covers the gap between launching an agent and its process becoming visible.
  */
 const LAUNCH_GRACE_MS = 4000;
-/**
- * How often to re-read each open coding-agent terminal's output buffer to
- * refresh the "latest activity" line shown under its row. Brisk enough to feel
- * live while an agent works, cheap because it only walks the last screenful of
- * a handful of terminals and emits only when a line actually changes.
- */
 const ACTIVITY_POLL_INTERVAL_MS = 1500;
 /**
- * Source-of-truth model for the running-terminals panel. Each running
- * terminal session known to the server is one entry; the registry caches
- * the last `widget.title.label` we observed so the agent name (or any
- * xterm-published title) survives the user closing the tab while the
- * session continues running on the backend.
- *
- * For sessions running a coding agent it also surfaces a *latest activity*
- * line — the freshest meaningful line of the terminal's output, read from the
- * open tab's xterm buffer on a poll (see {@link activityFor}) — so each row
- * shows what its agent is doing, not just its name.
- *
- * It also resolves *which agent is running* in each session, so the panel can
- * badge rows with the agent's logo. Two inputs feed that, reconciled by
- * {@link agentCommandFor}:
- *   - an optimistic launch tag ({@link IAgentSessions}) written when we start
- *     an agent ourselves — instant, but blind to the agent later exiting; and
- *   - authoritative server-side process detection, polled here, which works
- *     for hand-started agents too and clears once an agent exits.
- *
- * Upstream session signals:
- *   - `serviceManager.terminals.runningChanged` is the authoritative
- *     list of live sessions; everything not in it has been shut down
- *     server-side and we must drop it.
- *   - `tracker.widgetAdded` plus the per-widget `title.changed` /
- *     `disposed` signals keep our label cache in sync with whatever
- *     xterm/the launcher has set on the open tabs.
- *
- * `stateChanged` is emitted for every kind of update; the panel hooks it
- * through a `UseSignal` so a single subscription re-renders the list on
- * any change.
+ * Source-of-truth model for the running-terminals panel: live sessions,
+ * labels cached across tab closes, agent badges (launch tags reconciled with
+ * polled detection, see {@link agentCommandFor}), and per-row latest-activity
+ * lines. `stateChanged` fires on every kind of update.
  */
 export class SessionRegistry {
     constructor(options) {
@@ -86,17 +39,8 @@ export class SessionRegistry {
         this._tracker.widgetAdded.connect(this._onWidgetAdded, this);
         this._tracker.forEach(widget => this._trackWidget(widget));
         this._refreshLive();
-        // Track which terminal is the current widget in the main area so the panel
-        // can highlight its row — and highlight nothing while a notebook or any
-        // other non-terminal tab is current instead. `currentChanged` is optional
-        // on the shell interface (not every shell can switch focus), so guard it;
-        // when it is absent the highlight stays off.
         (_f = (_e = this._shell) === null || _e === void 0 ? void 0 : _e.currentChanged) === null || _f === void 0 ? void 0 : _f.connect(this._onShellCurrentChanged, this);
         this._updateCurrent();
-        // A freshly written launch tag should re-render the panel immediately
-        // (show the logo) and again once the grace window closes (so a tag for
-        // an agent that never started, or that detection later contradicts,
-        // doesn't linger).
         (_g = this._agentSessions) === null || _g === void 0 ? void 0 : _g.changed.connect(this._onTagChanged, this);
         this._poll = new Poll({
             name: '@xtralab/terminals:runningAgents',
@@ -108,10 +52,8 @@ export class SessionRegistry {
             },
             standby: 'when-hidden'
         });
-        // A second, faster poll reads the live output buffer of each open
-        // coding-agent terminal to keep its "latest activity" line current. Kept
-        // separate from the detection poll so reading xterm buffers neither delays
-        // nor is delayed by the server round-trip that drives the agent badges.
+        // Separate from the detection poll so reading xterm buffers neither
+        // delays nor is delayed by the server round-trip.
         this._activityPoll = new Poll({
             name: '@xtralab/terminals:activity',
             factory: () => this._refreshActivity(),
@@ -120,19 +62,19 @@ export class SessionRegistry {
         });
     }
     /**
-     * Emitted whenever the live session list, a cached label, or the detected
-     * running agent changes.
+     * Emitted on any change to the session list, labels, badges, or activity.
      */
     get stateChanged() {
         return this._stateChanged;
     }
+    /**
+     * Whether the registry has been disposed.
+     */
     get isDisposed() {
         return this._isDisposed;
     }
     /**
-     * Names of all live sessions, ordered by their stable rank so the
-     * rendered list keeps a consistent order (roughly creation order) as
-     * new sessions are added and old ones shut down.
+     * Names of all live sessions in stable (roughly creation) order.
      */
     sessionNames() {
         const names = Array.from(this._live);
@@ -140,22 +82,16 @@ export class SessionRegistry {
         return names;
     }
     /**
-     * True iff the named session is still on the server. Used by the panel
-     * to skip a row during the brief window between the session's shutdown
-     * and the next `runningChanged` arriving.
+     * True iff the named session is still on the server.
      */
     has(name) {
         return this._live.has(name);
     }
     /**
-     * Display name for the session. The cache wins because it only
-     * holds "real" labels (the launcher's agent name or an xterm escape
-     * sequence — see `_cacheLabel` for the filter); reading it first
-     * prevents the transient `Terminal {name}` an XTerm widget shows
-     * during reconnect from flickering into the panel. The live widget
-     * title is used when no cache exists, and the `Terminal {name}`
-     * fallback covers sessions we have never seen a widget for (e.g.
-     * surviving a lab reload).
+     * Display name for the session. The cache wins — it holds only "real"
+     * labels (see `_cacheLabel`), so the transient `Terminal {name}` an xterm
+     * widget shows during reconnect never flickers into the panel; the final
+     * fallback covers sessions never seen with a widget (e.g. a lab reload).
      */
     labelFor(name) {
         const cached = this._labels.get(name);
@@ -169,18 +105,10 @@ export class SessionRegistry {
         return `Terminal ${name}`;
     }
     /**
-     * An identifier for the agent running in the session — its configured
-     * command, or its canonical id when detection matched the spawned process by
-     * id rather than by an aliased command — or `null` if none. Callers resolve
-     * it to a logo through the plugin's `iconForCommand`, which accepts either.
-     *
-     * Server-side detection is authoritative whenever it reports a running
-     * agent. A launch tag fills two gaps: the startup grace window right after
-     * we launch an agent (so its logo shows before its process is detectable),
-     * and any time detection is unavailable (older server, transient error).
-     * Once the grace window has passed and detection has reported the session
-     * as idle, the tag is ignored — that is how the badge clears when an agent
-     * exits.
+     * Agent identifier for the session (configured command or canonical id), or
+     * `null`. Detection wins when it reports an agent; a launch tag fills the
+     * grace window and detection outages, and is ignored once detection says
+     * idle — that is how the badge clears when an agent exits.
      */
     agentCommandFor(name) {
         var _a, _b, _c;
@@ -203,26 +131,18 @@ export class SessionRegistry {
         return null;
     }
     /**
-     * The agent command server-side detection currently reports for the
-     * session, or `null` when it has not confirmed one (the session is idle,
-     * not yet covered by a poll, or detection is unavailable). Unlike
-     * {@link agentCommandFor} this never falls back to the optimistic launch
-     * tags: callers about to *write into* a session use it, and text must only
-     * ever be sent to a confirmed running agent — pasted into a shell prompt it
-     * would be executed.
+     * The agent command detection currently confirms for the session, or
+     * `null`. Never falls back to launch tags: callers about to *write into* a
+     * session use it, and text pasted into a shell prompt would be executed.
      */
     detectedCommandFor(name) {
         const detected = this._detected.get(name);
         return typeof detected === 'string' ? detected : null;
     }
     /**
-     * The most recent meaningful line of output from the session's terminal, or
-     * `null` when there is nothing to surface — no coding agent is running in the
-     * session, its tab is closed (so there is no live buffer to read), or the
-     * buffer holds only the agent's input box and chrome. Refreshed on a poll by
-     * {@link _refreshActivity}; shown as a smaller line under the row's title.
-     * Always `null` while the activity line is disabled (see
-     * {@link setActivityEnabled}).
+     * The most recent meaningful line of the session's output, or `null` when
+     * nothing qualifies (no running agent, closed tab, chrome-only buffer, or
+     * the activity line is disabled).
      */
     activityFor(name) {
         var _a;
@@ -232,11 +152,8 @@ export class SessionRegistry {
         return (_a = this._activity.get(name)) !== null && _a !== void 0 ? _a : null;
     }
     /**
-     * Turn the per-row latest-activity line on or off, driven by the
-     * `xtralab:terminals` `showAgentActivity` setting. When turned off the
-     * activity poll stops reading terminal buffers and any cached lines are
-     * dropped, so rows fall back to their title alone; when turned back on the
-     * lines are repopulated on the spot. A no-op when the value is unchanged.
+     * Turn the per-row activity line on or off (the `showAgentActivity`
+     * setting). Off drops cached lines; on repopulates them on the spot.
      */
     setActivityEnabled(enabled) {
         if (enabled === this._activityEnabled) {
@@ -244,8 +161,6 @@ export class SessionRegistry {
         }
         this._activityEnabled = enabled;
         if (enabled) {
-            // Repopulate immediately rather than waiting for the next poll tick;
-            // `_refreshActivity` emits `stateChanged` if it finds anything to show.
             void this._refreshActivity();
         }
         else {
@@ -254,30 +169,22 @@ export class SessionRegistry {
         }
     }
     /**
-     * Return the open widget for a session, if any. The panel uses this to
-     * switch behavior between "activate existing tab" and "open a new tab
-     * connected to the live session".
+     * The open widget for a session, if any.
      */
     widgetFor(name) {
         var _a;
         return ((_a = this._tracker.find(widget => widget.content.session.name === name)) !== null && _a !== void 0 ? _a : null);
     }
     /**
-     * Session name of the terminal that is currently the active widget in the
-     * shell's main area, or `null` when that widget is not a terminal (for
-     * example a notebook or text editor is current). The panel uses this to
-     * highlight the current terminal's row — mirroring how the file browser
-     * surfaces the open document — and to leave every row unhighlighted while a
-     * non-terminal tab is current.
+     * Session name of the terminal that is the shell's current main-area
+     * widget, or `null` when the current widget is not a terminal.
      */
     currentSessionName() {
         return this._currentName;
     }
     /**
-     * Stable per-session rank assigned in observation order. Used to keep
-     * the rendered list in a steady order so rows don't reshuffle as
-     * sessions come and go. Cleaned up when the session is shut down so the
-     * counter does not grow without bound across long sessions.
+     * Stable per-session rank in observation order, so rows don't reshuffle as
+     * sessions come and go.
      */
     rankFor(name) {
         let rank = this._ranks.get(name);
@@ -287,6 +194,9 @@ export class SessionRegistry {
         }
         return rank;
     }
+    /**
+     * Dispose of the registry's polls and signal connections.
+     */
     dispose() {
         var _a, _b, _c;
         if (this._isDisposed) {
@@ -314,17 +224,13 @@ export class SessionRegistry {
         this._stateChanged.emit();
     }
     /**
-     * Adopt `next` as the live set and prune every per-session map for
-     * sessions that have gone away — labels, ranks, first-seen timestamps,
-     * detection results, and the shared launch tag. Without this the maps (and
-     * the rank counter) would grow without bound as terminals come and go.
+     * Adopt `next` as the live set and prune every per-session map, so the
+     * maps and rank counter don't grow without bound.
      */
     _reconcileLive(next) {
         var _a;
-        // Names we had already seen, captured before we prune below — the set of
-        // candidates whose launch tag may now need forgetting. (The tag map is
-        // not enumerable, so we drive the prune from the sessions we know about;
-        // `_firstSeen` has an entry for every session that has ever been live.)
+        // The tag map is not enumerable, so the tag prune below is driven from
+        // `_firstSeen`, which has an entry for every session ever live.
         const known = Array.from(this._firstSeen.keys());
         for (const name of next) {
             if (!this._firstSeen.has(name)) {
@@ -357,10 +263,8 @@ export class SessionRegistry {
                 this._activity.delete(name);
             }
         }
-        // Forget launch tags for sessions that have gone away. This matters for
-        // correctness as well as bookkeeping: terminado reuses session names, so
-        // a stale tag could otherwise mislabel a brand-new terminal that happens
-        // to reuse a closed session's name.
+        // terminado reuses session names, so a stale tag could mislabel a
+        // brand-new terminal that reuses a closed session's name.
         for (const name of known) {
             if (!next.has(name)) {
                 (_a = this._agentSessions) === null || _a === void 0 ? void 0 : _a.delete(name);
@@ -368,9 +272,8 @@ export class SessionRegistry {
         }
     }
     /**
-     * Poll body: ask the server which agent runs in each terminal and update
-     * the detection map. On failure we keep the previous results rather than
-     * clearing them, so a transient error doesn't strip every badge.
+     * Poll body: update the detection map from the server. On failure the
+     * previous results are kept, so a transient error doesn't strip every badge.
      */
     async _refreshDetection() {
         const commands = this._detectCommands();
@@ -397,15 +300,9 @@ export class SessionRegistry {
         }
     }
     /**
-     * Poll body: re-read the buffer of each open coding-agent terminal and cache
-     * its latest meaningful line of output. Only sessions that have a running
-     * *agent* (not an editor) and an open tab qualify — a closed tab has no live
-     * buffer, editors run full-screen UIs that are not "activity", and plain
-     * shells would only echo their prompt. While a tab is reopening (its xterm
-     * is not ready yet) any existing line is kept; once the buffer is readable
-     * but has nothing worth showing the line is dropped, so a screen the agent
-     * has cleared doesn't leave a frozen line behind. Cached lines for sessions
-     * that no longer qualify are pruned. Emits only when something changed.
+     * Poll body: cache the latest meaningful output line of each open agent
+     * terminal (closed tabs have no live buffer; editors and shells don't
+     * qualify). Emits only when something changed.
      */
     async _refreshActivity() {
         if (!this._activityEnabled) {
@@ -425,8 +322,8 @@ export class SessionRegistry {
             qualifying.add(name);
             const term = widget.content._term;
             if (!term) {
-                // The tab is reopening and its xterm is not ready; keep any existing
-                // line until the buffer can be read again.
+                // The tab is reopening; keep any existing line until its xterm buffer
+                // is readable again.
                 continue;
             }
             const line = Private.readActivity(term);
@@ -437,8 +334,8 @@ export class SessionRegistry {
                 }
             }
             else if (this._activity.delete(name)) {
-                // Readable buffer with nothing to surface (e.g. the agent cleared its
-                // screen) — drop the now-stale line instead of freezing it.
+                // Readable buffer with nothing to surface (e.g. a cleared screen) —
+                // drop the stale line instead of freezing it.
                 changed = true;
             }
         }
@@ -454,8 +351,8 @@ export class SessionRegistry {
     }
     _onTagChanged() {
         this._stateChanged.emit();
-        // Re-render once the grace window closes so a tag that detection never
-        // confirmed (or has since contradicted) stops being shown.
+        // Re-emit once the grace window closes so a tag detection never confirmed
+        // (or has since contradicted) stops being shown.
         setTimeout(() => {
             if (!this._isDisposed) {
                 this._stateChanged.emit();
@@ -470,10 +367,8 @@ export class SessionRegistry {
         this._updateCurrent();
     }
     /**
-     * Recompute which terminal (if any) is the active main-area widget and emit
-     * only when it changes. The terminal tracker tells us whether the shell's
-     * current widget is one of our terminals; anything else — a notebook, an
-     * editor, or nothing — clears the highlight.
+     * Recompute which terminal (if any) is the active main-area widget; emits
+     * only on change. Anything not a tracked terminal clears the highlight.
      */
     _updateCurrent() {
         var _a, _b;
@@ -506,16 +401,10 @@ export class SessionRegistry {
         this._stateChanged.emit();
     }
     /**
-     * Update the cached label for a session, but only when the new
-     * label is "real" — non-empty and not one of the transient defaults
-     * the XTerm widget cycles through during reconnect (`'...'` while
-     * the websocket is opening, `'Terminal {name}'` once
-     * `_initialConnection` fires). Without the filter, briefly
-     * reopening a tab while an agent has yet to re-emit its xterm
-     * title escape sequence would clobber the cached agent name with
-     * `Terminal 1`. Live widget titles still display whatever the widget
-     * currently holds because `labelFor` consults the widget first;
-     * the filter only affects what survives a tab close.
+     * Cache a label only when it is "real" — not `'...'` or `Terminal {name}`,
+     * the transient defaults xterm cycles through during reconnect. Without the
+     * filter, reopening a tab before the agent re-emits its title escape would
+     * clobber the cached agent name.
      */
     _cacheLabel(name, label) {
         if (!label) {
@@ -527,11 +416,8 @@ export class SessionRegistry {
         this._labels.set(name, label);
     }
     _onWidgetDisposed(widget) {
-        // The widget is gone but the session may still be running on the
-        // server — keep the cached label so the panel keeps the agent's name
-        // when the user reopens the tab. We only clean up our subscriptions
-        // here; the cache is purged by `runningChanged` once the session
-        // itself goes away.
+        // The session may still be running on the server; the cached label stays
+        // until `runningChanged` purges it with the session itself.
         this._untrackWidget(widget);
         this._stateChanged.emit();
     }
@@ -539,8 +425,7 @@ export class SessionRegistry {
 var Private;
 (function (Private) {
     /**
-     * Value-equality for two detection maps, so a poll that changes nothing
-     * doesn't trigger a re-render.
+     * Whether two detection maps hold identical entries.
      */
     function detectedEqual(a, b) {
         if (a.size !== b.size) {
@@ -554,33 +439,21 @@ var Private;
         return true;
     }
     Private.detectedEqual = detectedEqual;
-    /**
-     * Rows above the cursor to scan when looking for the latest output.
-     */
     const ACTIVITY_SCAN_ROWS = 64;
-    /**
-     * Clamp for the activity string so one runaway block can't bloat a row.
-     */
     const ACTIVITY_MAX_LENGTH = 160;
     /**
-     * Horizontal box-drawing / rule characters, treated as blanks when
-     * sanitizing. Agents pad a status line or draw a separator with these (e.g.
-     * `Worked for 1m 06s ────`), which is chrome, not text. Vertical bars are
-     * deliberately excluded — {@link isMeaningfulActivity} relies on them to
-     * recognise (and skip) the contents of an input/quote box.
+     * Horizontal rule characters treated as blanks when sanitizing (status-line
+     * padding is chrome, not text). Vertical bars are excluded on purpose —
+     * {@link isMeaningfulActivity} uses them to skip input/quote boxes.
      */
     const RULE_CHARS = new Set([
         0x2500, 0x2501, 0x2504, 0x2505, 0x2508, 0x2509, 0x254c, 0x254d, 0x2550
     ]);
     /**
-     * The most recent meaningful line of agent output, or `null` if none is
-     * found. Agents park the cursor in an input box at the bottom of the screen,
-     * so the scan starts there and walks *up*, skipping that box, any hint or
-     * footer beneath it, blank lines and separators, until it reaches the block
-     * of real output nearest the input. It then rewinds to that block's first row
-     * and stitches the block back together (see {@link joinBlock}), so a reply
-     * the agent hard-wrapped across several rows reads as its opening sentence
-     * rather than the trailing fragment left next to the cursor.
+     * The most recent meaningful line of agent output, or `null`. Agents park
+     * the cursor in a bottom input box, so the scan walks *up* past chrome to
+     * the nearest output block, then rewinds to that block's first row so a
+     * hard-wrapped reply reads as its opening sentence, not a trailing fragment.
      */
     function readActivity(term) {
         var _a;
@@ -594,8 +467,6 @@ var Private;
             if (!isMeaningfulActivity(lineText(buffer, row))) {
                 continue;
             }
-            // `row` is the bottom of the output block nearest the input; walk up
-            // while rows stay meaningful to find the block's first row.
             let topRow = row;
             while (topRow > limit &&
                 isMeaningfulActivity(lineText(buffer, topRow - 1))) {
@@ -607,7 +478,7 @@ var Private;
     }
     Private.readActivity = readActivity;
     /**
-     * Sanitized text of one buffer row.
+     * Read a buffer row as sanitized text; empty when the row is missing.
      */
     function lineText(buffer, row) {
         var _a, _b;
@@ -615,10 +486,9 @@ var Private;
     }
     Private.lineText = lineText;
     /**
-     * Stitch rows `[topRow, lastRow]` of one output block into a single string,
-     * stopping once it is long enough to fill the row. A soft-wrapped row
-     * continues the previous one mid-word, so it is appended directly; a hard
-     * newline is a word boundary, so it is joined with a space.
+     * Stitch rows `[topRow, lastRow]` of one output block into a single string.
+     * A soft-wrapped row continues mid-word (appended directly); a hard newline
+     * is a word boundary (joined with a space).
      */
     function joinBlock(buffer, topRow, lastRow) {
         var _a;
@@ -648,9 +518,7 @@ var Private;
     }
     Private.clampActivity = clampActivity;
     /**
-     * Collapse a raw buffer row into displayable text: replace control characters
-     * and horizontal rule characters with spaces (so no escape sequence or drawn
-     * separator rides along), squeeze runs of whitespace, and trim.
+     * Replace control and rule characters with spaces and collapse whitespace.
      */
     function sanitizeActivity(value) {
         var _a;
@@ -664,18 +532,10 @@ var Private;
     }
     Private.sanitizeActivity = sanitizeActivity;
     /**
-     * Whether a sanitized row is worth showing as activity, i.e. real output
-     * rather than chrome. Doubles as the block-boundary test for
-     * {@link readActivity}'s walk up. A row is skipped when it:
-     *   - is blank or pure box-drawing (carries no letter or digit);
-     *   - begins with a vertical box-drawing bar (the contents of an input or
-     *     quote box), a prompt chevron (the input row and its ghost suggestion),
-     *     or Claude's tool-result / tip marker `⎿`; or
-     *   - is a transient status footer — one carrying a `for <time>` / `(<time>`
-     *     elapsed-time stamp, as agents print while and after they work
-     *     ("✻ Churned for 17s", "Working… (8s · …)", "— Worked for 1m 06s"). This
-     *     carries no real content, so skipping it lets the scan reach the reply
-     *     the agent wrote just above it.
+     * Whether a sanitized row is real output rather than chrome; doubles as
+     * {@link readActivity}'s block-boundary test. Skips rows without a letter
+     * or digit, rows starting with a box bar / prompt chevron / `⎿`, and
+     * elapsed-time status footers ("✻ Churned for 17s", "Working… (8s · …)").
      */
     function isMeaningfulActivity(text) {
         if (!text) {

package/lib/terminals/tokens.d.ts

@@ -10,15 +10,12 @@ export interface IAgentTerminalSession {
      */
     name: string;
     /**
-     * The agent identifier server-side detection reported for the session:
-     * the configured `command`, or the canonical agent `id` when the command
-     * is an alias (e.g. `ccm` spawning `claude`). Matches an `IAgent` by
-     * either field.
+     * The agent identifier detection reported: the configured `command`, or the
+     * canonical `id` when the command is an alias (e.g. `ccm` spawning `claude`).
      */
     command: string;
     /**
-     * Display label — the session's real title (the launcher's agent name, or
-     * whatever the running program published via an xterm escape sequence).
+     * Display label — the session's real (program-published) title.
      */
     label: string;
     /**
@@ -30,12 +27,9 @@ export interface IAgentTerminalSession {
 /**
  * Running agent terminals, and a way to send a prompt into one.
  *
- * `sessions` only lists sessions where server-side process detection has
- * *confirmed* a running coding agent (editors and plain shells are excluded,
- * as are optimistic just-launched tags): every listed session is one whose
- * TUI can meaningfully receive pasted prompt text. `sendPrompt` re-validates
- * against the server before writing, since pasting prose into a shell prompt
- * would execute it.
+ * Only sessions with a detection-*confirmed* running agent are listed — never
+ * optimistic launch tags: pasted prompt text must land in an agent's TUI, not
+ * a shell prompt where it would be executed.
  */
 export interface IAgentTerminals {
     /**
@@ -47,20 +41,15 @@ export interface IAgentTerminals {
      */
     readonly changed: ISignal<IAgentTerminals, void>;
     /**
-     * Paste `prompt` into the named session's terminal and press Enter.
-     *
-     * Delivery is deliberately background: the text is written straight to
-     * the session's websocket, bracketed-paste-wrapped so a multi-line prompt
-     * arrives as one block in the agent's input box, without revealing or
-     * focusing the terminal's tab — the user keeps working where they are,
-     * and the agent CLIs queue the prompt themselves when they are busy.
-     * Rejects when the session is gone or no agent is running in it anymore.
+     * Paste `prompt` (bracketed-paste-wrapped) into the named session and press
+     * Enter, writing straight to its websocket without revealing or focusing
+     * its tab. Rejects when the session is gone or no agent runs in it anymore.
      */
     sendPrompt(name: string, prompt: string): Promise<void>;
 }
 /**
  * DI token for {@link IAgentTerminals}. Provided by `xtralab:terminals`;
- * consumed — optionally, so each side works without the other — by
- * `xtralab:ask-agent` to offer running agent terminals as prompt targets.
+ * consumed optionally by `xtralab:ask-agent`, so each side works without
+ * the other.
  */
 export declare const IAgentTerminals: Token<IAgentTerminals>;

package/lib/terminals/tokens.js

@@ -1,7 +1,7 @@
 import { Token } from '@lumino/coreutils';
 /**
  * DI token for {@link IAgentTerminals}. Provided by `xtralab:terminals`;
- * consumed — optionally, so each side works without the other — by
- * `xtralab:ask-agent` to offer running agent terminals as prompt targets.
+ * consumed optionally by `xtralab:ask-agent`, so each side works without
+ * the other.
  */
 export const IAgentTerminals = new Token('xtralab:IAgentTerminals', 'The running terminal sessions with a detected coding agent, and a way to send a prompt into one.');