@theoremjs/agents 0.3.5-next.919.gc55551d → 0.3.5-next.926.g05c82e3

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/README.md CHANGED
@@ -463,12 +463,12 @@ Named exports from the root barrel (same symbols hosts get from `@theoremjs/agen
463
463
  | 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`, `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` |
464
464
  | Scope | `KernelScope`, `createKernelScope`, `defaultKernelScope`, `KernelRegistry`, `createKernelRegistry` |
465
465
  | Profiles | `ProfileDefinition`, `ProfileDefinitionBase`, `TextProfileDefinition`, `ImageProfileDefinition`, `SpeechProfileDefinition`, `TranscriptionProfileDefinition`, `LiveProfileDefinition`, `HostProfileDefinition`, `DecisionProfileDefinition`, `EmbeddingProfileDefinition`, `ProfileRegistry`, `createProfileRegistry`, `clearProfiles`, `defineProfile`, `getProfile`, `hasProfile`, `listProfiles`, `registerProfile`, `registerProfiles`, `projectProfile`, `resolveTurn`, `pickModel`, `resolveTurnSystemPrompt`, `systemLinesProblem` |
466
- | Tools | `ToolContext`, `GateReference`, `gateReferenceSchema`, `ToolRegistry`, `assertToolSettings`, `createToolRegistry`, `registerTool`, `registerTools`, `invokeTool`, `invokeToolStep`, `runTool`, `runToolStep`, `SettledToolCall`, `ToolCallResult`, `ToolStepCallResult`, `GATE_DECISIONS`, `GateDecision`, `askUserTool`, `registerHarnessTools`, `getTool`, `hasTool`, `requireTool`, `listTools`, `resetTools`, `formatToolResult`, `formatToolFailureForModel`, `prepareTurnToolSnapshot`, `buildHttpToolTarget`, `executeHttpTool`, `executeMcpTool`, `parseMcpRpcResponse`, `isUnsupportedMcpProtocolError`, `MCP_PROTOCOL_VERSIONS`, `mcpRequestMeta`, `McpProtocolVersion`, `resolveToolAuth`, `credentialPlacement`, `withCredentialQuery`, `CredentialQuery`, `uncheckedOutput`, `UncheckedOutput`, `ToolFailed`, `StatedToolFailure`, `McpRpcResponse`, `ModelToolResult`, `PageAnswer` |
466
+ | Tools | `ToolContext`, `GateReference`, `gateReferenceSchema`, `ToolRegistry`, `assertToolSettings`, `createToolRegistry`, `registerTool`, `registerTools`, `invokeTool`, `invokeToolStep`, `runTool`, `runToolStep`, `SettledToolCall`, `ToolCallResult`, `ToolStepCallResult`, `GATE_DECISIONS`, `GateDecision`, `askUserTool`, `registerHarnessTools`, `getTool`, `hasTool`, `requireTool`, `listTools`, `resetTools`, `formatToolResult`, `formatToolFailureForModel`, `prepareTurnToolSnapshot`, `buildHttpToolTarget`, `executeHttpTool`, `executeMcpTool`, `parseMcpRpcResponse`, `isUnsupportedMcpProtocolError`, `MCP_PROTOCOL_VERSIONS`, `mcpRequestMeta`, `McpProtocolVersion`, `resolveToolAuth`, `credentialPlacement`, `withCredentialQuery`, `CredentialQuery`, `uncheckedOutput`, `UncheckedOutput`, `ToolFailed`, `StatedToolFailure`, `McpRpcResponse`, `ModelToolResult`, `PageAnswer`, `ToolMediaEntry` (one entry of an HTTP or MCP tool's media hook) |
467
467
  | Tool execution | `ToolBackground`, `ToolBackgroundCall`, `ToolBackgroundHandle`, `ToolBackgroundService`, `ToolBackgroundSettled`, `ToolSteerReceipt`, `ToolSteerRefusal`, `ToolOperationReply`, `toolOperationReplySchema`, `BackgroundToolEvent`, `ToolExecutionCoordinator`, `createMemoryToolExecution`, `MemoryToolExecutionOptions`, `authorizeToolReplay`, `BeginToolOperationResult`, `ToolOperationClaim`, `ToolOperationIdentity`, `ToolOperationOutcome`, `ToolOperationUncertainty`, `toolOperationOutcomeSchema`, `SavedToolInvocation`, `savedToolInvocationSchema`, `toolInvocationHash`, `TerminalToolEvent`, `PageToolDispatch`, `PageToolExecution` |
468
468
  | Structured | `SchemaRegistry`, `createSchemaRegistry`, `getStructured`, `registerStructured` |
469
469
  | 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` |
470
- | 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) |
471
- | Turn events | `TURN_EVENT_SCHEMAS` (each kind's schema, for a wire parser), `turnEventSchema`, `turnHistoryMessageSchema`, `turnToolSnapshotSchema`, `reasoningPartSchema`, `historyHash`, `turnDoneOf`, `keptReply` (a turn's events without the replies a retry threw away), `z` (the zod these schemas are built with; compose them with it, since two copies of zod do not mix) — the event types themselves come through `export type *` from `src/kernel/types.ts` |
470
+ | 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`, `StageMutateSubject`, `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) |
471
+ | Turn events | `TURN_EVENT_SCHEMAS` (each kind's schema, for a wire parser), `turnEventSchema`, `ToolOutputPart` and `toolOutputPartSchema` (a tool's output parts: what the model reads, what is sent, and references), `turnHistoryMessageSchema`, `turnToolSnapshotSchema`, `reasoningPartSchema`, `historyHash`, `turnDoneOf`, `keptReply` (a turn's events without the replies a retry threw away), `z` (the zod these schemas are built with; compose them with it, since two copies of zod do not mix) — the event types themselves come through `export type *` from `src/kernel/types.ts` |
472
472
  | Observability | `memorySink`, `noopSink`, `readTraceparent`, `writeTrace`, `buildRecord`, `traceRecordSchema`, `contentOf`, `inlineContent`, `toOtlpJson`, `startTrace`, `traceContent`, `traceBytes`, `traceJson`, `registerTraceDestination`, `requireTraceDestination`, `getTraceDestination`, `listTraceDestinationIds`, `clearTraceDestinations`, `isTraceSink`, `resolveTraceWriter`, `resolveObservabilityPolicy`, `traceSpanMeta`, `traceAttributeMeta`, `traceEventMeta`, `traceEventAttributeMeta`, `TRACE_ATTRIBUTE_GROUPS`, `TRACE_STATUS`, `TRACE_FIELDS`, `TRACE_SPAN_TYPES`, `TraceSpanMeta`, `TraceSpanType`, `TraceAttributeMeta`, `TraceEventMeta`, `TraceOptionMeta`, `TraceAttributeGroup`, `TraceValueFormat`, `TraceRecord`, `TraceSink`, `TraceWriteContext`, `TraceSpan`, `TraceSpanEvent`, `TraceSpanKind`, `TraceSpanLink`, `TraceSpanStatus`, `TraceAttributes`, `TraceAttributeValue`, `TraceContent`, `TraceBytes`, `TraceJson`, `TraceTree`, `SpanHandle`, `SpanOptions`, `SpanLinkInput`, `TraceClock`, `ProfileObservabilitySpec`, `ResolvedObservabilityPolicy`, `ResolvedTraceInclude`, `ResolvedTraceScrub`, `TraceIncludeSpec`, `TraceScrubSpec`, `ScrubSwitch`, `ResolvedScrubSwitch`, `OtlpTraceRequest`, `OtlpSpan`, `OtlpKeyValue`, `OtlpAnyValue` (file sink: `@theoremjs/agents/observability/jsonl` → `jsonlSink`, `JsonlSinkOptions`) |
473
473
  | Providers | `registerProvider`, `getProvider`, `listProviders`, `listProtocols`, `createProviderRegistry`, `defineProvider`, `Provider`, `ProviderDefinition`, `Registration`, `RegisteredProvider`, `ProviderRegistry`, `geminiProvider`, `openRouterProvider`, `typesafeProvider`, `localProvider` |
474
474
  | Provider sign-in | `bearer`, `header`, `query`, `Authorize`, `Signer`, `Outgoing`, `Serve`, `endpointUrlSchema` |
package/esm/mod.d.ts CHANGED
@@ -60,7 +60,7 @@ export type { AuthUnauthenticatedPolicy, ContinueStopKind, CustomToolType, HttpM
60
60
  export { API_EXPORTS, ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, DYNAMIC_FIELD_PARENTS, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, KEY_SLOT_NAME, LIVE_ACTIVITY_HANDLINGS, LIVE_END_SENSITIVITIES, LIVE_START_SENSITIVITIES, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, REQUEST_FIELDS, SPEECH_AUDIO_FORMATS, STREAM_MODES, STUDIO_AUTH_TYPES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './src/kernel/schema.js';
61
61
  export type { KernelScope } from './src/kernel/scope.js';
62
62
  export { createKernelScope, defaultKernelScope } from './src/kernel/scope.js';
63
- export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageResult, } from './src/kernel/stages.js';
63
+ export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageMutateSubject, StageResult, } from './src/kernel/stages.js';
64
64
  export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './src/kernel/stages.js';
65
65
  export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './src/kernel/stop.js';
66
66
  export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, } from './src/kernel/stop.js';
@@ -77,8 +77,8 @@ export { askUserTool, assertToolSettings, buildHttpToolTarget, createToolRegistr
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
- export type { ModelToolResult, PageAnswer, ToolContext } from './src/kernel/tools/types.js';
81
- export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
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';
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
@@ -47,6 +47,6 @@ export { GATE_DECISIONS } from './src/kernel/tools/gate-answer.js';
47
47
  export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
48
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';
49
49
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './src/kernel/tools/operation.js';
50
- export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './src/kernel/turn-events.js';
50
+ export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, 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';
@@ -31,10 +31,11 @@ declare function composeToolText(finding: string, data: unknown): string;
31
31
  * Local host tools are still detected — a host tool reading a database returns
32
32
  * data the host did not write — but only remote origins are fenced, because
33
33
  * fencing a local tool's output would change prompts hosts have already tuned.
34
- * `boundary` is absent for text that crosses none: a provider builtin's, or a
35
- * failure already read at its own boundary, whose findings come in as `carried`.
34
+ * `boundary` is absent for text that crosses none: a provider builtin's. `read` is `'data'` for a
35
+ * failure: its message was read at the boundary already and framed by the kernel, so only its
36
+ * details are read here, and the message's findings come in as `carried`.
36
37
  */
37
- declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, callableTools?: readonly string[], labels?: LabelOverrides, carried?: GuardrailHit[]): GuardedToolText;
38
+ declare function guardToolResult(finding: string, data: unknown, provenance: Provenance, policy: ResolvedGuardrailPolicy, boundary: ToolBoundary | undefined, callableTools?: readonly string[], labels?: LabelOverrides, carried?: GuardrailHit[], read?: 'all' | 'data'): GuardedToolText;
38
39
  /**
39
40
  * A remote server authors its own error strings, so an unguarded failure message
40
41
  * is the cleanest injection path across this boundary: it reaches the model
@@ -104,12 +104,15 @@ function suspiciousHits(hits, provenance) {
104
104
  * Local host tools are still detected — a host tool reading a database returns
105
105
  * data the host did not write — but only remote origins are fenced, because
106
106
  * fencing a local tool's output would change prompts hosts have already tuned.
107
- * `boundary` is absent for text that crosses none: a provider builtin's, or a
108
- * failure already read at its own boundary, whose findings come in as `carried`.
107
+ * `boundary` is absent for text that crosses none: a provider builtin's. `read` is `'data'` for a
108
+ * failure: its message was read at the boundary already and framed by the kernel, so only its
109
+ * details are read here, and the message's findings come in as `carried`.
109
110
  */
110
- function guardToolResult(finding, data, provenance, policy, boundary, callableTools = [], labels, carried = []) {
111
- const composed = composeToolText(finding, data);
112
- const detected = readAt(composed, boundary, policy.detect, { callable: callableTools });
111
+ function guardToolResult(finding, data, provenance, policy, boundary, callableTools = [], labels, carried = [], read = 'all') {
112
+ const head = read === 'data' ? finding : '';
113
+ const composed = composeToolText(read === 'data' ? '' : finding, data);
114
+ const scanned = readAt(composed, boundary, policy.detect, { callable: callableTools });
115
+ const detected = scanned.text === undefined ? scanned : { ...scanned, text: `${head}${scanned.text}` };
113
116
  const remote = isRemoteOrigin(provenance.origin);
114
117
  const suspicious = [...carried, ...suspiciousHits(detected.hits, provenance)];
115
118
  const event = detected.action === 'allow'
@@ -1,7 +1,6 @@
1
1
  import { keptReply } from '../kernel/turn-events.js';
2
2
  import { partialJsonObject } from '../kernel/util/partial-json.js';
3
3
  import { applyToolDraft, applyToolEvent } from './tool-calls.js';
4
- import { collectPromotedMediaFromToolOutput } from './tool-media.js';
5
4
  let turnBlockCounter = 0;
6
5
  /**
7
6
  * User block ids are random: a counter restarts wherever this module loads
@@ -136,22 +135,6 @@ function foldCitation(blocks, event, idPrefix) {
136
135
  ...(event.callId !== undefined ? { callId: event.callId } : {}),
137
136
  });
138
137
  }
139
- function appendPromotedToolMedia(blocks, tool, idPrefix, seenUrls) {
140
- if (tool.phase !== 'complete' || tool.output === undefined)
141
- return;
142
- for (const media of collectPromotedMediaFromToolOutput(tool.output)) {
143
- if (seenUrls.has(media.url))
144
- continue;
145
- seenUrls.add(media.url);
146
- blocks.push({
147
- id: nextBlockId(idPrefix),
148
- kind: 'media',
149
- mimeType: media.mimeType,
150
- url: media.url,
151
- ...(media.previewUrl ? { previewUrl: media.previewUrl } : {}),
152
- });
153
- }
154
- }
155
138
  /**
156
139
  * A named inject's user messages as the user's own blocks, where the reply took them in: its
157
140
  * text, then a block per file. A message from anyone else (a host's note) is not the user's to show.
@@ -256,7 +239,9 @@ function standaloneBlock(event, idPrefix) {
256
239
  }
257
240
  }
258
241
  /**
259
- * The media a tool returned beside its output, where the call stands in the reply.
242
+ * The media a tool returned beside its output, where the call stands in the reply: bytes, `sent`
243
+ * when the tool sent them to the person, and references, always sent and kept as `uri` for the
244
+ * app's resolver.
260
245
  * why: a tool sends a picture when it runs, so the picture comes before what the model says next.
261
246
  */
262
247
  function appendToolParts(blocks, tool, idPrefix) {
@@ -269,7 +254,10 @@ function appendToolParts(blocks, tool, idPrefix) {
269
254
  id: nextBlockId(idPrefix),
270
255
  kind: 'media',
271
256
  mimeType: part.mimeType,
272
- ...('data' in part ? { data: part.data } : { url: part.uri }),
257
+ fromTool: true,
258
+ ...('data' in part
259
+ ? { data: part.data, ...(part.sent ? { sent: true } : {}) }
260
+ : { uri: part.uri, type: part.type, sent: true }),
273
261
  });
274
262
  }
275
263
  }
@@ -279,7 +267,6 @@ function foldTurnEvents(events, options = {}) {
279
267
  const showThoughts = options.showThoughts ?? true;
280
268
  turnBlockCounter = 0;
281
269
  const blocks = [];
282
- const promotedMediaUrls = new Set();
283
270
  for (const event of keptReply(events)) {
284
271
  switch (event.type) {
285
272
  case 'thought':
@@ -297,7 +284,6 @@ function foldTurnEvents(events, options = {}) {
297
284
  break;
298
285
  case 'tool':
299
286
  upsertToolBlock(blocks, event.tool);
300
- appendPromotedToolMedia(blocks, event.tool, idPrefix, promotedMediaUrls);
301
287
  appendToolParts(blocks, event.tool, idPrefix);
302
288
  break;
303
289
  case 'structured_draft':
@@ -27,7 +27,5 @@ export { stopText, WORDED_STOP_KINDS } from './stop.js';
27
27
  export type { SettledToolCallEvent } from './tool-calls.js';
28
28
  export { argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
29
29
  export { promotedToolIdsFromEvents, type ReplyCarried, replyCarriedFromEvents, toolSnapshotFromEvents, } from './tool-invoke.js';
30
- export type { PromotedToolMedia } from './tool-media.js';
31
- export { collectPromotedMediaFromToolOutput, promotedMediaFromUrlString, } from './tool-media.js';
32
30
  export type { AttachmentValidationResult, ComposerInterfaceFields, ComposerProfileInterface, FoldTurnEventsOptions, ImageProfileInterface, LiveProfileInterface, ModelBindingView, PendingAttachment, ProfileGuardrailsView, ProfileInputsInterface, ProfileInterface, ProfileObservabilityView, ProfileOutputsView, ProfileToolsView, SpeechProfileInterface, TextProfileInterface, TranscriptBlock, TranscriptBlockKind, TranscriptionProfileInterface, UserTurnDraft, } from './types.js';
33
31
  export { streamThoughtsEnabled } from './types.js';
@@ -18,5 +18,4 @@ export { applyTurnEventsToSession, awaitingFromEvents, branchInterfaceTurnSessio
18
18
  export { stopText, WORDED_STOP_KINDS } from './stop.js';
19
19
  export { argumentsSoFar, settlesToolCall, toolCallRanWith, toolCallsOf } from './tool-calls.js';
20
20
  export { promotedToolIdsFromEvents, replyCarriedFromEvents, toolSnapshotFromEvents, } from './tool-invoke.js';
21
- export { collectPromotedMediaFromToolOutput, promotedMediaFromUrlString, } from './tool-media.js';
22
21
  export { streamThoughtsEnabled } from './types.js';
@@ -3,6 +3,7 @@ import type { DetectAction, DetectMatrix, Detector, UrlDetector } from '../guard
3
3
  import type { GuardrailEvent } from '../guardrails/event-schemas.js';
4
4
  import type { LabelOverrides } from '../guardrails/labels.js';
5
5
  import type { ResolvedGuardrailPolicy } from '../guardrails/types.js';
6
+ import type { MediaInputKind } from '../kernel/schema.js';
6
7
  import type { ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
7
8
  import type { ReasoningPart } from '../kernel/turn-events.js';
8
9
  import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOptions, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TranscriptionProfile, TurnStop, TurnTokens } from '../kernel/types.js';
@@ -203,12 +204,19 @@ export interface StructuredBlock extends TranscriptBlockBase {
203
204
  export interface MediaBlock extends TranscriptBlockBase {
204
205
  kind: 'media';
205
206
  mimeType: string;
206
- /** Base64 for media a model generated, a tool returned or a person attached. Absent when `url` is set. */
207
+ /** Base64 for media a model generated, a tool returned or a person attached. Absent when `uri` is set. */
207
208
  data?: string;
208
- /** Remote URL from completed tool output or a tool's media part. Absent when `data` is set. */
209
- url?: string;
210
- /** A smaller copy of `url` for previews, when the tool output offered one. */
211
- previewUrl?: string;
209
+ /**
210
+ * A reference a tool returned, `{ type, mimeType, uri }`. The model never read it, and it is
211
+ * never a `src` itself: only what the app's own resolver makes of it is shown. Absent when `data` is set.
212
+ */
213
+ uri?: string;
214
+ /** The kind of media `uri` names, as the tool gave it. */
215
+ type?: MediaInputKind;
216
+ /** A tool returned it, rather than a model generating it or a person attaching it. */
217
+ fromTool?: true;
218
+ /** The tool sent it to the person: a reference always is; media bytes when the tool said `sent: true`. */
219
+ sent?: true;
212
220
  }
213
221
  export interface GroundingBlock extends TranscriptBlockBase {
214
222
  kind: 'grounding';
@@ -323,8 +323,7 @@ export const FIELD_DOCS = {
323
323
  'registerTool.headers': "Headers sent with every request to the tool's own origin, never once a redirect leaves it.",
324
324
  'registerTool.hostFields': 'Fields on an agent tool that only the host reads. The calling model fills them, or the host does when a field is marked exposeToModel: false. onAgentCall gets them as hostInput and turns them into what the agent is sent; the agent never sees them. A name the input already has is refused when the tool registers.',
325
325
  'registerTool.hostOnly': 'Channels the called profile takes that the calling model cannot fill on an agent tool; only onAgentCall sends them. A channel the profile does not take is refused when the tool registers.',
326
- 'registerTool.imageLimits': 'How many of those pictures the kernel fetches, how large, and how slowly.',
327
- 'registerTool.images': 'The https addresses of pictures in the output the model should see. The kernel fetches each one through the profile network policy, without the tool credentials.',
326
+ 'registerTool.imageLimits': 'How many of the pictures `media` names the kernel fetches, how large, and how slowly.',
328
327
  'registerTool.input': "The Zod schema for the tool's arguments, sent to the model and checked on every call.",
329
328
  'registerTool.inputSchema': "The tool's arguments as a JSON Schema, sent to the model.",
330
329
  'registerTool.labels': "Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label is dropped. A label is one line, or a list read top to bottom: the first line that fits is shown. A line fits when each {path} has a value and its condition holds, as in 'when status is archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in words. The last line of a list must always fit.",
@@ -341,6 +340,7 @@ export const FIELD_DOCS = {
341
340
  'registerTool.maxCallsPerTurn': 'How many times one turn of the calling agent may run this tool.',
342
341
  'registerTool.maxResponseBytes': 'The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with response_too_large.',
343
342
  'registerTool.mcpToolName': "The tool's name on the MCP server.",
343
+ 'registerTool.media': 'The media in the output: pictures the model should see, and references the person is shown.',
344
344
  'registerTool.method': 'The HTTP method; every method but GET sends a JSON body.',
345
345
  'registerTool.name': "The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model calls a custom tool by.",
346
346
  'registerTool.output': "The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is not checked.",
@@ -55,7 +55,7 @@ export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, StudioAuthT
55
55
  export { API_EXPORTS, ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, REQUEST_FIELDS, SPEECH_AUDIO_FORMATS, STREAM_MODES, STUDIO_AUTH_TYPES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
56
56
  export type { KernelScope } from './scope.js';
57
57
  export { createKernelScope, defaultKernelScope } from './scope.js';
58
- export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageResult, } from './stages.js';
58
+ export type { AwaitingUserInput, StageAffordance, StageApplyInput, StageApplyOutput, StageApplyWarning, StageApplyWarningCode, StageContext, StageEventExtra, StageHandler, StageMutate, StageMutateSubject, StageResult, } from './stages.js';
59
59
  export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
60
60
  export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
61
61
  export { AUTO_CONTINUE_DELAY_MS, CONTINUE_INSTRUCTION_TYPES, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE, GenerationStopError, isContinueStopKind, isGenerationStopError, isResumeableStop, isUserCancelledStop, profileAllowsInject, profileAllowsSteering, profileTurnResumption, shouldAutoContinue, turnStopFromClientStreamEnd, } from './stop.js';
@@ -76,8 +76,8 @@ export type { BackgroundToolEvent, BeginToolOperationResult, PageToolDispatch, P
76
76
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './tools/operation.js';
77
77
  export { jsonSchemaFromZod } from './tools/schema.js';
78
78
  export { CredentialRefusedError } from './tools/signed-in-fetch.js';
79
- export type { ModelToolResult, PageAnswer, ToolAuthConfig, ToolContext, ToolLabels, } from './tools/types.js';
80
- export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
79
+ export type { ModelToolResult, PageAnswer, ToolAuthConfig, ToolContext, ToolLabels, ToolMediaEntry, } from './tools/types.js';
80
+ export { awaitingUserInputSchema, type GateReference, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, type ToolOutputPart, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
81
81
  export type * from './types.js';
82
82
  export { base64ToBytes, bytesToBase64 } from './util/base64.js';
83
83
  export type { Equals } from './util/exact-type.js';
@@ -46,6 +46,6 @@ export { askUserTool, assertToolSettings, authorizeToolReplay, coerceToolResultP
46
46
  export { savedToolInvocationSchema, toolInvocationHash, toolOperationOutcomeSchema, toolOperationReplySchema, } from './tools/operation.js';
47
47
  export { jsonSchemaFromZod } from './tools/schema.js';
48
48
  export { CredentialRefusedError } from './tools/signed-in-fetch.js';
49
- export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
49
+ export { awaitingUserInputSchema, gateReferenceSchema, isAwaitingUserInput, keptReply, reasoningPartSchema, TURN_EVENT_SCHEMAS, toolGateSchema, toolOutputPartSchema, turnDoneOf, turnEventSchema, turnHistoryMessageSchema, turnToolSnapshotSchema, } from './turn-events.js';
50
50
  export { base64ToBytes, bytesToBase64 } from './util/base64.js';
51
51
  export { isRecord } from './util/record.js';
@@ -951,7 +951,7 @@ export const EXTRA_FIELDS = withFieldDocs({
951
951
  unset: 'The model can',
952
952
  },
953
953
  'registerTool.sources': field('(output) => Source[]'),
954
- 'registerTool.images': field('(output) => string[]'),
954
+ 'registerTool.media': field('(output) => ToolMediaEntry[]'),
955
955
  'registerTool.imageLimits': {
956
956
  ...field('ToolImageLimits'),
957
957
  unset: 'No limit',
@@ -91,7 +91,17 @@ export interface StageResult {
91
91
  confirm?: true | {
92
92
  summary?: string;
93
93
  };
94
- /** `pre_tool`: replace the call input. `post_tool`: replace the raw output. Both re-validate. */
94
+ /**
95
+ * Rewrites what the call has at this stage.
96
+ * - `pre_tool`: `{ input }` replaces the call input, which is validated again.
97
+ * - `post_tool` on a completed call: `{ output }` replaces the raw output, which is validated
98
+ * again.
99
+ * - `post_tool` on a failed call: `{ details }` replaces `failure.details`, a JSON object. The
100
+ * code, kind and message stay. To keep the old details, spread `ctx.failure.details` into the
101
+ * new ones. The model reads the new details, and the guardrails read them first.
102
+ *
103
+ * Any other key at a fire is a `mutate_invalid` warning, and nothing changes.
104
+ */
95
105
  mutate?: StageMutate;
96
106
  /**
97
107
  * `post_tool` only: the call completed, but show its failed label (`activityFailed`) on the
@@ -111,12 +121,19 @@ export interface StageResult {
111
121
  */
112
122
  end?: true;
113
123
  }
114
- /** A rewrite of a tool call's input or output. */
124
+ /** A rewrite of a tool call's input, its output, or its failure's details. */
115
125
  export type StageMutate = {
116
126
  input: unknown;
117
127
  } | {
118
128
  output: unknown;
129
+ } | {
130
+ details: Record<string, unknown>;
119
131
  };
132
+ /**
133
+ * What `mutate` rewrites at one stage fire: a `pre_tool` call's `input`, a completed call's
134
+ * `output`, or a failed call's `details`.
135
+ */
136
+ export type StageMutateSubject = 'input' | 'output' | 'details';
120
137
  /** A host function the turn calls at each stage. */
121
138
  export type StageHandler = (ctx: StageContext) => StageResult | undefined | Promise<StageResult | undefined>;
122
139
  export type { StageApplyWarning, StageApplyWarningCode };
@@ -127,11 +144,10 @@ export interface StageApplyInput {
127
144
  injectAllowed: boolean;
128
145
  injectWouldExceedMaxSteps?: boolean;
129
146
  /**
130
- * False when the stage's mutate subject is absent at this fire (a `post_tool`
131
- * whose body never completed, or a tool whose output the kernel must own).
132
- * `mutate` is then a `mutate_invalid` warning, never a silent no-op.
147
+ * What `mutate` rewrites at this fire. Absent when there is nothing to rewrite (a call whose
148
+ * output the kernel owns): `mutate` is then a `mutate_invalid` warning, never a silent no-op.
133
149
  */
134
- mutable?: boolean;
150
+ mutates?: StageMutateSubject;
135
151
  /** True on a text turn's tool step, the only place `end` has a turn to end. */
136
152
  endAllowed?: boolean;
137
153
  }
@@ -199,7 +215,7 @@ export interface RunStageArgs extends StageCallBag {
199
215
  guardrails: Profile['guardrails'];
200
216
  injectAllowed: boolean;
201
217
  injectWouldExceedMaxSteps?: boolean;
202
- mutable?: boolean;
218
+ mutates?: StageMutateSubject;
203
219
  endAllowed?: boolean;
204
220
  host?: unknown;
205
221
  signal?: AbortSignal;
@@ -5,6 +5,7 @@ import { resolveGuardrailPolicy } from '../guardrails/policy.js';
5
5
  import { requestRefused, sanitizeHistory } from '../guardrails/sanitize.js';
6
6
  import { guardrailAttributes } from './engine/turn-trace.js';
7
7
  import { hookFailed } from './hook-failure.js';
8
+ import { jsonValueSchema } from './json.js';
8
9
  import { isRecord } from './util/record.js';
9
10
  /**
10
11
  * What a stage handler can ask for: inject messages, abort, deny a tool call, ask for
@@ -255,10 +256,8 @@ function applyEndField(result, input, out) {
255
256
  out.end = true;
256
257
  }
257
258
  }
258
- const MUTATE_SUBJECT = { pre_tool: 'input', post_tool: 'output' };
259
- function mutateSubject(stage) {
260
- return stage in MUTATE_SUBJECT ? MUTATE_SUBJECT[stage] : undefined;
261
- }
259
+ /** Why a `post_tool` fire takes only `subject`, for a warning that says so. */
260
+ const MUTATE_FIRE = { input: '', output: ': the call completed', details: ': the call failed' }; // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
262
261
  function applyMutateField(result, input, out) {
263
262
  const { stage } = input;
264
263
  if (!('mutate' in result) || result.mutate === undefined)
@@ -267,28 +266,33 @@ function applyMutateField(result, input, out) {
267
266
  warn(out.warnings, 'affordance_not_allowed', 'mutate', `mutate is not allowed at stage ${stage}`);
268
267
  return;
269
268
  }
270
- const subject = mutateSubject(stage);
269
+ const subject = input.mutates;
271
270
  if (!subject) {
272
- // why: Matrix allows mutate but no subject is mapped: a kernel drift, surfaced not swallowed.
273
271
  warn(out.warnings, 'mutate_invalid', 'mutate',
274
272
  // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
275
- `no mutate subject is defined at stage ${stage}`);
273
+ `there is nothing to replace at this ${stage} fire`);
276
274
  return;
277
275
  }
278
- if (!isRecord(result.mutate) || result.mutate[subject] === undefined) {
276
+ const mutate = result.mutate;
277
+ if (!isRecord(mutate) || mutate[subject] === undefined) {
278
+ const shape = subject === 'details' ? '{ details: { … } }' : `{ ${subject}: unknown }`;
279
279
  warn(out.warnings, 'mutate_invalid', 'mutate',
280
280
  // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
281
- `mutate must be { ${subject}: unknown } at stage ${stage}`);
281
+ `mutate must be ${shape} at this ${stage} fire${MUTATE_FIRE[subject]}`);
282
282
  return;
283
283
  }
284
- if (input.mutable === false) {
285
- warn(out.warnings, 'mutate_invalid', 'mutate',
286
- // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
287
- `there is no ${subject} to replace at this ${stage} fire`);
284
+ if (subject === 'details') {
285
+ const details = mutate.details;
286
+ if (!isRecord(details) || !jsonValueSchema.safeParse(details).success) {
287
+ warn(out.warnings, 'mutate_invalid', 'mutate',
288
+ // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
289
+ 'mutate.details must be a JSON object');
290
+ return;
291
+ }
292
+ out.mutate = { details };
288
293
  return;
289
294
  }
290
- out.mutate =
291
- subject === 'input' ? { input: result.mutate.input } : { output: result.mutate.output };
295
+ out.mutate = subject === 'input' ? { input: mutate.input } : { output: mutate.output };
292
296
  }
293
297
  /** Never throws: invalid fields become warnings and are dropped. */
294
298
  export function applyStageResult(input) {
@@ -426,7 +430,7 @@ async function applyHandlers(handlers, ctx, apply, signal) {
426
430
  }
427
431
  /** Stage events always emit, even with no handlers. */
428
432
  export async function* runStage(args) {
429
- const { stage, step, history, handlers, guardrails, injectAllowed, injectWouldExceedMaxSteps, mutable, endAllowed, host, signal, span, ...bag } = args;
433
+ const { stage, step, history, handlers, guardrails, injectAllowed, injectWouldExceedMaxSteps, mutates, endAllowed, host, signal, span, ...bag } = args;
430
434
  throwIfAborted(signal);
431
435
  // why: Stream stage events stay lean (no outputRaw/failure). Hosts read those on
432
436
  // StageContext via onStage; tool failures also ride tool events.
@@ -444,7 +448,13 @@ export async function* runStage(args) {
444
448
  }
445
449
  const ctx = { stage, step, history, host, ...bag };
446
450
  const startedMs = span?.msSinceStart();
447
- const { parts, crashes } = await applyHandlers(handlers, ctx, { stage, injectAllowed, injectWouldExceedMaxSteps, mutable, endAllowed }, signal);
451
+ const { parts, crashes } = await applyHandlers(handlers, ctx, {
452
+ stage,
453
+ injectAllowed,
454
+ injectWouldExceedMaxSteps,
455
+ ...(mutates ? { mutates } : {}),
456
+ endAllowed,
457
+ }, signal);
448
458
  if (stage === 'pre_tool' && crashes.length > 0) {
449
459
  span?.event('theorem.stage', { stage, affordance: [] });
450
460
  return { warnings: [], inject: [], crashed: { error: crashes[0] } };
@@ -1,7 +1,8 @@
1
1
  import { z } from 'zod';
2
2
  import { TheoremError } from '../../guardrails/error.js';
3
+ import { mediaKindForMime } from '../registry/catalog.js';
3
4
  import { optionValues } from '../registry/options.js';
4
- import { interactionPartSchema, keptReply, sourceSchema } from '../turn-events.js';
5
+ import { keptReply, sourceSchema, toolOutputPartSchema } from '../turn-events.js';
5
6
  import { findLast } from '../util/find-last.js';
6
7
  import { profileToolAllow } from './resolve.js';
7
8
  /** The agents an agent tool can run: each has a turn that takes text, which a transcription turn does not. */
@@ -109,7 +110,7 @@ const agentToolOutput = z.object({
109
110
  removed: z
110
111
  .array(z.object({ path: z.string(), reason: z.string(), item: z.unknown() }))
111
112
  .optional(),
112
- parts: z.array(interactionPartSchema).optional(),
113
+ parts: z.array(toolOutputPartSchema).optional(),
113
114
  sources: z.array(sourceSchema).optional(),
114
115
  });
115
116
  function profileTakesText(profile) {
@@ -181,9 +182,11 @@ function agentToolOutputOf(turn) {
181
182
  const parts = events.flatMap((e) => e.type === 'media'
182
183
  ? [
183
184
  {
184
- type: e.media.mimeType.startsWith('audio/') ? 'audio' : 'image',
185
+ type: mediaKindForMime(e.media.mimeType) ?? 'document',
185
186
  mimeType: e.media.mimeType,
186
187
  data: e.media.data,
188
+ // why: The called agent made it to be seen, as a top-level agent's own media is shown.
189
+ sent: true,
187
190
  },
188
191
  ]
189
192
  : []);
@@ -5,7 +5,8 @@ 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 { InteractionPart, Profile, TurnEvent } from '../types.js';
8
+ import { type ToolOutputPart } from '../turn-events.js';
9
+ import type { Profile, TurnEvent } from '../types.js';
9
10
  import { type AgentCaller } from './agent.js';
10
11
  import { type ToolBackgroundSupport } from './background.js';
11
12
  import { startToolExecution, type ToolCallBase } from './events.js';
@@ -20,8 +21,12 @@ export declare function originOfTool(tool: RegisteredTool, tools: ToolRegistry):
20
21
  * whose text the kernel never reads. A call no tool takes is read as a function tool's.
21
22
  */
22
23
  export declare function toolArgumentsBoundary(tools: ToolRegistry, name: string): ToolBoundary | undefined;
23
- /** Invalid entries are dropped. */
24
- export declare function coerceToolResultParts(raw: unknown): InteractionPart[] | 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;
25
30
  /** A tool's output without its `parts` key, which carries media the model receives separately; any other value is returned as it is. */
26
31
  export declare function leanToolResultData(output: unknown): unknown;
27
32
  /** 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. */