@botbotgo/agent-harness 0.0.309 → 0.0.310

package/dist/cli/chat-workspace.js

@@ -0,0 +1,205 @@
+import { readFileSync, readdirSync } from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { interpolateEnvPlaceholders } from "../workspace/yaml-object-reader.js";
+import { frameworkCliWorkspaceRoot, hasCliConfigYaml, resolveCliConfigRoot, } from "./workspace.js";
+export function normalizeChatCommand(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("/")) {
+        return null;
+    }
+    const [name, ...rest] = trimmed.slice(1).split(/\s+/);
+    return {
+        name,
+        arg: rest.length > 0 ? rest.join(" ") : undefined,
+    };
+}
+function asRecord(value) {
+    return typeof value === "object" && value !== null ? value : undefined;
+}
+function readCliConfigObjects(workspaceRoot) {
+    const roots = [
+        resolveCliConfigRoot(frameworkCliWorkspaceRoot()),
+        resolveCliConfigRoot(workspaceRoot),
+    ];
+    const merged = new Map();
+    for (const configRoot of roots) {
+        if (!hasCliConfigYaml(configRoot)) {
+            continue;
+        }
+        const files = [];
+        const pending = [configRoot];
+        while (pending.length > 0) {
+            const current = pending.pop();
+            for (const entry of readdirSync(current, { withFileTypes: true })) {
+                const entryPath = path.join(current, entry.name);
+                if (entry.isDirectory()) {
+                    if (entry.name === "node_modules") {
+                        continue;
+                    }
+                    pending.push(entryPath);
+                    continue;
+                }
+                if (entry.isFile() && /\.ya?ml$/i.test(entry.name)) {
+                    files.push(entryPath);
+                }
+            }
+        }
+        for (const filePath of files.sort()) {
+            const content = readFileSync(filePath, "utf8");
+            for (const document of YAML.parseAllDocuments(content)) {
+                const resolved = interpolateEnvPlaceholders(document.toJSON(), filePath);
+                const typed = asRecord(resolved);
+                if (!typed) {
+                    continue;
+                }
+                if (typed.kind === "Models" && Array.isArray(typed.spec)) {
+                    for (const item of typed.spec) {
+                        const record = asRecord(item);
+                        if (!record) {
+                            continue;
+                        }
+                        const id = typeof record.name === "string" ? record.name : record.id;
+                        if (typeof id !== "string" || !id) {
+                            continue;
+                        }
+                        merged.set(`Model/${id}`, {
+                            ...record,
+                            kind: "Model",
+                            id,
+                        });
+                    }
+                    continue;
+                }
+                const metadata = asRecord(typed.metadata);
+                const spec = asRecord(typed.spec);
+                if (typeof typed.kind === "string" && spec) {
+                    const id = typeof metadata?.name === "string" ? metadata.name : typed.id;
+                    if (typeof id !== "string" || !id) {
+                        continue;
+                    }
+                    merged.set(`${typed.kind}/${id}`, {
+                        ...spec,
+                        kind: typed.kind,
+                        id,
+                    });
+                    continue;
+                }
+                const kind = typeof typed.kind === "string" ? typed.kind : undefined;
+                const id = typeof typed.id === "string" ? typed.id : undefined;
+                if (!kind || !id) {
+                    continue;
+                }
+                merged.set(`${kind}/${id}`, typed);
+            }
+        }
+    }
+    return Array.from(merged.values());
+}
+function getWorkspaceDefaultAgentId(workspaceRoot) {
+    const runtime = readCliConfigObjects(workspaceRoot).find((item) => item.kind === "Runtime" && item.id === "default");
+    const routing = asRecord(runtime?.routing);
+    return typeof routing?.defaultAgentId === "string" && routing.defaultAgentId.trim().length > 0 ? routing.defaultAgentId.trim() : undefined;
+}
+function getAgentModelRef(workspaceRoot, agentId) {
+    const agent = readCliConfigObjects(workspaceRoot).find((item) => item.kind === "Agent" && item.id === agentId);
+    return typeof agent?.modelRef === "string" && agent.modelRef.trim().length > 0 ? agent.modelRef.trim() : undefined;
+}
+function getModelInfo(workspaceRoot, modelRef) {
+    const modelName = modelRef.startsWith("model/") ? modelRef.slice("model/".length) : modelRef;
+    const model = readCliConfigObjects(workspaceRoot).find((item) => item.kind === "Model" && item.id === modelName);
+    if (!model) {
+        return undefined;
+    }
+    return {
+        provider: typeof model.provider === "string" ? model.provider : undefined,
+        model: typeof model.model === "string" ? model.model : undefined,
+        baseUrl: typeof model.baseUrl === "string" ? model.baseUrl : undefined,
+    };
+}
+export function readChatWorkspaceModelInfo(workspaceRoot, agentId) {
+    try {
+        const resolvedAgentId = agentId ?? getWorkspaceDefaultAgentId(workspaceRoot);
+        if (!resolvedAgentId) {
+            return getModelInfo(workspaceRoot, "model/default");
+        }
+        const modelRef = getAgentModelRef(workspaceRoot, resolvedAgentId) ?? "model/default";
+        return getModelInfo(workspaceRoot, modelRef);
+    }
+    catch {
+        return undefined;
+    }
+}
+function renderProviderFailureHint(modelInfo) {
+    if (!modelInfo?.provider) {
+        return undefined;
+    }
+    if (modelInfo.provider === "ollama") {
+        const modelText = modelInfo.model ? ` and ensure \`${modelInfo.model}\` is available` : "";
+        return `Hint: start Ollama${modelInfo.baseUrl ? ` at ${modelInfo.baseUrl}` : ""}${modelText}. Example: \`ollama serve\`${modelInfo.model ? ` and \`ollama pull ${modelInfo.model}\`` : ""}.`;
+    }
+    if (modelInfo.provider === "openai") {
+        return "Hint: verify network access and that `OPENAI_API_KEY` is set for this shell.";
+    }
+    if (modelInfo.provider === "anthropic") {
+        return "Hint: verify network access and that `ANTHROPIC_API_KEY` is set for this shell.";
+    }
+    if (modelInfo.provider === "google" || modelInfo.provider === "google-genai" || modelInfo.provider === "gemini") {
+        return "Hint: verify network access and that the configured Google API key is available in this shell.";
+    }
+    if (modelInfo.provider === "openai-compatible") {
+        return `Hint: verify the configured endpoint${modelInfo.baseUrl ? ` (${modelInfo.baseUrl})` : ""} and the required API key for that provider.`;
+    }
+    return undefined;
+}
+export function renderChatRuntimeFailure(output, modelInfo) {
+    const trimmed = output.trim();
+    if (!trimmed.startsWith("runtime_error=")) {
+        return output;
+    }
+    const normalized = trimmed.toLowerCase();
+    if (!normalized.includes("fetch failed") &&
+        !normalized.includes("connection error") &&
+        !normalized.includes("timed out") &&
+        !normalized.includes("404 page not found")) {
+        return output;
+    }
+    const lines = [trimmed];
+    if (modelInfo?.provider || modelInfo?.model) {
+        lines.push(`provider=${modelInfo?.provider ?? "unknown"}${modelInfo?.model ? ` model=${modelInfo.model}` : ""}`);
+    }
+    if (modelInfo?.baseUrl) {
+        lines.push(`endpoint=${modelInfo.baseUrl}`);
+    }
+    if (normalized.includes("404 page not found") && modelInfo?.provider === "ollama") {
+        lines.push("Hint: the configured endpoint responded, but it does not look like an Ollama API route. Check that `baseUrl` points at the Ollama server root and that no other service is bound to this port.");
+    }
+    const hint = renderProviderFailureHint(modelInfo);
+    if (hint) {
+        lines.push(hint);
+    }
+    return lines.join("\n");
+}
+export async function probeChatWorkspace(input) {
+    const modelInfo = readChatWorkspaceModelInfo(input.workspaceRoot, input.agentId);
+    if (!modelInfo?.provider || modelInfo.provider !== "ollama" || !modelInfo.baseUrl) {
+        return undefined;
+    }
+    try {
+        const response = await fetch(new URL("/api/tags", modelInfo.baseUrl), {
+            method: "GET",
+            headers: { accept: "application/json" },
+        });
+        if (response.ok) {
+            return undefined;
+        }
+        if (response.status === 404) {
+            return renderChatRuntimeFailure("runtime_error=404 page not found", modelInfo);
+        }
+        return renderChatRuntimeFailure(`runtime_error=HTTP ${response.status} ${response.statusText}`.trim(), modelInfo);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return renderChatRuntimeFailure(`runtime_error=${message}`, modelInfo);
+    }
+}

package/dist/cli/main.d.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { createInterface as createReadlineInterface } from "node:readline";
+import type { Readable } from "node:stream";
+import { createAgentHarness } from "../api.js";
+import { type HarnessClient } from "../client.js";
+import { serveA2aOverHttp } from "../protocol/a2a/http.js";
+import { serveAgUiOverHttp } from "../protocol/ag-ui/http.js";
+import { serveAcpOverHttp } from "../protocol/acp/http.js";
+import { serveAcpOverStdio } from "../protocol/acp/stdio.js";
+import { serveRuntimeMcpOverStdio, serveRuntimeMcpOverStreamableHttp } from "../mcp.js";
+export { renderChatBanner, renderChatPromptLine } from "./chat-ui.js";
+export { probeChatWorkspace, renderChatRuntimeFailure } from "./chat-workspace.js";
+export { installChatSubprocessExitGuard, isChatServerNoiseLine } from "./process-guards.js";
+type CliIo = {
+    cwd?: string;
+    stdin?: Readable;
+    stdout?: (message: string) => void;
+    stderr?: (message: string) => void;
+};
+type CliDeps = {
+    createChatClient?: (input: {
+        workspaceRoot: string;
+        transport: "stdio" | "http";
+        hostname?: string;
+        port?: number;
+        stderr?: (message: string) => void;
+    }) => Promise<HarnessClient>;
+    probeChatWorkspace?: (input: {
+        workspaceRoot: string;
+        agentId?: string;
+    }) => Promise<string | undefined>;
+    createReadlineInterface?: typeof createReadlineInterface;
+    createAgentHarness?: typeof createAgentHarness;
+    serveA2aOverHttp?: typeof serveA2aOverHttp;
+    serveAgUiOverHttp?: typeof serveAgUiOverHttp;
+    serveAcpOverHttp?: typeof serveAcpOverHttp;
+    serveAcpOverStdio?: typeof serveAcpOverStdio;
+    serveRuntimeMcpOverStdio?: typeof serveRuntimeMcpOverStdio;
+    serveRuntimeMcpOverStreamableHttp?: typeof serveRuntimeMcpOverStreamableHttp;
+    spawnManagedCliProcess?: (input: {
+        args: string[];
+        cwd: string;
+        stdoutPath: string;
+        stderrPath: string;
+    }) => Promise<{
+        pid?: number;
+    }>;
+    isManagedProcessRunning?: (pid: number) => boolean;
+    signalManagedProcess?: (pid: number, signal?: NodeJS.Signals) => void;
+};
+export declare function runCli(argv: string[], io?: CliIo, deps?: CliDeps): Promise<number>;
+export declare function resolveInvokedCliHref(argvPath?: string): string;

package/dist/cli/main.js

@@ -0,0 +1,323 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from "node:fs";
+import { createInterface as createReadlineInterface } from "node:readline";
+import { Writable } from "node:stream";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createAgentHarness } from "../api.js";
+import { installCliEmitterListenerGuard, installCliStderrNoiseFilter, installCliWarningFilter, installCliWriteListenerGuard, } from "./process-guards.js";
+import { createAgentHarnessClient, createAcpHttpHarnessClient, createInProcessHarnessClient, } from "../client.js";
+import { initProject } from "../init-project.js";
+import { serveA2aOverHttp } from "../protocol/a2a/http.js";
+import { serveAgUiOverHttp } from "../protocol/ag-ui/http.js";
+import { serveAcpOverHttp } from "../protocol/acp/http.js";
+import { serveAcpOverStdio } from "../protocol/acp/stdio.js";
+import { serveRuntimeMcpOverStdio, serveRuntimeMcpOverStreamableHttp } from "../mcp.js";
+import { renderChatBanner } from "./chat-ui.js";
+import { runInteractiveChatLoop } from "./chat-interactive.js";
+import { streamChatMessage } from "./chat-stream.js";
+import { probeChatWorkspace, readChatWorkspaceModelInfo, } from "./chat-workspace.js";
+import { handleA2aCommand, handleAcpCommand, handleAgUiCommand, handleMcpCommand } from "./server-commands.js";
+import { handleRuntimeCommand } from "./runtime-commands.js";
+import { defaultIsManagedProcessRunning, defaultSignalManagedProcess, defaultSpawnManagedCliProcess, sleep, } from "./managed-service.js";
+import { isTopLevelCliCommand, parseChatOptions, parseInitOptions, renderUsage, } from "./options.js";
+import { resolveCliWorkspaceRoot, validateCliWorkspaceRoot, } from "./workspace.js";
+export { renderChatBanner, renderChatPromptLine } from "./chat-ui.js";
+export { probeChatWorkspace, renderChatRuntimeFailure } from "./chat-workspace.js";
+export { installChatSubprocessExitGuard, isChatServerNoiseLine } from "./process-guards.js";
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function formatTimestamp(value) {
+    return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
+}
+function renderPlanResultSummary(result) {
+    if (typeof result === "string" && result.trim().length > 0) {
+        return result.trim();
+    }
+    if (!isObject(result)) {
+        return undefined;
+    }
+    const summary = typeof result.summary === "string" && result.summary.trim().length > 0
+        ? result.summary.trim()
+        : typeof result.message === "string" && result.message.trim().length > 0
+            ? result.message.trim()
+            : undefined;
+    if (summary) {
+        return summary;
+    }
+    const serialized = JSON.stringify(result);
+    return serialized && serialized !== "{}" ? serialized : undefined;
+}
+function renderChatPlanState(planState) {
+    const lines = [`[plan v${planState.version}] ${planState.summary.total} todo(s)`];
+    if (planState.summary.total === 0) {
+        lines.push("No todos tracked yet.");
+        return `${lines.join("\n")}\n`;
+    }
+    for (const [index, item] of planState.items.entries()) {
+        lines.push(`${index + 1}. [${item.status}] ${item.content}`);
+        const resultSummary = renderPlanResultSummary(item.result);
+        if (resultSummary) {
+            lines.push(`   result: ${resultSummary}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+export async function runCli(argv, io = {}, deps = {}) {
+    const cwd = io.cwd ?? process.cwd();
+    const stdin = io.stdin ?? process.stdin;
+    const stdout = io.stdout ?? ((message) => process.stdout.write(message));
+    const stderr = io.stderr ?? ((message) => process.stderr.write(message));
+    const stdoutStream = io.stdout === undefined ? process.stdout : undefined;
+    const stderrStream = io.stderr === undefined ? process.stderr : undefined;
+    const [command, projectName, ...rest] = argv;
+    const probeWorkspace = deps.probeChatWorkspace ?? probeChatWorkspace;
+    const createChatLineReader = deps.createReadlineInterface ?? createReadlineInterface;
+    const createHarness = deps.createAgentHarness ?? createAgentHarness;
+    const serveA2a = deps.serveA2aOverHttp ?? serveA2aOverHttp;
+    const serveAgUi = deps.serveAgUiOverHttp ?? serveAgUiOverHttp;
+    const serveAcpHttp = deps.serveAcpOverHttp ?? serveAcpOverHttp;
+    const serveAcp = deps.serveAcpOverStdio ?? serveAcpOverStdio;
+    const serveRuntimeMcp = deps.serveRuntimeMcpOverStdio ?? serveRuntimeMcpOverStdio;
+    const serveRuntimeMcpStreamableHttp = deps.serveRuntimeMcpOverStreamableHttp ?? serveRuntimeMcpOverStreamableHttp;
+    const spawnManagedCliProcess = deps.spawnManagedCliProcess ?? defaultSpawnManagedCliProcess;
+    const isManagedProcessRunning = deps.isManagedProcessRunning ?? defaultIsManagedProcessRunning;
+    const signalManagedProcess = deps.signalManagedProcess ?? defaultSignalManagedProcess;
+    const createChatClient = deps.createChatClient ?? (async (input) => {
+        if (input.transport === "http") {
+            return createAcpHttpHarnessClient({
+                rpcUrl: `http://${input.hostname ?? "127.0.0.1"}:${input.port ?? 8787}/rpc`,
+                eventsUrl: `http://${input.hostname ?? "127.0.0.1"}:${input.port ?? 8787}/events`,
+            });
+        }
+        if (deps.createAgentHarness) {
+            const runtime = await createHarness(input.workspaceRoot);
+            return createInProcessHarnessClient(runtime);
+        }
+        return createAgentHarnessClient(input.workspaceRoot);
+    });
+    const executeChat = async (parsed) => {
+        const workspacePath = resolveCliWorkspaceRoot(cwd, parsed.workspaceRoot);
+        const workspaceError = validateCliWorkspaceRoot(workspacePath, parsed.workspaceRoot);
+        if (workspaceError) {
+            stderr(`${workspaceError}\n`);
+            return 1;
+        }
+        const workspaceModelInfo = readChatWorkspaceModelInfo(workspacePath, parsed.agentId);
+        const chatStdinStream = stdin;
+        let client;
+        let restoreWriteListenerGuard;
+        let restoreEmitterListenerGuard;
+        let restoreStderrNoiseFilter;
+        let restoreWarningFilter;
+        try {
+            restoreEmitterListenerGuard = installCliEmitterListenerGuard();
+            restoreStderrNoiseFilter = installCliStderrNoiseFilter(io.stderr === undefined);
+            restoreWarningFilter = installCliWarningFilter();
+            client = await createChatClient({
+                workspaceRoot: workspacePath,
+                transport: parsed.transport,
+                hostname: parsed.hostname,
+                port: parsed.port,
+                stderr,
+            });
+            restoreWriteListenerGuard = installCliWriteListenerGuard([stdoutStream, stderrStream]);
+            let activeAgentId = parsed.agentId;
+            let activeSessionId = parsed.sessionId;
+            let latestRequestId;
+            const useColor = false;
+            const preflightWarning = parsed.message
+                ? undefined
+                : await probeWorkspace({
+                    workspaceRoot: workspacePath,
+                    agentId: activeAgentId,
+                });
+            if (parsed.message) {
+                await streamChatMessage({
+                    client,
+                    stdout,
+                    stdoutStream,
+                    stderr,
+                    stderrStream,
+                    agentId: activeAgentId,
+                    sessionId: activeSessionId,
+                    message: parsed.message,
+                    modelInfo: workspaceModelInfo,
+                    requestEvents: parsed.requestEvents,
+                    liveRequestTree: parsed.requestEvents && chatStdinStream.isTTY === true,
+                    colorRequestTree: useColor,
+                    showToolResults: parsed.requestEvents,
+                    showRunningState: false,
+                });
+                await client.stop();
+                restoreWriteListenerGuard?.();
+                restoreEmitterListenerGuard?.();
+                restoreStderrNoiseFilter?.();
+                restoreWarningFilter?.();
+                return 0;
+            }
+            stdout(renderChatBanner({
+                workspacePath,
+                transport: parsed.transport,
+                agentId: activeAgentId,
+                sessionId: activeSessionId,
+                color: useColor,
+            }));
+            if (preflightWarning) {
+                stdout(`${preflightWarning}\n\n`);
+            }
+            const stdoutSink = new Writable({
+                decodeStrings: false,
+                write(chunk, _encoding, callback) {
+                    stdout(typeof chunk === "string" ? chunk : String(chunk));
+                    callback();
+                },
+            });
+            const lineReader = createChatLineReader({
+                input: stdin,
+                output: stdoutSink,
+                crlfDelay: Infinity,
+                terminal: chatStdinStream.isTTY === true,
+            });
+            const interactiveState = await runInteractiveChatLoop({
+                client,
+                lineReader,
+                stdout,
+                stderr,
+                stdoutStream,
+                stderrStream,
+                workspacePath,
+                workspaceModelInfo,
+                requestEvents: parsed.requestEvents,
+                chatIsTty: chatStdinStream.isTTY === true,
+                useColor,
+                agentFilter: parsed.agentId,
+                activeAgentId,
+                activeSessionId,
+            });
+            activeAgentId = interactiveState.activeAgentId;
+            activeSessionId = interactiveState.activeSessionId;
+            latestRequestId = interactiveState.latestRequestId;
+            await client.stop();
+            restoreWriteListenerGuard?.();
+            restoreEmitterListenerGuard?.();
+            restoreStderrNoiseFilter?.();
+            restoreWarningFilter?.();
+            return 0;
+        }
+        catch (error) {
+            restoreWriteListenerGuard?.();
+            restoreEmitterListenerGuard?.();
+            restoreStderrNoiseFilter?.();
+            restoreWarningFilter?.();
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            if (client) {
+                await client.stop().catch(() => undefined);
+            }
+            return 1;
+        }
+    };
+    if (command === "init") {
+        if (!projectName?.trim()) {
+            stderr(renderUsage());
+            return 1;
+        }
+        const parsed = parseInitOptions(rest);
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        try {
+            const projectRoot = path.resolve(cwd, projectName);
+            const result = await initProject(projectRoot, projectName, parsed.options);
+            stdout(`Created ${result.projectSlug} at ${result.projectRoot}\n`);
+            stdout("Next steps:\n");
+            stdout(`  cd ${projectName}\n`);
+            stdout("  npm install\n");
+            if ((parsed.options?.provider ?? "openai") === "openai") {
+                stdout("  export OPENAI_API_KEY=your_key_here\n");
+            }
+            stdout('  npm run start -- "Research a topic"\n');
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            return 1;
+        }
+    }
+    if (command === "chat") {
+        const parsed = parseChatOptions([projectName, ...rest].filter((item) => typeof item === "string"));
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        return executeChat(parsed);
+    }
+    if (!isTopLevelCliCommand(command)) {
+        const parsed = parseChatOptions(argv);
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        return executeChat(parsed);
+    }
+    if (command === "acp") {
+        return handleAcpCommand([projectName, ...rest], { cwd, stderr }, {
+            createHarness,
+            serveAcp,
+            serveAcpHttp,
+            spawnManagedCliProcess,
+            isManagedProcessRunning,
+            signalManagedProcess,
+            serveA2a,
+            serveAgUi,
+            serveRuntimeMcp,
+            serveRuntimeMcpStreamableHttp,
+        });
+    }
+    if (command === "ag-ui") {
+        return handleAgUiCommand([projectName, ...rest], { cwd, stderr }, { createHarness, serveAgUi });
+    }
+    if (command === "a2a") {
+        return handleA2aCommand([projectName, ...rest], { cwd, stderr }, {
+            createHarness,
+            serveA2a,
+            spawnManagedCliProcess,
+            isManagedProcessRunning,
+            signalManagedProcess,
+        });
+    }
+    if (command === "mcp" || command === "runtime-mcp") {
+        return handleMcpCommand([projectName, ...rest], { cwd, stderr }, {
+            createHarness,
+            serveRuntimeMcp,
+            serveRuntimeMcpStreamableHttp,
+            spawnManagedCliProcess,
+            isManagedProcessRunning,
+            signalManagedProcess,
+        });
+    }
+    if (command === "runtime") {
+        return handleRuntimeCommand([projectName, ...rest], { cwd, stdout, stderr }, {
+            createHarness,
+            ...(deps.createAgentHarness ? {} : { createClient: createAgentHarnessClient }),
+            sleep,
+        });
+    }
+    stderr(renderUsage());
+    return 1;
+}
+export function resolveInvokedCliHref(argvPath) {
+    if (!argvPath) {
+        return "";
+    }
+    const resolved = path.resolve(argvPath);
+    const realPath = existsSync(resolved) ? realpathSync(resolved) : resolved;
+    return pathToFileURL(realPath).href;
+}

package/dist/cli/managed-service-commands.d.ts

@@ -0,0 +1,23 @@
+import { type ManagedCliService } from "./managed-service.js";
+export declare function startManagedHttpService(input: {
+    service: ManagedCliService;
+    workspacePath: string;
+    args: string[];
+    stderr: (message: string) => void;
+    spawnManagedCliProcess: (input: {
+        args: string[];
+        cwd: string;
+        stdoutPath: string;
+        stderrPath: string;
+    }) => Promise<{
+        pid?: number;
+    }>;
+    isManagedProcessRunning: (pid: number) => boolean;
+}): Promise<number>;
+export declare function stopManagedHttpService(input: {
+    service: ManagedCliService;
+    workspacePath: string;
+    stderr: (message: string) => void;
+    isManagedProcessRunning: (pid: number) => boolean;
+    signalManagedProcess: (pid: number, signal?: NodeJS.Signals) => void;
+}): Promise<number>;

package/dist/cli/managed-service-commands.js

@@ -0,0 +1,63 @@
+import { clearManagedServiceState, managedServiceLogPath, readManagedServiceState, sleep, writeManagedServiceState, } from "./managed-service.js";
+export async function startManagedHttpService(input) {
+    const existing = await readManagedServiceState(input.workspacePath, input.service);
+    if (existing && input.isManagedProcessRunning(existing.pid)) {
+        input.stderr(`${input.service.toUpperCase()} service is already running for ${input.workspacePath} (pid ${existing.pid}).\n`);
+        return 0;
+    }
+    if (existing) {
+        await clearManagedServiceState(input.workspacePath, input.service);
+    }
+    const stdoutPath = managedServiceLogPath(input.workspacePath, input.service, "stdout");
+    const stderrPath = managedServiceLogPath(input.workspacePath, input.service, "stderr");
+    const spawned = await input.spawnManagedCliProcess({
+        args: input.args,
+        cwd: input.workspacePath,
+        stdoutPath,
+        stderrPath,
+    });
+    if (!spawned.pid || spawned.pid <= 0) {
+        input.stderr(`Failed to start ${input.service.toUpperCase()} service for ${input.workspacePath}.\n`);
+        return 1;
+    }
+    await writeManagedServiceState({
+        pid: spawned.pid,
+        service: input.service,
+        workspaceRoot: input.workspacePath,
+        transport: input.service === "mcp" ? "streamable-http" : "http",
+        startedAt: new Date().toISOString(),
+        stdoutPath,
+        stderrPath,
+    });
+    await sleep(250);
+    if (!input.isManagedProcessRunning(spawned.pid)) {
+        await clearManagedServiceState(input.workspacePath, input.service);
+        input.stderr(`Failed to keep ${input.service.toUpperCase()} service running for ${input.workspacePath}. Check ${stderrPath}.\n`);
+        return 1;
+    }
+    input.stderr(`Started ${input.service.toUpperCase()} service for ${input.workspacePath} (pid ${spawned.pid}). Logs: ${stdoutPath}, ${stderrPath}\n`);
+    return 0;
+}
+export async function stopManagedHttpService(input) {
+    const existing = await readManagedServiceState(input.workspacePath, input.service);
+    if (!existing) {
+        input.stderr(`No managed ${input.service.toUpperCase()} service is recorded for ${input.workspacePath}.\n`);
+        return 0;
+    }
+    if (!input.isManagedProcessRunning(existing.pid)) {
+        await clearManagedServiceState(input.workspacePath, input.service);
+        input.stderr(`Managed ${input.service.toUpperCase()} service for ${input.workspacePath} is already stopped.\n`);
+        return 0;
+    }
+    input.signalManagedProcess(existing.pid, "SIGTERM");
+    for (let attempt = 0; attempt < 20; attempt += 1) {
+        await sleep(100);
+        if (!input.isManagedProcessRunning(existing.pid)) {
+            await clearManagedServiceState(input.workspacePath, input.service);
+            input.stderr(`Stopped ${input.service.toUpperCase()} service for ${input.workspacePath}.\n`);
+            return 0;
+        }
+    }
+    input.stderr(`Timed out while stopping ${input.service.toUpperCase()} service for ${input.workspacePath} (pid ${existing.pid}).\n`);
+    return 1;
+}