@modelprofile.com/flexharness 10.20.0 → 10.22.0

package/ts/interfaces.ts

@@ -73,6 +73,16 @@ export interface IFlexSessionMetricsState {
   pendingCompactionId?: string;
   lastObservedInputTokens?: number;
   lastObservedInputTokensAt?: string;
+  /**
+   * Sums of the settled per-call reports' input (cache reads included), cache-read and cache-write
+   * tokens. All four breakdown keys are present together; metrics written before they were counted
+   * have none of them.
+   */
+  reportedLifetimeInputTokens?: number;
+  reportedLifetimeCacheReadTokens?: number;
+  reportedLifetimeCacheWriteTokens?: number;
+  /** The breakdown counts every call since the session began, without saturation. */
+  lifetimeTokenBreakdownComplete?: boolean;
 }
 
 /** No member estimates current context size or includes child-session / tool-owned model calls. */
@@ -90,6 +100,17 @@ export interface IFlexSessionMetrics {
   lastObservedInputTokensAt?: string;
   /** Always historical: output, steering, compaction and reversion can change context. */
   lastObservedInputTokensFreshness?: 'historical';
+  /** Sum of the settled per-call reports' input tokens, cache reads included; a lower bound when incomplete. */
+  reportedLifetimeInputTokens: number;
+  /** Sum of the settled per-call reports' input tokens read from the prompt cache; a lower bound when incomplete. */
+  reportedLifetimeCacheReadTokens: number;
+  /** Sum of the settled per-call reports' input tokens written to the prompt cache; a lower bound when incomplete. */
+  reportedLifetimeCacheWriteTokens: number;
+  /**
+   * The three sums cover every call `lifetimeUsedTokens` covers: lifetime usage is complete and
+   * the session's calls were counted by input and cache since it began.
+   */
+  lifetimeTokenBreakdownComplete: boolean;
 }
 
 export interface IFlexModelIdentity {

package/ts/readme.md

@@ -65,7 +65,7 @@ or provider SDKs.
 | `/chat/harness` | `FlexHarnessTranscript` and intents for the `@design.estate/dees-catalog` harness components, browser-safe | `@design.estate/dees-catalog` `^17.0.0 \|\| ^19.5.0 \|\| ^20.0.0 \|\| ^21.0.0` (types only) |
 | `/kvm` | Browser control, terminal framing and OCR observation | `puppeteer` |
 | `/documents` | PDF and image documents, `extractTextFromPdf` | `@push.rocks/smartpdf`; for image documents `sharp` |
-| `/mcp` | MCP clients and AI SDK tool conversion | `@modelcontextprotocol/sdk` |
+| `/mcp` | MCP clients, AI SDK tool conversion and `createMcpToolCatalog`, the tool catalog of MCP tools | `@modelcontextprotocol/sdk` |
 | `/migration` | Existing versioned harness migrations | None |
 | `/stores/nosqldb` | `NoSqlFlexHarnessStores`: cross-process CAS stores on `@lossless.org/client/nosqldb` | `@lossless.org/client` |
 
@@ -108,6 +108,9 @@ A warm read joins outstanding projection writes and surfaces accounting failures
 | `inFlight` | A generation or actual compactor invocation has not settled its accounting yet. |
 | `lastObservedInputTokens`, `lastObservedInputTokensAt` | Input count and observation time of the last settled generation call with complete input/output totals. |
 | `lastObservedInputTokensFreshness` | Always `historical`. This is **not** current context size: output, steering, compaction and reversion can change context. |
+| `reportedLifetimeInputTokens` | Sum of the settled per-call reports' input tokens, prompt-cache reads included. |
+| `reportedLifetimeCacheReadTokens`, `reportedLifetimeCacheWriteTokens` | Sums of the settled per-call reports' input tokens read from and written to the prompt cache. |
+| `lifetimeTokenBreakdownComplete` | The three sums cover every call `lifetimeUsedTokens` covers: lifetime usage is complete and the session's calls were counted by input and cache since it began. Otherwise they are lower bounds. |
 
 Accounting covers this session's generation calls and reported compaction calls,
 including failure, cancellation and retries. Child sessions own their own spend;
@@ -122,6 +125,10 @@ conservative: unresolved operations are cleared without certifying their unknown
 spend. Undo, redo, compaction and transcript archiving never subtract lifetime
 spend. Importing visible history does not reconstruct historical billing.
 
+Sessions whose metrics were written before input and cache tokens were counted count
+them from their next settled call on and never report the breakdown complete; their
+lifetime total keeps its completeness.
+
 Conversational runs that exhaust `maxSteps` with tool work or unseen input remaining
 fail with `FlexHarnessStepLimitError` (`FLEX_STEP_LIMIT`), rather than being marked
 completed with an empty answer. Standalone Agent callers retain tool-only results
@@ -1137,7 +1144,7 @@ Each domain serializes its own mutations. A successful run first persists a hidd
 
 Projection stores accept schema version 1, 2, or 3 from `load()`, but every `save()` receives the current schema-3 shape. Schema 3 records explicit reversion protocol, transcript/workspace provenance, and V2 disposition. A terminal V2 segment must be conclusively `revertible`, `no-change`, or `nonrevertible`; a pending V2 capture remains owned by its capture WAL and is never treated as transcript history.
 
-Current schema-3 projections also persist optional `metrics` state. Older strict readers that do not recognize this key cannot reopen a projection after metrics have been written; downgrade or mixed-version access to that session is unsupported.
+Current schema-3 projections also persist optional `metrics` state. Older strict readers that do not recognize this key, or the token breakdown keys inside it (`reportedLifetimeInputTokens`, `reportedLifetimeCacheReadTokens`, `reportedLifetimeCacheWriteTokens`, `lifetimeTokenBreakdownComplete`), cannot reopen a projection after they have been written; downgrade or mixed-version access to that session is unsupported.
 
 A loaded schema-1 projection has no reversion state. Schema-2 `workspaceCaptured` segments migrate as protocol-1 workspace/revertible history without discarding references; transcript-only segments migrate as protocol-1 transcript provenance. Under `workspace-required`, that legacy transcript history is a barrier. The next projection mutation writes schema 3. Custom stores must preserve strict compare-and-swap revisions across schema-1 and schema-2 read-upgrade-write cycles, including uncertain-save reconciliation.
 

package/ts/utils.json.ts

@@ -1516,6 +1516,7 @@ function assertSessionMetrics(value: unknown): void {
   requireOnlyKeys(metrics, [
     'reportedLifetimeUsedTokens', 'reportedLifetimeUsedTokensExact', 'lifetimeUsageComplete',
     'pendingGenerationId', 'pendingCompactionId', 'lastObservedInputTokens', 'lastObservedInputTokensAt',
+    ...sessionMetricsBreakdownKeys,
   ], path);
   requireNonNegativeInteger(metrics.reportedLifetimeUsedTokens, `${path}.reportedLifetimeUsedTokens`);
   for (const key of ['reportedLifetimeUsedTokensExact', 'lifetimeUsageComplete']) {
@@ -1537,8 +1538,26 @@ function assertSessionMetrics(value: unknown): void {
       throw new FlexHarnessStoreFormatError(`${path}.lastObservedInputTokensAt must be an ISO timestamp.`);
     }
   }
+  // Metrics written before the breakdown was counted have none of its keys.
+  const breakdownKeys = sessionMetricsBreakdownKeys.filter((breakdownKey) => Object.hasOwn(metrics, breakdownKey));
+  if (breakdownKeys.length > 0) {
+    if (breakdownKeys.length !== sessionMetricsBreakdownKeys.length) {
+      throw new FlexHarnessStoreFormatError(`${path} has a partial token breakdown.`);
+    }
+    for (const counter of ['reportedLifetimeInputTokens', 'reportedLifetimeCacheReadTokens', 'reportedLifetimeCacheWriteTokens']) {
+      requireNonNegativeInteger(metrics[counter], `${path}.${counter}`);
+    }
+    if (typeof metrics.lifetimeTokenBreakdownComplete !== 'boolean') {
+      throw new FlexHarnessStoreFormatError(`${path}.lifetimeTokenBreakdownComplete must be boolean.`);
+    }
+  }
 }
 
+const sessionMetricsBreakdownKeys = [
+  'reportedLifetimeInputTokens', 'reportedLifetimeCacheReadTokens', 'reportedLifetimeCacheWriteTokens',
+  'lifetimeTokenBreakdownComplete',
+];
+
 export function assertFlexProjectionSnapshotV3(
   value: unknown,
 ): asserts value is IFlexProjectionSnapshotV3 {

package/ts/utils.sessionmetrics.ts

@@ -12,6 +12,11 @@ export interface ISessionMetricsOperation {
   reportedTokensExact: boolean;
   complete: boolean;
   sawCall: boolean;
+  inputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+  /** No breakdown sum saturated. */
+  breakdownExact: boolean;
   lastObservedInputTokens?: number;
   lastObservedInputTokensAt?: string;
 }
@@ -20,6 +25,10 @@ export const createSessionMetricsState = (complete: boolean): IFlexSessionMetric
   reportedLifetimeUsedTokens: 0,
   reportedLifetimeUsedTokensExact: true,
   lifetimeUsageComplete: complete,
+  reportedLifetimeInputTokens: 0,
+  reportedLifetimeCacheReadTokens: 0,
+  reportedLifetimeCacheWriteTokens: 0,
+  lifetimeTokenBreakdownComplete: complete,
 });
 
 export const createSessionMetricsOperation = (
@@ -27,6 +36,7 @@ export const createSessionMetricsOperation = (
   source: ISessionMetricsOperation['source'],
 ): ISessionMetricsOperation => ({
   id, source, reportedTokens: 0, reportedTokensExact: true, complete: true, sawCall: false,
+  inputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0, breakdownExact: true,
 });
 
 const isTokenCount = (value: unknown): value is number =>
@@ -60,6 +70,13 @@ export function observeSessionMetricsCall(
   const sum = addTokens(operation.reportedTokens, usage.totalTokens);
   operation.reportedTokens = sum.tokens;
   operation.reportedTokensExact &&= sum.exact;
+  const input = addTokens(operation.inputTokens, usage.inputTokens);
+  const cacheRead = addTokens(operation.cacheReadTokens, usage.cacheReadTokens);
+  const cacheWrite = addTokens(operation.cacheWriteTokens, usage.cacheWriteTokens);
+  operation.inputTokens = input.tokens;
+  operation.cacheReadTokens = cacheRead.tokens;
+  operation.cacheWriteTokens = cacheWrite.tokens;
+  operation.breakdownExact &&= input.exact && cacheRead.exact && cacheWrite.exact;
   if (operation.source === 'generation' && call.usageComplete !== false) {
     operation.lastObservedInputTokens = usage.inputTokens;
     operation.lastObservedInputTokensAt = new Date().toISOString();
@@ -79,6 +96,15 @@ export function settleSessionMetricsOperation(
     && metrics.reportedLifetimeUsedTokensExact
     // An arbitrary compactor may make uninstrumented calls. No report is not proof of zero spend.
     && (operation.source === 'generation' || operation.sawCall);
+  // Metrics written before the breakdown was counted start it now, short of the calls before.
+  const input = addTokens(metrics.reportedLifetimeInputTokens ?? 0, operation.inputTokens);
+  const cacheRead = addTokens(metrics.reportedLifetimeCacheReadTokens ?? 0, operation.cacheReadTokens);
+  const cacheWrite = addTokens(metrics.reportedLifetimeCacheWriteTokens ?? 0, operation.cacheWriteTokens);
+  metrics.lifetimeTokenBreakdownComplete = (metrics.lifetimeTokenBreakdownComplete ?? false)
+    && operation.breakdownExact && input.exact && cacheRead.exact && cacheWrite.exact;
+  metrics.reportedLifetimeInputTokens = input.tokens;
+  metrics.reportedLifetimeCacheReadTokens = cacheRead.tokens;
+  metrics.reportedLifetimeCacheWriteTokens = cacheWrite.tokens;
   if (operation.lastObservedInputTokens !== undefined) {
     metrics.lastObservedInputTokens = operation.lastObservedInputTokens;
     metrics.lastObservedInputTokensAt = operation.lastObservedInputTokensAt;
@@ -95,6 +121,10 @@ export function sessionMetricsView(metrics: IFlexSessionMetricsState): IFlexSess
     lifetimeUsageComplete,
     inFlight,
     ...(lifetimeUsageComplete ? { lifetimeUsedTokens: metrics.reportedLifetimeUsedTokens } : {}),
+    reportedLifetimeInputTokens: metrics.reportedLifetimeInputTokens ?? 0,
+    reportedLifetimeCacheReadTokens: metrics.reportedLifetimeCacheReadTokens ?? 0,
+    reportedLifetimeCacheWriteTokens: metrics.reportedLifetimeCacheWriteTokens ?? 0,
+    lifetimeTokenBreakdownComplete: lifetimeUsageComplete && metrics.lifetimeTokenBreakdownComplete === true,
     ...(metrics.lastObservedInputTokens === undefined ? {} : {
       lastObservedInputTokens: metrics.lastObservedInputTokens,
       lastObservedInputTokensAt: metrics.lastObservedInputTokensAt,

package/ts_mcp/index.ts

@@ -27,22 +27,32 @@ export interface IMcpServerClientOptions {
   requestOptions?: plugins.RequestOptions;
 }
 
-export interface IMcpStdioServerConfig extends plugins.StdioServerParameters, IMcpServerClientOptions {
+export interface IMcpServerTrustOptions {
+  /**
+   * Trusts the server's `readOnlyHint` annotations: `isReadOnlyToolCall` classifies a call of a tool
+   * the server annotates `readOnlyHint: true` as read-only. An annotation is the server's own claim,
+   * so no server's is trusted unless its configuration says so. Default: false.
+   */
+  trustReadOnlyHints?: boolean;
+}
+
+export interface IMcpStdioServerConfig
+  extends plugins.StdioServerParameters, IMcpServerClientOptions, IMcpServerTrustOptions {
   type: 'stdio';
 }
 
-export interface IMcpStreamableHttpServerConfig extends IMcpServerClientOptions {
+export interface IMcpStreamableHttpServerConfig extends IMcpServerClientOptions, IMcpServerTrustOptions {
   type: 'streamableHttp' | 'http';
   url: string | URL;
   transportOptions?: plugins.StreamableHTTPClientTransportOptions;
 }
 
-export interface IMcpTransportServerConfig extends IMcpServerClientOptions {
+export interface IMcpTransportServerConfig extends IMcpServerClientOptions, IMcpServerTrustOptions {
   type: 'transport';
   transport: plugins.Transport;
 }
 
-export interface IMcpClientServerConfig {
+export interface IMcpClientServerConfig extends IMcpServerTrustOptions {
   type: 'client';
   client: IMcpClientLike;
 }
@@ -86,6 +96,8 @@ export interface IMcpConnectedServer {
   name: string;
   client: IMcpClientLike;
   tools: TMcpToolMetadata[];
+  /** Whether its configuration trusts the server's `readOnlyHint` annotations. */
+  trustReadOnlyHints: boolean;
 }
 
 export interface IMcpToolNameMapping {
@@ -97,6 +109,12 @@ export interface ICreateMcpToolsResult {
   tools: plugins.ToolSet;
   servers: IMcpConnectedServer[];
   toolNameMap: Record<string, IMcpToolNameMapping>;
+  /**
+   * Whether a call of `tools` only reads: its server's configuration trusts `readOnlyHint`, and the
+   * server annotates the tool `readOnlyHint: true`. Every other call is not read-only. Pass it as the
+   * tool handle's `isReadOnlyToolCall`, or ask it from that classifier.
+   */
+  isReadOnlyToolCall: (call: { toolName: string }) => boolean;
   close: () => Promise<void>;
 }
 
@@ -113,7 +131,12 @@ export const createMcpTools = async (
   try {
     for (const [serverName, config] of serverEntries) {
       const client = await connectMcpServer(serverName, config, options);
-      const connectedServer: IMcpConnectedServer = { name: serverName, client, tools: [] };
+      const connectedServer: IMcpConnectedServer = {
+        name: serverName,
+        client,
+        tools: [],
+        trustReadOnlyHints: config.trustReadOnlyHints === true,
+      };
       connectedServers.push(connectedServer);
       connectedServer.tools = await listAllMcpTools(
         client,
@@ -124,68 +147,41 @@ export const createMcpTools = async (
 
     const exposedTools: plugins.ToolSet = {};
     const toolNameMap: Record<string, IMcpToolNameMapping> = {};
-    const usedToolNames = new Set<string>(['invalid']);
-    const formatResult = options.formatResult ?? formatMcpToolResult;
+    const readOnlyToolNames = new Set<string>();
     const shouldPrefixToolNames = options.prefixToolNames ?? connectedServers.length > 1;
 
-    for (const server of connectedServers) {
-      for (const mcpTool of server.tools) {
-        const baseToolName = createExposedToolName(server.name, mcpTool.name, shouldPrefixToolNames);
-        const exposedToolName = createUniqueToolName(baseToolName, usedToolNames);
-        usedToolNames.add(exposedToolName);
-        toolNameMap[exposedToolName] = {
+    for (const { server, tool: mcpTool, exposedToolName } of nameMcpTools(connectedServers, shouldPrefixToolNames)) {
+      toolNameMap[exposedToolName] = {
+        serverName: server.name,
+        toolName: mcpTool.name,
+      };
+      if (server.trustReadOnlyHints && mcpTool.annotations?.readOnlyHint === true) {
+        readOnlyToolNames.add(exposedToolName);
+      }
+
+      exposedTools[exposedToolName] = plugins.tool({
+        description: mcpTool.description ?? `MCP tool ${mcpTool.name} from ${server.name}`,
+        inputSchema: plugins.jsonSchema(mcpTool.inputSchema as never),
+        execute: async (input: unknown, invocationOptions?: plugins.ToolExecutionOptions<unknown>) => callMcpTool({
           serverName: server.name,
           toolName: mcpTool.name,
-        };
-
-        exposedTools[exposedToolName] = plugins.tool({
-          description: mcpTool.description ?? `MCP tool ${mcpTool.name} from ${server.name}`,
-          inputSchema: plugins.jsonSchema(mcpTool.inputSchema as never),
-          execute: async (input: unknown, invocationOptions?: plugins.ToolExecutionOptions<unknown>) => {
-            const normalizedArguments = normalizeMcpArguments(input);
-            await options.authorizeToolCall?.({
-              serverName: server.name,
-              toolName: mcpTool.name,
-              exposedToolName,
-              arguments: normalizedArguments,
-              tool: mcpTool,
-              toolCallId: invocationOptions?.toolCallId ?? '',
-              abortSignal: invocationOptions?.abortSignal,
-            });
-            const configuredCallToolOptions: plugins.RequestOptions = {
-              ...options.requestOptions,
-              ...options.callToolRequestOptions,
-            };
-            const result = await withMcpRequestOptions(
-              configuredCallToolOptions,
-              invocationOptions?.abortSignal,
-              (requestOptions) => server.client.callTool(
-                {
-                  name: mcpTool.name,
-                  arguments: normalizedArguments,
-                },
-                undefined,
-                requestOptions,
-              ),
-            );
-            const formattedResult = formatResult(result, {
-              serverName: server.name,
-              toolName: mcpTool.name,
-              exposedToolName,
-            });
-            if ((result as Record<string, unknown>).isError === true) {
-              throw new Error(formatMcpError(formattedResult));
-            }
-            return formattedResult;
-          },
-        });
-      }
+          tool: mcpTool,
+          exposedToolName,
+          arguments: normalizeMcpArguments(input),
+          toolCallId: invocationOptions?.toolCallId ?? '',
+          abortSignal: invocationOptions?.abortSignal,
+          authorize: (context) => options.authorizeToolCall?.(context),
+          client: () => server.client,
+          options,
+        }),
+      });
     }
 
     return {
       tools: exposedTools,
       servers: connectedServers,
       toolNameMap,
+      isReadOnlyToolCall: ({ toolName }) => readOnlyToolNames.has(toolName),
       close: async () => closeMcpClients(connectedServers),
     };
   } catch (error) {
@@ -197,6 +193,114 @@ export const createMcpTools = async (
   }
 };
 
+/** The tools one MCP server lists, as `listTools` answered them. `IMcpConnectedServer` is one. */
+export interface IMcpToolCatalogServer {
+  name: string;
+  tools: readonly TMcpToolMetadata[];
+}
+
+export interface IMcpToolCatalogToolContext extends IMcpToolFormatContext {
+  tool: TMcpToolMetadata;
+}
+
+/** A catalog call of an MCP tool: the run's `call` context names the scope, session, run and `requestPermission`. */
+export interface IMcpToolCatalogCallContext<TScope = unknown> extends IMcpToolFormatContext {
+  call: plugins.IFlexCatalogRunContext<TScope>;
+}
+
+export interface IMcpToolCatalogAuthorizeToolCallContext<TScope = unknown> extends IMcpAuthorizeToolCallContext {
+  abortSignal: AbortSignal;
+  call: plugins.IFlexCatalogRunContext<TScope>;
+}
+
+export interface ICreateMcpToolCatalogOptions<TScope = unknown> {
+  /** The servers and the tools they list, in the order `createMcpTools` was given them. */
+  servers: readonly IMcpToolCatalogServer[];
+  /**
+   * The client that runs a call: the one connected for the call's run, which `call.provider.runId`
+   * names. The catalog stays the same object across runs; only the clients change.
+   */
+  resolveClient(context: IMcpToolCatalogCallContext<TScope>): IMcpClientLike | PromiseLike<IMcpClientLike>;
+  /** As for `createMcpTools`: `<server>__<tool>`, by default when there is more than one server. */
+  prefixToolNames?: boolean;
+  requestOptions?: plugins.RequestOptions;
+  callToolRequestOptions?: plugins.RequestOptions;
+  formatResult?: (result: TMcpCallToolResult, context: IMcpToolFormatContext) => unknown;
+  /**
+   * Resolve to allow the call, or throw to deny it, before the client is resolved. It sees `execute`
+   * and `run_code` calls as `createMcpTools`' hook sees tool calls. Omission allows all calls.
+   */
+  authorizeToolCall?: (context: IMcpToolCatalogAuthorizeToolCallContext<TScope>) => PromiseLike<void> | void;
+  /**
+   * Declares a tool's method read-only: its calls run concurrently with other reads and a turn
+   * answers identical ones once. A tool whose calls ask for permission must not be. Omission
+   * declares none; a server's `readOnlyHint` annotation is not trusted for it.
+   */
+  isReadOnly?: (context: IMcpToolCatalogToolContext) => boolean;
+}
+
+export interface ICreateMcpToolCatalogResult<TScope = unknown> {
+  catalog: plugins.IFlexToolCatalog<TScope>;
+  /** The server and tool of each method path. */
+  toolNameMap: Record<string, IMcpToolNameMapping>;
+}
+
+/**
+ * The MCP tools of `servers` as a tool catalog, which the model searches, describes and calls through
+ * `execute` and `run_code`. A method's path is the name `createMcpTools` gives the tool; a name that
+ * is no identifier (with `-`, or a reserved word) is declared as `FlexToolCatalog.identifierOf()`
+ * makes it. Create one catalog per set of tool definitions and return the same object on every run.
+ */
+export const createMcpToolCatalog = <TScope = unknown>(
+  options: ICreateMcpToolCatalogOptions<TScope>,
+): ICreateMcpToolCatalogResult<TScope> => {
+  if (typeof options?.resolveClient !== 'function') {
+    throw new Error('createMcpToolCatalog requires resolveClient().');
+  }
+  const shouldPrefixToolNames = options.prefixToolNames ?? options.servers.length > 1;
+  const named = nameMcpTools(options.servers, shouldPrefixToolNames);
+  // A name that is an identifier is its path; a mapped one gets a path no such name has.
+  const usedPaths = new Set(named.map(({ exposedToolName }) => exposedToolName)
+    .filter((exposedToolName) => catalogPathOf(exposedToolName) === exposedToolName));
+  const toolNameMap: Record<string, IMcpToolNameMapping> = {};
+  const methods: plugins.IFlexCatalogMethod<TScope, Record<string, unknown>>[] = [];
+  for (const { server, tool: mcpTool, exposedToolName } of named) {
+    const identifier = catalogPathOf(exposedToolName);
+    const path = identifier === exposedToolName ? identifier : createUniqueToolName(identifier, usedPaths);
+    usedPaths.add(path);
+    toolNameMap[path] = { serverName: server.name, toolName: mcpTool.name };
+    const toolContext: IMcpToolCatalogToolContext = {
+      serverName: server.name,
+      toolName: mcpTool.name,
+      exposedToolName: path,
+      tool: mcpTool,
+    };
+    const text = mcpTool.description?.trim() || `MCP tool ${mcpTool.name} from ${server.name}`;
+    const summary = summaryOf(text);
+    const description = text === summary ? undefined : truncateUtf8(text, plugins.FLEX_TOOL_CATALOG_LIMITS.maxDescriptionBytes);
+    methods.push({
+      method: path,
+      summary,
+      ...(description ? { description } : {}),
+      inputSchema: mcpTool.inputSchema,
+      ...(options.isReadOnly?.(toolContext) ? { readOnly: true } : {}),
+      run: (params, call) => callMcpTool({
+        serverName: server.name,
+        toolName: mcpTool.name,
+        tool: mcpTool,
+        exposedToolName: path,
+        arguments: normalizeMcpArguments(params),
+        toolCallId: call.toolCallId,
+        abortSignal: call.abortSignal,
+        authorize: (context) => options.authorizeToolCall?.({ ...context, abortSignal: call.abortSignal, call }),
+        client: () => options.resolveClient({ serverName: server.name, toolName: mcpTool.name, exposedToolName: path, call }),
+        options,
+      }),
+    });
+  }
+  return { catalog: { methods }, toolNameMap };
+};
+
 export const sanitizeMcpToolName = (name: string, fallback = 'mcp_tool'): string => {
   const sanitized = name
     .trim()
@@ -283,7 +387,15 @@ const createMcpTransport = (
   config: Exclude<TMcpServerConfig, IMcpClientServerConfig>,
 ): plugins.Transport => {
   if (config.type === 'stdio') {
-    const { type, clientName, clientVersion, clientOptions, requestOptions, ...serverParameters } = config;
+    const {
+      type,
+      clientName,
+      clientVersion,
+      clientOptions,
+      requestOptions,
+      trustReadOnlyHints,
+      ...serverParameters
+    } = config;
     return new plugins.StdioClientTransport(serverParameters);
   }
 
@@ -340,6 +452,100 @@ const normalizeMaxListToolsPages = (maxPages = DEFAULT_MAX_LIST_TOOLS_PAGES): nu
   return maxPages;
 };
 
+/** Every tool of `servers` with the name it is exposed under, unique across them, in order. */
+const nameMcpTools = <TServer extends IMcpToolCatalogServer>(
+  servers: readonly TServer[],
+  prefixToolNames: boolean,
+): Array<{ server: TServer; tool: TMcpToolMetadata; exposedToolName: string }> => {
+  const usedToolNames = new Set<string>(['invalid']);
+  const named: Array<{ server: TServer; tool: TMcpToolMetadata; exposedToolName: string }> = [];
+  for (const server of servers) {
+    for (const mcpTool of server.tools) {
+      const exposedToolName = createUniqueToolName(
+        createExposedToolName(server.name, mcpTool.name, prefixToolNames),
+        usedToolNames,
+      );
+      usedToolNames.add(exposedToolName);
+      named.push({ server, tool: mcpTool, exposedToolName });
+    }
+  }
+  return named;
+};
+
+interface IMcpToolCall extends IMcpToolFormatContext {
+  tool: TMcpToolMetadata;
+  arguments: Record<string, unknown>;
+  toolCallId: string;
+  abortSignal?: AbortSignal;
+  authorize: (context: IMcpAuthorizeToolCallContext) => PromiseLike<void> | void;
+  client: () => IMcpClientLike | PromiseLike<IMcpClientLike>;
+  options: Pick<ICreateMcpToolsOptions, 'requestOptions' | 'callToolRequestOptions' | 'formatResult'>;
+}
+
+/** Authorizes a call, runs it on the client and formats its result; an MCP error result throws. */
+const callMcpTool = async (call: IMcpToolCall): Promise<unknown> => {
+  await call.authorize({
+    serverName: call.serverName,
+    toolName: call.toolName,
+    exposedToolName: call.exposedToolName,
+    arguments: call.arguments,
+    tool: call.tool,
+    toolCallId: call.toolCallId,
+    abortSignal: call.abortSignal,
+  });
+  const client = await call.client();
+  const configuredCallToolOptions: plugins.RequestOptions = {
+    ...call.options.requestOptions,
+    ...call.options.callToolRequestOptions,
+  };
+  const result = await withMcpRequestOptions(
+    configuredCallToolOptions,
+    call.abortSignal,
+    (requestOptions) => client.callTool(
+      {
+        name: call.toolName,
+        arguments: call.arguments,
+      },
+      undefined,
+      requestOptions,
+    ),
+  );
+  const formattedResult = (call.options.formatResult ?? formatMcpToolResult)(result, {
+    serverName: call.serverName,
+    toolName: call.toolName,
+    exposedToolName: call.exposedToolName,
+  });
+  if ((result as Record<string, unknown>).isError === true) {
+    throw new Error(formatMcpError(formattedResult));
+  }
+  return formattedResult;
+};
+
+/** A catalog method path: the exposed name where it is an identifier, else the identifier made of it. */
+const catalogPathOf = (exposedToolName: string): string => plugins.FlexToolCatalog.identifierOf(exposedToolName);
+
+/** The first line of a description, as one line of at most the catalog's summary length. */
+const summaryOf = (text: string): string => {
+  const line = text.split(/\r?\n/).find((candidate) => candidate.trim())!.replace(/[\s\u0000-\u001f\u007f]+/g, ' ').trim();
+  const characters = [...line];
+  const max = plugins.FLEX_TOOL_CATALOG_LIMITS.maxSummaryCharacters;
+  return characters.length <= max ? line : `${characters.slice(0, max - 1).join('').trimEnd()}…`;
+};
+
+/** The text cut to at most `maxBytes` UTF-8 bytes on a character boundary, marked with `…` when cut. */
+const truncateUtf8 = (text: string, maxBytes: number): string => {
+  const encoder = new TextEncoder();
+  if (encoder.encode(text).length <= maxBytes) return text;
+  let bytes = encoder.encode('…').length;
+  let kept = '';
+  for (const character of text) {
+    bytes += encoder.encode(character).length;
+    if (bytes > maxBytes) break;
+    kept += character;
+  }
+  return `${kept}…`;
+};
+
 const createExposedToolName = (
   serverName: string,
   toolName: string,

package/ts_mcp/plugins.ts

@@ -10,6 +10,12 @@ export type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol
 export type { RequestOptions } from '@modelcontextprotocol/sdk/shared/protocol.js';
 export type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js';
 
+// @modelprofile.com scope
+import { FLEX_TOOL_CATALOG_LIMITS, FlexToolCatalog } from '@modelprofile.com/flexharness';
+
+export { FLEX_TOOL_CATALOG_LIMITS, FlexToolCatalog };
+export type { IFlexCatalogMethod, IFlexCatalogRunContext, IFlexToolCatalog } from '@modelprofile.com/flexharness';
+
 // ai-sdk core
 import { jsonSchema, tool } from 'ai';
 

package/ts_mcp/readme.md

@@ -8,6 +8,18 @@ the agent and harness do not install or register vendor SDKs.
 pnpm add @modelprofile.com/flexharness @modelcontextprotocol/sdk
 ```
 
+`createMcpTools()` connects MCP servers and exposes their tools as AI SDK tools.
+Its `isReadOnlyToolCall` is the tool handle's classifier for them: a call is read-only when the
+server annotates its tool `readOnlyHint: true` and the server's configuration sets
+`trustReadOnlyHints: true`, so those reads run concurrently. No server's annotations are trusted
+by default; `servers` carries each server's `trustReadOnlyHints`.
+`createMcpToolCatalog()` makes the tools servers list into a FlexHarness tool catalog
+(`search_tools`, `describe_tools`, `execute`, `run_code`): one catalog object for every
+run, each call on the client `resolveClient` names for its run, method paths equal to
+`createMcpTools()`' tool names, `authorizeToolCall` deciding catalog calls as it decides
+tool calls, and read-only methods only where `isReadOnly` declares them. The root readme's
+Tool Catalog section shows a tool provider that connects clients per run.
+
 See the [toolbox usage and migration guide](https://code.foss.global/modelprofile.com/flexharness#readme)
 for composition examples and the SmartAI/SmartAgent migration map.
 

package/ts_tools/index.ts

@@ -9,7 +9,7 @@ export type {
   IToolExecutionContextLease,
 } from './plugins.js';
 export type { ICreateBrowserToolsOptions } from './tool.browser.js';
-export { createFilesystemTools } from './tool.filesystem.js';
+export { createFilesystemTools, isReadOnlyFilesystemToolCall } from './tool.filesystem.js';
 export type { ICreateFilesystemToolsOptions } from './tool.filesystem.js';
 export { createShellTools } from './tool.shell.js';
 export type { ICreateShellToolsOptions } from './tool.shell.js';

package/ts_tools/readme.md

@@ -15,6 +15,8 @@ for composition examples and the SmartAI/SmartAgent migration map.
 
 `createFilesystemTools(context, options)` exposes `read_file`, `write_file`, `list_directory` and, unless `includeDelete: false`, `delete_file` over the context's `fs`. `write_file` and `delete_file` ask `context.requestPermission` (`write`, `delete`) before they change anything.
 
+`isReadOnlyFilesystemToolCall({ toolName })` is true for `read_file` and `list_directory`, which change nothing and ask for no permission. Pass it as the FlexHarness tool handle's `isReadOnlyToolCall`, or ask it from that classifier, and their calls run concurrently; leave it out for a context whose `fs.readFile` or `fs.listDirectory` changes something or asks for permission.
+
 `includeEdit: true` adds `edit_file { path, find, replace, replaceAll? }`. It replaces one exact occurrence of `find`, or every occurrence with `replaceAll`, and refuses a `find` that does not occur or, without `replaceAll`, occurs more than once. The replacement text is literal. It asks for `write` permission before it reads the file, so an edit made while the request waits is kept. It is off by default, so the tools an existing agent sees do not change.
 
 ```typescript

package/ts_tools/tool.filesystem.ts

@@ -15,6 +15,18 @@ export interface ICreateFilesystemToolsOptions {
   maxBytes?: number;
 }
 
+/** The tools of `createFilesystemTools()` that only read. */
+const readOnlyFilesystemToolNames: ReadonlySet<string> = new Set(['read_file', 'list_directory']);
+
+/**
+ * Whether a call of `createFilesystemTools()`' tools only reads: `read_file` and `list_directory`
+ * change nothing and ask for no permission. Pass it as the tool handle's `isReadOnlyToolCall`, or ask
+ * it from that classifier, when the context's `fs.readFile` and `fs.listDirectory` do neither either.
+ */
+export function isReadOnlyFilesystemToolCall(call: { toolName: string }): boolean {
+  return readOnlyFilesystemToolNames.has(call.toolName);
+}
+
 export function createFilesystemTools(context: IToolExecutionContext, options: ICreateFilesystemToolsOptions = {}): plugins.ToolSet {
   const truncate = (output: unknown) => plugins.truncateOutput(formatToolOutput(output), {
     maxLines: options.maxLines,