@mcoda/codali 0.1.107 → 0.1.109

package/dist/cli/AuthCommand.js

@@ -0,0 +1,161 @@
+import { readFileSync, writeFileSync, existsSync, chmodSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { MICROSOFT_GRAPH_SCOPES, microsoftEndpoints, pollForDeviceCodeTokens, startDeviceCode, DeviceCodeError, } from "../connectors/oauth/DeviceCodeAuth.js";
+import { resolveCredential, resetCredentialCache } from "../runcontext/CredentialFile.js";
+/**
+ * `codali auth <provider>` — interactive sign-in for connectors that need a
+ * user context rather than a static key.
+ *
+ * The refresh token is written back to `~/.codali/.creds`, which is the same
+ * place every other credential lives, so a connector references it as
+ * `env:MICROSOFT_REFRESH_TOKEN` exactly like any other secret.
+ */
+const CREDS = path.join(homedir(), ".codali", ".creds");
+const HELP = `Usage: codali auth <provider>
+
+Providers:
+  microsoft    Sign in to Microsoft Graph via device code
+
+Options:
+  --tenant <id>      Directory (tenant) ID. Default: $MICROSOFT_TENANT_ID
+  --client <id>      Application (client) ID. Default: $MICROSOFT_CLIENT_ID
+  --scope "<a b c>"  Override the requested delegated scopes
+  --help, -h         Show this help
+`;
+/**
+ * Writes a key into the credentials file, replacing any existing entry.
+ * Rewrites in place rather than appending, so re-authenticating does not leave
+ * a stale token above the new one — the parser takes the last occurrence, and
+ * relying on that is a trap.
+ */
+export const upsertCredential = (key, value, file = CREDS) => {
+    const lines = existsSync(file)
+        ? readFileSync(file, "utf8").split(/\r?\n/)
+        : ["# Codali credentials. Format: KEY=value", ""];
+    let replaced = false;
+    const output = lines.map((line) => {
+        if (line.startsWith(`${key}=`)) {
+            replaced = true;
+            return `${key}=${value}`;
+        }
+        return line;
+    });
+    if (!replaced) {
+        if (output.length > 0 && output[output.length - 1] !== "")
+            output.push("");
+        output.push(`${key}=${value}`, "");
+    }
+    writeFileSync(file, output.join("\n"), "utf8");
+    chmodSync(file, 0o600);
+};
+const authMicrosoft = async (argv, deps) => {
+    const write = deps.write ?? ((line) => process.stdout.write(`${line}\n`));
+    resetCredentialCache();
+    let tenant = resolveCredential("MICROSOFT_TENANT_ID");
+    let client = resolveCredential("MICROSOFT_CLIENT_ID");
+    let scope = MICROSOFT_GRAPH_SCOPES;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = argv[index + 1];
+        if (arg === "--tenant" && next) {
+            tenant = next;
+            index += 1;
+        }
+        else if (arg === "--client" && next) {
+            client = next;
+            index += 1;
+        }
+        else if (arg === "--scope" && next) {
+            scope = next;
+            index += 1;
+        }
+    }
+    if (!tenant || !client) {
+        write("Microsoft sign-in needs a tenant and client id.");
+        write("Add MICROSOFT_TENANT_ID and MICROSOFT_CLIENT_ID to ~/.codali/.creds,");
+        write("or pass --tenant and --client.");
+        return 1;
+    }
+    const endpoints = microsoftEndpoints(tenant);
+    const config = { ...endpoints, clientId: client, scope };
+    let start;
+    try {
+        start = await startDeviceCode(config, deps.fetchImpl);
+    }
+    catch (error) {
+        const detail = error instanceof DeviceCodeError ? error.message : String(error);
+        write(`Could not start device sign-in: ${detail}`);
+        if (detail.includes("7000218") || detail.toLowerCase().includes("public client")) {
+            write("");
+            write("The app needs public client flows enabled:");
+            write("  Entra portal -> App registrations -> your app -> Authentication");
+            write("  -> Advanced settings -> Allow public client flows -> Yes");
+        }
+        return 1;
+    }
+    write("");
+    write(`  Open:  ${start.verificationUri}`);
+    write(`  Code:  ${start.userCode}`);
+    write("");
+    write("Waiting for approval…");
+    try {
+        const tokens = await pollForDeviceCodeTokens(config, start, deps.fetchImpl, {
+            sleep: deps.sleep,
+            onPending: () => { },
+        });
+        if (!tokens.refreshToken) {
+            // Without offline_access the grant is good for one hour and then gone,
+            // which is not a workflow.
+            write("Signed in, but no refresh token was returned.");
+            write("The `offline_access` scope is required for a durable session.");
+            return 1;
+        }
+        const file = deps.credsFile ?? CREDS;
+        upsertCredential("MICROSOFT_REFRESH_TOKEN", tokens.refreshToken, file);
+        upsertCredential("MICROSOFT_TENANT_ID", tenant, file);
+        upsertCredential("MICROSOFT_CLIENT_ID", client, file);
+        resetCredentialCache();
+        write("");
+        write("Signed in. Refresh token stored in ~/.codali/.creds");
+        if (tokens.scope) {
+            write("");
+            write("Granted scopes:");
+            for (const granted of tokens.scope.split(/\s+/).filter(Boolean)) {
+                write(`  ${granted}`);
+            }
+        }
+        return 0;
+    }
+    catch (error) {
+        const detail = error instanceof DeviceCodeError ? error.message : String(error);
+        write(`Sign-in failed: ${detail}`);
+        if (detail.includes("consent") || detail.includes("65001")) {
+            write("");
+            write("Grant the delegated permissions first:");
+            write("  Entra portal -> App registrations -> your app -> API permissions");
+            write("  -> Add Microsoft Graph delegated permissions -> Grant admin consent");
+        }
+        return 1;
+    }
+};
+export const runAuth = async (argv, deps = {}) => {
+    const write = deps.write ?? ((line) => process.stdout.write(`${line}\n`));
+    const [provider, ...rest] = argv;
+    if (!provider || argv.includes("--help") || argv.includes("-h")) {
+        write(HELP);
+        return provider ? 0 : 1;
+    }
+    if (provider === "microsoft" || provider === "ms" || provider === "graph") {
+        return authMicrosoft(rest, deps);
+    }
+    write(`Unknown auth provider: ${provider}\n\n${HELP}`);
+    return 1;
+};
+export const AuthCommand = {
+    async run(argv) {
+        const exitCode = await runAuth(argv);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+    },
+};

package/dist/cli/ServeCommand.d.ts

@@ -0,0 +1,5 @@
+export declare const runServe: (argv: string[], write?: (line: string) => void) => Promise<number>;
+export declare const ServeCommand: {
+    run(argv: string[]): Promise<void>;
+};
+//# sourceMappingURL=ServeCommand.d.ts.map

package/dist/cli/ServeCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ServeCommand.d.ts","sourceRoot":"","sources":["../../src/cli/ServeCommand.ts"],"names":[],"mappings":"AA+BA,eAAO,MAAM,QAAQ,GACnB,MAAM,MAAM,EAAE,EACd,QAAO,CAAC,IAAI,EAAE,MAAM,KAAK,IAAkD,KAC1E,OAAO,CAAC,MAAM,CA6ChB,CAAC;AAEF,eAAO,MAAM,YAAY;cACP,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzC,CAAC"}

package/dist/cli/ServeCommand.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { startCodaliServer } from "../api/CodaliServer.js";
+import { LocalConfigRunContextResolver } from "../runcontext/RunContextResolver.js";
+/**
+ * `codali serve` — the local HTTP surface.
+ *
+ * Single-tenant by design: it authenticates against one operator-supplied key
+ * and serves that operator's own configured context. Multi-tenant hosting is a
+ * product's job, using {@link createCodaliServer} with its own `authenticate`
+ * implementation, because only the product knows how to map a caller to a
+ * tenant.
+ */
+const HELP = `Usage: codali serve [options]
+
+Serve Codali over HTTP with the same result contract the CLI produces.
+
+Endpoints:
+  POST /v1/chat/completions   OpenAI-compatible; carries Codali provenance
+  POST /v1/codali/run         Canonical Codali request/result
+  GET  /healthz
+
+Options:
+  --port <n>                Port to listen on (default: 8787)
+  --host <addr>             Address to bind (default: 127.0.0.1)
+  --workspace-root <path>   Repository runs resolve against (default: cwd)
+  --api-key <key>           Required key. Defaults to $CODALI_API_KEY.
+  --help, -h                Show this help
+`;
+export const runServe = async (argv, write = (line) => process.stdout.write(`${line}\n`)) => {
+    if (argv.includes("--help") || argv.includes("-h")) {
+        write(HELP);
+        return 0;
+    }
+    let port = 8787;
+    let host = "127.0.0.1";
+    let workspaceRoot = process.cwd();
+    let apiKey = process.env.CODALI_API_KEY;
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        const next = argv[index + 1];
+        if (arg === "--port" && next) {
+            port = Number.parseInt(next, 10);
+            index += 1;
+        }
+        else if (arg === "--host" && next) {
+            host = next;
+            index += 1;
+        }
+        else if (arg === "--workspace-root" && next) {
+            workspaceRoot = path.resolve(next);
+            index += 1;
+        }
+        else if (arg === "--api-key" && next) {
+            apiKey = next;
+            index += 1;
+        }
+    }
+    if (!apiKey) {
+        // Refusing to start without a key is deliberate: an unauthenticated server
+        // has no tenant, and a run with no tenant scope should not reach
+        // connectors or credentials.
+        write("codali serve requires an API key. Set CODALI_API_KEY or pass --api-key.");
+        return 1;
+    }
+    const context = await new LocalConfigRunContextResolver().resolve({ workspaceRoot });
+    const principal = {
+        tenant: { id: "local", slug: "local" },
+        runContext: context,
+    };
+    const { port: boundPort } = await startCodaliServer({
+        port,
+        host,
+        workspaceRoot,
+        authenticate: async (candidate) => (candidate === apiKey ? principal : undefined),
+    });
+    write(`codali serve listening on http://${host}:${boundPort}`);
+    write("  POST /v1/chat/completions");
+    write("  POST /v1/codali/run");
+    return 0;
+};
+export const ServeCommand = {
+    async run(argv) {
+        const exitCode = await runServe(argv);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+    },
+};

package/dist/cli/ToolsCommand.d.ts

@@ -0,0 +1,22 @@
+import { attachMcpTools } from "../connectors/mcp/McpToolSource.js";
+import type { RunContext } from "../runcontext/RunContextResolver.js";
+import { ToolRegistry } from "../tools/ToolRegistry.js";
+export interface ToolsOptions {
+    command: "list" | "describe" | "call" | "health";
+    target?: string;
+    workspaceRoot: string;
+    argsJson?: string;
+    json: boolean;
+}
+export declare const parseToolsArgs: (argv: string[]) => ToolsOptions;
+export interface ToolsDependencies {
+    resolveRunContext?: (workspaceRoot: string) => Promise<RunContext>;
+    buildBaseRegistry?: (context: RunContext, workspaceRoot: string) => ToolRegistry;
+    attachMcp?: typeof attachMcpTools;
+    write?: (line: string) => void;
+}
+export declare const runTools: (argv: string[], deps?: ToolsDependencies) => Promise<number>;
+export declare const ToolsCommand: {
+    run(argv: string[]): Promise<void>;
+};
+//# sourceMappingURL=ToolsCommand.d.ts.map

package/dist/cli/ToolsCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToolsCommand.d.ts","sourceRoot":"","sources":["../../src/cli/ToolsCommand.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AAGpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qCAAqC,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AA2BxD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,QAAQ,CAAC;IACjD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,OAAO,CAAC;CACf;AAED,eAAO,MAAM,cAAc,GAAI,MAAM,MAAM,EAAE,KAAG,YAiC/C,CAAC;AAEF,MAAM,WAAW,iBAAiB;IAChC,iBAAiB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,CAAC,CAAC;IACnE,iBAAiB,CAAC,EAAE,CAAC,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,KAAK,YAAY,CAAC;IACjF,SAAS,CAAC,EAAE,OAAO,cAAc,CAAC;IAClC,KAAK,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAkBD,eAAO,MAAM,QAAQ,GACnB,MAAM,MAAM,EAAE,EACd,OAAM,iBAAsB,KAC3B,OAAO,CAAC,MAAM,CA8IhB,CAAC;AAEF,eAAO,MAAM,YAAY;cACP,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC;CAIzC,CAAC"}

package/dist/cli/ToolsCommand.js

@@ -0,0 +1,208 @@
+import path from "node:path";
+import { attachHttpTools } from "../connectors/http/HttpToolSource.js";
+import { attachMcpTools } from "../connectors/mcp/McpToolSource.js";
+import { DocdexClient } from "../docdex/DocdexClient.js";
+import { LocalConfigRunContextResolver } from "../runcontext/RunContextResolver.js";
+import { ToolRegistry } from "../tools/ToolRegistry.js";
+import { createDocdexTools } from "../tools/docdex/DocdexTools.js";
+import { sanitizeArgs } from "../gateway/GatewayTracer.js";
+/**
+ * `codali tools` — inspect what an orchestration run can actually reach.
+ *
+ * Without this the only way to find out which tools a configured MCP server
+ * exposes is to ask a question and read the trace, which conflates connector
+ * problems with planning problems.
+ */
+const HELP = `Usage: codali tools <list|describe|call|health> [options]
+
+Commands:
+  list                 List every tool available to a run, grouped by capability
+  describe <name>      Show one tool's description and argument schema
+  call <name>          Invoke a tool directly (read-only connectors)
+  health               Show MCP server connection status
+
+Options:
+  --workspace-root <path>   Repository to resolve config against (default: cwd)
+  --args-json <json>        Arguments for "call"
+  --json                    Machine-readable output
+  --help, -h                Show this help
+`;
+export const parseToolsArgs = (argv) => {
+    const [rawCommand, ...rest] = argv;
+    const command = rawCommand;
+    if (!["list", "describe", "call", "health"].includes(command)) {
+        throw new Error(`Unknown tools command: ${rawCommand ?? "(none)"}\n\n${HELP}`);
+    }
+    let workspaceRoot = process.cwd();
+    let argsJson;
+    let json = false;
+    let target;
+    for (let index = 0; index < rest.length; index += 1) {
+        const arg = rest[index];
+        const next = rest[index + 1];
+        if (arg === "--workspace-root" && next) {
+            workspaceRoot = path.resolve(next);
+            index += 1;
+        }
+        else if (arg === "--args-json" && next) {
+            argsJson = next;
+            index += 1;
+        }
+        else if (arg === "--json") {
+            json = true;
+        }
+        else if (arg && !arg.startsWith("--") && !target) {
+            target = arg;
+        }
+    }
+    if ((command === "describe" || command === "call") && !target) {
+        throw new Error(`codali tools ${command} requires a tool name.\n\n${HELP}`);
+    }
+    return { command, target, workspaceRoot, argsJson, json };
+};
+const buildBaseRegistryDefault = (context, workspaceRoot) => {
+    const registry = new ToolRegistry();
+    const client = new DocdexClient({
+        baseUrl: context.docdex?.baseUrl ?? "http://127.0.0.1:28491",
+        repoRoot: context.repo?.root ?? workspaceRoot,
+        repoId: context.docdex?.repoId,
+        apiKey: context.docdex?.apiKey,
+        allowedOperations: context.docdex?.allowedOperations,
+    });
+    for (const tool of createDocdexTools(client))
+        registry.register(tool);
+    return registry;
+};
+export const runTools = async (argv, deps = {}) => {
+    const write = deps.write ?? ((line) => process.stdout.write(`${line}\n`));
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+        write(HELP);
+        return 0;
+    }
+    const options = parseToolsArgs(argv);
+    const context = deps.resolveRunContext
+        ? await deps.resolveRunContext(options.workspaceRoot)
+        : await new LocalConfigRunContextResolver().resolve({
+            workspaceRoot: options.workspaceRoot,
+        });
+    const registry = (deps.buildBaseRegistry ?? buildBaseRegistryDefault)(context, options.workspaceRoot);
+    const mcp = await (deps.attachMcp ?? attachMcpTools)({
+        context,
+        toolRegistry: registry,
+    });
+    // Hand-declared HTTP connectors are part of the same catalog; omitting them
+    // here would make `tools list` disagree with what a run can actually reach.
+    const http = attachHttpTools({ context, toolRegistry: registry });
+    mcp.warnings.push(...http.warnings);
+    try {
+        if (options.command === "health") {
+            if (options.json) {
+                write(JSON.stringify({ servers: mcp.health, warnings: mcp.warnings }, null, 2));
+            }
+            else if (mcp.health.length === 0) {
+                write("No MCP servers configured.");
+                write("Add them under \"mcpServers\" in ~/.codali/config.json.");
+            }
+            else {
+                for (const server of mcp.health) {
+                    const detail = server.status === "connected"
+                        ? `${server.toolCount} tool(s), ${server.discoveryMs ?? 0}ms`
+                        : (server.error ?? server.status);
+                    write(`${server.status === "connected" ? "ok  " : "FAIL"} ${server.name}  ${detail}`);
+                }
+            }
+            return mcp.health.some((server) => server.status === "failed") ? 1 : 0;
+        }
+        if (options.command === "list") {
+            const capabilities = registry.capabilities();
+            if (options.json) {
+                write(JSON.stringify(registry.catalog(), null, 2));
+                return 0;
+            }
+            if (capabilities.size === 0) {
+                write("No tools available.");
+                return 0;
+            }
+            for (const [capability, tools] of [...capabilities.entries()].sort(([a], [b]) => a.localeCompare(b))) {
+                write(`${capability} (${tools.length})`);
+                for (const tool of tools.sort((a, b) => a.name.localeCompare(b.name))) {
+                    const flag = tool.readOnly ? "" : " [write]";
+                    write(`  ${tool.name}${flag}`);
+                    write(`    ${tool.description}`);
+                }
+                write("");
+            }
+            for (const warning of mcp.warnings)
+                write(`warning: ${warning}`);
+            return 0;
+        }
+        if (options.command === "describe") {
+            const descriptor = registry.catalog([options.target])[0];
+            if (!descriptor) {
+                write(`Unknown tool: ${options.target}`);
+                return 1;
+            }
+            if (options.json) {
+                write(JSON.stringify(descriptor, null, 2));
+                return 0;
+            }
+            write(descriptor.name);
+            write(`  capability: ${descriptor.capability}`);
+            write(`  read-only:  ${descriptor.readOnly}`);
+            write(`  ${descriptor.description}`);
+            if (descriptor.inputSchema) {
+                write("  input schema:");
+                write(JSON.stringify(descriptor.inputSchema, null, 2)
+                    .split("\n")
+                    .map((line) => `    ${line}`)
+                    .join("\n"));
+            }
+            return 0;
+        }
+        // call
+        const descriptor = registry.catalog([options.target])[0];
+        if (!descriptor) {
+            write(`Unknown tool: ${options.target}`);
+            return 1;
+        }
+        if (!descriptor.readOnly) {
+            // Phase 2 connectors are read-only by policy; a direct invocation must
+            // not be the way around that.
+            write(`Refusing to call ${descriptor.name}: it is not marked read-only.`);
+            return 1;
+        }
+        const args = options.argsJson ? JSON.parse(options.argsJson) : {};
+        const result = await registry.execute(descriptor.name, args, {
+            workspaceRoot: options.workspaceRoot,
+            allowShell: false,
+            allowDestructiveOperations: false,
+            allowOutsideWorkspace: false,
+        });
+        if (options.json) {
+            write(JSON.stringify({
+                ok: result.ok,
+                output: result.output,
+                error: result.error,
+                args: sanitizeArgs(args),
+            }, null, 2));
+        }
+        else if (result.ok) {
+            write(result.output);
+        }
+        else {
+            write(`Tool failed (${result.error?.code}): ${result.error?.message}`);
+        }
+        return result.ok ? 0 : 1;
+    }
+    finally {
+        // stdio servers are child processes; leaving them running would orphan them.
+        await mcp.registry?.close();
+    }
+};
+export const ToolsCommand = {
+    async run(argv) {
+        const exitCode = await runTools(argv);
+        if (exitCode !== 0)
+            process.exitCode = exitCode;
+    },
+};

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AA0EA,eAAO,MAAM,MAAM,GAAU,OAAM,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CA8CjF,CAAC"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAsFA,eAAO,MAAM,MAAM,GAAU,OAAM,MAAM,EAA0B,KAAG,OAAO,CAAC,IAAI,CAkEjF,CAAC"}

package/dist/cli.js

@@ -2,12 +2,20 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { AskCommand } from "./cli/AskCommand.js";
 import { RunCommand } from "./cli/RunCommand.js";
+import { ToolsCommand } from "./cli/ToolsCommand.js";
+import { ServeCommand } from "./cli/ServeCommand.js";
+import { AuthCommand } from "./cli/AuthCommand.js";
 import { FeedbackCommand } from "./cli/FeedbackCommand.js";
 import { EvalCommand } from "./cli/EvalCommand.js";
 import { DatasetCommand } from "./cli/DatasetCommand.js";
 import { ImprovementCommand } from "./cli/ImprovementCommand.js";
-const HELP_TEXT = "Usage: codali run [--workspace-root <path>] --agent <slug> [--task <file>]\n" +
+const HELP_TEXT = "Usage: codali ask \"<question>\" [--trace] [--json] [--workspace-root <path>]\n" +
+    "   or: codali tools <list|describe|call|health> [options]\n" +
+    "   or: codali auth <microsoft>\n" +
+    "   or: codali serve [--port <n>] [--api-key <key>]\n" +
+    "   or: codali run [--workspace-root <path>] --agent <slug> [--task <file>]\n" +
     "   or: codali run [--workspace-root <path>] --provider <name> --model <model> [--task <file>]\n" +
     "   or: codali <fix|review|explain|test> [run options] [--task <file>]\n" +
     "   or: codali eval --suite <path> [eval options]\n" +
@@ -18,6 +26,10 @@ const HELP_TEXT = "Usage: codali run [--workspace-root <path>] --agent <slug> [-
     "   or: codali learn --confirm <dedupe_key> [--confirm <dedupe_key> ...]\n" +
     "\n" +
     "Commands:\n" +
+    "  ask      Ask a question. Routes, gathers evidence with tools, answers with citations.\n" +
+    "  tools    Inspect the tools a run can reach, including MCP servers.\n" +
+    "  auth     Sign in to a connector that needs a user context (Microsoft Graph).\n" +
+    "  serve    Serve Codali over HTTP with the same contract as the CLI.\n" +
     "  run      Run a single task (advanced/general profile).\n" +
     "  fix      Apply fix workflow profile (patch-focused output).\n" +
     "  review   Apply review workflow profile (findings-focused output).\n" +
@@ -83,6 +95,22 @@ export const runCli = async (argv = process.argv.slice(2)) => {
         printDoctor();
         return;
     }
+    if (command === "ask") {
+        await AskCommand.run(rest);
+        return;
+    }
+    if (command === "auth") {
+        await AuthCommand.run(rest);
+        return;
+    }
+    if (command === "serve") {
+        await ServeCommand.run(rest);
+        return;
+    }
+    if (command === "tools" || command === "mcp") {
+        await ToolsCommand.run(command === "mcp" ? ["health", ...rest] : rest);
+        return;
+    }
     if (["run", "fix", "review", "explain", "test"].includes(command)) {
         await RunCommand.run(["--command", command, ...rest]);
         return;

package/dist/connectors/http/HttpToolDefinition.d.ts

@@ -0,0 +1,74 @@
+import type { ToolDefinition, ToolInputSchema } from "../../tools/ToolTypes.js";
+/**
+ * Hand-declared HTTP tools.
+ *
+ * Deliberately *not* a generic OpenAPI compiler. Importing an arbitrary spec
+ * drags in hundreds of irrelevant operations, several authentication styles,
+ * inconsistent pagination, enormous nested schemas, and write operations that
+ * have no business being reachable — and then the orchestrator has to choose
+ * among them. A Jira, CRM, or Graph lookup is three lines of declaration; an
+ * offline importer is worth building only once maintaining those declarations
+ * across several real connectors proves burdensome.
+ *
+ * Everything here is read-only by construction: the method allowlist rejects
+ * anything that mutates.
+ */
+export type HttpToolMethod = "GET" | "HEAD";
+export interface HttpConnectorAuth {
+    type: "bearer" | "basic" | "header" | "none" | "oauth2_refresh";
+    /** Resolved value. Never a reference — resolution happens before this point. */
+    token?: string;
+    username?: string;
+    password?: string;
+    headerName?: string;
+    /** oauth2_refresh only: exchanges a stored refresh token for an access token. */
+    tokenUrl?: string;
+    clientId?: string;
+    refreshToken?: string;
+    scope?: string;
+}
+export declare const resetAccessTokenCache: () => void;
+export interface HttpToolDeclaration {
+    id: string;
+    description: string;
+    method: HttpToolMethod;
+    /** e.g. `/rest/api/3/issue/{issueKey}` — `{name}` is substituted from args. */
+    urlTemplate: string;
+    inputSchema?: ToolInputSchema;
+    /**
+     * Dotted path into the response, e.g. `issues[].fields.summary`. Applied
+     * before the result reaches a model, because a raw API payload routinely
+     * exceeds an entire evidence budget.
+     */
+    responseSelector?: string;
+    /** Cap on serialized response characters. */
+    maxResponseChars?: number;
+}
+export interface HttpConnectorDefinition {
+    name: string;
+    baseUrl: string;
+    auth?: HttpConnectorAuth;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+    tools: HttpToolDeclaration[];
+    enabled?: boolean;
+}
+/**
+ * Substitutes `{name}` placeholders and appends anything left over as query
+ * parameters. Placeholder values are URL-encoded, so a model cannot inject a
+ * path segment or escape the connector's base URL.
+ */
+export declare const buildHttpUrl: (baseUrl: string, template: string, args: Record<string, unknown>) => string;
+/**
+ * Projects a response down to what was asked for. `items[].name` maps over an
+ * array; a plain dotted path drills in.
+ */
+export declare const applyResponseSelector: (payload: unknown, selector?: string) => unknown;
+export interface HttpToolFactoryOptions {
+    connector: HttpConnectorDefinition;
+    fetchImpl?: typeof fetch;
+}
+export declare const httpToolName: (connector: string, tool: string) => string;
+export declare const httpToolToDefinition: (declaration: HttpToolDeclaration, options: HttpToolFactoryOptions) => ToolDefinition;
+export declare const httpConnectorToDefinitions: (options: HttpToolFactoryOptions) => ToolDefinition[];
+//# sourceMappingURL=HttpToolDefinition.d.ts.map

package/dist/connectors/http/HttpToolDefinition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HttpToolDefinition.d.ts","sourceRoot":"","sources":["../../../src/connectors/http/HttpToolDefinition.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAEhF;;;;;;;;;;;;;GAaG;AAEH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5C,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,MAAM,GAAG,gBAAgB,CAAC;IAChE,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAYD,eAAO,MAAM,qBAAqB,QAAO,IAAgC,CAAC;AAwC1E,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,cAAc,CAAC;IACvB,+EAA+E;IAC/E,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,eAAe,CAAC;IAC9B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,iBAAiB,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,mBAAmB,EAAE,CAAC;IAC7B,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAcD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,SAAS,MAAM,EACf,UAAU,MAAM,EAChB,MAAM,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAC5B,MAqBF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,qBAAqB,GAAI,SAAS,OAAO,EAAE,WAAW,MAAM,KAAG,OAoB3E,CAAC;AAsBF,MAAM,WAAW,sBAAsB;IACrC,SAAS,EAAE,uBAAuB,CAAC;IACnC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,eAAO,MAAM,YAAY,GAAI,WAAW,MAAM,EAAE,MAAM,MAAM,KAAG,MAClC,CAAC;AAE9B,eAAO,MAAM,oBAAoB,GAC/B,aAAa,mBAAmB,EAChC,SAAS,sBAAsB,KAC9B,cA6FF,CAAC;AAEF,eAAO,MAAM,0BAA0B,GACrC,SAAS,sBAAsB,KAC9B,cAAc,EAIkC,CAAC"}