@botbotgo/agent-harness 0.0.309 → 0.0.310

package/README.md

@@ -128,6 +128,20 @@ This file is both a quickstart and a long reference—you do not need to read it
 | **Operations / governance** | [Runtime capabilities at a glance](#readme-en-runtime-glance) → [Primary use cases](#readme-en-use-cases) | [Runtime operations](./docs/development/runtime-operations.html) and [`docs/tool-execution-policy.md`](./docs/tool-execution-policy.md). |
 | **API lookup** | Skip to [API Summary](#readme-en-api-summary) | Use it as a bookmarked index; the [API reference](./docs/development/api-reference.html) has fuller detail. |
 
+## Repository Source Layout
+
+When you work on the open-source package itself, treat `src/` as a layered tree instead of one flat folder:
+
+- top-level `src/*.ts` files should stay as stable public entrypoints or compatibility shims
+- public API implementation belongs under `src/public/`
+- protocol servers and transports belong under `src/protocol/**`
+- terminal, projection, and rendering helpers belong under `src/surface/` or `src/cli/`
+- scaffolding and bootstrap generation belong under `src/scaffold/`
+- extension and tool-definition machinery belong under `src/tooling/`
+- runtime internals stay under `src/runtime/`, persistence under `src/persistence/`, and workspace assembly under `src/workspace/`
+
+For new code, prefer the domain folder first. Only add a new top-level `src/*.ts` file when it is intentionally part of the package entry surface.
+
 ## License & Commercial Support
 
 This project is licensed under **Apache License 2.0**.

package/README.zh.md

@@ -126,6 +126,20 @@ durable memory 的写入现在也会在模型做 mutation reconciliation 之前
 | **运维 / 治理** | [运行时能力速览](#readme-zh-runtime-glance) → [典型应用场景](#readme-zh-use-cases) | [运行时运维](./docs/development/zh/runtime-operations.html) 与 [`docs/tool-execution-policy.md`](./docs/tool-execution-policy.md)。 |
 | **查 API** | 跳转到文末 [API 摘要](#readme-zh-api-summary) | 日常以[API 参考](./docs/development/zh/api-reference.html)为准。 |
 
+## 仓库源码分层
+
+如果你维护的是这个开源包本身，请把 `src/` 当成分层目录，而不是平铺文件夹：
+
+- `src/*.ts` 顶层文件尽量只保留稳定公共入口或兼容 shim
+- 公共 API 实现放进 `src/public/`
+- 协议服务与传输实现放进 `src/protocol/**`
+- 终端、事件投影与渲染辅助放进 `src/surface/` 或 `src/cli/`
+- 脚手架与项目初始化逻辑放进 `src/scaffold/`
+- 扩展注册、工具定义与模块装载放进 `src/tooling/`
+- runtime 内部继续放在 `src/runtime/`，持久化放在 `src/persistence/`，workspace 装配放在 `src/workspace/`
+
+新增实现代码时，优先进入对应 domain 子目录。只有当一个文件本来就属于包的公开入口面时，才新增顶层 `src/*.ts`。
+
 ## 许可证与商业支持
 
 本项目采用 **Apache License 2.0** 开源许可。[查看 LICENSE](./LICENSE)

package/dist/acp.d.ts

@@ -1,116 +1 @@
-import type { ArtifactRecord, HarnessEvent, HarnessStreamItem, RequestRecord, RequestOptions, SessionRecord } from "./contracts/types.js";
-import type { AgentHarnessRuntime } from "./runtime/harness.js";
-import { getApproval, type PublicRequestListeners } from "./api.js";
-type JsonRpcId = string | number | null;
-export type AcpJsonRpcRequest = {
-    jsonrpc?: "2.0";
-    id?: JsonRpcId;
-    method: string;
-    params?: unknown;
-};
-export type AcpJsonRpcError = {
-    jsonrpc: "2.0";
-    id: JsonRpcId;
-    error: {
-        code: number;
-        message: string;
-        data?: unknown;
-    };
-};
-export type AcpJsonRpcSuccess = {
-    jsonrpc: "2.0";
-    id: JsonRpcId;
-    result: unknown;
-};
-export type AcpJsonRpcResponse = AcpJsonRpcError | AcpJsonRpcSuccess;
-export type AcpSessionRecord = SessionRecord;
-export type AcpRequestRecord = RequestRecord;
-export type AcpApproval = Awaited<ReturnType<typeof getApproval>> extends infer T ? Exclude<T, null> : never;
-export type AcpArtifact = ArtifactRecord & {
-    content?: unknown;
-};
-export type AcpRequestParams = Omit<Extract<RequestOptions, {
-    input: unknown;
-}>, "listeners"> & {
-    sessionId?: string;
-    streamId?: string;
-    listeners?: PublicRequestListeners;
-};
-export type AcpServerCapabilities = {
-    sessions: {
-        list: true;
-        get: true;
-        summaries: true;
-    };
-    requests: {
-        submit: true;
-        list: true;
-        get: true;
-        plan: {
-            get: true;
-        };
-        cancel: true;
-        stream: true;
-        trace: {
-            list: true;
-        };
-    };
-    approvals: {
-        list: true;
-        get: true;
-        resolve: true;
-    };
-    artifacts: {
-        list: true;
-        read: true;
-    };
-    events: {
-        subscribe: true;
-        list: true;
-    };
-    runtime: {
-        health: true;
-        overview: true;
-    };
-};
-export type AcpEventNotification = {
-    jsonrpc: "2.0";
-    method: "events.runtime";
-    params: {
-        event: {
-            eventId: string;
-            eventType: string;
-            timestamp: string;
-            sessionId: string;
-            requestId: string;
-            sequence: number;
-            source: HarnessEvent["source"];
-            payload: Record<string, unknown>;
-        };
-    };
-};
-export type AcpStreamNotification = {
-    jsonrpc: "2.0";
-    method: "requests.stream";
-    params: {
-        streamId: string;
-        item: HarnessStreamItem;
-    };
-};
-export type AcpNotification = AcpEventNotification | AcpStreamNotification;
-export declare class AgentHarnessAcpServer {
-    private readonly runtime;
-    private readonly listeners;
-    constructor(runtime: AgentHarnessRuntime);
-    capabilities(): AcpServerCapabilities;
-    subscribe(listener: (notification: AcpNotification) => void): () => void;
-    handle(request: AcpJsonRpcRequest): Promise<AcpJsonRpcResponse | undefined>;
-    private methodExists;
-    private emitNotification;
-    private dispatch;
-    private submitStreamingRequest;
-}
-export declare function createAcpServer(runtime: AgentHarnessRuntime): AgentHarnessAcpServer;
-export { createAcpStdioClient } from "./protocol/acp/client.js";
-export { createAcpHttpClient } from "./protocol/acp/client.js";
-export type { AcpHttpClient, AcpHttpClientOptions, AcpStdioClient, AcpStdioClientOptions } from "./protocol/acp/client.js";
+export * from "./protocol/acp/server.js";

package/dist/acp.js

@@ -1,310 +1 @@
-import { cancelRequest, getApproval, getArtifact, getHealth, getOperatorOverview, getRequestPlanState, getRequest, getSession, listApprovals, listRequestEvents, listRequestArtifacts, listRequestTraceItems, listRequests, listSessionSummaries, listSessions, request, resolveApproval, } from "./api.js";
-const CAPABILITIES = {
-    sessions: { list: true, get: true, summaries: true },
-    requests: { submit: true, list: true, get: true, plan: { get: true }, cancel: true, stream: true, trace: { list: true } },
-    approvals: { list: true, get: true, resolve: true },
-    artifacts: { list: true, read: true },
-    events: { subscribe: true, list: true },
-    runtime: { health: true, overview: true },
-};
-function asObject(value, method) {
-    if (!value || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error(`${method} requires an object params payload.`);
-    }
-    return value;
-}
-function readOptionalString(value) {
-    return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
-}
-function readRequiredString(value, field, method) {
-    const normalized = readOptionalString(value);
-    if (!normalized) {
-        throw new Error(`${method} requires ${field}.`);
-    }
-    return normalized;
-}
-function toNotification(event) {
-    return {
-        jsonrpc: "2.0",
-        method: "events.runtime",
-        params: {
-            event: {
-                eventId: event.eventId,
-                eventType: event.eventType,
-                timestamp: event.timestamp,
-                sessionId: event.sessionId,
-                requestId: event.requestId,
-                sequence: event.sequence,
-                source: event.source,
-                payload: event.payload,
-            },
-        },
-    };
-}
-function toStreamNotification(streamId, item) {
-    return {
-        jsonrpc: "2.0",
-        method: "requests.stream",
-        params: {
-            streamId,
-            item,
-        },
-    };
-}
-async function readArtifactContent(runtime, params) {
-    const method = "artifacts.read";
-    const sessionId = readRequiredString(params.sessionId, "sessionId", method);
-    const requestId = readRequiredString(params.requestId, "requestId", method);
-    const artifactPath = readRequiredString(params.artifactPath, "artifactPath", method);
-    const listing = await listRequestArtifacts(runtime, { sessionId, requestId });
-    const artifact = listing.items.find((item) => item.path === artifactPath);
-    if (!artifact) {
-        throw new Error(`Artifact not found for ${requestId}: ${artifactPath}`);
-    }
-    return {
-        ...artifact,
-        content: await getArtifact(runtime, { sessionId, requestId, artifactPath }),
-    };
-}
-export class AgentHarnessAcpServer {
-    runtime;
-    listeners = new Set();
-    constructor(runtime) {
-        this.runtime = runtime;
-        this.runtime.subscribe((event) => {
-            this.emitNotification(toNotification(event));
-        });
-    }
-    capabilities() {
-        return CAPABILITIES;
-    }
-    subscribe(listener) {
-        this.listeners.add(listener);
-        return () => {
-            this.listeners.delete(listener);
-        };
-    }
-    async handle(request) {
-        const id = request.id ?? null;
-        if (!request || typeof request !== "object" || typeof request.method !== "string" || request.method.trim().length === 0) {
-            return {
-                jsonrpc: "2.0",
-                id,
-                error: {
-                    code: -32600,
-                    message: "Invalid JSON-RPC request.",
-                },
-            };
-        }
-        if (request.jsonrpc !== undefined && request.jsonrpc !== "2.0") {
-            return {
-                jsonrpc: "2.0",
-                id,
-                error: {
-                    code: -32600,
-                    message: "Only JSON-RPC 2.0 requests are supported.",
-                },
-            };
-        }
-        try {
-            const result = await this.dispatch(request.method, request.params);
-            if (request.id === undefined) {
-                return undefined;
-            }
-            return {
-                jsonrpc: "2.0",
-                id,
-                result,
-            };
-        }
-        catch (error) {
-            if (request.id === undefined) {
-                return undefined;
-            }
-            return {
-                jsonrpc: "2.0",
-                id,
-                error: {
-                    code: this.methodExists(request.method) ? -32602 : -32601,
-                    message: error instanceof Error ? error.message : "ACP request failed.",
-                },
-            };
-        }
-    }
-    methodExists(method) {
-        return new Set([
-            "capabilities.get",
-            "sessions.list",
-            "sessions.get",
-            "sessions.summaries",
-            "requests.submit",
-            "requests.list",
-            "requests.get",
-            "requests.plan.get",
-            "requests.cancel",
-            "requests.stream",
-            "requests.trace.list",
-            "approvals.list",
-            "approvals.get",
-            "approvals.resolve",
-            "artifacts.list",
-            "artifacts.read",
-            "events.list",
-            "runtime.health",
-            "runtime.overview",
-        ]).has(method);
-    }
-    emitNotification(notification) {
-        for (const listener of Array.from(this.listeners)) {
-            try {
-                listener(notification);
-            }
-            catch {
-                // Ignore subscriber failures so one ACP consumer cannot tear down the server.
-            }
-        }
-    }
-    async dispatch(method, params) {
-        switch (method) {
-            case "capabilities.get":
-                return this.capabilities();
-            case "sessions.list": {
-                const payload = params === undefined ? {} : asObject(params, method);
-                return listSessions(this.runtime, {
-                    agentId: readOptionalString(payload.agentId),
-                });
-            }
-            case "sessions.get": {
-                const payload = asObject(params, method);
-                return getSession(this.runtime, readRequiredString(payload.sessionId, "sessionId", method));
-            }
-            case "sessions.summaries": {
-                const payload = params === undefined ? {} : asObject(params, method);
-                return listSessionSummaries(this.runtime, {
-                    agentId: readOptionalString(payload.agentId),
-                });
-            }
-            case "requests.submit": {
-                const payload = asObject(params, method);
-                if (readOptionalString(payload.streamId)) {
-                    return this.submitStreamingRequest(payload, method);
-                }
-                return request(this.runtime, {
-                    agentId: readOptionalString(payload.agentId),
-                    input: payload.input,
-                    invocation: payload.invocation,
-                    listeners: payload.listeners,
-                    priority: typeof payload.priority === "number" ? payload.priority : undefined,
-                    sessionId: readOptionalString(payload.sessionId),
-                });
-            }
-            case "requests.cancel": {
-                const payload = asObject(params, method);
-                return cancelRequest(this.runtime, {
-                    requestId: readRequiredString(payload.requestId, "requestId", method),
-                    reason: readOptionalString(payload.reason),
-                });
-            }
-            case "requests.list": {
-                const payload = params === undefined ? {} : asObject(params, method);
-                return listRequests(this.runtime, {
-                    agentId: readOptionalString(payload.agentId),
-                    sessionId: readOptionalString(payload.sessionId),
-                    state: payload.state,
-                });
-            }
-            case "requests.get": {
-                const payload = asObject(params, method);
-                return getRequest(this.runtime, readRequiredString(payload.requestId, "requestId", method));
-            }
-            case "requests.plan.get": {
-                const payload = asObject(params, method);
-                return getRequestPlanState(this.runtime, {
-                    sessionId: readRequiredString(payload.sessionId, "sessionId", method),
-                    requestId: readRequiredString(payload.requestId, "requestId", method),
-                });
-            }
-            case "requests.trace.list": {
-                const payload = asObject(params, method);
-                return listRequestTraceItems(this.runtime, {
-                    sessionId: readRequiredString(payload.sessionId, "sessionId", method),
-                    requestId: readRequiredString(payload.requestId, "requestId", method),
-                });
-            }
-            case "approvals.list": {
-                const payload = params === undefined ? {} : asObject(params, method);
-                return listApprovals(this.runtime, {
-                    status: payload.status,
-                    sessionId: readOptionalString(payload.sessionId),
-                    requestId: readOptionalString(payload.requestId),
-                });
-            }
-            case "approvals.get": {
-                const payload = asObject(params, method);
-                return getApproval(this.runtime, readRequiredString(payload.approvalId, "approvalId", method));
-            }
-            case "approvals.resolve": {
-                const payload = asObject(params, method);
-                return resolveApproval(this.runtime, {
-                    approvalId: readRequiredString(payload.approvalId, "approvalId", method),
-                    decision: payload.decision,
-                    editedInput: payload.editedInput,
-                    requestId: readOptionalString(payload.requestId),
-                    sessionId: readOptionalString(payload.sessionId),
-                });
-            }
-            case "artifacts.list": {
-                const payload = asObject(params, method);
-                return listRequestArtifacts(this.runtime, {
-                    sessionId: readRequiredString(payload.sessionId, "sessionId", method),
-                    requestId: readRequiredString(payload.requestId, "requestId", method),
-                });
-            }
-            case "artifacts.read":
-                return readArtifactContent(this.runtime, asObject(params, method));
-            case "events.list": {
-                const payload = asObject(params, method);
-                return listRequestEvents(this.runtime, {
-                    sessionId: readRequiredString(payload.sessionId, "sessionId", method),
-                    requestId: readRequiredString(payload.requestId, "requestId", method),
-                });
-            }
-            case "runtime.health":
-                return getHealth(this.runtime);
-            case "runtime.overview": {
-                const payload = params === undefined ? {} : asObject(params, method);
-                return getOperatorOverview(this.runtime, {
-                    limit: typeof payload.limit === "number" ? payload.limit : undefined,
-                });
-            }
-            default:
-                throw new Error(`Unknown ACP method: ${method}`);
-        }
-    }
-    async submitStreamingRequest(payload, method) {
-        const streamId = readRequiredString(payload.streamId, "streamId", method);
-        let finalResult;
-        for await (const item of this.runtime.streamEvents({
-            agentId: readOptionalString(payload.agentId),
-            input: payload.input,
-            invocation: payload.invocation,
-            listeners: payload.listeners,
-            priority: typeof payload.priority === "number" ? payload.priority : undefined,
-            sessionId: readOptionalString(payload.sessionId),
-        })) {
-            this.emitNotification(toStreamNotification(streamId, item));
-            if (item.type === "result") {
-                finalResult = item.result;
-            }
-        }
-        if (finalResult) {
-            return finalResult;
-        }
-        throw new Error("ACP streaming request completed without a terminal result.");
-    }
-}
-export function createAcpServer(runtime) {
-    return new AgentHarnessAcpServer(runtime);
-}
-export { createAcpStdioClient } from "./protocol/acp/client.js";
-export { createAcpHttpClient } from "./protocol/acp/client.js";
+export * from "./protocol/acp/server.js";

package/dist/api.d.ts

@@ -8,7 +8,7 @@ export { createAcpStdioClient } from "./protocol/acp/client.js";
 export type { RuntimeMcpStreamableHttpServer, RuntimeMcpStreamableHttpServerOptions } from "./mcp.js";
 export type { AcpApproval, AcpArtifact, AcpEventNotification, AcpNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRequestParams, AcpServerCapabilities, AcpSessionRecord, AcpStreamNotification, } from "./acp.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
-export { createUpstreamTimelineReducer } from "./upstream-events.js";
+export { createUpstreamTimelineReducer } from "./projections/upstream-events.js";
 export type { ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RequestPlanState, SessionListSummary, RuntimeSessionPackageInput, RuntimeSessionPackage, UpdateMemoryInput, } from "./contracts/types.js";
 export type { AcpHttpServer, AcpHttpServerOptions } from "./protocol/acp/http.js";
 export type { AcpStdioClient, AcpStdioClientOptions } from "./protocol/acp/client.js";

package/dist/api.js

@@ -10,7 +10,7 @@ import { traceStartupStage } from "./runtime/startup-tracing.js";
 export { AgentHarnessAcpServer, createAcpServer } from "./acp.js";
 export { createAcpStdioClient } from "./protocol/acp/client.js";
 export { AgentHarnessRuntime } from "./runtime/harness.js";
-export { createUpstreamTimelineReducer } from "./upstream-events.js";
+export { createUpstreamTimelineReducer } from "./projections/upstream-events.js";
 function toApprovalRecord(record) {
     return {
         approvalId: record.approvalId,

package/dist/cli/chat-interactive.d.ts

@@ -0,0 +1,24 @@
+import type { Interface as ReadlineInterface } from "node:readline";
+import type { Writable as WritableStream } from "node:stream";
+import type { HarnessClient } from "../client.js";
+import { type ChatWorkspaceModelInfo } from "./chat-workspace.js";
+export declare function runInteractiveChatLoop(input: {
+    client: HarnessClient;
+    lineReader: ReadlineInterface;
+    stdout: (message: string) => void;
+    stderr: (message: string) => void;
+    stdoutStream?: WritableStream;
+    stderrStream?: WritableStream;
+    workspacePath: string;
+    workspaceModelInfo?: ChatWorkspaceModelInfo;
+    requestEvents: boolean;
+    chatIsTty: boolean;
+    useColor: boolean;
+    agentFilter?: string;
+    activeAgentId?: string;
+    activeSessionId?: string;
+}): Promise<{
+    activeAgentId?: string;
+    activeSessionId?: string;
+    latestRequestId?: string;
+}>;