@modelprofile.com/flexharness 10.19.0 → 10.21.0

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

@@ -124,62 +124,30 @@ 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 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,
+      };
+
+      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 {
@@ -197,6 +165,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()
@@ -340,6 +416,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,14 @@ 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.
+`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_typedrequest/catalog.ts

@@ -28,7 +28,9 @@ export class FlexTypedRequestError extends Error {
  * The tool catalog of a typedrequest surface: every included method becomes a catalog method of
  * its path, declared as its contract writes it and validated against its schema, and runs through
  * `router.routeAndAddResponse()` in process, its request the model's parameters with the omitted
- * properties `request` fills. A refusal rejects with `FlexTypedRequestError`.
+ * properties `request` fills and its result what `response` makes of the answer. A refusal rejects
+ * with `FlexTypedRequestError`. A method `readOnly` marks is declared read-only and not gated by
+ * `onCall`.
  */
 export function catalogFromTypedRequests<TScope = unknown>(
   surface: IFlexTypedRequestSurface,
@@ -49,6 +51,7 @@ export function catalogFromTypedRequests<TScope = unknown>(
     );
   }
   const include = options.include ?? ((method: IFlexTypedRequestMethod) => !method.deprecated);
+  const readOnly = options.readOnly ?? (() => false);
   const { router } = options;
   const call = async (
     method: IFlexTypedRequestMethod,
@@ -68,7 +71,9 @@ export function catalogFromTypedRequests<TScope = unknown>(
     );
     if (!answer) throw new FlexTypedRequestError(method.method, 'The router answered nothing.');
     if (answer.error) throw new FlexTypedRequestError(method.method, answer.error.text, answer.error.data);
-    return answer.response;
+    return options.response
+      ? await options.response(method, answer.response as Record<string, unknown>, context)
+      : answer.response;
   };
   return {
     methods: surface.methods.filter((method) => include(method)).map((method): IFlexCatalogMethod<TScope> => ({
@@ -80,9 +85,11 @@ export function catalogFromTypedRequests<TScope = unknown>(
       outputSchema: method.outputSchema,
       declaration: method.declaration,
       run: (params: Record<string, unknown>, context) => call(method, params, context),
-      ...(options.onCall
-        ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
-        : {}),
+      ...(readOnly(method)
+        ? { readOnly: true }
+        : options.onCall
+          ? { onCall: (params: Record<string, unknown>, context: IFlexCatalogRunContext<TScope>) => options.onCall!(method, params, context) }
+          : {}),
     })),
     types: surface.types,
     ...(options.vocabulary ? { vocabulary: options.vocabulary } : {}),

package/ts_typedrequest/interfaces.ts

@@ -109,11 +109,31 @@ export interface IFlexTypedRequestCatalogOptions<TScope = unknown> {
   ): Record<string, unknown> | PromiseLike<Record<string, unknown>>;
   /** The methods the model may use. Default: every method that is not deprecated. */
   include?(method: IFlexTypedRequestMethod): boolean;
+  /**
+   * The methods that only read: a call has no effect but its result. Such a method is declared
+   * `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may
+   * start while the model still streams its response, and a turn answers identical ones once; see
+   * `IFlexCatalogMethod.readOnly`. Default: none.
+   */
+  readOnly?(method: IFlexTypedRequestMethod): boolean;
+  /**
+   * What the model sees of a method's answered response, such as the response without a
+   * credential's secret. Default: the response. A refusal does not reach it, and the method's
+   * declaration still shows the contract's response.
+   */
+  response?(
+    method: IFlexTypedRequestMethod,
+    response: Record<string, unknown>,
+    context: IFlexCatalogRunContext<TScope>,
+  ): unknown;
   /** Other names of methods, by typed method: `{ getVoucher: ['Beleg abrufen'] }`. */
   aliases?: Readonly<Record<string, readonly string[]>>;
   /** The words the API's users say for its own words; see `IFlexToolCatalog.vocabulary`. */
   vocabulary?: IFlexToolCatalog['vocabulary'];
-  /** Decides each validated call before it runs; see `IFlexCatalogMethod.onCall`. */
+  /**
+   * Decides each validated call of a method `readOnly` does not mark before it runs; see
+   * `IFlexCatalogMethod.onCall`.
+   */
   onCall?(
     method: IFlexTypedRequestMethod,
     params: Record<string, unknown>,

package/ts_typedrequest/readme.md

@@ -19,7 +19,8 @@ const surface = await describeTypedRequests({
 const catalog = catalogFromTypedRequests<IAppScope>(surface, {
   router: server.typedrouter,
   request: (method, context) => ({ identity: identityOf(context.provider.scope) }),
-  onCall: (method) => (method.method.startsWith('get') || method.method.startsWith('list') ? 'run' : 'propose'),
+  readOnly: (method) => method.method.startsWith('get') || method.method.startsWith('list'),
+  onCall: () => 'propose',
 });
 ```
 
@@ -38,6 +39,8 @@ The surface is plain JSON, so a build step can write it next to the server and t
 - `router` answers the calls: anything with `routeAndAddResponse()`, such as a `TypedRouter` of `@api.global/typedrequest`. A call is routed as a typed request with the model's parameters and what `request` returns for the omitted properties, `localData` as the trusted route data a transport would hand the handlers, and the run's abort signal.
 - A refusal rejects with `FlexTypedRequestError`: the typed method, the error's `text` and `data`, as a client of the API would receive them. A handler's own failure arrives as the router's internal error. A host's `externalErrorProjector` decides what of it the model sees.
 - `include` picks the methods the model may use, by default every method that is not deprecated; `aliases` gives methods other names by typed method; `vocabulary`, `onCall` and `onProposals` are the catalog's own (`onCall` receives the typed method first).
+- `readOnly` marks the methods that only read. A marked method is declared `readOnly` and `onCall` does not decide its calls, so they run concurrently with other reads, may start while the model still streams, and a turn answers identical ones once; every other method's calls, gated by `onCall` or not, run in the order the model made them. Mark nothing that asks for permission.
+- `response` decides what the model sees of an answered response, such as the response without a credential's secret; by default the response itself. A refusal does not reach it, and the method's declaration still shows the contract's response.
 - A surface that omits properties needs `request`; an alias for a method the surface lacks is refused.
 
 ## Issue Reporting and Security