@theoremjs/agents 0.3.5-next.945.g127cfdd → 0.3.5-next.947.ga93f6be

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/esm/mod.d.ts CHANGED
@@ -73,12 +73,12 @@ export { GATE_DECISIONS, type GateDecision } from './src/kernel/tools/gate-answe
73
73
  export type { MemoryToolExecutionOptions } from './src/kernel/tools/memory-execution.js';
74
74
  export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
75
75
  export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './src/kernel/tools/mod.js';
76
- export { askUserTool, assertToolSettings, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
76
+ export { askUserTool, assertToolSettings, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, toolOutputPartSchema, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
77
77
  export type { BackgroundToolEvent, BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationReply, ToolOperationUncertainty, } from './src/kernel/tools/operation.js';
78
78
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './src/kernel/tools/operation.js';
79
79
  export type { SettledToolCall, ToolCallResult, ToolStepCallResult, } from './src/kernel/tools/run.js';
80
80
  export type { ModelToolResult, PageAnswer, ToolContext, ToolMediaEntry, } from './src/kernel/tools/types.js';
81
- export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, type ToolOutputPart, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
81
+ export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, type ToolOutputPart, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
82
82
  export type * from './src/kernel/types.js';
83
83
  export type { OtlpAnyValue, OtlpKeyValue, OtlpSpan, OtlpTraceRequest, ProfileObservabilitySpec, ResolvedObservabilityPolicy, ResolvedScrubSwitch, ResolvedTraceInclude, ResolvedTraceScrub, ScrubSwitch, SpanHandle, SpanLinkInput, SpanOptions, TraceAttributeGroup, TraceAttributeMeta, TraceAttributes, TraceAttributeValue, TraceBytes, TraceClock, TraceContent, TraceEventMeta, TraceIncludeSpec, TraceJson, TraceOptionMeta, TraceRecord, TraceScrubSpec, TraceSink, TraceSpan, TraceSpanEvent, TraceSpanKind, TraceSpanLink, TraceSpanMeta, TraceSpanStatus, TraceSpanType, TraceTree, TraceValueFormat, TraceWriteContext, } from './src/observability/mod.js';
84
84
  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/mod.js CHANGED
@@ -45,8 +45,8 @@ export { authorizeToolReplay } from './src/kernel/tools/execute.js';
45
45
  export { ToolFailed } from './src/kernel/tools/failed.js';
46
46
  export { GATE_DECISIONS } from './src/kernel/tools/gate-answer.js';
47
47
  export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
48
- export { askUserTool, assertToolSettings, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
48
+ export { askUserTool, assertToolSettings, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, toolOutputPartSchema, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
49
49
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './src/kernel/tools/operation.js';
50
- export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
50
+ export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
51
51
  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';
52
52
  export * from './src/providers/mod.js';
@@ -42,19 +42,20 @@ declare function guardToolResult(finding: string, data: unknown, provenance: Pro
42
42
  * verbatim and is framed by the kernel as a system report.
43
43
  */
44
44
  declare function guardToolFailureText(message: string, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined): GuardedToolText;
45
- /** What a call shows the person of one value, after it was read at `tool_shown_<kind>`. */
46
- export interface ShownToolValue {
47
- /** The value to show: every match set to `redact` replaced. Absent when a match blocks it. */
45
+ /** One value of a call after it was read at its boundary. */
46
+ export interface GuardedToolValue {
47
+ /** The value to pass on: every match set to `redact` replaced. Absent when a match blocks it. */
48
48
  value?: unknown;
49
49
  event?: GuardrailEvent;
50
50
  }
51
51
  /**
52
- * A call's output, error, and trace reach the person on the turn's events, apart from
53
- * what the model read back: the host's server forwards them to the browser as they are. Each is
54
- * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
55
- * untouched: what the model read is settled at `tool_output_<kind>`.
52
+ * A value of a call read whole at `boundary`, each match set to `redact` replaced in the string
53
+ * it sits in. A call's output, error, trace and parts reach the person on the turn's events,
54
+ * apart from what the model read back: the host's server forwards them to the browser as they
55
+ * are, so each is read at `tool_shown_<kind>`. The text parts the model reads beside its
56
+ * read-back are read at `tool_output_<kind>`, with `scope`.
56
57
  */
57
- declare function guardShownValue(value: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined): ShownToolValue;
58
+ declare function guardToolValue(value: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, scope?: DetectScope): GuardedToolValue;
58
59
  /** A tool call's arguments after they were read at their boundary. */
59
60
  export interface InspectedToolArguments {
60
61
  /** The arguments to call the tool with. Absent when a match blocks: the tool is not called. */
@@ -88,4 +89,4 @@ declare function isSuspicious(taint: TurnTaint | undefined): boolean;
88
89
  * or not enforcement is configured, so the risk is visible before a host opts in.
89
90
  */
90
91
  declare function checkTaintGate(taint: TurnTaint | undefined, access: string, policy: ResolvedGuardrailPolicy, labels?: LabelOverrides): Verdict;
91
- export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, };
92
+ export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, guardToolValue, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, };
@@ -152,15 +152,16 @@ function guardToolFailureText(message, provenance, policy, boundary) {
152
152
  };
153
153
  }
154
154
  /**
155
- * A call's output, error, and trace reach the person on the turn's events, apart from
156
- * what the model read back: the host's server forwards them to the browser as they are. Each is
157
- * read here at `tool_shown_<kind>`, so a key a tool returned is not shown. `readBack` is
158
- * untouched: what the model read is settled at `tool_output_<kind>`.
155
+ * A value of a call read whole at `boundary`, each match set to `redact` replaced in the string
156
+ * it sits in. A call's output, error, trace and parts reach the person on the turn's events,
157
+ * apart from what the model read back: the host's server forwards them to the browser as they
158
+ * are, so each is read at `tool_shown_<kind>`. The text parts the model reads beside its
159
+ * read-back are read at `tool_output_<kind>`, with `scope`.
159
160
  */
160
- function guardShownValue(value, provenance, policy, boundary) {
161
+ function guardToolValue(value, provenance, policy, boundary, scope) {
161
162
  if (!boundary || value === undefined)
162
163
  return { value };
163
- const found = readValue(value, boundary, policy.detect);
164
+ const found = readValue(value, boundary, policy.detect, scope);
164
165
  const event = detectEvent(boundary, found, provenance);
165
166
  return {
166
167
  ...(found.action === 'block' ? {} : { value: found.value }),
@@ -279,4 +280,4 @@ function checkTaintGate(taint, access, policy, labels) {
279
280
  rejection: labelText('taint.blocked', { access, sources: read, reason }, labels),
280
281
  };
281
282
  }
282
- export { checkTaintGate, composeToolText, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, };
283
+ export { checkTaintGate, composeToolText, guardToolFailureText, guardToolResult, guardToolValue, inspectToolArguments, isRemoteOrigin, isSuspicious, isTainted, recordTaint, toolCallEvent, wrapToolData, };
@@ -259,6 +259,7 @@ function appendToolParts(blocks, tool, idPrefix) {
259
259
  ...('data' in part
260
260
  ? { data: part.data, ...(part.sent ? { sent: true } : {}) }
261
261
  : { uri: part.uri, type: part.type, sent: true }),
262
+ ...(part.metadata ? { metadata: part.metadata } : {}),
262
263
  });
263
264
  }
264
265
  }
@@ -217,6 +217,8 @@ export interface MediaBlock extends TranscriptBlockBase {
217
217
  fromTool?: true;
218
218
  /** The tool sent it to the person: a reference always is; media bytes when the tool said `sent: true`. */
219
219
  sent?: true;
220
+ /** The tool's own values for the file, as it gave them in the part's `metadata`. */
221
+ metadata?: Record<string, unknown>;
220
222
  }
221
223
  export interface GroundingBlock extends TranscriptBlockBase {
222
224
  kind: 'grounding';
@@ -72,13 +72,13 @@ export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequ
72
72
  export type { MemoryToolExecutionOptions } from './tools/memory-execution.js';
73
73
  export { createMemoryToolExecution } from './tools/memory-execution.js';
74
74
  export type { CredentialQuery, McpProtocolVersion, McpRpcResponse, ToolRegistry, } from './tools/mod.js';
75
- export { askUserTool, assertToolSettings, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
75
+ export { askUserTool, assertToolSettings, authorizeToolReplay, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, toolOutputPartSchema, withCredentialQuery, } from './tools/mod.js';
76
76
  export type { BackgroundToolEvent, BeginToolOperationResult, PageToolDispatch, PageToolExecution, SavedToolInvocation, TerminalToolEvent, ToolExecutionCoordinator, ToolOperationClaim, ToolOperationIdentity, ToolOperationOutcome, ToolOperationReply, ToolOperationUncertainty, } from './tools/operation.js';
77
77
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './tools/operation.js';
78
78
  export { jsonSchemaFromZod } from './tools/schema.js';
79
79
  export { CredentialRefusedError } from './tools/signed-in-fetch.js';
80
80
  export type { ModelToolResult, PageAnswer, ToolAuthConfig, ToolContext, ToolLabels, ToolMediaEntry, } from './tools/types.js';
81
- export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, type ToolOutputPart, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
81
+ export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, type ToolOutputPart, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
82
82
  export type * from './types.js';
83
83
  export { base64ToBytes, bytesToBase64 } from './util/base64.js';
84
84
  export type { Equals } from './util/exact-type.js';
@@ -43,10 +43,10 @@ export { declaredInputSchema } from './tools/call-order.js';
43
43
  export { ToolFailed } from './tools/failed.js';
44
44
  export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
45
45
  export { createMemoryToolExecution } from './tools/memory-execution.js';
46
- export { askUserTool, assertToolSettings, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
46
+ export { askUserTool, assertToolSettings, authorizeToolReplay, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolFailureForModel, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, toolOutputPartSchema, withCredentialQuery, } from './tools/mod.js';
47
47
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './tools/operation.js';
48
48
  export { jsonSchemaFromZod } from './tools/schema.js';
49
49
  export { CredentialRefusedError } from './tools/signed-in-fetch.js';
50
- export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
50
+ export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
51
51
  export { base64ToBytes, bytesToBase64 } from './util/base64.js';
52
52
  export { isRecord } from './util/record.js';
@@ -2,8 +2,9 @@ import { z } from 'zod';
2
2
  import { TheoremError } from '../../guardrails/error.js';
3
3
  import { mediaKindForMime } from '../registry/catalog.js';
4
4
  import { optionValues } from '../registry/options.js';
5
- import { keptReply, sourceSchema, toolOutputPartSchema } from '../turn-events.js';
5
+ import { keptReply, sourceSchema } from '../turn-events.js';
6
6
  import { findLast } from '../util/find-last.js';
7
+ import { toolOutputPartSchema } from './output-parts.js';
7
8
  import { profileToolAllow } from './resolve.js';
8
9
  /** The agents an agent tool can run: each has a turn that takes text, which a transcription turn does not. */
9
10
  const AGENT_TOOL_TYPES = new Set(['text', 'image', 'speech']);
@@ -5,7 +5,6 @@ import type { ToolOrigin } from '../../guardrails/types.js';
5
5
  import type { SpanHandle, TraceAttributes } from '../../observability/trace-span.js';
6
6
  import { type ToolCallEnd } from '../engine/tool-trace.js';
7
7
  import type { InjectUnit } from '../stages.js';
8
- import { type ToolOutputPart } from '../turn-events.js';
9
8
  import type { Profile, TurnEvent } from '../types.js';
10
9
  import { type AgentCaller } from './agent.js';
11
10
  import { type ToolBackgroundSupport } from './background.js';
@@ -21,12 +20,6 @@ export declare function originOfTool(tool: RegisteredTool, tools: ToolRegistry):
21
20
  * whose text the kernel never reads. A call no tool takes is read as a function tool's.
22
21
  */
23
22
  export declare function toolArgumentsBoundary(tools: ToolRegistry, name: string): ToolBoundary | undefined;
24
- /**
25
- * A function tool's `parts` as tool media: text, media bytes (`sent: true` also shows them to the
26
- * person) and references `{ type, mimeType, uri }` the person is shown and the model never reads.
27
- * Invalid entries are dropped.
28
- */
29
- export declare function coerceToolResultParts(raw: unknown): ToolOutputPart[] | undefined;
30
23
  /** A tool's output without its `parts` key, which carries media the model receives separately; any other value is returned as it is. */
31
24
  export declare function leanToolResultData(output: unknown): unknown;
32
25
  /** What the model is told of a function tool's output: a fixed finding for a hidden tool, a finding plus the output for an awaiting-user result, otherwise the tool's own summary or finding and its data. */
@@ -1,14 +1,15 @@
1
+ import { z } from 'zod';
1
2
  import { toolBoundary } from '../../guardrails/boundaries.js';
2
3
  import { checkDestinationGate } from '../../guardrails/destinations.js';
3
4
  import { scopeOf } from '../../guardrails/detect-at.js';
4
5
  import { errorKind, isAbortError, TheoremError, throwIfAborted } from '../../guardrails/error.js';
5
6
  import { labelText } from '../../guardrails/labels.js';
6
7
  import { resolveGuardrailPolicy } from '../../guardrails/policy.js';
7
- import { checkTaintGate, guardShownValue, guardToolFailureText, guardToolResult, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
8
+ import { checkTaintGate, guardToolFailureText, guardToolResult, guardToolValue, inspectToolArguments, toolCallEvent, } from '../../guardrails/tool-result.js';
8
9
  import { recordToolCheck, startToolTrace, } from '../engine/tool-trace.js';
9
10
  import { sumTurnTokens } from '../engine/usage.js';
10
11
  import { jsonObjectSchema } from '../json.js';
11
- import { isAwaitingUserInput } from '../turn-events.js';
12
+ import { isAwaitingUserInput, toolOutputPartRecord, } from '../turn-events.js';
12
13
  import { isRecord } from '../util/record.js';
13
14
  import { fillActivityLabel } from './activity-label.js';
14
15
  import { agentToolOrigin } from './agent.js';
@@ -28,6 +29,7 @@ import { plainToolInput } from './schema.js';
28
29
  import { CredentialRefusedError, signedInFetch } from './signed-in-fetch.js';
29
30
  import { emitGateSettlement, runPostToolStages, runPreToolPipeline, } from './stage-run.js';
30
31
  export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
32
+ import { checkedToolOutputParts, toolOutputPartIssues } from './output-parts.js';
31
33
  import { schemaIssueDetails } from './schema-issues.js';
32
34
  import { UncheckedOutput } from './unchecked-output.js';
33
35
  export function originOfTool(tool, tools) {
@@ -63,43 +65,6 @@ function isStreamHandler(handler) {
63
65
  return (typeof handler === 'function' &&
64
66
  Object.prototype.toString.call(handler) === '[object AsyncGeneratorFunction]');
65
67
  }
66
- const MEDIA_PART_TYPES = new Set(['image', 'audio', 'video', 'document']);
67
- /**
68
- * A function tool's `parts` as tool media: text, media bytes (`sent: true` also shows them to the
69
- * person) and references `{ type, mimeType, uri }` the person is shown and the model never reads.
70
- * Invalid entries are dropped.
71
- */
72
- export function coerceToolResultParts(raw) {
73
- if (!Array.isArray(raw) || raw.length === 0)
74
- return undefined;
75
- const parts = [];
76
- for (const item of raw) {
77
- if (!isRecord(item) || typeof item.type !== 'string')
78
- continue;
79
- if (item.type === 'text' && typeof item.text === 'string') {
80
- parts.push({ type: 'text', text: item.text });
81
- continue;
82
- }
83
- if (!MEDIA_PART_TYPES.has(item.type) ||
84
- typeof item.mimeType !== 'string' ||
85
- !item.mimeType.trim()) {
86
- continue;
87
- }
88
- const type = item.type;
89
- if (typeof item.data === 'string' && item.data.length > 0) {
90
- parts.push({
91
- type,
92
- mimeType: item.mimeType,
93
- data: item.data,
94
- ...(item.sent === true ? { sent: true } : {}),
95
- });
96
- }
97
- else if (typeof item.uri === 'string' && item.uri.length > 0) {
98
- parts.push({ type, mimeType: item.mimeType, uri: item.uri });
99
- }
100
- }
101
- return parts.length > 0 ? parts : undefined;
102
- }
103
68
  /** A tool's output without its `parts` key, which carries media the model receives separately; any other value is returned as it is. */
104
69
  export function leanToolResultData(output) {
105
70
  if (!isRecord(output))
@@ -127,7 +92,7 @@ async function* runHandler(handler, input, ctx, shown) {
127
92
  }
128
93
  /** What the model is told of a function tool's output: a fixed finding for a hidden tool, a finding plus the output for an awaiting-user result, otherwise the tool's own summary or finding and its data. */
129
94
  export function projectForModel(tool, output, labels) {
130
- const media = isRecord(output) ? coerceToolResultParts(output.parts) : undefined;
95
+ const media = checkedToolOutputParts(output);
131
96
  if (tool.exposeToModel === false) {
132
97
  // why: The model reads none of a hidden tool's output, its media included; what it sent, the person is shown.
133
98
  const sent = media?.filter((part) => part.type !== 'text' && ('uri' in part || part.sent));
@@ -257,7 +222,7 @@ function pastActivity(labels, input, output) {
257
222
  return fillActivityLabel(labels?.activityPast, { input, output });
258
223
  }
259
224
  function completeEvent(base, settled) {
260
- const { input, outputRaw, modelResult } = settled;
225
+ const { input, outputRaw, modelResult, parts } = settled;
261
226
  const activityPast = settled.labelFailed
262
227
  ? failedActivityOf(base)
263
228
  : pastActivity(settled.labels, input, outputRaw);
@@ -265,7 +230,7 @@ function completeEvent(base, settled) {
265
230
  phase: 'complete',
266
231
  output: outputRaw,
267
232
  readBack: formatToolResult(modelResult),
268
- ...(modelResult.media?.length ? { parts: modelResult.media } : {}),
233
+ ...(parts.length ? { parts: [...parts] } : {}),
269
234
  ...(modelResult.hidden ? { hidden: true } : {}),
270
235
  ...(activityPast ? { activityPast } : {}),
271
236
  });
@@ -322,6 +287,7 @@ async function* settleToolCall(args) {
322
287
  input,
323
288
  outputRaw: yield* guard.shown(outputRaw),
324
289
  modelResult,
290
+ parts: yield* guard.shownParts(modelResult.media ?? []),
325
291
  labels: args.labels,
326
292
  ...(post?.labelFailed ? { labelFailed: true } : {}),
327
293
  });
@@ -433,6 +399,7 @@ function resultGuard(tools, tool, ctx, snapshot, span) {
433
399
  drafts,
434
400
  };
435
401
  const shown = (value) => showValue(value, inputs);
402
+ const shownParts = (parts) => showParts(parts, inputs);
436
403
  const service = isGateResumeGranted(ctx.resume) ? signInService(tool, ctx.resume) : undefined;
437
404
  if (!service) {
438
405
  return {
@@ -440,6 +407,7 @@ function resultGuard(tools, tool, ctx, snapshot, span) {
440
407
  failure: (failure) => guardFailure(failure, inputs),
441
408
  handlerEvents,
442
409
  shown,
410
+ shownParts,
443
411
  };
444
412
  }
445
413
  const note = labelText('sign_in.done', { service }, ctx.profile.labels);
@@ -448,6 +416,7 @@ function resultGuard(tools, tool, ctx, snapshot, span) {
448
416
  failure: (failure) => afterSignIn(note, guardFailure(failure, inputs)),
449
417
  handlerEvents,
450
418
  shown,
419
+ shownParts,
451
420
  };
452
421
  }
453
422
  /** A call the person signed in for tells the model so before what it read back. */
@@ -475,6 +444,14 @@ async function* runFunctionPreBodyStages(args) {
475
444
  ...(pre.denied ? { denied: true } : {}),
476
445
  });
477
446
  }
447
+ /** `value` checked by the tool's own output schema, then its `parts` by `toolOutputPartSchema`. */
448
+ function checkOutput(tool, value) {
449
+ const checked = tool.output.safeParse(value);
450
+ if (!checked.success)
451
+ return checked;
452
+ const issues = toolOutputPartIssues(checked.data);
453
+ return issues.length > 0 ? { success: false, error: { issues } } : checked;
454
+ }
478
455
  function makeReproject(parse, project, labels) {
479
456
  return (output) => {
480
457
  const checked = parse(output);
@@ -642,7 +619,7 @@ agent, beginBody) {
642
619
  message: labelText('tool.handler_no_output', {}, ctx.profile.labels),
643
620
  });
644
621
  }
645
- const checked = tool.output.safeParse(output);
622
+ const checked = checkOutput(tool, output);
646
623
  if (!checked.success) {
647
624
  return yield* fail({
648
625
  code: 'invalid_output',
@@ -674,7 +651,7 @@ agent, beginBody) {
674
651
  ...(ownsOutput
675
652
  ? {}
676
653
  : {
677
- reproject: makeReproject((v) => tool.output.safeParse(v), (data) => projectForModel(tool, data, ctx.profile.labels), ctx.profile.labels),
654
+ reproject: makeReproject((v) => checkOutput(tool, v), (data) => projectForModel(tool, data, ctx.profile.labels), ctx.profile.labels),
678
655
  }),
679
656
  });
680
657
  }
@@ -1302,16 +1279,65 @@ function* reportFailure(failure, guard, suspicious) {
1302
1279
  }
1303
1280
  /** A result read at `tool_output_<kind>`. A blocked one settles as a failed call the model is told about. */
1304
1281
  function* guardResult(result, guard) {
1305
- const read = yield* readBack(result, guard, guard.kind && toolBoundary('tool_output', guard.kind));
1282
+ const boundary = guard.kind && toolBoundary('tool_output', guard.kind);
1283
+ const texts = yield* readTextParts(result, guard, boundary);
1284
+ const read = texts && (yield* readBack(texts, guard, boundary));
1306
1285
  if (read)
1307
1286
  return { modelResult: read };
1308
1287
  const withheld = blockedOutput(guard);
1309
1288
  return { modelResult: yield* reportFailure(withheld, guard), withheld };
1310
1289
  }
1290
+ /**
1291
+ * `result` with the text parts the model reads beside its read-back read at `boundary`, each
1292
+ * match set to `redact` replaced; `undefined` when a match blocks them.
1293
+ */
1294
+ function* readTextParts(result, guard, boundary) {
1295
+ const media = result.media;
1296
+ if (!media?.some((part) => part.type === 'text'))
1297
+ return result;
1298
+ const texts = media.map((part) => (part.type === 'text' ? part.text : null));
1299
+ const read = guardToolValue(texts, guard.provenance, guard.policy, boundary, {
1300
+ callable: guard.callableTools,
1301
+ });
1302
+ if (read.event)
1303
+ yield { type: 'guardrail', guardrail: read.event };
1304
+ if (!('value' in read))
1305
+ return undefined;
1306
+ const kept = keptTexts.safeParse(read.value);
1307
+ if (!kept.success || kept.data.length !== media.length) {
1308
+ throw new TheoremError('internal', 'A guard changed the shape of the text parts it read'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
1309
+ }
1310
+ const { media: _media, parts: _parts, ...rest } = result;
1311
+ return withMedia(rest, media.map((part, index) => {
1312
+ const text = kept.data[index];
1313
+ return part.type === 'text' && typeof text === 'string' ? { ...part, text } : part;
1314
+ }));
1315
+ }
1316
+ const keptTexts = z.array(z.string().nullable());
1317
+ /** The parts the person is shown, each read without its bytes at `tool_shown_<kind>`; a blocked one is left out. */
1318
+ function* showParts(parts, guard) {
1319
+ const boundary = guard.kind && toolBoundary('tool_shown', guard.kind);
1320
+ const shown = [];
1321
+ for (const part of parts) {
1322
+ // why: bytes are not text the detectors read; every other field of the part is read as it is shown.
1323
+ const { data, ...read } = 'data' in part ? part : { ...part, data: undefined };
1324
+ const checked = guardToolValue(read, guard.provenance, guard.policy, boundary);
1325
+ if (checked.event)
1326
+ yield { type: 'guardrail', guardrail: checked.event };
1327
+ if (!('value' in checked))
1328
+ continue;
1329
+ const kept = toolOutputPartRecord.safeParse(data === undefined || !isRecord(checked.value) ? checked.value : { ...checked.value, data });
1330
+ if (!kept.success) {
1331
+ throw new TheoremError('internal', 'A guard changed the shape of a part it read'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
1332
+ }
1333
+ shown.push(kept.data);
1334
+ }
1335
+ return shown;
1336
+ }
1311
1337
  /** What the person is shown of `value`, read at `tool_shown_<kind>`; a blocked one is the labels' words. */
1312
1338
  function* showValue(value, guard) {
1313
1339
  const boundary = guard.kind && toolBoundary('tool_shown', guard.kind);
1314
- const shown = guardShownValue(value, guard.provenance, guard.policy, boundary);
1340
+ const shown = guardToolValue(value, guard.provenance, guard.policy, boundary);
1315
1341
  if (shown.event)
1316
1342
  yield { type: 'guardrail', guardrail: shown.event };
1317
1343
  return 'value' in shown ? shown.value : labelText('detect.shown_blocked', {}, guard.labels);
@@ -1,5 +1,5 @@
1
1
  import { createDraftGate, DraftReader, } from '../../guardrails/progressive-yield.js';
2
- import { guardShownValue, guardToolResult } from '../../guardrails/tool-result.js';
2
+ import { guardToolResult, guardToolValue } from '../../guardrails/tool-result.js';
3
3
  import { toolEvent } from './events.js';
4
4
  /** A handler's event as the tool phase it is, unchecked. */
5
5
  export function* yieldHandlerSideEvent(base, event) {
@@ -68,7 +68,7 @@ export class HandlerEvents {
68
68
  const checks = this.checks;
69
69
  if (!checks)
70
70
  return { shown: true, value };
71
- const read = guardShownValue(value, checks.provenance, checks.policy, checks.shown);
71
+ const read = guardToolValue(value, checks.provenance, checks.policy, checks.shown);
72
72
  if (read.event)
73
73
  yield { type: 'guardrail', guardrail: read.event };
74
74
  return 'value' in read ? { shown: true, value: read.value } : { shown: false };
@@ -1,8 +1,9 @@
1
1
  import { fetchGuarded } from '../../guardrails/network.js';
2
- import { MEDIA_INPUT_KIND_VALUES } from '../schema.js';
3
2
  import { bytesToBase64 } from '../util/base64.js';
4
3
  import { isRecord } from '../util/record.js';
5
4
  import { toolNetworkPolicy } from './events.js';
5
+ import { toolOutputRefPartSchema } from './output-parts.js';
6
+ import { issuePath } from './schema-issues.js';
6
7
  const IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
7
8
  /** The body, read up to `maxBytes` when set; `undefined` when it runs past. */
8
9
  async function readCappedBytes(response, maxBytes = Number.POSITIVE_INFINITY) {
@@ -90,8 +91,12 @@ export async function fetchToolMedia(hook, output, ctx, limits = {}) {
90
91
  try {
91
92
  for (const entry of hook(output)) {
92
93
  const ref = mediaRef(entry);
94
+ if (ref && 'reason' in ref) {
95
+ reasons.push(ref.reason);
96
+ continue;
97
+ }
93
98
  if (ref) {
94
- refs.push(ref);
99
+ refs.push(ref.ref);
95
100
  continue;
96
101
  }
97
102
  const address = httpsAddress(isRecord(entry) ? entry.url : entry);
@@ -140,22 +145,16 @@ export async function fetchToolMedia(hook, output, ctx, limits = {}) {
140
145
  function sentEntry(entry) {
141
146
  return isRecord(entry) && entry.sent === true;
142
147
  }
143
- /** The entry as a reference, when it is one. */
148
+ /** The entry as a reference, or why it is not one; `undefined` for a picture entry (`url`). */
144
149
  function mediaRef(entry) {
145
150
  if (!isRecord(entry) || 'url' in entry)
146
151
  return undefined;
147
- const { type, mimeType, uri } = entry;
148
- if (typeof type !== 'string' ||
149
- !MEDIA_KINDS.has(type) ||
150
- typeof mimeType !== 'string' ||
151
- !mimeType.trim() ||
152
- typeof uri !== 'string' ||
153
- !uri) {
154
- return undefined;
155
- }
156
- return { type: type, mimeType, uri };
152
+ const ref = toolOutputRefPartSchema.safeParse(entry);
153
+ if (ref.success)
154
+ return { ref: ref.data };
155
+ const issues = ref.error.issues.map((issue) => `${issuePath(issue.path)}: ${issue.message}`);
156
+ return { reason: `a reference that is not a part (${issues.join(', ')})` }; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
157
157
  }
158
- const MEDIA_KINDS = new Set(MEDIA_INPUT_KIND_VALUES);
159
158
  function unfetched(reasons) {
160
159
  return {
161
160
  code: 'images_unfetched',
@@ -1,6 +1,7 @@
1
- export { authorizeToolReplay, coerceToolResultParts, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
1
+ export { authorizeToolReplay, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
2
2
  export { askUserTool, registerHarnessTools } from './harness.js';
3
3
  export { formatToolFailureForModel, formatToolResult } from './model-text.js';
4
+ export { toolOutputPartSchema } from './output-parts.js';
4
5
  export type { ToolRegistry } from './registry.js';
5
6
  export { assertToolSettings, createToolRegistry } from './registry.js';
6
7
  export type { CredentialQuery, McpProtocolVersion, McpRpcResponse } from './remote.js';
@@ -1,6 +1,7 @@
1
- export { authorizeToolReplay, coerceToolResultParts, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
1
+ export { authorizeToolReplay, executeRegisteredTool, leanToolResultData, projectForModel, } from './execute.js';
2
2
  export { askUserTool, registerHarnessTools } from './harness.js';
3
3
  export { formatToolFailureForModel, formatToolResult } from './model-text.js';
4
+ export { toolOutputPartSchema } from './output-parts.js';
4
5
  export { assertToolSettings, createToolRegistry } from './registry.js';
5
6
  export { buildHttpToolTarget, credentialPlacement, executeHttpTool, executeMcpTool, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, resolveToolAuth, withCredentialQuery, } from './remote.js';
6
7
  export { cloneTurnToolSnapshot, prepareTurnToolSnapshot } from './resolve.js';
@@ -2,7 +2,7 @@ import { z } from 'zod';
2
2
  import { TheoremError } from '../../guardrails/error.js';
3
3
  import { errorKindSchema, guardrailHit, provenance } from '../../guardrails/event-schemas.js';
4
4
  import { jsonObjectSchema, jsonValueSchema } from '../json.js';
5
- import { interactionPartSchema, TURN_EVENT_SCHEMAS, toolOutputPartSchema, turnHistoryMessageSchema, } from '../turn-events.js';
5
+ import { interactionPartSchema, TURN_EVENT_SCHEMAS, toolOutputPartRecord, turnHistoryMessageSchema, } from '../turn-events.js';
6
6
  export const savedToolInvocationSchema = z.strictObject({
7
7
  accepted: jsonObjectSchema,
8
8
  preparedInput: jsonValueSchema,
@@ -46,7 +46,7 @@ const modelResultSchema = z.strictObject({
46
46
  finding: z.string(),
47
47
  data: jsonValueSchema.optional(),
48
48
  parts: z.array(interactionPartSchema).optional(),
49
- media: z.array(toolOutputPartSchema).optional(),
49
+ media: z.array(toolOutputPartRecord).optional(),
50
50
  hidden: z.literal(true).optional(),
51
51
  modelText: z.string().optional(),
52
52
  provenance: provenance.optional(),
@@ -0,0 +1,24 @@
1
+ import { z } from 'zod';
2
+ import { type ToolOutputPart } from '../turn-events.js';
3
+ import type { SchemaIssue } from './schema-issues.js';
4
+ /** A reference part: the person is shown it through the app's own resolver. */
5
+ export declare const toolOutputRefPartSchema: z.ZodObject<{
6
+ type: z.ZodEnum<{
7
+ image: "image";
8
+ audio: "audio";
9
+ video: "video";
10
+ document: "document";
11
+ }>;
12
+ mimeType: z.ZodString;
13
+ uri: z.ZodString;
14
+ metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
15
+ }, z.core.$strict>;
16
+ /**
17
+ * A part a tool returns in its `parts`. A field the part does not name, empty bytes or an empty
18
+ * reference fail the call as `invalid_output`, never dropped: put your own values in `metadata`.
19
+ */
20
+ export declare const toolOutputPartSchema: z.ZodType<ToolOutputPart>;
21
+ /** Where an output's `parts` break {@link toolOutputPartSchema}, each issue on its own part's field. */
22
+ export declare function toolOutputPartIssues(output: unknown): SchemaIssue[];
23
+ /** The `parts` of an output whose parts had no {@link toolOutputPartIssues}. */
24
+ export declare function checkedToolOutputParts(output: unknown): ToolOutputPart[] | undefined;
@@ -0,0 +1,60 @@
1
+ import { z } from 'zod';
2
+ import { TheoremError } from '../../guardrails/error.js';
3
+ import { MEDIA_INPUT_KIND_VALUES } from '../schema.js';
4
+ import { toolOutputPartRecord } from '../turn-events.js';
5
+ import { isRecord } from '../util/record.js';
6
+ const mimeType = z.string().regex(/\S/);
7
+ const metadata = z.record(z.string(), z.unknown()).optional();
8
+ const textPart = z.strictObject({ type: z.literal('text'), text: z.string() });
9
+ const mediaPart = z.strictObject({
10
+ type: z.enum(MEDIA_INPUT_KIND_VALUES),
11
+ mimeType,
12
+ data: z.string().min(1),
13
+ sent: z.literal(true).optional(),
14
+ metadata,
15
+ });
16
+ /** A reference part: the person is shown it through the app's own resolver. */
17
+ export const toolOutputRefPartSchema = z.strictObject({
18
+ type: z.enum(MEDIA_INPUT_KIND_VALUES),
19
+ mimeType,
20
+ uri: z.string().min(1),
21
+ metadata,
22
+ });
23
+ const toolOutputPartInput = z.union([textPart, mediaPart, toolOutputRefPartSchema]);
24
+ true;
25
+ /**
26
+ * A part a tool returns in its `parts`. A field the part does not name, empty bytes or an empty
27
+ * reference fail the call as `invalid_output`, never dropped: put your own values in `metadata`.
28
+ */
29
+ export const toolOutputPartSchema = toolOutputPartInput;
30
+ /** The kind of part `value` is meant to be: text, a reference (it names a `uri`), or media bytes. */
31
+ function partShapeOf(value) {
32
+ if (isRecord(value) && value.type === 'text')
33
+ return textPart;
34
+ return isRecord(value) && 'uri' in value ? toolOutputRefPartSchema : mediaPart;
35
+ }
36
+ /** Where an output's `parts` break {@link toolOutputPartSchema}, each issue on its own part's field. */
37
+ export function toolOutputPartIssues(output) {
38
+ if (!isRecord(output) || output.parts === undefined)
39
+ return [];
40
+ const list = z.array(z.unknown()).safeParse(output.parts);
41
+ if (!list.success)
42
+ return list.error.issues.map((issue) => atParts(issue, []));
43
+ return list.data.flatMap((part, index) => {
44
+ const checked = partShapeOf(part).safeParse(part);
45
+ return checked.success ? [] : checked.error.issues.map((issue) => atParts(issue, [index]));
46
+ });
47
+ }
48
+ function atParts(issue, at) {
49
+ return { path: ['parts', ...at, ...issue.path], message: issue.message };
50
+ }
51
+ /** The `parts` of an output whose parts had no {@link toolOutputPartIssues}. */
52
+ export function checkedToolOutputParts(output) {
53
+ if (!isRecord(output) || output.parts === undefined)
54
+ return undefined;
55
+ const parts = z.array(toolOutputPartRecord).safeParse(output.parts);
56
+ if (!parts.success) {
57
+ throw new TheoremError('internal', 'Tool parts were read before they were checked'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
58
+ }
59
+ return parts.data.length > 0 ? parts.data : undefined;
60
+ }
@@ -5,8 +5,8 @@ import type { GuardrailHit, Provenance, TurnTaint } from '../../guardrails/types
5
5
  import type { ToolCredentialSource } from '../auth/credential-source.js';
6
6
  import type { OAuthEndpoints } from '../auth/types.js';
7
7
  import type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolGateKind, ToolLoadTier, ToolPermission, ToolResumeCause } from '../schema.js';
8
- import type { RemovedItem, Source, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolOutputPart, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool } from '../turn-events.js';
9
- import type { InteractionMediaRefPart, InteractionPart, ModelId, Profile, ProfileId, RunControls, ToolId, TurnInput, TurnRequest, TurnSpeech } from '../types.js';
8
+ import type { RemovedItem, Source, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolOutputPart, ToolOutputRefPart, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool } from '../turn-events.js';
9
+ import type { InteractionPart, ModelId, Profile, ProfileId, RunControls, ToolId, TurnInput, TurnRequest, TurnSpeech } from '../types.js';
10
10
  import type { LabelTemplate } from './activity-label.js';
11
11
  import type { ToolBackground, ToolBackgroundService } from './background.js';
12
12
  import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js';
@@ -250,7 +250,7 @@ export interface ToolOutputHooks<TOut = unknown> {
250
250
  export type ToolMediaEntry = {
251
251
  url: string;
252
252
  sent?: true;
253
- } | InteractionMediaRefPart;
253
+ } | ToolOutputRefPart;
254
254
  /** For a tool whose response the builder does not write; a function tool returns its media itself as `parts`. */
255
255
  export interface ToolMediaHooks<TOut = unknown> {
256
256
  /**
@@ -25,15 +25,25 @@ export interface InteractionMediaRefPart {
25
25
  /** A part of a history message: text or media. */
26
26
  export type InteractionPart = InteractionTextPart | InteractionMediaPart | InteractionMediaRefPart;
27
27
  export declare const interactionPartSchema: z.ZodType<InteractionPart>;
28
+ /** Media bytes a tool returned: the model reads them, and `sent` also shows them to the person. */
29
+ export interface ToolOutputMediaPart extends InteractionMediaPart {
30
+ sent?: true;
31
+ /** Your own values, carried with the file to every view and resolver; Theorem does not read them, and the model never sees them. */
32
+ metadata?: Record<string, unknown>;
33
+ }
34
+ /** A reference a tool returned: the person is shown it through the app's own resolver, and the model never reads it. */
35
+ export interface ToolOutputRefPart extends InteractionMediaRefPart {
36
+ /** Your own values, carried with the file to every view and resolver; Theorem does not read them, and the model never sees them. */
37
+ metadata?: Record<string, unknown>;
38
+ }
28
39
  /**
29
40
  * A part of what a tool returned. Text and media bytes are what the model reads; `sent` on media
30
41
  * also shows it to the person. A reference (`uri`) is shown to the person only, through the app's
31
42
  * own resolver: the model never reads it.
32
43
  */
33
- export type ToolOutputPart = InteractionTextPart | (InteractionMediaPart & {
34
- sent?: true;
35
- }) | InteractionMediaRefPart;
36
- export declare const toolOutputPartSchema: z.ZodType<ToolOutputPart>;
44
+ export type ToolOutputPart = InteractionTextPart | ToolOutputMediaPart | ToolOutputRefPart;
45
+ /** Reads a tool output part Theorem recorded; a tool's own output is checked by the stricter `toolOutputPartSchema`. */
46
+ export declare const toolOutputPartRecord: z.ZodType<ToolOutputPart>;
37
47
  /** One message of a conversation history the host replays into a turn. */
38
48
  /** Where a piece of signed reasoning came from. `protocol` decides where it may go back to. */
39
49
  export interface ReasoningOrigin {
@@ -29,13 +29,17 @@ const interactionPart = z.union([
29
29
  ]);
30
30
  true;
31
31
  export const interactionPartSchema = interactionPart;
32
- const toolOutputPart = z.union([
33
- interactionTextPart,
34
- interactionMediaPart.extend({ sent: z.literal(true).optional() }),
35
- interactionMediaRefPart,
36
- ]);
32
+ const toolOutputMediaPart = interactionMediaPart.extend({
33
+ sent: z.literal(true).optional(),
34
+ metadata: jsonObject.optional(),
35
+ });
36
+ true;
37
+ const toolOutputRefPart = interactionMediaRefPart.extend({ metadata: jsonObject.optional() });
38
+ true;
39
+ const toolOutputPart = z.union([interactionTextPart, toolOutputMediaPart, toolOutputRefPart]);
37
40
  true;
38
- export const toolOutputPartSchema = toolOutputPart;
41
+ /** Reads a tool output part Theorem recorded; a tool's own output is checked by the stricter `toolOutputPartSchema`. */
42
+ export const toolOutputPartRecord = toolOutputPart;
39
43
  const reasoningOrigin = z.object({
40
44
  protocol: z.string().min(1),
41
45
  provider: z.string().min(1).optional(),
@@ -6,8 +6,8 @@ import type { ToolBackgroundService } from './tools/background.js';
6
6
  import type { GateDecision } from './tools/gate-answer.js';
7
7
  import type { PageToolExecution, ToolExecutionCoordinator, ToolOperationOutcome } from './tools/operation.js';
8
8
  import type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, HostProfileToolsSpec, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, LiveProfileToolsSpec, ModelToolResult, PageAnswer, ProfileToolsSpec, RegisteredTool, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolMediaEntry, ToolPolicy, TurnToolSnapshot, WireFunctionTool } from './tools/types.js';
9
- import type { AttemptReason, CallDone, CompactionFailure, CompactionResult, CompactionSignal, DoneFields, GroundingEvent, InjectedMessages, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, ModelEvent, ProviderEvidence, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, ToolOutputPart, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnTokenSide, TurnTokens } from './turn-events.js';
10
- export type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, AttemptReason, CallDone, CompactionFailure, CompactionMeter, CompactionOutcome, CompactionResult, CompactionSignal, CompactionTiming, ContinueStopKind, DoneFields, FieldMeta, GroundingEvent, HostProfileToolsSpec, InjectedMessages, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveProfileToolsSpec, LiveStartSensitivity, MediaInputKind, ModelEvent, ProfileToolsSpec, ProfileType, ProviderEvidence, RegisteredTool, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolLoadTier, ToolMediaEntry, ToolOutputPart, ToolPolicy, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnStage, TurnStopKind, TurnTokenSide, TurnTokens, TurnToolSnapshot, WireFunctionTool, };
9
+ import type { AttemptReason, CallDone, CompactionFailure, CompactionResult, CompactionSignal, DoneFields, GroundingEvent, InjectedMessages, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, ModelEvent, ProviderEvidence, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, ToolOutputMediaPart, ToolOutputPart, ToolOutputRefPart, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnTokenSide, TurnTokens } from './turn-events.js';
10
+ export type { AgentCall, AgentCallHook, AgentCallRequest, AgentToolDef, AgentToolInput, AgentToolOutput, AttemptReason, CallDone, CompactionFailure, CompactionMeter, CompactionOutcome, CompactionResult, CompactionSignal, CompactionTiming, ContinueStopKind, DoneFields, FieldMeta, GroundingEvent, HostProfileToolsSpec, InjectedMessages, InteractionMediaPart, InteractionMediaRefPart, InteractionPart, InteractionTextPart, InvalidField, InvokeToolRequest, InvokeToolResume, InvokeToolStepCall, InvokeToolStepRequest, KeySlot, KeyVault, LiveActivityHandling, LiveEndSensitivity, LiveProfileToolsSpec, LiveStartSensitivity, MediaInputKind, ModelEvent, ProfileToolsSpec, ProfileType, ProviderEvidence, RegisteredTool, RemovedItem, SessionEnded, SessionEvent, SessionEventKind, SessionEventOf, Source, SpeechAudioFormat, StreamMode, SummaryMode, ThinkingLevel, ToolCallEvent, ToolFailure, ToolGate, ToolLoadContext, ToolLoadTier, ToolMediaEntry, ToolOutputMediaPart, ToolOutputPart, ToolOutputRefPart, ToolPolicy, TurnCost, TurnEvent, TurnEventOf, TurnEventType, TurnGroundingCount, TurnHistoryMessage, TurnResponse, TurnStage, TurnStopKind, TurnTokenSide, TurnTokens, TurnToolSnapshot, WireFunctionTool, };
11
11
  /** A host-chosen key naming one model binding in a profile's `models`. */
12
12
  export type ModelId = string;
13
13
  /** The id of a provider-side tool such as web search. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.945.g127cfdd",
3
+ "version": "0.3.5-next.947.ga93f6be",
4
4
  "description": "A flat TypeScript agent kernel for typed profiles, deterministic turn execution, registered tools, provider adapters, guardrails, and host-injected traces.",
5
5
  "keywords": [
6
6
  "agent",