agent-sh 0.12.27 → 0.13.1

package/dist/agent/tool-registry.d.ts

@@ -1,15 +1,20 @@
-import type { ToolDefinition } from "./types.js";
+import type { ToolDefinition, ToolResult } from "./types.js";
 import type { ChatCompletionTool } from "../utils/llm-client.js";
+import type { HandlerFunctions } from "../utils/handler-registry.js";
 /**
- * Registry for agent tools. Holds tool definitions and converts them
- * to OpenAI-compatible function schemas for API calls.
+ * Registry for agent tools. Execution is routed through the named-handler
+ * registry under `tool:<name>` so extensions can `advise` a tool without
+ * owning it; duplicate `register` calls throw rather than silently evict.
  */
 export declare class ToolRegistry {
+    private handlers;
     private tools;
+    constructor(handlers: HandlerFunctions);
     register(tool: ToolDefinition): void;
     unregister(name: string): void;
     get(name: string): ToolDefinition | undefined;
     all(): ToolDefinition[];
-    /** Convert to OpenAI-compatible tool schemas for API calls. */
+    allView(): ToolDefinition[];
+    call(name: string, ...args: Parameters<ToolDefinition["execute"]>): Promise<ToolResult>;
     toAPITools(): ChatCompletionTool[];
 }

package/dist/agent/tool-registry.js

@@ -1,12 +1,25 @@
 import { registerReadOnlyTool, unregisterReadOnlyTool } from "./nuclear-form.js";
 /**
- * Registry for agent tools. Holds tool definitions and converts them
- * to OpenAI-compatible function schemas for API calls.
+ * Registry for agent tools. Execution is routed through the named-handler
+ * registry under `tool:<name>` so extensions can `advise` a tool without
+ * owning it; duplicate `register` calls throw rather than silently evict.
  */
 export class ToolRegistry {
+    handlers;
     tools = new Map();
+    constructor(handlers) {
+        this.handlers = handlers;
+    }
     register(tool) {
+        if (this.tools.has(tool.name)) {
+            throw new Error(`Tool "${tool.name}" already registered. Use ctx.agent.adviseTool() to wrap it.`);
+        }
         this.tools.set(tool.name, tool);
+        this.handlers.define(`tool:${tool.name}`, tool.execute.bind(tool));
+        this.handlers.define(`tool:${tool.name}:schema`, () => ({
+            description: tool.description,
+            parameters: tool.input_schema,
+        }));
         if (tool.readOnly)
             registerReadOnlyTool(tool.name);
         else
@@ -15,6 +28,8 @@ export class ToolRegistry {
     unregister(name) {
         this.tools.delete(name);
         unregisterReadOnlyTool(name);
+        // Handler entry intentionally retained so external advisors survive a
+        // reload of the tool's owner and reattach when the name re-registers.
     }
     get(name) {
         return this.tools.get(name);
@@ -22,9 +37,17 @@ export class ToolRegistry {
     all() {
         return Array.from(this.tools.values());
     }
-    /** Convert to OpenAI-compatible tool schemas for API calls. */
+    allView() {
+        return this.all().map((t) => {
+            const view = this.handlers.call(`tool:${t.name}:schema`);
+            return { ...t, description: view.description, input_schema: view.parameters };
+        });
+    }
+    call(name, ...args) {
+        return this.handlers.call(`tool:${name}`, ...args);
+    }
     toAPITools() {
-        return this.all().map((t) => ({
+        return this.allView().map((t) => ({
             type: "function",
             function: {
                 name: t.name,

package/dist/agent/tools/bash.d.ts

@@ -1,4 +1,4 @@
-import type { EventBus } from "../../event-bus.js";
+import type { EventBus } from "../../core/event-bus.js";
 import type { ToolDefinition } from "../types.js";
 export declare function createBashTool(opts: {
     getCwd: () => string;

package/dist/agent/tools/bash.js

@@ -1,10 +1,12 @@
-import { executeCommand, killSession } from "../../executor.js";
+import { executeCommand, killSession } from "../../utils/executor.js";
 export function createBashTool(opts) {
     return {
         name: "bash",
         description: "Execute a bash command in an isolated subprocess. Output is captured and returned. " +
             "Does not affect the user's shell state. " +
             "cwd is set to the working directory from the shell context. " +
+            "Keep commands focused; avoid long-running or blocking processes. " +
+            "Always check the returned exit code before treating output as success. " +
             "Do NOT use bash for file searching — use grep/glob instead. " +
             "Do NOT use bash for reading files — use read_file instead.",
         input_schema: {
@@ -27,7 +29,6 @@ export function createBashTool(opts) {
         },
         showOutput: true,
         modifiesFiles: true,
-        requiresPermission: true,
         getDisplayInfo: (args) => ({
             kind: "execute",
             icon: "▶",

package/dist/agent/tools/edit-file.js

@@ -63,7 +63,6 @@ export function createEditFileTool(getCwd) {
         },
         showOutput: true,
         modifiesFiles: true,
-        requiresPermission: true,
         getDisplayInfo: (args) => ({
             kind: "write",
             icon: "✎",

package/dist/agent/tools/glob.js

@@ -1,6 +1,6 @@
 import * as fs from "node:fs/promises";
 import * as path from "node:path";
-import { executeArgv } from "../../executor.js";
+import { executeArgv } from "../../utils/executor.js";
 import { resolveRgPath } from "../../utils/ripgrep-path.js";
 import { expandHome } from "./expand-home.js";
 export function createGlobTool(getCwd) {

package/dist/agent/tools/grep.js

@@ -1,4 +1,4 @@
-import { executeArgv } from "../../executor.js";
+import { executeArgv } from "../../utils/executor.js";
 import { resolveRgPath } from "../../utils/ripgrep-path.js";
 import { expandHome } from "./expand-home.js";
 export function createGrepTool(getCwd) {

package/dist/agent/tools/pwsh.d.ts

@@ -1,4 +1,4 @@
-import type { EventBus } from "../../event-bus.js";
+import type { EventBus } from "../../core/event-bus.js";
 import type { ToolDefinition } from "../types.js";
 export declare function createPwshTool(opts: {
     getCwd: () => string;

package/dist/agent/tools/pwsh.js

@@ -1,5 +1,5 @@
 import { spawnSync } from "node:child_process";
-import { executeArgv, killSession } from "../../executor.js";
+import { executeArgv, killSession } from "../../utils/executor.js";
 let cachedPwshPath;
 /** Resolve a usable PowerShell binary, or null if none is on PATH.
  *  Prefers PowerShell 7+ (`pwsh`), falls back to Windows PowerShell (`powershell`). */
@@ -55,7 +55,6 @@ export function createPwshTool(opts) {
         },
         showOutput: true,
         modifiesFiles: true,
-        requiresPermission: true,
         getDisplayInfo: () => ({
             kind: "execute",
             icon: "▶",

package/dist/agent/tools/read-file.js

@@ -46,8 +46,10 @@ export function createReadFileTool(getCwd, cache) {
             const reqLimit = args.limit;
             try {
                 const stat = await fs.stat(absPath);
-                // Deduplication: if the file hasn't changed and same range, return stub
-                if (cache) {
+                // Deduplication: if the file hasn't changed and same range, return stub.
+                // bypass_cache lets in-process callers consume content as a value
+                // rather than a tool_result, where the dedup stub would be meaningless.
+                if (cache && !args.bypass_cache) {
                     const prev = cache.get(absPath);
                     if (prev &&
                         prev.mtimeMs === stat.mtimeMs &&
@@ -83,8 +85,9 @@ export function createReadFileTool(getCwd, cache) {
                 const suffix = truncated
                     ? `\n[${lines.length - end} more lines, use offset=${end + 1} to continue]`
                     : "";
-                // Update cache on successful read
-                if (cache) {
+                // Skip cache write for in-process callers — they shouldn't poison
+                // the LLM-facing dedup state.
+                if (cache && !args.bypass_cache) {
                     cache.set(absPath, {
                         mtimeMs: stat.mtimeMs,
                         offset: reqOffset,

package/dist/agent/tools/write-file.js

@@ -23,7 +23,6 @@ export function createWriteFileTool(getCwd) {
         },
         showOutput: true,
         modifiesFiles: true,
-        requiresPermission: true,
         getDisplayInfo: (args) => ({
             kind: "write",
             icon: "✎",

package/dist/agent/types.d.ts

@@ -47,6 +47,9 @@ export interface ToolDisplayInfo {
     /** Custom icon character for TUI display (e.g., "◆", "⌕"). When set, the TUI shows
      *  icon + detail only. When absent, the tool name is shown alongside the detail. */
     icon?: string;
+    /** highlight.js-style language identifier ("scheme", "python", …) for
+     *  renderers that syntax-highlight tool source. Omit for plain text. */
+    sourceLanguage?: string;
 }
 /** Interactive UI session — imperative control over rendering + input. */
 export interface InteractiveSession<T> {
@@ -70,6 +73,16 @@ export interface ToolExecutionContext {
     /** Aborted on Ctrl-C — tools with subprocess work should listen and clean up. */
     signal?: AbortSignal;
 }
+/** LLM-facing view of a tool — what `adviseToolSchema` advisors return. */
+export interface ToolSchemaView {
+    description: string;
+    parameters: Record<string, unknown>;
+}
+/** LLM-facing view of a skill — what `adviseSkill` advisors return. */
+export interface SkillView {
+    description: string;
+    filePath: string;
+}
 export interface ToolDefinition {
     name: string;
     /** Short label for TUI display (e.g. "search" instead of "ads_search"). Defaults to name. */
@@ -84,8 +97,6 @@ export interface ToolDefinition {
     /** Results are re-fetchable; nuclear compaction drops the tool_result
      *  body on eviction (like the builtin read_file/grep/ls). Default: false. */
     readOnly?: boolean;
-    /** Whether to gate execution via permission:request (default: false). */
-    requiresPermission?: boolean;
     /** Derive display metadata (icon kind, file paths) for the TUI. */
     getDisplayInfo?: (args: Record<string, unknown>) => ToolDisplayInfo;
     /**
@@ -101,4 +112,8 @@ export interface ToolDefinition {
      * Extensions can further override via bus.onPipe("agent:tool-completed", ...).
      */
     formatResult?: (args: Record<string, unknown>, result: ToolResult) => ToolResultDisplay;
+    /** Override the agent-loop's per-tool-result truncation cap (default 16 KB).
+     *  Use for tools that bundle multiple operations and legitimately produce
+     *  larger output (interpreter substrates etc.). */
+    maxResultBytes?: number;
 }

package/dist/cli/auth/cli.d.ts

@@ -0,0 +1 @@
+export declare function runAuth(args: string[]): Promise<void>;

package/dist/cli/auth/cli.js

@@ -0,0 +1,216 @@
+import * as readline from "node:readline";
+import { palette as p } from "../../utils/palette.js";
+import { KNOWN_PROVIDERS, KEYS_PATH, loadKeysFile, saveKeysFile, resolveApiKey, listAllProviders, findProvider as findProviderById, } from "./keys.js";
+export async function runAuth(args) {
+    const sub = args[0];
+    if (!sub || sub === "--help" || sub === "-h") {
+        printHelp();
+        return;
+    }
+    if (sub === "login") {
+        await runLogin(args[1]);
+        return;
+    }
+    if (sub === "logout") {
+        runLogout(args[1]);
+        return;
+    }
+    if (sub === "list" || sub === "ls" || sub === "status") {
+        runList();
+        return;
+    }
+    console.error(`agent-sh auth: unknown subcommand "${sub}"`);
+    printHelp();
+    process.exit(1);
+}
+function printHelp() {
+    const builtins = KNOWN_PROVIDERS.map((p) => p.id).join(" | ");
+    console.log(`agent-sh auth — manage API keys for providers\n\n` +
+        `Usage:\n` +
+        `  agent-sh auth login [provider]   Store an API key (prompts if omitted)\n` +
+        `  agent-sh auth logout <provider>  Remove a stored key\n` +
+        `  agent-sh auth list               Show configured providers and key sources\n\n` +
+        `Built-in providers: ${builtins}\n` +
+        `Custom providers declared in settings.json are also accepted by id.\n\n` +
+        `Keys are stored in ${KEYS_PATH} (chmod 0600).\n` +
+        `Resolution order: settings.json > keys.json > env var.\n`);
+}
+async function runLogin(providerArg) {
+    let provider;
+    if (providerArg) {
+        const id = providerArg.toLowerCase();
+        if (!/^[a-z0-9][a-z0-9_\-./:]*$/.test(id)) {
+            console.error(`agent-sh auth: invalid provider id "${providerArg}".`);
+            process.exit(1);
+        }
+        provider = findProviderById(id);
+        if (!provider) {
+            console.error(`${p.warning}Note:${p.reset} no built-in or settings.json provider named "${id}". ` +
+                `Storing the key anyway — it will resolve once an extension or settings.json declares the provider.`);
+            provider = { id, label: id, unattached: true };
+        }
+    }
+    else {
+        provider = await pickProvider();
+    }
+    if (!provider)
+        process.exit(1);
+    const key = await promptSecret(`Enter ${provider.label} API key: `);
+    const trimmed = key.trim();
+    if (!trimmed) {
+        console.error("agent-sh auth: empty key, nothing saved.");
+        process.exit(1);
+    }
+    if (/\s/.test(trimmed)) {
+        console.error("agent-sh auth: key contains whitespace; aborting.");
+        process.exit(1);
+    }
+    const keys = { ...loadKeysFile() };
+    keys[provider.id] = trimmed;
+    saveKeysFile(keys);
+    const resolved = resolveApiKey(provider.id);
+    console.log(`${p.success}✓${p.reset} Saved ${provider.label} key to ${KEYS_PATH}`);
+    if (resolved.source !== "keys-file") {
+        console.log(`${p.warning}Note:${p.reset} an existing ${sourceLabel(resolved.source, provider)} entry ` +
+            `takes precedence; the stored key is shadowed until you remove it.`);
+    }
+}
+function runLogout(providerArg) {
+    if (!providerArg) {
+        console.error("Usage: agent-sh auth logout <provider>");
+        process.exit(1);
+    }
+    const id = providerArg.toLowerCase();
+    const keys = { ...loadKeysFile() };
+    if (!(id in keys)) {
+        console.log(`agent-sh auth: no stored key for ${id}.`);
+        return;
+    }
+    delete keys[id];
+    saveKeysFile(keys);
+    console.log(`${p.success}✓${p.reset} Removed ${id} key from ${KEYS_PATH}`);
+}
+function runList() {
+    const providers = listAllProviders();
+    console.log("Provider key status:\n");
+    const idWidth = Math.max(...providers.map((p) => p.id.length));
+    for (const info of providers) {
+        const resolved = resolveApiKey(info.id);
+        const padded = info.id.padEnd(idWidth);
+        const marker = info.custom
+            ? `  ${p.dim}custom${p.reset}`
+            : info.unattached
+                ? `  ${p.dim}unattached${p.reset}`
+                : "";
+        if (resolved.key) {
+            console.log(`  ${p.success}●${p.reset} ${padded}  ${p.dim}(${sourceLabel(resolved.source, info)})${p.reset}${marker}`);
+        }
+        else {
+            console.log(`  ${p.muted}○${p.reset} ${padded}  ${p.dim}(not configured)${p.reset}${marker}`);
+        }
+    }
+    const example = providers[0].id;
+    console.log(`\n${p.muted}Login with:${p.reset} agent-sh auth login <id>   ${p.dim}(e.g. agent-sh auth login ${example})${p.reset}`);
+}
+async function pickProvider() {
+    if (!process.stdin.isTTY) {
+        console.error("agent-sh auth: no provider specified and stdin is not a TTY.");
+        return null;
+    }
+    const providers = listAllProviders();
+    console.log("Select a provider:");
+    providers.forEach((info, i) => {
+        const resolved = resolveApiKey(info.id);
+        const tag = resolved.key
+            ? `${p.dim}(currently from ${sourceLabel(resolved.source, info)})${p.reset}`
+            : `${p.dim}(not configured)${p.reset}`;
+        const labelStr = info.custom
+            ? `${p.dim}custom${p.reset}`
+            : info.unattached
+                ? `${p.dim}unattached${p.reset}`
+                : `${p.dim}${info.label}${p.reset}`;
+        console.log(`  ${i + 1}) ${info.id.padEnd(12)} ${labelStr}  ${tag}`);
+    });
+    const answer = await promptLine("Choice [1]: ");
+    const idx = answer.trim() === "" ? 0 : Number(answer.trim()) - 1;
+    if (!Number.isInteger(idx) || idx < 0 || idx >= providers.length) {
+        console.error("agent-sh auth: invalid selection.");
+        return null;
+    }
+    return providers[idx];
+}
+function promptLine(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    return new Promise((resolve) => {
+        rl.question(question, (answer) => {
+            rl.close();
+            resolve(answer);
+        });
+    });
+}
+function promptSecret(question) {
+    return new Promise((resolve) => {
+        if (!process.stdin.isTTY) {
+            let buf = "";
+            process.stdin.setEncoding("utf-8");
+            process.stdin.on("data", (chunk) => {
+                buf += chunk;
+                const nl = buf.indexOf("\n");
+                if (nl >= 0) {
+                    process.stdin.pause();
+                    resolve(buf.slice(0, nl).replace(/\r$/, ""));
+                }
+            });
+            return;
+        }
+        const stdin = process.stdin;
+        const stdout = process.stdout;
+        const wasRaw = stdin.isRaw;
+        stdout.write(question);
+        stdin.resume();
+        stdin.setRawMode(true);
+        stdin.setEncoding("utf-8");
+        let buf = "";
+        const finish = (value) => {
+            stdout.write("\n");
+            stdin.removeListener("data", onData);
+            stdin.setRawMode(wasRaw);
+            stdin.pause();
+            if (value === null)
+                process.exit(130);
+            resolve(value);
+        };
+        const onData = (ch) => {
+            for (const c of ch) {
+                if (c === "\n" || c === "\r" || c === "\x04") {
+                    finish(buf);
+                    return;
+                }
+                if (c === "\x03") {
+                    finish(null);
+                    return;
+                }
+                if (c === "\x7f" || c === "\b") {
+                    if (buf.length > 0) {
+                        buf = buf.slice(0, -1);
+                        stdout.write("\b \b");
+                    }
+                    continue;
+                }
+                if (c < " ")
+                    continue;
+                buf += c;
+                stdout.write("*");
+            }
+        };
+        stdin.on("data", onData);
+    });
+}
+function sourceLabel(source, info) {
+    switch (source) {
+        case "settings": return "settings.json";
+        case "keys-file": return "keys.json";
+        case "env": return info ? `$${info.envVar}` : "env var";
+        default: return source;
+    }
+}

package/dist/cli/auth/keys.d.ts

@@ -0,0 +1,31 @@
+export declare const KEYS_PATH: string;
+export interface ProviderAuthInfo {
+    id: string;
+    label: string;
+    /** Conventional env var. Absent for user-declared providers. */
+    envVar?: string;
+    /** True for entries declared in settings.json (vs. a built-in). */
+    custom?: boolean;
+    /** True for ids only present in keys.json — likely owned by an extension
+     *  that registers a provider at runtime. */
+    unattached?: boolean;
+}
+export declare const KNOWN_PROVIDERS: ProviderAuthInfo[];
+/** Built-ins merged with settings-declared providers, plus any ids that only
+ *  appear in keys.json (likely registered by an extension at runtime). */
+export declare function listAllProviders(): ProviderAuthInfo[];
+/** Resolve an id against known + settings entries only. Returns null for
+ *  unattached or unknown ids — callers decide whether to accept them. */
+export declare function findProvider(id: string): ProviderAuthInfo | null;
+export type KeySource = "settings" | "keys-file" | "env" | "none";
+export interface ResolvedKey {
+    key: string | null;
+    source: KeySource;
+}
+type KeysFile = Record<string, string>;
+export declare function loadKeysFile(): KeysFile;
+export declare function saveKeysFile(keys: KeysFile): void;
+export declare function reloadKeysFile(): void;
+export declare function resolveApiKey(providerId: string): ResolvedKey;
+export declare function anyProviderConfigured(): boolean;
+export {};

package/dist/cli/auth/keys.js

@@ -0,0 +1,102 @@
+// Resolution order: settings.json → keys.json → env var.
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { CONFIG_DIR, getSettings, expandEnvVars } from "../../core/settings.js";
+export const KEYS_PATH = path.join(CONFIG_DIR, "keys.json");
+export const KNOWN_PROVIDERS = [
+    { id: "openai", label: "OpenAI", envVar: "OPENAI_API_KEY" },
+    { id: "openrouter", label: "OpenRouter", envVar: "OPENROUTER_API_KEY" },
+    { id: "deepseek", label: "DeepSeek", envVar: "DEEPSEEK_API_KEY" },
+];
+/** Built-ins merged with settings-declared providers, plus any ids that only
+ *  appear in keys.json (likely registered by an extension at runtime). */
+export function listAllProviders() {
+    const out = [...KNOWN_PROVIDERS];
+    const seen = new Set(out.map((p) => p.id));
+    const settingsProviders = getSettings().providers ?? {};
+    for (const id of Object.keys(settingsProviders)) {
+        if (seen.has(id))
+            continue;
+        out.push({ id, label: id, custom: true });
+        seen.add(id);
+    }
+    for (const id of Object.keys(loadKeysFile())) {
+        if (seen.has(id))
+            continue;
+        out.push({ id, label: id, unattached: true });
+        seen.add(id);
+    }
+    return out;
+}
+/** Resolve an id against known + settings entries only. Returns null for
+ *  unattached or unknown ids — callers decide whether to accept them. */
+export function findProvider(id) {
+    const lower = id.toLowerCase();
+    const known = KNOWN_PROVIDERS.find((p) => p.id === lower);
+    if (known)
+        return known;
+    const settings = getSettings().providers ?? {};
+    if (lower in settings)
+        return { id: lower, label: lower, custom: true };
+    return null;
+}
+let cached = null;
+export function loadKeysFile() {
+    if (cached)
+        return cached;
+    try {
+        const raw = fs.readFileSync(KEYS_PATH, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            cached = parsed;
+        }
+        else {
+            cached = {};
+        }
+    }
+    catch (err) {
+        if (err instanceof SyntaxError) {
+            console.error(`[agent-sh] Warning: invalid JSON in ${KEYS_PATH}: ${err.message}`);
+        }
+        cached = {};
+    }
+    return cached;
+}
+export function saveKeysFile(keys) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const tmp = `${KEYS_PATH}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(keys, null, 2) + "\n", { mode: 0o600 });
+    fs.renameSync(tmp, KEYS_PATH);
+    try {
+        fs.chmodSync(KEYS_PATH, 0o600);
+    }
+    catch { /* best effort */ }
+    cached = { ...keys };
+}
+export function reloadKeysFile() {
+    cached = null;
+}
+export function resolveApiKey(providerId) {
+    const settingsKey = getSettings().providers?.[providerId]?.apiKey;
+    if (settingsKey) {
+        const expanded = expandEnvVars(settingsKey);
+        if (expanded)
+            return { key: expanded, source: "settings" };
+    }
+    const fileKey = loadKeysFile()[providerId];
+    if (fileKey)
+        return { key: fileKey, source: "keys-file" };
+    const info = KNOWN_PROVIDERS.find((p) => p.id === providerId);
+    if (info?.envVar) {
+        const envKey = process.env[info.envVar];
+        if (envKey)
+            return { key: envKey, source: "env" };
+    }
+    return { key: null, source: "none" };
+}
+export function anyProviderConfigured() {
+    // openai-compatible activates on OPENAI_BASE_URL alone (keyless local servers).
+    if (process.env.OPENAI_BASE_URL)
+        return true;
+    return listAllProviders().some((p) => resolveApiKey(p.id).key);
+}