@stll/folio-cli 0.3.4 → 0.4.1

package/dist/execute-write.js

@@ -1,3 +1,4 @@
+import { expandBatchOperations } from "./batch-operations.js";
 import { checkExpectedVersion, openReviewer, readDocumentFile } from "./document.js";
 import { acquireLeaseForWrite } from "./editor-lease.js";
 import { FOLIO_CLI_ERROR_CODES, cliError } from "./errors.js";
@@ -8,10 +9,10 @@ import { diffPackages, nextRevisionIdSeed } from "./package-parts.js";
 import { SIDECAR_DIRECTORY, inspectPath, readSidecarFile, unsafePath } from "./sidecar.js";
 import { commitTransaction } from "./transaction.js";
 import { Result, panic } from "better-result";
-import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
-import { generateRedlineDocx } from "@stll/folio-agents/compare";
 import { executeFolioToolCallUntyped } from "@stll/folio-agents/execute";
 import { FOLIO_AGENT_TOOL_NAMES } from "@stll/folio-agents/types";
+import { createReviewerBridge } from "@stll/folio-agents/bridges/reviewer";
+import { generateRedlineDocx } from "@stll/folio-agents/compare";
 import { realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
@@ -110,32 +111,50 @@ const saveReviewer = async (reviewer, repack) => {
 const commentExists = (reviewer, commentId) => reviewer.getComments().some((thread) => String(thread.id) === commentId || thread.replies.some((reply) => String(reply.id) === commentId));
 const mutateWithAgentTool = async ({ tool, source, args, options }) => {
 	if (tool.type !== "agentWrite") return panic("mutateWithAgentTool needs an agentWrite tool");
-	const reviewer = await openReviewer(source, options.author);
-	if (reviewer.isErr()) return Result.err(reviewer.error);
+	const opened = await openReviewer(source, options.author);
+	if (opened.isErr()) return Result.err(opened.error);
+	const { reviewer } = opened.value;
 	const idSeed = await nextRevisionIdSeed(source.bytes);
 	if (idSeed.isErr()) return Result.err(idSeed.error);
-	if ((tool.agentTool === FOLIO_AGENT_TOOL_NAMES.replyComment || tool.agentTool === FOLIO_AGENT_TOOL_NAMES.resolveComment) && !commentExists(reviewer.value, args["commentId"])) return Result.err(cliError({
+	if ((tool.agentTool === FOLIO_AGENT_TOOL_NAMES.replyComment || tool.agentTool === FOLIO_AGENT_TOOL_NAMES.resolveComment) && !commentExists(reviewer, args["commentId"])) return Result.err(cliError({
 		code: FOLIO_CLI_ERROR_CODES.notFound,
 		message: `No comment with id ${JSON.stringify(args["commentId"])}.`,
 		hint: "Take the id from folio comments."
 	}));
-	const bridge = createReviewerBridge(reviewer.value, {
+	const bridge = createReviewerBridge(reviewer, {
 		mode: tool.editMode === "tracked-or-direct" ? options.mode : "tracked-changes",
 		revisionStamp: {
 			date: options.date,
 			idSeed: idSeed.value
 		}
 	});
-	const executed = executeFolioToolCallUntyped(tool.agentTool, args, bridge);
+	let callArgs = args;
+	let callOptions = {};
+	let replaced = [];
+	if (tool.agentTool === FOLIO_AGENT_TOOL_NAMES.suggestChanges) {
+		const batch = expandBatchOperations(args["operations"], bridge);
+		if (batch.isErr()) return Result.err(batch.error);
+		callArgs = {
+			...args,
+			operations: batch.value.operations
+		};
+		callOptions = batch.value.options;
+		replaced = batch.value.replaced;
+	}
+	const executed = executeFolioToolCallUntyped(tool.agentTool, callArgs, bridge, callOptions);
 	if (!executed.ok) return Result.err(invalidInput(executed.error));
 	const refusal = refusalFor(executed.result);
 	if (refusal !== null) return Result.err(refusal);
-	const saved = await saveReviewer(reviewer.value, options.repack);
+	const saved = await saveReviewer(reviewer, options.repack);
 	if (saved.isErr()) return Result.err(saved.error);
 	const receipts = isRecord(executed.result) && Array.isArray(executed.result["receipts"]) ? executed.result["receipts"] : [];
+	const result = replaced.length > 0 && isRecord(executed.result) ? {
+		...executed.result,
+		replaced
+	} : executed.result;
 	return Result.ok({
 		...saved.value,
-		result: executed.result,
+		result,
 		receipts
 	});
 };
@@ -145,11 +164,12 @@ const resolveChanges = async ({ source, args, options }) => {
 	if (!isResolveAction(action)) return Result.err(invalidInput("resolve_changes needs action \"accept\" or \"reject\"."));
 	const idList = Array.isArray(ids) && ids.every((id) => typeof id === "string") ? ids : void 0;
 	if ((idList !== void 0 && idList.length > 0) === (all === true)) return Result.err(invalidInput("Pass change ids or all, exactly one of them.", "folio accept --id 12 or --all."));
-	const reviewer = await openReviewer(source, options.author);
-	if (reviewer.isErr()) return Result.err(reviewer.error);
+	const opened = await openReviewer(source, options.author);
+	if (opened.isErr()) return Result.err(opened.error);
+	const { reviewer } = opened.value;
 	let resolved;
 	if (all === true) {
-		const count = action === "accept" ? reviewer.value.acceptAll() : reviewer.value.rejectAll();
+		const count = action === "accept" ? reviewer.acceptAll() : reviewer.rejectAll();
 		if (count === 0) return Result.err(cliError({
 			code: FOLIO_CLI_ERROR_CODES.operationRejected,
 			message: "The document has no pending tracked changes; nothing was written."
@@ -157,7 +177,7 @@ const resolveChanges = async ({ source, args, options }) => {
 		resolved = count;
 	} else {
 		const selected = idList ?? [];
-		const known = new Set(reviewer.value.getChanges().map(({ id }) => String(id)));
+		const known = new Set(reviewer.getChanges().map(({ id }) => String(id)));
 		const missing = selected.filter((id) => !known.has(id));
 		if (missing.length > 0) return Result.err(cliError({
 			code: FOLIO_CLI_ERROR_CODES.notFound,
@@ -165,20 +185,20 @@ const resolveChanges = async ({ source, args, options }) => {
 			hint: "Take ids from folio changes.",
 			details: { missing }
 		}));
-		for (const id of selected) if (!(action === "accept" ? reviewer.value.acceptChange(Number(id)) : reviewer.value.rejectChange(Number(id)))) return Result.err(cliError({
+		for (const id of selected) if (!(action === "accept" ? reviewer.acceptChange(Number(id)) : reviewer.rejectChange(Number(id)))) return Result.err(cliError({
 			code: FOLIO_CLI_ERROR_CODES.operationRejected,
 			message: `Change ${id} could not be ${action}ed; nothing was written.`
 		}));
 		resolved = selected;
 	}
-	const saved = await saveReviewer(reviewer.value, options.repack);
+	const saved = await saveReviewer(reviewer, options.repack);
 	if (saved.isErr()) return Result.err(saved.error);
 	return Result.ok({
 		...saved.value,
 		result: {
 			action,
 			resolved,
-			remaining: reviewer.value.getChanges().length
+			remaining: reviewer.getChanges().length
 		},
 		receipts: []
 	});

package/dist/mcp-kit/envelope.d.ts

@@ -0,0 +1,27 @@
+import { ToolCallResult, ToolError, ToolInputIssue, ToolOutcome } from "./types.js";
+//#region src/mcp-kit/envelope.d.ts
+/** Error codes the surface itself answers with; a tool adds its own. */
+declare const KIT_ERROR_CODES: {
+  readonly validation: "validation_error";
+  readonly unknownTool: "unknown_tool";
+  readonly notFound: "not_found";
+  readonly internal: "internal_error";
+};
+declare const toolError: (error: {
+  code: string;
+  message: string;
+  hint?: string | undefined;
+  retryable?: boolean | undefined;
+  issues?: readonly ToolInputIssue[] | undefined;
+  details?: unknown;
+}) => ToolError;
+declare const failure: (error: Parameters<typeof toolError>[0]) => ToolOutcome;
+declare const success: (value: unknown) => ToolOutcome;
+declare const validationError: (message: string, issues: readonly ToolInputIssue[], hint?: string) => ToolOutcome;
+/** Encode an outcome as a `tools/call` result, with the input notes after a success. */
+declare const toCallResult: (outcome: ToolOutcome, notes?: readonly string[]) => ToolCallResult;
+/** Up to three known names close to `name`, closest first. */
+declare const closestNames: (name: string, known: readonly string[]) => string[];
+declare const didYouMean: (suggestions: readonly string[]) => string;
+//#endregion
+export { KIT_ERROR_CODES, closestNames, didYouMean, failure, success, toCallResult, toolError, validationError };

package/dist/mcp-kit/envelope.js

@@ -0,0 +1,80 @@
+//#region src/mcp-kit/envelope.ts
+/** Error codes the surface itself answers with; a tool adds its own. */
+const KIT_ERROR_CODES = {
+	validation: "validation_error",
+	unknownTool: "unknown_tool",
+	notFound: "not_found",
+	internal: "internal_error"
+};
+const toolError = (error) => ({
+	code: error.code,
+	message: error.message,
+	...error.hint !== void 0 && { hint: error.hint },
+	retryable: error.retryable ?? false,
+	...error.issues !== void 0 && error.issues.length > 0 && { issues: error.issues },
+	...error.details !== void 0 && { details: error.details }
+});
+const failure = (error) => ({
+	ok: false,
+	error: toolError(error)
+});
+const success = (value) => ({
+	ok: true,
+	value
+});
+const validationError = (message, issues, hint) => failure({
+	code: KIT_ERROR_CODES.validation,
+	message,
+	issues,
+	hint,
+	retryable: true
+});
+/** Encode an outcome as a `tools/call` result, with the input notes after a success. */
+const toCallResult = (outcome, notes = []) => {
+	if (!outcome.ok) return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({ error: outcome.error })
+		}],
+		isError: true
+	};
+	const content = [{
+		type: "text",
+		text: JSON.stringify(outcome.value ?? null)
+	}];
+	const distinct = [...new Set(notes)];
+	if (distinct.length > 0) content.push({
+		type: "text",
+		text: `Input read: ${distinct.join(" ")}`
+	});
+	return {
+		content,
+		isError: false
+	};
+};
+const editDistance = (a, b) => {
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	for (let i = 1; i <= a.length; i += 1) {
+		const current = [i];
+		for (let j = 1; j <= b.length; j += 1) {
+			const substitution = (previous[j - 1] ?? 0) + (a[i - 1] === b[j - 1] ? 0 : 1);
+			current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, substitution);
+		}
+		previous = current;
+	}
+	return previous[b.length] ?? 0;
+};
+/** Up to three known names close to `name`, closest first. */
+const closestNames = (name, known) => {
+	const lowered = name.toLowerCase();
+	return known.map((candidate) => {
+		const lower = candidate.toLowerCase();
+		return {
+			candidate,
+			distance: lower.includes(lowered) || lowered.includes(lower) ? 0 : editDistance(lowered, lower)
+		};
+	}).filter(({ distance }) => distance <= Math.max(2, Math.floor(name.length / 3))).toSorted((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate)).slice(0, 3).map(({ candidate }) => candidate);
+};
+const didYouMean = (suggestions) => suggestions.length === 0 ? "" : `Did you mean ${suggestions.map((name) => `"${name}"`).join(" or ")}? `;
+//#endregion
+export { KIT_ERROR_CODES, closestNames, didYouMean, failure, success, toCallResult, toolError, validationError };

package/dist/mcp-kit/index.d.ts

@@ -0,0 +1,6 @@
+import { JsonSchema, ListedTool, ToolAccess, ToolCallResult, ToolDefinition, ToolError, ToolInputIssue, ToolOutcome } from "./types.js";
+import { KIT_ERROR_CODES, closestNames, didYouMean, failure, success, toCallResult, toolError, validationError } from "./envelope.js";
+import { ReadInput, readToolInput } from "./input.js";
+import { CompactSchemaOptions, advertisedBytes, compactSchema, hoistRepeatedSchemas } from "./schema.js";
+import { CAPABILITY_TOOL_NAMES, ToolSurface, ToolSurfaceOptions, createToolSurface } from "./surface.js";
+export { CAPABILITY_TOOL_NAMES, type CompactSchemaOptions, type JsonSchema, KIT_ERROR_CODES, type ListedTool, type ReadInput, type ToolAccess, type ToolCallResult, type ToolDefinition, type ToolError, type ToolInputIssue, type ToolOutcome, type ToolSurface, type ToolSurfaceOptions, advertisedBytes, closestNames, compactSchema, createToolSurface, didYouMean, failure, hoistRepeatedSchemas, readToolInput, success, toCallResult, toolError, validationError };

package/dist/mcp-kit/index.js

@@ -0,0 +1,5 @@
+import { KIT_ERROR_CODES, closestNames, didYouMean, failure, success, toCallResult, toolError, validationError } from "./envelope.js";
+import { readToolInput } from "./input.js";
+import { advertisedBytes, compactSchema, hoistRepeatedSchemas } from "./schema.js";
+import { CAPABILITY_TOOL_NAMES, createToolSurface } from "./surface.js";
+export { CAPABILITY_TOOL_NAMES, KIT_ERROR_CODES, advertisedBytes, closestNames, compactSchema, createToolSurface, didYouMean, failure, hoistRepeatedSchemas, readToolInput, success, toCallResult, toolError, validationError };

package/dist/mcp-kit/input.d.ts

@@ -0,0 +1,23 @@
+import { JsonSchema, ToolAccess, ToolInputIssue } from "./types.js";
+//#region src/mcp-kit/input.d.ts
+type ReadInput = {
+  ok: true;
+  value: Record<string, unknown>;
+  notes: readonly string[];
+} | {
+  ok: false;
+  message: string;
+  issues: readonly ToolInputIssue[];
+  hint: string;
+};
+type ReadInputOptions = {
+  schema: JsonSchema;
+  value: unknown;
+  access: ToolAccess;
+  /** Properties passed through exactly as sent. */
+  exactProperties?: readonly string[] | undefined;
+};
+/** Check and leniently read one call's arguments against the tool's schema. */
+declare const readToolInput: ({ schema, value, access, exactProperties }: ReadInputOptions) => ReadInput;
+//#endregion
+export { ReadInput, readToolInput };

package/dist/mcp-kit/input.js

@@ -0,0 +1,76 @@
+import { normalizeAgentInput } from "@stll/agent-input";
+//#region src/mcp-kit/input.ts
+/**
+* Reading a model's arguments before a tool sees them: `null` in an optional
+* property is absent, spellings that carry one meaning (`"true"`, `"20"`, an
+* enum value in another case) are read through `@stll/agent-input` with a
+* note, anything that carries two is asked about, and an argument the schema
+* does not declare, or a required one that is missing, is refused rather than
+* dropped.
+*/
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const propertiesOf = (schema) => isRecord(schema["properties"]) ? schema["properties"] : {};
+const requiredOf = (schema) => Array.isArray(schema["required"]) ? schema["required"].filter((key) => typeof key === "string") : [];
+/**
+* A placeholder in an optional property of a read is "not filtering" and is
+* dropped with a note; on a write it may be an id that changes what the call
+* does, so it is asked about.
+*/
+const PLACEHOLDER_POLICY = {
+	read: "absent",
+	write: "ask"
+};
+const refusal = (message, issues, hint) => ({
+	ok: false,
+	message,
+	issues,
+	hint
+});
+/** Check and leniently read one call's arguments against the tool's schema. */
+const readToolInput = ({ schema, value, access, exactProperties = [] }) => {
+	if (value !== void 0 && !isRecord(value)) return refusal("Arguments must be a JSON object.", [], "Send the arguments as an object.");
+	const properties = propertiesOf(schema);
+	const required = requiredOf(schema);
+	const input = {};
+	const unknown = [];
+	for (const [key, entry] of Object.entries(value ?? {})) {
+		if (entry === void 0) continue;
+		if (!Object.hasOwn(properties, key)) unknown.push({
+			path: key,
+			message: `Unknown parameter: ${key}`
+		});
+		else if (entry !== null || required.includes(key)) Object.defineProperty(input, key, {
+			value: entry,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
+	if (unknown.length > 0) return refusal("Arguments need clarification.", unknown, `Accepted parameters: ${Object.keys(properties).join(", ")}.`);
+	const exact = new Set(exactProperties);
+	const normalized = normalizeAgentInput({
+		placeholders: PLACEHOLDER_POLICY[access],
+		schema: {
+			...schema,
+			properties: Object.fromEntries(Object.entries(properties).map(([key, property]) => [key, exact.has(key) ? {} : property]))
+		},
+		value: input
+	});
+	if (!normalized.ok) return refusal("Arguments need clarification.", normalized.issues.map(({ path, received, expected }) => ({
+		path,
+		message: `${received} is not ${expected}.`
+	})), normalized.issues.map(({ path, hint }) => path.length === 0 ? hint : `${path}: ${hint}`).join(" "));
+	const read = isRecord(normalized.value) ? normalized.value : {};
+	const missing = required.filter((key) => read[key] === void 0).map((key) => ({
+		path: key,
+		message: `Missing parameter: ${key}`
+	}));
+	if (missing.length > 0) return refusal("Arguments are incomplete.", missing, `Required: ${required.join(", ")}.`);
+	return {
+		ok: true,
+		value: read,
+		notes: normalized.notes
+	};
+};
+//#endregion
+export { readToolInput };

package/dist/mcp-kit/schema.d.ts

@@ -0,0 +1,20 @@
+import { JsonSchema, ListedTool } from "./types.js";
+//#region src/mcp-kit/schema.d.ts
+type CompactSchemaOptions = {
+  /** Keep descriptions this many property levels deep; 0 (the default) keeps none. */
+  describedDepth?: number;
+};
+/** The schema without annotation keywords, descriptions kept only as deep as asked. */
+declare const compactSchema: (schema: JsonSchema, { describedDepth }?: CompactSchemaOptions) => JsonSchema;
+/**
+ * Hoist every object subschema that occurs more than once and serializes to
+ * at least `minBytes` into `$defs`, referenced by `$ref`: a schema that
+ * repeats one shape for several properties states it once.
+ */
+declare const hoistRepeatedSchemas: (schema: JsonSchema, { minBytes }?: {
+  minBytes?: number;
+}) => JsonSchema;
+/** The UTF-8 size of what `tools/list` sends for these tools. */
+declare const advertisedBytes: (tools: readonly ListedTool[]) => number;
+//#endregion
+export { CompactSchemaOptions, advertisedBytes, compactSchema, hoistRepeatedSchemas };

package/dist/mcp-kit/schema.js

@@ -0,0 +1,97 @@
+//#region src/mcp-kit/schema.ts
+const ANNOTATION_KEYWORDS = /* @__PURE__ */ new Set([
+	"$comment",
+	"$schema",
+	"default",
+	"description",
+	"examples",
+	"title"
+]);
+/** Keywords whose value is a map of property name to schema. */
+const SCHEMA_MAP_KEYWORDS = /* @__PURE__ */ new Set([
+	"$defs",
+	"definitions",
+	"patternProperties",
+	"properties"
+]);
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+* `describedDepth` keeps `description` on schemas that many property maps
+* down (1: the tool's own arguments) and strips it below, where a large
+* nested schema repeats itself.
+*/
+const compactNode = (node, depth, describedDepth) => {
+	if (Array.isArray(node)) return node.map((item) => compactNode(item, depth, describedDepth));
+	if (!isRecord(node)) return node;
+	const compacted = {};
+	for (const [key, value] of Object.entries(node)) {
+		const keptDescription = key === "description" && depth > 0 && depth <= describedDepth;
+		if (ANNOTATION_KEYWORDS.has(key) && !keptDescription) continue;
+		if (key === "maximum" && value === Number.MAX_SAFE_INTEGER) continue;
+		compacted[key] = SCHEMA_MAP_KEYWORDS.has(key) && isRecord(value) ? Object.fromEntries(Object.entries(value).map(([name, schema]) => [name, compactNode(schema, depth + 1, describedDepth)])) : compactNode(value, depth, describedDepth);
+	}
+	return compacted;
+};
+/** The schema without annotation keywords, descriptions kept only as deep as asked. */
+const compactSchema = (schema, { describedDepth = 0 } = {}) => {
+	const compacted = compactNode(schema, 0, describedDepth);
+	return isRecord(compacted) ? compacted : {};
+};
+/** Count every object subschema below the root by its serialization, naming each by where it first appears. */
+const countSubschemas = (node, name, seen, isRoot) => {
+	if (Array.isArray(node)) {
+		for (const item of node) countSubschemas(item, name, seen, false);
+		return;
+	}
+	if (!isRecord(node)) return;
+	if (!isRoot) {
+		const key = JSON.stringify(node);
+		const occurrence = seen.get(key);
+		if (occurrence === void 0) seen.set(key, {
+			count: 1,
+			name,
+			bytes: key.length
+		});
+		else occurrence.count += 1;
+	}
+	for (const [key, value] of Object.entries(node)) if (SCHEMA_MAP_KEYWORDS.has(key) && isRecord(value)) for (const [child, schema] of Object.entries(value)) countSubschemas(schema, child, seen, false);
+	else countSubschemas(value, name, seen, false);
+};
+/**
+* Hoist every object subschema that occurs more than once and serializes to
+* at least `minBytes` into `$defs`, referenced by `$ref`: a schema that
+* repeats one shape for several properties states it once.
+*/
+const hoistRepeatedSchemas = (schema, { minBytes = 200 } = {}) => {
+	const seen = /* @__PURE__ */ new Map();
+	countSubschemas(schema, "schema", seen, true);
+	const refs = /* @__PURE__ */ new Map();
+	const defs = {};
+	const repeated = [...seen.entries()].filter(([, { count, bytes }]) => count > 1 && bytes >= minBytes).toSorted(([, a], [, b]) => b.bytes - a.bytes);
+	for (const [key, { name }] of repeated) {
+		let defName = name;
+		for (let suffix = 2; defName in defs; suffix += 1) defName = `${name}${suffix}`;
+		refs.set(key, defName);
+		defs[defName] = null;
+	}
+	if (refs.size === 0) return schema;
+	const replace = (node, isRoot) => {
+		if (Array.isArray(node)) return node.map((item) => replace(item, false));
+		if (!isRecord(node)) return node;
+		const ref = isRoot ? void 0 : refs.get(JSON.stringify(node));
+		if (ref !== void 0) return { $ref: `#/$defs/${ref}` };
+		const replaced = {};
+		for (const [key, value] of Object.entries(node)) replaced[key] = SCHEMA_MAP_KEYWORDS.has(key) && isRecord(value) ? Object.fromEntries(Object.entries(value).map(([child, sub]) => [child, replace(sub, false)])) : replace(value, false);
+		return replaced;
+	};
+	for (const [key, defName] of refs) defs[defName] = replace(JSON.parse(key), true);
+	const root = replace(schema, true);
+	return isRecord(root) ? {
+		...root,
+		$defs: defs
+	} : schema;
+};
+/** The UTF-8 size of what `tools/list` sends for these tools. */
+const advertisedBytes = (tools) => new TextEncoder().encode(JSON.stringify(tools)).length;
+//#endregion
+export { advertisedBytes, compactSchema, hoistRepeatedSchemas };

package/dist/mcp-kit/surface.d.ts

@@ -0,0 +1,19 @@
+import { ListedTool, ToolCallResult, ToolDefinition } from "./types.js";
+//#region src/mcp-kit/surface.d.ts
+declare const CAPABILITY_TOOL_NAMES: {
+  readonly list: "list_capabilities";
+  readonly describe: "describe_capability";
+  readonly invoke: "invoke_capability";
+};
+type ToolSurfaceOptions<Context> = {
+  readonly tools: readonly ToolDefinition<Context>[];
+};
+type ToolSurface<Context> = {
+  /** What `tools/list` returns: the direct tools, then the capability tools. */
+  readonly listTools: () => ListedTool[];
+  readonly callTool: (name: string, args: unknown, context: Context) => Promise<ToolCallResult>;
+};
+/** Build a surface over `tools`. Names must be unique and not a capability tool's. */
+declare const createToolSurface: <Context>({ tools }: ToolSurfaceOptions<Context>) => ToolSurface<Context>;
+//#endregion
+export { CAPABILITY_TOOL_NAMES, ToolSurface, ToolSurfaceOptions, createToolSurface };