@botbotgo/agent-harness 0.0.308 → 0.0.310

package/dist/cli/runtime-commands.js

@@ -0,0 +1,247 @@
+import { renderApprovalList, renderHealthSnapshot, renderJson, renderOperatorOverview, renderRequestList } from "./runtime-output.js";
+import { parseRuntimeExportOptions, parseRuntimeInspectOptions, parseScheduledRunOptions, renderUsage } from "./options.js";
+import { resolveCliWorkspaceRoot, validateCliWorkspaceRoot } from "./workspace.js";
+function resolveValidatedWorkspace(cwd, workspaceRoot, stderr) {
+    const workspacePath = resolveCliWorkspaceRoot(cwd, workspaceRoot);
+    const workspaceError = validateCliWorkspaceRoot(workspacePath, workspaceRoot);
+    if (workspaceError) {
+        stderr(`${workspaceError}\n`);
+        return undefined;
+    }
+    return workspacePath;
+}
+export async function handleRuntimeCommand(subcommandAndArgs, io, deps) {
+    const { cwd, stdout, stderr } = io;
+    const { createHarness, createClient } = deps;
+    const [subcommand, possibleNestedCommand, possibleThirdCommand, ...remainingArgs] = subcommandAndArgs;
+    if (!subcommand) {
+        stderr(renderUsage());
+        return 1;
+    }
+    if (subcommand === "scheduled-run") {
+        const parsed = parseScheduledRunOptions([possibleNestedCommand, possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string"));
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        if (!parsed.scheduleId) {
+            stderr("Missing value for --schedule\n");
+            stderr(renderUsage());
+            return 1;
+        }
+        try {
+            const workspacePath = resolveValidatedWorkspace(cwd, parsed.workspaceRoot, stderr);
+            if (!workspacePath) {
+                return 1;
+            }
+            const runtime = await createHarness(workspacePath);
+            try {
+                const result = await runtime.runScheduledTask(parsed.scheduleId);
+                stdout(`${String(result.output ?? "").trim()}\n`);
+            }
+            finally {
+                await runtime.stop();
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            return 1;
+        }
+    }
+    if (subcommand === "export") {
+        const exportTarget = possibleNestedCommand;
+        const parsed = parseRuntimeExportOptions([possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string"));
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        if (!parsed.sessionId) {
+            stderr("Missing value for --session\n");
+            stderr(renderUsage());
+            return 1;
+        }
+        if (exportTarget !== "request" && exportTarget !== "session") {
+            stderr(renderUsage());
+            return 1;
+        }
+        if (exportTarget === "request" && !parsed.requestId) {
+            stderr("Missing value for --request\n");
+            stderr(renderUsage());
+            return 1;
+        }
+        try {
+            const workspacePath = resolveValidatedWorkspace(cwd, parsed.workspaceRoot, stderr);
+            if (!workspacePath) {
+                return 1;
+            }
+            const runtime = await createHarness(workspacePath);
+            try {
+                if (exportTarget === "request") {
+                    const pkg = await runtime.exportRequestPackage({
+                        sessionId: parsed.sessionId,
+                        requestId: parsed.requestId,
+                        includeArtifacts: parsed.includeArtifacts,
+                        includeArtifactContents: parsed.includeArtifactContents,
+                        includeRuntimeHealth: parsed.includeRuntimeHealth,
+                    });
+                    stdout(renderJson(pkg));
+                }
+                else {
+                    const pkg = await runtime.exportSessionPackage({
+                        sessionId: parsed.sessionId,
+                        includeArtifacts: parsed.includeArtifacts,
+                        includeArtifactContents: parsed.includeArtifactContents,
+                        includeRuntimeHealth: parsed.includeRuntimeHealth,
+                    });
+                    stdout(renderJson(pkg));
+                }
+            }
+            finally {
+                await runtime.stop();
+            }
+            return 0;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            stderr(`${message}\n`);
+            return 1;
+        }
+    }
+    const nestedCommand = (subcommand === "approvals" || subcommand === "requests") && possibleNestedCommand
+        ? possibleNestedCommand
+        : undefined;
+    const subcommandArgs = nestedCommand
+        ? [possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string")
+        : [possibleNestedCommand, possibleThirdCommand, ...remainingArgs].filter((item) => typeof item === "string");
+    const parsed = parseRuntimeInspectOptions(subcommandArgs);
+    if (parsed.error) {
+        stderr(`${parsed.error}\n`);
+        stderr(renderUsage());
+        return 1;
+    }
+    try {
+        const workspacePath = resolveValidatedWorkspace(cwd, parsed.workspaceRoot, stderr);
+        if (!workspacePath) {
+            return 1;
+        }
+        const shouldUseClient = subcommand === "health"
+            || subcommand === "overview"
+            || (subcommand === "approvals" && (nestedCommand === "list" || nestedCommand === "watch"))
+            || (subcommand === "requests" && (nestedCommand === "list" || nestedCommand === "tail"));
+        if (shouldUseClient && createClient) {
+            const client = await createClient(workspacePath);
+            try {
+                if (subcommand === "health") {
+                    const snapshot = await client.getHealth();
+                    stdout(parsed.json ? renderJson(snapshot) : renderHealthSnapshot(snapshot, workspacePath));
+                    return 0;
+                }
+                if (subcommand === "overview") {
+                    const overview = await client.getOperatorOverview({ limit: parsed.limit });
+                    stdout(parsed.json ? renderJson(overview) : renderOperatorOverview(overview, workspacePath));
+                    return 0;
+                }
+                if (subcommand === "approvals" && (nestedCommand === "list" || nestedCommand === "watch")) {
+                    const renderApprovals = async () => {
+                        const approvals = await client.listApprovals(parsed.status ? { status: parsed.status } : undefined);
+                        stdout(parsed.json ? renderJson(approvals) : renderApprovalList(approvals));
+                    };
+                    await renderApprovals();
+                    if (nestedCommand === "watch" && !parsed.once) {
+                        for (;;) {
+                            await deps.sleep(parsed.pollMs);
+                            await renderApprovals();
+                        }
+                    }
+                    return 0;
+                }
+                if (subcommand === "requests" && (nestedCommand === "list" || nestedCommand === "tail")) {
+                    const renderRequests = async () => {
+                        const requests = await client.listRequests({
+                            ...(parsed.agentId ? { agentId: parsed.agentId } : {}),
+                            ...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
+                            ...(parsed.state ? { state: parsed.state } : {}),
+                        });
+                        stdout(parsed.json ? renderJson(requests) : renderRequestList(requests));
+                    };
+                    await renderRequests();
+                    if (nestedCommand === "tail" && !parsed.once) {
+                        for (;;) {
+                            await deps.sleep(parsed.pollMs);
+                            await renderRequests();
+                        }
+                    }
+                    return 0;
+                }
+            }
+            finally {
+                await client.stop();
+            }
+        }
+        if (shouldUseClient) {
+            const runtime = await createHarness(workspacePath);
+            try {
+                if (subcommand === "health") {
+                    const snapshot = await runtime.getHealth();
+                    stdout(parsed.json ? renderJson(snapshot) : renderHealthSnapshot(snapshot, workspacePath));
+                    return 0;
+                }
+                if (subcommand === "overview") {
+                    const overview = await runtime.getOperatorOverview({ limit: parsed.limit });
+                    stdout(parsed.json ? renderJson(overview) : renderOperatorOverview(overview, workspacePath));
+                    return 0;
+                }
+                if (subcommand === "approvals" && (nestedCommand === "list" || nestedCommand === "watch")) {
+                    const renderApprovals = async () => {
+                        const approvals = await runtime.listApprovals(parsed.status ? { status: parsed.status } : undefined);
+                        stdout(parsed.json ? renderJson(approvals) : renderApprovalList(approvals));
+                    };
+                    await renderApprovals();
+                    if (nestedCommand === "watch" && !parsed.once) {
+                        for (;;) {
+                            await deps.sleep(parsed.pollMs);
+                            await renderApprovals();
+                        }
+                    }
+                    return 0;
+                }
+                if (subcommand === "requests" && (nestedCommand === "list" || nestedCommand === "tail")) {
+                    const renderRequests = async () => {
+                        const listRequests = runtime.listRequests?.bind(runtime);
+                        if (!listRequests) {
+                            throw new Error("Runtime does not support request listing");
+                        }
+                        const requests = await listRequests({
+                            ...(parsed.agentId ? { agentId: parsed.agentId } : {}),
+                            ...(parsed.sessionId ? { sessionId: parsed.sessionId } : {}),
+                            ...(parsed.state ? { state: parsed.state } : {}),
+                        });
+                        stdout(parsed.json ? renderJson(requests) : renderRequestList(requests));
+                    };
+                    await renderRequests();
+                    if (nestedCommand === "tail" && !parsed.once) {
+                        for (;;) {
+                            await deps.sleep(parsed.pollMs);
+                            await renderRequests();
+                        }
+                    }
+                    return 0;
+                }
+            }
+            finally {
+                await runtime.stop();
+            }
+        }
+        stderr(renderUsage());
+        return 1;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`${message}\n`);
+        return 1;
+    }
+}

package/dist/cli/runtime-output.d.ts

@@ -0,0 +1,5 @@
+export declare function renderJson(value: unknown): string;
+export declare function renderHealthSnapshot(snapshot: Record<string, unknown>, workspacePath: string): string;
+export declare function renderApprovalList(approvals: Array<Record<string, unknown>>): string;
+export declare function renderRequestList(requests: Array<Record<string, unknown>>): string;
+export declare function renderOperatorOverview(overview: Record<string, unknown>, workspacePath: string): string;

package/dist/cli/runtime-output.js

@@ -0,0 +1,124 @@
+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;
+}
+export function renderJson(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+export function renderHealthSnapshot(snapshot, workspacePath) {
+    const lines = [];
+    const status = typeof snapshot.status === "string" ? snapshot.status : "unknown";
+    lines.push(`Runtime health ${workspacePath}: ${status}`);
+    const checks = isObject(snapshot.checks) ? snapshot.checks : {};
+    const checkEntries = Object.entries(checks)
+        .filter(([, value]) => isObject(value))
+        .map(([name, value]) => {
+        const check = value;
+        const reason = typeof check.reason === "string" && check.reason.trim().length > 0 ? ` (${check.reason})` : "";
+        return `  - ${name}: ${typeof check.status === "string" ? check.status : "unknown"}${reason}`;
+    });
+    if (checkEntries.length > 0) {
+        lines.push("Checks:");
+        lines.push(...checkEntries);
+    }
+    const stats = isObject(snapshot.stats) ? snapshot.stats : {};
+    const statEntries = [
+        ["activeRequestSlots", stats.activeRequestSlots],
+        ["pendingRequestSlots", stats.pendingRequestSlots],
+        ["pendingApprovals", stats.pendingApprovals],
+        ["stuckRequests", stats.stuckRequests],
+        ["llmSuccessRate1m", stats.llmSuccessRate1m],
+        ["llmP95LatencyMs1m", stats.llmP95LatencyMs1m],
+    ]
+        .filter(([, value]) => typeof value === "number")
+        .map(([name, value]) => `  - ${name}: ${value}`);
+    if (statEntries.length > 0) {
+        lines.push("Stats:");
+        lines.push(...statEntries);
+    }
+    const symptoms = Array.isArray(snapshot.symptoms) ? snapshot.symptoms.filter(isObject) : [];
+    if (symptoms.length > 0) {
+        lines.push("Symptoms:");
+        lines.push(...symptoms.map((symptom) => {
+            const code = typeof symptom.code === "string" ? symptom.code : "unknown";
+            const severity = typeof symptom.severity === "string" ? symptom.severity : "unknown";
+            const message = typeof symptom.message === "string" ? symptom.message : "";
+            return `  - ${code}: ${severity}${message ? ` (${message})` : ""}`;
+        }));
+    }
+    return `${lines.join("\n")}\n`;
+}
+export function renderApprovalList(approvals) {
+    if (approvals.length === 0) {
+        return "No approvals matched.\n";
+    }
+    return approvals.map((approval) => {
+        const status = typeof approval.status === "string" ? approval.status : "unknown";
+        const toolName = typeof approval.toolName === "string" ? approval.toolName : "unknown_tool";
+        const approvalId = typeof approval.approvalId === "string" ? approval.approvalId : "unknown";
+        const sessionId = typeof approval.sessionId === "string" ? ` session=${approval.sessionId}` : "";
+        const requestId = typeof approval.requestId === "string" ? ` request=${approval.requestId}` : "";
+        const reason = typeof approval.approvalReason === "string" ? ` reason=${approval.approvalReason}` : "";
+        const requestedAt = formatTimestamp(approval.requestedAt);
+        const resolvedAt = formatTimestamp(approval.resolvedAt);
+        const requested = requestedAt ? ` requested=${requestedAt}` : "";
+        const resolved = resolvedAt ? ` resolved=${resolvedAt}` : "";
+        return `${approvalId} status=${status} tool=${toolName}${sessionId}${requestId}${reason}${requested}${resolved}`;
+    }).join("\n") + "\n";
+}
+export function renderRequestList(requests) {
+    if (requests.length === 0) {
+        return "No requests matched.\n";
+    }
+    return requests.map((request) => {
+        const requestId = typeof request.requestId === "string" ? request.requestId : "unknown";
+        const sessionId = typeof request.sessionId === "string" ? request.sessionId : "unknown";
+        const agentId = typeof request.agentId === "string" ? request.agentId : "unknown";
+        const state = typeof request.state === "string" ? request.state : "unknown";
+        const currentAgent = typeof request.currentAgentId === "string" ? ` current=${request.currentAgentId}` : "";
+        const resumable = typeof request.resumable === "boolean" ? ` resumable=${request.resumable}` : "";
+        const updatedAt = formatTimestamp(request.updatedAt);
+        const lastActivityAt = formatTimestamp(request.lastActivityAt);
+        const updated = updatedAt ? ` updated=${updatedAt}` : "";
+        const lastActivity = lastActivityAt ? ` activity=${lastActivityAt}` : "";
+        return `${requestId} session=${sessionId} agent=${agentId}${currentAgent} state=${state}${resumable}${updated}${lastActivity}`;
+    }).join("\n") + "\n";
+}
+export function renderOperatorOverview(overview, workspacePath) {
+    const lines = [];
+    const summary = typeof overview.summary === "string" ? overview.summary : "";
+    lines.push(`Runtime overview ${workspacePath}`);
+    if (summary) {
+        lines.push(`Summary: ${summary}`);
+    }
+    const health = isObject(overview.health) ? overview.health : {};
+    if (Object.keys(health).length > 0) {
+        lines.push("");
+        lines.push(renderHealthSnapshot(health, workspacePath).trimEnd());
+    }
+    const queue = isObject(overview.queue) ? overview.queue : {};
+    if (Object.keys(queue).length > 0) {
+        lines.push("");
+        lines.push(`Queue: ${typeof queue.summary === "string" ? queue.summary : "unavailable"}`);
+    }
+    const governance = isObject(overview.governance) ? overview.governance : {};
+    if (Object.keys(governance).length > 0) {
+        lines.push("Governance:");
+        lines.push(`  - ${typeof governance.summary === "string" ? governance.summary : "unavailable"}`);
+    }
+    const approvals = isObject(overview.approvals) ? overview.approvals : {};
+    const approvalItems = Array.isArray(approvals.items) ? approvals.items.filter(isObject) : [];
+    lines.push(`Pending approvals: ${typeof approvals.total === "number" ? approvals.total : approvalItems.length}`);
+    if (approvalItems.length > 0) {
+        lines.push(renderApprovalList(approvalItems).trimEnd());
+    }
+    const requests = isObject(overview.requests) ? overview.requests : {};
+    const requestItems = Array.isArray(requests.items) ? requests.items.filter(isObject) : [];
+    lines.push(`Active requests: ${typeof requests.total === "number" ? requests.total : requestItems.length}`);
+    if (requestItems.length > 0) {
+        lines.push(renderRequestList(requestItems).trimEnd());
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/cli/server-commands.d.ts

@@ -0,0 +1,36 @@
+import { createAgentHarness } from "../api.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";
+type CommandIo = {
+    cwd: string;
+    stderr: (message: string) => void;
+};
+type ManagedDeps = {
+    spawnManagedCliProcess: (input: {
+        args: string[];
+        cwd: string;
+        stdoutPath: string;
+        stderrPath: string;
+    }) => Promise<{
+        pid?: number;
+    }>;
+    isManagedProcessRunning: (pid: number) => boolean;
+    signalManagedProcess: (pid: number, signal?: NodeJS.Signals) => void;
+};
+type ServerDeps = ManagedDeps & {
+    createHarness: typeof createAgentHarness;
+    serveA2a: typeof serveA2aOverHttp;
+    serveAgUi: typeof serveAgUiOverHttp;
+    serveAcpHttp: typeof serveAcpOverHttp;
+    serveAcp: typeof serveAcpOverStdio;
+    serveRuntimeMcp: typeof serveRuntimeMcpOverStdio;
+    serveRuntimeMcpStreamableHttp: typeof serveRuntimeMcpOverStreamableHttp;
+};
+export declare function handleAcpCommand(subcommandAndArgs: string[], io: CommandIo, deps: ServerDeps): Promise<number>;
+export declare function handleAgUiCommand(subcommandAndArgs: string[], io: CommandIo, deps: Pick<ServerDeps, "createHarness" | "serveAgUi">): Promise<number>;
+export declare function handleA2aCommand(subcommandAndArgs: string[], io: CommandIo, deps: Pick<ServerDeps, "createHarness" | "serveA2a"> & ManagedDeps): Promise<number>;
+export declare function handleMcpCommand(subcommandAndArgs: string[], io: CommandIo, deps: Pick<ServerDeps, "createHarness" | "serveRuntimeMcp" | "serveRuntimeMcpStreamableHttp"> & ManagedDeps): Promise<number>;
+export {};

package/dist/cli/server-commands.js

@@ -0,0 +1,250 @@
+import { parseAcpServeOptions, parseHttpServeOptions, parseRuntimeMcpServeOptions, parseWorkspaceOnlyOptions, renderUsage } from "./options.js";
+import { startManagedHttpService, stopManagedHttpService } from "./managed-service-commands.js";
+import { resolveCliWorkspaceRoot, validateCliWorkspaceRoot } from "./workspace.js";
+function resolveValidatedWorkspace(cwd, workspaceRoot, stderr) {
+    const workspacePath = resolveCliWorkspaceRoot(cwd, workspaceRoot);
+    const workspaceError = validateCliWorkspaceRoot(workspacePath, workspaceRoot);
+    if (workspaceError) {
+        stderr(`${workspaceError}\n`);
+        return undefined;
+    }
+    return workspacePath;
+}
+export async function handleAcpCommand(subcommandAndArgs, io, deps) {
+    const [subcommand, ...subcommandArgs] = subcommandAndArgs;
+    const { cwd, stderr } = io;
+    const { createHarness, serveAcp, serveAcpHttp, spawnManagedCliProcess, isManagedProcessRunning, signalManagedProcess } = deps;
+    if (subcommand !== "serve" && subcommand !== "start" && subcommand !== "stop") {
+        stderr(renderUsage());
+        return 1;
+    }
+    const parsedStop = subcommand === "stop" ? parseWorkspaceOnlyOptions(subcommandArgs) : undefined;
+    const parsedServe = subcommand !== "stop"
+        ? parseAcpServeOptions(subcommandArgs, subcommand === "start" ? "http" : "stdio")
+        : undefined;
+    const parseError = parsedStop?.error ?? parsedServe?.error;
+    if (parseError) {
+        stderr(`${parseError}\n`);
+        stderr(renderUsage());
+        return 1;
+    }
+    try {
+        const workspaceRoot = parsedStop?.workspaceRoot ?? parsedServe?.workspaceRoot;
+        const workspacePath = resolveValidatedWorkspace(cwd, workspaceRoot, stderr);
+        if (!workspacePath) {
+            return 1;
+        }
+        if (subcommand === "start") {
+            if (!parsedServe) {
+                stderr(renderUsage());
+                return 1;
+            }
+            if (parsedServe.transport !== "http") {
+                stderr("ACP start only supports --transport http. Use `acp serve --transport stdio` for stdio clients.\n");
+                return 1;
+            }
+            const args = ["acp", "serve", "--workspace", workspacePath, "--transport", "http"];
+            if (parsedServe.hostname) {
+                args.push("--host", parsedServe.hostname);
+            }
+            if (typeof parsedServe.port === "number") {
+                args.push("--port", String(parsedServe.port));
+            }
+            return startManagedHttpService({ service: "acp", workspacePath, args, stderr, spawnManagedCliProcess, isManagedProcessRunning });
+        }
+        if (subcommand === "stop") {
+            return stopManagedHttpService({ service: "acp", workspacePath, stderr, isManagedProcessRunning, signalManagedProcess });
+        }
+        if (!parsedServe) {
+            stderr(renderUsage());
+            return 1;
+        }
+        const runtime = await createHarness(workspacePath);
+        if (parsedServe.transport === "http") {
+            const server = await serveAcpHttp(runtime, {
+                hostname: parsedServe.hostname,
+                port: parsedServe.port,
+            });
+            stderr(`Serving ACP over http from ${workspacePath} at ${server.rpcUrl} (events ${server.eventsUrl})\n`);
+            await server.completed;
+        }
+        else {
+            stderr(`Serving ACP over stdio from ${workspacePath}\n`);
+            const server = serveAcp(runtime);
+            await server.completed;
+        }
+        await runtime.stop();
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`${message}\n`);
+        return 1;
+    }
+}
+export async function handleAgUiCommand(subcommandAndArgs, io, deps) {
+    const [subcommand, ...subcommandArgs] = subcommandAndArgs;
+    const { cwd, stderr } = io;
+    const { createHarness, serveAgUi } = deps;
+    if (subcommand !== "serve") {
+        stderr(renderUsage());
+        return 1;
+    }
+    const parsed = parseHttpServeOptions(subcommandArgs, "AG-UI");
+    if (parsed.error) {
+        stderr(`${parsed.error}\n`);
+        stderr(renderUsage());
+        return 1;
+    }
+    try {
+        const workspacePath = resolveValidatedWorkspace(cwd, parsed.workspaceRoot, stderr);
+        if (!workspacePath) {
+            return 1;
+        }
+        const runtime = await createHarness(workspacePath);
+        const server = await serveAgUi(runtime, {
+            hostname: parsed.hostname,
+            port: parsed.port,
+        });
+        stderr(`Serving AG-UI over http from ${workspacePath} at ${server.runUrl}\n`);
+        await server.completed;
+        await runtime.stop();
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`${message}\n`);
+        return 1;
+    }
+}
+export async function handleA2aCommand(subcommandAndArgs, io, deps) {
+    const [subcommand, ...subcommandArgs] = subcommandAndArgs;
+    const { cwd, stderr } = io;
+    const { createHarness, serveA2a, spawnManagedCliProcess, isManagedProcessRunning, signalManagedProcess } = deps;
+    if (subcommand !== "serve" && subcommand !== "start" && subcommand !== "stop") {
+        stderr(renderUsage());
+        return 1;
+    }
+    const parsedStop = subcommand === "stop" ? parseWorkspaceOnlyOptions(subcommandArgs) : undefined;
+    const parsedServe = subcommand !== "stop" ? parseHttpServeOptions(subcommandArgs, "A2A") : undefined;
+    const parseError = parsedStop?.error ?? parsedServe?.error;
+    if (parseError) {
+        stderr(`${parseError}\n`);
+        stderr(renderUsage());
+        return 1;
+    }
+    try {
+        const workspaceRoot = parsedStop?.workspaceRoot ?? parsedServe?.workspaceRoot;
+        const workspacePath = resolveValidatedWorkspace(cwd, workspaceRoot, stderr);
+        if (!workspacePath) {
+            return 1;
+        }
+        if (subcommand === "start") {
+            const args = ["a2a", "serve", "--workspace", workspacePath];
+            if (parsedServe?.hostname) {
+                args.push("--host", parsedServe.hostname);
+            }
+            if (typeof parsedServe?.port === "number") {
+                args.push("--port", String(parsedServe.port));
+            }
+            return startManagedHttpService({ service: "a2a", workspacePath, args, stderr, spawnManagedCliProcess, isManagedProcessRunning });
+        }
+        if (subcommand === "stop") {
+            return stopManagedHttpService({ service: "a2a", workspacePath, stderr, isManagedProcessRunning, signalManagedProcess });
+        }
+        if (!parsedServe) {
+            stderr(renderUsage());
+            return 1;
+        }
+        const runtime = await createHarness(workspacePath);
+        const server = await serveA2a(runtime, {
+            hostname: parsedServe.hostname,
+            port: parsedServe.port,
+        });
+        stderr(`Serving A2A over http from ${workspacePath} at ${server.rpcUrl} (card ${server.agentCardUrl})\n`);
+        await server.completed;
+        await runtime.stop();
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`${message}\n`);
+        return 1;
+    }
+}
+export async function handleMcpCommand(subcommandAndArgs, io, deps) {
+    const [subcommand, ...subcommandArgs] = subcommandAndArgs;
+    const { cwd, stderr } = io;
+    const { createHarness, serveRuntimeMcp, serveRuntimeMcpStreamableHttp, spawnManagedCliProcess, isManagedProcessRunning, signalManagedProcess } = deps;
+    if (subcommand !== "serve" && subcommand !== "start" && subcommand !== "stop") {
+        stderr(renderUsage());
+        return 1;
+    }
+    const parsedStop = subcommand === "stop" ? parseWorkspaceOnlyOptions(subcommandArgs) : undefined;
+    const parsedServe = subcommand !== "stop"
+        ? parseRuntimeMcpServeOptions(subcommandArgs, subcommand === "start" ? "streamable-http" : "stdio")
+        : undefined;
+    const parseError = parsedStop?.error ?? parsedServe?.error;
+    if (parseError) {
+        stderr(`${parseError}\n`);
+        stderr(renderUsage());
+        return 1;
+    }
+    try {
+        const workspaceRoot = parsedStop?.workspaceRoot ?? parsedServe?.workspaceRoot;
+        const workspacePath = resolveValidatedWorkspace(cwd, workspaceRoot, stderr);
+        if (!workspacePath) {
+            return 1;
+        }
+        if (subcommand === "start") {
+            if (!parsedServe) {
+                stderr(renderUsage());
+                return 1;
+            }
+            if (parsedServe.transport !== "streamable-http") {
+                stderr("MCP start only supports --transport streamable-http. Use `mcp serve --transport stdio` for stdio clients.\n");
+                return 1;
+            }
+            const args = ["mcp", "serve", "--workspace", workspacePath, "--transport", "streamable-http"];
+            if (parsedServe.hostname) {
+                args.push("--host", parsedServe.hostname);
+            }
+            if (typeof parsedServe.port === "number") {
+                args.push("--port", String(parsedServe.port));
+            }
+            return startManagedHttpService({ service: "mcp", workspacePath, args, stderr, spawnManagedCliProcess, isManagedProcessRunning });
+        }
+        if (subcommand === "stop") {
+            return stopManagedHttpService({ service: "mcp", workspacePath, stderr, isManagedProcessRunning, signalManagedProcess });
+        }
+        if (!parsedServe) {
+            stderr(renderUsage());
+            return 1;
+        }
+        const runtime = await createHarness(workspacePath);
+        if (parsedServe.transport === "streamable-http") {
+            const server = await serveRuntimeMcpStreamableHttp(runtime, {
+                hostname: parsedServe.hostname,
+                port: parsedServe.port,
+            });
+            stderr(`Serving runtime MCP over streamable HTTP from ${workspacePath} at ${server.url}\n`);
+            await server.completed;
+        }
+        else {
+            stderr(`Serving runtime MCP over stdio from ${workspacePath}\n`);
+            const server = await serveRuntimeMcp(runtime);
+            await new Promise((resolve, reject) => {
+                process.stdin.on("end", resolve);
+                process.stdin.on("error", reject);
+            });
+            await server.close();
+        }
+        await runtime.stop();
+        return 0;
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        stderr(`${message}\n`);
+        return 1;
+    }
+}

package/dist/cli/workspace.d.ts

@@ -0,0 +1,6 @@
+export declare function resolveCliWorkspaceRoot(cwd: string, inputPath?: string): string;
+export declare function getWorkspaceConfigPath(workspaceRoot: string): string;
+export declare function hasCliConfigYaml(configRoot: string): boolean;
+export declare function validateCliWorkspaceRoot(workspaceRoot: string, inputPath?: string): string | undefined;
+export declare function resolveCliConfigRoot(workspaceRoot: string): string;
+export declare function frameworkCliWorkspaceRoot(): string;