agent-sh 0.12.13 → 0.12.14

package/dist/extensions/slash-commands.js

@@ -14,7 +14,7 @@ import { palette as p } from "../utils/palette.js";
 import { discoverSkills, loadSkillContent } from "../agent/skills.js";
 import { reloadExtensions } from "../extension-loader.js";
 export default function activate(ctx) {
-    const { bus, contextManager } = ctx;
+    const { bus } = ctx;
     const commands = new Map();
     const register = (cmd) => {
         const name = cmd.name.startsWith("/") ? cmd.name : `/${cmd.name}`;
@@ -128,7 +128,7 @@ export default function activate(ctx) {
     });
     // ── Skill commands (/skill:<name>) ────────────────────────────
     const getSkills = () => {
-        const cwd = contextManager?.getCwd() ?? process.cwd();
+        const cwd = ctx.call("cwd") ?? process.cwd();
         return discoverSkills(cwd);
     };
     const handleSkillCommand = (skillName, args) => {

package/dist/index.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { spawn } from "node:child_process";
 import * as path from "node:path";
-import { Shell } from "./shell/shell.js";
+import { activateShell } from "./shell/index.js";
 import { createCore } from "./core.js";
 import { palette as p } from "./utils/palette.js";
 import { loadBuiltinExtensions } from "./extensions/index.js";
@@ -199,26 +199,32 @@ async function main() {
     process.stdout.write(`\x1b]0;agent-sh\x07`);
     const cols = process.stdout.columns || 80;
     const rows = process.stdout.rows || 24;
+    // Bound after activateShell — cleanup is wired into extCtx.quit before the
+    // shell exists, so the closure captures the var by reference.
+    let shell = null;
     const cleanup = () => {
         core.kill();
-        shell.kill();
+        shell?.kill();
         if (process.stdin.isTTY) {
             process.stdin.setRawMode(false);
         }
         process.exit(0);
     };
+    // ── Extension context (must precede shell activation) ────────
+    if (process.env.DEBUG) {
+        console.error('[agent-sh] Setting up extensions...');
+    }
+    const extCtx = core.extensionContext({ quit: cleanup });
+    // ── Shell frontend bootstrap (special-cased; see src/shell/index.ts) ──
     if (process.env.DEBUG) {
         console.error('[agent-sh] Creating Shell...');
     }
     await new Promise(resolve => setTimeout(resolve, 100));
-    const shell = new Shell({
-        bus,
-        handlers: core.handlers,
+    shell = activateShell(extCtx, {
         cols,
         rows,
-        shell: config.shell || process.env.SHELL || "/bin/bash",
+        shellPath: config.shell || process.env.SHELL || "/bin/bash",
         cwd: process.cwd(),
-        instanceId: core.instanceId,
         onShowAgentInfo: () => {
             if (agentInfo) {
                 return { info: `${p.dim}${agentInfo.name}${agentInfo.model ? ` (${agentInfo.model})` : ""}${p.reset}` };
@@ -241,11 +247,6 @@ async function main() {
         },
         returnToSelf: true,
     });
-    // ── Extensions ────────────────────────────────────────────────
-    if (process.env.DEBUG) {
-        console.error('[agent-sh] Setting up extensions...');
-    }
-    const extCtx = core.extensionContext({ quit: cleanup });
     // Load built-in extensions (individually disableable via settings.disabledBuiltins)
     await loadBuiltinExtensions(extCtx, getSettings().disabledBuiltins);
     // Load user extensions (may register alternative agent backends)
@@ -273,7 +274,7 @@ async function main() {
     // If none did, the built-in AgentLoop gets wired to bus events.
     const { names: backendNames } = core.bus.emitPipe("config:get-backends", { names: [], active: null });
     if (backendNames.length === 0) {
-        shell.kill();
+        shell?.kill();
         console.error("\nagent-sh: no agent backend available.\n\n" +
             "  Export OPENROUTER_API_KEY or OPENAI_API_KEY for zero-config launch, or\n" +
             "  pass --api-key on the command line, or\n" +
@@ -354,9 +355,7 @@ async function main() {
             }
         }
     });
-    process.stdout.on("resize", () => {
-        shell.resize(process.stdout.columns || 80, process.stdout.rows || 24);
-    });
+    // resize forwarding is set up inside activateShell; nothing to wire here.
     shell.onExit((e) => {
         core.kill();
         if (process.stdin.isTTY) {

package/dist/shell/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Frontend bootstrap. Loaded directly from src/index.ts (not the built-in
+ * extensions manifest) because PTY + stdin raw mode ownership is order-
+ * critical. For pluggable capability extensions see `src/extensions/`.
+ */
+import type { ExtensionContext } from "../types.js";
+export interface ShellActivateOptions {
+    cols: number;
+    rows: number;
+    /** Path to the shell binary (zsh, bash, etc.). */
+    shellPath: string;
+    cwd: string;
+    /** Optional callback used by the inline status indicator. */
+    onShowAgentInfo?: () => {
+        info: string;
+        model?: string;
+    };
+}
+export interface ShellHandle {
+    /** Terminate the PTY. */
+    kill(): void;
+    /** Subscribe to PTY exit. The frontend uses this to clean up + exit. */
+    onExit(callback: (e: {
+        exitCode: number;
+        signal?: number;
+    }) => void): void;
+    /** Forward terminal size changes to the PTY. */
+    resize(cols: number, rows: number): void;
+}
+/**
+ * Construct the Shell, wire resize forwarding, and register cleanup with the
+ * provided ExtensionContext. Returns a handle the caller (typically
+ * `src/index.ts`) uses to drive lifecycle from process-level events.
+ */
+export declare function activateShell(ctx: ExtensionContext, opts: ShellActivateOptions): ShellHandle;

package/dist/shell/index.js

@@ -0,0 +1,47 @@
+import { Shell } from "./shell.js";
+import { StdoutSurface } from "../utils/compositor.js";
+import { TerminalBuffer } from "../utils/terminal-buffer.js";
+/**
+ * Construct the Shell, wire resize forwarding, and register cleanup with the
+ * provided ExtensionContext. Returns a handle the caller (typically
+ * `src/index.ts`) uses to drive lifecycle from process-level events.
+ */
+export function activateShell(ctx, opts) {
+    // Stdout-as-default is a frontend choice, not a kernel one — a hub or
+    // web bridge would point these at its own surfaces.
+    const stdoutSurface = new StdoutSurface();
+    ctx.compositor.setDefault("agent", stdoutSurface);
+    ctx.compositor.setDefault("query", stdoutSurface);
+    ctx.compositor.setDefault("status", stdoutSurface);
+    // Lazy because @xterm/headless is optional; null when not installed.
+    let terminalBufferSingleton;
+    ctx.define("terminal-buffer", () => {
+        if (terminalBufferSingleton !== undefined)
+            return terminalBufferSingleton;
+        terminalBufferSingleton = TerminalBuffer.createWired(ctx.bus);
+        return terminalBufferSingleton;
+    });
+    const shell = new Shell({
+        bus: ctx.bus,
+        handlers: { define: ctx.define, call: ctx.call },
+        cols: opts.cols,
+        rows: opts.rows,
+        shell: opts.shellPath,
+        cwd: opts.cwd,
+        instanceId: ctx.instanceId,
+        onShowAgentInfo: opts.onShowAgentInfo,
+    });
+    const onResize = () => {
+        shell.resize(process.stdout.columns || 80, process.stdout.rows || 24);
+    };
+    process.stdout.on("resize", onResize);
+    ctx.onDispose(() => {
+        process.stdout.off("resize", onResize);
+        shell.kill();
+    });
+    return {
+        kill: () => shell.kill(),
+        onExit: (callback) => shell.onExit(callback),
+        resize: (cols, rows) => shell.resize(cols, rows),
+    };
+}

package/dist/types.d.ts

@@ -1,9 +1,7 @@
 import type { EventBus } from "./event-bus.js";
-import type { ContextManager } from "./context-manager.js";
 import type { ColorPalette } from "./utils/palette.js";
 import type { BlockTransformOptions, FencedBlockTransformOptions } from "./utils/stream-transform.js";
 import type { ToolDefinition } from "./agent/types.js";
-import type { TerminalBuffer } from "./utils/terminal-buffer.js";
 import type { Compositor } from "./utils/compositor.js";
 import type { HistoryAdapter } from "./agent/history-file.js";
 export type { ContentBlock } from "./event-bus.js";
@@ -20,8 +18,6 @@ export interface RemoteSessionOptions {
     suppressQueryBox?: boolean;
     /** Suppress usage stats line (default: true). */
     suppressUsage?: boolean;
-    /** Set interactive-session dynamic context (default: false). */
-    interactive?: boolean;
 }
 export interface RemoteSession {
     /** Submit a query to the agent from this session. */
@@ -100,7 +96,6 @@ export interface AgentShellConfig {
  */
 export interface ExtensionContext {
     bus: EventBus;
-    contextManager: ContextManager;
     /** Stable per-instance identifier (4-char hex). */
     readonly instanceId: string;
     quit: () => void;
@@ -134,6 +129,31 @@ export interface ExtensionContext {
     registerSkill: (name: string, description: string, filePath: string) => void;
     /** Remove a registered skill by name. */
     removeSkill: (name: string) => void;
+    /**
+     * Register a context producer — a function that contributes a string
+     * (or `null` to skip) into one of two lifecycles:
+     *
+     * - `mode: "per-request"` (default) — fires on **every LLM request**,
+     *   including each tool-loop iteration. Output is ephemerally wrapped
+     *   in `<dynamic_context>` onto the trailing message at request time;
+     *   never persisted. Use for "current state" signals (in-flight work,
+     *   active mode, threshold warnings).
+     *
+     * - `mode: "per-query"` — fires **once at user-query start** in
+     *   handleQuery. Output is wrapped in `<query_context>` and frozen into
+     *   the user message; persists in conversation history. Use for
+     *   "what happened between turns" signals (shell events, accumulated
+     *   notifications, calendar/inbox deltas).
+     *
+     * In both modes producers run in registration order, non-null outputs
+     * joined with blank lines. When nothing contributes, no envelope tag
+     * is emitted.
+     *
+     * Returns a dispose fn that unregisters the producer.
+     */
+    registerContextProducer: (name: string, producer: () => string | null, opts?: {
+        mode?: "per-request" | "per-query";
+    }) => () => void;
     providers: {
         configure: (id: string, opts: {
             reasoningParams?: (level: string) => Record<string, unknown>;
@@ -148,11 +168,6 @@ export interface ExtensionContext {
     call: (name: string, ...args: any[]) => any;
     /** Names of all registered handlers — for diagnostic / introspection use. */
     list: () => string[];
-    /**
-     * Shared headless terminal buffer mirroring PTY output.
-     * Lazily created on first access. Returns null if @xterm/headless is not installed.
-     */
-    terminalBuffer: TerminalBuffer | null;
     /**
      * Routes named render streams ("agent", "query", "status") to surfaces.
      * Extensions use `compositor.redirect()` to capture output (e.g. overlay panels).
@@ -166,7 +181,7 @@ export interface ExtensionContext {
      * optionally accepts queries. Handles all compositor routing, shell
      * lifecycle advisors, and chrome suppression.
      *
-     *   const session = ctx.createRemoteSession({ surface, interactive: true });
+     *   const session = ctx.createRemoteSession({ surface });
      *   session.submit("what's on screen?");
      *   session.close();  // restores everything
      */
@@ -193,24 +208,3 @@ export interface TerminalSession {
     done: boolean;
     resolve?: (value: void) => void;
 }
-export type Exchange = {
-    type: "shell_command";
-    id: number;
-    timestamp: number;
-    cwd: string;
-    command: string;
-    /** In-context representation: full text if short, head+tail+path stub if spilled. */
-    output: string;
-    exitCode: number | null;
-    outputLines: number;
-    outputBytes: number;
-    /** Who initiated this command: "user" (typed) or "agent" (via user_shell). */
-    source: "user" | "agent";
-    /** Path to the tempfile holding the full captured output, if spilled. */
-    spillPath?: string;
-} | {
-    type: "agent_query";
-    id: number;
-    timestamp: number;
-    query: string;
-};

package/dist/utils/message-utils.d.ts

@@ -20,6 +20,19 @@ export declare function findToolCallIds(messages: any[], toolName: string, argFi
  * replaced. Non-matching messages are passed through by reference.
  */
 export declare function stubToolResults(messages: any[], callIds: Set<string>, stub: string): any[];
+/**
+ * Prepend a `<dynamic_context>` block onto the trailing message.
+ *
+ * Wrapping the *trailing* message (rather than inserting at the head) keeps
+ * the [system] + [prior history] prefix byte-stable across turns, so the
+ * provider's prefix cache holds. Caller passes a copy; conversation state
+ * is never mutated.
+ *
+ * No-op when both `dynamicContext` and `toolPrompt` are empty — i.e. no
+ * extension registered any per-turn signal — so a vanilla session sends
+ * exactly `[system, ...history]` with no synthetic envelope.
+ */
+export declare function wrapTrailingWithDynamicContext(history: any[], dynamicContext: string, toolPrompt?: string): any[];
 /**
  * Deduplicate tool results: keep only the latest result for a given
  * tool name + argument filter, replace all older results with a stub.

package/dist/utils/message-utils.js

@@ -53,6 +53,32 @@ export function stubToolResults(messages, callIds, stub) {
         return msg;
     });
 }
+/**
+ * Prepend a `<dynamic_context>` block onto the trailing message.
+ *
+ * Wrapping the *trailing* message (rather than inserting at the head) keeps
+ * the [system] + [prior history] prefix byte-stable across turns, so the
+ * provider's prefix cache holds. Caller passes a copy; conversation state
+ * is never mutated.
+ *
+ * No-op when both `dynamicContext` and `toolPrompt` are empty — i.e. no
+ * extension registered any per-turn signal — so a vanilla session sends
+ * exactly `[system, ...history]` with no synthetic envelope.
+ */
+export function wrapTrailingWithDynamicContext(history, dynamicContext, toolPrompt) {
+    const ctx = dynamicContext.trim();
+    const tp = (toolPrompt ?? "").trim();
+    if (!ctx && !tp)
+        return history;
+    if (history.length === 0)
+        return history;
+    const last = history[history.length - 1];
+    if (typeof last.content !== "string")
+        return history;
+    const blockBody = ctx && tp ? `${ctx}\n${tp}` : ctx || tp;
+    const wrappedContent = `<dynamic_context>\n${blockBody}\n</dynamic_context>\n\n${last.content}`;
+    return [...history.slice(0, -1), { ...last, content: wrappedContent }];
+}
 /**
  * Deduplicate tool results: keep only the latest result for a given
  * tool name + argument filter, replace all older results with a stub.

package/examples/extensions/overlay-agent.ts

@@ -48,7 +48,8 @@ function createPanelSurface(panel: FloatingPanel): RenderSurface {
 }
 
 export default function activate(ctx: ExtensionContext): void {
-  const { bus, registerInstruction, createRemoteSession, terminalBuffer } = ctx;
+  const { bus, registerInstruction, createRemoteSession } = ctx;
+  const terminalBuffer = ctx.call("terminal-buffer");
 
   const panel = new FloatingPanel(bus, {
     trigger: "\x1c", // Ctrl+\
@@ -59,6 +60,13 @@ export default function activate(ctx: ExtensionContext): void {
   const panelSurface = createPanelSurface(panel);
   let session: RemoteSession | null = null;
 
+  // Tell the LLM it's running inside an overlay session. The matching
+  // system-prompt block (registered via registerInstruction below) describes
+  // how to behave in this mode.
+  ctx.registerContextProducer("interactive-session", () =>
+    session?.active ? "interactive-session: true" : null,
+  );
+
   registerInstruction("Interactive Overlay Sessions", [
     "When the dynamic context includes `interactive-session: true`, the user has summoned you",
     "via a hotkey overlay from inside their live terminal. They may be in the middle of using",
@@ -77,7 +85,6 @@ export default function activate(ctx: ExtensionContext): void {
       session = createRemoteSession({
         surface: panelSurface,
         suppressQueryBox: true,
-        interactive: true,
       });
     }
     panel.setActive();
@@ -90,7 +97,6 @@ export default function activate(ctx: ExtensionContext): void {
       session = createRemoteSession({
         surface: panelSurface,
         suppressQueryBox: true,
-        interactive: true,
       });
     }
   });

package/examples/extensions/peer-mesh.ts

@@ -190,10 +190,11 @@ class PeerServer {
 }
 
 export default function activate(ctx: ExtensionContext): void {
-  const { bus, contextManager, registerCommand, registerTool, registerInstruction, define } = ctx;
+  const { bus, registerCommand, registerTool, registerInstruction, define } = ctx;
+  const getCwd = () => ctx.call("cwd") as string;
   const startTime = Date.now();
 
-  const server = new PeerServer(ctx.instanceId, contextManager.getCwd(), (...args) => ctx.call(...args));
+  const server = new PeerServer(ctx.instanceId, getCwd(), (...args) => ctx.call(...args));
   server.start();
 
   // Track PTY idle window so peer:terminal-send doesn't stomp on a busy shell.
@@ -203,13 +204,13 @@ export default function activate(ctx: ExtensionContext): void {
   define("peer:info", () => ({
     id: ctx.instanceId,
     pid: process.pid,
-    cwd: contextManager.getCwd(),
+    cwd: getCwd(),
     uptime: Math.round((Date.now() - startTime) / 1000),
   }));
   server.expose("peer:info");
 
   define("peer:terminal-read", () => {
-    const tb = ctx.terminalBuffer;
+    const tb = ctx.call("terminal-buffer");
     if (!tb) return { text: "(terminal buffer not available)", altScreen: false };
     return tb.readScreen({ includeScrollback: true });
   });
@@ -229,15 +230,17 @@ export default function activate(ctx: ExtensionContext): void {
     }
     bus.emit("shell:pty-write", { data: interpretEscapes(keys) });
     await new Promise((r) => setTimeout(r, typeof settleMs === "number" ? settleMs : SETTLE_MS));
-    const tb = ctx.terminalBuffer;
+    const tb = ctx.call("terminal-buffer");
     return { sent: true, screen: tb ? tb.readScreen({ includeScrollback: false }) : null };
   });
   server.expose("peer:terminal-send");
 
-  define("peer:context-recent", (n: number = 15) => contextManager.getRecentSummary(n));
+  // If shell-context isn't loaded, the underlying handler is undefined
+  // and these calls surface a clear error to the requesting peer.
+  define("peer:context-recent", (n: number = 15) => ctx.call("shell:context-recent", n));
   server.expose("peer:context-recent");
 
-  define("peer:context-search", (query: string) => contextManager.search(query));
+  define("peer:context-search", (query: string) => ctx.call("shell:context-search", query));
   server.expose("peer:context-search");
 
   // ── Inbox + drained turn ──────────────────────────────────────

package/examples/extensions/subagents.ts

@@ -12,7 +12,7 @@ import type { ExtensionContext } from "agent-sh/types";
 import { runSubagent } from "agent-sh/agent/subagent";
 
 export default function activate(ctx: ExtensionContext): void {
-  const { bus, llmClient, contextManager } = ctx;
+  const { bus, llmClient } = ctx;
   if (!llmClient) return;
 
   const allToolNames = () => ctx.getTools().map(t => t.name);
@@ -73,7 +73,7 @@ export default function activate(ctx: ExtensionContext): void {
 
       const systemPrompt =
         `You are a focused subagent. Complete the task and return a clear, concise result.\n` +
-        `Working directory: ${contextManager.getCwd()}` +
+        `Working directory: ${ctx.call("cwd")}` +
         (nuclearSummary ? `\n\n[Parent session history]\n${nuclearSummary}` : "");
 
       try {

package/examples/extensions/terminal-buffer.ts

@@ -34,8 +34,9 @@ function settle(ms = 100): Promise<void> {
 }
 
 export default function activate(ctx: ExtensionContext): void {
-  const { bus, terminalBuffer: tb, registerTool, registerInstruction } = ctx;
-  if (!tb) return; // @xterm/headless not installed
+  const { bus, registerTool, registerInstruction } = ctx;
+  const tb = ctx.call("terminal-buffer");
+  if (!tb) return; // @xterm/headless not installed, or shell frontend not loaded
 
   registerTool({
     name: "terminal_read",

package/examples/extensions/tmux-pane.ts

@@ -149,6 +149,11 @@ export default function activate(ctx: ExtensionContext): void {
 
   let state: PaneState | null = null;
 
+  // Tell the LLM it's running inside an interactive pane session.
+  ctx.registerContextProducer("interactive-session", () =>
+    state?.mode === "rsplit" ? "interactive-session: true" : null,
+  );
+
   registerInstruction("Tmux Interactive Session", [
     "When the dynamic context includes `interactive-session: true`, the user is chatting",
     "with you in a side pane next to their terminal. They may have a program running in",
@@ -229,7 +234,6 @@ export default function activate(ctx: ExtensionContext): void {
       const session = createRemoteSession({
         surface,
         suppressQueryBox: true,
-        interactive: true,
       });
 
       state = { mode: "rsplit", paneId, ttyFd, session, server, client, sockPath, scriptPath };

package/examples/extensions/user-shell.ts

@@ -18,7 +18,7 @@ import type { ToolDefinition } from "agent-sh/agent/types";
 
 export default function activate(ctx: ExtensionContext): void {
   const { bus, registerTool, registerInstruction } = ctx;
-  const getCwd = () => ctx.contextManager.getCwd();
+  const getCwd = () => ctx.call("cwd") as string;
 
   // ── Tool ───────────────────────────────────────────────────────
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-sh",
-  "version": "0.12.13",
+  "version": "0.12.14",
   "description": "A shell-first terminal where AI is one keystroke away",
   "type": "module",
   "main": "dist/core.js",

package/dist/context-manager.d.ts

@@ -1,45 +0,0 @@
-import type { EventBus } from "./event-bus.js";
-import type { HandlerRegistry } from "./utils/handler-registry.js";
-export declare class ContextManager {
-    private exchanges;
-    private nextId;
-    private currentCwd;
-    private agentShellActive;
-    constructor(bus: EventBus, _handlers?: HandlerRegistry);
-    getCwd(): string;
-    /**
-     * Regex/keyword search across all exchanges. Returns formatted results.
-     */
-    search(query: string): string;
-    /**
-     * Return shell events with id > afterId, formatted as an incremental
-     * delta suitable for injection into conversation history. Skips
-     * agent-source commands (already visible in tool results). Returns
-     * null when nothing new exists.
-     *
-     * The motivation: resending the full <shell_context> every turn wastes
-     * tokens — N turns × full history = O(N²) cost for O(N) information.
-     * Instead we inject only new events as regular conversation messages,
-     * so the provider's prefix cache amortizes them to O(N).
-     */
-    getEventsSince(afterId: number): {
-        text: string;
-        lastSeq: number;
-    } | null;
-    /** Highest exchange id seen so far (0 if none). */
-    lastSeq(): number;
-    /**
-     * One-line summaries of last N exchanges.
-     */
-    getRecentSummary(n?: number): string;
-    /**
-     * Clear exchange history (used by /clear command).
-     */
-    clear(): void;
-    private addExchange;
-    private formatExchangeTruncated;
-    private formatExchangeFull;
-    private exchangeOneLiner;
-    private exchangeSearchText;
-    private exchangeSize;
-}