@theoremjs/agents 0.3.4-next.433.gf6b4da5 → 0.3.4-next.452.gb2a8e30

package/README.md

@@ -460,7 +460,7 @@ Named exports from the root barrel (same symbols hosts get from `@theoremjs/agen
 | Schema | `PROFILE_FIELDS`, `PROFILE_GRAPH`, `PROFILE_TYPES`, `PROFILE_ID_MAX_CHARS`, `PROFILE_HANDLE_MAX_CHARS`, `EXTRA_FIELDS`, `REQUEST_FIELDS`, `API_EXPORTS`, `fieldMeta`, `catalogPathFor`, `DYNAMIC_FIELD_PARENTS`, `spineFacetsForProfileType`, `profileGraphFacet`, `ProfileGraphFacet`, `ProfileGraphFacetId`, `ProfileGraphEditor`, `ProfileGraphRole`, `THINKING_LEVELS`, `KEY_SLOT_NAME`, `isKeySlotName`, `MEDIA_INPUT_KINDS`, `MEDIA_INPUT_KIND_VALUES`, `MEDIA_WILDCARDS`, `ATTACHMENT_ACCEPT_MIMES`, `IMAGE_ATTACHMENT_ACCEPT_MIMES`, `VOICE_ACCEPT_MIMES`, `SUMMARY_MODES`, `STREAM_MODES`, `SPEECH_AUDIO_FORMATS`, `COMPACTION_METERS`, `COMPACTION_OUTCOMES`, `COMPACTION_TIMINGS`, `CACHE_MODES`, `CACHE_TTLS`, `TURN_STAGES`, `TURN_INJECT_STAGES`, `TURN_STOP_KINDS`, `CONTINUE_STOP_KINDS`, `TOOL_GATE_KINDS`, `AWAITING_USER_INPUT_KINDS`, `AWAITING_USER_INPUT_STATUS`, `TOOL_LOAD_TIERS`, `TOOL_ACCESS`, `TOOL_PERMISSION`, `TOOL_TYPES`, `AUTH_UNAUTHENTICATED_POLICIES`, `HTTP_METHODS`, `STUDIO_AUTH_TYPES`, `TOOL_AUTH_TYPES`, `AuthUnauthenticatedPolicy`, `CustomToolType`, `HttpMethod`, `StudioAuthType`, `ToolAccess`, `ToolAuthType`, `ToolPermission`, `ToolType`, `LIVE_ACTIVITY_HANDLINGS`, `LIVE_START_SENSITIVITIES`, `LIVE_END_SENSITIVITIES` |
 | Scope | `KernelScope`, `createKernelScope`, `defaultKernelScope`, `KernelRegistry`, `createKernelRegistry` |
 | Profiles | `ProfileDefinition`, `ProfileDefinitionBase`, `TextProfileDefinition`, `ImageProfileDefinition`, `SpeechProfileDefinition`, `LiveProfileDefinition`, `HostProfileDefinition`, `DecisionProfileDefinition`, `EmbeddingProfileDefinition`, `ProfileRegistry`, `createProfileRegistry`, `clearProfiles`, `defineProfile`, `getProfile`, `hasProfile`, `listProfiles`, `registerProfile`, `registerProfiles`, `projectProfile`, `resolveTurn`, `pickModel` |
-| Tools | `ToolContext`, `GateReference`, `gateReferenceSchema`, `ToolRegistry`, `createToolRegistry`, `registerTool`, `registerTools`, `invokeTool`, `invokeToolStep`, `runTool`, `runToolStep`, `SettledToolCall`, `ToolCallResult`, `ToolStepCallResult`, `GATE_DECISIONS`, `GateDecision`, `askUserTool`, `registerHarnessTools`, `getTool`, `hasTool`, `requireTool`, `listTools`, `resetTools`, `formatToolResult`, `prepareTurnToolSnapshot`, `buildHttpToolTarget`, `executeHttpTool`, `executeMcpTool`, `parseMcpRpcResponse`, `isUnsupportedMcpProtocolError`, `MCP_PROTOCOL_VERSIONS`, `McpProtocolVersion`, `resolveToolAuth`, `credentialPlacement`, `withCredentialQuery`, `CredentialQuery`, `uncheckedOutput`, `UncheckedOutput` |
+| Tools | `ToolContext`, `GateReference`, `gateReferenceSchema`, `ToolRegistry`, `createToolRegistry`, `registerTool`, `registerTools`, `invokeTool`, `invokeToolStep`, `runTool`, `runToolStep`, `SettledToolCall`, `ToolCallResult`, `ToolStepCallResult`, `GATE_DECISIONS`, `GateDecision`, `askUserTool`, `registerHarnessTools`, `getTool`, `hasTool`, `requireTool`, `listTools`, `resetTools`, `formatToolResult`, `prepareTurnToolSnapshot`, `buildHttpToolTarget`, `executeHttpTool`, `executeMcpTool`, `parseMcpRpcResponse`, `isUnsupportedMcpProtocolError`, `MCP_PROTOCOL_VERSIONS`, `mcpRequestMeta`, `McpProtocolVersion`, `resolveToolAuth`, `credentialPlacement`, `withCredentialQuery`, `CredentialQuery`, `uncheckedOutput`, `UncheckedOutput` |
 | Structured | `SchemaRegistry`, `createSchemaRegistry`, `getStructured`, `registerStructured` |
 | Stop / resume | `ProfileTurnBehaviourSpec`, `MediaTurnBehaviourSpec`, `ProfileTurnResumptionSpec`, `TurnContinueFrom`, `TurnStop`, `TurnStopKind`, `ContinueStopKind`, `StepLimitMode`, `CONTINUE_STOP_KINDS`, `AUTO_CONTINUE_DELAY_MS`, `DEFAULT_ALLOW_CONTINUE`, `DEFAULT_AUTO_CONTINUE`, `GenerationStopError`, `isContinueStopKind`, `isGenerationStopError`, `isResumeableStop`, `isUserCancelledStop`, `profileAllowsSteering`, `profileAllowsInject`, `profileTurnResumption`, `shouldAutoContinue`, `turnStopFromClientStreamEnd`, `turnStopFromInteractionStatus`, `turnStopFromOpenAiFinishReason` |
 | Stages (target foundation) | `TURN_STAGES`, `TURN_INJECT_STAGES`, `STAGE_AFFORDANCES`, `STAGE_AFFORDANCE_MATRIX`, `TOOL_GATE_KINDS`, `AWAITING_USER_INPUT_KINDS`, `AWAITING_USER_INPUT_STATUS`, `applyStageResult`, `awaitingUserInputSchema`, `toolGateSchema`, `isTurnStage`, `isTurnInjectStage`, `isToolGateKind`, `isAwaitingUserInput`, `stageAllowsAffordance`, `stageEventFields`, `profileAllowsInject`, `StageAffordance`, `StageContext`, `StageResult`, `StageMutate`, `StageHandler`, `StageApplyInput`, `StageApplyOutput`, `StageApplyWarning`, `StageApplyWarningCode`, `StageEventExtra`, `AwaitingUserInput`, `ToolGate` — contract [`docs/contracts/stages.md`](https://github.com/masudl-hub/theoremai/blob/main/docs/contracts/stages.md) |

package/esm/mod.d.ts

@@ -68,7 +68,7 @@ export { GATE_DECISIONS, type GateDecision } from './src/kernel/tools/gate-answe
 export type { MemoryToolExecutionOptions } from './src/kernel/tools/memory-execution.js';
 export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
 export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './src/kernel/tools/mod.js';
-export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
+export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
 export type { BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, } from './src/kernel/tools/operation.js';
 export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './src/kernel/tools/operation.js';
 export type { SettledToolCall, ToolCallResult, ToolStepCallResult, } from './src/kernel/tools/run.js';

package/esm/mod.js

@@ -42,7 +42,7 @@ export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE,
 export { authorizeToolReplay } from './src/kernel/tools/execute.js';
 export { GATE_DECISIONS } from './src/kernel/tools/gate-answer.js';
 export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
-export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
+export { askUserTool, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
 export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './src/kernel/tools/operation.js';
 export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
 export { buildRecord, clearTraceDestinations, contentOf, getTraceDestination, inlineContent, isTraceSink, listTraceDestinationIds, memorySink, noopSink, readTraceparent, registerTraceDestination, requireTraceDestination, resolveObservabilityPolicy, resolveTraceWriter, startTrace, TRACE_ATTRIBUTE_GROUPS, TRACE_FIELDS, TRACE_SPAN_TYPES, TRACE_STATUS, toOtlpJson, traceAttributeMeta, traceBytes, traceContent, traceEventAttributeMeta, traceEventMeta, traceJson, traceRecordSchema, traceSpanMeta, writeTrace, } from './src/observability/mod.js';

package/esm/src/kernel/mod.d.ts

@@ -63,7 +63,7 @@ export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequ
 export type { MemoryToolExecutionOptions } from './tools/memory-execution.js';
 export { createMemoryToolExecution } from './tools/memory-execution.js';
 export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './tools/mod.js';
-export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
+export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
 export type { BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationUncertainty, } from './tools/operation.js';
 export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './tools/operation.js';
 export { jsonSchemaFromZod } from './tools/schema.js';

package/esm/src/kernel/mod.js

@@ -37,7 +37,7 @@ export { activityLabelProblem } from './tools/activity-label.js';
 export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
 export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
 export { createMemoryToolExecution } from './tools/memory-execution.js';
-export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
+export { askUserTool, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
 export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, } from './tools/operation.js';
 export { jsonSchemaFromZod } from './tools/schema.js';
 export { CredentialRefusedError } from './tools/signed-in-fetch.js';

package/esm/src/kernel/tools/activity-label.js

@@ -196,8 +196,9 @@ function placeholdersAt(node, prefix) {
     const branches = schemaBranches(node);
     if (branches.length)
         return branches.flatMap((branch) => placeholdersAt(branch, prefix));
+    // why: A list's length is a number a label can show, after its first item's fields.
     if (schemaTypes(node).includes('array'))
-        return leavesAt(node.items, at('0'));
+        return [...leavesAt(node.items, at('0')), at('length')];
     if (!isRecord(node.properties))
         return [];
     return Object.entries(node.properties).flatMap(([key, child]) => leavesAt(child, at(key)));
@@ -288,7 +289,12 @@ function placeholderProblem(template, schemas, sides) {
             group: 'is a list or group; a label shows text or a number.', // labels-exempt: builder diagnostic
             flag: 'is true or false; a label shows text or a number.', // labels-exempt: builder diagnostic
         }[found.holds];
-        return `{${path}} ${reason}${tryInstead(near.length ? near : all)}`;
+        // why: What the builder ended the path with (a length, a name) says which of the fields they meant.
+        const last = route.keys.at(-1);
+        const tail = (candidate) => (candidate.split('.').at(-1) === last ? 0 : 1);
+        // why: Not `toSorted`: the studio's declaration build targets a lib before ES2023.
+        const ranked = [...(near.length ? near : all)].sort((a, b) => tail(a) - tail(b));
+        return `{${path}} ${reason}${tryInstead(ranked)}`;
     }
     return undefined;
 }

package/esm/src/kernel/tools/mod.d.ts

@@ -4,7 +4,7 @@ export { formatToolResult } from './model-text.js';
 export type { ToolRegistry } from './registry.js';
 export { createToolRegistry } from './registry.js';
 export type { CredentialQuery, McpProtocolVersion, McpRpcResponse } from './remote.js';
-export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
+export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
 export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
 export type * from './types.js';
 export { UncheckedOutput, uncheckedOutput } from './unchecked-output.js';

package/esm/src/kernel/tools/mod.js

@@ -2,6 +2,6 @@ export { authorizeToolReplay, coerceToolResultParts, executeRegisteredTool, lean
 export { askUserTool, registerHarnessTools } from './harness.js';
 export { formatToolResult } from './model-text.js';
 export { createToolRegistry } from './registry.js';
-export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
+export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
 export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
 export { UncheckedOutput, uncheckedOutput } from './unchecked-output.js';

package/esm/src/kernel/tools/remote.d.ts

@@ -111,6 +111,11 @@ export declare function audienceMismatch(audience: string | undefined, url: URL)
 export declare function executeHttpTool(tool: HttpToolDef, rawInput: unknown, ctx: ToolContext, base: ToolCallBase, stages?: ToolStageSupport, beginBody?: (preparedInput: unknown) => Promise<ToolOperationClaim | undefined>, shown?: HandlerEvents): AsyncGenerator<TurnEvent, ToolBodyOutcome>;
 /** Preferred first. */
 export declare const MCP_PROTOCOL_VERSIONS: readonly ["2026-07-28", "2025-11-25", "2025-06-18", "2025-03-26"];
+/**
+ * The `_meta` an MCP request carries. Stateless servers (2026-07-28) read the client's revision and
+ * capabilities from each request, not from an initialize, and refuse one without both.
+ */
+export declare function mcpRequestMeta(protocolVersion: string): Record<string, unknown>;
 /** An MCP protocol version the client can speak. */
 export type McpProtocolVersion = (typeof MCP_PROTOCOL_VERSIONS)[number];
 /** A JSON-RPC message from an MCP server: a result or an error. */

package/esm/src/kernel/tools/remote.js

@@ -653,6 +653,16 @@ export const MCP_PROTOCOL_VERSIONS = [
     '2025-06-18',
     '2025-03-26',
 ];
+/**
+ * The `_meta` an MCP request carries. Stateless servers (2026-07-28) read the client's revision and
+ * capabilities from each request, not from an initialize, and refuse one without both.
+ */
+export function mcpRequestMeta(protocolVersion) {
+    return {
+        'io.modelcontextprotocol/protocolVersion': protocolVersion,
+        'io.modelcontextprotocol/clientCapabilities': {},
+    };
+}
 /** Accepts a JSON body or an SSE (`data:`) stream. */
 export function parseMcpRpcResponse(text) {
     const trimmed = text.trim();
@@ -717,11 +727,7 @@ async function fetchMcpProtocolAttempt(transport, rpcId, mcpToolName, input, pro
         params: {
             name: mcpToolName,
             arguments: input,
-            // why: Stateless servers read the client's capabilities from each call, not from an initialize.
-            _meta: {
-                'io.modelcontextprotocol/protocolVersion': protocolVersion,
-                'io.modelcontextprotocol/clientCapabilities': {},
-            },
+            _meta: mcpRequestMeta(protocolVersion),
         },
     };
     const response = await fetchGuarded(transport.url, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/agents",
-  "version": "0.3.4-next.433.gf6b4da5",
+  "version": "0.3.4-next.452.gb2a8e30",
   "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
   "keywords": [
     "agent",