agent-dir 1.0.0 → 1.1.1

package/dist/bin/agent-dir.js

@@ -5,6 +5,7 @@ import { createRequire } from "node:module";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { parseArgs } from "node:util";
+import { CodeGraphIntegration } from "../src/codegraph.js";
 import { configPath, loadConfig, mergeProfile, saveConfig } from "../src/config.js";
 import { printBanner, printHelp, printRequestHeader } from "../src/logging.js";
 import { startServer } from "../src/server.js";
@@ -445,6 +446,10 @@ if (allowedCommands)
 if (commandConfig.blacklistedCommands?.length) {
     bannerOptions.blacklistedCommands = commandConfig.blacklistedCommands;
 }
+const codeGraph = new CodeGraphIntegration(directory);
+const codeGraphCapability = await codeGraph.prepare();
+if (codeGraphCapability.tool)
+    bannerOptions.codeGraph = true;
 printBanner(bannerOptions);
 const telemetrySessionId = randomUUID();
 const server = await startServer({
@@ -452,18 +457,26 @@ const server = await startServer({
     port,
     token,
     commandConfig,
+    codeGraph,
     telemetry: {
         ...(config.telemetry ?? { level: "none" }),
         ...(telemetryConfigId ? { configId: telemetryConfigId } : {}),
         sessionId: telemetrySessionId,
         persist: true,
     },
+}).catch(async (error) => {
+    await codeGraph.close();
+    throw error;
 });
 let tunnelResult;
-console.log("  ✓ SERVER ONLINE");
-console.log(`    Local target : http://127.0.0.1:${port}`);
-console.log("    Auth         : Bearer token");
-console.log("    Token        : <configured>");
+console.log(`  ${"╭─ SERVER ONLINE ".padEnd(76, "─")}╮`
+    .replace("╭", "\x1b[92m╭")
+    .replace(/─/g, "─\x1b[92m")
+    .replace("╮", "╮\x1b[0m"));
+console.log(`  \x1b[92m│\x1b[0m ${"Local target".padEnd(14)}: http://127.0.0.1:${port}`);
+console.log(`  \x1b[92m│\x1b[0m ${"Auth".padEnd(14)}: Bearer token`);
+console.log(`  \x1b[92m│\x1b[0m ${"Token".padEnd(14)}: <configured>`);
+console.log(`  \x1b[92m╰${"─".repeat(74)}╯\x1b[0m`);
 if (tunnel !== "none") {
     try {
         tunnelResult = await startTunnel({

package/dist/src/codegraph.d.ts

@@ -18,6 +18,7 @@ export declare class CodeGraphIntegration {
     private readonly pending;
     constructor(root: string);
     capability(): Promise<CodeGraphCapability>;
+    prepare(): Promise<CodeGraphCapability>;
     explore(query: string, maxFiles?: number): Promise<Record<string, unknown>>;
     close(): Promise<void>;
     private detect;

package/dist/src/codegraph.js

@@ -27,6 +27,18 @@ export class CodeGraphIntegration {
             this.capabilityPromise = this.detect();
         return this.capabilityPromise;
     }
+    async prepare() {
+        const capability = await this.capability();
+        if (capability.status === "available") {
+            try {
+                await this.ensureStarted();
+            }
+            catch {
+                // Keep Agent Dir startup available even if CodeGraph fails to start.
+            }
+        }
+        return this.capability();
+    }
     async explore(query, maxFiles) {
         const capability = await this.capability();
         if (capability.status === "not_installed")

package/dist/src/logging.d.ts

@@ -11,6 +11,7 @@ export declare function printBanner(options: {
     npmScripts?: string[];
     commands?: string[];
     blacklistedCommands?: string[];
+    codeGraph?: boolean;
 }): void;
 export declare function printRequestLog(entry: RequestLog): void;
 export declare function logRequest(entry: RequestLog): void;

package/dist/src/logging.js

@@ -4,11 +4,11 @@ const MAGENTA = "\x1b[35m";
 const YELLOW = "\x1b[33m";
 const RED = "\x1b[31m";
 const GREEN = "\x1b[32m";
-const BLUE = "\x1b[34m";
 const BRIGHT_BLUE = "\x1b[94m";
 const BRIGHT_CYAN = "\x1b[96m";
 const BRIGHT_MAGENTA = "\x1b[95m";
 const BRIGHT_YELLOW = "\x1b[93m";
+const BRIGHT_GREEN = "\x1b[92m";
 const writeLine = (line = "") => {
     process.stdout.write(`${line}\r\n`);
 };
@@ -56,6 +56,67 @@ const TOOL_COLORS = {
 };
 const NARROW_TOOL_ICONS = new Set(["✎", "✖", "⚙", "⌘", "↪", "↗"]);
 const TOOL_ICON_SLOT_WIDTH = 3;
+const DIM = "\x1b[90m";
+function visibleLength(value) {
+    const esc = String.fromCharCode(27);
+    const plain = value
+        .replaceAll(`${esc}[90m`, "")
+        .replaceAll(`${esc}[0m`, "")
+        .replaceAll(`${esc}[92m`, "")
+        .replaceAll(`${esc}[96m`, "")
+        .replaceAll(`${esc}[95m`, "")
+        .replaceAll(`${esc}[94m`, "")
+        .replaceAll(`${esc}[93m`, "")
+        .replaceAll(`${esc}[32m`, "")
+        .replaceAll(`${esc}[36m`, "")
+        .replaceAll(`${esc}[35m`, "")
+        .replaceAll(`${esc}[34m`, "")
+        .replaceAll(`${esc}[33m`, "");
+    let width = 0;
+    for (const character of plain) {
+        const code = character.codePointAt(0) ?? 0;
+        width +=
+            code >= 0x1100 &&
+                (code <= 0x115f ||
+                    code === 0x2329 ||
+                    code === 0x232a ||
+                    (code >= 0x2e80 && code <= 0xa4cf) ||
+                    (code >= 0xac00 && code <= 0xd7a3) ||
+                    (code >= 0xf900 && code <= 0xfaff) ||
+                    (code >= 0xfe10 && code <= 0xfe19) ||
+                    (code >= 0xfe30 && code <= 0xfe6f) ||
+                    (code >= 0xff00 && code <= 0xff60) ||
+                    (code >= 0xffe0 && code <= 0xffe6) ||
+                    (code >= 0x1f300 && code <= 0x1faff))
+                ? 2
+                : 1;
+    }
+    return width;
+}
+const BOX_WIDTH = 76;
+function boxTop(label, borderColor, width = BOX_WIDTH) {
+    const heading = `─ ${label} `;
+    return `  ${color(`╭${heading}${"─".repeat(Math.max(1, width - visibleLength(heading) - 2))}╮`, borderColor)}`;
+}
+function boxContent(content, borderColor, width = BOX_WIDTH) {
+    const padding = Math.max(0, width - visibleLength(content) - 3);
+    return `  ${color("│", borderColor)} ${content}${" ".repeat(padding)}${color("│", borderColor)}`;
+}
+function boxBottom(borderColor, width = BOX_WIDTH) {
+    return `  ${color(`╰${"─".repeat(width - 2)}╯`, borderColor)}`;
+}
+function printGrid(items, columns = 2) {
+    const width = Math.max(40, Math.min(100, (process.stdout.columns || 100) - 4));
+    const columnWidth = Math.floor(width / columns);
+    for (let index = 0; index < items.length; index += columns) {
+        const row = items.slice(index, index + columns);
+        writeLine(`  ${row
+            .map((item) => item +
+            " ".repeat(Math.max(1, columnWidth -
+                item.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g"), "").length)))
+            .join("")}`);
+    }
+}
 function toolIcon(name) {
     return TOOL_ICONS[name] ?? MCP_METHOD_ICONS[name] ?? "•";
 }
@@ -112,54 +173,51 @@ export function printHelp() {
 }
 export function printBanner(options) {
     writeLine("");
-    const banner = [
-        "╭──────────────────────────────────────────────────────────────╮",
-        "│                         AGENT-DIR                            │",
-        "╰──────────────────────────────────────────────────────────────╯",
-    ];
-    const gradient = [BRIGHT_CYAN, BRIGHT_BLUE, BRIGHT_MAGENTA];
-    for (let i = 0; i < banner.length; i++) {
-        writeLine(color(banner[i] ?? "", gradient[i] ?? BRIGHT_CYAN));
-    }
-    writeLine("");
-    writeLine(`  Directory    ${options.root}`);
-    writeLine(`  Port         ${options.port}`);
-    writeLine(`  Config       ${options.profileName ?? "CLI options"}`);
-    writeLine(`  Tunnel       ${options.tunnel}`);
-    if (options.blacklistedCommands?.length) {
-        writeLine(`  Blocked      ${options.blacklistedCommands.join(", ")}`);
-    }
+    writeLine(color("  ╭──────────────────────────────────────────────────────────────────────────────╮", BRIGHT_CYAN));
+    writeLine(`${color("  │", BRIGHT_CYAN)}  ${color("AGENT", BRIGHT_CYAN)}${color("·", BRIGHT_MAGENTA)}${color("DIR", BRIGHT_BLUE)}  ${color("LOCAL PROJECT BRIDGE", BRIGHT_MAGENTA)}`);
+    writeLine(color("  ╰──────────────────────────────────────────────────────────────────────────────╯", BRIGHT_CYAN));
+    writeLine(`  ${color("● SESSION", BRIGHT_GREEN)}  ${color(options.profileName ?? "CLI options", BRIGHT_CYAN)}  ${color("│", DIM)}  ${color(options.tunnel.toUpperCase(), BRIGHT_MAGENTA)}  ${color("│", DIM)}  ${color(`PORT ${options.port}`, BRIGHT_BLUE)}`);
+    writeLine(boxTop("PROJECT", BRIGHT_CYAN));
+    writeLine(boxContent(`${color("DIR", DIM)}     ${options.root}`, BRIGHT_CYAN));
     if (options.subdomain)
-        writeLine(`  Domain       https://${options.subdomain}.wormhole.bar`);
+        writeLine(boxContent(`${color("DOMAIN", DIM)}  ${color(`https://${options.subdomain}.wormhole.bar`, BRIGHT_GREEN)}`, BRIGHT_CYAN));
     if (options.hostname)
-        writeLine(`  Domain       https://${options.hostname}`);
+        writeLine(boxContent(`${color("DOMAIN", DIM)}  ${color(`https://${options.hostname}`, BRIGHT_GREEN)}`, BRIGHT_CYAN));
+    if (options.blacklistedCommands?.length)
+        writeLine(boxContent(`${color("BLOCKED", BRIGHT_YELLOW)}  ${options.blacklistedCommands.join(", ")}`, BRIGHT_CYAN));
+    writeLine(boxBottom(BRIGHT_CYAN));
     writeLine("");
-    writeLine("  MCP");
-    writeLine(`    ${color("⚡ /mcp", CYAN)}`);
+    writeLine(boxTop("MCP ENDPOINT", BRIGHT_MAGENTA));
+    writeLine(boxContent(`${color("⚡ POST", BRIGHT_YELLOW)} ${color("/mcp", BRIGHT_CYAN)}  ${color("JSON-RPC · tools · resources", DIM)}`, BRIGHT_MAGENTA));
+    writeLine(boxBottom(BRIGHT_MAGENTA));
     writeLine("");
-    writeLine("  TOOLS");
-    writeLine(`    ${color(toolLabel("project_context"), BRIGHT_CYAN)}`);
-    writeLine(`    ${color(toolLabel("find_files"), CYAN)}`);
-    writeLine(`    ${color(toolLabel("search_code"), BRIGHT_CYAN)}`);
-    writeLine(`    ${color(toolLabel("find_symbol"), GREEN)}`);
-    writeLine(`    ${color(toolLabel("find_references"), GREEN)}`);
-    writeLine(`    ${color(toolLabel("read_range"), GREEN)}`);
-    writeLine(`    ${color(toolLabel("apply_changes"), BRIGHT_MAGENTA)}`);
-    writeLine(`    ${color(toolLabel("validate"), BRIGHT_YELLOW)}`);
-    writeLine(`    ${color(toolLabel("run_npm_batch"), BRIGHT_BLUE)}`);
-    writeLine(`    ${color(toolLabel("run_command_batch"), BRIGHT_CYAN)}`);
-    writeLine(`    ${color(toolLabel("file_info"), YELLOW)}`);
+    writeLine(boxTop("AVAILABLE TOOLS", BRIGHT_BLUE));
+    const toolRows = [
+        color(toolLabel("project_context"), BRIGHT_CYAN),
+        color(toolLabel("find_files"), CYAN),
+        color(toolLabel("search_code"), BRIGHT_CYAN),
+        color(toolLabel("find_symbol"), GREEN),
+        color(toolLabel("find_references"), GREEN),
+        color(toolLabel("read_range"), GREEN),
+        color(toolLabel("apply_changes"), BRIGHT_MAGENTA),
+        color(toolLabel("validate"), BRIGHT_YELLOW),
+        color(toolLabel("run_npm_batch"), BRIGHT_BLUE),
+        color(toolLabel("run_command_batch"), BRIGHT_CYAN),
+        color(toolLabel("file_info"), YELLOW),
+    ];
+    if (options.codeGraph)
+        toolRows.push(color(toolLabel("codegraph_explore"), BRIGHT_MAGENTA));
+    printGrid(toolRows, 2);
+    writeLine(boxBottom(BRIGHT_BLUE));
     writeLine("");
     if (options.npmScripts?.length) {
-        writeLine("  NPM COMMANDS");
-        for (const script of options.npmScripts)
-            writeLine(`    ${color("•", BLUE)} npm run ${script}`);
+        writeLine(`  ${color("◆ NPM SCRIPTS", BRIGHT_YELLOW)}  ${color("· scripts are allowlisted", "\x1b[90m")}`);
+        printGrid(options.npmScripts.map((script) => `${color("›", BRIGHT_YELLOW)} ${color("npm run", BRIGHT_YELLOW)} ${color(script, BRIGHT_CYAN)}`), 2);
         writeLine("");
     }
     if (options.commands?.length) {
-        writeLine("  ALLOWED COMMANDS");
-        for (const command of options.commands)
-            writeLine(`    ${color("•", CYAN)} ${command}`);
+        writeLine(`  ${color("◆ COMMAND ALLOWLIST", BRIGHT_GREEN)}  ${color("· shell access is restricted", "\x1b[90m")}`);
+        printGrid(options.commands.map((command) => `${color("›", BRIGHT_GREEN)} ${color(command, CYAN)}`), 3);
         writeLine("");
     }
 }
@@ -206,7 +264,7 @@ export function logRequest(entry) {
 }
 export function printRequestHeader() {
     writeLine("");
-    writeLine("  ──────────────────────────────────────────────────────────────");
-    writeLine("  [Request logs]");
-    writeLine("  ──────────────────────────────────────────────────────────────");
+    writeLine(boxTop("REQUEST STREAM", BRIGHT_MAGENTA));
+    writeLine(boxContent(color("Live MCP traffic · method · status · tool activity", DIM), BRIGHT_MAGENTA));
+    writeLine(boxBottom(BRIGHT_MAGENTA));
 }

package/dist/src/mcp.d.ts

@@ -1,3 +1,4 @@
+import { CodeGraphIntegration } from "./codegraph.js";
 import { TelemetryRecorder } from "./telemetry/recorder.js";
 import type { TelemetryConfig } from "./telemetry/types.js";
 import type { CommandConfig } from "./types.js";
@@ -6,6 +7,6 @@ interface McpHandler {
     closeSubscriptions: () => void;
     telemetrySnapshot: () => ReturnType<TelemetryRecorder["snapshot"]>;
 }
-export declare function createMcpHandler(root: string, commandConfig?: CommandConfig, telemetry?: TelemetryConfig): McpHandler;
+export declare function createMcpHandler(root: string, commandConfig?: CommandConfig, telemetry?: TelemetryConfig, codeGraphIntegration?: CodeGraphIntegration): McpHandler;
 export declare function validateMcpParamHeaders(inputSchema: Record<string, unknown>, args: Record<string, unknown>, headers: Headers): string | undefined;
 export {};

package/dist/src/mcp.js

@@ -162,8 +162,8 @@ function tool(name, description, properties, outputSchema, required = []) {
         outputSchema,
     };
 }
-export function createMcpHandler(root, commandConfig = {}, telemetry = { level: "none" }) {
-    const codeGraph = new CodeGraphIntegration(root);
+export function createMcpHandler(root, commandConfig = {}, telemetry = { level: "none" }, codeGraphIntegration) {
+    const codeGraph = codeGraphIntegration ?? new CodeGraphIntegration(root);
     const telemetryRecorder = new TelemetryRecorder({
         level: telemetry.level,
         persist: telemetry.persist ?? false,
@@ -774,12 +774,12 @@ async function callTool(name, args, root, npmAllowed, allowedCommands, blacklist
         const serialized = JSON.stringify(result);
         if (Buffer.byteLength(serialized, "utf8") <= maxBytes)
             return result;
-        return {
+        return completeToolResult({
             truncated: true,
             originalBytes: Buffer.byteLength(serialized, "utf8"),
             message: "CodeGraph response exceeded the output budget. Narrow the query or lower maxFiles.",
-            preview: truncateText(serialized, Math.min(2_000, maxBytes - 256)).text,
-        };
+            preview: truncateText(serialized, Math.min(2_000, Math.max(256, maxBytes - 512))).text,
+        });
     }
     switch (name) {
         case "read_range": {

package/dist/src/server.d.ts

@@ -2,7 +2,7 @@ import type { ServerOptions } from "./types.js";
 export interface ServerHandle {
     close: () => Promise<void>;
 }
-export declare function startServer({ root, port, token, commandConfig, telemetry, }: ServerOptions): Promise<ServerHandle>;
+export declare function startServer({ root, port, token, commandConfig, telemetry, codeGraph, }: ServerOptions): Promise<ServerHandle>;
 export declare function validateMcpHeaders(request: Request, message: Record<string, unknown> | null): Response | undefined;
 export declare function getMcpLog(body: Buffer, responseBody?: unknown): {
     name: string;

package/dist/src/server.js

@@ -9,8 +9,8 @@ const REQUEST_TIMEOUT_MS = 120_000;
 const HEADERS_TIMEOUT_MS = 30_000;
 const KEEP_ALIVE_TIMEOUT_MS = 5_000;
 const HEALTH_PATH = "/__health";
-export function startServer({ root, port, token, commandConfig = {}, telemetry = { level: "none" }, }) {
-    const mcp = createMcpHandler(root, commandConfig, telemetry);
+export function startServer({ root, port, token, commandConfig = {}, telemetry = { level: "none" }, codeGraph, }) {
+    const mcp = createMcpHandler(root, commandConfig, telemetry, codeGraph);
     const httpTelemetry = new TelemetryRecorder({
         level: telemetry.level,
         persist: telemetry.persist ?? false,
@@ -138,10 +138,15 @@ export function startServer({ root, port, token, commandConfig = {}, telemetry =
     return new Promise((resolve, reject) => {
         server.once("error", reject);
         server.listen(port, "127.0.0.1", () => resolve({
-            close: () => new Promise((done) => {
+            close: async () => {
                 mcp.closeSubscriptions();
-                server.close(() => done());
-            }),
+                try {
+                    await new Promise((done) => server.close(() => done()));
+                }
+                finally {
+                    await codeGraph?.close();
+                }
+            },
         }));
     });
 }

package/dist/src/tunnel.js

@@ -95,10 +95,11 @@ export function startTunnel(options) {
             record(event);
             if (event.type === "online") {
                 writeLine();
-                writeLine("  ✓ TUNNEL ONLINE");
-                writeLine(`    Public URL   : ${event.url}`);
-                writeLine(`    MCP endpoint : ${event.url}/mcp`);
-                writeLine(`    Forwarding   : ${event.url} → http://127.0.0.1:${options.port}`);
+                writeLine(`  \x1b[96m╭─ TUNNEL ONLINE ${"─".repeat(58)}╮\x1b[0m`);
+                writeLine(`  \x1b[96m│\x1b[0m Public URL   : \x1b[92m${event.url}\x1b[0m`);
+                writeLine(`  \x1b[96m│\x1b[0m MCP endpoint : \x1b[96m${event.url}/mcp\x1b[0m`);
+                writeLine(`  \x1b[96m│\x1b[0m Forwarding   : ${event.url} → http://127.0.0.1:${options.port}`);
+                writeLine(`  \x1b[96m╰${"─".repeat(74)}╯\x1b[0m`);
                 writeLine();
             }
             else if (event.type === "disconnected") {

package/dist/src/types.d.ts

@@ -41,6 +41,7 @@ export interface ServerOptions {
     token: string;
     commandConfig?: CommandConfig;
     telemetry?: TelemetryConfig;
+    codeGraph?: import("./codegraph.js").CodeGraphIntegration;
 }
 export interface RequestLog {
     method: string;

package/docs/RELEASING.md

@@ -6,10 +6,7 @@ This document is the authoritative maintainer/agent procedure for publishing `ag
 
     feature/*
         │
-        ├── PR → staging
-        │        └── CI
-        │
-        └── promotion PR → main
+        └── PR → main
                  └── CI
                       │
                       ▼
@@ -28,7 +25,7 @@ This document is the authoritative maintainer/agent procedure for publishing `ag
                                   ├── create GitHub Release
                                   └── publish npm package
 
-`main` and `staging` are protected. Normal human and agent changes reach them through pull requests.
+`main` is the single protected release branch. Normal human and agent changes reach it through pull requests. There is no permanent `staging` branch.
 
 ## Release source of truth
 
@@ -61,21 +58,15 @@ Do not manually edit the package version.
 
 `npm pack --dry-run` is important: inspect the file list and make sure the package does not contain credentials, local configuration, development-only files, or other unintended content.
 
-### 3. Merge through staging
+### 3. Open and merge a pull request
 
-Push the feature branch and open a PR targeting `staging`.
+Push the branch and open a PR targeting `main`.
 
 The required CI check is `Check`. It runs `npm ci`, `npm run check`, `npm test`, and `npm pack --dry-run`.
 
-Do not bypass a failing check. After checks pass, merge the PR into `staging`.
-
-### 4. Promote staging to main
-
-Create a promotion PR: `staging → main`.
-
-CI runs again because `main` is also a pull-request target. Merge only after the required `Check` status is green.
+Do not bypass a failing check. Merge only after the required `Check` status is green and the required review is approved.
 
-### 5. Let GitHub Actions publish
+### 4. Let GitHub Actions publish
 
 The merge to `main` creates a push to `main`, which starts `.github/workflows/publish.yml`.
 
@@ -179,7 +170,7 @@ If a release was partially created, reconcile the actual Git/npm/GitHub state be
 
 ## CI workflow constraints
 
-`.github/workflows/ci.yml` runs for pull requests targeting `staging` and `main`.
+`.github/workflows/ci.yml` runs on pushes to `main` and pull requests targeting `main`.
 
 Its concurrency key must remain safe for both PR events and any diagnostic/manual event that may temporarily be introduced:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dir",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Expose a local project to an AI agent through authenticated MCP, filesystem tools, and allowlisted development commands",
   "repository": {
     "type": "git",