@theoremjs/agents 0.3.5-next.907.g49f9ef9 → 0.3.5-next.911.g193d75c

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
@@ -506,7 +506,7 @@ live_sessions = "registered provider via runSession; host owns mic, camera, and
506
506
  session_memory_in_kernel = false
507
507
  ```
508
508
 
509
- **Facts and policy.** Provider wire shapes and protocol metadata may ship in `@theoremjs/agents/providers`. Product policy may not ship: prompts, personas, end-user copy, demo apps, and channel behaviour. Every string that a user or a model reads is either supplied by the host or is an overridable default in the kernel labels (`overrideLabels`). Behavioural defaults are typed profile-schema fields. Optional packages, such as `studio/`, are inert extras. If you delete one, no kernel behaviour changes.
509
+ **Facts and policy.** Provider wire shapes and protocol metadata may ship in `@theoremjs/agents/providers`, and only there: the kernel makes no claim about a provider or a model. Product policy may not ship: prompts, personas, end-user copy, demo apps, and channel behaviour. Every string that a user or a model reads is either supplied by the host or is an overridable default in the kernel labels (`overrideLabels`). Behavioural defaults are typed profile-schema fields. Optional packages, such as `studio/`, are inert extras. If you delete one, no kernel behaviour changes.
510
510
 
511
511
  Four properties are invariant. Where a test or a lint checks one, the table names it.
512
512
 
@@ -1,7 +1,7 @@
1
1
  /** Values that fill a label template's `{param}` placeholders. */
2
2
  export type LabelParams = Record<string, string | number>;
3
3
  /** Keys are stable API. */
4
- export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.reply_cut_off", "repair.call_cut_off", "repair.call_cut_off_guidance", "repair.nothing_written", "repair.nothing_written_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.hook_failed", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
4
+ export declare const LABEL_KEYS: readonly ["provider.decision_failed", "provider.decision_unavailable", "provider.decision_model_missing", "provider.decision_ended", "provider.decision_images_off", "provider.decision_box_model", "provider.budget_exhausted", "provider.adapter_version", "provider.adapter_methods", "provider.adapter_schemas", "provider.fallback_slot", "provider.model_fallback_slot", "provider.host_model", "turn.media_refused_image", "turn.media_refused_video", "turn.media_refused_file", "provider.turn_profile", "provider.model_binding_missing", "provider.session_closed", "provider.settled_call", "provider.session_unavailable", "provider.live_input", "provider.tool_cancel_missing", "provider.kernel_gate", "provider.event_invalid", "provider.response_identity", "provider.credential_resolution", "provider.credential_shape", "provider.stored_continuation", "provider.continuation_mismatch", "provider.continuation_contract", "provider.stateless_history", "provider.events_after_completion", "provider.duplicate_call", "provider.tool_cancel_live", "provider.complete_unavailable", "provider.parallel_tools", "provider.binding_identity", "provider.profile_type", "provider.event_type", "provider.feature", "provider.input_kind", "provider.output_kind", "provider.builtin", "provider.credential_missing", "provider.profile_configuration", "continue.instruction", "canary.bind_note", "user_data.note", "context.note", "taint.blocked", "taint.reason_steered", "taint.reason_tainted", "taint.destination_blocked", "taint.destination_confirm", "advisory.notice_elevated", "advisory.notice_high", "advisory.guidance", "attachments.too_many_files", "attachments.too_many_of_kind", "attachments.file_too_large", "attachments.turn_too_large", "attachments.not_accepted", "attachments.mime_not_allowed", "attachments.limits_unconfigured", "quota.exhausted", "quota.busy", "error.config", "error.request", "error.conflict", "error.not_found", "error.input", "error.action", "error.auth", "error.rate_limit", "error.busy", "error.unsupported", "error.unavailable", "error.bad_response", "error.network", "error.timeout", "error.safety", "error.blocked", "error.declined", "error.failed", "error.cancelled", "error.internal", "repair.default_guidance", "repair.items_guidance", "repair.cut_off_guidance", "repair.reply_cut_off", "repair.call_cut_off", "repair.call_cut_off_guidance", "repair.nothing_written", "repair.nothing_written_guidance", "repair.prompt_header", "repair.prompt_intro", "repair.prompt_instructions", "repair.history_heading", "repair.section_previous_output", "repair.section_validator_rejection", "repair.section_repair_guidance", "repair.section_instructions", "structured.answer_tool", "structured.answer_missing", "structured.cut_off", "structured.not_json", "compaction.request", "compaction.tool_call", "compaction.tool_result", "compaction.tool_files", "decision.box_image", "detect.blocked", "detect.call_blocked", "detect.output_blocked", "detect.shown_blocked", "detect.hint.ids", "detect.hint.financial", "detect.hint.network", "detect.hint.credentials", "detect.hint.email", "detect.hint.phone", "detect.hint.bank_account", "detect.hint.injection", "detect.hint.canary_leak", "detect.hint.prompt_leak", "detect.hint.marker_leak", "detect.hint.ungiven_images", "detect.hint.ungiven_links", "detect.hint.tool_leak", "detect.hint.own", "egress.default_repair_guidance", "egress.refusal", "egress.refusal_cut", "egress.rejection", "egress.rejection_found", "egress.hint_unscannable", "egress.hint_provider_tool_leak", "thought.omitted_image", "thought.omitted_link", "thought.omitted_instructions", "session.abandon_gated", "session.tool_denied", "session.tool_aborted", "session.sign_in", "sign_in.link", "sign_in.pending", "sign_in.done", "sign_in.declined", "sign_in.expired", "sign_in.out_of_scope", "session.gate_expired", "session.provider_state_unowned", "session.conversation_unknown", "session.full", "session.busy", "session.turn_ended", "session.gate_pending", "session.part_skipped", "live.session_ended", "voice.unsupported", "voice.permission", "voice.unavailable", "voice.failed", "voice.empty", "stop.cancelled", "stop.interrupted", "stop.length", "stop.filtered", "stop.provider_error", "stop.stream_incomplete", "stop.step_limit", "stop.answer_missing", "composer.model", "composer.effort", "tool.awaiting_user", "tool.completed_hidden", "tool.t2_loader_needs_snapshot", "tool.t2_loader_shape", "tool.t2_loader_output_invalid", "tool.execution_uncertain", "tool.input_invalid", "tool.input_host_fields", "tool.hook_failed", "tool.input_invalid_after_mutate", "tool.output_invalid_after_mutate", "tool.handler_no_output", "tool.did_not_run", "tool.unreachable", "tool.page_no_answer", "tool.page_timed_out", "tool.output_invalid", "tool.not_loaded_t2", "tool.wait_unknown", "tool.wait_cycle", "tool.after_field", "tool.background_field", "tool.background_started", "tool.late_result", "tool.not_visible", "tool.builtin_not_enabled", "tool.provider_native", "tool.not_registered", "tool.builtin_needs_snapshot", "tool.not_allowed", "tool.not_eligible", "tool.unsupported_type", "tool.agent_call_limit", "tool.agent_failed", "tool.activity_failed", "protocol.not_served", "protocol.profile_type", "protocol.options", "protocol.option_clash", "protocol.base_options", "protocol.id_clash", "protocol.ws_headers", "protocol.builtin_unwritten", "protocol.provider_missing", "protocol.connection", "protocol.part_schema", "protocol.part_invalid", "protocol.key_invalid", "protocol.no_key", "protocol.reply_shape", "protocol.endpoint_url", "protocol.endpoint_host", "protocol.http", "protocol.no_operation", "protocol.definition", "protocol.provider_id_clash", "protocol.history_needed"];
5
5
  /** One of {@linkcode LABEL_KEYS}. */
6
6
  export type LabelKey = (typeof LABEL_KEYS)[number];
7
7
  /**
@@ -186,6 +186,7 @@ export const LABEL_KEYS = [
186
186
  'tool.t2_loader_output_invalid',
187
187
  'tool.execution_uncertain',
188
188
  'tool.input_invalid',
189
+ 'tool.input_host_fields',
189
190
  'tool.hook_failed',
190
191
  'tool.input_invalid_after_mutate',
191
192
  'tool.output_invalid_after_mutate',
@@ -539,6 +540,7 @@ const DEFAULTS = {
539
540
  'tool.t2_loader_output_invalid': 'T2 loader output validation failed after promotion',
540
541
  'tool.execution_uncertain': 'This action has an unresolved execution. Check the destination before trying it again.',
541
542
  'tool.input_invalid': 'Tool input validation failed',
543
+ 'tool.input_host_fields': 'Your call to {tool} sent {fields}, which {tool} does not take. Call it again without them.',
542
544
  'tool.hook_failed': 'This tool call did not run: the app hit an error before it could start.',
543
545
  'tool.did_not_run': "Tool '{tool}' did not run.",
544
546
  'tool.unreachable': "Sorry, a tool couldn't be reached. Please try again.",
@@ -769,6 +771,7 @@ export const LABEL_NOTES = {
769
771
  'tool.t2_loader_output_invalid': "Told to the model when the T2 loader's output fails its schema after promotion.",
770
772
  'tool.execution_uncertain': 'Shown when a tool operation has no confirmed outcome and cannot execute again.',
771
773
  'tool.input_invalid': "Told to the model when a tool call's input fails the tool's input schema.",
774
+ 'tool.input_host_fields': 'Told to the model when its call sends input fields marked exposeToModel: false, which the host fills. Takes {tool} and {fields}.',
772
775
  'tool.hook_failed': "Told to the model when a host hook threw before a tool call could start. The hook's own error goes to the host as hook_failed.",
773
776
  'tool.did_not_run': 'Given by runTool and runToolStep for a call that never settled when the invoke gave no error of its own. Takes {tool}.',
774
777
  'tool.unreachable': 'Shown to the user when a tool call never reached its host. Takes {tool}.',
@@ -873,6 +876,7 @@ const LABEL_PLACEHOLDERS = {
873
876
  'tool.builtin_not_enabled': TOOL,
874
877
  'tool.provider_native': TOOL,
875
878
  'tool.not_registered': TOOL,
879
+ 'tool.input_host_fields': ['tool', 'fields'],
876
880
  'tool.builtin_needs_snapshot': TOOL,
877
881
  'tool.not_allowed': ['tool', 'profile'],
878
882
  'tool.not_eligible': TOOL,
@@ -321,7 +321,7 @@ export const FIELD_DOCS = {
321
321
  'registerTool.fieldText': 'What the calling model reads on a field of an agent tool input, such as text. A field the profile does not take is refused when the tool registers.',
322
322
  'registerTool.handler': 'Your function that runs the tool; it can also yield progress as it goes.',
323
323
  'registerTool.headers': "Headers sent with every request to the tool's own origin, never once a redirect leaves it.",
324
- 'registerTool.hostFields': 'Fields the calling model fills on an agent tool that only the host reads. 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.',
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
326
  'registerTool.imageLimits': 'How many of those pictures the kernel fetches, how large, and how slowly.',
327
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.',
@@ -13,6 +13,7 @@ import { CONTEXT_SENDERS, CONTINUE_STOP_KINDS, IMAGE_ATTACHMENT_ACCEPT_MIMES, PR
13
13
  import { isContinueStopKind } from '../stop.js';
14
14
  import { assertSystemLines, systemLinesProblem } from '../system-lines.js';
15
15
  import { profileToolAllow, profileToolsSpec } from '../tools/resolve.js';
16
+ import { issuePath } from '../tools/schema-issues.js';
16
17
  import { isTurnMediaRef } from './attachments.js';
17
18
  import { mediaKindForMime, mimeAllowed, profileInputs } from './catalog.js';
18
19
  import { optionValues, profileOption } from './options.js';
@@ -65,7 +66,7 @@ function defineTranscriptionProfile(input) {
65
66
  function assertBindingData(profileId, modelId, binding, schema) {
66
67
  const parsed = schema.safeParse(binding);
67
68
  if (!parsed.success)
68
- throw new TheoremError('config', `Profile ${profileId} model '${modelId}': ${parsed.error.issues.map((issue) => `${issue.path.join('.')}: ${issue.message}`).join('; ')}`);
69
+ throw new TheoremError('config', `Profile ${profileId} model '${modelId}': ${parsed.error.issues.map((issue) => `${issuePath(issue.path)}: ${issue.message}`).join('; ')}`);
69
70
  }
70
71
  function validateDecisionBinding(profileId, modelId, binding) {
71
72
  assertBindingData(profileId, modelId, binding, decisionModelBindingSchema);
@@ -900,7 +900,7 @@ export const EXTRA_FIELDS = withFieldDocs({
900
900
  unset: 'The input is only what the profile takes',
901
901
  },
902
902
  'registerTool.hostOnly': {
903
- ...field("Array<'attachments' | 'voice' | 'options'>"),
903
+ ...field("Array<'attachments' | 'voice' | 'options' | 'speech'>"),
904
904
  unset: 'The model can fill every channel the profile takes',
905
905
  },
906
906
  'registerTool.auth': {
@@ -9,6 +9,7 @@ import { isRecord } from '../util/record.js';
9
9
  import { fillActivityLabel, toolNameInWords } from './activity-label.js';
10
10
  import { formatToolFailureForModel, formatToolResult } from './model-text.js';
11
11
  import { inputForModel } from './model-view.js';
12
+ import { issuePath, schemaIssueDetails } from './schema-issues.js';
12
13
  export function toolEvent(base, patch) {
13
14
  return {
14
15
  type: 'tool',
@@ -95,7 +96,7 @@ export function* sourceEvents(base, sources, output) {
95
96
  if (parsed.success)
96
97
  cited.push(parsed.data);
97
98
  else
98
- invalid.push(`[${String(index)}] ${parsed.error.issues.map((i) => `${i.path.join('.') || 'source'}: ${i.message}`).join('; ')}`);
99
+ invalid.push(`[${String(index)}] ${parsed.error.issues.map((i) => `${issuePath(i.path) || 'source'}: ${i.message}`).join('; ')}`);
99
100
  });
100
101
  if (invalid.length > 0) {
101
102
  yield sourcesInvalid(base, `sources not cited: ${invalid.join(' | ')}`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
@@ -155,7 +156,7 @@ export function startToolExecution(tool, rawInput, ctx) {
155
156
  code: 'invalid_input',
156
157
  kind: 'bad_response',
157
158
  message: labelText('tool.input_invalid', {}, ctx.profile.labels),
158
- details: parsed.error.flatten(),
159
+ details: schemaIssueDetails(parsed.error.issues),
159
160
  },
160
161
  };
161
162
  }
@@ -27,6 +27,7 @@ import { plainToolInput } from './schema.js';
27
27
  import { CredentialRefusedError, signedInFetch } from './signed-in-fetch.js';
28
28
  import { emitGateSettlement, runPostToolStages, runPreToolPipeline, } from './stage-run.js';
29
29
  export { checkPermission, isGateResumeGranted, isResumeContinuation, permissionGranted, } from './permission.js';
30
+ import { schemaIssueDetails } from './schema-issues.js';
30
31
  import { UncheckedOutput } from './unchecked-output.js';
31
32
  export function originOfTool(tool, tools) {
32
33
  if (tool.type === 'agent')
@@ -184,7 +185,7 @@ function applyT2LoaderPromotion(tools, tool, checkedData, ctx, snapshot) {
184
185
  code: 'invalid_output',
185
186
  kind: 'bad_response',
186
187
  message: labelText('tool.t2_loader_output_invalid', {}, ctx.profile.labels),
187
- details: rechecked.error.flatten(),
188
+ details: schemaIssueDetails(rechecked.error.issues),
188
189
  },
189
190
  };
190
191
  }
@@ -453,7 +454,7 @@ function makeReproject(parse, project, labels) {
453
454
  code: 'invalid_output',
454
455
  kind: 'bad_response',
455
456
  message: labelText('tool.output_invalid_after_mutate', {}, labels),
456
- details: checked.error.flatten(),
457
+ details: schemaIssueDetails(checked.error.issues),
457
458
  },
458
459
  };
459
460
  }
@@ -617,7 +618,7 @@ agent, beginBody) {
617
618
  code: 'invalid_output',
618
619
  kind: 'bad_response',
619
620
  message: labelText('tool.output_invalid', {}, ctx.profile.labels),
620
- details: checked.error.flatten(),
621
+ details: schemaIssueDetails(checked.error.issues),
621
622
  });
622
623
  }
623
624
  const promoted = applyT2LoaderPromotion(tools, tool, checked.data, ctx, snapshot);
@@ -719,7 +720,7 @@ function hostFieldsFailure(args, tool, input) {
719
720
  return {
720
721
  code: 'invalid_input',
721
722
  kind: 'bad_response',
722
- message: labelText('tool.input_invalid', {}, args.profile.labels),
723
+ message: labelText('tool.input_host_fields', { tool: args.name, fields: notInputs.join(', ') }, args.profile.labels),
723
724
  details: { notInputs },
724
725
  };
725
726
  }
@@ -6,6 +6,7 @@ import type { HandlerEvents } from './handler-events.js';
6
6
  import { type McpSessionCache } from './mcp-sessions.js';
7
7
  import type { ToolOperationClaim } from './operation.js';
8
8
  import { type JsonSchema } from './schema.js';
9
+ import { type SchemaIssue } from './schema-issues.js';
9
10
  import { type ToolStageSupport } from './stage-run.js';
10
11
  import type { HttpToolDef, McpToolDef, ModelToolResult, ToolAuthConfig, ToolBodyOutcome, ToolContext, ToolFailure, ToolGate } from './types.js';
11
12
  export type AuthResolveResult = {
@@ -54,7 +55,7 @@ export declare function parseToolOutput<T>(schema: {
54
55
  } | {
55
56
  success: false;
56
57
  error: {
57
- flatten: () => unknown;
58
+ issues: readonly SchemaIssue[];
58
59
  };
59
60
  };
60
61
  }, responseData: unknown): {
@@ -63,7 +64,7 @@ export declare function parseToolOutput<T>(schema: {
63
64
  } | {
64
65
  success: false;
65
66
  error: {
66
- flatten: () => unknown;
67
+ issues: readonly SchemaIssue[];
67
68
  };
68
69
  };
69
70
  /**
@@ -10,6 +10,7 @@ import { createMcpSessionCache, isMcpSessionId, mcpSessionKey, } from './mcp-ses
10
10
  import { outputForModel } from './model-view.js';
11
11
  import { checkPermission, gateDetails } from './permission.js';
12
12
  import { assertFixedEndpointOrigin } from './schema.js';
13
+ import { issuePath, schemaIssueDetails } from './schema-issues.js';
13
14
  import { runPreToolPipeline } from './stage-run.js';
14
15
  /** `url` with the credential set in its query parameter; `url` itself is left as it was. */
15
16
  export function withCredentialQuery(url, query) {
@@ -632,7 +633,7 @@ async function* sendHttpRequest(tool, targetUrl, body, { authHeaders, secret },
632
633
  code: 'invalid_output',
633
634
  kind: 'bad_response',
634
635
  message: 'HTTP response did not match tool output schema', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
635
- details: checked.error.flatten(),
636
+ details: schemaIssueDetails(checked.error.issues),
636
637
  };
637
638
  return failureOutcome(failure, false);
638
639
  }
@@ -1017,7 +1018,7 @@ function extractMcpOutput(tool, result) {
1017
1018
  function structuredMismatch(issues) {
1018
1019
  const shown = issues
1019
1020
  .slice(0, 3)
1020
- .map((issue) => `${issue.path.map(String).join('.') || '(root)'}: ${issue.message}`);
1021
+ .map((issue) => `${issuePath(issue.path) || '(root)'}: ${issue.message}`);
1021
1022
  const more = issues.length > 3 ? ` (+${String(issues.length - 3)} more)` : '';
1022
1023
  return {
1023
1024
  code: 'mcp_structured_mismatch',
@@ -1073,7 +1074,7 @@ function interpretMcpRpc(tool, negotiated) {
1073
1074
  code: 'invalid_output',
1074
1075
  kind: 'bad_response',
1075
1076
  message: 'MCP output schema validation failed', // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
1076
- details: checked.error.flatten(),
1077
+ details: schemaIssueDetails(checked.error.issues),
1077
1078
  },
1078
1079
  ...withWarning,
1079
1080
  };
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Where a schema refused a value, as text. Every issue keeps its whole path.
3
+ *
4
+ * why: zod's `flatten()` keys each issue by the first segment of its path and drops the rest,
5
+ * so a bad key inside `action.save` read as a bad `action`.
6
+ *
7
+ * @module
8
+ */
9
+ /** One schema issue: the place in the value, and what was wrong there. */
10
+ export type SchemaIssue = {
11
+ readonly path: readonly PropertyKey[];
12
+ readonly message: string;
13
+ };
14
+ /** A failure's `details` when a schema refuses a value. */
15
+ export type SchemaIssueDetails = {
16
+ /** Issues on the value itself. */
17
+ formErrors: string[];
18
+ /** Issues by top-level field. A line names the place below that field first: `save.from: …`. */
19
+ fieldErrors: Record<string, string[]>;
20
+ };
21
+ /** A path as dotted text; empty at the root. */
22
+ export declare function issuePath(path: readonly PropertyKey[]): string;
23
+ /** The details of a refused value, keyed like zod's `flatten()` but with no part of a path lost. */
24
+ export declare function schemaIssueDetails(issues: readonly SchemaIssue[]): SchemaIssueDetails;
@@ -0,0 +1,28 @@
1
+ /**
2
+ * Where a schema refused a value, as text. Every issue keeps its whole path.
3
+ *
4
+ * why: zod's `flatten()` keys each issue by the first segment of its path and drops the rest,
5
+ * so a bad key inside `action.save` read as a bad `action`.
6
+ *
7
+ * @module
8
+ */
9
+ /** A path as dotted text; empty at the root. */
10
+ export function issuePath(path) {
11
+ return path.map(String).join('.');
12
+ }
13
+ /** The details of a refused value, keyed like zod's `flatten()` but with no part of a path lost. */
14
+ export function schemaIssueDetails(issues) {
15
+ const formErrors = [];
16
+ const fieldErrors = {};
17
+ for (const { path, message } of issues) {
18
+ const [field, ...below] = path;
19
+ if (field === undefined) {
20
+ formErrors.push(message);
21
+ continue;
22
+ }
23
+ const line = below.length > 0 ? `${issuePath(below)}: ${message}` : message;
24
+ const key = String(field);
25
+ fieldErrors[key] = [...(fieldErrors[key] ?? []), line];
26
+ }
27
+ return { formErrors, fieldErrors };
28
+ }
@@ -9,6 +9,7 @@ import { inputForModel } from './model-view.js';
9
9
  import { operationWireValue } from './operation.js';
10
10
  import { gateDetails, isGateResumeGranted } from './permission.js';
11
11
  import { plainToolInput } from './schema.js';
12
+ import { schemaIssueDetails } from './schema-issues.js';
12
13
  function defaultToolStageSupport(ctx) {
13
14
  return {
14
15
  handlers: [],
@@ -41,7 +42,7 @@ function invalidAfterMutate(error, ctx) {
41
42
  code: 'invalid_input',
42
43
  kind: 'bad_response',
43
44
  message: labelText('tool.input_invalid_after_mutate', {}, ctx.profile.labels),
44
- details: error.flatten(),
45
+ details: schemaIssueDetails(error.issues),
45
46
  },
46
47
  };
47
48
  }
@@ -479,8 +479,8 @@ export interface AgentToolOutput {
479
479
  /** What the called agent cited; the caller's turn cites them too. */
480
480
  sources?: Source[];
481
481
  }
482
- /** A channel of an agent tool's input that the called profile's `inputs` declares. */
483
- export type AgentToolChannel = 'attachments' | 'voice' | 'options';
482
+ /** A channel of an agent tool's input: one the called profile's `inputs` declares, or `speech` on a speech profile. */
483
+ export type AgentToolChannel = 'attachments' | 'voice' | 'options' | 'speech';
484
484
  /**
485
485
  * A tool whose call runs one turn of another registered agent. That agent is a
486
486
  * standalone profile; the tool is how another agent's model calls it. Its input
@@ -512,13 +512,15 @@ export interface AgentToolDef extends ToolBase {
512
512
  */
513
513
  fieldText?: Partial<Record<keyof AgentToolInput, string>>;
514
514
  /**
515
- * Fields the calling model fills on an agent tool that only the host reads. onAgentCall gets them
516
- * as hostInput and turns them into what the agent is sent; the agent never sees them. A name the
517
- * input already has is refused when the tool registers.
515
+ * Fields on an agent tool that only the host reads. The calling model fills them, or the host
516
+ * does when a field is marked exposeToModel: false. onAgentCall gets them as hostInput and turns
517
+ * them into what the agent is sent; the agent never sees them. A name the input already has is
518
+ * refused when the tool registers.
518
519
  *
519
- * @remarks Fields the calling model fills that only the host reads. `onAgentCall` gets them as
520
- * `hostInput` and turns them into the agent's input; they are never sent to the agent. A name the
521
- * input already has is refused, and a call without the hook is a config error.
520
+ * @remarks Fields only the host reads. The calling model fills them, or the host when a field is
521
+ * marked `exposeToModel: false`. `onAgentCall` gets them as `hostInput` and turns them into the
522
+ * agent's input; they are never sent to the agent. A name the input already has is refused, and a
523
+ * call without the hook is a config error.
522
524
  */
523
525
  hostFields?: Record<string, z.ZodType>;
524
526
  /**
@@ -10,7 +10,7 @@ export type InteractionsRequest = ModelRequest & {
10
10
  export declare function camelToSnake(key: string): string;
11
11
  export declare function toGoogleValue(value: unknown): unknown;
12
12
  /** A part in camel case; `toGoogleValue` snake-cases `mimeType` to the documented `mime_type`. */
13
- export declare function wirePart(part: InteractionPart): Record<string, string>;
13
+ export declare function wireInteractionPart(part: InteractionPart): Record<string, string>;
14
14
  export declare function userInputStep(parts: InteractionPart[]): Record<string, unknown>;
15
15
  /** A thought's signature, for the tool call at `call` in the same assistant message. */
16
16
  export declare const thoughtSignature: z.ZodType<{
@@ -28,7 +28,7 @@ export function toGoogleValue(value) {
28
28
  return value;
29
29
  }
30
30
  /** A part in camel case; `toGoogleValue` snake-cases `mimeType` to the documented `mime_type`. */
31
- export function wirePart(part) {
31
+ export function wireInteractionPart(part) {
32
32
  if (part.type === 'text') {
33
33
  return { type: 'text', text: part.text };
34
34
  }
@@ -39,11 +39,11 @@ export function wirePart(part) {
39
39
  }
40
40
  const USER_INPUT = 'user_input';
41
41
  export function userInputStep(parts) {
42
- return { type: USER_INPUT, content: parts.map(wirePart) };
42
+ return { type: USER_INPUT, content: parts.map(wireInteractionPart) };
43
43
  }
44
44
  function historyContent(msg) {
45
45
  const parts = historyMessageParts(msg);
46
- return parts.length > 0 ? parts.map(wirePart) : [{ type: 'text', text: '' }];
46
+ return parts.length > 0 ? parts.map(wireInteractionPart) : [{ type: 'text', text: '' }];
47
47
  }
48
48
  // why: Google refuses any other part inside a `function_result`: "The value 'document' is not supported for 'type' at 'input[8].result[2]'. Supported values: 'function', 'image', 'text', 'video'." (live, 13/10/2026, gemini-3.5-flash-lite).
49
49
  const FUNCTION_RESULT_PART_TYPES = new Set([
@@ -56,7 +56,7 @@ function functionResultStep(msg) {
56
56
  return {
57
57
  type: 'function_result',
58
58
  ...historyToolIdentity({ name: msg.name, call_id: msg.tool_call_id }),
59
- result: parts.length > 0 ? parts.map(wirePart) : [{ type: 'text', text: '' }],
59
+ result: parts.length > 0 ? parts.map(wireInteractionPart) : [{ type: 'text', text: '' }],
60
60
  };
61
61
  }
62
62
  /**
@@ -203,7 +203,7 @@ function speechInputStep(parts, style, apiId) {
203
203
  type: USER_INPUT,
204
204
  content: [
205
205
  { type: 'text', text: `Read the following aloud. ${style.trim()}\n` },
206
- ...parts.map(wirePart),
206
+ ...parts.map(wireInteractionPart),
207
207
  ],
208
208
  };
209
209
  }
@@ -212,7 +212,7 @@ function speechInputStep(parts, style, apiId) {
212
212
  return {
213
213
  type: USER_INPUT,
214
214
  content: parts
215
- .map(wirePart)
215
+ .map(wireInteractionPart)
216
216
  .map((part) => (part.type === 'text' ? { ...part, annotations } : part)),
217
217
  };
218
218
  }
@@ -21,13 +21,17 @@ export { geminiEmbeddings } from './gemini/embeddings-protocol.js';
21
21
  export { geminiInteractions } from './gemini/interactions-protocol.js';
22
22
  export { geminiLive } from './gemini/live-protocol.js';
23
23
  export { geminiProvider } from './gemini/provider.js';
24
+ export { wireInteractionPart } from './google/interactions/framing.js';
25
+ export { turnStopFromInteractionStatus } from './google/interactions/status.js';
24
26
  export { ollamaEmbeddings } from './local/embeddings-protocol.js';
25
27
  export { localProvider } from './local/provider.js';
28
+ export { turnStopFromOpenAiFinishReason } from './open-ai/finish-reason.js';
26
29
  export { openAi } from './open-ai/protocol.js';
27
30
  export { openRouterDecisions } from './openrouter/decisions-protocol.js';
28
31
  export { openRouterEmbeddings } from './openrouter/embeddings-protocol.js';
29
32
  export { openRouterImages } from './openrouter/images-protocol.js';
30
- export { openRouterOpenAi } from './openrouter/protocol.js';
33
+ export type { CacheMode, CacheSpec, CacheTtl } from './openrouter/protocol.js';
34
+ export { CACHE_MODES, CACHE_TTLS, openRouterOpenAi } from './openrouter/protocol.js';
31
35
  export { openRouterProvider } from './openrouter/provider.js';
32
36
  export type { OpenRouterTranscriptionsOptions } from './openrouter/transcriptions-protocol.js';
33
37
  export { openRouterTranscriptions } from './openrouter/transcriptions-protocol.js';
@@ -12,13 +12,16 @@ export { geminiEmbeddings } from './gemini/embeddings-protocol.js';
12
12
  export { geminiInteractions } from './gemini/interactions-protocol.js';
13
13
  export { geminiLive } from './gemini/live-protocol.js';
14
14
  export { geminiProvider } from './gemini/provider.js';
15
+ export { wireInteractionPart } from './google/interactions/framing.js';
16
+ export { turnStopFromInteractionStatus } from './google/interactions/status.js';
15
17
  export { ollamaEmbeddings } from './local/embeddings-protocol.js';
16
18
  export { localProvider } from './local/provider.js';
19
+ export { turnStopFromOpenAiFinishReason } from './open-ai/finish-reason.js';
17
20
  export { openAi } from './open-ai/protocol.js';
18
21
  export { openRouterDecisions } from './openrouter/decisions-protocol.js';
19
22
  export { openRouterEmbeddings } from './openrouter/embeddings-protocol.js';
20
23
  export { openRouterImages } from './openrouter/images-protocol.js';
21
- export { openRouterOpenAi } from './openrouter/protocol.js';
24
+ export { CACHE_MODES, CACHE_TTLS, openRouterOpenAi } from './openrouter/protocol.js';
22
25
  export { openRouterProvider } from './openrouter/provider.js';
23
26
  export { openRouterTranscriptions } from './openrouter/transcriptions-protocol.js';
24
27
  export { systemOne } from './system-one/protocol.js';
@@ -1,11 +1,11 @@
1
1
  import { type JsonObject } from '../../kernel/json.js';
2
2
  import { type Protocol } from '../../kernel/protocols/mod.js';
3
3
  /** What is cached: the whole request (`automatic`) or the system instruction only (`system`). */
4
- declare const CACHE_MODES: readonly ["automatic", "system"];
4
+ export declare const CACHE_MODES: readonly ["automatic", "system"];
5
5
  /** One of {@linkcode CACHE_MODES}. */
6
6
  export type CacheMode = (typeof CACHE_MODES)[number];
7
7
  /** How long OpenRouter's upstream keeps a cached prompt. */
8
- declare const CACHE_TTLS: readonly ["5m", "1h"];
8
+ export declare const CACHE_TTLS: readonly ["5m", "1h"];
9
9
  /** One of {@linkcode CACHE_TTLS}. */
10
10
  export type CacheTtl = (typeof CACHE_TTLS)[number];
11
11
  /**
@@ -50,4 +50,3 @@ export interface OpenRouterRouting {
50
50
  }
51
51
  /** Chat Completions with OpenRouter's caching, routing, web search, citations, and reasoning. */
52
52
  export declare const openRouterOpenAi: Protocol<OpenRouterOptions>;
53
- export {};
@@ -5,9 +5,9 @@ import { extendProtocol } from '../../kernel/protocols/mod.js';
5
5
  import { openAi } from '../open-ai/protocol.js';
6
6
  import { collectReasoning } from './openai/reasoning-state.js';
7
7
  /** What is cached: the whole request (`automatic`) or the system instruction only (`system`). */
8
- const CACHE_MODES = ['automatic', 'system'];
8
+ export const CACHE_MODES = ['automatic', 'system'];
9
9
  /** How long OpenRouter's upstream keeps a cached prompt. */
10
- const CACHE_TTLS = ['5m', '1h'];
10
+ export const CACHE_TTLS = ['5m', '1h'];
11
11
  // labels-exempt: builder field description, read by the studio and docs
12
12
  const cache = z
13
13
  .strictObject({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.5-next.907.g49f9ef9",
3
+ "version": "0.3.5-next.911.g193d75c",
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",