@botbotgo/agent-harness 0.0.324 → 0.0.325

package/README.md

@@ -1195,6 +1195,7 @@ ACP transport notes:
 - ACP transport validation now covers the reference-client core flow: capability discovery, request submit, session lookup, request lookup, invalid-JSON handling, notification calls without response ids, stdio JSON-RPC, and HTTP plus SSE runtime notifications.
 - Cross-protocol conformance now has an explicit regression gate as well: ACP submission, A2A task lookup and continuation, and runtime MCP inspection must all project the same persisted `sessionId` / `requestId` runtime records instead of drifting into surface-specific identifiers or side stores.
 - For the thinnest editor or CLI starter, begin with `agent-harness acp serve --workspace . --transport stdio` and mirror the `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` wire shape. Applications that want an in-process reference client can use `createAcpStdioClient(...)` to issue JSON-RPC requests and route runtime notifications without hand-rolling line parsing.
+- For the shortest local operator workflow, `botbotgo start --workspace .` now starts ACP, A2A, runtime MCP, and AG-UI together as managed local services, and `botbotgo stop --workspace .` stops the same set. `--services acp,mcp` narrows the set when one workspace only needs part of the local protocol surface.
 - When a local ACP HTTP endpoint should stay up beyond one foreground shell, use `botbotgo acp start --workspace . --host 127.0.0.1 --port 8787` and later `botbotgo acp stop --workspace .`. The CLI records the managed process under `.botbotgo/services/` so local operators can start and stop it without a second process manager.
 - `botbotgo` is the shortest local terminal entrypoint for a published install. It defaults the workspace to the current directory, so teams can `cd` into their own runtime workspace and run `botbotgo` or `botbotgo "..."` directly. `agent-harness` keeps the same implicit-chat behavior, and `-w/--workspace` still lets one shell point at another workspace when needed.
 - `agent-harness chat --workspace .` still acts as a local terminal shell over the shared `HarnessClient` contract when you want the explicit subcommand form: the default `stdio` path runs directly in-process against the workspace runtime, while `--transport http --host <host> --port <port>` can still target an already-running ACP HTTP endpoint. One-shot use can pass `--message`, while interactive mode supports `/context`, `/new`, `/agent <agentId>`, `/sessions`, `/requests`, `/resume <sessionId>`, `/approvals`, `/approve`, `/reject`, `/cancel`, `/events`, `/trace`, `/health`, `/overview`, `/session`, `/request [requestId]`, and `/exit`. `/resume` now validates the target session, restores its latest request id, and rehydrates the active agent context; `/request <requestId>` can switch the active request context to a persisted request; `/new` clears the current session/request context without leaving the shell. Terminal chat now keeps one operator-facing flow: it streams tool and progress events as they happen and still prints the full final answer, instead of switching to a separate request-tree-only mode.
@@ -1205,7 +1206,7 @@ ACP transport notes:
 - The interactive prompt now carries the live `agent`, `session`, and short `request` identifier together, so after each reply and during shell-history navigation the user stays anchored to the current runtime turn instead of dropping back to a bare input prompt.
 - `serveA2aHttp(runtime)` exposes an A2A-compatible HTTP JSON-RPC bridge plus agent card discovery, mapping both existing methods such as `message/send` and A2A v1.0 PascalCase methods such as `SendMessage`, `SendStreamingMessage`, `GetTask`, `ListTasks`, `CancelTask`, `SubscribeToTask`, `GetAgentCard`, `GetExtendedAgentCard`, and task push-notification config methods onto the existing session/request runtime surface. The bridge now advertises both `1.0` and `0.3` JSON-RPC interfaces, answers `HEAD` / `OPTIONS` discovery on the agent-card path, sets supported-version discovery headers, can optionally expose registry URLs plus detached signed-card metadata for surrounding discovery systems, validates `A2A-Version`, records `A2A-Extensions` into runtime invocation metadata, publishes `TASK_STATE_*` statuses plus the `{ task }` `SendMessage` wrapper, streams an initial `{ task }` snapshot plus later `{ statusUpdate }` payloads over SSE for v1 streaming methods, and can send best-effort webhook task snapshots for configured push notification receivers.
 - For a managed local bridge, use `botbotgo a2a start --workspace . --host 127.0.0.1 --port 8080` and later `botbotgo a2a stop --workspace .`. This uses the same `.botbotgo/services/` state directory as ACP so both local protocol bridges follow one terminal-first workflow.
-- `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, safe progress commentary, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `STATUS_UPDATE`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients.
+- `serveAgUiHttp(runtime)` exposes an AG-UI-compatible HTTP SSE bridge that projects runtime lifecycle, safe progress commentary, text output, upstream thinking, step progress, and tool calls onto `RUN_*`, `STATUS_UPDATE`, `TEXT_MESSAGE_*`, `THINKING_TEXT_MESSAGE_*`, `STEP_*`, and `TOOL_CALL_*` events for UI clients. `botbotgo ag-ui start|stop` now manages that HTTP bridge in the same workspace-local service registry as ACP, A2A, and runtime MCP.
 - `createRuntimeMcpServer(runtime)`, `serveRuntimeMcpOverStdio(runtime)`, and `serveRuntimeMcpOverStreamableHttp(runtime)` expose the persisted runtime control surface itself as MCP tools, including sessions, requests, approvals, artifacts, events, and package export helpers. `botbotgo mcp serve --transport streamable-http --host 127.0.0.1 --port 8090` serves the same tool surface over Streamable HTTP, and `botbotgo mcp start|stop` manages that background endpoint for one workspace.
 - `listRequestEvents(...)`, `listRequestTraceItems(...)`, and `exportRequestPackage(...)` are the request-first inspection helpers.
 - `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, artifacts, and governance evidence for operator tooling without reaching into persistence internals.

package/README.zh.md

@@ -1161,6 +1161,7 @@ ACP transport 说明：
 - ACP transport 现已覆盖核心参考客户端流程验证：capability discovery、request submit、session lookup、request lookup、invalid JSON 处理、无 id notification 不返回响应，以及 stdio JSON-RPC 与 HTTP + SSE runtime notifications。
 - 现在还额外有一条跨协议一致性回归门：ACP 发起的 request、A2A 读取或继续的 task，以及 runtime MCP 暴露的检查结果，必须始终指向同一组持久化 `sessionId` / `requestId` 运行时记录，不能漂移成各协议各自维护的标识体系。
 - 如果要从最薄的一层 editor / CLI starter 开始，优先用 `agent-harness acp serve --workspace . --transport stdio`，并直接参考 `examples/03_protocol-surfaces/app/acp-stdio/main.mjs` 的 wire shape。需要在应用内使用 reference client 时，可直接用 `createAcpStdioClient(...)` 发起 JSON-RPC 请求并分流 runtime notifications，避免每个 sidecar 自己重写 line parsing。
+- 如果想用最短的本地运维命令把整套协议面一起拉起，现在可以直接运行 `botbotgo start --workspace .`，它会把 ACP、A2A、runtime MCP 与 AG-UI 一起作为受管本地服务启动；`botbotgo stop --workspace .` 会按同一组服务统一停止。若只需要其中一部分，可用 `--services acp,mcp` 收窄启动集合。
 - 如果本地 ACP HTTP endpoint 需要在前台 shell 之外持续运行，可使用 `botbotgo acp start --workspace . --host 127.0.0.1 --port 8787`，之后再用 `botbotgo acp stop --workspace .` 停止。CLI 会把受管进程记录到 `.botbotgo/services/` 下，因此本地运维不必再额外引入第二套进程管理器。
 - 对发布后的安装包来说，`botbotgo` 是最短的本地终端入口。它会默认把当前目录当作 workspace，所以团队只需要 `cd` 到自己的 runtime workspace，然后直接运行 `botbotgo` 或 `botbotgo "..."`。`agent-harness` 也保留同样的隐式 chat 行为；如果要从同一个 shell 指向别的 workspace，继续用 `-w/--workspace` 即可。
 - `agent-harness chat --workspace .` 则继续保留为显式子命令形式的本地终端壳：默认 `stdio` 路径会直接在当前进程里连接 workspace runtime，而 `--transport http --host <host> --port <port>` 仍然可以直连已运行的 ACP HTTP endpoint。一次性调用可用 `--message`，交互模式则支持 `/context`、`/new`、`/agent <agentId>`、`/sessions`、`/requests`、`/resume <sessionId>`、`/approvals`、`/approve`、`/reject`、`/cancel`、`/events`、`/trace`、`/health`、`/overview`、`/session`、`/request [requestId]` 与 `/exit`。`/resume` 现在会先校验目标 session，恢复它的 latest request id，并同步 active agent context；`/request <requestId>` 可以把当前上下文切到某个已持久化 request；`/new` 则会在不退出 shell 的情况下清空当前 session/request context。终端 chat 现在统一走一条面向 operator 的输出路径：tool 和进度事件会实时打印，最终完整答复也会继续输出，而不再切到单独的 request-tree-only 模式。
@@ -1171,7 +1172,7 @@ ACP transport 说明：
 - 交互式 prompt 现在会同时显示当前 `agent`、`session` 和短 `request` 标识，因此每轮回复之后以及使用 shell 历史记录时，用户都还能清楚地看到自己正处在哪个 runtime turn 上，而不会掉回一个没有上下文的裸输入提示。
 - `serveA2aHttp(runtime)` 提供 A2A HTTP JSON-RPC bridge 与 agent card discovery，同时兼容 `message/send` 这类旧方法，以及 `SendMessage`、`SendStreamingMessage`、`GetTask`、`ListTasks`、`CancelTask`、`SubscribeToTask`、`GetAgentCard`、`GetExtendedAgentCard` 与 task push-notification config 这类 A2A v1.0 方法，并统一映射到现有 session/request 运行记录。bridge 现在会同时声明 `1.0` 与 `0.3` 两个 JSON-RPC interface、在 agent card 路径上响应 `HEAD` / `OPTIONS` discovery、写出支持版本的 discovery headers、可选暴露 registry URL 与 detached signed-card metadata 供外围发现系统使用、校验 `A2A-Version`、把 `A2A-Extensions` 记录进 runtime invocation metadata、发布 `TASK_STATE_*` 状态与 `SendMessage` 的 `{ task }` wrapper、在 v1 streaming 方法上先通过 SSE 输出 `{ task }` 初始快照，再输出 `{ statusUpdate }` 增量状态，并可向已配置的 webhook receiver 发送 best-effort task push notifications。
 - 如果要把本地 A2A bridge 作为受管后台服务运行，可使用 `botbotgo a2a start --workspace . --host 127.0.0.1 --port 8080`，之后再用 `botbotgo a2a stop --workspace .` 停止。它与 ACP 共用 `.botbotgo/services/` 状态目录，因此两个本地协议桥都可以沿用同一套终端优先运维流程。
-- `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、安全进度播报、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`STATUS_UPDATE`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。
+- `serveAgUiHttp(runtime)` 提供 AG-UI HTTP SSE bridge，把 runtime 生命周期、安全进度播报、文本输出、upstream thinking、step 进度与 tool call 投影成 `RUN_*`、`STATUS_UPDATE`、`TEXT_MESSAGE_*`、`THINKING_TEXT_MESSAGE_*`、`STEP_*` 与 `TOOL_CALL_*` 事件，便于 UI 客户端直接接入。`botbotgo ag-ui start|stop` 现在也会把这条 HTTP bridge 托管进与 ACP、A2A、runtime MCP 相同的 workspace 本地服务注册表中。
 - `createRuntimeMcpServer(runtime)`、`serveRuntimeMcpOverStdio(runtime)` 与 `serveRuntimeMcpOverStreamableHttp(runtime)` 会把持久化 runtime 控制面本身暴露成 MCP tools，包括 sessions、requests、approvals、artifacts、events 与 package export helpers。`botbotgo mcp serve --transport streamable-http --host 127.0.0.1 --port 8090` 会把同一套控制面作为 Streamable HTTP 暴露出去，而 `botbotgo mcp start|stop` 可直接托管该后台 endpoint。
 - `listRequestEvents(...)`、`listRequestTraceItems(...)` 与 `exportRequestPackage(...)` 是 request-first 的检查 helper。
 - `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events、artifacts 与 governance evidence 一起打包给管理工具，而不必直接访问 persistence 内部实现。

package/dist/cli/main.js

@@ -20,7 +20,7 @@ import { probeChatWorkspace, readChatWorkspaceModelInfo, } from "./chat-workspac
 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 { isTopLevelCliCommand, parseChatOptions, parseInitOptions, parseTopLevelManagedServiceOptions, renderUsage, } from "./options.js";
 import { resolveCliWorkspaceRoot, validateCliWorkspaceRoot, } from "./workspace.js";
 export { renderChatBanner, renderChatPromptLine } from "./chat-ui.js";
 export { probeChatWorkspace, renderChatRuntimeFailure } from "./chat-workspace.js";
@@ -258,6 +258,79 @@ export async function runCli(argv, io = {}, deps = {}) {
         }
         return executeChat(parsed);
     }
+    const runManagedServiceLifecycle = async (lifecycle, rawArgs) => {
+        const parsed = parseTopLevelManagedServiceOptions(rawArgs);
+        if (parsed.error) {
+            stderr(`${parsed.error}\n`);
+            stderr(renderUsage());
+            return 1;
+        }
+        const startOrder = ["acp", "a2a", "mcp", "ag-ui"];
+        const stopOrder = ["ag-ui", "mcp", "a2a", "acp"];
+        const serviceOrder = lifecycle === "start" ? startOrder : stopOrder;
+        const selectedServices = serviceOrder.filter((service) => parsed.services.includes(service));
+        for (const service of selectedServices) {
+            const commandArgs = [
+                lifecycle,
+                "--workspace",
+                parsed.workspaceRoot ?? ".",
+            ];
+            if (lifecycle === "start" && parsed.hostname) {
+                commandArgs.push("--host", parsed.hostname);
+            }
+            const resolvedPort = service === "acp"
+                ? parsed.acpPort
+                : service === "a2a"
+                    ? parsed.a2aPort
+                    : service === "mcp"
+                        ? parsed.mcpPort
+                        : parsed.agUiPort;
+            if (lifecycle === "start" && typeof resolvedPort === "number") {
+                commandArgs.push("--port", String(resolvedPort));
+            }
+            const exitCode = service === "acp"
+                ? await handleAcpCommand(commandArgs, { cwd, stderr }, {
+                    createHarness,
+                    serveAcp,
+                    serveAcpHttp,
+                    spawnManagedCliProcess,
+                    isManagedProcessRunning,
+                    signalManagedProcess,
+                    serveA2a,
+                    serveAgUi,
+                    serveRuntimeMcp,
+                    serveRuntimeMcpStreamableHttp,
+                })
+                : service === "a2a"
+                    ? await handleA2aCommand(commandArgs, { cwd, stderr }, {
+                        createHarness,
+                        serveA2a,
+                        spawnManagedCliProcess,
+                        isManagedProcessRunning,
+                        signalManagedProcess,
+                    })
+                    : service === "mcp"
+                        ? await handleMcpCommand(commandArgs, { cwd, stderr }, {
+                            createHarness,
+                            serveRuntimeMcp,
+                            serveRuntimeMcpStreamableHttp,
+                            spawnManagedCliProcess,
+                            isManagedProcessRunning,
+                            signalManagedProcess,
+                        })
+                        : await handleAgUiCommand(commandArgs, { cwd, stderr }, {
+                            createHarness,
+                            serveAgUi,
+                            spawnManagedCliProcess,
+                            isManagedProcessRunning,
+                            signalManagedProcess,
+                        });
+            if (exitCode !== 0) {
+                return exitCode;
+            }
+        }
+        return 0;
+    };
     if (!isTopLevelCliCommand(command)) {
         const parsed = parseChatOptions(argv);
         if (parsed.error) {
@@ -267,6 +340,9 @@ export async function runCli(argv, io = {}, deps = {}) {
         }
         return executeChat(parsed);
     }
+    if (command === "start" || command === "stop") {
+        return runManagedServiceLifecycle(command, [projectName, ...rest].filter((item) => typeof item === "string"));
+    }
     if (command === "acp") {
         return handleAcpCommand([projectName, ...rest], { cwd, stderr }, {
             createHarness,
@@ -282,7 +358,13 @@ export async function runCli(argv, io = {}, deps = {}) {
         });
     }
     if (command === "ag-ui") {
-        return handleAgUiCommand([projectName, ...rest], { cwd, stderr }, { createHarness, serveAgUi });
+        return handleAgUiCommand([projectName, ...rest], { cwd, stderr }, {
+            createHarness,
+            serveAgUi,
+            spawnManagedCliProcess,
+            isManagedProcessRunning,
+            signalManagedProcess,
+        });
     }
     if (command === "a2a") {
         return handleA2aCommand([projectName, ...rest], { cwd, stderr }, {

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

@@ -1,4 +1,4 @@
-export type ManagedCliService = "acp" | "a2a" | "mcp";
+export type ManagedCliService = "acp" | "a2a" | "mcp" | "ag-ui";
 export type ManagedCliServiceState = {
     pid: number;
     service: ManagedCliService;
@@ -16,6 +16,7 @@ export declare function writeManagedServiceState(state: ManagedCliServiceState):
 export declare function clearManagedServiceState(workspaceRoot: string, service: ManagedCliService): Promise<void>;
 export declare function defaultIsManagedProcessRunning(pid: number): boolean;
 export declare function defaultSignalManagedProcess(pid: number, signal?: NodeJS.Signals): void;
+export declare function resolveManagedCliNodeExecutable(cwd: string, env?: NodeJS.ProcessEnv, currentNodePath?: string, currentNodeVersion?: string): string;
 export declare function defaultSpawnManagedCliProcess(input: {
     args: string[];
     cwd: string;

package/dist/cli/managed-service.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
-import { existsSync, openSync } from "node:fs";
+import { existsSync, openSync, readFileSync, readdirSync } from "node:fs";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 function resolveManagedServiceRoot(workspaceRoot) {
@@ -44,11 +45,86 @@ export function defaultIsManagedProcessRunning(pid) {
 export function defaultSignalManagedProcess(pid, signal) {
     process.kill(pid, signal);
 }
+function parseRequestedNodeMajor(cwd) {
+    const nodeVersionPath = path.join(cwd, ".node-version");
+    if (existsSync(nodeVersionPath)) {
+        const value = readFileSync(nodeVersionPath, "utf8").trim();
+        const major = Number.parseInt(value.replace(/^v/i, ""), 10);
+        if (Number.isInteger(major) && major > 0) {
+            return major;
+        }
+    }
+    const packageJsonPath = path.join(cwd, "package.json");
+    if (!existsSync(packageJsonPath)) {
+        return undefined;
+    }
+    try {
+        const packageJson = JSON.parse(readFileSync(packageJsonPath, "utf8"));
+        const match = packageJson.engines?.node?.match(/>=\s*(\d+)/);
+        if (!match) {
+            return undefined;
+        }
+        const major = Number.parseInt(match[1] ?? "", 10);
+        return Number.isInteger(major) && major > 0 ? major : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseNodeMajorFromExecutable(nodePath) {
+    const match = nodePath.match(/\/v(\d+)\.\d+\.\d+\/bin\/node$/);
+    if (!match) {
+        return undefined;
+    }
+    const major = Number.parseInt(match[1] ?? "", 10);
+    return Number.isInteger(major) && major > 0 ? major : undefined;
+}
+function compareNodeVersionDirNames(left, right) {
+    const leftParts = left.replace(/^v/i, "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const rightParts = right.replace(/^v/i, "").split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const length = Math.max(leftParts.length, rightParts.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftValue = leftParts[index] ?? 0;
+        const rightValue = rightParts[index] ?? 0;
+        if (leftValue !== rightValue) {
+            return rightValue - leftValue;
+        }
+    }
+    return 0;
+}
+export function resolveManagedCliNodeExecutable(cwd, env = process.env, currentNodePath = process.execPath, currentNodeVersion = process.versions.node) {
+    const requestedMajor = parseRequestedNodeMajor(cwd);
+    if (!requestedMajor) {
+        return currentNodePath;
+    }
+    const currentMajor = Number.parseInt(currentNodeVersion.split(".")[0] ?? "", 10);
+    if (currentMajor === requestedMajor) {
+        return currentNodePath;
+    }
+    const home = env.HOME ?? env.USERPROFILE ?? homedir();
+    const versionsRoot = path.join(home, ".nvm", "versions", "node");
+    if (!existsSync(versionsRoot)) {
+        return currentNodePath;
+    }
+    const preferredVersion = readdirSync(versionsRoot, { withFileTypes: true })
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith(`v${requestedMajor}.`))
+        .map((entry) => entry.name)
+        .sort(compareNodeVersionDirNames)[0];
+    if (!preferredVersion) {
+        return currentNodePath;
+    }
+    const preferredNodePath = path.join(versionsRoot, preferredVersion, "bin", "node");
+    if (!existsSync(preferredNodePath)) {
+        return currentNodePath;
+    }
+    const preferredMajor = parseNodeMajorFromExecutable(preferredNodePath);
+    return preferredMajor === requestedMajor ? preferredNodePath : currentNodePath;
+}
 export async function defaultSpawnManagedCliProcess(input) {
     await mkdir(path.dirname(input.stdoutPath), { recursive: true });
     const stdoutFd = openSync(input.stdoutPath, "a");
     const stderrFd = openSync(input.stderrPath, "a");
-    const child = spawn(process.execPath, [fileURLToPath(import.meta.url), ...input.args], {
+    const child = spawn(resolveManagedCliNodeExecutable(input.cwd), [fileURLToPath(import.meta.url), ...input.args], {
         cwd: input.cwd,
         detached: true,
         stdio: ["ignore", stdoutFd, stderrFd],

package/dist/cli/options-serve.d.ts

@@ -1,3 +1,15 @@
+declare const TOP_LEVEL_MANAGED_SERVICES: readonly ["acp", "a2a", "mcp", "ag-ui"];
+export type TopLevelManagedService = (typeof TOP_LEVEL_MANAGED_SERVICES)[number];
+export declare function parseTopLevelManagedServiceOptions(args: string[]): {
+    workspaceRoot?: string;
+    services: TopLevelManagedService[];
+    hostname?: string;
+    acpPort?: number;
+    a2aPort?: number;
+    mcpPort?: number;
+    agUiPort?: number;
+    error?: string;
+};
 export declare function parseAcpServeOptions(args: string[], defaultTransport?: "stdio" | "http"): {
     workspaceRoot?: string;
     transport: "stdio" | "http";
@@ -22,3 +34,4 @@ export declare function parseRuntimeMcpServeOptions(args: string[], defaultTrans
     port?: number;
     error?: string;
 };
+export {};

package/dist/cli/options-serve.js

@@ -1,3 +1,119 @@
+const TOP_LEVEL_MANAGED_SERVICES = ["acp", "a2a", "mcp", "ag-ui"];
+export function parseTopLevelManagedServiceOptions(args) {
+    let workspaceRoot;
+    let hostname;
+    let services;
+    let acpPort;
+    let a2aPort;
+    let mcpPort;
+    let agUiPort;
+    const parsePort = (value, label) => {
+        if (!value) {
+            return { error: `Missing value for ${label}` };
+        }
+        const parsedPort = Number.parseInt(value, 10);
+        if (!Number.isFinite(parsedPort) || parsedPort < 0) {
+            return { error: `Invalid ${label} value: ${value}` };
+        }
+        return parsedPort;
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--workspace" || arg === "-w") {
+            const value = args[index + 1];
+            if (!value) {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], hostname, acpPort, a2aPort, mcpPort, agUiPort, error: "Missing value for --workspace" };
+            }
+            workspaceRoot = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--services") {
+            const value = args[index + 1];
+            if (!value) {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: "Missing value for --services" };
+            }
+            const parsedServices = value
+                .split(",")
+                .map((item) => item.trim())
+                .filter(Boolean);
+            if (parsedServices.length === 0) {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: "Missing value for --services" };
+            }
+            const invalidService = parsedServices.find((service) => !TOP_LEVEL_MANAGED_SERVICES.includes(service));
+            if (invalidService) {
+                return {
+                    services: services ?? [...TOP_LEVEL_MANAGED_SERVICES],
+                    workspaceRoot,
+                    hostname,
+                    acpPort,
+                    a2aPort,
+                    mcpPort,
+                    agUiPort,
+                    error: `Unsupported managed service: ${invalidService}`,
+                };
+            }
+            services = Array.from(new Set(parsedServices));
+            index += 1;
+            continue;
+        }
+        if (arg === "--host") {
+            const value = args[index + 1];
+            if (!value) {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, acpPort, a2aPort, mcpPort, agUiPort, error: "Missing value for --host" };
+            }
+            hostname = value;
+            index += 1;
+            continue;
+        }
+        if (arg === "--acp-port") {
+            const parsedPort = parsePort(args[index + 1], "--acp-port");
+            if (typeof parsedPort !== "number") {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: parsedPort.error };
+            }
+            acpPort = parsedPort;
+            index += 1;
+            continue;
+        }
+        if (arg === "--a2a-port") {
+            const parsedPort = parsePort(args[index + 1], "--a2a-port");
+            if (typeof parsedPort !== "number") {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: parsedPort.error };
+            }
+            a2aPort = parsedPort;
+            index += 1;
+            continue;
+        }
+        if (arg === "--mcp-port") {
+            const parsedPort = parsePort(args[index + 1], "--mcp-port");
+            if (typeof parsedPort !== "number") {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: parsedPort.error };
+            }
+            mcpPort = parsedPort;
+            index += 1;
+            continue;
+        }
+        if (arg === "--ag-ui-port") {
+            const parsedPort = parsePort(args[index + 1], "--ag-ui-port");
+            if (typeof parsedPort !== "number") {
+                return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: parsedPort.error };
+            }
+            agUiPort = parsedPort;
+            index += 1;
+            continue;
+        }
+        return { services: services ?? [...TOP_LEVEL_MANAGED_SERVICES], workspaceRoot, hostname, acpPort, a2aPort, mcpPort, agUiPort, error: `Unknown option: ${arg}` };
+    }
+    return {
+        workspaceRoot,
+        services: services ?? [...TOP_LEVEL_MANAGED_SERVICES],
+        hostname,
+        acpPort,
+        a2aPort,
+        mcpPort,
+        agUiPort,
+    };
+}
 export function parseAcpServeOptions(args, defaultTransport = "stdio") {
     let workspaceRoot;
     let transport = defaultTransport;

package/dist/cli/options.d.ts

@@ -1,5 +1,5 @@
 export declare function renderUsage(): string;
 export declare function isTopLevelCliCommand(value?: string): boolean;
 export { parseChatOptions, parseInitOptions } from "./options-init-chat.js";
-export { parseAcpServeOptions, parseHttpServeOptions, parseRuntimeMcpServeOptions, parseWorkspaceOnlyOptions, } from "./options-serve.js";
+export { parseAcpServeOptions, parseHttpServeOptions, parseTopLevelManagedServiceOptions, parseRuntimeMcpServeOptions, parseWorkspaceOnlyOptions, } from "./options-serve.js";
 export { parseRuntimeExportOptions, parseRuntimeInspectOptions, parseScheduledRunOptions, } from "./options-runtime.js";

package/dist/cli/options.js

@@ -4,6 +4,8 @@ export function renderUsage() {
   agent-harness chat [-w <path>] [--transport stdio|http] [--host <hostname>] [--port <port>] [--agent <agentId>] [--session <sessionId>] [--message <text>]
   agent-harness [-w <path>] [prompt]
   botbotgo [-w <path>] [prompt]
+  agent-harness start [-w <path>] [--services acp,a2a,mcp,ag-ui] [--host <hostname>] [--acp-port <port>] [--a2a-port <port>] [--mcp-port <port>] [--ag-ui-port <port>]
+  agent-harness stop [-w <path>] [--services acp,a2a,mcp,ag-ui]
   agent-harness acp serve [--workspace <path>] [--transport stdio|http] [--host <hostname>] [--port <port>]
   agent-harness acp start [--workspace <path>] [--host <hostname>] [--port <port>]
   agent-harness acp stop [--workspace <path>]
@@ -11,6 +13,8 @@ export function renderUsage() {
   agent-harness a2a start [--workspace <path>] [--host <hostname>] [--port <port>]
   agent-harness a2a stop [--workspace <path>]
   agent-harness ag-ui serve [--workspace <path>] [--host <hostname>] [--port <port>]
+  agent-harness ag-ui start [--workspace <path>] [--host <hostname>] [--port <port>]
+  agent-harness ag-ui stop [--workspace <path>]
   agent-harness runtime overview [--workspace <path>] [--limit <n>] [--json]
   agent-harness runtime health [--workspace <path>] [--json]
   agent-harness runtime approvals list [--workspace <path>] [--status <pending|approved|edited|rejected|expired>] [--json]
@@ -35,6 +39,8 @@ Chat defaults to the current directory as the workspace. Use -w to point at anot
 export function isTopLevelCliCommand(value) {
     return value === "init"
         || value === "chat"
+        || value === "start"
+        || value === "stop"
         || value === "acp"
         || value === "a2a"
         || value === "ag-ui"
@@ -43,5 +49,5 @@ export function isTopLevelCliCommand(value) {
         || value === "runtime-mcp";
 }
 export { parseChatOptions, parseInitOptions } from "./options-init-chat.js";
-export { parseAcpServeOptions, parseHttpServeOptions, parseRuntimeMcpServeOptions, parseWorkspaceOnlyOptions, } from "./options-serve.js";
+export { parseAcpServeOptions, parseHttpServeOptions, parseTopLevelManagedServiceOptions, parseRuntimeMcpServeOptions, parseWorkspaceOnlyOptions, } from "./options-serve.js";
 export { parseRuntimeExportOptions, parseRuntimeInspectOptions, parseScheduledRunOptions, } from "./options-runtime.js";

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

@@ -30,7 +30,7 @@ type ServerDeps = ManagedDeps & {
     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 handleAgUiCommand(subcommandAndArgs: string[], io: CommandIo, deps: Pick<ServerDeps, "createHarness" | "serveAgUi"> & ManagedDeps): 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

@@ -85,26 +85,46 @@ export async function handleAcpCommand(subcommandAndArgs, io, deps) {
 export async function handleAgUiCommand(subcommandAndArgs, io, deps) {
     const [subcommand, ...subcommandArgs] = subcommandAndArgs;
     const { cwd, stderr } = io;
-    const { createHarness, serveAgUi } = deps;
-    if (subcommand !== "serve") {
+    const { createHarness, serveAgUi, spawnManagedCliProcess, isManagedProcessRunning, signalManagedProcess } = deps;
+    if (subcommand !== "serve" && subcommand !== "start" && subcommand !== "stop") {
         stderr(renderUsage());
         return 1;
     }
-    const parsed = parseHttpServeOptions(subcommandArgs, "AG-UI");
-    if (parsed.error) {
-        stderr(`${parsed.error}\n`);
+    const parsedStop = subcommand === "stop" ? parseWorkspaceOnlyOptions(subcommandArgs) : undefined;
+    const parsedServe = subcommand !== "stop" ? parseHttpServeOptions(subcommandArgs, "AG-UI") : undefined;
+    const parseError = parsedStop?.error ?? parsedServe?.error;
+    if (parseError) {
+        stderr(`${parseError}\n`);
         stderr(renderUsage());
         return 1;
     }
     try {
-        const workspacePath = resolveValidatedWorkspace(cwd, parsed.workspaceRoot, stderr);
+        const workspaceRoot = parsedStop?.workspaceRoot ?? parsedServe?.workspaceRoot;
+        const workspacePath = resolveValidatedWorkspace(cwd, workspaceRoot, stderr);
         if (!workspacePath) {
             return 1;
         }
+        if (subcommand === "start") {
+            const args = ["ag-ui", "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: "ag-ui", workspacePath, args, stderr, spawnManagedCliProcess, isManagedProcessRunning });
+        }
+        if (subcommand === "stop") {
+            return stopManagedHttpService({ service: "ag-ui", workspacePath, stderr, isManagedProcessRunning, signalManagedProcess });
+        }
+        if (!parsedServe) {
+            stderr(renderUsage());
+            return 1;
+        }
         const runtime = await createHarness(workspacePath);
         const server = await serveAgUi(runtime, {
-            hostname: parsed.hostname,
-            port: parsed.port,
+            hostname: parsedServe.hostname,
+            port: parsedServe.port,
         });
         stderr(`Serving AG-UI over http from ${workspacePath} at ${server.runUrl}\n`);
         await server.completed;

package/dist/config/knowledge/knowledge-runtime.yaml

@@ -50,7 +50,8 @@ spec:
         Rules:
         - Store only durable reusable knowledge. Reject transient chatter, scratchpad, or duplication without added value.
         - Reject raw request/session summaries, source-specific page/news recaps, and generic "we learned how to use the tools/workflow" reflections unless they clearly contain reusable preferences, facts, decisions, or procedures.
-        - If transcript evidence shows the user explicitly asked the system to remember or follow a future instruction and the assistant confirmed that intent, store the durable instruction instead of rejecting it as a generic summary.
+        - Never store assistant- or system-authored workflow instructions inferred from a single transcript reflection, such as "how the system should investigate", "what the assistant should ask first", or other generic control-flow recipes for future turns.
+        - If transcript evidence shows the user explicitly asked the system to remember or follow a future instruction and the assistant confirmed that intent, store the durable user instruction instead of rejecting it as a generic summary.
         - Treat durable knowledge as generic mutable records with database-like operations over the same underlying knowledge item.
         - One candidate may yield zero, one, or multiple durable knowledge items. Split it only when the input clearly contains multiple independently mutable knowledge points.
         - When storing a knowledge item, always return a `knowledgeMutation` object with a stable `identity` and an `operation` of `create`, `update`, or `delete`.
@@ -59,7 +60,7 @@ spec:
         - If an existing relevant record already represents the same underlying knowledge item, reuse that record's `knowledge_identity` instead of inventing a new one.
         - Do not invent a second identity just because the new statement negates, revokes, deletes, or replaces the old wording. That is usually the same knowledge item with a different mutation operation.
         - The stored `content` must be canonical knowledge text, not an assistant acknowledgement such as "已记住" or "I will remember".
-        - You may optionally include `operationalRule` when the knowledge is naturally a rule, instruction, or recurring procedure. Treat it as structured metadata, not as the primary identity mechanism.
+        - You may optionally include `operationalRule` when the knowledge is a durable user-approved rule, instruction, or recurring procedure. Do not use it for assistant-only workflow guidance inferred from one conversation. Treat it as structured metadata, not as the primary identity mechanism.
         - Prefer semantic/episodic/procedural kinds only.
         - Prefer scopes session/agent/workspace/user/project only.
         - If the candidate should not be stored, return {"store": false, "reason": "..."}

package/dist/config/prompts/orchestra-system.md

@@ -31,6 +31,10 @@ mark completed steps as `completed`, keep the active step as `in_progress`, mark
 short `result` summaries when they help the user follow progress. Use descriptive todo content that names the
 real step; never use placeholders like `1`, `2`, `3`, `step 1`, or `todo 1`.
 
+For local troubleshooting and investigation requests, default the initial scope to the current workspace and the
+active shell/runtime context. Start by inspecting the available evidence yourself instead of asking the user to
+restate the problem, choose the first diagnostic branch, or manually provide the obvious starting context.
+
 For workspace file operations, always use workspace-relative paths such as `tmp-counter.txt` or `docs/index.html`.
 Do not use absolute host paths like `/tmp/...` or `/Users/...`. Use `write_file` only for the initial creation of
 a file. After a file exists, switch to `read_file` plus `edit_file` for updates instead of repeating `write_file`.

package/dist/config/runtime/runtime-memory.yaml

@@ -81,7 +81,8 @@ spec:
         Rules:
         - Store only durable reusable knowledge. Reject transient chatter, scratchpad, or duplication without added value.
         - Reject raw request/session summaries, source-specific page/news recaps, and generic "we learned how to use the tools/workflow" reflections unless they clearly contain reusable preferences, facts, decisions, or procedures.
-        - If transcript evidence shows the user explicitly asked the system to remember or follow a future instruction and the assistant confirmed that intent, store the durable instruction instead of rejecting it as a generic summary.
+        - Never store assistant- or system-authored workflow instructions inferred from a single transcript reflection, such as "how the system should investigate", "what the assistant should ask first", or other generic control-flow recipes for future turns.
+        - If transcript evidence shows the user explicitly asked the system to remember or follow a future instruction and the assistant confirmed that intent, store the durable user instruction instead of rejecting it as a generic summary.
         - Treat durable knowledge as generic mutable records with database-like operations over the same underlying knowledge item.
         - One candidate may yield zero, one, or multiple durable knowledge items. Split it only when the input clearly contains multiple independently mutable knowledge points.
         - When storing a knowledge item, always return a `knowledgeMutation` object with a stable `identity` and an `operation` of `create`, `update`, or `delete`.
@@ -90,7 +91,7 @@ spec:
         - If an existing relevant record already represents the same underlying knowledge item, reuse that record's `knowledge_identity` instead of inventing a new one.
         - Do not invent a second identity just because the new statement negates, revokes, deletes, or replaces the old wording. That is usually the same knowledge item with a different mutation operation.
         - The stored `content` must be canonical knowledge text, not an assistant acknowledgement such as "已记住" or "I will remember".
-        - You may optionally include `operationalRule` when the knowledge is naturally a rule, instruction, or recurring procedure. Treat it as structured metadata, not as the primary identity mechanism.
+        - You may optionally include `operationalRule` when the knowledge is a durable user-approved rule, instruction, or recurring procedure. Do not use it for assistant-only workflow guidance inferred from one conversation. Treat it as structured metadata, not as the primary identity mechanism.
         - Prefer semantic/episodic/procedural kinds only.
         - Prefer scopes session/agent/workspace/user/project only.
         - If the candidate should not be stored, return {"store": false, "reason": "..."}

package/dist/knowledge/module.js

@@ -2,7 +2,7 @@ import { createPersistentId } from "../utils/id.js";
 import { findMemoryRecordById, getMemoryRecord, listMemoryRecordsForScopes, persistStructuredMemoryRecords, removeMemoryRecord, updateMemoryRecord, } from "../runtime/harness/system/runtime-memory-records.js";
 import { consolidateStructuredMemoryScope } from "../runtime/harness/system/runtime-memory-consolidation.js";
 import { renderMemoryCandidatesMarkdown } from "../runtime/harness/system/runtime-memory-candidates.js";
-import { shouldRecallDurableMemory, normalizeLangMemMemoryKind, shouldStoreMemoryCandidate, } from "../runtime/harness/system/runtime-memory-policy.js";
+import { shouldRecallDurableMemory, normalizeLangMemMemoryKind, shouldStoreMemoryCandidate, isNonDurableTranscriptWorkflowMemory, } from "../runtime/harness/system/runtime-memory-policy.js";
 const ALL_SCOPES = ["session", "agent", "workspace", "user", "project"];
 const TITLE_BY_SCOPE = {
     session: "Session Structured Memory",
@@ -499,6 +499,7 @@ export class DefaultKnowledgeModule {
             includeStale: input.includeStale === true,
             context: normalizedContext,
         }))
+            .filter(({ record }) => !isNonDurableTranscriptWorkflowMemory(record))
             .map((item) => {
             const scopeBoost = item.record.scope === "session"
                 ? 4

package/dist/package-version.d.ts

@@ -1,2 +1,2 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.323";
-export declare const AGENT_HARNESS_RELEASE_DATE = "2026-04-21";
+export declare const AGENT_HARNESS_VERSION = "0.0.324";
+export declare const AGENT_HARNESS_RELEASE_DATE = "2026-04-22";

package/dist/package-version.js

@@ -1,2 +1,2 @@
-export const AGENT_HARNESS_VERSION = "0.0.323";
-export const AGENT_HARNESS_RELEASE_DATE = "2026-04-21";
+export const AGENT_HARNESS_VERSION = "0.0.324";
+export const AGENT_HARNESS_RELEASE_DATE = "2026-04-22";