@aiwayds/dsh-tui-pi 0.1.1 → 0.4.0

package/lib/subagent-policy.js

@@ -0,0 +1,189 @@
+/**
+ * Subagent policy for the TUI.
+ *
+ * Three knobs, all read live from the `dsh-tui` settings section at every
+ * decision point — no watcher needed (the /settings browser hot-applies, so
+ * the next guard execution / turn count reads the new value):
+ * - `maxAgents` caps concurrent live children. A `tools.guard` registered on
+ *   the plugin root ctx denies model-facing spawn tools once the bridge's
+ *   live child count meets the cap. Registered globally, every agent in the
+ *   process obeys — this TUI's session and any delegation nesting. The
+ *   workflow/ralph fan-out bypasses the tool pipeline (its worker thread
+ *   spawns through the subagent provider directly), so a `subagent/start`
+ *   listener prunes any newcomer that slips past the guard.
+ * - `disableSubagent` disables the plain native `subagent` tool: its calls
+ *   are denied for every agent (and it is hidden from the main agent's
+ *   catalog), so delegation goes through registered agent definitions
+ *   (`~/.dsh/agents/*.md` via the registry's `use_agent`). `subagent_fork`,
+ *   `workflow` and `ralph` stay available.
+ * - `maxRounds` caps a child's completed turns: on the bridge's `onTurnCount`
+ *   the policy injects one plugin-sourced user message telling the child to
+ *   wrap up. Queued as the child's next turn, it never interrupts work
+ *   already underway.
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { readSubagentLimits } from "./theme-settings.js";
+/**
+ * Tool names the maxAgents guard intercepts: the native subagent tool, the
+ * one-shot fork variant, the workflow fan-out entrypoint, its ralph-loop
+ * sibling, and registry plugins' `use_agent`.
+ */
+export const SPAWN_TOOLS = [
+    'subagent',
+    'subagent_fork',
+    'workflow',
+    'ralph',
+    'use_agent',
+];
+/**
+ * The native plain one-shot spawn tool - the only spawn tool `disableSubagent`
+ * fences. Deliberately a single name: the TUI's user delegates through
+ * registered agents (`~/.dsh/agents/*.md` via `use_agent`) and wants ONLY the
+ * plain `subagent` tool off; `subagent_fork` (fork a running session),
+ * `workflow` and `ralph` (fan-out loops) stay available.
+ */
+export const NATIVE_SPAWN_TOOLS = [
+    'subagent',
+];
+/**
+ * Hide the plain `subagent` tool from ONE agent's tool catalog (best-effort).
+ * The disableSubagent guard DENIES calls at execution; this additionally
+ * makes the tool INVISIBLE to the model, so the agent sees the registered
+ * `use_agent` as its delegation entry and never attempts the fenced tool.
+ *
+ * `tools.restrict` requires a scoped context (it throws on a plain plugin
+ * ctx) - the agent setup passes its scoped `agentCtx`, exactly the surface
+ * dsh-subagent uses for `deep: 0` leaves. Best-effort by design: an absent
+ * tools service, or a restrict failure (an unknown tool name in this
+ * profile, a transient registration race), degrades silently - the live
+ * disableSubagent guard remains the enforcement backstop, so the fence is
+ * NEVER weaker for hiding. Restriction is a creation-time snapshot: a
+ * disableSubagent toggle takes effect for agents created afterwards (the
+ * guard, being live, applies immediately in both directions).
+ */
+export function installSpawnToolFence(agentCtx) {
+    const tools = agentCtx.get('tools');
+    if (tools?.restrict === undefined)
+        return;
+    try {
+        tools.restrict({ deny: [...NATIVE_SPAWN_TOOLS] });
+    }
+    catch {
+        // Cosmetic hide only - never fail the agent setup over it. The guard
+        // below still denies the subagent tool at execution time.
+    }
+}
+/** Injected into a child that reached `maxRounds` — wrap up and report back. */
+export const SUMMARY_MESSAGE = '总结和结束这个任务，汇报情况。';
+/**
+ * Install the subagent policy on the plugin root ctx.
+ *
+ * @param ctx - plugin context. The settings-service lookup inside the helpers
+ * is defensive: a settings-less deployment resolves the defaults, so the
+ * policy still enforces its documented caps.
+ * @param state - the host's live view (bridge.getLiveChildren /
+ * bridge.getTurnCount). The guard and the round injection read it at every
+ * decision — no snapshot, no watch.
+ * @returns the policy handle wired to the bridge's `onTurnCount`.
+ */
+export function applySubagentPolicy(ctx, state) {
+    const disposers = [];
+    const injected = new Set();
+    // maxAgents guard: global (plugin root ctx), every spawn-tool call is
+    // denied while live children are at the cap. Zero disables the guard.
+    // The cap is approximate, not a hard admission lock: a burst of parallel
+    // spawn calls can briefly overshoot before the bridge's firehose discovery
+    // counts the newcomers — the subagent/start backstop below prunes the
+    // overshoot, and the next spawn's guard reads the caught-up count.
+    //
+    // disableSubagent fence: the plain native `subagent` tool is denied
+    // outright (checked before the cap - a tool violation is the reason even
+    // when the cap would also deny). `use_agent`, the fork/workflow/ralph
+    // variants and every non-spawn tool pass through to the cap check below.
+    const tools = ctx.get('tools');
+    if (tools?.guard !== undefined) {
+        disposers.push(tools.guard((exec) => {
+            if (!SPAWN_TOOLS.includes(exec.name))
+                return undefined;
+            if (readSubagentLimits(ctx).disableSubagent && NATIVE_SPAWN_TOOLS.includes(exec.name)) {
+                return `Tool "subagent" is disabled here - delegation goes through registered agents. `
+                    + 'Dispatch the work through the use_agent tool with one of the registered agent names instead.';
+            }
+            const maxAgents = readSubagentLimits(ctx).maxAgents;
+            if (maxAgents <= 0)
+                return undefined;
+            const live = state.getLive();
+            if (live.length < maxAgents)
+                return undefined;
+            const running = live.map((agent) => agent.label).join(', ');
+            return `Agent limit reached (${live.length}/${maxAgents}): ${running} still running — wait for one to finish or use list_agents before spawning more.`;
+        }));
+    }
+    // Workflow/ralph backstop: the worker thread fans children out through the
+    // subagent provider, never through the tool pipeline — the only leak past
+    // the guard. Prune a newcomer whose start overshoots the cap. The event is
+    // foreign to this bundle's type environment (`@deepseek-ai/dsh-subagent` is
+    // not installed), so the subscription rides the base event bus rather than
+    // the typed `ctx.on`.
+    const eventDisposer = ctx.events.on('subagent/start', (info) => {
+        if (info?.id === undefined)
+            return;
+        const maxAgents = readSubagentLimits(ctx).maxAgents;
+        if (maxAgents <= 0)
+            return;
+        // Exclude the newcomer itself: whether or not its own session events
+        // have reached the bridge's count yet (the subagent/start notification
+        // and the child's first firehose event race), the child is pruned only
+        // when the OTHER live children already fill the cap — a legitimate
+        // Nth-at-cap child is never cancelled on either ordering.
+        const live = state.getLive().filter(view => view.childId !== String(info.id));
+        if (live.length < maxAgents)
+            return;
+        ctx.agents.get(info.id)?.cancel({
+            kind: 'hook',
+            reason: 'over the dsh-tui maxAgents policy cap — prune a fan-out child',
+        });
+    });
+    disposers.push(eventDisposer);
+    /**
+     * Bridge turn-count sink: inject the summary message exactly once per
+     * child, at the first turn that reaches a positive `maxRounds`. A missing
+     * agent (cold, or transiently unregistered) is skipped silently; a settled
+     * child is skipped too — injecting into a finished one would wake it for a
+     * pointless wrap-up round (continuable children that resume later get their
+     * chance on the next counted turn). Repeated injections are impossible by
+     * construction (the set is only written on success).
+     */
+    function onTurnCount(childId, count) {
+        if (injected.has(childId))
+            return;
+        const maxRounds = readSubagentLimits(ctx).maxRounds;
+        if (maxRounds <= 0)
+            return;
+        if (count < maxRounds)
+            return;
+        if (state.isSettled(childId))
+            return;
+        const agent = ctx.agents.get(SessionId(childId));
+        if (agent === undefined)
+            return;
+        injected.add(childId);
+        agent.followup(createUserMessage({
+            content: [{ type: 'text', text: SUMMARY_MESSAGE }],
+            source: { kind: 'plugin', plugin: 'dsh-tui-pi' },
+        }));
+    }
+    return {
+        onTurnCount,
+        dispose() {
+            for (const dispose of disposers.splice(0)) {
+                try {
+                    dispose();
+                }
+                catch { /* contained */ }
+            }
+        },
+    };
+}
+//# sourceMappingURL=subagent-policy.js.map

package/lib/subagent-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subagent-policy.js","sourceRoot":"","sources":["../src/subagent-policy.ts"],"names":[],"mappings":"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"}

package/lib/subagent-viewer.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The subagent viewer — the Ctrl+G surface. Two levels, both on the shared
+ * PanelHost overlay (80%): a SelectList picker over the bridge's child views,
+ * then a live transcript panel for one child's buffered event log.
+ *
+ * Picker rows (running first, then the five most recent settled) carry the
+ * full picture of a delegation: status icon, label, delegation mode, rounds
+ * against the policy cap (`maxRounds` from `readSubagentLimits`, only shown
+ * when > 0), token spend (k) and elapsed time. Settled rows read as faded
+ * because their status icon and the muted description column mark the outcome.
+ *
+ * Transcript panel: one human-readable line per buffered SessionEvent
+ * (user/assistant messages, tool calls + truncated results, turns, descriptor,
+ * todos). The log is a capped per-child ring buffer (2000 events); a dropped
+ * head is reported at the top. While the panel is open a ~300ms timer rebuilds
+ * the lines from the bridge and re-renders, and the view follows the tail like
+ * a ScrollView follow:'end' (an explicit scroll-up detaches; reaching the
+ * bottom re-attaches). Esc closes, or a deliberate double-`x` within
+ * `DOUBLE_PRESS_MS`.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type SelectItem, type TUI } from '@earendil-works/pi-tui';
+import type { AgentView } from './dsh-events.ts';
+import type { DshSessionBridge } from './session.ts';
+import { type TuiTheme } from './theme/index.ts';
+/**
+ * The picker rows: running children first (the live items the key is for),
+ * then the five most recent settled ones (newest settle first). Each row
+ * reads `⠋ label [mode] · rounds N[/max]` with the token spend and elapsed
+ * seconds in the muted description column.
+ */
+export declare function pickerItems(views: readonly AgentView[], getTurnCount: (childId: string) => number, maxRounds: number): SelectItem[];
+/**
+ * The next selected index after a picker items swap, preserving the selection
+ * by item value. `previous === undefined` (no selection yet) starts at 0; a
+ * value that dropped off the new list (e.g. a settled child fell out of the
+ * recent-settled cap) clamps to the last row rather than resetting the user
+ * to the top. Pure and exported for the regression test.
+ */
+export declare function nextSelectedIndex(items: readonly SelectItem[], previous: string | undefined): number;
+/**
+ * Open the subagent picker / viewer. A SelectList of the bridge's child views
+ * (running first, then the five recent settled) opens; Enter opens a
+ * live-refreshing transcript panel for that child. An empty list (no running,
+ * no settled) closes immediately. Focus returns to `restoreFocus` on close;
+ * the promise settles when the viewer closes (value is meaningless — index.ts
+ * never branches on it).
+ */
+export declare function openSubagentViewer(ctx: Context, tui: TUI, theme: TuiTheme, bridge: DshSessionBridge, restoreFocus: () => void): Promise<void>;