@theoremjs/agents 0.3.4-next.542.g59bcbcf → 0.3.4-next.548.gbb156b2

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.
@@ -1,5 +1,6 @@
1
1
  import { attachmentIssues, resolveMediaLimits } from '../kernel/registry/attachments.js';
2
2
  import { mimeAllowed } from '../kernel/registry/catalog.js';
3
+ import { normalizeSlots } from '../kernel/registry/slots.js';
3
4
  const RECORDER_CANDIDATES = [
4
5
  'audio/webm;codecs=opus',
5
6
  'audio/webm',
@@ -23,7 +24,7 @@ function inputsFromSpec(inputs) {
23
24
  maxBytes: inputs?.maxBytes,
24
25
  maxTurnBytes: inputs?.maxTurnBytes,
25
26
  limitsByMime: inputs?.limitsByMime,
26
- slots: inputs?.slots,
27
+ slots: normalizeSlots(inputs?.slots),
27
28
  context: inputs?.context,
28
29
  };
29
30
  }
@@ -105,7 +105,15 @@ const inputs = z.object({
105
105
  maxBytes: z.number().optional(),
106
106
  maxTurnBytes: z.number().optional(),
107
107
  limitsByMime: z.record(z.string(), z.number()).optional(),
108
- slots: z.record(z.string(), z.array(z.string())).optional(),
108
+ slots: z
109
+ .record(z.string(), z.object({
110
+ label: z.string().optional(),
111
+ choices: z.array(z.object({
112
+ value: z.string(),
113
+ description: z.string().optional(),
114
+ })),
115
+ }))
116
+ .optional(),
109
117
  context: z.object({ from: z.array(z.enum(CONTEXT_SENDERS)), maxChars: z.number() }).optional(),
110
118
  });
111
119
  const resumption = z.object({
@@ -5,7 +5,7 @@ import type { LabelOverrides } from '../guardrails/labels.js';
5
5
  import type { ResolvedGuardrailPolicy } from '../guardrails/types.js';
6
6
  import type { ProfileToolsSpec, ToolCallEdit, ToolPhaseEvent } from '../kernel/tools/types.js';
7
7
  import type { ReasoningPart } from '../kernel/turn-events.js';
8
- import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOutputsSpec, ProviderEvidence, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
8
+ import type { AttachmentValidationIssue, CompactionSpec, GroundingEvent, ImageProfile, LiveProfile, ModelBinding, ModelId, ProfileContextSpec, ProfileOutputsSpec, ProviderEvidence, SlotDecl, Source, SpeechProfile, TextProfile, TurnStop, TurnTokens } from '../kernel/types.js';
9
9
  import type { ResolvedObservabilityPolicy } from '../observability/types.js';
10
10
  /** What a URL detector lets through besides the given URLs, with its defaults applied. */
11
11
  export interface UrlAllowView {
@@ -62,7 +62,8 @@ export interface ProfileInputsInterface {
62
62
  maxBytes?: number;
63
63
  maxTurnBytes?: number;
64
64
  limitsByMime?: Record<string, number>;
65
- slots?: Record<string, string[]>;
65
+ /** Normalized slot decls (`label?` + `choices`); legacy string lists are expanded upstream. */
66
+ slots?: Record<string, SlotDecl>;
66
67
  context?: ProfileContextSpec;
67
68
  }
68
69
  /**
@@ -47,6 +47,7 @@ export { createProfileRegistry, defineProfile } from './registry/profiles.js';
47
47
  export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
48
48
  export type { SchemaRegistry } from './registry/schemas.js';
49
49
  export { createSchemaRegistry } from './registry/schemas.js';
50
+ export { normalizeProfileInputsSlots, normalizeSlotDecl, normalizeSlots, slotValues, } from './registry/slots.js';
50
51
  export type { CredentialContext, CredentialResolver, KeyCredential } from './registry/vault.js';
51
52
  export type { AuthUnauthenticatedPolicy, CustomToolType, HttpMethod, StudioAuthType, ToolAccess, ToolAuthType, ToolPermission, ToolType, } from './schema.js';
52
53
  export { API_EXPORTS, ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, REQUEST_FIELDS, SPEECH_AUDIO_FORMATS, STREAM_MODES, STUDIO_AUTH_TYPES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
@@ -28,6 +28,7 @@ export { createKernelRegistry } from './registry/kernel-registry.js';
28
28
  export { createProfileRegistry, defineProfile } from './registry/profiles.js';
29
29
  export { projectProfileObject, requireModelProfile } from './registry/resolve.js';
30
30
  export { createSchemaRegistry } from './registry/schemas.js';
31
+ export { normalizeProfileInputsSlots, normalizeSlotDecl, normalizeSlots, slotValues, } from './registry/slots.js';
31
32
  export { API_EXPORTS, ATTACHMENT_ACCEPT_MIMES, AUTH_UNAUTHENTICATED_POLICIES, AWAITING_USER_INPUT_KINDS, AWAITING_USER_INPUT_STATUS, CACHE_MODES, CACHE_TTLS, COMPACTION_METERS, COMPACTION_OUTCOMES, COMPACTION_TIMINGS, CONTINUE_STOP_KINDS, catalogPathFor, EXTRA_FIELDS, fieldMeta, HTTP_METHODS, IMAGE_ATTACHMENT_ACCEPT_MIMES, isKeySlotName, isToolGateKind, isTurnInjectStage, isTurnStage, KEY_SLOT_NAME, MEDIA_INPUT_KIND_VALUES, MEDIA_INPUT_KINDS, MEDIA_WILDCARDS, PROFILE_FIELDS, PROFILE_HANDLE_MAX_CHARS, PROFILE_ID_MAX_CHARS, PROFILE_TYPES, REQUEST_FIELDS, SPEECH_AUDIO_FORMATS, STREAM_MODES, STUDIO_AUTH_TYPES, SUMMARY_MODES, THINKING_LEVELS, TOOL_ACCESS, TOOL_AUTH_TYPES, TOOL_GATE_KINDS, TOOL_LOAD_TIERS, TOOL_PERMISSION, TOOL_TYPES, TURN_INJECT_STAGES, TURN_STAGES, TURN_STOP_KINDS, VOICE_ACCEPT_MIMES, } from './schema.js';
32
33
  export { createKernelScope, defaultKernelScope } from './scope.js';
33
34
  export { applyStageResult, STAGE_AFFORDANCE_MATRIX, STAGE_AFFORDANCES, stageAllowsAffordance, stageEventFields, } from './stages.js';
@@ -7,6 +7,7 @@ import { CONTEXT_SENDERS } from '../schema.js';
7
7
  import { CONTINUE_INSTRUCTION_TYPES } from '../stop.js';
8
8
  import { isTurnMediaRef } from './attachments.js';
9
9
  import { mediaKindForMime, mimeEssence, profileInputs } from './catalog.js';
10
+ import { slotValues } from './slots.js';
10
11
  function activePrimaryOutputModes(profile, structuredId) {
11
12
  const modes = [];
12
13
  if (structuredId) {
@@ -149,10 +150,11 @@ function assertTurnSlots(profile, req) {
149
150
  return;
150
151
  const declared = profileInputs(profile)?.slots ?? {};
151
152
  for (const [key, value] of Object.entries(slots)) {
152
- const choices = Object.hasOwn(declared, key) ? declared[key] : undefined;
153
- if (!choices) {
153
+ const decl = Object.hasOwn(declared, key) ? declared[key] : undefined;
154
+ if (!decl) {
154
155
  throw new TheoremError('request', `Profile ${profile.id} has no slot '${key}'`);
155
156
  }
157
+ const choices = slotValues(decl);
156
158
  if (!choices.includes(value)) {
157
159
  throw new TheoremError('request', `Profile ${profile.id}: slot '${key}' takes ${choices.join(', ')}, not '${value}'`);
158
160
  }
@@ -15,6 +15,7 @@ import { assertSystemPrompt } from '../system-parts.js';
15
15
  import { profileToolAllow, profileToolsSpec } from '../tools/resolve.js';
16
16
  import { isTurnMediaRef } from './attachments.js';
17
17
  import { mediaKindForMime, mimeAllowed, profileInputs } from './catalog.js';
18
+ import { normalizeProfileInputsSlots, slotValues } from './slots.js';
18
19
  import { soleModelId } from './sole-model.js';
19
20
  function assertModelRoute(_profileId, _modelId, binding, _type) {
20
21
  if (!binding.provider?.trim() || !binding.apiId?.trim())
@@ -400,7 +401,7 @@ function defineProfile(input) {
400
401
  identity,
401
402
  ...modelFields,
402
403
  tools: input.tools,
403
- inputs: input.inputs,
404
+ inputs: normalizeProfileInputsSlots(input.inputs),
404
405
  outputs: input.outputs,
405
406
  turnBehaviour: input.turnBehaviour,
406
407
  guardrails,
@@ -416,7 +417,7 @@ function defineProfile(input) {
416
417
  ...modelFields,
417
418
  image: input.image,
418
419
  tools: input.tools,
419
- inputs: input.inputs,
420
+ inputs: normalizeProfileInputsSlots(input.inputs),
420
421
  outputs: input.outputs,
421
422
  turnBehaviour: input.turnBehaviour,
422
423
  guardrails,
@@ -447,7 +448,7 @@ function defineProfile(input) {
447
448
  identity,
448
449
  ...modelFields,
449
450
  live: input.live,
450
- inputs: input.inputs,
451
+ inputs: input.inputs ? normalizeProfileInputsSlots(input.inputs) : input.inputs,
451
452
  tools: { allow: input.tools.allow, ...optionalParallel(input.tools.parallel) },
452
453
  turnBehaviour: input.turnBehaviour,
453
454
  guardrails,
@@ -491,10 +492,11 @@ function assertStructuredSlot(profile) {
491
492
  const structured = profile.outputs?.structured;
492
493
  if (!structured || typeof structured === 'string')
493
494
  return;
494
- const choices = profileInputs(profile)?.slots?.[structured.by];
495
- if (!choices) {
495
+ const decl = profileInputs(profile)?.slots?.[structured.by];
496
+ if (!decl) {
496
497
  throw new TheoremError('config', `Profile ${profile.id}: outputs.structured.by '${structured.by}' is not a slot in inputs.slots`);
497
498
  }
499
+ const choices = slotValues(decl);
498
500
  const unknown = Object.keys(structured.map).filter((value) => !choices.includes(value));
499
501
  if (unknown.length) {
500
502
  throw new TheoremError('config', `Profile ${profile.id}: outputs.structured.map maps ${unknown.join(', ')}, not a choice of slot '${structured.by}'`);
@@ -0,0 +1,13 @@
1
+ /**
2
+ * Slot declaration helpers: normalize authoring forms and read choice values for
3
+ * validation and fillSlots. Descriptions and labels are UI-only.
4
+ */
5
+ import type { ProfileInputsSpec, SlotDecl, SlotDeclInput } from '../types.js';
6
+ /** The allowed values of one slot declaration (legacy list or labeled form). */
7
+ export declare function slotValues(decl: SlotDeclInput): string[];
8
+ /** Canonical slot declaration: always `{ choices }`, optional `label`. */
9
+ export declare function normalizeSlotDecl(decl: SlotDeclInput): SlotDecl;
10
+ /** Canonical `inputs.slots`, or undefined when none. */
11
+ export declare function normalizeSlots(slots: Record<string, SlotDeclInput> | undefined): Record<string, SlotDecl> | undefined;
12
+ /** Profile inputs with every slot normalized (labels/descriptions preserved). */
13
+ export declare function normalizeProfileInputsSlots<T extends ProfileInputsSpec | undefined>(inputs: T): T;
@@ -0,0 +1,31 @@
1
+ /** The allowed values of one slot declaration (legacy list or labeled form). */
2
+ export function slotValues(decl) {
3
+ return Array.isArray(decl) ? [...decl] : decl.choices.map((choice) => choice.value);
4
+ }
5
+ /** Canonical slot declaration: always `{ choices }`, optional `label`. */
6
+ export function normalizeSlotDecl(decl) {
7
+ if (Array.isArray(decl)) {
8
+ return { choices: decl.map((value) => ({ value })) };
9
+ }
10
+ return {
11
+ ...(decl.label !== undefined && decl.label !== '' ? { label: decl.label } : {}),
12
+ choices: decl.choices.map((choice) => ({
13
+ value: choice.value,
14
+ ...(choice.description !== undefined && choice.description !== ''
15
+ ? { description: choice.description }
16
+ : {}),
17
+ })),
18
+ };
19
+ }
20
+ /** Canonical `inputs.slots`, or undefined when none. */
21
+ export function normalizeSlots(slots) {
22
+ if (!slots)
23
+ return undefined;
24
+ return Object.fromEntries(Object.entries(slots).map(([name, decl]) => [name, normalizeSlotDecl(decl)]));
25
+ }
26
+ /** Profile inputs with every slot normalized (labels/descriptions preserved). */
27
+ export function normalizeProfileInputsSlots(inputs) {
28
+ if (!inputs?.slots)
29
+ return inputs;
30
+ return { ...inputs, slots: normalizeSlots(inputs.slots) };
31
+ }
@@ -585,8 +585,12 @@ export const PROFILE_FIELDS = withScopeAndPresence({
585
585
  'inputs.maxTurnBytes': field('number', 'The most bytes one turn or embedding request may send inline across all its files and clips.'),
586
586
  'inputs.limitsByMime': field('Record<string, number>', 'Size limits by file type that replace maxBytes for those types.'),
587
587
  'inputs.limitsByMime.*': field('number', 'The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.'),
588
- 'inputs.slots': field('Record<string, string[]>', 'Named choices a turn or a call can make, such as language, each with its allowed values. {name} in a prompt becomes the chosen value.'),
589
- 'inputs.slots.*': field('string[]', 'The values a turn may choose for this slot; any other is refused.'),
588
+ 'inputs.slots': field('Record<string, string[] | SlotDecl>', 'Named choices a turn or a call can make. A bare string list is the allowed values; an object may add a UI label and per-choice descriptions. {name} in a prompt becomes the chosen value string.'),
589
+ 'inputs.slots.*': field('string[] | SlotDecl', 'Either the allowed value strings, or { label?, choices: { value, description? }[] }. Descriptions are UI-only; value is what the turn sends and what {name} fills.'),
590
+ 'inputs.slots.*.label': field('string', 'Visitor-facing group title for this slot in the composer (for example Source Bias). Omit to show the slot name.'),
591
+ 'inputs.slots.*.choices': field('SlotChoice[]', 'The allowed values for this slot, each with an optional UI description.'),
592
+ 'inputs.slots.*.choices.*.value': field('string', 'The string the turn sends for this choice and that {name} substitutes into prompts.'),
593
+ 'inputs.slots.*.choices.*.description': field('string', 'Visitor-facing blurb for this choice in the composer. Never substituted into prompts.'),
590
594
  'inputs.context': field('{ from: ContextSender[]; maxChars: number }', 'Lets the page or the host send the agent one package of things to know, read at the context boundary.'),
591
595
  'inputs.context.from': field("Array<'client' | 'server'>", 'Who may send context; context from anyone else is refused.', CONTEXT_SENDERS, {
592
596
  client: 'The browser. A visitor can change it, so it is untrusted.',
@@ -1,5 +1,6 @@
1
1
  import { z } from 'zod';
2
2
  import { TheoremError } from '../../guardrails/error.js';
3
+ import { slotValues } from '../registry/slots.js';
3
4
  import { interactionPartSchema, keptReply, sourceSchema } from '../turn-events.js';
4
5
  import { findLast } from '../util/find-last.js';
5
6
  import { profileToolAllow } from './resolve.js';
@@ -32,7 +33,10 @@ const speechInput = z.strictObject({
32
33
  });
33
34
  /** One choice per declared slot; a slot or a value the profile does not declare is refused. */
34
35
  function slotsInput(slots) {
35
- return z.strictObject(Object.fromEntries(Object.entries(slots).map(([slot, choices]) => [slot, z.enum(choices).optional()])));
36
+ return z.strictObject(Object.fromEntries(Object.entries(slots).map(([slot, decl]) => {
37
+ const choices = slotValues(decl);
38
+ return [slot, z.enum(choices).optional()];
39
+ })));
36
40
  }
37
41
  /** The fields an agent tool's input can carry to the called agent; a host field takes none of these names. */
38
42
  const AGENT_INPUT_FIELDS = new Set([
@@ -313,6 +313,24 @@ export interface ProfileModelFields {
313
313
  /** Tool-loop ceiling. Omit = `DEFAULT_MAX_STEPS`; `1` = one-shot; `> 1` = hard cap. */
314
314
  maxSteps?: number;
315
315
  }
316
+ /**
317
+ * One allowed value for an `inputs.slots` entry. `value` is what the turn sends and what
318
+ * `{name}` fills; optional `description` is visitor-facing UI copy only.
319
+ */
320
+ export interface SlotChoice {
321
+ value: string;
322
+ description?: string;
323
+ }
324
+ /**
325
+ * One named slot: optional group `label` for the UI, and its choices. A bare `string[]` is
326
+ * still accepted on define and normalized to `{ choices: [{ value }] }`.
327
+ */
328
+ export interface SlotDecl {
329
+ label?: string;
330
+ choices: SlotChoice[];
331
+ }
332
+ /** Authoring form for one slot: legacy value list, or a labeled declaration. */
333
+ export type SlotDeclInput = string[] | SlotDecl;
316
334
  /** What a profile accepts as input. */
317
335
  export interface ProfileInputsSpec {
318
336
  text?: boolean;
@@ -326,7 +344,7 @@ export interface ProfileInputsSpec {
326
344
  maxBytes?: number;
327
345
  maxTurnBytes?: number;
328
346
  limitsByMime?: Record<string, number>;
329
- slots?: Record<string, string[]>;
347
+ slots?: Record<string, SlotDeclInput>;
330
348
  context?: ProfileContextSpec;
331
349
  }
332
350
  /** What a live profile declares beside its ingress channels. */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@theoremjs/agents",
3
- "version": "0.3.4-next.542.g59bcbcf",
3
+ "version": "0.3.4-next.548.gbb156b2",
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",