@botbotgo/agent-harness 0.0.352 → 0.0.353

package/README.md

@@ -1218,9 +1218,10 @@ ACP transport notes:
 - `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.
+- `analyzeBoundaries(runtime)` returns a workspace boundary report covering agent, subagent, tool, and skill surfaces, including structural findings such as missing subagent references, unreferenced tools or skills, and skill allow-lists that do not match the owning agent's exposed tools.
 - `exportRequestPackage(...)` and `exportSessionPackage(...)` package stable runtime records, transcript, approvals, events, artifacts, and governance evidence for operator tooling without reaching into persistence internals.
 - `runtime/default.governance.remoteMcp` can now deny or allow specific MCP servers, raise approval requirements by transport, and stamp transport-based risk tiers into runtime governance bundles. MCP server catalogs can also declare trust tier, access mode, tenant scope, approval policy, prompt-injection risk, and OAuth scope metadata so governance bundles capture why one remote tool is treated as high-risk. Tool policy overrides can also set `decisionMode: manual | auto-approve | auto-reject | deny-and-continue` so operator evidence and execution behavior stay aligned.
 - Protocol responsibilities stay split on purpose: ACP is the primary editor/client runtime boundary, A2A is the streaming-capable agent-platform bridge with polling compatibility, AG-UI is the UI event surface, and runtime MCP is the operator-facing control plane exported as MCP tools.
 - `runtime/default.observability.tracing` can now describe exporter metadata such as OTLP endpoints and propagation mode, so frozen runtime snapshots keep trace-correlation plus operator-visible export context without exposing backend-private span internals.
-- `agent-harness runtime overview`, `agent-harness runtime health`, `agent-harness runtime approvals list|watch`, `agent-harness runtime requests list|tail`, and `agent-harness runtime export request|session` provide a thin operator CLI over persisted runtime health, queue pressure, governance risk, approval queues, active request state, and audit-ready evidence packages.
+- `agent-harness runtime overview`, `agent-harness runtime boundaries`, `agent-harness runtime health`, `agent-harness runtime approvals list|watch`, `agent-harness runtime requests list|tail`, and `agent-harness runtime export request|session` provide a thin operator CLI over workspace boundary analysis, persisted runtime health, queue pressure, governance risk, approval queues, active request state, and audit-ready evidence packages.
 - detailed A2A adapter guidance lives in [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/README.zh.md

@@ -1175,9 +1175,10 @@ ACP transport 说明：
 - `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。
+- `analyzeBoundaries(runtime)` 会返回 workspace boundary report，覆盖 agent、subagent、tool 与 skill 的可见边界，并指出缺失 subagent 引用、未被引用的 tools/skills、以及 skill allow-list 与所属 agent 暴露工具不匹配等结构性问题。
 - `exportRequestPackage(...)` 与 `exportSessionPackage(...)` 可把稳定 runtime 记录、transcript、approvals、events、artifacts 与 governance evidence 一起打包给管理工具，而不必直接访问 persistence 内部实现。
 - `runtime/default.governance.remoteMcp` 现在可以按 MCP server 或 transport 做 allow/deny、审批升级，并把 transport 风险等级写进 runtime governance bundles。MCP server catalog 也可以声明 trust tier、access mode、tenant scope、approval policy、prompt-injection risk 与 OAuth scope 元数据，让治理快照能解释为什么某个远端工具被视为高风险。tool policy override 也可以声明 `decisionMode: manual | auto-approve | auto-reject | deny-and-continue`，让治理快照与实际执行路径保持一致。
 - 协议分工要继续保持清晰：ACP 是 editor / client 的主运行时边界，A2A 是支持 streaming 且兼容轮询的 agent-platform bridge，AG-UI 是 UI 事件面，runtime MCP 是以 MCP tools 暴露的 operator control plane。
 - `runtime/default.observability.tracing` 现在可描述 OTLP endpoint 和 propagation mode 这类 exporter 元数据，使冻结的 runtime snapshot 在保留 trace correlation 的同时，也能保留有用的导出上下文，而不暴露 backend 私有 span 细节。
-- `agent-harness runtime overview`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch`、`agent-harness runtime requests list|tail` 与 `agent-harness runtime export request|session` 提供了一层轻量 CLI，可直接查看 runtime health、queue pressure、governance risk、审批队列、运行状态与可审计证据包。
+- `agent-harness runtime overview`、`agent-harness runtime boundaries`、`agent-harness runtime health`、`agent-harness runtime approvals list|watch`、`agent-harness runtime requests list|tail` 与 `agent-harness runtime export request|session` 提供了一层轻量 CLI，可直接查看 workspace boundary analysis、runtime health、queue pressure、governance risk、审批队列、运行状态与可审计证据包。
 - 更详细的 A2A 适配层开发说明见 [`docs/a2a-bridge.md`](docs/a2a-bridge.md)

package/dist/api.d.ts

@@ -1,6 +1,8 @@
 import type { ArtifactListing, CancelOptions, InvocationEnvelope, ListMemoriesInput, ListMemoriesResult, MemoryRecord, MemorizeInput, MemorizeResult, MessageContent, RequestDataEvent, RecallInput, RecallResult, RemoveMemoryInput, RequestEventSnapshot, RequestPlanState, RequestDecisionOptions, RequestRecord, RequestResult as InternalRequestResult, RequestStartOptions, RequestSummary, RuntimeArtifactWriteInput, ResumeOptions, RequestListeners, RuntimeHealthSnapshot, RuntimeGovernanceEvidence, RuntimeGovernanceDiagnostics, RuntimeOperatorOverview, RuntimeQueueDiagnostics, RuntimeAdapterOptions, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationArtifact, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult as InternalRuntimeEvaluationReplayResult, RuntimeSessionPackage, RuntimeSessionPackageInput, SessionListSummary, SessionRecord, SessionSummary, TranscriptMessage, UpdateMemoryInput, WorkspaceLoadOptions } from "./contracts/types.js";
 import { AgentHarnessRuntime } from "./runtime/harness.js";
 import type { InventoryAgentRecord, InventorySkillRecord } from "./runtime/harness/system/inventory.js";
+import type { BoundaryAnalysisOptions, WorkspaceBoundaryAnalysis } from "./runtime/harness/system/boundary-analysis.js";
+export type { BoundaryAgentSurface, BoundaryAnalysisOptions, BoundaryAnalysisSummary, BoundaryFinding, BoundaryFindingSeverity, WorkspaceBoundaryAnalysis, } from "./runtime/harness/system/boundary-analysis.js";
 import type { RequirementAssessmentOptions } from "./runtime/harness/system/skill-requirements.js";
 import type { RuntimeMcpServerOptions, RuntimeMcpStreamableHttpServerOptions, ToolMcpServerOptions } from "./mcp.js";
 export { AgentHarnessAcpServer, createAcpServer } from "./acp.js";
@@ -202,6 +204,7 @@ export declare function describeInventory(runtime: AgentHarnessRuntime, options?
     workspaceRoot: string;
     agents: InventoryAgentRecord[];
 };
+export declare function analyzeBoundaries(runtime: AgentHarnessRuntime, options?: BoundaryAnalysisOptions): WorkspaceBoundaryAnalysis;
 export declare function resolveApproval(runtime: AgentHarnessRuntime, options: ResumeOptions): Promise<PublicRequestResult>;
 export declare function cancelRequest(runtime: AgentHarnessRuntime, options: CancelOptions): Promise<PublicRequestResult>;
 export declare function stop(runtime: AgentHarnessRuntime): Promise<void>;

package/dist/api.js

@@ -366,6 +366,9 @@ export function getAgent(runtime, agentId, options) {
 export function describeInventory(runtime, options) {
     return runtime.describeWorkspaceInventory(options);
 }
+export function analyzeBoundaries(runtime, options) {
+    return runtime.analyzeWorkspaceBoundaries(options);
+}
 export async function resolveApproval(runtime, options) {
     return toPublicRequestResult(await runtime.resume(toInternalResumeOptions(options)));
 }

package/dist/cli/options.js

@@ -16,6 +16,7 @@ export function renderUsage() {
   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 boundaries [--workspace <path>] [--json]
   agent-harness runtime health [--workspace <path>] [--json]
   agent-harness runtime approvals list [--workspace <path>] [--status <pending|approved|edited|rejected|expired>] [--json]
   agent-harness runtime approvals watch [--workspace <path>] [--status <pending|approved|edited|rejected|expired>] [--poll-ms <ms>] [--once] [--json]

package/dist/cli/runtime-commands.js

@@ -1,4 +1,4 @@
-import { renderApprovalList, renderHealthSnapshot, renderJson, renderOperatorOverview, renderRequestList } from "./runtime-output.js";
+import { renderApprovalList, renderBoundaryAnalysis, 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) {
@@ -128,6 +128,17 @@ export async function handleRuntimeCommand(subcommandAndArgs, io, deps) {
         if (!workspacePath) {
             return 1;
         }
+        if (subcommand === "boundaries") {
+            const runtime = await createHarness(workspacePath);
+            try {
+                const analysis = runtime.analyzeWorkspaceBoundaries();
+                stdout(parsed.json ? renderJson(analysis) : renderBoundaryAnalysis(analysis, workspacePath));
+                return analysis.summary.errorCount > 0 ? 2 : 0;
+            }
+            finally {
+                await runtime.stop();
+            }
+        }
         const shouldUseClient = subcommand === "health"
             || subcommand === "overview"
             || (subcommand === "approvals" && (nestedCommand === "list" || nestedCommand === "watch"))

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

@@ -3,3 +3,4 @@ export declare function renderHealthSnapshot(snapshot: Record<string, unknown>,
 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;
+export declare function renderBoundaryAnalysis(analysis: Record<string, unknown>, workspacePath: string): string;

package/dist/cli/runtime-output.js

@@ -122,3 +122,34 @@ export function renderOperatorOverview(overview, workspacePath) {
     }
     return `${lines.join("\n")}\n`;
 }
+export function renderBoundaryAnalysis(analysis, workspacePath) {
+    const lines = [];
+    const summary = isObject(analysis.summary) ? analysis.summary : {};
+    const findings = Array.isArray(analysis.findings) ? analysis.findings.filter(isObject) : [];
+    const errors = typeof summary.errorCount === "number" ? summary.errorCount : 0;
+    const warnings = typeof summary.warningCount === "number" ? summary.warningCount : 0;
+    const info = typeof summary.infoCount === "number" ? summary.infoCount : 0;
+    lines.push(`Runtime boundary analysis ${workspacePath}`);
+    lines.push(`Findings: errors=${errors} warnings=${warnings} info=${info}`);
+    const agents = typeof summary.agentCount === "number" ? summary.agentCount : undefined;
+    const tools = typeof summary.toolCount === "number" ? summary.toolCount : undefined;
+    const skills = typeof summary.skillCount === "number" ? summary.skillCount : undefined;
+    if (agents !== undefined || tools !== undefined || skills !== undefined) {
+        lines.push(`Inventory: agents=${agents ?? "unknown"} tools=${tools ?? "unknown"} skills=${skills ?? "unknown"}`);
+    }
+    if (findings.length === 0) {
+        lines.push("No boundary findings.");
+        return `${lines.join("\n")}\n`;
+    }
+    lines.push("Boundary findings:");
+    for (const finding of findings) {
+        const severity = typeof finding.severity === "string" ? finding.severity : "unknown";
+        const code = typeof finding.code === "string" ? finding.code : "unknown";
+        const message = typeof finding.message === "string" ? finding.message : "";
+        const agent = typeof finding.agentId === "string" ? ` agent=${finding.agentId}` : "";
+        const tool = typeof finding.toolName === "string" ? ` tool=${finding.toolName}` : "";
+        const skill = typeof finding.skillName === "string" ? ` skill=${finding.skillName}` : "";
+        lines.push(`  - ${severity} ${code}:${agent}${tool}${skill}${message ? ` ${message}` : ""}`);
+    }
+    return `${lines.join("\n")}\n`;
+}

package/dist/index.d.ts

@@ -1,9 +1,9 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRequest, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequestPlanState, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listRequestArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, recordArtifact, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveRuntimeMcpOverStreamableHttp, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRequest, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, analyzeBoundaries, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequestPlanState, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listRequestArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, recordArtifact, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveRuntimeMcpOverStreamableHttp, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
 export { AcpHarnessClient, InProcessHarnessClient, createAcpHarnessClient, createAcpHttpHarnessClient, createAcpStdioHarnessClient, createAgentHarnessClient, createInProcessHarnessClient, } from "./client.js";
 export { createKnowledgeModule, readKnowledgeRuntimeConfig } from "./knowledge/index.js";
 export { readProceduralMemoryRuntimeConfig } from "./knowledge/procedural/index.js";
 export type { AcpApproval, AcpHttpClient, AcpHttpClientOptions, AcpArtifact, AcpEventNotification, AcpNotification, AcpJsonRpcError, AcpJsonRpcRequest, AcpJsonRpcResponse, AcpJsonRpcSuccess, AcpRequestRecord, AcpRequestParams, AcpServerCapabilities, AcpSessionRecord, AcpStreamNotification, AcpStdioClient, AcpStdioClientOptions, } from "./acp.js";
-export type { Approval, CreateAgentHarnessOptions, ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, OperatorOverview, RecordArtifactInput, PublicRequestListeners, RequestData, RequestArtifactListing, RequestEvent, RequestEventType, RequestSnapshot, RequestPlanState, RequestPackage, RequestPackageInput, RequestFlowGraphInput, RequestResult, RequestTraceItem, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, SessionListSummary, RuntimeSessionPackage, RuntimeSessionPackageInput, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
+export type { Approval, BoundaryAgentSurface, BoundaryAnalysisOptions, BoundaryAnalysisSummary, BoundaryFinding, BoundaryFindingSeverity, CreateAgentHarnessOptions, ListMemoriesInput, ListMemoriesResult, MemoryDecision, MemoryKind, MemoryRecord, MemoryScope, MemorizeInput, MemorizeResult, NormalizeUserChatInputOptions, OperatorOverview, RecordArtifactInput, PublicRequestListeners, RequestData, RequestArtifactListing, RequestEvent, RequestEventType, RequestSnapshot, RequestPlanState, RequestPackage, RequestPackageInput, RequestFlowGraphInput, RequestResult, RequestTraceItem, RecallInput, RecallResult, RemoveMemoryInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, SessionListSummary, RuntimeSessionPackage, RuntimeSessionPackageInput, WorkspaceBoundaryAnalysis, UpdateMemoryInput, UserChatInput, UserChatMessage, } from "./api.js";
 export type { AcpHarnessTransport, HarnessClient, HarnessClientApprovalFilter, HarnessClientRequestFilter, HarnessClientRequestOptions, HarnessClientRequestResult, HarnessClientRequestStartOptions, } from "./client.js";
 export type { KnowledgeListInput, KnowledgeMemorizeInput, KnowledgeModule, KnowledgeModuleDependencies, KnowledgeRecallInput, KnowledgeRuntimeConfig, KnowledgeRuntimeContext, } from "./knowledge/index.js";
 export type { ProceduralMemoryBackgroundConfig, ProceduralMemoryFormationConfig, ProceduralMemoryMaintenanceConfig, ProceduralMemoryMaintenanceIdleConfig, ProceduralMemoryMaintenanceScheduleConfig, ProceduralMemoryProviderConfig, ProceduralMemoryRetrievalConfig, ProceduralMemoryRuntimeConfig, } from "./knowledge/procedural/index.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRequest, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequestPlanState, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listRequestArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, recordArtifact, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveRuntimeMcpOverStreamableHttp, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
+export { AgentHarnessAcpServer, AgentHarnessRuntime, cancelRequest, createAgentHarness, createAcpServer, createAcpStdioClient, createRuntimeMcpServer, createUpstreamTimelineReducer, createToolMcpServer, analyzeBoundaries, deleteSession, describeInventory, exportEvaluationBundle, exportFlow, exportSequence, exportRequestPackage, exportSessionPackage, replayEvaluationBundle, getArtifact, getAgent, getApproval, getOperatorOverview, getRequestPlanState, getRequest, getHealth, listMemories, listRequestTraceItems, getSession, listAgentSkills, listRequestArtifacts, listApprovals, listRequests, listRequestEvents, listSessionSummaries, listSessions, memorize, normalizeUserChatInput, recordArtifact, request, recall, removeMemory, resolveApproval, serveA2aHttp, serveAcpHttp, serveAcpStdio, serveAgUiHttp, serveRuntimeMcpOverStdio, serveRuntimeMcpOverStreamableHttp, serveToolsOverStdio, subscribe, stop, updateMemory, } from "./api.js";
 export { AcpHarnessClient, InProcessHarnessClient, createAcpHarnessClient, createAcpHttpHarnessClient, createAcpStdioHarnessClient, createAgentHarnessClient, createInProcessHarnessClient, } from "./client.js";
 export { createKnowledgeModule, readKnowledgeRuntimeConfig } from "./knowledge/index.js";
 export { readProceduralMemoryRuntimeConfig } from "./knowledge/procedural/index.js";

package/dist/package-version.d.ts

@@ -1,2 +1,2 @@
-export declare const AGENT_HARNESS_VERSION = "0.0.352";
+export declare const AGENT_HARNESS_VERSION = "0.0.353";
 export declare const AGENT_HARNESS_RELEASE_DATE = "2026-04-24";

package/dist/package-version.js

@@ -1,2 +1,2 @@
-export const AGENT_HARNESS_VERSION = "0.0.352";
+export const AGENT_HARNESS_VERSION = "0.0.353";
 export const AGENT_HARNESS_RELEASE_DATE = "2026-04-24";

package/dist/runtime/harness/system/boundary-analysis.d.ts

@@ -0,0 +1,42 @@
+import type { WorkspaceBundle } from "../../../contracts/types.js";
+export type BoundaryFindingSeverity = "info" | "warning" | "error";
+export type BoundaryFinding = {
+    severity: BoundaryFindingSeverity;
+    code: string;
+    message: string;
+    agentId?: string;
+    parentAgentId?: string;
+    toolName?: string;
+    skillName?: string;
+    skillPath?: string;
+    relatedAgents?: string[];
+    sourcePath?: string;
+};
+export type BoundaryAgentSurface = {
+    id: string;
+    description: string;
+    tools: string[];
+    skills: string[];
+    subagents: string[];
+    sourcePath?: string;
+    parentAgentId?: string;
+};
+export type BoundaryAnalysisSummary = {
+    agentCount: number;
+    toolCount: number;
+    skillCount: number;
+    findingCount: number;
+    errorCount: number;
+    warningCount: number;
+    infoCount: number;
+};
+export type WorkspaceBoundaryAnalysis = {
+    workspaceRoot: string;
+    summary: BoundaryAnalysisSummary;
+    agents: BoundaryAgentSurface[];
+    findings: BoundaryFinding[];
+};
+export type BoundaryAnalysisOptions = {
+    includeInfo?: boolean;
+};
+export declare function analyzeWorkspaceBoundaries(workspace: WorkspaceBundle, options?: BoundaryAnalysisOptions): WorkspaceBoundaryAnalysis;

package/dist/runtime/harness/system/boundary-analysis.js

@@ -0,0 +1,234 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { readSkillMetadata } from "../../skills/skill-metadata.js";
+import { getBindingPrimaryTools, getBindingSkills, getBindingSubagents, } from "../../support/compiled-binding.js";
+const BUILTIN_SKILL_TOOLS = new Set(["read_todos", "write_todos"]);
+function uniqueSorted(values) {
+    return Array.from(new Set(values.filter((value) => value.trim().length > 0))).sort();
+}
+function addFinding(findings, options, finding) {
+    if (finding.severity === "info" && options.includeInfo === false) {
+        return;
+    }
+    findings.push(finding);
+}
+function discoverWorkspaceSkillPaths(workspaceRoot, referencedSkillPaths) {
+    const skillPaths = new Set(referencedSkillPaths);
+    const skillsRoot = path.join(workspaceRoot, "resources", "skills");
+    if (!existsSync(skillsRoot)) {
+        return uniqueSorted(Array.from(skillPaths));
+    }
+    for (const entry of readdirSync(skillsRoot)) {
+        const skillPath = path.join(skillsRoot, entry);
+        try {
+            if (statSync(skillPath).isDirectory() && existsSync(path.join(skillPath, "SKILL.md"))) {
+                skillPaths.add(skillPath);
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return uniqueSorted(Array.from(skillPaths));
+}
+function describeTopLevelSurface(binding) {
+    return {
+        id: binding.agent.id,
+        description: binding.agent.description,
+        tools: uniqueSorted(getBindingPrimaryTools(binding).map((tool) => tool.name)),
+        skills: uniqueSorted(getBindingSkills(binding)),
+        subagents: uniqueSorted(getBindingSubagents(binding).map((subagent) => subagent.name)),
+        sourcePath: binding.agent.sourcePath,
+    };
+}
+function describeSubagentSurface(subagent, parentAgentId) {
+    return {
+        id: subagent.name,
+        description: subagent.description,
+        tools: uniqueSorted((subagent.tools ?? []).map((tool) => tool.name)),
+        skills: uniqueSorted(subagent.skills ?? []),
+        subagents: [],
+        parentAgentId,
+    };
+}
+function addOwner(index, key, agentId) {
+    const owners = index.get(key) ?? [];
+    owners.push(agentId);
+    index.set(key, owners);
+}
+function stripAgentRefPrefix(value) {
+    const prefix = "agent/";
+    return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+export function analyzeWorkspaceBoundaries(workspace, options = {}) {
+    const findings = [];
+    const agentSurfaces = [];
+    const referencedSkillPaths = [];
+    const toolOwners = new Map();
+    const skillOwners = new Map();
+    const skillSurfaceOwners = new Map();
+    for (const binding of workspace.bindings.values()) {
+        const topLevel = describeTopLevelSurface(binding);
+        agentSurfaces.push(topLevel);
+        for (const skillPath of topLevel.skills) {
+            referencedSkillPaths.push(skillPath);
+        }
+        for (const subagent of getBindingSubagents(binding)) {
+            const surface = describeSubagentSurface(subagent, binding.agent.id);
+            agentSurfaces.push(surface);
+            for (const skillPath of surface.skills) {
+                referencedSkillPaths.push(skillPath);
+            }
+        }
+    }
+    for (const surface of agentSurfaces) {
+        if (surface.description.trim().length === 0) {
+            addFinding(findings, options, {
+                severity: "warning",
+                code: "agent-missing-description",
+                message: `Agent '${surface.id}' has no description, making routing boundaries ambiguous.`,
+                agentId: surface.id,
+                parentAgentId: surface.parentAgentId,
+                sourcePath: surface.sourcePath,
+            });
+        }
+        if (surface.subagents.length > 0 && (surface.tools.length > 0 || surface.skills.length > 0)) {
+            addFinding(findings, options, {
+                severity: "warning",
+                code: "mixed-routing-and-execution-surface",
+                message: `Agent '${surface.id}' declares subagents and also exposes local tools or skills.`,
+                agentId: surface.id,
+                sourcePath: surface.sourcePath,
+            });
+        }
+        if (surface.subagents.length === 0 && surface.tools.length === 0 && surface.skills.length === 0) {
+            addFinding(findings, options, {
+                severity: "info",
+                code: "empty-execution-surface",
+                message: `Agent '${surface.id}' has no tools, skills, or subagents declared.`,
+                agentId: surface.id,
+                parentAgentId: surface.parentAgentId,
+                sourcePath: surface.sourcePath,
+            });
+        }
+        for (const toolName of surface.tools) {
+            addOwner(toolOwners, toolName, surface.id);
+        }
+        for (const skillPath of surface.skills) {
+            addOwner(skillOwners, skillPath, surface.id);
+            skillSurfaceOwners.set(skillPath, [...(skillSurfaceOwners.get(skillPath) ?? []), surface]);
+        }
+    }
+    for (const agent of workspace.agents.values()) {
+        for (const subagentRef of agent.subagentRefs) {
+            const subagentId = stripAgentRefPrefix(subagentRef);
+            if (!workspace.agents.has(subagentId)) {
+                addFinding(findings, options, {
+                    severity: "error",
+                    code: "missing-subagent-reference",
+                    message: `Agent '${agent.id}' references missing subagent '${subagentRef}'.`,
+                    agentId: agent.id,
+                    sourcePath: agent.sourcePath,
+                });
+            }
+        }
+    }
+    for (const [toolName, owners] of toolOwners) {
+        const uniqueOwners = uniqueSorted(owners);
+        if (uniqueOwners.length > 1) {
+            addFinding(findings, options, {
+                severity: "info",
+                code: "shared-tool-surface",
+                message: `Tool '${toolName}' is exposed by multiple agents; review whether the shared surface is intentional.`,
+                toolName,
+                relatedAgents: uniqueOwners,
+            });
+        }
+    }
+    for (const [skillPath, owners] of skillOwners) {
+        const uniqueOwners = uniqueSorted(owners);
+        if (uniqueOwners.length > 1) {
+            const metadata = readSkillMetadata(skillPath);
+            addFinding(findings, options, {
+                severity: "info",
+                code: "shared-skill-surface",
+                message: `Skill '${metadata.name}' is exposed by multiple agents; review whether the shared surface is intentional.`,
+                skillName: metadata.name,
+                skillPath,
+                relatedAgents: uniqueOwners,
+            });
+        }
+    }
+    for (const tool of workspace.tools.values()) {
+        if (!toolOwners.has(tool.name)) {
+            addFinding(findings, options, {
+                severity: "warning",
+                code: "unreferenced-tool",
+                message: `Tool '${tool.name}' is defined but not exposed by any agent or subagent.`,
+                toolName: tool.name,
+                sourcePath: tool.sourcePath,
+            });
+        }
+    }
+    const discoveredSkillPaths = discoverWorkspaceSkillPaths(workspace.workspaceRoot, referencedSkillPaths);
+    for (const skillPath of discoveredSkillPaths) {
+        const metadata = readSkillMetadata(skillPath);
+        const owners = skillOwners.get(skillPath) ?? [];
+        if (owners.length === 0) {
+            addFinding(findings, options, {
+                severity: "warning",
+                code: "unreferenced-skill",
+                message: `Skill '${metadata.name}' is present but not exposed by any agent or subagent.`,
+                skillName: metadata.name,
+                skillPath,
+            });
+            continue;
+        }
+        if (!metadata.allowedTools || metadata.allowedTools.length === 0) {
+            addFinding(findings, options, {
+                severity: "warning",
+                code: "skill-missing-allowed-tools",
+                message: `Skill '${metadata.name}' does not declare allowed-tools.`,
+                skillName: metadata.name,
+                skillPath,
+                relatedAgents: uniqueSorted(owners),
+            });
+            continue;
+        }
+        for (const surface of skillSurfaceOwners.get(skillPath) ?? []) {
+            const owner = surface.parentAgentId ? `${surface.parentAgentId}/${surface.id}` : surface.id;
+            const availableTools = new Set([...surface.tools, ...BUILTIN_SKILL_TOOLS]);
+            for (const allowedTool of metadata.allowedTools) {
+                if (!availableTools.has(allowedTool)) {
+                    addFinding(findings, options, {
+                        severity: "error",
+                        code: "skill-allowed-tool-unavailable",
+                        message: `Skill '${metadata.name}' allows tool '${allowedTool}', but agent '${owner}' does not expose it.`,
+                        agentId: surface.id,
+                        parentAgentId: surface.parentAgentId,
+                        toolName: allowedTool,
+                        skillName: metadata.name,
+                        skillPath,
+                    });
+                }
+            }
+        }
+    }
+    const errorCount = findings.filter((finding) => finding.severity === "error").length;
+    const warningCount = findings.filter((finding) => finding.severity === "warning").length;
+    const infoCount = findings.filter((finding) => finding.severity === "info").length;
+    return {
+        workspaceRoot: workspace.workspaceRoot,
+        summary: {
+            agentCount: agentSurfaces.length,
+            toolCount: workspace.tools.size,
+            skillCount: discoveredSkillPaths.length,
+            findingCount: findings.length,
+            errorCount,
+            warningCount,
+            infoCount,
+        },
+        agents: agentSurfaces,
+        findings,
+    };
+}

package/dist/runtime/harness.d.ts

@@ -1,6 +1,7 @@
 import type { ApprovalRecord, ArtifactListing, CancelOptions, HarnessEvent, HarnessStreamItem, RuntimeHealthSnapshot, RuntimeOperatorOverview, ListMemoriesInput, ListMemoriesResult, MessageContent, RemoveMemoryInput, RequestPlanState, RequestOptions, RequestRecord, RequestResult, RequestSummary, RequestStartOptions, RestartConversationOptions, RuntimeAdapterOptions, RuntimeArtifactWriteInput, RuntimeEvaluationExport, RuntimeEvaluationExportInput, RuntimeEvaluationReplayInput, RuntimeEvaluationReplayResult, RuntimeRequestPackage, RuntimeRequestPackageInput, RuntimeSessionPackage, RuntimeSessionPackageInput, ResumeOptions, MemoryRecord, MemorizeInput, MemorizeResult, RecallInput, RecallResult, UpdateMemoryInput, SessionSummary, SessionRecord, SessionListSummary, WorkspaceBundle } from "../contracts/types.js";
 import { type RuntimeMcpServerOptions, type ToolMcpServerOptions } from "../mcp.js";
 import { type InventoryAgentRecord, type InventorySkillRecord } from "./harness/system/inventory.js";
+import { type BoundaryAnalysisOptions, type WorkspaceBoundaryAnalysis } from "./harness/system/boundary-analysis.js";
 import type { RequirementAssessmentOptions } from "./harness/system/skill-requirements.js";
 import { SystemScheduleManager } from "./scheduling/system-schedule-manager.js";
 export declare class AgentHarnessRuntime {
@@ -119,6 +120,7 @@ export declare class AgentHarnessRuntime {
         workspaceRoot: string;
         agents: InventoryAgentRecord[];
     };
+    analyzeWorkspaceBoundaries(options?: BoundaryAnalysisOptions): WorkspaceBoundaryAnalysis;
     private deleteSessionCheckpoints;
     deleteSession(sessionId: string): Promise<boolean>;
     createToolMcpServer(options: ToolMcpServerOptions): Promise<import("@modelcontextprotocol/sdk/server/mcp").McpServer>;

package/dist/runtime/harness.js

@@ -30,6 +30,7 @@ import { closeMcpClientsForWorkspace } from "../resource/mcp/tool-support.js";
 import { getBindingRuntimeExecutionMode, } from "./support/compiled-binding.js";
 import { bindingSupportsRunningReplay, getWorkspaceBinding, resolveWorkspaceAgentTools, } from "./harness/bindings.js";
 import { describeWorkspaceInventory, getAgentInventoryRecord, listAgentSkills as listWorkspaceAgentSkills, } from "./harness/system/inventory.js";
+import { analyzeWorkspaceBoundaries, } from "./harness/system/boundary-analysis.js";
 import { createDefaultHealthSnapshot, isInventoryEnabled, isSessionMemorySyncEnabled, } from "./harness/runtime-defaults.js";
 import { cloneRequestRecord, cloneSessionRecord, deriveRequestInputFromTranscript, mergeMemoryItems, summarizeApprovalEvidence, toPublicHarnessStreamItem, toPublicRequestResultShape, toSessionListSummary, } from "./harness/public-shapes.js";
 import { Mem0IngestionSync, Mem0SemanticRecall, readMem0RuntimeConfig, } from "./harness/system/mem0-ingestion-sync.js";
@@ -877,6 +878,9 @@ export class AgentHarnessRuntime {
             ...options,
         });
     }
+    analyzeWorkspaceBoundaries(options = {}) {
+        return analyzeWorkspaceBoundaries(this.workspace, options);
+    }
     async deleteSessionCheckpoints(sessionId) {
         const resolver = this.resolvedRuntimeAdapterOptions.checkpointerResolver;
         if (!resolver) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@botbotgo/agent-harness",
-  "version": "0.0.352",
+  "version": "0.0.353",
   "description": "Workspace runtime for multi-agent applications",
   "license": "MIT",
   "type": "module",