@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 +2 -2
- package/esm/mod.js +2 -2
- package/esm/src/guardrails/tool-result.d.ts +10 -9
- package/esm/src/guardrails/tool-result.js +8 -7
- package/esm/src/interface/blocks.js +1 -0
- package/esm/src/interface/types.d.ts +2 -0
- package/esm/src/kernel/mod.d.ts +2 -2
- package/esm/src/kernel/mod.js +2 -2
- package/esm/src/kernel/tools/agent.js +2 -1
- package/esm/src/kernel/tools/execute.d.ts +0 -7
- package/esm/src/kernel/tools/execute.js +72 -46
- package/esm/src/kernel/tools/handler-events.js +2 -2
- package/esm/src/kernel/tools/image-fetch.js +13 -14
- package/esm/src/kernel/tools/mod.d.ts +2 -1
- package/esm/src/kernel/tools/mod.js +2 -1
- package/esm/src/kernel/tools/operation.js +2 -2
- package/esm/src/kernel/tools/output-parts.d.ts +24 -0
- package/esm/src/kernel/tools/output-parts.js +60 -0
- package/esm/src/kernel/tools/types.d.ts +3 -3
- package/esm/src/kernel/turn-events.d.ts +14 -4
- package/esm/src/kernel/turn-events.js +10 -6
- package/esm/src/kernel/types.d.ts +2 -2
- package/package.json +1 -1
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,
|
|
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,
|
|
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
|
-
/**
|
|
46
|
-
export interface
|
|
47
|
-
/** The value to
|
|
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
|
|
53
|
-
*
|
|
54
|
-
*
|
|
55
|
-
*
|
|
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
|
|
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,
|
|
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
|
|
156
|
-
*
|
|
157
|
-
*
|
|
158
|
-
*
|
|
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
|
|
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,
|
|
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';
|
package/esm/src/kernel/mod.d.ts
CHANGED
|
@@ -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,
|
|
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,
|
|
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';
|
package/esm/src/kernel/mod.js
CHANGED
|
@@ -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,
|
|
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,
|
|
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
|
|
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,
|
|
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 =
|
|
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
|
-
...(
|
|
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
|
|
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
|
|
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
|
|
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 =
|
|
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 {
|
|
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 =
|
|
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,
|
|
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
|
|
148
|
-
if (
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
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,
|
|
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,
|
|
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,
|
|
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(
|
|
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 {
|
|
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
|
-
} |
|
|
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 |
|
|
34
|
-
|
|
35
|
-
|
|
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
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
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.
|
|
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",
|