@theoremjs/agents 0.3.5-next.911.g193d75c → 0.3.5-next.912.g25d311a

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,7 +463,7 @@ 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`, `prepareTurnToolSnapshot`, `buildHttpToolTarget`, `executeHttpTool`, `executeMcpTool`, `parseMcpRpcResponse`, `isUnsupportedMcpProtocolError`, `MCP_PROTOCOL_VERSIONS`, `mcpRequestMeta`, `McpProtocolVersion`, `resolveToolAuth`, `credentialPlacement`, `withCredentialQuery`, `CredentialQuery`, `uncheckedOutput`, `UncheckedOutput`, `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`, `prepareTurnToolSnapshot`, `buildHttpToolTarget`, `executeHttpTool`, `executeMcpTool`, `parseMcpRpcResponse`, `isUnsupportedMcpProtocolError`, `MCP_PROTOCOL_VERSIONS`, `mcpRequestMeta`, `McpProtocolVersion`, `resolveToolAuth`, `credentialPlacement`, `withCredentialQuery`, `CredentialQuery`, `uncheckedOutput`, `UncheckedOutput`, `ToolFailed`, `StatedToolFailure`, `McpRpcResponse`, `ModelToolResult`, `PageAnswer` |
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` |
package/esm/mod.d.ts CHANGED
@@ -67,6 +67,8 @@ export { AUTO_CONTINUE_DELAY_MS, DEFAULT_ALLOW_CONTINUE, DEFAULT_AUTO_CONTINUE,
67
67
  export { systemLinesProblem } from './src/kernel/system-lines.js';
68
68
  export type { ToolBackground, ToolBackgroundCall, ToolBackgroundHandle, ToolBackgroundService, ToolBackgroundSettled, ToolSteerReceipt, ToolSteerRefusal, } from './src/kernel/tools/background.js';
69
69
  export { authorizeToolReplay } from './src/kernel/tools/execute.js';
70
+ export type { StatedToolFailure } from './src/kernel/tools/failed.js';
71
+ export { ToolFailed } from './src/kernel/tools/failed.js';
70
72
  export { GATE_DECISIONS, type GateDecision } from './src/kernel/tools/gate-answer.js';
71
73
  export type { MemoryToolExecutionOptions } from './src/kernel/tools/memory-execution.js';
72
74
  export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
package/esm/mod.js CHANGED
@@ -42,6 +42,7 @@ export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllo
42
42
  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';
43
43
  export { systemLinesProblem } from './src/kernel/system-lines.js';
44
44
  export { authorizeToolReplay } from './src/kernel/tools/execute.js';
45
+ export { ToolFailed } from './src/kernel/tools/failed.js';
45
46
  export { GATE_DECISIONS } from './src/kernel/tools/gate-answer.js';
46
47
  export { createMemoryToolExecution } from './src/kernel/tools/memory-execution.js';
47
48
  export { askUserTool, assertToolSettings, buildHttpToolTarget, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, formatToolResult, isUnsupportedMcpProtocolError, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, registerHarnessTools, resolveToolAuth, UncheckedOutput, uncheckedOutput, withCredentialQuery, } from './src/kernel/tools/mod.js';
@@ -65,6 +65,8 @@ export { systemPromptProblem } from './system-parts.js';
65
65
  export { activityLabelProblem } from './tools/activity-label.js';
66
66
  export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
67
67
  export type { ToolBackground, ToolBackgroundCall, ToolBackgroundHandle, ToolBackgroundService, ToolBackgroundSettled, ToolSteerReceipt, ToolSteerRefusal, } from './tools/background.js';
68
+ export type { StatedToolFailure } from './tools/failed.js';
69
+ export { ToolFailed } from './tools/failed.js';
68
70
  export { type AnsweredGate, answerGatedCall, GATE_DECISIONS, type GateAnswerRequest, type GateDecision, gateExpired, type HeldGatedCall, resolveGateTtlMs, sessionPermissionsAfterApproval, type ToolGateAuth, } from './tools/gate-answer.js';
69
71
  export type { MemoryToolExecutionOptions } from './tools/memory-execution.js';
70
72
  export { createMemoryToolExecution } from './tools/memory-execution.js';
@@ -39,6 +39,7 @@ export { systemLinesProblem, systemReading } from './system-lines.js';
39
39
  export { systemPromptProblem } from './system-parts.js';
40
40
  export { activityLabelProblem } from './tools/activity-label.js';
41
41
  export { agentToolInputFor, agentToolOutput } from './tools/agent.js';
42
+ export { ToolFailed } from './tools/failed.js';
42
43
  export { answerGatedCall, GATE_DECISIONS, gateExpired, resolveGateTtlMs, sessionPermissionsAfterApproval, } from './tools/gate-answer.js';
43
44
  export { createMemoryToolExecution } from './tools/memory-execution.js';
44
45
  export { askUserTool, assertToolSettings, authorizeToolReplay, coerceToolResultParts, createToolRegistry, credentialPlacement, executeHttpTool, executeMcpTool, executeRegisteredTool, formatToolResult, isUnsupportedMcpProtocolError, leanToolResultData, MCP_PROTOCOL_VERSIONS, mcpRequestMeta, parseMcpRpcResponse, prepareTurnToolSnapshot, projectForModel, registerHarnessTools, resolveToolAuth, withCredentialQuery, } from './tools/mod.js';
@@ -28,11 +28,6 @@ interface AgentCaller {
28
28
  /** Whether a running call of `tool` can be steered: its agent's profile allows injects. */
29
29
  takesSteers(tool: RegisteredAgentTool): boolean;
30
30
  }
31
- /** A call that settled without a reply; the model reads `failure`. */
32
- declare class AgentCallFailed extends Error {
33
- readonly failure: ToolFailure;
34
- constructor(failure: ToolFailure);
35
- }
36
31
  /**
37
32
  * What the model sent, split into what goes to the called agent and what only the host reads.
38
33
  *
@@ -68,4 +63,4 @@ declare function normalizeAgent(def: AgentToolDef, input: z.ZodType<AgentToolInp
68
63
  outputSchema: Record<string, unknown>;
69
64
  }): RegisteredAgentTool;
70
65
  export type { AgentCaller, AgentRun };
71
- export { AgentCallFailed, agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };
66
+ export { agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };
@@ -4,14 +4,6 @@ import { optionValues } from '../registry/options.js';
4
4
  import { interactionPartSchema, keptReply, sourceSchema } from '../turn-events.js';
5
5
  import { findLast } from '../util/find-last.js';
6
6
  import { profileToolAllow } from './resolve.js';
7
- /** A call that settled without a reply; the model reads `failure`. */
8
- class AgentCallFailed extends Error {
9
- failure;
10
- constructor(failure) {
11
- super(failure.message);
12
- this.failure = failure;
13
- }
14
- }
15
7
  /** The agents an agent tool can run: each has a turn that takes text, which a transcription turn does not. */
16
8
  const AGENT_TOOL_TYPES = new Set(['text', 'image', 'speech']);
17
9
  // why: Bytes that are not base64, or a text of only spaces, would be refused inside the called turn as the host's error and end the caller's turn; checked here, the model reads a failed call.
@@ -213,4 +205,4 @@ function normalizeAgent(def, input, schemas) {
213
205
  ...schemas,
214
206
  };
215
207
  }
216
- export { AgentCallFailed, agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };
208
+ export { agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };
@@ -11,10 +11,11 @@ import { jsonObjectSchema } from '../json.js';
11
11
  import { isAwaitingUserInput } from '../turn-events.js';
12
12
  import { isRecord } from '../util/record.js';
13
13
  import { fillActivityLabel } from './activity-label.js';
14
- import { AgentCallFailed, agentToolOrigin } from './agent.js';
14
+ import { agentToolOrigin } from './agent.js';
15
15
  import { planDetach, splitBackground } from './background.js';
16
16
  import { coordinateTool } from './coordinate.js';
17
17
  import { dispatchToolBody, failedActivity, failedActivityOf, failureEvent, messageOf, networkBlocked, networkBlockedEvent, requestChecks, sourceEvents, startToolExecution, toolCallArguments, toolEvent, } from './events.js';
18
+ import { ToolFailed } from './failed.js';
18
19
  import { HandlerEvents } from './handler-events.js';
19
20
  import { fetchToolImages } from './image-fetch.js';
20
21
  import { formatToolFailureForModel, formatToolResult, frameToolFailure } from './model-text.js';
@@ -584,12 +585,11 @@ agent, beginBody) {
584
585
  checks.record();
585
586
  }
586
587
  catch (err) {
587
- if (agent) {
588
- // why: Anything but a settled failure is the host's to fix, as a compactor's is.
589
- if (err instanceof AgentCallFailed)
590
- return yield* fail(err.failure);
588
+ if (err instanceof ToolFailed)
589
+ return yield* fail(err.failure);
590
+ // why: Anything but a settled failure is the host's to fix, as a compactor's is.
591
+ if (agent)
591
592
  throw err;
592
- }
593
593
  if (signedIn.prepared && err instanceof CredentialRefusedError) {
594
594
  checks.record();
595
595
  const refused = yield* refusedCredentialOutcome(tool, err.refusal, signedIn.secret !== undefined, ctx, base);
@@ -1141,7 +1141,7 @@ async function* executeAgentTool(args) {
1141
1141
  if (next.done) {
1142
1142
  tokens = next.value.tokens;
1143
1143
  if ('failure' in next.value)
1144
- throw new AgentCallFailed(next.value.failure);
1144
+ throw new ToolFailed(next.value.failure);
1145
1145
  yield { kind: 'complete', output: next.value.output };
1146
1146
  return;
1147
1147
  }
@@ -0,0 +1,12 @@
1
+ import type { ToolFailure } from '../turn-events.js';
2
+ /** A failure a tool states itself: the person's wording (`error`) is added where the event reaches the host. */
3
+ export type StatedToolFailure = Omit<ToolFailure, 'error'>;
4
+ /**
5
+ * Thrown by a handler whose call ran and did not do what it was asked. The call settles as
6
+ * `failure`, under its own `code` and `kind`, and the model reads it; any other throw is a
7
+ * `handler_error`.
8
+ */
9
+ export declare class ToolFailed extends Error {
10
+ readonly failure: StatedToolFailure;
11
+ constructor(failure: StatedToolFailure);
12
+ }
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Thrown by a handler whose call ran and did not do what it was asked. The call settles as
3
+ * `failure`, under its own `code` and `kind`, and the model reads it; any other throw is a
4
+ * `handler_error`.
5
+ */
6
+ export class ToolFailed extends Error {
7
+ failure;
8
+ constructor(failure) {
9
+ super(failure.message);
10
+ this.name = 'ToolFailed';
11
+ this.failure = failure;
12
+ }
13
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.911.g193d75c",
3
+ "version": "0.3.5-next.912.g25d311a",
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",