agent-sh 0.15.0 → 0.15.2

package/src/agent/subagent.ts

@@ -0,0 +1,305 @@
+/**
+ * Subagent runner — executes a focused agent loop with its own context.
+ *
+ * Unlike the main AgentLoop, a subagent:
+ *   - Has its own conversation (starts fresh, stays focused)
+ *   - Has its own system prompt (specialized for the task)
+ *   - Runs to completion and returns the final text
+ *   - Optionally emits tool events to the bus for TUI rendering
+ *
+ * Used by the subagent extension to delegate tasks from the main agent.
+ */
+import type { EventBus } from "../core/event-bus.js";
+import type { LlmClient } from "./llm-client.js";
+import { contentText, type ToolDefinition } from "./types.js";
+import { LiveView } from "./live-view.js";
+import { normalizeToolArgs } from "./normalize-args.js";
+import { wrapTrailingWithDynamicContext } from "../utils/message-utils.js";
+
+interface PendingToolCall {
+  id: string;
+  name: string;
+  argumentsJson: string;
+}
+
+export interface SubagentOptions {
+  /** LLM client to use. */
+  llmClient: LlmClient;
+  /** Tools available to the subagent. */
+  tools: ToolDefinition[];
+  /** System prompt for this subagent. */
+  systemPrompt: string;
+  /** The task to perform. */
+  task: string;
+  /** Model override (optional, defaults to llmClient's model). */
+  model?: string;
+  /** Event bus for TUI events (optional — silent if omitted). */
+  bus?: EventBus;
+  /** Abort signal for cancellation. */
+  signal?: AbortSignal;
+  /** Max tool loop iterations (default 20). */
+  maxIterations?: number;
+  /**
+   * Ambient context rebuilt per iteration, same shape the parent's
+   * streamResponse uses. If provided, the subagent sees budget,
+   * metacognitive signals, in-flight siblings, etc.
+   */
+  dynamicContext?: string;
+  /**
+   * Per-subagent completion-token budget. When the cumulative
+   * completion_tokens across iterations exceeds this, the subagent
+   * terminates gracefully on the next iteration. We deliberately don't
+   * count prompt tokens: the full history is resent each iteration, so
+   * prompt-inclusive counting double-charges context and makes a budget
+   * of N exhaust after O(log N) tool calls. Completion tokens measure
+   * the work the subagent actually produces. The parent's daily budget
+   * still sees real prompt+completion via onUsage.
+   */
+  budgetTokens?: number;
+  /**
+   * Invoked after every streamed LLM response with its usage totals.
+   * The parent uses this to forward to its event bus so global budget
+   * tracking stays accurate.
+   */
+  onUsage?: (usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number }) => void;
+}
+
+/**
+ * Run a subagent to completion.
+ * Returns the final response text.
+ */
+export async function runSubagent(opts: SubagentOptions): Promise<string> {
+  const {
+    llmClient,
+    tools,
+    systemPrompt,
+    task,
+    model,
+    bus,
+    signal,
+    maxIterations = 20,
+    dynamicContext,
+    budgetTokens,
+    onUsage,
+  } = opts;
+
+  const toolMap = new Map(tools.map(t => [t.name, t]));
+  const apiTools = tools.map(t => ({
+    type: "function" as const,
+    function: {
+      name: t.name,
+      description: t.description,
+      parameters: t.input_schema,
+    },
+  }));
+
+  const conversation = new LiveView();
+  conversation.addUserMessage(task);
+
+  let fullResponseText = "";
+  let iterations = 0;
+  let tokensConsumed = 0;
+  let budgetExhausted = false;
+
+  while (iterations++ < maxIterations) {
+    if (signal?.aborted) break;
+    if (budgetTokens != null && tokensConsumed >= budgetTokens) {
+      budgetExhausted = true;
+      break;
+    }
+
+    // Stream LLM response
+    const { text, toolCalls, assistantContent, assistantToolCalls, extras, usage } =
+      await streamOnce(llmClient, systemPrompt, conversation, apiTools, model, signal, dynamicContext);
+
+    if (usage) {
+      tokensConsumed += usage.completion_tokens || 0;
+      onUsage?.(usage);
+    }
+
+    fullResponseText += text;
+
+    conversation.addAssistantMessage(assistantContent, assistantToolCalls, extras);
+
+    // No tool calls → done
+    if (toolCalls.length === 0) break;
+
+    // Execute tools
+    for (const tc of toolCalls) {
+      if (signal?.aborted) break;
+
+      const tool = toolMap.get(tc.name);
+      if (!tool) {
+        conversation.addToolResult(tc.id, `Error: Unknown tool "${tc.name}"`, true);
+        continue;
+      }
+
+      let args: Record<string, unknown>;
+      try {
+        args = JSON.parse(tc.argumentsJson);
+      } catch {
+        conversation.addToolResult(tc.id, `Error: Invalid JSON arguments for ${tc.name}`, true);
+        continue;
+      }
+      args = normalizeToolArgs(args, tool.input_schema);
+
+      // Emit tool events for TUI (if bus provided)
+      if (bus) {
+        const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
+        bus.emit("agent:tool-started", {
+          title: tc.name,
+          name: tc.name,
+          toolCallId: tc.id,
+          kind: display.kind,
+          locations: display.locations,
+          rawInput: args,
+        });
+      }
+
+      const onChunk = bus && tool.showOutput !== false
+        ? (chunk: string) => { bus.emit("agent:tool-output-chunk", { chunk }); }
+        : undefined;
+
+      const result = await tool.execute(args, onChunk);
+
+      if (bus) {
+        const display = tool.getDisplayInfo?.(args) ?? { kind: "execute" };
+        const resultDisplay = tool.formatResult?.(args, result);
+        bus.emitTransform("agent:tool-completed", {
+          toolCallId: tc.id,
+          exitCode: result.exitCode,
+          rawOutput: result.content,
+          kind: display.kind,
+          resultDisplay,
+        });
+      }
+
+      const content = result.isError
+        ? `Error: ${contentText(result.content)}`
+        : result.content;
+      conversation.addToolResult(tc.id, content, !!result.isError);
+    }
+  }
+
+  if (budgetExhausted) {
+    const note = `\n\n[Subagent terminated: completion-token budget (${budgetTokens}) exhausted after ${tokensConsumed} completion tokens. Returning partial progress.]`;
+    return fullResponseText + note;
+  }
+
+  return fullResponseText;
+}
+
+/** Stream a single LLM response. */
+async function streamOnce(
+  llmClient: LlmClient,
+  systemPrompt: string,
+  conversation: LiveView,
+  apiTools: any[],
+  model: string | undefined,
+  signal: AbortSignal | undefined,
+  dynamicContext?: string,
+): Promise<{
+  text: string;
+  toolCalls: PendingToolCall[];
+  assistantContent: string | null;
+  assistantToolCalls: { id: string; function: { name: string; arguments: string } }[] | undefined;
+  extras?: Record<string, unknown>;
+  usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number } | null;
+}> {
+  let text = "";
+  let reasoning = "";
+  let reasoningField: string | null = null;
+  const reasoningDetailsByIndex = new Map<number, Record<string, unknown>>();
+  const pendingToolCalls: PendingToolCall[] = [];
+  let usage: { prompt_tokens: number; completion_tokens: number; total_tokens: number } | null = null;
+
+  const stream = await llmClient.stream({
+    messages: [
+      { role: "system", content: systemPrompt },
+      ...wrapTrailingWithDynamicContext(conversation.forLLM(), dynamicContext ?? ""),
+    ],
+    tools: apiTools.length > 0 ? apiTools : undefined,
+    model,
+    signal,
+  });
+
+  for await (const chunk of stream) {
+    if (signal?.aborted) break;
+
+    if ((chunk as any).usage) {
+      const u = (chunk as any).usage;
+      usage = {
+        prompt_tokens: u.prompt_tokens ?? 0,
+        completion_tokens: u.completion_tokens ?? 0,
+        total_tokens: u.total_tokens ?? 0,
+      };
+    }
+
+    const choice = chunk.choices[0];
+    if (!choice) continue;
+    const delta = choice.delta;
+
+    if (delta?.content) {
+      text += delta.content;
+    }
+
+    const d = delta as any;
+    for (const name of ["reasoning", "reasoning_content"] as const) {
+      if (typeof d?.[name] === "string" && d[name].length > 0) {
+        reasoning += d[name];
+        reasoningField ??= name;
+      }
+    }
+    if (Array.isArray(d?.reasoning_details)) {
+      for (const x of d.reasoning_details) {
+        const idx = typeof x?.index === "number" ? x.index : reasoningDetailsByIndex.size;
+        const prev = reasoningDetailsByIndex.get(idx);
+        if (!prev) {
+          reasoningDetailsByIndex.set(idx, { ...x });
+        } else {
+          if (typeof x.text === "string") prev.text = (prev.text ?? "") + x.text;
+          for (const [k, v] of Object.entries(x)) if (k !== "text" && prev[k] === undefined) prev[k] = v;
+        }
+      }
+    }
+
+    if (delta?.tool_calls) {
+      for (const tc of delta.tool_calls) {
+        const idx = tc.index;
+        if (!pendingToolCalls[idx]) {
+          pendingToolCalls[idx] = { id: tc.id!, name: tc.function!.name!, argumentsJson: "" };
+        }
+        if (tc.function?.arguments) {
+          pendingToolCalls[idx].argumentsJson += tc.function.arguments;
+        }
+      }
+    }
+  }
+
+  // Normalize arguments JSON (same fix as agent-loop): strict providers
+  // reject empty "" on replay next turn even though OpenAI is lenient.
+  for (const tc of pendingToolCalls) {
+    const s = tc.argumentsJson.trim();
+    if (s === "") { tc.argumentsJson = "{}"; continue; }
+    try { JSON.parse(s); } catch { tc.argumentsJson = "{}"; }
+  }
+
+  const assistantToolCalls = pendingToolCalls.length
+    ? pendingToolCalls.map(tc => ({ id: tc.id, function: { name: tc.name, arguments: tc.argumentsJson } }))
+    : undefined;
+
+  const extras: Record<string, unknown> = {};
+  if (reasoning && reasoningField) extras[reasoningField] = reasoning;
+  if (reasoningDetailsByIndex.size > 0) {
+    extras.reasoning_details = [...reasoningDetailsByIndex.entries()]
+      .sort((a, b) => a[0] - b[0]).map(([, v]) => v);
+  }
+  return {
+    text,
+    toolCalls: pendingToolCalls,
+    assistantContent: text || null,
+    assistantToolCalls,
+    extras: Object.keys(extras).length > 0 ? extras : undefined,
+    usage,
+  };
+}

package/src/agent/system-prompt.ts

@@ -0,0 +1,151 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverProjectSkills, type Skill } from "./skills.js";
+
+/**
+ * Format skills for inline display in prompt.
+ * Shows name, description, and file path so the model can decide immediately
+ * whether to load a skill — no extra round-trip needed.
+ */
+export function formatSkillsBlock(skills: Skill[]): string {
+  if (skills.length === 0) return "";
+  return "# Available Skills\n\n"
+    + "Load a skill's full content from its file path with your file-reading tool when needed.\n\n"
+    + skills.map(s => `- **${s.name}**: ${s.description}\n  Path: ${s.filePath}`).join("\n\n");
+}
+
+import { CONFIG_DIR } from "../core/settings.js";
+const GLOBAL_AGENTS_MD = path.join(CONFIG_DIR, "AGENTS.md");
+
+// ── File caches ─────────────────────────────────────────────────────
+// Convention files (CLAUDE.md/AGENT.md) are walked synchronously from
+// CWD to root on every query. In practice they almost never change,
+// so a short TTL cache keyed by CWD avoids redundant filesystem walks.
+// The 5-second TTL is short enough to pick up edits quickly but long
+// enough to eliminate repeated walks within a multi-tool agent loop.
+
+const CACHE_TTL_MS = 5_000;
+
+/** TTL cache for convention files, keyed by resolved CWD. */
+let conventionCache: { cwd: string; result: string[]; expiry: number } | null = null;
+
+/** TTL cache for global AGENTS.md — changes extremely rarely. */
+let agentsMdCache: { result: string | null; expiry: number } | null = null;
+
+export function loadGlobalAgentsMd(): string | null {
+  const now = Date.now();
+  if (agentsMdCache && now < agentsMdCache.expiry) {
+    return agentsMdCache.result;
+  }
+  try {
+    const content = fs.readFileSync(GLOBAL_AGENTS_MD, "utf-8").trim();
+    const result = content || null;
+    agentsMdCache = { result, expiry: now + CACHE_TTL_MS };
+    return result;
+  } catch {
+    agentsMdCache = { result: null, expiry: now + CACHE_TTL_MS };
+    return null;
+  }
+}
+
+/** Resolve the absolute path to agent-sh's own docs directory. */
+const CODE_DIR = path.resolve(
+  path.dirname(fileURLToPath(import.meta.url)),
+  "../../",
+);
+
+/** File names to scan for project conventions (checked in order). */
+const CONVENTION_FILES = ["CLAUDE.md", "AGENT.md"];
+
+/**
+ * Scan from `dir` upward for project convention files.
+ * Returns contents ordered root-first (general → specific).
+ * Results are cached for CACHE_TTL_MS, keyed by resolved directory.
+ */
+function loadConventionFiles(dir: string): string[] {
+  const cwd = path.resolve(dir);
+  const now = Date.now();
+
+  if (conventionCache && conventionCache.cwd === cwd && now < conventionCache.expiry) {
+    return conventionCache.result;
+  }
+
+  const files: { path: string; content: string }[] = [];
+  let current = cwd;
+
+  while (true) {
+    for (const name of CONVENTION_FILES) {
+      const candidate = path.join(current, name);
+      try {
+        const content = fs.readFileSync(candidate, "utf-8").trim();
+        if (content) {
+          files.push({ path: candidate, content });
+          break;
+        }
+      } catch {
+        // File doesn't exist
+      }
+    }
+
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  files.reverse();
+  const result = files.map(f => `<!-- ${f.path} -->\n${f.content}`);
+  conventionCache = { cwd, result, expiry: now + CACHE_TTL_MS };
+  return result;
+}
+
+/**
+ * Identity — paragraph one of the system prompt. Surface-agnostic, cacheable.
+ */
+export const STATIC_IDENTITY = `You are ash, an AI coding assistant running inside agent-sh — a composable agent runtime with a small core and everything else, including the frontend you're attached to, layered on as extensions.`;
+
+/**
+ * The rest of the static prompt — code map, tool guidance, envelope contract.
+ * Follows the frontend surface description in the assembled prompt.
+ */
+export const STATIC_GUIDE = `agent-sh source and documentation live at ${CODE_DIR}. Read them when you need to understand how the runtime works, or when the user asks how to modify or extend it:
+- ${path.join(CODE_DIR, "docs")} — start with README.md; architecture.md and extensions.md cover the kernel boundary and extension API
+- ${path.join(CODE_DIR, "src")} — kernel in src/core, default backend in src/agent, shell host in src/shell, built-in extensions in src/extensions
+- ${path.join(CODE_DIR, "examples/extensions")} — reference extensions to study or copy when adding functionality
+
+# Tools
+
+Use your registered tools to investigate, search, read, and modify files.
+Each tool's description tells you when and how to use it; follow that
+guidance rather than assuming a particular tool exists. Tool output is
+returned to you for reasoning — the user doesn't see it directly.
+
+# Context Envelopes
+
+A turn may be preceded by either of two wrappers:
+- \`<query_context>\`: the user's situation when they sent this turn — the frontend and extensions inject what grounds the request here. Trust the most recent values over anything referenced earlier in history.
+- \`<dynamic_context>\`: current system state — in-flight work, mode markers, warnings.
+
+Either may be absent on any turn.`;
+
+/**
+ * CWD-scoped static context: project conventions (CLAUDE.md / AGENT.md)
+ * and discovered skills. Stable for a given cwd — callers should cache
+ * on cwd identity rather than rebuilding per LLM iteration.
+ */
+export function buildStaticByCwd(cwd: string): string {
+  const sections: string[] = [];
+
+  const conventions = loadConventionFiles(cwd);
+  if (conventions.length > 0) {
+    sections.push("# Project Conventions\n\n" + conventions.join("\n\n"));
+  }
+
+  const projectSkills = discoverProjectSkills(cwd);
+  const skillsBlock = formatSkillsBlock(projectSkills);
+  if (skillsBlock) {
+    sections.push(skillsBlock);
+  }
+
+  return sections.join("\n\n");
+}

package/src/agent/token-budget.ts

@@ -0,0 +1,12 @@
+/**
+ * Shared token-budget constants used by auto-compaction.
+ *
+ * RESPONSE_RESERVE: tokens reserved for the model's output.
+ * DEFAULT_CONTEXT_WINDOW: fallback when the active mode doesn't declare one.
+ */
+
+/** Response reserve — tokens reserved for the model's output. */
+export const RESPONSE_RESERVE = 8192;
+
+/** Fallback when contextWindow is unknown. */
+export const DEFAULT_CONTEXT_WINDOW = 60_000;