@theoremjs/studio 0.3.4-next.863.gb601f58 → 0.3.4-next.871.gea9bbcc
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/browser-connection.d.ts +12 -0
- package/draft.d.ts +26 -2
- package/map.d.ts +13 -0
- package/map.js +28 -0
- package/mod.d.ts +1 -1
- package/mod.js +1 -1
- package/package.json +4 -4
- package/page/assets/{BottomSheet-B8-prREc.js → BottomSheet-Ijd3-EiJ.js} +1 -1
- package/page/assets/{ConsoleFrame-CYYtfWNI.js → ConsoleFrame-sl_08t-S.js} +1 -1
- package/page/assets/{DateInput-CaOcecG2.js → DateInput-3xmp6QyV.js} +1 -1
- package/page/assets/{MenuBottomSheet-Ctymn_LQ.js → MenuBottomSheet-bFIiEbF_.js} +1 -1
- package/page/assets/{SchemaFields-D1_c3uax.js → SchemaFields-DHG2EecV.js} +1 -1
- package/page/assets/{TokenizerBottomSheet-BOahsgu5.js → TokenizerBottomSheet-C7wWNjLf.js} +1 -1
- package/page/assets/{ToolResultCharts-DxlRxTlp.js → ToolResultCharts-DFKefRvo.js} +1 -1
- package/page/assets/{Toolbar-DzqcK9Za.js → Toolbar-B0ZpvYnL.js} +1 -1
- package/page/assets/TraceInspector-ep2qcy9_.js +1 -0
- package/page/assets/TraceOverview-Yhf9L-7s.js +57 -0
- package/page/assets/{_virtual_studio-type-sources-DW2xrHRZ.js → _virtual_studio-type-sources-NQ8eY2_H.js} +1470 -320
- package/page/assets/browser-connection-Nwupg4Oq.js +1 -0
- package/page/assets/browser-engine-B9h8eThv.js +16 -0
- package/page/assets/browser-transport-BhFcGvWp.js +2 -0
- package/page/assets/compile-Brpb8u3_.js +2 -0
- package/page/assets/{encode-files-JlTZOKQT.js → encode-files-CQ_E7QUG.js} +1 -1
- package/page/assets/{export-agent-DbT9mJEv.js → export-agent-C1LknzFc.js} +1 -1
- package/page/assets/{guardrail-tester-XhX2mqHc.js → guardrail-tester-C188dNNz.js} +1 -1
- package/page/assets/{index-C1WNmgOO.js → index-Hix1w6kY.js} +73 -73
- package/page/assets/{json-code-DoIDKNEG.js → json-code-B13g9rlg.js} +1 -1
- package/page/assets/{labels-provider-Bv9WPagB.js → labels-provider-Cdg61Tfx.js} +1 -1
- package/page/assets/{live-messages-iGBTap-t.js → live-messages-CDqr92n4.js} +1 -1
- package/page/assets/{prompt-row-Bsz-A4Bf.js → prompt-row-DGE5h-0F.js} +1 -1
- package/page/assets/reader-CYeq9zud.js +5 -0
- package/page/assets/registry-Du0mj5wR.js +1 -0
- package/page/assets/{schema-DfEjr_N4.js → schema-Cra2BPNa.js} +2 -2
- package/page/assets/shaped-data-BlRLB3TY.js +25 -0
- package/page/assets/{stub-CsZVvwgT.js → stub-J7M8qV3l.js} +1 -1
- package/page/assets/{studio-code-pane-Db-AAr3b.js → studio-code-pane-BpYrChnW.js} +4 -4
- package/page/assets/{studio-console-71u2GwPw.js → studio-console-5ZwlH-1a.js} +1 -1
- package/page/assets/{studio-decision-BHPpdQM9.js → studio-decision-DaWLDjAy.js} +1 -1
- package/page/assets/{studio-embedding-VyWNTUU8.js → studio-embedding-DCMMMVFw.js} +1 -1
- package/page/assets/{studio-host-console-C1Rt8PSv.js → studio-host-console-CVKWwl3t.js} +2 -2
- package/page/assets/{studio-labels-EQRWPOr5.js → studio-labels-h-JoNVLI.js} +2 -2
- package/page/assets/{studio-live-D0pjddZ9.js → studio-live-DqPhe9Gd.js} +2 -2
- package/page/assets/studio-map-Dcz7oT-v.js +1 -0
- package/page/assets/studio-trace-replay-DLHxUh4T.js +3 -0
- package/page/assets/{studio-type-checker-dXJ4DZVL.js → studio-type-checker-DDcpR_0b.js} +1 -1
- package/page/assets/tool-schema-DWmQkthX.js +13 -0
- package/page/assets/trace-record-C07Cf_EG.js +1 -0
- package/page/assets/tree-CgaAoXtn.js +3 -0
- package/page/assets/{turn-client-CobwqNwm.js → turn-client-B4zazitl.js} +2 -2
- package/page/assets/{types-2sRz_M-W.js → types-D5agZBnA.js} +1 -1
- package/page/assets/{use-one-call-CMoYqsKk.js → use-one-call-Ds7HYrGe.js} +1 -1
- package/page/assets/{workspace-C7bvk7HE.js → workspace-Dsqtx6eI.js} +1 -1
- package/page/index.html +17 -17
- package/types.d.ts +10 -0
- package/ui/profile-editor.js +4 -4
- package/ui/studio-map.js +4 -13
- package/ui/studio-screen.js +20 -7
- package/page/assets/TraceInspector-BR3SDDuV.js +0 -1
- package/page/assets/TraceOverview-bvtLAnsR.js +0 -57
- package/page/assets/browser-connection-CA_G_F8Q.js +0 -1
- package/page/assets/browser-engine-DctWhKjF.js +0 -16
- package/page/assets/browser-transport-DVnbvtNO.js +0 -2
- package/page/assets/compile-CYYqzzo2.js +0 -2
- package/page/assets/reader-DhyhAoss.js +0 -5
- package/page/assets/registry-CtZn4S17.js +0 -1
- package/page/assets/shaped-data-CtJtZSw9.js +0 -21
- package/page/assets/studio-map-CpYHfNRm.js +0 -1
- package/page/assets/studio-trace-replay-B0O6qFwD.js +0 -3
- package/page/assets/tool-schema-hDeCZqPI.js +0 -17
- package/page/assets/trace-record-C-Opk3HK.js +0 -1
- package/page/assets/tree-Bo29WGA0.js +0 -3
|
@@ -4363,13 +4363,26 @@ export { bundledEgressAutomata, compileDetect, compileDetectTables, compiledDete
|
|
|
4363
4363
|
type HostPattern = {
|
|
4364
4364
|
/** What a match is called in the trace. */
|
|
4365
4365
|
name: string;
|
|
4366
|
-
/**
|
|
4366
|
+
/**
|
|
4367
|
+
* The source of a regular expression. A pattern takes this or words.
|
|
4368
|
+
*
|
|
4369
|
+
* @remarks The source of a regular expression.
|
|
4370
|
+
*/
|
|
4367
4371
|
pattern: string;
|
|
4368
|
-
/**
|
|
4372
|
+
/**
|
|
4373
|
+
* Regular-expression flags, each a letter: i ignores case, m matches ^ and $ at each line, s
|
|
4374
|
+
* lets . match a line break, u reads Unicode. Not g or y: every match is always found.
|
|
4375
|
+
*
|
|
4376
|
+
* @remarks Any of \`i\`, \`m\`, \`s\`, and \`u\`. Every match is found, so \`g\` is implied; \`y\` is
|
|
4377
|
+
* refused.
|
|
4378
|
+
*/
|
|
4369
4379
|
flags?: string;
|
|
4370
4380
|
} | {
|
|
4371
4381
|
/** What a match is called in the trace. */
|
|
4372
4382
|
name: string;
|
|
4383
|
+
/**
|
|
4384
|
+
* Words to match whole, whatever their case. A space in one matches any run of whitespace.
|
|
4385
|
+
*/
|
|
4373
4386
|
words: readonly string[];
|
|
4374
4387
|
};
|
|
4375
4388
|
/**
|
|
@@ -4463,45 +4476,90 @@ declare const DETECT_ACTIONS: readonly ["ignore", "flag", "redact", "block"];
|
|
|
4463
4476
|
type DetectAction = (typeof DETECT_ACTIONS)[number];
|
|
4464
4477
|
/** The addresses \`ungiven_images\` or \`ungiven_links\` lets through beyond the ones the model was given. */
|
|
4465
4478
|
interface UrlAllow {
|
|
4466
|
-
/**
|
|
4479
|
+
/**
|
|
4480
|
+
* Hostnames whose images load whatever their URL, such as your own CDN.
|
|
4481
|
+
*
|
|
4482
|
+
* @catalog guardrails.detect.ungiven_links.allow.hosts Hostnames whose links pass whatever their
|
|
4483
|
+
* URL; the hosts ungiven_images allows pass too.
|
|
4484
|
+
*
|
|
4485
|
+
* @remarks Hostnames let through whatever their URL, such as the host's own CDN.
|
|
4486
|
+
*/
|
|
4467
4487
|
hosts?: readonly string[];
|
|
4468
4488
|
/**
|
|
4469
|
-
* Whether a URL a tool returned counts as given.
|
|
4470
|
-
*
|
|
4489
|
+
* Whether a URL a tool returned counts as given. Off keeps only what the system prompt, the user,
|
|
4490
|
+
* and history gave.
|
|
4491
|
+
*
|
|
4492
|
+
* @remarks Whether a URL a tool returned counts as given. Default true. A tool result can offer
|
|
4493
|
+
* the model URLs to pick from, and the pick tells their server something; false closes that
|
|
4471
4494
|
* channel, and keeps only what the system prompt, the user, and host history gave.
|
|
4472
4495
|
*/
|
|
4473
4496
|
fromTools?: boolean;
|
|
4474
4497
|
}
|
|
4475
4498
|
/** The names \`tool_leak\` lets through. */
|
|
4476
4499
|
interface NameAllow {
|
|
4477
|
-
/**
|
|
4500
|
+
/**
|
|
4501
|
+
* Names of tools or parameters that are not read for, such as a tool called search.
|
|
4502
|
+
*
|
|
4503
|
+
* @remarks Names of tools or parameters that are innocent in a reply, such as a tool called
|
|
4504
|
+
* \`search\`.
|
|
4505
|
+
*/
|
|
4478
4506
|
names?: readonly string[];
|
|
4479
4507
|
}
|
|
4480
4508
|
/** A detector's setting in full. */
|
|
4481
4509
|
interface DetectorConfig {
|
|
4482
|
-
/**
|
|
4510
|
+
/**
|
|
4511
|
+
* What a match of this detector does at every boundary it reads, unless \`at\` names that boundary.
|
|
4512
|
+
*
|
|
4513
|
+
* @remarks The action at every boundary. Left out, each boundary keeps its default.
|
|
4514
|
+
*/
|
|
4483
4515
|
action?: DetectAction;
|
|
4484
|
-
/**
|
|
4516
|
+
/**
|
|
4517
|
+
* An action per boundary, over action or the default.
|
|
4518
|
+
*
|
|
4519
|
+
* @remarks An action for the boundaries it names, over \`action\` or the default.
|
|
4520
|
+
*/
|
|
4485
4521
|
at?: Partial<Record<Boundary, DetectAction>>;
|
|
4486
4522
|
/**
|
|
4487
|
-
* Whether Theorem
|
|
4488
|
-
*
|
|
4489
|
-
*
|
|
4523
|
+
* Whether Theorem’s own patterns run. Off with no patterns of your own turns the detector off.
|
|
4524
|
+
*
|
|
4525
|
+
* @remarks Whether Theorem's own patterns run. Default true. With \`patterns\` it gives the four
|
|
4526
|
+
* choices: both, only Theorem's, only the host's (\`false\` with patterns), or none (\`false\`
|
|
4527
|
+
* without). A detector that takes no patterns refuses it.
|
|
4490
4528
|
*/
|
|
4491
4529
|
theorem?: boolean;
|
|
4492
|
-
/**
|
|
4530
|
+
/**
|
|
4531
|
+
* Your own patterns, each a name and a regular expression or a list of words. A match takes this
|
|
4532
|
+
* detector’s action.
|
|
4533
|
+
*
|
|
4534
|
+
* @remarks The host's own patterns, read on the text as written. A detector that takes no
|
|
4535
|
+
* patterns refuses them.
|
|
4536
|
+
*/
|
|
4493
4537
|
patterns?: readonly HostPattern[];
|
|
4494
|
-
/**
|
|
4538
|
+
/**
|
|
4539
|
+
* The table your patterns compile to, from compileDetect or \`agents detect-compile\`. Needed
|
|
4540
|
+
* whenever patterns is set.
|
|
4541
|
+
*
|
|
4542
|
+
* @remarks The table compiled for \`patterns\` (\`compilePatterns\`, \`agents detect-compile\`).
|
|
4543
|
+
* Patterns need it.
|
|
4544
|
+
*/
|
|
4495
4545
|
compiled?: CompiledPatterns;
|
|
4496
4546
|
/**
|
|
4497
4547
|
* One line telling the model what to leave out, sent when this detector blocks a reply that is
|
|
4498
|
-
* then retried.
|
|
4499
|
-
*
|
|
4548
|
+
* then retried. Set it beside patterns of your own.
|
|
4549
|
+
*
|
|
4550
|
+
* @remarks One line telling the model what to leave out, sent when this detector blocks a reply
|
|
4551
|
+
* that is then retried. Left out, the labels' \`detect.hint.<detector>\`. Only beside \`patterns\`:
|
|
4552
|
+
* the labels' hint describes Theorem's patterns, not the host's.
|
|
4500
4553
|
*/
|
|
4501
4554
|
hint?: string;
|
|
4502
4555
|
/**
|
|
4503
|
-
* What
|
|
4504
|
-
*
|
|
4556
|
+
* What passes besides the URLs the model was given this turn.
|
|
4557
|
+
*
|
|
4558
|
+
* @catalog guardrails.detect.tool_leak.allow The names that are innocent in a reply.
|
|
4559
|
+
*
|
|
4560
|
+
* @remarks What the detector lets through: for \`ungiven_images\` and \`ungiven_links\` the addresses
|
|
4561
|
+
* besides the given ones, for \`tool_leak\` the names that are innocent. Any other detector refuses
|
|
4562
|
+
* it.
|
|
4505
4563
|
*/
|
|
4506
4564
|
allow?: UrlAllow | NameAllow;
|
|
4507
4565
|
}
|
|
@@ -4530,23 +4588,48 @@ type HostFind = (text: string, context: {
|
|
|
4530
4588
|
interface HostDetectorConfig {
|
|
4531
4589
|
/** What an editor and the trace call it. */
|
|
4532
4590
|
label: string;
|
|
4533
|
-
/**
|
|
4591
|
+
/**
|
|
4592
|
+
* What a match does, at every boundary.
|
|
4593
|
+
*
|
|
4594
|
+
* @remarks The action at every boundary. Left out, only the boundaries \`at\` names are read.
|
|
4595
|
+
*/
|
|
4534
4596
|
action?: DetectAction;
|
|
4535
|
-
/**
|
|
4597
|
+
/**
|
|
4598
|
+
* An action per boundary, over action.
|
|
4599
|
+
*
|
|
4600
|
+
* @remarks An action for the boundaries it names, over \`action\`.
|
|
4601
|
+
*/
|
|
4536
4602
|
at?: Partial<Record<Boundary, DetectAction>>;
|
|
4537
|
-
/**
|
|
4603
|
+
/**
|
|
4604
|
+
* Its patterns, each a name and a regular expression or a list of words, read on the text as
|
|
4605
|
+
* written.
|
|
4606
|
+
*
|
|
4607
|
+
* @remarks Its patterns, read on the text as written.
|
|
4608
|
+
*/
|
|
4538
4609
|
patterns?: readonly HostPattern[];
|
|
4539
|
-
/**
|
|
4610
|
+
/**
|
|
4611
|
+
* The table your patterns compile to, from compileDetect or \`agents detect-compile\`. Needed
|
|
4612
|
+
* whenever patterns is set.
|
|
4613
|
+
*
|
|
4614
|
+
* @remarks The table compiled for \`patterns\` (\`compilePatterns\`, \`agents detect-compile\`).
|
|
4615
|
+
* Patterns need it.
|
|
4616
|
+
*/
|
|
4540
4617
|
compiled?: CompiledPatterns;
|
|
4541
4618
|
/**
|
|
4542
|
-
* Its own reading
|
|
4619
|
+
* Its own reading, for what patterns cannot say: a function that returns where the matches start
|
|
4620
|
+
* and end. It runs on every text crossing a boundary the detector reads, so it returns at once.
|
|
4621
|
+
*
|
|
4622
|
+
* @remarks Its own reading. As a reply streams, a \`find\` reads the text held so far, and the last
|
|
4543
4623
|
* \`HOST_FIND_HOLD\` characters stay held (\`HOST_FIND_HOLD_LIVE\` in a Live reply): a match is
|
|
4544
4624
|
* caught whole when it is no longer than that.
|
|
4545
4625
|
*/
|
|
4546
4626
|
find?: HostFind;
|
|
4547
4627
|
/**
|
|
4548
4628
|
* One line telling the model what to leave out, sent when this detector blocks a reply that is
|
|
4549
|
-
* then retried.
|
|
4629
|
+
* then retried.
|
|
4630
|
+
*
|
|
4631
|
+
* @remarks One line telling the model what to leave out, sent when this detector blocks a reply
|
|
4632
|
+
* that is then retried. Left out, the labels' \`detect.hint.own\`, which names the label.
|
|
4550
4633
|
*/
|
|
4551
4634
|
hint?: string;
|
|
4552
4635
|
}
|
|
@@ -4896,7 +4979,11 @@ export interface ProviderDefinition<C = unknown, K = unknown> {
|
|
|
4896
4979
|
}
|
|
4897
4980
|
/** A provider as defined; register it to use it. */
|
|
4898
4981
|
export type Provider<C = unknown, K = unknown> = Readonly<ProviderDefinition<C, K>>;
|
|
4899
|
-
/**
|
|
4982
|
+
/**
|
|
4983
|
+
* Validates a provider definition and supplies its typed model helper.
|
|
4984
|
+
*
|
|
4985
|
+
* @remarks Defines a provider. Nothing in it can change a request or read a reply.
|
|
4986
|
+
*/
|
|
4900
4987
|
export declare function defineProvider<C = undefined, K = undefined>(definition: ProviderDefinition<C, K>): Provider<C, K>;
|
|
4901
4988
|
/** What a builder sets when registering a provider. */
|
|
4902
4989
|
export interface Registration<C> {
|
|
@@ -5205,14 +5292,23 @@ export declare function carriesTo(writer: string, target: Pick<Protocol, 'lineag
|
|
|
5205
5292
|
`,"file:///node_modules/@theoremjs/agents/src/kernel/protocols/limits.d.ts":`import { z } from 'zod';
|
|
5206
5293
|
/** The budgets a provider call runs under. Each one left out is no limit: the provider's own applies. */
|
|
5207
5294
|
export interface ProviderLimits {
|
|
5295
|
+
/** How long one call may take, in milliseconds, retries included. */
|
|
5208
5296
|
operationTimeoutMs?: number;
|
|
5297
|
+
/** How long a live session may take to open, in milliseconds. */
|
|
5209
5298
|
connectTimeoutMs?: number;
|
|
5299
|
+
/** How long a live session may wait for the model to answer, in milliseconds. */
|
|
5210
5300
|
liveStepTimeoutMs?: number;
|
|
5301
|
+
/** The most bytes in one record the provider sends: a stream event or a socket message. */
|
|
5211
5302
|
maxWireRecordBytes?: number;
|
|
5303
|
+
/** The most bytes the provider sends for one step. */
|
|
5212
5304
|
maxWireResponseBytes?: number;
|
|
5305
|
+
/** The most bytes in one event of a step. */
|
|
5213
5306
|
maxEventBytes?: number;
|
|
5307
|
+
/** The most bytes in all the events of one step. */
|
|
5214
5308
|
maxStepBytes?: number;
|
|
5309
|
+
/** The most events in one step. */
|
|
5215
5310
|
maxStepEvents?: number;
|
|
5311
|
+
/** The most tool calls one step may ask for. */
|
|
5216
5312
|
maxPendingToolCalls?: number;
|
|
5217
5313
|
}
|
|
5218
5314
|
export declare const providerLimitsSchema: z.ZodType<ProviderLimits>;
|
|
@@ -5252,16 +5348,43 @@ export type ProfileId = string;
|
|
|
5252
5348
|
export type ChatRole = 'system' | 'user' | 'assistant';
|
|
5253
5349
|
/** Host strings (presets own the vocabularies); an unpinned value is the provider default. */
|
|
5254
5350
|
export interface ProfileImageSpec {
|
|
5351
|
+
/** The shape of generated images, such as 16:9. */
|
|
5255
5352
|
aspectRatio?: string;
|
|
5353
|
+
/** How detailed generated images are, such as 1K, 2K or 4K. */
|
|
5256
5354
|
resolution?: string;
|
|
5355
|
+
/**
|
|
5356
|
+
* The file type of generated images; a provider that takes a fixed set of types may use png for
|
|
5357
|
+
* any other.
|
|
5358
|
+
*/
|
|
5257
5359
|
mimeType?: string;
|
|
5360
|
+
/**
|
|
5361
|
+
* How much effort the model spends on each image: auto, low, medium, or high. A provider that has
|
|
5362
|
+
* no such setting refuses it.
|
|
5363
|
+
*/
|
|
5258
5364
|
quality?: string;
|
|
5365
|
+
/**
|
|
5366
|
+
* The background of generated images: auto, transparent, or opaque. A provider that has no such
|
|
5367
|
+
* setting refuses it.
|
|
5368
|
+
*/
|
|
5259
5369
|
background?: string;
|
|
5370
|
+
/** How many images one request makes, where the provider takes a count. */
|
|
5260
5371
|
n?: number;
|
|
5372
|
+
/** A seed for repeatable images, where the provider and the model honour it. */
|
|
5261
5373
|
seed?: number;
|
|
5374
|
+
/** Compression from 0 to 100 for jpeg and webp images, where the provider takes it. */
|
|
5262
5375
|
outputCompression?: number;
|
|
5376
|
+
/**
|
|
5377
|
+
* Images sent with every turn, before the user's. Each is bytes (\`data\`) or a link (\`uri\`). Some
|
|
5378
|
+
* providers take http(s) links only, and none with includeText.
|
|
5379
|
+
*/
|
|
5263
5380
|
references?: Array<TurnBlob | TurnMediaRef>;
|
|
5264
|
-
/**
|
|
5381
|
+
/**
|
|
5382
|
+
* Whether the model may write text alongside its images; with some providers this also sends the
|
|
5383
|
+
* system instruction and history.
|
|
5384
|
+
*
|
|
5385
|
+
* @remarks Also request interleaved text with the images (Google: text + image
|
|
5386
|
+
* \`response_format\`).
|
|
5387
|
+
*/
|
|
5265
5388
|
includeText?: boolean;
|
|
5266
5389
|
}
|
|
5267
5390
|
import type { DecisionModelBinding, ModelBinding } from './protocols/binding.js';
|
|
@@ -5290,60 +5413,110 @@ export interface CompactionTriggerContext {
|
|
|
5290
5413
|
/** When history compacts and how: the meter, the token budget, and the compactor. */
|
|
5291
5414
|
export interface CompactionSpec {
|
|
5292
5415
|
/**
|
|
5293
|
-
*
|
|
5294
|
-
*
|
|
5416
|
+
* The token budget compactAt is a fraction of.
|
|
5417
|
+
*
|
|
5418
|
+
* @remarks Token budget compared by the trigger (\`compactAt * maxTokens\`). Meaning depends on
|
|
5419
|
+
* \`meter\`: history budget vs full-prompt input budget.
|
|
5295
5420
|
*/
|
|
5296
5421
|
maxTokens: number;
|
|
5297
|
-
/**
|
|
5422
|
+
/**
|
|
5423
|
+
* The fraction of maxTokens, between 0 and 1, at which compaction starts, unless trigger decides.
|
|
5424
|
+
*
|
|
5425
|
+
* @remarks Fraction of \`maxTokens\` at which compaction fires. Must be in (0, 1).
|
|
5426
|
+
*/
|
|
5298
5427
|
compactAt: number;
|
|
5299
5428
|
/**
|
|
5300
|
-
*
|
|
5429
|
+
* How much recent history compaction keeps: a number of exchanges (1 or more), a fraction of
|
|
5430
|
+
* maxTokens below compactAt, or 0 to compact it all.
|
|
5431
|
+
*
|
|
5432
|
+
* @remarks Recent exchanges kept verbatim (an exchange is a user message and everything up to the
|
|
5301
5433
|
* next one). \`≥ 1\` = exchange count, \`(0, 1)\` = fraction of \`maxTokens\`, \`0\` = compact all.
|
|
5302
5434
|
*/
|
|
5303
5435
|
previousExchanges: number;
|
|
5304
5436
|
/**
|
|
5305
|
-
*
|
|
5306
|
-
*
|
|
5437
|
+
* The text profile that writes the summary; register it before this one. Leave it out and a text
|
|
5438
|
+
* agent summarises its own history, with its own instructions and model and no tools. Its
|
|
5439
|
+
* registered model binding selects the provider independently of the calling agent.
|
|
5440
|
+
*
|
|
5441
|
+
* @remarks Profile id of the compaction agent. Must be registered before the owning profile. Omit
|
|
5442
|
+
* it and the agent compacts its own history: the same instructions and model, no tools.
|
|
5307
5443
|
*/
|
|
5308
5444
|
profile?: ProfileId;
|
|
5309
5445
|
/**
|
|
5310
|
-
*
|
|
5446
|
+
* Whether the kernel compacts before the turn or tells the host to compact after it.
|
|
5447
|
+
*
|
|
5448
|
+
* @remarks When compaction runs relative to the primary turn.
|
|
5311
5449
|
* - \`'before'\`: kernel compacts synchronously before the turn; user pays latency on this turn.
|
|
5312
5450
|
* - \`'after'\`: kernel signals in the \`done\` event; host runs compaction asynchronously.
|
|
5313
5451
|
*/
|
|
5314
5452
|
timing: CompactionTiming;
|
|
5315
5453
|
/**
|
|
5316
|
-
*
|
|
5317
|
-
*
|
|
5318
|
-
*
|
|
5454
|
+
* What the threshold counts.
|
|
5455
|
+
*
|
|
5456
|
+
* @remarks Threshold meter. Defaults to \`'history'\`. Use \`'input'\` when the host prefers provider
|
|
5457
|
+
* full-prompt usage (after subtracting a known baseline in \`maxTokens\` / \`compactAt\`).
|
|
5319
5458
|
*/
|
|
5320
5459
|
meter?: CompactionMeter;
|
|
5321
|
-
/**
|
|
5460
|
+
/**
|
|
5461
|
+
* Your function that decides when to compact, in place of compactAt and maxTokens.
|
|
5462
|
+
*
|
|
5463
|
+
* @remarks Replaces the default \`tokens > compactAt * maxTokens\` check.
|
|
5464
|
+
*/
|
|
5322
5465
|
trigger?: (ctx: CompactionTriggerContext) => boolean | Promise<boolean>;
|
|
5323
5466
|
}
|
|
5324
5467
|
/** What every request that runs a model takes: how to stop it, and where its trace goes. */
|
|
5325
5468
|
export interface RunControls {
|
|
5326
|
-
/**
|
|
5469
|
+
/**
|
|
5470
|
+
* Stops the run when it aborts, and cancels its provider call where the provider can.
|
|
5471
|
+
*
|
|
5472
|
+
* @remarks Stops the run when it aborts, and cancels in-flight provider HTTP where the adapter
|
|
5473
|
+
* supports it.
|
|
5474
|
+
*/
|
|
5327
5475
|
signal?: AbortSignal;
|
|
5328
|
-
/**
|
|
5476
|
+
/**
|
|
5477
|
+
* Your own values, kept on the trace; Theorem does not read them.
|
|
5478
|
+
*
|
|
5479
|
+
* @remarks Host-owned metadata preserved on the run's trace records; the kernel does not
|
|
5480
|
+
* interpret it.
|
|
5481
|
+
*/
|
|
5329
5482
|
metadata?: Record<string, unknown>;
|
|
5330
5483
|
/**
|
|
5331
|
-
* W3C
|
|
5332
|
-
*
|
|
5484
|
+
* The W3C traceparent of your span; the run's trace joins it as a child.
|
|
5485
|
+
*
|
|
5486
|
+
* @remarks W3C \`traceparent\` of the host span this run goes under. The run's root span joins that
|
|
5487
|
+
* trace as its child; without it the run starts a new trace. A malformed value throws.
|
|
5333
5488
|
*/
|
|
5334
5489
|
traceparent?: string;
|
|
5335
5490
|
/** Your project id, recorded on the trace. */
|
|
5336
5491
|
projectId?: string;
|
|
5337
|
-
/**
|
|
5492
|
+
/**
|
|
5493
|
+
* Your conversation id, recorded on the trace.
|
|
5494
|
+
*
|
|
5495
|
+
* @remarks Host conversation id, recorded as \`gen_ai.conversation.id\`.
|
|
5496
|
+
*/
|
|
5338
5497
|
conversationId?: string;
|
|
5339
|
-
/**
|
|
5498
|
+
/**
|
|
5499
|
+
* Earlier traces this run follows: a resume, a continue, or a retry.
|
|
5500
|
+
*
|
|
5501
|
+
* @remarks Earlier traces this run follows.
|
|
5502
|
+
*/
|
|
5340
5503
|
links?: TurnTraceLink[];
|
|
5341
5504
|
}
|
|
5342
5505
|
/** Which of the profile's models a run uses, and how hard it thinks. */
|
|
5343
5506
|
export interface ModelChoice {
|
|
5344
|
-
/**
|
|
5507
|
+
/**
|
|
5508
|
+
* The model id the turn or session picks from the profile's models; refused unless the profile
|
|
5509
|
+
* sets allowModelSelect.
|
|
5510
|
+
*
|
|
5511
|
+
* @remarks Selected model id when \`profile.allowModelSelect\` is true.
|
|
5512
|
+
*/
|
|
5345
5513
|
model?: ModelId;
|
|
5346
|
-
/**
|
|
5514
|
+
/**
|
|
5515
|
+
* The effort the turn or session picks from the model's efforts; refused unless the model sets
|
|
5516
|
+
* allowEffortSelect.
|
|
5517
|
+
*
|
|
5518
|
+
* @remarks Selected effort alias when the binding has \`allowEffortSelect\`.
|
|
5519
|
+
*/
|
|
5347
5520
|
effort?: string;
|
|
5348
5521
|
}
|
|
5349
5522
|
/** \`compactHistory\` input, for \`timing: 'after'\`: the host passes back what \`done.compaction\` carried. */
|
|
@@ -5358,6 +5531,7 @@ export interface CompactHistoryRequest extends RunControls {
|
|
|
5358
5531
|
}
|
|
5359
5532
|
/** A structured-output schema given inline. */
|
|
5360
5533
|
export interface StructuredSpec {
|
|
5534
|
+
/** The JSON Schema a structured reply must follow, sent to the model as its response format. */
|
|
5361
5535
|
jsonSchema: Record<string, unknown>;
|
|
5362
5536
|
}
|
|
5363
5537
|
/** Caps on the files a turn may attach. */
|
|
@@ -5434,39 +5608,90 @@ export type ProfileItemCheck = (item: unknown, turn: ItemCheckTurn) => Validatio
|
|
|
5434
5608
|
* rewrite the refused items alone, then removes any that are refused again.
|
|
5435
5609
|
*/
|
|
5436
5610
|
export interface ProfileItemRule {
|
|
5611
|
+
/**
|
|
5612
|
+
* Your check on one item, given what the tools of the turn returned (turn.toolResults); its error
|
|
5613
|
+
* is the reason the model reads on a rewrite and the host reads on the removed item.
|
|
5614
|
+
*/
|
|
5437
5615
|
check: ProfileItemCheck;
|
|
5616
|
+
/**
|
|
5617
|
+
* drop removes a refused item. fix first asks the model to rewrite the refused items alone, once
|
|
5618
|
+
* and while retries remain, then removes any refused again. Removed items leave on the structured
|
|
5619
|
+
* event as removed.
|
|
5620
|
+
*/
|
|
5438
5621
|
onFail: 'drop' | 'fix';
|
|
5439
5622
|
}
|
|
5440
5623
|
/** Host validators a profile runs on its structured output. */
|
|
5441
5624
|
export interface ProfileValidationSpec {
|
|
5442
5625
|
/**
|
|
5443
|
-
*
|
|
5444
|
-
*
|
|
5445
|
-
*
|
|
5626
|
+
* Your checks, each keyed by a dotted path into the structured reply, such as diagram.mermaid; a
|
|
5627
|
+
* path no structured schema reaches is refused when the profile registers.
|
|
5628
|
+
*
|
|
5629
|
+
* @remarks Host domain validators keyed by dotted paths into structured output (e.g.
|
|
5630
|
+
* \`diagram.mermaid\`). Presence/required is owned by the JSON Schema; these run only for required
|
|
5631
|
+
* paths and for optional paths that are present.
|
|
5632
|
+
*
|
|
5633
|
+
* @catalog outputs.validation.fields.* Your check on this part of the reply, reached through object properties only; a failure sends its error back to the model to rewrite while retries remain.
|
|
5446
5634
|
*/
|
|
5447
5635
|
fields?: Record<string, ProfileValidator>;
|
|
5448
|
-
/**
|
|
5636
|
+
/**
|
|
5637
|
+
* Your checks on the items of a list, each keyed by the dotted path of that list in the
|
|
5638
|
+
* structured reply, such as claims; a path no structured schema reaches as a list is refused when
|
|
5639
|
+
* the profile registers.
|
|
5640
|
+
*
|
|
5641
|
+
* @remarks Host checks on list items, keyed by the dotted path of a list in the structured
|
|
5642
|
+
* output.
|
|
5643
|
+
*
|
|
5644
|
+
* @catalog outputs.validation.items.* Your check on each item of this list. A refused item never fails the reply and the rest of the reply is kept.
|
|
5645
|
+
*/
|
|
5449
5646
|
items?: Record<string, ProfileItemRule>;
|
|
5647
|
+
/**
|
|
5648
|
+
* How many times the model may rewrite a reply that fails your checks or the schema's required
|
|
5649
|
+
* keys before it goes out as it is; under sse, an attempt that gets rewritten has already
|
|
5650
|
+
* streamed. A rewrite of a blocked reply (guardrails.blockedReply) counts against this too.
|
|
5651
|
+
*/
|
|
5450
5652
|
maxRetries?: number;
|
|
5451
5653
|
}
|
|
5452
5654
|
/** \`voice\` is the TTS voice id, not ingress audio (\`inputs.voice\`). */
|
|
5453
5655
|
export interface ProfileSpeechSpec {
|
|
5656
|
+
/**
|
|
5657
|
+
* The voice the speech is read in, by the provider's own name for it; a turn's speech.voice
|
|
5658
|
+
* replaces it.
|
|
5659
|
+
*/
|
|
5454
5660
|
voice?: string;
|
|
5455
|
-
/**
|
|
5661
|
+
/**
|
|
5662
|
+
* How the script is delivered, in plain words (pace, mood, accent); it is never read aloud, and a
|
|
5663
|
+
* turn's speech.style replaces it. A model that takes no direction ignores it.
|
|
5664
|
+
*
|
|
5665
|
+
* @remarks How the script is delivered, in plain words: pace, mood, accent. Never read aloud.
|
|
5666
|
+
*/
|
|
5456
5667
|
style?: string;
|
|
5457
|
-
/**
|
|
5668
|
+
/**
|
|
5669
|
+
* The speaking rate, where 1 is the voice's own pace; a turn's speech.speed replaces it. A
|
|
5670
|
+
* provider that has no rate refuses it or ignores it.
|
|
5671
|
+
*
|
|
5672
|
+
* @remarks The speaking rate; 1 is the voice's own pace.
|
|
5673
|
+
*/
|
|
5458
5674
|
speed?: number;
|
|
5459
|
-
/**
|
|
5675
|
+
/**
|
|
5676
|
+
* The audio encoding each turn's speech comes back in, and so what the host plays or stores.
|
|
5677
|
+
*
|
|
5678
|
+
* @remarks A provider that cannot make the format refuses the turn.
|
|
5679
|
+
*/
|
|
5460
5680
|
format?: SpeechAudioFormat;
|
|
5461
5681
|
}
|
|
5462
5682
|
/** What one speech turn sets for itself; each field given replaces the profile's \`speech\` field of that name. */
|
|
5463
5683
|
export type TurnSpeech = Pick<ProfileSpeechSpec, 'voice' | 'style' | 'speed'>;
|
|
5464
5684
|
/** Voice activity detection settings for a live session. */
|
|
5465
5685
|
export interface LiveVadSpec {
|
|
5686
|
+
/** Whether the user speaking interrupts the model's reply. */
|
|
5466
5687
|
activityHandling?: LiveActivityHandling;
|
|
5688
|
+
/** How readily the session decides the user has started speaking. */
|
|
5467
5689
|
startSensitivity?: LiveStartSensitivity;
|
|
5690
|
+
/** How readily the session decides the user has stopped speaking. */
|
|
5468
5691
|
endSensitivity?: LiveEndSensitivity;
|
|
5692
|
+
/** How long speech must last, in milliseconds, before it counts as the user starting to speak. */
|
|
5469
5693
|
prefixPaddingMs?: number;
|
|
5694
|
+
/** How long a silence, in milliseconds, ends the user's speech. */
|
|
5470
5695
|
silenceDurationMs?: number;
|
|
5471
5696
|
}
|
|
5472
5697
|
/**
|
|
@@ -5476,25 +5701,37 @@ export interface LiveVadSpec {
|
|
|
5476
5701
|
*/
|
|
5477
5702
|
export interface LiveContextCompressionSpec {
|
|
5478
5703
|
/**
|
|
5479
|
-
*
|
|
5480
|
-
*
|
|
5481
|
-
*
|
|
5704
|
+
* The context size, in tokens, that starts trimming.
|
|
5705
|
+
*
|
|
5706
|
+
* @remarks Context tokens, counted before a turn, that start compression. A whole number above 0.
|
|
5707
|
+
* Omit → provider default (Gemini: 80% of the model's context window).
|
|
5482
5708
|
*/
|
|
5483
5709
|
triggerTokens?: number;
|
|
5484
|
-
/**
|
|
5710
|
+
/**
|
|
5711
|
+
* Trims by dropping the oldest turns; the system instruction stays.
|
|
5712
|
+
*
|
|
5713
|
+
* @remarks Drops the oldest turns; the system instruction stays. Gemini's only mechanism.
|
|
5714
|
+
*/
|
|
5485
5715
|
slidingWindow: LiveSlidingWindowSpec;
|
|
5486
5716
|
}
|
|
5487
5717
|
/** Sliding-window context compression for a live session. */
|
|
5488
5718
|
export interface LiveSlidingWindowSpec {
|
|
5489
5719
|
/**
|
|
5490
|
-
*
|
|
5491
|
-
*
|
|
5720
|
+
* The context size, in tokens, to trim down to; below the trigger.
|
|
5721
|
+
*
|
|
5722
|
+
* @remarks Tokens to keep after compressing. A whole number above 0, below \`triggerTokens\`. Omit
|
|
5723
|
+
* → provider default (Gemini: half of \`triggerTokens\`).
|
|
5492
5724
|
*/
|
|
5493
5725
|
targetTokens?: number;
|
|
5494
5726
|
}
|
|
5495
5727
|
/** Which sides of a live session are transcribed. */
|
|
5496
5728
|
export interface LiveTranscriptionSpec {
|
|
5729
|
+
/** Whether the user's speech is transcribed. */
|
|
5497
5730
|
input?: boolean;
|
|
5731
|
+
/**
|
|
5732
|
+
* Whether the model's speech is transcribed; always on while a detector reads live_reply, since
|
|
5733
|
+
* it reads the transcript.
|
|
5734
|
+
*/
|
|
5498
5735
|
output?: boolean;
|
|
5499
5736
|
}
|
|
5500
5737
|
/**
|
|
@@ -5503,37 +5740,87 @@ export interface LiveTranscriptionSpec {
|
|
|
5503
5740
|
* \`LiveSession.sendAudio\` / \`sendVideo\` / \`sendText\` channels.
|
|
5504
5741
|
*/
|
|
5505
5742
|
export interface LiveIngressSpec {
|
|
5506
|
-
/**
|
|
5743
|
+
/**
|
|
5744
|
+
* Whether the session accepts microphone audio.
|
|
5745
|
+
*
|
|
5746
|
+
* @remarks Microphone PCM via \`sendAudio\`. Omit → enabled.
|
|
5747
|
+
*/
|
|
5507
5748
|
audio?: boolean;
|
|
5508
|
-
/**
|
|
5749
|
+
/**
|
|
5750
|
+
* Whether the session accepts camera frames.
|
|
5751
|
+
*
|
|
5752
|
+
* @remarks Webcam JPEG frames via \`sendVideo\`. Omit → enabled.
|
|
5753
|
+
*/
|
|
5509
5754
|
video?: boolean;
|
|
5510
|
-
/**
|
|
5755
|
+
/**
|
|
5756
|
+
* Whether the session accepts typed text.
|
|
5757
|
+
*
|
|
5758
|
+
* @remarks Typed text via \`sendText\`. Omit → disabled (opt-in).
|
|
5759
|
+
*/
|
|
5511
5760
|
text?: boolean;
|
|
5512
5761
|
}
|
|
5513
5762
|
/** The prompt a resumed call opens with, and how long away earns it. */
|
|
5514
5763
|
export interface LiveResumedSpec {
|
|
5764
|
+
/**
|
|
5765
|
+
* A prompt the call sends itself when it resumes, so the agent says it is back. The visitor does
|
|
5766
|
+
* not see it. It may use {name}, and is not sent when an option it prints is unset.
|
|
5767
|
+
*/
|
|
5515
5768
|
prompt: string;
|
|
5516
|
-
/**
|
|
5769
|
+
/**
|
|
5770
|
+
* The shortest time away, in milliseconds, that earns the prompt; a shorter drop resumes
|
|
5771
|
+
* silently.
|
|
5772
|
+
*
|
|
5773
|
+
* @remarks The shortest time away, in milliseconds, the agent remarks on. Omit →
|
|
5774
|
+
* \`DEFAULT_RESUMED_AFTER_MS\`.
|
|
5775
|
+
*/
|
|
5517
5776
|
afterMs?: number;
|
|
5518
5777
|
}
|
|
5519
5778
|
/** The settings only a live profile has: ingress, voice, detection, windowing, transcription, and resumption. */
|
|
5520
5779
|
export interface ProfileLiveSpec {
|
|
5780
|
+
/** Which channels the session accepts from the user. */
|
|
5521
5781
|
ingress?: LiveIngressSpec;
|
|
5782
|
+
/** The voice the model speaks in. */
|
|
5522
5783
|
voice?: string;
|
|
5784
|
+
/** How the session detects when the user starts and stops speaking. */
|
|
5523
5785
|
vad?: LiveVadSpec;
|
|
5786
|
+
/**
|
|
5787
|
+
* Whether the provider sends resume handles, which the host can pass to a new session to carry
|
|
5788
|
+
* this one on.
|
|
5789
|
+
*/
|
|
5524
5790
|
sessionResumption?: boolean;
|
|
5525
|
-
/**
|
|
5791
|
+
/**
|
|
5792
|
+
* A prompt the call sends itself when it opens new, so the agent speaks first. The visitor does
|
|
5793
|
+
* not see it. It may use {name}, and is not sent when an option it prints is unset.
|
|
5794
|
+
*
|
|
5795
|
+
* @remarks A prompt the session sends itself when a call opens new, so the agent speaks first.
|
|
5796
|
+
* Omit → the agent waits.
|
|
5797
|
+
*/
|
|
5526
5798
|
greeting?: string;
|
|
5527
|
-
/**
|
|
5799
|
+
/**
|
|
5800
|
+
* What happens when a call comes back after a drop. It needs live.sessionResumption.
|
|
5801
|
+
*
|
|
5802
|
+
* @remarks What the agent is prompted with when a call resumes after the caller was away. Omit →
|
|
5803
|
+
* a resumed call is silent.
|
|
5804
|
+
*/
|
|
5528
5805
|
resumed?: LiveResumedSpec;
|
|
5529
|
-
/**
|
|
5806
|
+
/**
|
|
5807
|
+
* Trims the session's context once it grows past the trigger.
|
|
5808
|
+
*
|
|
5809
|
+
* @remarks Context window compression. Omit → none: the provider ends the session at its limit.
|
|
5810
|
+
*/
|
|
5530
5811
|
contextCompression?: LiveContextCompressionSpec;
|
|
5812
|
+
/** Text transcripts of the session's speech. */
|
|
5531
5813
|
transcription?: LiveTranscriptionSpec;
|
|
5532
5814
|
}
|
|
5533
5815
|
/** How a profile's reply streams. */
|
|
5534
5816
|
export interface ProfileStreamingSpec {
|
|
5817
|
+
/** Whether the reply reaches the host as the model writes it, or whole. */
|
|
5535
5818
|
mode?: StreamMode;
|
|
5536
|
-
/**
|
|
5819
|
+
/**
|
|
5820
|
+
* Whether the model's thinking reaches the host.
|
|
5821
|
+
*
|
|
5822
|
+
* @remarks When false, filter \`thought\` events from the turn stream.
|
|
5823
|
+
*/
|
|
5537
5824
|
streamThoughts?: boolean;
|
|
5538
5825
|
}
|
|
5539
5826
|
export type { MediaTurnBehaviourSpec, ProfileTurnBehaviourSpec, ProfileTurnResumptionSpec, TurnContinueFrom, TurnStop, } from './stop.js';
|
|
@@ -5557,46 +5844,105 @@ export interface ProfileModelFields {
|
|
|
5557
5844
|
}
|
|
5558
5845
|
/** One value an option can take. \`description\` is what a picker shows beside it. */
|
|
5559
5846
|
export interface OptionChoice {
|
|
5847
|
+
/**
|
|
5848
|
+
* The value the code sets, which \`when\` reads and {name} prints.
|
|
5849
|
+
*
|
|
5850
|
+
* @catalog inputs.options.*.choices.*.value The value the turn sends for this choice, which
|
|
5851
|
+
* \`when\` reads and {name} prints.
|
|
5852
|
+
*/
|
|
5560
5853
|
value: string;
|
|
5854
|
+
/**
|
|
5855
|
+
* What this value means. It is never sent to the model.
|
|
5856
|
+
*
|
|
5857
|
+
* @catalog inputs.options.*.choices.*.description Visitor-facing blurb for this choice in the
|
|
5858
|
+
* composer. Never substituted into prompts.
|
|
5859
|
+
*/
|
|
5561
5860
|
description?: string;
|
|
5562
5861
|
}
|
|
5563
5862
|
/** One named option: its \`label\` for a picker, and the values it can take. */
|
|
5564
5863
|
export interface OptionDecl {
|
|
5864
|
+
/**
|
|
5865
|
+
* A person-readable title. Omit to show the option's name.
|
|
5866
|
+
*
|
|
5867
|
+
* @catalog inputs.options.*.label Visitor-facing title for this option in the composer (for
|
|
5868
|
+
* example Source Bias). Omit to show the option's name.
|
|
5869
|
+
*/
|
|
5565
5870
|
label?: string;
|
|
5871
|
+
/**
|
|
5872
|
+
* The values this option can take.
|
|
5873
|
+
*
|
|
5874
|
+
* @catalog inputs.options.*.choices The values this option can take, each with an optional UI
|
|
5875
|
+
* description.
|
|
5876
|
+
*/
|
|
5566
5877
|
choices: OptionChoice[];
|
|
5567
5878
|
}
|
|
5568
5879
|
/** A profile's options by name. Which object holds them says who drives them. */
|
|
5569
5880
|
export type ProfileOptions = Readonly<Record<string, OptionDecl>>;
|
|
5570
5881
|
/** What a profile accepts as input. */
|
|
5571
5882
|
export interface ProfileInputsSpec {
|
|
5883
|
+
/** Whether a turn may send text. */
|
|
5572
5884
|
text?: boolean;
|
|
5885
|
+
/** Lets turns send files. */
|
|
5573
5886
|
attachments?: {
|
|
5887
|
+
/**
|
|
5888
|
+
* The file types a turn may send, where type/* matches a whole family; image profiles take only
|
|
5889
|
+
* images, video, and PDF.
|
|
5890
|
+
*/
|
|
5574
5891
|
accept: string[];
|
|
5575
5892
|
};
|
|
5893
|
+
/** Lets turns send voice clips. A transcription profile must set it. */
|
|
5576
5894
|
voice?: {
|
|
5577
|
-
accept: string[];
|
|
5895
|
+
/** The audio types a voice clip may be; audio/* matches them all. */ accept: string[];
|
|
5578
5896
|
};
|
|
5897
|
+
/** The most files and voice clips one turn or embedding request may send, counted together. */
|
|
5579
5898
|
maxFiles?: number;
|
|
5899
|
+
/** The largest file or clip, in bytes, a turn or embedding request may send inline. */
|
|
5580
5900
|
maxBytes?: number;
|
|
5901
|
+
/**
|
|
5902
|
+
* The most bytes one turn or embedding request may send inline across all its files and clips.
|
|
5903
|
+
*/
|
|
5581
5904
|
maxTurnBytes?: number;
|
|
5905
|
+
/**
|
|
5906
|
+
* Size limits by file type that replace maxBytes for those types.
|
|
5907
|
+
*
|
|
5908
|
+
* @catalog inputs.limitsByMime.* The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.
|
|
5909
|
+
*/
|
|
5582
5910
|
limitsByMime?: Record<string, number>;
|
|
5583
|
-
/**
|
|
5911
|
+
/**
|
|
5912
|
+
* The options a person picks, each shown as a picker. A prompt reads one as "when reader is
|
|
5913
|
+
* student: …" and prints it as {reader}.
|
|
5914
|
+
*
|
|
5915
|
+
* @remarks The options a person picks: a host shows each one as a picker.
|
|
5916
|
+
* @catalog inputs.options.* { label?, choices: { value, description? }[] }. Value is what the turn sends and what {name} prints.
|
|
5917
|
+
*/
|
|
5584
5918
|
options?: ProfileOptions;
|
|
5919
|
+
/**
|
|
5920
|
+
* Lets the page or the host send the agent one package of things to know, read at the context
|
|
5921
|
+
* boundary.
|
|
5922
|
+
*/
|
|
5585
5923
|
context?: ProfileContextSpec;
|
|
5586
5924
|
}
|
|
5587
5925
|
/** What a live profile declares beside its ingress channels. */
|
|
5588
5926
|
export type LiveInputsSpec = Pick<ProfileInputsSpec, 'options' | 'context'>;
|
|
5589
5927
|
/** Who may send a turn its context, and how much. */
|
|
5590
5928
|
export interface ProfileContextSpec {
|
|
5929
|
+
/** Who may send context; context from anyone else is refused. */
|
|
5591
5930
|
from: ContextSender[];
|
|
5931
|
+
/** The longest package, in characters of its JSON, each sender may send. */
|
|
5592
5932
|
maxChars: number;
|
|
5593
5933
|
}
|
|
5594
5934
|
/** The context each sender gives a turn: any JSON, or text. */
|
|
5595
5935
|
export type TurnContext = Partial<Record<ContextSender, unknown>>;
|
|
5596
5936
|
/** What a profile returns: its structured schema, validation, and streaming. */
|
|
5597
5937
|
export interface ProfileOutputsSpec {
|
|
5938
|
+
/**
|
|
5939
|
+
* The registered JSON schema the reply must follow, which can vary by option; register it before
|
|
5940
|
+
* the profile.
|
|
5941
|
+
*/
|
|
5598
5942
|
structured?: StructuredSchemaId | StructuredByOption | null;
|
|
5943
|
+
/** Your checks on a structured reply, and how many rewrites a failure gets. */
|
|
5599
5944
|
validation?: ProfileValidationSpec;
|
|
5945
|
+
/** How the reply reaches the host, and whether its thinking does. */
|
|
5600
5946
|
streaming?: ProfileStreamingSpec;
|
|
5601
5947
|
}
|
|
5602
5948
|
/** Text a reply may not repeat when the rest of its prompt is marked shareable. */
|
|
@@ -5622,9 +5968,26 @@ export interface SystemPiece {
|
|
|
5622
5968
|
}
|
|
5623
5969
|
/** A profile's handle and system prompt. */
|
|
5624
5970
|
export interface ProfileIdentity {
|
|
5971
|
+
/**
|
|
5972
|
+
* The name hosts and users see for this agent, at most 32 characters; the model never sees it.
|
|
5973
|
+
*/
|
|
5625
5974
|
handle: string;
|
|
5626
|
-
/**
|
|
5975
|
+
/**
|
|
5976
|
+
* The options the host's code sets on runTurn, which a person never sees. A line of
|
|
5977
|
+
* identity.system reads one as "when plan is free: …" and prints it as {plan}. One named path
|
|
5978
|
+
* holds the turn's path.
|
|
5979
|
+
*
|
|
5980
|
+
* @remarks The options the host's code states. A person never sees them.
|
|
5981
|
+
* @catalog identity.options.* { label?, choices: { value, description? }[] }, the same shape as inputs.options.*.
|
|
5982
|
+
*/
|
|
5627
5983
|
options?: ProfileOptions;
|
|
5984
|
+
/**
|
|
5985
|
+
* The instruction the model gets, as one string or a list of lines; some providers send it for an
|
|
5986
|
+
* image profile only with includeText on. A line that opens "when plan is free: …" goes only on
|
|
5987
|
+
* turns where that fits, and every line that fits is sent, a blank line apart. A line can be a
|
|
5988
|
+
* list of parts; mark what must not leak as { private: text }; only that is guarded. With none,
|
|
5989
|
+
* the whole prompt is.
|
|
5990
|
+
*/
|
|
5628
5991
|
system?: ProfileSystem;
|
|
5629
5992
|
}
|
|
5630
5993
|
/** The fields every profile type shares. */
|
|
@@ -5648,7 +6011,12 @@ export type DecisionJson = null | string | number | boolean | DecisionJson[] | {
|
|
|
5648
6011
|
};
|
|
5649
6012
|
/** What a decision profile accepts: JSON state up to a byte cap. */
|
|
5650
6013
|
export interface DecisionInputsSpec {
|
|
6014
|
+
/** A decision reads JSON state, passed on each call. */
|
|
5651
6015
|
state: 'json';
|
|
6016
|
+
/**
|
|
6017
|
+
* The largest state, in bytes, a decision call may send; larger state is refused before it leaves
|
|
6018
|
+
* your process.
|
|
6019
|
+
*/
|
|
5652
6020
|
maxStateBytes?: number;
|
|
5653
6021
|
}
|
|
5654
6022
|
/**
|
|
@@ -5666,6 +6034,10 @@ export interface DecisionProfile {
|
|
|
5666
6034
|
models: Record<ModelId, DecisionModelBinding>;
|
|
5667
6035
|
inputs: DecisionInputsSpec;
|
|
5668
6036
|
decision: {
|
|
6037
|
+
/**
|
|
6038
|
+
* Your name for this decision, on its traces. Not sent to the model. Not checked against the
|
|
6039
|
+
* questions.
|
|
6040
|
+
*/
|
|
5669
6041
|
contract: DecisionContractId;
|
|
5670
6042
|
};
|
|
5671
6043
|
guardrails?: DecisionGuardrailsSpec;
|
|
@@ -5783,13 +6155,29 @@ export type EmbeddingInput = string | {
|
|
|
5783
6155
|
};
|
|
5784
6156
|
/** A profile's accepted embedding input kinds and limits. */
|
|
5785
6157
|
export interface EmbeddingInputsSpec {
|
|
6158
|
+
/** Whether a turn may send text. */
|
|
5786
6159
|
text?: boolean;
|
|
6160
|
+
/** Lets turns send files. */
|
|
5787
6161
|
attachments?: {
|
|
6162
|
+
/**
|
|
6163
|
+
* The file types a turn may send, where type/* matches a whole family; image profiles take only
|
|
6164
|
+
* images, video, and PDF.
|
|
6165
|
+
*/
|
|
5788
6166
|
accept: string[];
|
|
5789
6167
|
};
|
|
6168
|
+
/** The most files and voice clips one turn or embedding request may send, counted together. */
|
|
5790
6169
|
maxFiles?: number;
|
|
6170
|
+
/** The largest file or clip, in bytes, a turn or embedding request may send inline. */
|
|
5791
6171
|
maxBytes?: number;
|
|
6172
|
+
/**
|
|
6173
|
+
* The most bytes one turn or embedding request may send inline across all its files and clips.
|
|
6174
|
+
*/
|
|
5792
6175
|
maxTurnBytes?: number;
|
|
6176
|
+
/**
|
|
6177
|
+
* Size limits by file type that replace maxBytes for those types.
|
|
6178
|
+
*
|
|
6179
|
+
* @catalog inputs.limitsByMime.* The largest file of this type (or type/* family), in bytes, a turn or embedding request may send inline.
|
|
6180
|
+
*/
|
|
5793
6181
|
limitsByMime?: Record<string, number>;
|
|
5794
6182
|
}
|
|
5795
6183
|
/** A profile that returns vectors instead of a model turn. */
|
|
@@ -5942,26 +6330,57 @@ export interface TurnRepairRequest {
|
|
|
5942
6330
|
}
|
|
5943
6331
|
/** What the user sent for a turn: text, options, attachments, voice, and history. */
|
|
5944
6332
|
export interface TurnInput {
|
|
6333
|
+
/** The user's message. */
|
|
5945
6334
|
text?: string;
|
|
5946
|
-
/**
|
|
6335
|
+
/**
|
|
6336
|
+
* The value a person picked for each option in the profile's inputs.options; an option or a value
|
|
6337
|
+
* the profile does not declare is refused.
|
|
6338
|
+
*
|
|
6339
|
+
* @remarks The value picked for each of the profile's \`inputs.options\`.
|
|
6340
|
+
*/
|
|
5947
6341
|
options?: Readonly<Record<string, string>>;
|
|
5948
|
-
/**
|
|
6342
|
+
/**
|
|
6343
|
+
* What the page (client) or the host (server) wants the model to know, as any JSON or text; a
|
|
6344
|
+
* sender the profile's inputs.context does not list, or a package over its maxChars, is refused.
|
|
6345
|
+
*
|
|
6346
|
+
* @remarks What the page or the host wants the model to know, by sender; the profile's
|
|
6347
|
+
* \`inputs.context\` allows it.
|
|
6348
|
+
*/
|
|
5949
6349
|
context?: TurnContext;
|
|
6350
|
+
/**
|
|
6351
|
+
* Files sent with the turn, as bytes or as a provider file reference; each must pass the
|
|
6352
|
+
* profile's inputs.attachments.
|
|
6353
|
+
*/
|
|
5950
6354
|
attachments?: Array<TurnBlob | TurnMediaRef>;
|
|
6355
|
+
/** Recorded speech sent with the turn; each must pass the profile's inputs.voice. */
|
|
5951
6356
|
voice?: TurnBlob[];
|
|
6357
|
+
/** The earlier messages of the conversation, when the host keeps them. */
|
|
5952
6358
|
history?: TurnHistoryMessage[];
|
|
5953
|
-
/**
|
|
6359
|
+
/**
|
|
6360
|
+
* Background tool calls that settled after their turn, as the host stored them. The model reads
|
|
6361
|
+
* each as a tool result, and this reply counts it as a remote read when the call was remote. Pass
|
|
6362
|
+
* each one once: the turn emits it as a late_results event, so a history built from events holds
|
|
6363
|
+
* it.
|
|
6364
|
+
*
|
|
6365
|
+
* @remarks Tool calls that settled after their turn, as the host stored them. Each counts as read
|
|
6366
|
+
* in this reply.
|
|
6367
|
+
*/
|
|
5954
6368
|
lateResults?: ToolOperationOutcome[];
|
|
6369
|
+
/** A reply your host rejected and why, so that the model writes it again. */
|
|
5955
6370
|
repair?: TurnRepairRequest;
|
|
5956
6371
|
/**
|
|
5957
|
-
*
|
|
5958
|
-
*
|
|
6372
|
+
* Your count of the history's tokens, used by compaction that meters history.
|
|
6373
|
+
*
|
|
6374
|
+
* @remarks Optional host-supplied history token count for \`meter: 'history'\`. When set, overrides
|
|
6375
|
+
* the local history estimate. Not full-prompt API tokens.
|
|
5959
6376
|
*/
|
|
5960
6377
|
historyTokens?: number;
|
|
5961
6378
|
/**
|
|
5962
|
-
*
|
|
5963
|
-
*
|
|
5964
|
-
*
|
|
6379
|
+
* Your count of the whole prompt's tokens, used by compaction that meters input before the call.
|
|
6380
|
+
*
|
|
6381
|
+
* @remarks Optional host-supplied full-prompt input token count for \`meter: 'input'\` with
|
|
6382
|
+
* \`timing: 'before'\` (typically the previous turn's \`tokens.input\`). Ignored when \`meter\` is
|
|
6383
|
+
* \`'history'\`.
|
|
5965
6384
|
*/
|
|
5966
6385
|
inputTokens?: number;
|
|
5967
6386
|
}
|
|
@@ -5983,94 +6402,164 @@ export interface TurnTraceLink {
|
|
|
5983
6402
|
}
|
|
5984
6403
|
/** What \`runTurn\` and \`runSession\` both take: an agent's profile, its model, and the host's hooks and keys. */
|
|
5985
6404
|
export interface AgentRunRequest extends RunControls, ModelChoice {
|
|
6405
|
+
/** Host-owned atomic tool claims and outcomes. Never sent to providers. */
|
|
5986
6406
|
execution?: ToolExecutionCoordinator;
|
|
6407
|
+
/**
|
|
6408
|
+
* Host-issued service for tool calls that go on after their reply. It needs a coordinator with
|
|
6409
|
+
* detach. Without it every tool runs inline.
|
|
6410
|
+
*/
|
|
5987
6411
|
background?: ToolBackgroundService;
|
|
6412
|
+
/** Host-issued browser dispatch with a claimed operation and correlated result. */
|
|
5988
6413
|
pageExecution?: PageToolExecution;
|
|
6414
|
+
/** Native provider state saved alongside portable history. */
|
|
5989
6415
|
providerState?: ProviderCheckpoint;
|
|
6416
|
+
/** The id of the registered profile the turn or session runs. */
|
|
5990
6417
|
profile: ProfileId;
|
|
5991
6418
|
/**
|
|
5992
|
-
* Args for
|
|
5993
|
-
*
|
|
6419
|
+
* Args for the provider's own tools on the chosen model's builtInTools, by tool id; each is
|
|
6420
|
+
* checked by the schema the provider declares for that tool.
|
|
6421
|
+
*
|
|
6422
|
+
* @remarks Args for built-in tools on the chosen model's \`builtInTools\`, by tool id. Each is
|
|
6423
|
+
* parsed by the schema the provider's adapter declares for that tool.
|
|
5994
6424
|
*/
|
|
5995
6425
|
builtInArgs?: BuiltInArgs;
|
|
5996
|
-
/**
|
|
6426
|
+
/**
|
|
6427
|
+
* An instruction for this request only, added to the profile's own.
|
|
6428
|
+
*
|
|
6429
|
+
* @remarks Host-provided dynamic system prompt combined with profile persona
|
|
6430
|
+
*/
|
|
5997
6431
|
system?: SystemPrompt;
|
|
6432
|
+
/** The tools the user has already approved for this session. */
|
|
5998
6433
|
sessionPermissions?: string[];
|
|
5999
|
-
/**
|
|
6434
|
+
/**
|
|
6435
|
+
* The channel the turn or session comes from; only tools whose paths name it, or *, are offered.
|
|
6436
|
+
*
|
|
6437
|
+
* @remarks Host channel/path for catalog \`paths\` filtering.
|
|
6438
|
+
*/
|
|
6000
6439
|
path?: string;
|
|
6001
|
-
/**
|
|
6440
|
+
/**
|
|
6441
|
+
* The value the host's code sets for each option in the profile's identity.options but path; an
|
|
6442
|
+
* option or a value the profile does not declare is refused.
|
|
6443
|
+
*
|
|
6444
|
+
* @remarks This run's value for each of \`profile.identity.options\` it sets; \`path\` is the run's
|
|
6445
|
+
* own.
|
|
6446
|
+
*/
|
|
6002
6447
|
options?: Readonly<Record<string, string>>;
|
|
6003
6448
|
/**
|
|
6004
|
-
*
|
|
6005
|
-
*
|
|
6006
|
-
*
|
|
6449
|
+
* Your own context, handed to tool handlers as ctx.host; Theorem never reads or records it.
|
|
6450
|
+
*
|
|
6451
|
+
* @remarks Opaque application context handed to tool \`handler\` / \`preTool\` and \`tools.t1Policy\`
|
|
6452
|
+
* as \`ctx.host\`. The kernel never reads, logs, traces, or serializes it.
|
|
6007
6453
|
*/
|
|
6008
6454
|
host?: unknown;
|
|
6009
|
-
/**
|
|
6455
|
+
/**
|
|
6456
|
+
* Where an HTTP or MCP tool gets the credential for its auth slot.
|
|
6457
|
+
*
|
|
6458
|
+
* @remarks Credentials for authenticated HTTP / MCP tools, read by auth slot when a tool needs
|
|
6459
|
+
* one.
|
|
6460
|
+
*/
|
|
6010
6461
|
credentials?: ToolCredentialSource;
|
|
6011
6462
|
/**
|
|
6012
|
-
* Resolves
|
|
6013
|
-
*
|
|
6463
|
+
* Resolves the host name of a remote tool before each request; a name that resolves to a private
|
|
6464
|
+
* address is refused.
|
|
6465
|
+
*
|
|
6466
|
+
* @remarks Resolves remote tool and OAuth host names before each request; a name that resolves to
|
|
6467
|
+
* a private address is refused (see \`fetchGuarded\`).
|
|
6014
6468
|
*/
|
|
6015
6469
|
resolveHost?: ResolveHost;
|
|
6016
6470
|
/**
|
|
6017
|
-
* Sends each request a remote tool makes
|
|
6018
|
-
*
|
|
6019
|
-
*
|
|
6471
|
+
* Sends each request a remote tool makes, once that request's network checks pass. A page whose
|
|
6472
|
+
* tools cannot reach a host directly sends them through its own server here.
|
|
6473
|
+
*
|
|
6474
|
+
* @remarks Sends each request a remote tool makes (HTTP, MCP, a signed-in fetch, an image read),
|
|
6475
|
+
* once that request's network checks pass. A page whose tools cannot reach a host directly sends
|
|
6476
|
+
* them through its own server here. Default: the global \`fetch\`.
|
|
6020
6477
|
*/
|
|
6021
6478
|
fetch?: typeof fetch;
|
|
6022
|
-
/**
|
|
6479
|
+
/**
|
|
6480
|
+
* Your function that sees each stage of a text turn or a live session, and can answer with what
|
|
6481
|
+
* the stage allows.
|
|
6482
|
+
*
|
|
6483
|
+
* @remarks Text \`runTurn\` and \`runSession\` emit stages and apply the returned affordances. A
|
|
6484
|
+
* session's is set once.
|
|
6485
|
+
*/
|
|
6023
6486
|
onStage?: StageHandler;
|
|
6024
6487
|
/**
|
|
6025
|
-
* Runs before each agent tool call
|
|
6026
|
-
*
|
|
6027
|
-
*
|
|
6488
|
+
* Runs before each agent tool call, to shape the request to the called agent or to refuse the
|
|
6489
|
+
* call.
|
|
6490
|
+
*
|
|
6491
|
+
* @remarks Runs before each agent tool call in this run, and in the turns those calls run. Shape
|
|
6492
|
+
* the called agent's request (history, model, provider) or refuse the call. Omit it: the agent
|
|
6493
|
+
* runs on what the model sent.
|
|
6028
6494
|
*/
|
|
6029
6495
|
onAgentCall?: AgentCallHook;
|
|
6030
6496
|
}
|
|
6031
6497
|
/** A request to \`runTurn\`: the shared controls and the turn's input. */
|
|
6032
6498
|
export interface TurnRequest extends AgentRunRequest {
|
|
6033
6499
|
/**
|
|
6034
|
-
*
|
|
6035
|
-
*
|
|
6500
|
+
* A session key that OpenRouter uses for routing and caching.
|
|
6501
|
+
*
|
|
6502
|
+
* @remarks Sticky routing / cache session key for OpenRouter (\`session_id\`). Not the same as
|
|
6503
|
+
* \`projectId\` or Gemini \`previousInteractionId\`.
|
|
6036
6504
|
*/
|
|
6037
6505
|
sessionId?: string;
|
|
6038
|
-
/**
|
|
6506
|
+
/**
|
|
6507
|
+
* This turn's voice, style, and speed; each one given replaces the profile's speech field of that
|
|
6508
|
+
* name. Refused on a profile that is not speech.
|
|
6509
|
+
*
|
|
6510
|
+
* @remarks This turn's voice, style, and speed, over \`profile.speech\`. Speech profiles only.
|
|
6511
|
+
*/
|
|
6039
6512
|
speech?: TurnSpeech;
|
|
6040
6513
|
/**
|
|
6041
|
-
*
|
|
6042
|
-
*
|
|
6043
|
-
*
|
|
6044
|
-
*
|
|
6514
|
+
* Continues a turn that stopped in a way the profile lets a turn continue.
|
|
6515
|
+
*
|
|
6516
|
+
* @remarks Continue a prior resumeable stop. On text profiles the turn's user message is the
|
|
6517
|
+
* continue instruction (no \`input.text\`); the host passes the partial reply as the last assistant
|
|
6518
|
+
* message in \`input.history\`. Image and speech re-send the original request unchanged.
|
|
6045
6519
|
*/
|
|
6046
6520
|
continueFrom?: TurnContinueFrom;
|
|
6047
6521
|
/**
|
|
6048
|
-
*
|
|
6049
|
-
*
|
|
6522
|
+
* Which continue attempt this is, from 1; checked against the maxContinues of the profile.
|
|
6523
|
+
*
|
|
6524
|
+
* @remarks 1-based continue attempt when \`continueFrom\` is set. Compared to
|
|
6525
|
+
* \`profile.turnBehaviour.resumption.maxContinues\` when that cap is set.
|
|
6050
6526
|
*/
|
|
6051
6527
|
continuation?: number;
|
|
6052
6528
|
/**
|
|
6053
|
-
* Tools this reply already had when an earlier run of it paused
|
|
6054
|
-
* list
|
|
6055
|
-
*
|
|
6529
|
+
* Tools this reply already had when an earlier run of it paused; the turn opens with them on its
|
|
6530
|
+
* list.
|
|
6531
|
+
*
|
|
6532
|
+
* @remarks Tools this reply already had when an earlier run of it paused. The turn opens with
|
|
6533
|
+
* them on its list, so an answered call does not take back what the model loaded. An id
|
|
6534
|
+
* \`tools.allow\` or the path does not grant is left out, as for \`tools.t1Policy\`.
|
|
6056
6535
|
*/
|
|
6057
6536
|
promoted?: ToolId[];
|
|
6058
6537
|
/**
|
|
6059
|
-
* Steps this reply already took when an earlier run of it paused
|
|
6060
|
-
*
|
|
6538
|
+
* Steps this reply already took when an earlier run of it paused; they count against maxSteps.
|
|
6539
|
+
*
|
|
6540
|
+
* @remarks Steps this reply already took when an earlier run of it paused. They count against
|
|
6541
|
+
* \`maxSteps\`, so an answered call does not give the reply its steps back. Read \`done.steps\`.
|
|
6061
6542
|
*/
|
|
6062
6543
|
stepsTaken?: number;
|
|
6063
6544
|
/**
|
|
6064
|
-
* Reads each of
|
|
6065
|
-
*
|
|
6066
|
-
*
|
|
6545
|
+
* Reads each of the turn's events as it leaves runTurn, before the caller gets it. A throw ends
|
|
6546
|
+
* the turn with that error.
|
|
6547
|
+
*
|
|
6548
|
+
* @remarks Reads each of this turn's events as it leaves \`runTurn\`, before the caller gets it.
|
|
6549
|
+
* The app sets it in \`TurnWiring.prepare\` to act on a turn someone else runs, such as saving the
|
|
6550
|
+
* reply when \`done\` arrives. A throw ends the turn with that error. \`invokeTool\` does not call
|
|
6551
|
+
* it.
|
|
6067
6552
|
*/
|
|
6068
6553
|
onEvent?: (event: TurnEvent) => void | Promise<void>;
|
|
6069
6554
|
/**
|
|
6070
|
-
* Set on the turn
|
|
6071
|
-
* model runs and
|
|
6555
|
+
* Set on the turn TurnWiring.prepare is given for a held call that goes on once answered: no
|
|
6556
|
+
* model runs, and input is the paused turn's.
|
|
6557
|
+
*
|
|
6558
|
+
* @remarks Set on the turn \`TurnWiring.prepare\` is given for a held call that goes on once
|
|
6559
|
+
* answered. No model runs and \`input\` is the paused turn's, so it is not a new message.
|
|
6072
6560
|
*/
|
|
6073
6561
|
answersHeldCall?: true;
|
|
6562
|
+
/** What the user sent for the turn. */
|
|
6074
6563
|
input?: TurnInput;
|
|
6075
6564
|
}
|
|
6076
6565
|
/**
|
|
@@ -6306,26 +6795,39 @@ export declare const AUTO_CONTINUE_DELAY_MS = 1500;
|
|
|
6306
6795
|
/** Which stops a profile offers Continue for, and which the host continues on its own. */
|
|
6307
6796
|
export interface ProfileTurnResumptionSpec {
|
|
6308
6797
|
/**
|
|
6309
|
-
*
|
|
6310
|
-
*
|
|
6311
|
-
*
|
|
6798
|
+
* Which early stops the host offers the user a Continue for; the kernel doesn't refuse a continue
|
|
6799
|
+
* after other stops.
|
|
6800
|
+
*
|
|
6801
|
+
* @remarks The host's UI policy for offering Continue: the kernel does not refuse a
|
|
6802
|
+
* \`continueFrom\` outside it, since a continue is one more turn the host could send as plain text
|
|
6803
|
+
* anyway. Omit → length / stream_incomplete / provider_error; \`[]\` = none.
|
|
6312
6804
|
*/
|
|
6313
6805
|
allowContinue?: ContinueStopKind[];
|
|
6314
6806
|
/**
|
|
6315
|
-
*
|
|
6316
|
-
*
|
|
6317
|
-
*
|
|
6318
|
-
*
|
|
6319
|
-
*
|
|
6320
|
-
*
|
|
6321
|
-
*
|
|
6322
|
-
*
|
|
6323
|
-
*
|
|
6807
|
+
* Which early stops are continued without asking, whether or not allowContinue offers a Continue
|
|
6808
|
+
* for them. When set, a text turn sends a listed failed model call that gave no reply again
|
|
6809
|
+
* itself; the host continues the rest. Naming length also repairs a call the output limit cut
|
|
6810
|
+
* off: the model gets back what it wrote, or that it wrote nothing, and is asked again to fit.
|
|
6811
|
+
*
|
|
6812
|
+
* @remarks Omit → length / stream_incomplete; \`[]\` = none. Apart from \`allowContinue\`: a stop can
|
|
6813
|
+
* be continued without Continue being offered for it. The host sends the \`continueFrom\` turn with
|
|
6814
|
+
* \`continuation\`. A text turn also sends a failed model call (\`provider_error\`,
|
|
6815
|
+
* \`stream_incomplete\`) again itself when this list is set and names that stop, and the call gave
|
|
6816
|
+
* no reply and no tool call: the turn keeps its history, its step count and what it has read. A
|
|
6817
|
+
* failure the same call would meet again (the provider refused the request) is not sent again,
|
|
6818
|
+
* except once without its files when it carried any: accepted that way, the turn goes on and
|
|
6819
|
+
* \`done.mediaRefused\` names them. Named here, \`length\` also repairs a call the output limit cut
|
|
6820
|
+
* off: the model gets back what it wrote, or that it wrote nothing, and is asked again to fit.
|
|
6821
|
+
* Omitted, a turn sends nothing again.
|
|
6324
6822
|
*/
|
|
6325
6823
|
autoContinue?: ContinueStopKind[];
|
|
6326
6824
|
/**
|
|
6327
|
-
*
|
|
6328
|
-
* calls one text turn sends again itself
|
|
6825
|
+
* How many times one reply may be continued; once set, each continue must say which one it is.
|
|
6826
|
+
* Also how many model calls one text turn sends again itself, failed calls and cut-off repairs
|
|
6827
|
+
* together (one when unset).
|
|
6828
|
+
*
|
|
6829
|
+
* @remarks Compared against \`TurnRequest.continuation\`; omit → no count cap. Also how many model
|
|
6830
|
+
* calls one text turn sends again itself, failed calls and cut-off repairs together; omit → one.
|
|
6329
6831
|
*/
|
|
6330
6832
|
maxContinues?: number;
|
|
6331
6833
|
}
|
|
@@ -6336,12 +6838,20 @@ export declare function isContinueStopKind(kind: string): kind is ContinueStopKi
|
|
|
6336
6838
|
* interfaces always project \`canStop: true\` because \`TurnRequest.signal\` is always wired.
|
|
6337
6839
|
*/
|
|
6338
6840
|
export interface ProfileTurnBehaviourSpec {
|
|
6841
|
+
/** Continuing a reply that stopped early; live uses sessionResumption instead. */
|
|
6339
6842
|
resumption?: ProfileTurnResumptionSpec;
|
|
6340
|
-
/**
|
|
6843
|
+
/**
|
|
6844
|
+
* Lets your onStage hook add messages to a running turn. Text profiles also let the user steer.
|
|
6845
|
+
*
|
|
6846
|
+
* @remarks Default true on text / live. Gates injects only; stage events still emit.
|
|
6847
|
+
*/
|
|
6341
6848
|
allowSteering?: boolean;
|
|
6342
6849
|
/**
|
|
6343
|
-
*
|
|
6344
|
-
*
|
|
6850
|
+
* What happens when a turn reaches maxSteps while the model still wants tools: the turn stops
|
|
6851
|
+
* with no answer, or the last call is made without tools so it answers.
|
|
6852
|
+
*
|
|
6853
|
+
* @remarks Text only. What the last model call under \`maxSteps\` may do. Omit = \`'stop'\`: it may
|
|
6854
|
+
* call tools, and if it does the turn stops as \`step_limit\`. \`'answer'\` sends it without tools.
|
|
6345
6855
|
*/
|
|
6346
6856
|
atStepLimit?: StepLimitMode;
|
|
6347
6857
|
}
|
|
@@ -6351,6 +6861,7 @@ export interface ProfileTurnBehaviourSpec {
|
|
|
6351
6861
|
* no mid-turn inject to steer.
|
|
6352
6862
|
*/
|
|
6353
6863
|
export interface MediaTurnBehaviourSpec {
|
|
6864
|
+
/** Continuing a reply that stopped early; live uses sessionResumption instead. */
|
|
6354
6865
|
resumption?: ProfileTurnResumptionSpec;
|
|
6355
6866
|
}
|
|
6356
6867
|
/**
|
|
@@ -6381,6 +6892,8 @@ export declare function profileTurnResumption(profile: {
|
|
|
6381
6892
|
type: string;
|
|
6382
6893
|
turnBehaviour?: ProfileTurnBehaviourSpec;
|
|
6383
6894
|
}): ProfileTurnResumptionSpec | undefined;
|
|
6895
|
+
/** How many model calls a turn sends again when the output limit cuts one off: \`maxContinues\` (one when unset) while \`autoContinue\` names \`length\`, else none. */
|
|
6896
|
+
export declare function cutOffRepairs(profile: Parameters<typeof profileTurnResumption>[0]): number;
|
|
6384
6897
|
/** Text-only, for the interface \`allowSteering\` projection; \`profileAllowsInject\` adds live. */
|
|
6385
6898
|
export declare function profileAllowsSteering(profile: {
|
|
6386
6899
|
type: string;
|
|
@@ -6488,6 +7001,7 @@ export interface InjectedMessages {
|
|
|
6488
7001
|
}
|
|
6489
7002
|
/** Why a turn or live utterance ended. */
|
|
6490
7003
|
export interface TurnStop {
|
|
7004
|
+
/** Why the turn ended, on the done event: its stop.kind. */
|
|
6491
7005
|
kind: TurnStopKind;
|
|
6492
7006
|
native?: string;
|
|
6493
7007
|
}
|
|
@@ -6495,15 +7009,15 @@ export declare const turnStopSchema: z.ZodObject<{
|
|
|
6495
7009
|
kind: z.ZodEnum<{
|
|
6496
7010
|
length: "length";
|
|
6497
7011
|
tool: "tool";
|
|
6498
|
-
|
|
6499
|
-
interrupted: "interrupted";
|
|
7012
|
+
gate: "gate";
|
|
6500
7013
|
stream_incomplete: "stream_incomplete";
|
|
6501
7014
|
provider_error: "provider_error";
|
|
6502
7015
|
answer_missing: "answer_missing";
|
|
7016
|
+
cancelled: "cancelled";
|
|
6503
7017
|
completed: "completed";
|
|
6504
|
-
gate: "gate";
|
|
6505
7018
|
filtered: "filtered";
|
|
6506
7019
|
step_limit: "step_limit";
|
|
7020
|
+
interrupted: "interrupted";
|
|
6507
7021
|
generation_complete: "generation_complete";
|
|
6508
7022
|
}>;
|
|
6509
7023
|
native: z.ZodOptional<z.ZodString>;
|
|
@@ -7297,11 +7811,7 @@ export type CompactionMeter = (typeof COMPACTION_METERS)[number];
|
|
|
7297
7811
|
export declare const COMPACTION_TIMINGS: readonly ["before", "after"];
|
|
7298
7812
|
/** One of {@linkcode COMPACTION_TIMINGS}. */
|
|
7299
7813
|
export type CompactionTiming = (typeof COMPACTION_TIMINGS)[number];
|
|
7300
|
-
/**
|
|
7301
|
-
* - \`compacted\`: a summary replaced the compacted messages.
|
|
7302
|
-
* - \`deferred\`: the compactor failed and the history still fits \`maxTokens\`, so it is kept whole.
|
|
7303
|
-
* - \`dropped\`: the compactor failed over \`maxTokens\`, so the compacted messages were dropped.
|
|
7304
|
-
*/
|
|
7814
|
+
/** What a compaction did. */
|
|
7305
7815
|
export declare const COMPACTION_OUTCOMES: readonly ["compacted", "deferred", "dropped"];
|
|
7306
7816
|
/** One of {@linkcode COMPACTION_OUTCOMES}. */
|
|
7307
7817
|
export type CompactionOutcome = (typeof COMPACTION_OUTCOMES)[number];
|
|
@@ -7438,8 +7948,10 @@ export declare const DYNAMIC_FIELD_PARENTS: ReadonlySet<string>;
|
|
|
7438
7948
|
/** Turns a key path into its catalog path, replacing host-chosen map keys with \`*\`. */
|
|
7439
7949
|
export declare function catalogPathFor(keys: readonly string[]): string;
|
|
7440
7950
|
/**
|
|
7441
|
-
* Adding a profile field?
|
|
7442
|
-
*
|
|
7951
|
+
* Adding a profile field? Write its doc as JSDoc on the type, run \`deno task field-docs\`, and add
|
|
7952
|
+
* it here with \`field()\`; scope it in \`PROFILE_FIELD_SCOPE\` if only some types take it, and record
|
|
7953
|
+
* it in \`PROFILE_FIELD_PRESENCE\` if it is required or its absence matters. A map's entries
|
|
7954
|
+
* (\`models.*\`) take their doc from a \`@catalog <path> <text>\` tag on the map's property.
|
|
7443
7955
|
*/
|
|
7444
7956
|
export declare const PROFILE_FIELDS: Record<string, FieldMeta>;
|
|
7445
7957
|
/**
|
|
@@ -7609,88 +8121,39 @@ export { profileGraphFacet, spineFacetsForProfileType };
|
|
|
7609
8121
|
`,"file:///node_modules/@theoremjs/agents/src/kernel/api-catalog.d.ts":`/** labels-exempt-file: authoring request-field and export meta — not runtime user or model copy (P2) */
|
|
7610
8122
|
import type { FieldMeta } from './schema.js';
|
|
7611
8123
|
import type { TurnInput, TurnRequest } from './types.js';
|
|
8124
|
+
/** A \`runTurn\` request field's catalog path. */
|
|
8125
|
+
export type RequestPath = \`runTurn.\${keyof TurnRequest | \`input.\${keyof TurnInput}\`}\`;
|
|
7612
8126
|
/** The catalog of the fields a \`runTurn\` request takes, keyed \`runTurn.<field>\`. */
|
|
7613
|
-
export declare const REQUEST_FIELDS: Record
|
|
8127
|
+
export declare const REQUEST_FIELDS: Record<RequestPath, FieldMeta>;
|
|
7614
8128
|
/** What the catalog records about one export: what it is and what it does. */
|
|
7615
8129
|
export type ApiExportMeta = {
|
|
7616
8130
|
kind: 'function' | 'class';
|
|
7617
8131
|
doc: string;
|
|
7618
8132
|
};
|
|
7619
|
-
/**
|
|
7620
|
-
|
|
7621
|
-
readonly defineProfile:
|
|
7622
|
-
|
|
7623
|
-
|
|
7624
|
-
|
|
7625
|
-
readonly
|
|
7626
|
-
|
|
7627
|
-
|
|
7628
|
-
|
|
7629
|
-
readonly
|
|
7630
|
-
|
|
7631
|
-
|
|
7632
|
-
|
|
7633
|
-
readonly
|
|
7634
|
-
|
|
7635
|
-
|
|
7636
|
-
|
|
7637
|
-
readonly
|
|
7638
|
-
|
|
7639
|
-
|
|
7640
|
-
|
|
7641
|
-
|
|
7642
|
-
|
|
7643
|
-
readonly doc: "Validates a provider definition and supplies its typed model helper.";
|
|
7644
|
-
};
|
|
7645
|
-
readonly registerProvider: {
|
|
7646
|
-
readonly kind: "function";
|
|
7647
|
-
readonly doc: "Registers a provider instance before profiles reference its ID.";
|
|
7648
|
-
};
|
|
7649
|
-
readonly runTurn: {
|
|
7650
|
-
readonly kind: "function";
|
|
7651
|
-
readonly doc: "Runs one turn of a text, image, or speech profile and yields its events.";
|
|
7652
|
-
};
|
|
7653
|
-
readonly runSession: {
|
|
7654
|
-
readonly kind: "function";
|
|
7655
|
-
readonly doc: "Runs a realtime voice or video session of a live profile.";
|
|
7656
|
-
};
|
|
7657
|
-
readonly runDecision: {
|
|
7658
|
-
readonly kind: "function";
|
|
7659
|
-
readonly doc: "Asks a decision profile its questions about your JSON state and returns checked answers.";
|
|
7660
|
-
};
|
|
7661
|
-
readonly invokeTool: {
|
|
7662
|
-
readonly kind: "function";
|
|
7663
|
-
readonly doc: "Runs one registered tool through a profile, with no model.";
|
|
7664
|
-
};
|
|
7665
|
-
readonly runTool: {
|
|
7666
|
-
readonly kind: "function";
|
|
7667
|
-
readonly doc: "Runs one registered tool through a profile, with no model, and returns how the call settled.";
|
|
7668
|
-
};
|
|
7669
|
-
readonly compactHistory: {
|
|
7670
|
-
readonly kind: "function";
|
|
7671
|
-
readonly doc: "Shortens a conversation history with the compaction the profile sets.";
|
|
7672
|
-
};
|
|
7673
|
-
readonly takeSlot: {
|
|
7674
|
-
readonly kind: "function";
|
|
7675
|
-
readonly doc: "Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.";
|
|
7676
|
-
};
|
|
7677
|
-
readonly releaseSlot: {
|
|
7678
|
-
readonly kind: "function";
|
|
7679
|
-
readonly doc: "Frees the turn slot that takeSlot gave.";
|
|
7680
|
-
};
|
|
7681
|
-
readonly overrideLabels: {
|
|
7682
|
-
readonly kind: "function";
|
|
7683
|
-
readonly doc: "Replaces status lines for every profile in the process; a profile's own labels wins.";
|
|
7684
|
-
};
|
|
7685
|
-
readonly resetLabels: {
|
|
7686
|
-
readonly kind: "function";
|
|
7687
|
-
readonly doc: "Removes every replacement that overrideLabels made.";
|
|
7688
|
-
};
|
|
7689
|
-
readonly TheoremError: {
|
|
7690
|
-
readonly kind: "class";
|
|
7691
|
-
readonly doc: "The error Theorem throws; its kind tells your host which status and wording to use.";
|
|
7692
|
-
};
|
|
7693
|
-
};
|
|
8133
|
+
/** What each export a builder calls by name is. */
|
|
8134
|
+
declare const EXPORT_KINDS: {
|
|
8135
|
+
readonly defineProfile: "function";
|
|
8136
|
+
readonly registerProfile: "function";
|
|
8137
|
+
readonly registerTool: "function";
|
|
8138
|
+
readonly registerStructured: "function";
|
|
8139
|
+
readonly registerTraceDestination: "function";
|
|
8140
|
+
readonly defineProvider: "function";
|
|
8141
|
+
readonly registerProvider: "function";
|
|
8142
|
+
readonly runTurn: "function";
|
|
8143
|
+
readonly runSession: "function";
|
|
8144
|
+
readonly runDecision: "function";
|
|
8145
|
+
readonly invokeTool: "function";
|
|
8146
|
+
readonly runTool: "function";
|
|
8147
|
+
readonly compactHistory: "function";
|
|
8148
|
+
readonly takeSlot: "function";
|
|
8149
|
+
readonly releaseSlot: "function";
|
|
8150
|
+
readonly overrideLabels: "function";
|
|
8151
|
+
readonly resetLabels: "function";
|
|
8152
|
+
readonly TheoremError: "class";
|
|
8153
|
+
};
|
|
8154
|
+
/** The catalog of the exports a builder calls by name, keyed by that name; each doc is its JSDoc. */
|
|
8155
|
+
export declare const API_EXPORTS: Record<keyof typeof EXPORT_KINDS, ApiExportMeta>;
|
|
8156
|
+
export {};
|
|
7694
8157
|
`,"file:///node_modules/@theoremjs/agents/src/kernel/registry/vault.d.ts":`import type { JsonObject } from '../json.js';
|
|
7695
8158
|
import type { KeySlot } from '../types.js';
|
|
7696
8159
|
/** A key as the vault holds it: a string, or an object for a provider that signs in with several fields. */
|
|
@@ -7747,14 +8210,19 @@ export type BlockedReplyOnBlock = (typeof BLOCKED_REPLY_ON_BLOCK)[number];
|
|
|
7747
8210
|
/** What happens once a detector blocks a reply. */
|
|
7748
8211
|
export interface BlockedReplySpec {
|
|
7749
8212
|
/**
|
|
7750
|
-
*
|
|
7751
|
-
*
|
|
7752
|
-
*
|
|
8213
|
+
* Whether the model gets to rewrite a reply a guardrail blocked, or the user gets a refusal in
|
|
8214
|
+
* its place.
|
|
8215
|
+
*
|
|
8216
|
+
* @remarks \`retry\` (the default) tells the model what blocked the reply and has it write another;
|
|
8217
|
+
* \`refuse\` sends the user the labels' \`egress.refusal\` in its place, or ends the part they
|
|
8218
|
+
* already have with \`egress.refusal_cut\`.
|
|
7753
8219
|
*/
|
|
7754
8220
|
onBlock?: BlockedReplyOnBlock;
|
|
7755
8221
|
/**
|
|
7756
|
-
*
|
|
7757
|
-
*
|
|
8222
|
+
* How many times the model may rewrite a blocked reply. Live ignores it.
|
|
8223
|
+
*
|
|
8224
|
+
* @remarks Under \`retry\`, how many times the model may rewrite a blocked reply (default 1). Once
|
|
8225
|
+
* they are spent the reply is withheld and the turn ends in a \`safety\` error.
|
|
7758
8226
|
*/
|
|
7759
8227
|
maxRetries?: number;
|
|
7760
8228
|
}
|
|
@@ -7844,11 +8312,20 @@ export type DestinationGate = (typeof DESTINATION_GATES)[number];
|
|
|
7844
8312
|
*/
|
|
7845
8313
|
export interface TaintGuardrailSpec {
|
|
7846
8314
|
/**
|
|
7847
|
-
*
|
|
7848
|
-
*
|
|
7849
|
-
*
|
|
8315
|
+
* Which tool calls are refused, by each tool's access, once the turn has read a remote tool's
|
|
8316
|
+
* result.
|
|
8317
|
+
*
|
|
8318
|
+
* @remarks Stated as a capability threshold rather than a list of tool \`access\` values so the
|
|
8319
|
+
* guardrail vocabulary stays independent of the tool registry; the kernel maps a tool's declared
|
|
8320
|
+
* access onto it.
|
|
7850
8321
|
*/
|
|
7851
8322
|
afterRemoteRead?: TaintGate;
|
|
8323
|
+
/**
|
|
8324
|
+
* What happens to a tool call, read-only ones too, that sends to an email address, a link's host
|
|
8325
|
+
* or a bank account number (IBAN) that only the running text of a remote tool's result named. One
|
|
8326
|
+
* the user, the system prompt, or a local tool gave passes, and so does one that is a whole field
|
|
8327
|
+
* of the result.
|
|
8328
|
+
*/
|
|
7852
8329
|
remoteDestination?: DestinationGate;
|
|
7853
8330
|
}
|
|
7854
8331
|
/** Facts a check may read. Deliberately excludes the full profile. */
|
|
@@ -7896,35 +8373,67 @@ export interface OutboundPayload {
|
|
|
7896
8373
|
}
|
|
7897
8374
|
/** Which hosts and networks a tool's requests may reach. */
|
|
7898
8375
|
export interface NetworkGuardrailSpec {
|
|
7899
|
-
/**
|
|
8376
|
+
/**
|
|
8377
|
+
* Lets tools reach localhost and private network addresses, for local development.
|
|
8378
|
+
*
|
|
8379
|
+
* @remarks Allows localhost, loopback, and private subnets (local dev and testing). Default
|
|
8380
|
+
* false.
|
|
8381
|
+
*/
|
|
7900
8382
|
allowPrivateNetworks?: boolean;
|
|
7901
|
-
/**
|
|
8383
|
+
/**
|
|
8384
|
+
* Hostnames tools may reach even when they resolve to a private address; public hosts don't need
|
|
8385
|
+
* listing. Names are resolved only when the host passes resolveHost.
|
|
8386
|
+
*
|
|
8387
|
+
* @remarks Hostnames or IP addresses permitted regardless of private subnet status.
|
|
8388
|
+
*/
|
|
7902
8389
|
allowedHosts?: string[];
|
|
7903
8390
|
/**
|
|
7904
|
-
*
|
|
8391
|
+
* The URL schemes tools may use.
|
|
8392
|
+
*
|
|
8393
|
+
* @remarks Allowed URL schemes. Defaults to \`['https']\`, or \`['http', 'https']\` when
|
|
7905
8394
|
* \`allowPrivateNetworks\` is set.
|
|
7906
8395
|
*/
|
|
7907
8396
|
allowedSchemes?: string[];
|
|
7908
8397
|
}
|
|
7909
8398
|
/** Optional daily turn quota consumed by host HTTP middleware. */
|
|
7910
8399
|
export interface QuotaGuardrailSpec {
|
|
8400
|
+
/**
|
|
8401
|
+
* Turns each client IP may run on this profile per UTC day, one at a time; counts live in the
|
|
8402
|
+
* process, and a loopback caller is not counted.
|
|
8403
|
+
*/
|
|
7911
8404
|
perDay: number;
|
|
7912
8405
|
}
|
|
7913
8406
|
/** The guardrails a profile turns on, each with its own settings. */
|
|
7914
8407
|
export interface ProfileGuardrailsSpec {
|
|
7915
|
-
/**
|
|
8408
|
+
/**
|
|
8409
|
+
* A daily turn limit. Your server enforces it with takeSlot.
|
|
8410
|
+
*
|
|
8411
|
+
* @remarks Omitted means quota enforcement is not configured.
|
|
8412
|
+
*/
|
|
7916
8413
|
quota?: QuotaGuardrailSpec;
|
|
7917
8414
|
/**
|
|
7918
|
-
* What
|
|
7919
|
-
*
|
|
7920
|
-
*
|
|
7921
|
-
*
|
|
7922
|
-
* the
|
|
8415
|
+
* What a guardrail does when a detector matches. One action covers every detector; an object sets
|
|
8416
|
+
* each detector (or one of your own) apart. Absent: each detector keeps its default action.
|
|
8417
|
+
*
|
|
8418
|
+
* @remarks What the kernel does when a detector finds a match, per boundary: one action for
|
|
8419
|
+
* everything, or a rule for the detectors it names. Anything left out keeps its default
|
|
8420
|
+
* (\`DETECT_DEFAULTS\`). A canary is bound into the system prompt while \`canary_leak\` is above
|
|
8421
|
+
* \`ignore\` somewhere; the note that binds it is the labels' \`canary.bind_note\` (the profile's
|
|
8422
|
+
* \`labels\` may replace it).
|
|
8423
|
+
*
|
|
8424
|
+
* @catalog guardrails.detect.* Your own detector, keyed with a dot: acme.codenames. No default action.
|
|
7923
8425
|
*/
|
|
7924
8426
|
detect?: DetectSpec;
|
|
7925
|
-
/**
|
|
8427
|
+
/**
|
|
8428
|
+
* How a reply a guardrail blocked is handled: the model rewrites it, or the user gets a refusal,
|
|
8429
|
+
* and how many rewrites it gets.
|
|
8430
|
+
*
|
|
8431
|
+
* @remarks What happens once a reply is blocked. Left out, the model rewrites it once.
|
|
8432
|
+
*/
|
|
7926
8433
|
blockedReply?: BlockedReplySpec;
|
|
8434
|
+
/** Addresses HTTP and MCP tools may reach. */
|
|
7927
8435
|
network?: NetworkGuardrailSpec;
|
|
8436
|
+
/** Tool limits after a remote read. */
|
|
7928
8437
|
taint?: TaintGuardrailSpec;
|
|
7929
8438
|
}
|
|
7930
8439
|
/** Pre-dispatch policy for structured state leaving a decision profile. */
|
|
@@ -7947,7 +8456,9 @@ export type DecisionDisclosureEnforcer = (state: unknown, context: {
|
|
|
7947
8456
|
* decision registry rejects every inherited field as inert in this release.
|
|
7948
8457
|
*/
|
|
7949
8458
|
export interface DecisionGuardrailsSpec extends Partial<ProfileGuardrailsSpec> {
|
|
8459
|
+
/** Your check on the state before a decision sends it to the model. */
|
|
7950
8460
|
disclosure?: {
|
|
8461
|
+
/** Your function that allows or blocks the state before it is sent. */
|
|
7951
8462
|
enforce: DecisionDisclosureEnforcer;
|
|
7952
8463
|
};
|
|
7953
8464
|
}
|
|
@@ -8018,7 +8529,7 @@ export { applySpans, blobAt, mergeSpans, OMIT_CANARY, OMIT_INJECTION, OMIT_PROMP
|
|
|
8018
8529
|
`,"file:///node_modules/@theoremjs/agents/src/guardrails/labels.d.ts":`/** Values that fill a label template's \`{param}\` placeholders. */
|
|
8019
8530
|
export type LabelParams = Record<string, string | number>;
|
|
8020
8531
|
/** Keys are stable API. */
|
|
8021
|
-
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.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_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"];
|
|
8532
|
+
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_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"];
|
|
8022
8533
|
/** One of {@linkcode LABEL_KEYS}. */
|
|
8023
8534
|
export type LabelKey = (typeof LABEL_KEYS)[number];
|
|
8024
8535
|
/**
|
|
@@ -8045,9 +8556,17 @@ export declare const LABEL_NOTES: Record<LabelKey, string>;
|
|
|
8045
8556
|
export declare function labelPlaceholders(key: LabelKey): readonly string[];
|
|
8046
8557
|
/** \`owner\` names where the overrides came from in the error. */
|
|
8047
8558
|
export declare function validateLabelOverrides(entries: LabelOverrides, owner: string): void;
|
|
8048
|
-
/**
|
|
8559
|
+
/**
|
|
8560
|
+
* Replaces status lines for every profile in the process; a profile's own labels wins.
|
|
8561
|
+
*
|
|
8562
|
+
* @remarks Process-wide; a profile's own \`labels\` wins over these.
|
|
8563
|
+
*/
|
|
8049
8564
|
export declare function overrideLabels(entries: LabelOverrides): void;
|
|
8050
|
-
/**
|
|
8565
|
+
/**
|
|
8566
|
+
* Removes every replacement that overrideLabels made.
|
|
8567
|
+
*
|
|
8568
|
+
* @remarks Remove every label override.
|
|
8569
|
+
*/
|
|
8051
8570
|
export declare function resetLabels(): void;
|
|
8052
8571
|
/** The wording for a key, with a profile's override applied and the params filled in. */
|
|
8053
8572
|
export declare function labelText(key: LabelKey, params?: LabelParams, profileLabels?: LabelOverrides): string;
|
|
@@ -8180,7 +8699,11 @@ export interface TheoremErrorOptions extends ErrorOptions {
|
|
|
8180
8699
|
/** User wording more specific than the kind's: one line, or one per problem found. */
|
|
8181
8700
|
copy?: ErrorCopies;
|
|
8182
8701
|
}
|
|
8183
|
-
/**
|
|
8702
|
+
/**
|
|
8703
|
+
* The error Theorem throws; its kind tells your host which status and wording to use.
|
|
8704
|
+
*
|
|
8705
|
+
* @remarks An error that carries a \`kind\`, from which hosts choose a status and the user's wording.
|
|
8706
|
+
*/
|
|
8184
8707
|
export declare class TheoremError extends Error {
|
|
8185
8708
|
readonly kind: ErrorKind;
|
|
8186
8709
|
readonly copy?: ErrorCopies;
|
|
@@ -8305,7 +8828,11 @@ export interface ProviderWarning {
|
|
|
8305
8828
|
export declare const providerWarningSchema: z.ZodType<ProviderWarning>;
|
|
8306
8829
|
export interface ProviderContinuationPolicy {
|
|
8307
8830
|
/**
|
|
8308
|
-
* Who holds the conversation a checkpoint continues
|
|
8831
|
+
* Who holds the conversation a checkpoint continues: the host passes history back, the provider
|
|
8832
|
+
* keeps it and the checkpoint travels alone, or the profile is stateless and every request stands
|
|
8833
|
+
* alone.
|
|
8834
|
+
*
|
|
8835
|
+
* @remarks Who holds the conversation a checkpoint continues. \`'host'\` (unset) passes the covered
|
|
8309
8836
|
* history back with the checkpoint. \`'provider'\` passes the checkpoint alone: the provider's
|
|
8310
8837
|
* stored conversation is the history, and a turn that goes elsewhere needs the host's history.
|
|
8311
8838
|
* \`'stateless'\` keeps no conversation: a request that carries history or a checkpoint is refused,
|
|
@@ -8543,19 +9070,45 @@ import type { TraceSink } from './trace-sink.js';
|
|
|
8543
9070
|
import type { TraceAttributes } from './trace-span.js';
|
|
8544
9071
|
/** Which payloads land in each TraceRecord. Omitted keys use resolved defaults. */
|
|
8545
9072
|
export interface TraceIncludeSpec {
|
|
8546
|
-
/**
|
|
9073
|
+
/**
|
|
9074
|
+
* Keeps each row the provider sent back, scrubbed, as it arrived, with media bytes replaced by
|
|
9075
|
+
* their sha256.
|
|
9076
|
+
*
|
|
9077
|
+
* @remarks Scrubbed provider rows and frames (\`theorem.upstream.row\` events). Default: true.
|
|
9078
|
+
*/
|
|
8547
9079
|
upstreamLog?: boolean;
|
|
8548
|
-
/**
|
|
9080
|
+
/**
|
|
9081
|
+
* Keeps each request body sent to the provider, scrubbed.
|
|
9082
|
+
*
|
|
9083
|
+
* @remarks Scrubbed outbound request bodies (\`theorem.wire.request\` events). Default: false.
|
|
9084
|
+
*/
|
|
8549
9085
|
outboundWire?: boolean;
|
|
8550
|
-
/**
|
|
9086
|
+
/**
|
|
9087
|
+
* Keeps the provider's raw payload on grounding results such as search citations; upstreamLog
|
|
9088
|
+
* rows keep their own copy.
|
|
9089
|
+
*
|
|
9090
|
+
* @remarks The provider's raw grounding payload (\`raw\` on \`theorem.grounding\` events). Default:
|
|
9091
|
+
* false.
|
|
9092
|
+
*/
|
|
8551
9093
|
evidenceRaw?: boolean;
|
|
8552
|
-
/**
|
|
9094
|
+
/**
|
|
9095
|
+
* Keeps token counts and other usage figures on spans; upstreamLog rows keep their own.
|
|
9096
|
+
*
|
|
9097
|
+
* @remarks Usage attributes (\`gen_ai.usage.*\`, \`theorem.usage.*\`). Default: true.
|
|
9098
|
+
*/
|
|
8553
9099
|
usage?: boolean;
|
|
8554
|
-
/**
|
|
9100
|
+
/**
|
|
9101
|
+
* Keeps each guardrail decision.
|
|
9102
|
+
*
|
|
9103
|
+
* @remarks Guardrail decisions (\`theorem.guardrail\` events). Default: true.
|
|
9104
|
+
*/
|
|
8555
9105
|
guardrailDecisions?: boolean;
|
|
8556
9106
|
/**
|
|
8557
|
-
*
|
|
8558
|
-
* debugging only
|
|
9107
|
+
* Keeps the exact text each guardrail matched, unscrubbed, on the trace and the host's event
|
|
9108
|
+
* stream; for debugging only.
|
|
9109
|
+
*
|
|
9110
|
+
* @remarks Keep \`GuardrailHit.match\` (the exact matched text) on guardrail events. Default:
|
|
9111
|
+
* false; debugging only, so treat the store like server logs when enabled.
|
|
8559
9112
|
*/
|
|
8560
9113
|
guardrailMatchPreview?: boolean;
|
|
8561
9114
|
}
|
|
@@ -8574,42 +9127,90 @@ export type ScrubSwitch = boolean | {
|
|
|
8574
9127
|
* their actions: a detector set to \`ignore\` in the turn still cleans the trace. Defaults are on.
|
|
8575
9128
|
*/
|
|
8576
9129
|
export interface TraceScrubSpec {
|
|
8577
|
-
/**
|
|
9130
|
+
/**
|
|
9131
|
+
* Removes what the data detectors (IDs, Financial, Network, Credentials) and your own detectors
|
|
9132
|
+
* find from stored traces. On, it cleans with the patterns each reads the turn with; { theorem,
|
|
9133
|
+
* host } picks Theorem's patterns, yours, or both for the trace alone.
|
|
9134
|
+
*
|
|
9135
|
+
* @remarks The data detectors (\`ids\`, \`financial\`, \`network\`, \`credentials\`) and the host's own.
|
|
9136
|
+
* Default: true.
|
|
9137
|
+
*/
|
|
8578
9138
|
sensitive?: ScrubSwitch;
|
|
8579
|
-
/**
|
|
9139
|
+
/**
|
|
9140
|
+
* Removes what Injection and Tool instructions find from stored traces. On, it cleans with the
|
|
9141
|
+
* patterns each reads the turn with; { theorem, host } picks Theorem's patterns, yours, or both
|
|
9142
|
+
* for the trace alone.
|
|
9143
|
+
*
|
|
9144
|
+
* @remarks \`injection\`, with the orders to the agent it finds in what a tool returns. Default:
|
|
9145
|
+
* true.
|
|
9146
|
+
*/
|
|
8580
9147
|
injection?: ScrubSwitch;
|
|
8581
|
-
/**
|
|
9148
|
+
/**
|
|
9149
|
+
* Removes the canary token from stored traces. The canary is Theorem's, so { theorem: false }
|
|
9150
|
+
* keeps it.
|
|
9151
|
+
*
|
|
9152
|
+
* @remarks Never persist the canary token. It is Theorem's alone, so the host side adds nothing.
|
|
9153
|
+
* Default: true.
|
|
9154
|
+
*/
|
|
8582
9155
|
canary?: ScrubSwitch;
|
|
8583
9156
|
}
|
|
8584
9157
|
/** Omit the whole block for no tracing. */
|
|
8585
9158
|
export interface ProfileObservabilitySpec {
|
|
8586
9159
|
/**
|
|
8587
|
-
*
|
|
8588
|
-
*
|
|
9160
|
+
* Where traces go: a registered destination id, your own writer, or false. An unregistered id
|
|
9161
|
+
* fails the turn at the start. A sink passed to runTurn replaces it.
|
|
9162
|
+
*
|
|
9163
|
+
* @remarks \`false\` is off, a string is a \`registerTraceDestination\` id, a TraceSink is an inline
|
|
9164
|
+
* writer. \`runTurn(..., sink)\` still overrides this for one call.
|
|
8589
9165
|
*/
|
|
8590
9166
|
writeTo?: false | string | TraceSink;
|
|
8591
9167
|
/**
|
|
8592
|
-
*
|
|
9168
|
+
* The share of traces kept, from 0 to 1, each kept or dropped whole; a sink passed straight to
|
|
9169
|
+
* runTurn keeps every trace.
|
|
9170
|
+
*
|
|
9171
|
+
* @remarks Fraction of traces to record, 0–1 inclusive. Default: 1. Decided by trace id, so every
|
|
8593
9172
|
* record of one trace is kept or dropped together.
|
|
8594
9173
|
*/
|
|
8595
9174
|
sampleRate?: number;
|
|
9175
|
+
/** Which optional parts of a trace are kept. */
|
|
8596
9176
|
include?: TraceIncludeSpec;
|
|
8597
|
-
/**
|
|
9177
|
+
/**
|
|
9178
|
+
* Attributes stamped on every trace, such as service.name.
|
|
9179
|
+
*
|
|
9180
|
+
* @remarks Stamped on every record as \`TraceRecord.resource\`, e.g. \`{ 'service.name': 'harbor'
|
|
9181
|
+
* }\`.
|
|
9182
|
+
*/
|
|
8598
9183
|
resource?: TraceAttributes;
|
|
8599
|
-
/**
|
|
9184
|
+
/**
|
|
9185
|
+
* What is removed from stored traces, separately from the turn's guardrails.
|
|
9186
|
+
*
|
|
9187
|
+
* @remarks Defaults stay on even when \`guardrails.detect\` is \`ignore\`.
|
|
9188
|
+
*/
|
|
8600
9189
|
scrub?: TraceScrubSpec;
|
|
8601
9190
|
/**
|
|
8602
|
-
* Days
|
|
8603
|
-
*
|
|
8604
|
-
*
|
|
9191
|
+
* Days a trace file is kept, by its UTC day. The next write removes old files. 0 or less keeps
|
|
9192
|
+
* all.
|
|
9193
|
+
*
|
|
9194
|
+
* @remarks Days to keep each record, handed to every destination with the record
|
|
9195
|
+
* (\`TraceWriteContext\`): the JSONL writer prunes by it, a host store computes its own expiry from
|
|
9196
|
+
* it. \`<= 0\` keeps records forever. Default: 14.
|
|
8605
9197
|
*/
|
|
8606
9198
|
retainForDays?: number;
|
|
8607
9199
|
/**
|
|
8608
9200
|
* File size in MiB at which a file-based destination starts a new file, handed to every
|
|
9201
|
+
* destination with the record. Default 32.
|
|
9202
|
+
*
|
|
9203
|
+
* @remarks File size in MiB at which a file-based destination starts a new file, handed to every
|
|
8609
9204
|
* destination with the record (\`TraceWriteContext\`). Default: 32.
|
|
8610
9205
|
*/
|
|
8611
9206
|
rotateAfterMiB?: number;
|
|
8612
|
-
/**
|
|
9207
|
+
/**
|
|
9208
|
+
* Your function called when a trace can't be built or written; the turn carries on, and a
|
|
9209
|
+
* destination's own error handler takes priority. An unregistered writeTo id is a config error
|
|
9210
|
+
* instead.
|
|
9211
|
+
*
|
|
9212
|
+
* @remarks Called when record build or destination write fails. Must not throw.
|
|
9213
|
+
*/
|
|
8613
9214
|
onWriteError?: (err: unknown) => void;
|
|
8614
9215
|
}
|
|
8615
9216
|
/** Which optional content a trace record includes, each on or off. */
|
|
@@ -8937,8 +9538,23 @@ import type { RegisteredProvider } from './provider.js';
|
|
|
8937
9538
|
/** A vault slot name. */
|
|
8938
9539
|
export declare const keySlotSchema: z.ZodString;
|
|
8939
9540
|
export declare const commonModelSettingsSchema: z.ZodObject<{
|
|
9541
|
+
/**
|
|
9542
|
+
* The token limit for one reply. Some providers never send it for speech, or for image without
|
|
9543
|
+
* includeText.
|
|
9544
|
+
*/
|
|
8940
9545
|
maxOutputTokens: z.ZodOptional<z.ZodNumber>;
|
|
9546
|
+
/**
|
|
9547
|
+
* How varied the model's wording is; higher is more random. Some providers never send it for
|
|
9548
|
+
* speech, or for image without includeText.
|
|
9549
|
+
*/
|
|
8941
9550
|
temperature: z.ZodOptional<z.ZodNumber>;
|
|
9551
|
+
/**
|
|
9552
|
+
* Named thinking levels. A turn picks one when allowEffortSelect is on. A provider refuses a
|
|
9553
|
+
* level its model does not take. Speech ignores them, and so may an image profile without
|
|
9554
|
+
* includeText.
|
|
9555
|
+
*
|
|
9556
|
+
* @catalog models.*.efforts.* The thinking level sent to the provider for this name.
|
|
9557
|
+
*/
|
|
8942
9558
|
efforts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
|
|
8943
9559
|
none: 'none';
|
|
8944
9560
|
minimal: 'minimal';
|
|
@@ -8948,24 +9564,65 @@ export declare const commonModelSettingsSchema: z.ZodObject<{
|
|
|
8948
9564
|
xhigh: 'xhigh';
|
|
8949
9565
|
max: 'max';
|
|
8950
9566
|
}>>>;
|
|
9567
|
+
/** The effort a turn gets when it doesn't pick one. */
|
|
8951
9568
|
defaultEffort: z.ZodOptional<z.ZodString>;
|
|
9569
|
+
/** Lets a turn pick an effort; needs two or more efforts. */
|
|
8952
9570
|
allowEffortSelect: z.ZodOptional<z.ZodBoolean>;
|
|
9571
|
+
/**
|
|
9572
|
+
* Asks the model for summaries of its thinking, which not every model sends; with some providers,
|
|
9573
|
+
* off only hides thoughts, and others ignore it.
|
|
9574
|
+
*/
|
|
8953
9575
|
summaries: z.ZodOptional<z.ZodBoolean>;
|
|
9576
|
+
/**
|
|
9577
|
+
* The provider's own tools, such as Google Search, this model may use; each must be registered as
|
|
9578
|
+
* a builtin tool and declared by the provider's adapter.
|
|
9579
|
+
*/
|
|
8954
9580
|
builtInTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
9581
|
+
/**
|
|
9582
|
+
* Summarises history past a threshold. A text agent can write the summary. Other types name a
|
|
9583
|
+
* compaction profile.
|
|
9584
|
+
*/
|
|
8955
9585
|
compaction: z.ZodOptional<z.ZodCustom<import('../types.js').CompactionSpec>>;
|
|
8956
9586
|
}>;
|
|
8957
9587
|
/** One entry under a profile's \`models\`: which protocol, which provider, which model, and its settings. */
|
|
8958
9588
|
export interface ModelBinding extends z.infer<typeof commonModelSettingsSchema> {
|
|
9589
|
+
/** The API shape this model is spoken to in. */
|
|
8959
9590
|
protocol: string;
|
|
9591
|
+
/**
|
|
9592
|
+
* The service that runs the model or routes requests to one, such as Gemini or OpenRouter. Its
|
|
9593
|
+
* registration supplies the endpoint and authentication.
|
|
9594
|
+
*/
|
|
8960
9595
|
provider: string;
|
|
9596
|
+
/**
|
|
9597
|
+
* The model's id as the provider lists it, such as gemini-2.5-flash; sent on every call. The name
|
|
9598
|
+
* this model has in the profile is its key in models.
|
|
9599
|
+
*/
|
|
8961
9600
|
apiId: string;
|
|
9601
|
+
/**
|
|
9602
|
+
* The key slot this model's calls are signed with, instead of the provider's. Use it to bill one
|
|
9603
|
+
* model to a different key. Absent: the provider's primary slot.
|
|
9604
|
+
*/
|
|
8962
9605
|
keySlot?: string;
|
|
9606
|
+
/**
|
|
9607
|
+
* The key slot tried once after a rate limit or a busy model on the primary slot, instead of the
|
|
9608
|
+
* provider's fallback. Must differ from the primary slot. Absent: the provider's fallback slot,
|
|
9609
|
+
* if it has one.
|
|
9610
|
+
*/
|
|
8963
9611
|
fallbackKeySlot?: string;
|
|
9612
|
+
/**
|
|
9613
|
+
* Settings only this model's protocol has, such as a task type or vector size. Each is checked
|
|
9614
|
+
* when the profile loads. Any left out keep the provider's default.
|
|
9615
|
+
*/
|
|
8964
9616
|
options?: JsonObject;
|
|
9617
|
+
/**
|
|
9618
|
+
* The points at which Theorem stops this model's calls. Each one left out is no limit, so the
|
|
9619
|
+
* provider's own limits apply. A runTurn limits value overrides each field it sets.
|
|
9620
|
+
*/
|
|
8965
9621
|
limits?: ProviderLimits;
|
|
8966
9622
|
}
|
|
8967
9623
|
/** A decision profile's model: no generation settings, and a time limit. */
|
|
8968
9624
|
export interface DecisionModelBinding extends Pick<ModelBinding, 'protocol' | 'provider' | 'apiId' | 'keySlot' | 'fallbackKeySlot' | 'options' | 'limits'> {
|
|
9625
|
+
/** How long a decision waits for its provider, in milliseconds. Omit for no timeout. */
|
|
8969
9626
|
timeoutMs?: number;
|
|
8970
9627
|
}
|
|
8971
9628
|
export declare const modelBindingSchema: z.ZodType<ModelBinding>;
|
|
@@ -9030,19 +9687,63 @@ import type { PageToolExecution, ToolExecutionCoordinator } from './operation.js
|
|
|
9030
9687
|
import type { UncheckedOutput } from './unchecked-output.js';
|
|
9031
9688
|
export type { AuthUnauthenticatedPolicy, HttpMethod, ToolAccess, ToolAuthType, ToolCallEdit, ToolCallEvent, ToolCallRequest, ToolFailure, ToolGate, ToolPermission, ToolPhaseEvent, ToolTraceStep, ToolWarning, TurnToolSnapshot, WireFunctionTool, };
|
|
9032
9689
|
export interface ToolLabels {
|
|
9690
|
+
/**
|
|
9691
|
+
* Transcript text while a call runs, e.g. 'Saving {title} to your collection'. {path} reads the
|
|
9692
|
+
* call's input.
|
|
9693
|
+
*/
|
|
9033
9694
|
activity?: LabelTemplate;
|
|
9695
|
+
/**
|
|
9696
|
+
* What the transcript says once a call completes, e.g. 'Found {results.0.name}'. Each {path} is
|
|
9697
|
+
* filled from the call's input, then its output.
|
|
9698
|
+
*/
|
|
9034
9699
|
activityPast?: LabelTemplate;
|
|
9700
|
+
/**
|
|
9701
|
+
* What the transcript says when a call fails or the host labels it failed, e.g. 'Couldn't save
|
|
9702
|
+
* {title}'. Each {path} is filled from the call's input.
|
|
9703
|
+
*/
|
|
9035
9704
|
activityFailed?: LabelTemplate;
|
|
9705
|
+
/**
|
|
9706
|
+
* What the approval card says the agent wants to do, e.g. 'check the weather in {city}'. Each
|
|
9707
|
+
* {path} is filled from the call's input.
|
|
9708
|
+
*/
|
|
9036
9709
|
request?: LabelTemplate;
|
|
9037
9710
|
}
|
|
9038
9711
|
export interface ToolBase {
|
|
9712
|
+
/**
|
|
9713
|
+
* The tool's id, which profiles list in tools.allow (or a model's builtInTools) and the model
|
|
9714
|
+
* calls a custom tool by.
|
|
9715
|
+
*/
|
|
9039
9716
|
name: string;
|
|
9717
|
+
/** Tells the model what the tool does (custom tools only). */
|
|
9040
9718
|
description: string;
|
|
9719
|
+
/** A label for grouping tools; nothing reads it yet. */
|
|
9041
9720
|
category: string;
|
|
9721
|
+
/**
|
|
9722
|
+
* What the tool can change, which taint.afterRemoteRead refuses calls by after a turn reads a
|
|
9723
|
+
* remote tool's result.
|
|
9724
|
+
*/
|
|
9042
9725
|
access: ToolAccess;
|
|
9726
|
+
/**
|
|
9727
|
+
* The turn paths this tool is offered on, where * means every path; a turn with no path gets only
|
|
9728
|
+
* * tools. Host profiles ignore it.
|
|
9729
|
+
*/
|
|
9043
9730
|
paths: string[];
|
|
9731
|
+
/**
|
|
9732
|
+
* When the tool becomes available to the model; live and host profiles load every allowed tool at
|
|
9733
|
+
* the start.
|
|
9734
|
+
*/
|
|
9044
9735
|
loadTier: ToolLoadTier;
|
|
9736
|
+
/** Whether the host must approve a call before it runs; the provider's own tools never ask. */
|
|
9045
9737
|
permission: ToolPermission;
|
|
9738
|
+
/**
|
|
9739
|
+
* Transcript text for a call. {path} reads a value from the call. {results.0.name} reads a list
|
|
9740
|
+
* item. {path|text} shows the text when the value is unusable. {count hit|hits} shows a number
|
|
9741
|
+
* with the word for one or for any other number: '1 hit', '3 hits'. With no fallback, the label
|
|
9742
|
+
* is dropped. A label is one line, or a list read top to bottom: the first line that fits is
|
|
9743
|
+
* shown. A line fits when each {path} has a value and its condition holds, as in 'when status is
|
|
9744
|
+
* archived: archiving {title}'. Neighbouring lines that open with '+ ' show together, joined in
|
|
9745
|
+
* words. The last line of a list must always fit.
|
|
9746
|
+
*/
|
|
9046
9747
|
labels?: ToolLabels;
|
|
9047
9748
|
}
|
|
9048
9749
|
/**
|
|
@@ -9050,7 +9751,9 @@ export interface ToolBase {
|
|
|
9050
9751
|
* adapter declares it (\`ProviderAdapter.builtins\`) and owns how it is sent.
|
|
9051
9752
|
*/
|
|
9052
9753
|
export interface BuiltinToolDef extends ToolBase {
|
|
9754
|
+
/** How the tool runs. */
|
|
9053
9755
|
type: 'builtin';
|
|
9756
|
+
/** The built-in tools a builtin tool cannot run beside. */
|
|
9054
9757
|
conflictsWith?: string[];
|
|
9055
9758
|
}
|
|
9056
9759
|
/** How a held tool call resumes: approved, refused, or retried after sign-in. */
|
|
@@ -9169,32 +9872,71 @@ export type ToolHandler<TIn, TOut> = SyncToolHandler<TIn, TOut> | StreamToolHand
|
|
|
9169
9872
|
* the handler's return type; moving them here silently breaks inference for stream handlers.
|
|
9170
9873
|
*/
|
|
9171
9874
|
export interface ToolHostHooks<TIn = unknown> {
|
|
9875
|
+
/**
|
|
9876
|
+
* The tool's arguments as a JSON Schema, sent to the model.
|
|
9877
|
+
*/
|
|
9172
9878
|
inputSchema: Record<string, unknown>;
|
|
9879
|
+
/**
|
|
9880
|
+
* The tool's result as a JSON Schema, which a function tool's stand-in result is built from.
|
|
9881
|
+
*/
|
|
9173
9882
|
outputSchema: Record<string, unknown>;
|
|
9174
|
-
/**
|
|
9883
|
+
/**
|
|
9884
|
+
* Runs before the host's pre_tool onStage.
|
|
9885
|
+
*
|
|
9886
|
+
* @remarks Runs before the host's \`pre_tool\` \`onStage\`.
|
|
9887
|
+
*/
|
|
9175
9888
|
preTool?: (input: TIn, ctx: ToolContext) => import('../stages.js').StageResult | undefined | Promise<import('../stages.js').StageResult | undefined>;
|
|
9889
|
+
/** Whether the model can see and call the tool. */
|
|
9176
9890
|
exposeToModel?: boolean;
|
|
9177
|
-
/**
|
|
9891
|
+
/**
|
|
9892
|
+
* Gives the model an after field on this tool: the tools called in the same step that must settle
|
|
9893
|
+
* before this call starts. The kernel removes the field before the tool, the stages or a gate
|
|
9894
|
+
* read the input. A name with no other call in the step fails the call wait_unknown.
|
|
9895
|
+
*
|
|
9896
|
+
* @remarks The model gets an \`after\` field: the tools in the same step that must settle before
|
|
9897
|
+
* this call starts.
|
|
9898
|
+
*/
|
|
9178
9899
|
after?: boolean;
|
|
9179
|
-
/**
|
|
9900
|
+
/**
|
|
9901
|
+
* When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }:
|
|
9902
|
+
* once the body has run past this time. 'ask': at the hand-off if the model sets the background
|
|
9903
|
+
* argument. A turn with no background service runs the tool inline.
|
|
9904
|
+
*
|
|
9905
|
+
* @remarks When the model gets its reply. Unset is \`never\`: when the body ends. A turn without a
|
|
9906
|
+
* background service runs inline.
|
|
9907
|
+
*/
|
|
9180
9908
|
background?: ToolBackground;
|
|
9181
9909
|
/** \`inputSchema\` with the \`background\` argument. The registry sets it on an \`ask\` tool. */
|
|
9182
9910
|
askInputSchema?: Record<string, unknown>;
|
|
9183
9911
|
}
|
|
9184
9912
|
export interface ToolOutputHooks<TOut = unknown> {
|
|
9185
|
-
/**
|
|
9913
|
+
/**
|
|
9914
|
+
* The sources a result cites. One that fails sourceSchema, or a throw, is a sources_invalid
|
|
9915
|
+
* warning and is not cited.
|
|
9916
|
+
*
|
|
9917
|
+
* @remarks A source that fails \`sourceSchema\`, or a throw, is a \`sources_invalid\` warning and is
|
|
9918
|
+
* not cited.
|
|
9919
|
+
*/
|
|
9186
9920
|
sources?: (output: TOut) => Source[];
|
|
9187
9921
|
}
|
|
9188
9922
|
/** For a tool whose result names pictures by address; function tools return the bytes themselves as \`parts\`. */
|
|
9189
9923
|
export interface ToolImageHooks<TOut = unknown> {
|
|
9190
9924
|
/**
|
|
9191
|
-
* The https addresses of pictures in
|
|
9192
|
-
*
|
|
9193
|
-
*
|
|
9194
|
-
* \`
|
|
9925
|
+
* The https addresses of pictures in the output the model should see. The kernel fetches each one
|
|
9926
|
+
* through the profile network policy, without the tool credentials.
|
|
9927
|
+
*
|
|
9928
|
+
* @remarks The https addresses of pictures in \`output\` the model should see. After the result
|
|
9929
|
+
* passes the output guard, the kernel fetches each one through the profile's network policy,
|
|
9930
|
+
* without the tool's credentials, and hands the model the image as a part; one it cannot fetch is
|
|
9931
|
+
* an \`images_unfetched\` warning, never a failed call.
|
|
9195
9932
|
*/
|
|
9196
9933
|
images?: (output: TOut) => string[];
|
|
9197
|
-
/**
|
|
9934
|
+
/**
|
|
9935
|
+
* How many of those pictures the kernel fetches, how large, and how slowly.
|
|
9936
|
+
*
|
|
9937
|
+
* @remarks How many of those pictures the kernel fetches, how large, and how slowly. Left out,
|
|
9938
|
+
* there is no limit.
|
|
9939
|
+
*/
|
|
9198
9940
|
imageLimits?: ToolImageLimits;
|
|
9199
9941
|
}
|
|
9200
9942
|
/** Each limit left out is no limit. A picture past one is left out, not cut. */
|
|
@@ -9209,67 +9951,140 @@ export interface ToolImageLimits {
|
|
|
9209
9951
|
timeoutMs?: number;
|
|
9210
9952
|
}
|
|
9211
9953
|
export interface FunctionToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut> {
|
|
9954
|
+
/** How the tool runs. */
|
|
9212
9955
|
type: 'function';
|
|
9956
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9213
9957
|
input: z.ZodType<TIn>;
|
|
9958
|
+
/**
|
|
9959
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
9960
|
+
* not checked.
|
|
9961
|
+
*/
|
|
9214
9962
|
output: z.ZodType<TOut>;
|
|
9215
|
-
/**
|
|
9963
|
+
/**
|
|
9964
|
+
* Your function that runs the tool; it can also yield progress as it goes.
|
|
9965
|
+
*
|
|
9966
|
+
* @remarks Returns \`output\`'s type, or \`uncheckedOutput(value)\` for a value it cannot type.
|
|
9967
|
+
*/
|
|
9216
9968
|
handler: ToolHandler<TIn, NoInfer<TOut>>;
|
|
9217
9969
|
/**
|
|
9218
|
-
*
|
|
9219
|
-
*
|
|
9970
|
+
* Who answers a call to a function tool. With page, the page the agent is on returns the
|
|
9971
|
+
* output, and the tool has no handler.
|
|
9972
|
+
*
|
|
9973
|
+
* @remarks \`'page'\`: the page the person is on answers the call, and the kernel supplies the
|
|
9974
|
+
* handler. \`output\` checks what the page sent.
|
|
9220
9975
|
*/
|
|
9221
9976
|
answeredBy?: 'page';
|
|
9222
9977
|
/**
|
|
9223
|
-
*
|
|
9224
|
-
*
|
|
9225
|
-
*
|
|
9978
|
+
* How the tool gets its credential.
|
|
9979
|
+
*
|
|
9980
|
+
* @remarks The service the handler acts on for the person. The kernel resolves the slot before
|
|
9981
|
+
* the handler runs (gating, refreshing, or telling the model as the policy says) and hands the
|
|
9982
|
+
* handler \`ctx.signedInFetch\`; the handler never sees the credential.
|
|
9226
9983
|
*/
|
|
9227
9984
|
auth?: ToolAuthConfig;
|
|
9228
9985
|
}
|
|
9229
9986
|
/** How a tool that acts for the person signs in to the service; http, mcp, and function tools share it. */
|
|
9230
9987
|
export interface ToolAuthConfig {
|
|
9988
|
+
/** Which of the credentials the turn passes in this tool uses. */
|
|
9231
9989
|
slot: string;
|
|
9990
|
+
/**
|
|
9991
|
+
* The kind of credential the tool expects, shown when a turn stops to ask for one; the header
|
|
9992
|
+
* follows the stored credential's own kind.
|
|
9993
|
+
*/
|
|
9232
9994
|
type: ToolAuthType;
|
|
9233
|
-
/**
|
|
9995
|
+
/**
|
|
9996
|
+
* The service the person signs in to, as they know it, named when a turn stops to ask for a
|
|
9997
|
+
* credential.
|
|
9998
|
+
*
|
|
9999
|
+
* @remarks The service the person signs in to, as they know it (e.g. "GitHub"); never blank.
|
|
10000
|
+
*/
|
|
9234
10001
|
service: string;
|
|
10002
|
+
/** The header the credential goes in; an API key's own headerName comes first. */
|
|
9235
10003
|
headerName?: string;
|
|
10004
|
+
/** Text put before the credential in the header; an API key's own headerPrefix comes first. */
|
|
9236
10005
|
headerPrefix?: string;
|
|
9237
10006
|
/**
|
|
9238
|
-
* For a service that takes its API key in the URL
|
|
9239
|
-
*
|
|
10007
|
+
* For a service that takes its API key in the URL: the query parameter the key goes in, in place
|
|
10008
|
+
* of a header.
|
|
10009
|
+
*
|
|
10010
|
+
* @remarks For a service that takes its API key in the URL (\`?key=…\`): the query parameter the
|
|
10011
|
+
* key goes in, in place of a header. Only an \`api_key\` tool sets it, with no \`headerName\` or
|
|
9240
10012
|
* \`headerPrefix\`.
|
|
9241
10013
|
*/
|
|
9242
10014
|
queryParam?: string;
|
|
10015
|
+
/**
|
|
10016
|
+
* What happens when the credential is missing, expired, can't be refreshed or is refused by the
|
|
10017
|
+
* service.
|
|
10018
|
+
*/
|
|
9243
10019
|
onUnauthenticated?: AuthUnauthenticatedPolicy;
|
|
9244
|
-
/**
|
|
10020
|
+
/**
|
|
10021
|
+
* Named on the auth gate for the host's OAuth flow, so it need not find them.
|
|
10022
|
+
*
|
|
10023
|
+
* @remarks Named on the auth gate for the host's OAuth flow.
|
|
10024
|
+
*/
|
|
9245
10025
|
preResolved?: Partial<OAuthEndpoints & {
|
|
9246
10026
|
resource: string;
|
|
9247
10027
|
}>;
|
|
10028
|
+
/**
|
|
10029
|
+
* The OAuth scopes the tool needs, shown when a turn stops to ask for a credential. A service
|
|
10030
|
+
* asking for any other scope fails the call, with no new sign-in.
|
|
10031
|
+
*/
|
|
9248
10032
|
scopes?: string[];
|
|
10033
|
+
/** Your OAuth client id, kept for the host's sign-in flow; the kernel doesn't read it. */
|
|
9249
10034
|
clientId?: string;
|
|
10035
|
+
/** Your OAuth redirect URI, kept for the host's sign-in flow; the kernel doesn't read it. */
|
|
9250
10036
|
redirectUri?: string;
|
|
9251
10037
|
}
|
|
9252
10038
|
export interface HttpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut>, ToolImageHooks<TOut> {
|
|
10039
|
+
/** How the tool runs. */
|
|
9253
10040
|
type: 'http';
|
|
10041
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9254
10042
|
input: z.ZodType<TIn>;
|
|
10043
|
+
/**
|
|
10044
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
10045
|
+
* not checked.
|
|
10046
|
+
*/
|
|
9255
10047
|
output: z.ZodType<TOut>;
|
|
10048
|
+
/**
|
|
10049
|
+
* The URL the tool calls, with {name} placeholders for mapping.pathParams; the scheme and host
|
|
10050
|
+
* must be written out.
|
|
10051
|
+
*/
|
|
9256
10052
|
endpoint: string;
|
|
10053
|
+
/** The HTTP method; every method but GET sends a JSON body. */
|
|
9257
10054
|
method: HttpMethod;
|
|
10055
|
+
/** Headers sent with every request to the tool's own origin, never once a redirect leaves it. */
|
|
9258
10056
|
headers?: Record<string, string>;
|
|
10057
|
+
/** How the tool gets its credential. */
|
|
9259
10058
|
auth?: ToolAuthConfig;
|
|
10059
|
+
/** Where each argument goes in the request. */
|
|
9260
10060
|
mapping?: {
|
|
10061
|
+
/** Arguments that fill the {name} placeholders in the endpoint. */
|
|
9261
10062
|
pathParams?: string[];
|
|
10063
|
+
/** Arguments added to the query string. */
|
|
9262
10064
|
queryParams?: string[];
|
|
10065
|
+
/**
|
|
10066
|
+
* The one argument sent as the whole JSON body; without it, a method other than GET sends every
|
|
10067
|
+
* argument the path and query leave unused.
|
|
10068
|
+
*/
|
|
9263
10069
|
bodyParam?: string;
|
|
9264
10070
|
};
|
|
9265
10071
|
/** The service's own limit for one key; the kernel keeps this tool's requests within it. */
|
|
9266
10072
|
limit?: HttpToolLimit;
|
|
9267
|
-
/**
|
|
10073
|
+
/**
|
|
10074
|
+
* The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with
|
|
10075
|
+
* response_too_large.
|
|
10076
|
+
*
|
|
10077
|
+
* @remarks The most of a response body the kernel reads; past it the call fails
|
|
10078
|
+
* \`response_too_large\`. Left out, there is no limit.
|
|
10079
|
+
*/
|
|
9268
10080
|
maxResponseBytes?: number;
|
|
9269
10081
|
/**
|
|
9270
|
-
* How long the service may take to answer, its body read included. Past it the call
|
|
9271
|
-
*
|
|
9272
|
-
*
|
|
10082
|
+
* How long the service may take to answer, its body read included. Past it the call fails timeout
|
|
10083
|
+
* and frees its place in the limit.
|
|
10084
|
+
*
|
|
10085
|
+
* @remarks How long the service may take to answer, its body read included. Past it the call
|
|
10086
|
+
* fails \`timeout\` and frees its place in the limit. Left out, a call waits as long as the
|
|
10087
|
+
* caller's signal lets it.
|
|
9273
10088
|
*/
|
|
9274
10089
|
timeoutMs?: number;
|
|
9275
10090
|
}
|
|
@@ -9279,16 +10094,37 @@ export interface HttpToolLimit {
|
|
|
9279
10094
|
windowMs: number;
|
|
9280
10095
|
}
|
|
9281
10096
|
export interface McpToolDef<TIn = unknown, TOut = unknown> extends ToolBase, ToolHostHooks<TIn>, ToolOutputHooks<TOut>, ToolImageHooks<TOut> {
|
|
10097
|
+
/** How the tool runs. */
|
|
9282
10098
|
type: 'mcp';
|
|
10099
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9283
10100
|
input: z.ZodType<TIn>;
|
|
10101
|
+
/**
|
|
10102
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
10103
|
+
* not checked.
|
|
10104
|
+
*/
|
|
9284
10105
|
output: z.ZodType<TOut>;
|
|
10106
|
+
/** The MCP server's URL. */
|
|
9285
10107
|
serverUrl: string;
|
|
10108
|
+
/** The tool's name on the MCP server. */
|
|
9286
10109
|
mcpToolName: string;
|
|
10110
|
+
/** Headers sent with every request to the tool's own origin, never once a redirect leaves it. */
|
|
9287
10111
|
headers?: Record<string, string>;
|
|
10112
|
+
/** How the tool gets its credential. */
|
|
9288
10113
|
auth?: ToolAuthConfig;
|
|
9289
|
-
/**
|
|
10114
|
+
/**
|
|
10115
|
+
* The most bytes of a response body an HTTP or MCP tool reads; past it the call fails with
|
|
10116
|
+
* response_too_large.
|
|
10117
|
+
*
|
|
10118
|
+
* @remarks The most of a response body the kernel reads; past it the call fails
|
|
10119
|
+
* \`response_too_large\`. Left out, there is no limit.
|
|
10120
|
+
*/
|
|
9290
10121
|
maxResponseBytes?: number;
|
|
9291
|
-
/**
|
|
10122
|
+
/**
|
|
10123
|
+
* How long and how many of an MCP tool's server sessions the kernel keeps.
|
|
10124
|
+
*
|
|
10125
|
+
* @remarks How long and how many of this tool's server sessions the kernel keeps. Left out, there
|
|
10126
|
+
* is no limit.
|
|
10127
|
+
*/
|
|
9292
10128
|
session?: McpSessionLimits;
|
|
9293
10129
|
}
|
|
9294
10130
|
/** The sessions an MCP tool keeps: each field left out is no limit. */
|
|
@@ -9325,28 +10161,72 @@ export type AgentToolChannel = 'attachments' | 'voice' | 'options';
|
|
|
9325
10161
|
* is what that profile's \`inputs\` declares; the host can reshape a call (\`onAgentCall\`).
|
|
9326
10162
|
*/
|
|
9327
10163
|
export interface AgentToolDef extends ToolBase {
|
|
10164
|
+
/** How the tool runs. */
|
|
9328
10165
|
type: 'agent';
|
|
9329
|
-
/**
|
|
10166
|
+
/**
|
|
10167
|
+
* The profile this agent tool runs: text, image, or speech. Register it first. Nothing it calls
|
|
10168
|
+
* may stop on a gate.
|
|
10169
|
+
*
|
|
10170
|
+
* @remarks A text, image, or speech profile, registered before this tool. Nothing it can call may
|
|
10171
|
+
* gate.
|
|
10172
|
+
*/
|
|
9330
10173
|
profile: ProfileId;
|
|
9331
|
-
/**
|
|
10174
|
+
/**
|
|
10175
|
+
* How many times one turn of the calling agent may run this tool.
|
|
10176
|
+
*
|
|
10177
|
+
* @remarks Calls to this tool in one turn of its caller. Omit: only \`maxSteps\` bounds them.
|
|
10178
|
+
*/
|
|
9332
10179
|
maxCallsPerTurn?: number;
|
|
9333
|
-
/**
|
|
10180
|
+
/**
|
|
10181
|
+
* What the calling model reads on a field of an agent tool input, such as text. A field the
|
|
10182
|
+
* profile does not take is refused when the tool registers.
|
|
10183
|
+
*
|
|
10184
|
+
* @remarks What the calling model reads on a field of the tool's input, by field. A field the
|
|
10185
|
+
* profile does not take is refused.
|
|
10186
|
+
*/
|
|
9334
10187
|
fieldText?: Partial<Record<keyof AgentToolInput, string>>;
|
|
9335
10188
|
/**
|
|
9336
|
-
* Fields the calling model fills that only the host reads.
|
|
9337
|
-
*
|
|
9338
|
-
*
|
|
10189
|
+
* Fields the calling model fills on an agent tool that only the host reads. onAgentCall gets them
|
|
10190
|
+
* as hostInput and turns them into what the agent is sent; the agent never sees them. A name the
|
|
10191
|
+
* input already has is refused when the tool registers.
|
|
10192
|
+
*
|
|
10193
|
+
* @remarks Fields the calling model fills that only the host reads. \`onAgentCall\` gets them as
|
|
10194
|
+
* \`hostInput\` and turns them into the agent's input; they are never sent to the agent. A name the
|
|
10195
|
+
* input already has is refused, and a call without the hook is a config error.
|
|
9339
10196
|
*/
|
|
9340
10197
|
hostFields?: Record<string, z.ZodType>;
|
|
9341
|
-
/**
|
|
10198
|
+
/**
|
|
10199
|
+
* Channels the called profile takes that the calling model cannot fill on an agent tool; only
|
|
10200
|
+
* onAgentCall sends them. A channel the profile does not take is refused when the tool registers.
|
|
10201
|
+
*
|
|
10202
|
+
* @remarks Channels the profile takes that the calling model can't fill; only \`onAgentCall\` sends
|
|
10203
|
+
* them.
|
|
10204
|
+
*/
|
|
9342
10205
|
hostOnly?: AgentToolChannel[];
|
|
10206
|
+
/** Runs before the host's pre_tool onStage. */
|
|
9343
10207
|
preTool?: ToolHostHooks<AgentToolInput>['preTool'];
|
|
10208
|
+
/**
|
|
10209
|
+
* Gives the model an after field on this tool: the tools called in the same step that must settle
|
|
10210
|
+
* before this call starts. The kernel removes the field before the tool, the stages or a gate
|
|
10211
|
+
* read the input. A name with no other call in the step fails the call wait_unknown.
|
|
10212
|
+
*/
|
|
9344
10213
|
after?: ToolHostHooks<AgentToolInput>['after'];
|
|
10214
|
+
/**
|
|
10215
|
+
* When the model gets its reply while the body goes on. 'always': at the hand-off. { afterMs }:
|
|
10216
|
+
* once the body has run past this time. 'ask': at the hand-off if the model sets the background
|
|
10217
|
+
* argument. A turn with no background service runs the tool inline.
|
|
10218
|
+
*/
|
|
9345
10219
|
background?: ToolHostHooks<AgentToolInput>['background'];
|
|
10220
|
+
/** Whether the model can see and call the tool. */
|
|
9346
10221
|
exposeToModel?: boolean;
|
|
9347
10222
|
}
|
|
9348
10223
|
export interface RegisteredAgentTool extends AgentToolDef, ToolHostHooks<AgentToolInput>, ToolOutputHooks<AgentToolOutput> {
|
|
10224
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9349
10225
|
input: z.ZodType<AgentToolInput>;
|
|
10226
|
+
/**
|
|
10227
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
10228
|
+
* not checked.
|
|
10229
|
+
*/
|
|
9350
10230
|
output: z.ZodType<AgentToolOutput>;
|
|
9351
10231
|
}
|
|
9352
10232
|
/** An agent tool call, as the host's \`onAgentCall\` sees it before the agent runs. */
|
|
@@ -9388,20 +10268,45 @@ export type AgentCallHook = (call: AgentCall) => AgentCallRequest | {
|
|
|
9388
10268
|
export type RegisteredTool<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolDef<TIn, TOut> | HttpToolDef<TIn, TOut> | McpToolDef<TIn, TOut> | RegisteredAgentTool;
|
|
9389
10269
|
/** A function tool as registered: it has a \`handler\`, or the page answers it. */
|
|
9390
10270
|
export type FunctionToolInput<TIn = unknown, TOut = unknown> = Omit<FunctionToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema' | 'handler' | 'answeredBy'> & {
|
|
10271
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9391
10272
|
input: z.ZodType<TIn>;
|
|
10273
|
+
/**
|
|
10274
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in note is
|
|
10275
|
+
* not checked.
|
|
10276
|
+
*/
|
|
9392
10277
|
output: z.ZodType<TOut>;
|
|
9393
10278
|
} & ({
|
|
10279
|
+
/** Your function that runs the tool; it can also yield progress as it goes. */
|
|
9394
10280
|
handler: ToolHandler<TIn, NoInfer<TOut>>;
|
|
10281
|
+
/**
|
|
10282
|
+
* Who answers a call to a function tool. With page, the page the agent is on returns the
|
|
10283
|
+
* output, and the tool has no handler.
|
|
10284
|
+
*/
|
|
9395
10285
|
answeredBy?: 'page';
|
|
9396
10286
|
} | {
|
|
10287
|
+
/**
|
|
10288
|
+
* Who answers a call to a function tool. With page, the page the agent is on returns the
|
|
10289
|
+
* output, and the tool has no handler.
|
|
10290
|
+
*/
|
|
9397
10291
|
answeredBy: 'page';
|
|
10292
|
+
/** Your function that runs the tool; it can also yield progress as it goes. */
|
|
9398
10293
|
handler?: undefined;
|
|
9399
10294
|
});
|
|
9400
10295
|
export type ToolDefinitionInput<TIn = unknown, TOut = unknown> = BuiltinToolDef | FunctionToolInput<TIn, TOut> | (Omit<HttpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
|
|
10296
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9401
10297
|
input: z.ZodType<TIn>;
|
|
10298
|
+
/**
|
|
10299
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in
|
|
10300
|
+
* note is not checked.
|
|
10301
|
+
*/
|
|
9402
10302
|
output: z.ZodType<TOut>;
|
|
9403
10303
|
}) | (Omit<McpToolDef<TIn, TOut>, 'inputSchema' | 'outputSchema'> & {
|
|
10304
|
+
/** The Zod schema for the tool's arguments, sent to the model and checked on every call. */
|
|
9404
10305
|
input: z.ZodType<TIn>;
|
|
10306
|
+
/**
|
|
10307
|
+
* The Zod schema every result the tool returns must match; the kernel's own not-signed-in
|
|
10308
|
+
* note is not checked.
|
|
10309
|
+
*/
|
|
9405
10310
|
output: z.ZodType<TOut>;
|
|
9406
10311
|
}) | AgentToolDef;
|
|
9407
10312
|
export interface PromoteLoadedResult {
|
|
@@ -9484,37 +10389,77 @@ export interface InvokeToolStepRequest extends Omit<InvokeToolRequest, 'name' |
|
|
|
9484
10389
|
}
|
|
9485
10390
|
/** The tools a profile may use and how they load. */
|
|
9486
10391
|
export interface ProfileToolsSpec {
|
|
9487
|
-
/**
|
|
10392
|
+
/**
|
|
10393
|
+
* Your registered tools this agent may use; the provider's own tools go on the model's
|
|
10394
|
+
* builtInTools instead.
|
|
10395
|
+
*
|
|
10396
|
+
* @remarks Custom tools only; builtins live on \`models.*.builtInTools\`.
|
|
10397
|
+
*/
|
|
9488
10398
|
allow: ToolId[];
|
|
9489
|
-
/**
|
|
10399
|
+
/**
|
|
10400
|
+
* Your function that picks, at the start of each turn, which T2 tools to load up front; the rest
|
|
10401
|
+
* wait for tools.t2Loader.
|
|
10402
|
+
*
|
|
10403
|
+
* @remarks Returns ids already allowed with \`loadTier: 'T2'\` to load at turn start. Not supported
|
|
10404
|
+
* on \`type: 'live'\`.
|
|
10405
|
+
*/
|
|
9490
10406
|
t1Policy?: ToolPolicy;
|
|
9491
10407
|
/**
|
|
9492
|
-
*
|
|
9493
|
-
* The tools it loads can be
|
|
10408
|
+
* The function tool that loads T2 tools. It must be in allow and return { loaded: ToolId[] }. One
|
|
10409
|
+
* forbidden id fails the load. Ids off the turn path are skipped. The tools it loads can be
|
|
10410
|
+
* called from the next step: a step's calls see the tools as they stood when the step began.
|
|
10411
|
+
*
|
|
10412
|
+
* @remarks Must be in \`allow\`; completing with \`{ loaded: string[] }\` promotes those T2 ids. Not
|
|
10413
|
+
* on \`type: 'live'\`. The tools it loads can be called from the next step.
|
|
9494
10414
|
*/
|
|
9495
10415
|
t2Loader?: ToolId;
|
|
9496
10416
|
/**
|
|
9497
|
-
*
|
|
9498
|
-
*
|
|
10417
|
+
* true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
|
|
10418
|
+
* its body once those calls settle. Left out or false: they run one at a time, in the order the
|
|
10419
|
+
* model made them. A step is the calls the model makes together in a turn, or the calls a host
|
|
10420
|
+
* runs through invokeToolStep.
|
|
10421
|
+
*
|
|
10422
|
+
* @remarks \`true\`: a step's calls run side by side, each body starting once the calls its
|
|
10423
|
+
* \`pre_tool\` \`waitFor\` names have settled. Left out or \`false\`: one at a time, in the order the
|
|
10424
|
+
* model made them.
|
|
9499
10425
|
*/
|
|
9500
10426
|
parallel?: boolean;
|
|
9501
10427
|
}
|
|
9502
10428
|
/** Live declarations cannot be added mid-session, so every allowed tool is wired at setup as if T0. */
|
|
9503
10429
|
export interface LiveProfileToolsSpec {
|
|
10430
|
+
/**
|
|
10431
|
+
* Your registered tools this agent may use; the provider's own tools go on the model's
|
|
10432
|
+
* builtInTools instead.
|
|
10433
|
+
*/
|
|
9504
10434
|
allow: ToolId[];
|
|
9505
10435
|
/**
|
|
9506
|
-
*
|
|
9507
|
-
*
|
|
9508
|
-
*
|
|
10436
|
+
* true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
|
|
10437
|
+
* its body once those calls settle. Left out or false: they run one at a time, in the order the
|
|
10438
|
+
* model made them. A step is the calls the model makes together in a turn, or the calls a host
|
|
10439
|
+
* runs through invokeToolStep.
|
|
10440
|
+
*
|
|
10441
|
+
* @remarks \`true\`: the calls of one model message, run as a step through \`invokeToolStep\`, run
|
|
10442
|
+
* side by side, each body starting once the calls its \`pre_tool\` \`waitFor\` names have settled.
|
|
10443
|
+
* Left out or \`false\`: one at a time, in the order the model made them.
|
|
9509
10444
|
*/
|
|
9510
10445
|
parallel?: boolean;
|
|
9511
10446
|
}
|
|
9512
10447
|
/** Every id in \`allow\` is invokable with no visibility tiers and no path gating. */
|
|
9513
10448
|
export interface HostProfileToolsSpec {
|
|
10449
|
+
/**
|
|
10450
|
+
* Your registered tools this agent may use; the provider's own tools go on the model's
|
|
10451
|
+
* builtInTools instead.
|
|
10452
|
+
*/
|
|
9514
10453
|
allow: ToolId[];
|
|
9515
10454
|
/**
|
|
9516
|
-
*
|
|
9517
|
-
* its
|
|
10455
|
+
* true: the calls of one step run side by side, and a call whose pre_tool answers waitFor starts
|
|
10456
|
+
* its body once those calls settle. Left out or false: they run one at a time, in the order the
|
|
10457
|
+
* model made them. A step is the calls the model makes together in a turn, or the calls a host
|
|
10458
|
+
* runs through invokeToolStep.
|
|
10459
|
+
*
|
|
10460
|
+
* @remarks \`true\`: the calls of one \`invokeToolStep\` run side by side, each body starting once
|
|
10461
|
+
* the calls its \`pre_tool\` \`waitFor\` names have settled. Left out or \`false\`: one at a time, in
|
|
10462
|
+
* the order given.
|
|
9518
10463
|
*/
|
|
9519
10464
|
parallel?: boolean;
|
|
9520
10465
|
}
|
|
@@ -9875,6 +10820,10 @@ import { type ToolCallBase } from './events.js';
|
|
|
9875
10820
|
import { type ToolExecutionCoordinator, type ToolOperationReply } from './operation.js';
|
|
9876
10821
|
/** When the model gets its reply: at the hand-off, past a time, if it asks, or when the body ends. */
|
|
9877
10822
|
export type ToolBackground = 'always' | {
|
|
10823
|
+
/**
|
|
10824
|
+
* Milliseconds the body runs before the model gets its reply. A body that ends sooner answers
|
|
10825
|
+
* in the turn.
|
|
10826
|
+
*/
|
|
9878
10827
|
afterMs: number;
|
|
9879
10828
|
} | 'ask' | 'never';
|
|
9880
10829
|
/** The call a detached event belongs to. */
|
|
@@ -10604,7 +11553,11 @@ export { toOtlpJson };
|
|
|
10604
11553
|
`,"file:///node_modules/@theoremjs/agents/src/observability/destinations.d.ts":`import type { TraceSink } from './trace-sink.js';
|
|
10605
11554
|
/** True when the value is a trace sink. */
|
|
10606
11555
|
declare function isTraceSink(value: unknown): value is TraceSink;
|
|
10607
|
-
/**
|
|
11556
|
+
/**
|
|
11557
|
+
* Stores a place to write traces under an id, so that a profile can name it in observability.
|
|
11558
|
+
*
|
|
11559
|
+
* @remarks Register a trace sink under an id; throws when the id is empty.
|
|
11560
|
+
*/
|
|
10608
11561
|
declare function registerTraceDestination(id: string, destination: TraceSink): void;
|
|
10609
11562
|
/** The sink registered under the id, or \`undefined\`. */
|
|
10610
11563
|
declare function getTraceDestination(id: string): TraceSink | undefined;
|
|
@@ -10711,89 +11664,238 @@ import type { DecisionModelBinding, DecisionProfile, EmbeddingProfile, HostProfi
|
|
|
10711
11664
|
import type { SchemaRegistry } from './schemas.js';
|
|
10712
11665
|
/** Not shared by host profiles, which invoke tools without a model turn. */
|
|
10713
11666
|
export type ProfileDefinitionBase = {
|
|
11667
|
+
/**
|
|
11668
|
+
* The name this profile is registered and looked up by, at most 64 characters; registering the
|
|
11669
|
+
* same id again replaces it.
|
|
11670
|
+
*/
|
|
10714
11671
|
id: Profile['id'];
|
|
11672
|
+
/** The agent's display name and the system instruction it is given. */
|
|
10715
11673
|
identity: ProfileIdentity;
|
|
11674
|
+
/**
|
|
11675
|
+
* The trained AI systems that turn input into results. Each entry binds a local name to an
|
|
11676
|
+
* upstream model and its call settings.
|
|
11677
|
+
*
|
|
11678
|
+
* @catalog models.* One model: how to reach it and the settings sent with it.
|
|
11679
|
+
*/
|
|
10716
11680
|
models: Record<ModelId, ModelBinding>;
|
|
11681
|
+
/** Who holds the conversation a saved provider state continues. */
|
|
10717
11682
|
providerContinuation?: import('../checkpoint.js').ProviderContinuationPolicy;
|
|
11683
|
+
/** The model a turn gets when it doesn't pick one. */
|
|
10718
11684
|
defaultModel?: ModelId;
|
|
11685
|
+
/** Lets a turn name the model it runs on; a name the profile does not declare is refused. */
|
|
10719
11686
|
allowModelSelect?: boolean;
|
|
11687
|
+
/**
|
|
11688
|
+
* The most model calls one turn may make while using tools, counted afresh for each rewrite; 1
|
|
11689
|
+
* runs the tools asked for but never sends their results back. Live sessions ignore it.
|
|
11690
|
+
*/
|
|
10720
11691
|
maxSteps?: number;
|
|
11692
|
+
/** The shape of the reply, how it is checked, and how it streams. */
|
|
10721
11693
|
outputs?: ProfileOutputsSpec;
|
|
11694
|
+
/**
|
|
11695
|
+
* Theorem checks what enters or leaves an agent’s context and generation against built-in or
|
|
11696
|
+
* custom rules at each configured boundary.
|
|
11697
|
+
*/
|
|
10722
11698
|
guardrails?: ProfileGuardrailsSpec;
|
|
11699
|
+
/** Where this profile's traces go and what they keep. */
|
|
10723
11700
|
observability?: ProfileObservabilitySpec;
|
|
11701
|
+
/**
|
|
11702
|
+
* This profile's own wording for error lines, notices, and notes to the model, by labels key.
|
|
11703
|
+
*
|
|
11704
|
+
* @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
|
|
11705
|
+
*/
|
|
10724
11706
|
labels?: LabelOverrides;
|
|
10725
11707
|
};
|
|
10726
11708
|
/** What a host writes to define an embedding profile. */
|
|
10727
11709
|
export type EmbeddingProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
|
|
11710
|
+
/**
|
|
11711
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11712
|
+
* transcription, live, decision, embedding, or host.
|
|
11713
|
+
*/
|
|
10728
11714
|
type: 'embedding';
|
|
11715
|
+
/** The agent's display name and the system instruction it is given. */
|
|
10729
11716
|
identity: Pick<ProfileIdentity, 'handle'>;
|
|
11717
|
+
/** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
|
|
10730
11718
|
inputs: EmbeddingProfile['inputs'];
|
|
10731
11719
|
};
|
|
10732
11720
|
/** What a host writes to define a text profile. */
|
|
10733
11721
|
export type TextProfileDefinition = ProfileDefinitionBase & {
|
|
11722
|
+
/**
|
|
11723
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11724
|
+
* transcription, live, decision, embedding, or host.
|
|
11725
|
+
*/
|
|
10734
11726
|
type: 'text';
|
|
11727
|
+
/**
|
|
11728
|
+
* The registered tools this profile may use, and how they load. Built-in tools are set per model.
|
|
11729
|
+
*/
|
|
10735
11730
|
tools: ProfileToolsSpec;
|
|
11731
|
+
/** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
|
|
10736
11732
|
inputs: ProfileInputsSpec;
|
|
11733
|
+
/**
|
|
11734
|
+
* Whether a reply that stopped early can be continued, and whether a running turn can be steered.
|
|
11735
|
+
*/
|
|
10737
11736
|
turnBehaviour?: ProfileTurnBehaviourSpec;
|
|
10738
11737
|
};
|
|
10739
11738
|
/** What a host writes to define an image profile. */
|
|
10740
11739
|
export type ImageProfileDefinition = ProfileDefinitionBase & {
|
|
11740
|
+
/**
|
|
11741
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11742
|
+
* transcription, live, decision, embedding, or host.
|
|
11743
|
+
*/
|
|
10741
11744
|
type: 'image';
|
|
11745
|
+
/**
|
|
11746
|
+
* How the images this profile generates are shaped and made: size, format, quality and
|
|
11747
|
+
* references. Each setting is sent only where the provider has it; one it lacks is refused or
|
|
11748
|
+
* ignored, as that setting says.
|
|
11749
|
+
*/
|
|
10742
11750
|
image: NonNullable<ImageProfile['image']>;
|
|
11751
|
+
/**
|
|
11752
|
+
* The registered tools this profile may use, and how they load. Built-in tools are set per model.
|
|
11753
|
+
*/
|
|
10743
11754
|
tools: ProfileToolsSpec;
|
|
11755
|
+
/** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
|
|
10744
11756
|
inputs: ImageInputsSpec;
|
|
11757
|
+
/**
|
|
11758
|
+
* Whether a reply that stopped early can be continued, and whether a running turn can be steered.
|
|
11759
|
+
*/
|
|
10745
11760
|
turnBehaviour?: MediaTurnBehaviourSpec;
|
|
10746
11761
|
};
|
|
10747
11762
|
/** What a host writes to define a speech profile. */
|
|
10748
11763
|
export type SpeechProfileDefinition = Omit<ProfileDefinitionBase, 'identity'> & {
|
|
11764
|
+
/**
|
|
11765
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11766
|
+
* transcription, live, decision, embedding, or host.
|
|
11767
|
+
*/
|
|
10749
11768
|
type: 'speech';
|
|
11769
|
+
/** The agent's display name and the system instruction it is given. */
|
|
10750
11770
|
identity: SpeechProfile['identity'];
|
|
11771
|
+
/**
|
|
11772
|
+
* How the profile's speech sounds and is delivered: voice, style, speed and audio format. A turn
|
|
11773
|
+
* may replace voice, style and speed for that turn.
|
|
11774
|
+
*/
|
|
10751
11775
|
speech: NonNullable<SpeechProfile['speech']>;
|
|
11776
|
+
/**
|
|
11777
|
+
* Whether a reply that stopped early can be continued, and whether a running turn can be steered.
|
|
11778
|
+
*/
|
|
10752
11779
|
turnBehaviour?: MediaTurnBehaviourSpec;
|
|
10753
11780
|
};
|
|
10754
11781
|
/** What a host writes to define a transcription profile. */
|
|
10755
11782
|
export type TranscriptionProfileDefinition = Omit<ProfileDefinitionBase, 'identity' | 'outputs' | 'maxSteps'> & {
|
|
11783
|
+
/**
|
|
11784
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11785
|
+
* transcription, live, decision, embedding, or host.
|
|
11786
|
+
*/
|
|
10756
11787
|
type: 'transcription';
|
|
11788
|
+
/** The agent's display name and the system instruction it is given. */
|
|
10757
11789
|
identity: TranscriptionProfile['identity'];
|
|
11790
|
+
/** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
|
|
10758
11791
|
inputs: TranscriptionInputsSpec & {
|
|
10759
|
-
text?: false;
|
|
11792
|
+
/** Whether a turn may send text. */ text?: false;
|
|
10760
11793
|
};
|
|
10761
11794
|
};
|
|
10762
11795
|
/** What a host writes to define a live profile. */
|
|
10763
11796
|
export type LiveProfileDefinition = Omit<ProfileDefinitionBase, 'maxSteps'> & {
|
|
11797
|
+
/**
|
|
11798
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11799
|
+
* transcription, live, decision, embedding, or host.
|
|
11800
|
+
*/
|
|
10764
11801
|
type: 'live';
|
|
11802
|
+
/**
|
|
11803
|
+
* How a realtime voice and video session runs: what it accepts from the user, the voice it
|
|
11804
|
+
* answers in, when it hears the user start and stop, and how it resumes and trims its context.
|
|
11805
|
+
*/
|
|
10765
11806
|
live: NonNullable<LiveProfile['live']>;
|
|
11807
|
+
/** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
|
|
10766
11808
|
inputs?: LiveProfile['inputs'];
|
|
11809
|
+
/**
|
|
11810
|
+
* The registered tools this profile may use, and how they load. Built-in tools are set per model.
|
|
11811
|
+
*/
|
|
10767
11812
|
tools: LiveProfileToolsSpec;
|
|
10768
|
-
/**
|
|
11813
|
+
/**
|
|
11814
|
+
* Whether a reply that stopped early can be continued, and whether a running turn can be steered.
|
|
11815
|
+
*
|
|
11816
|
+
* @remarks Inject gate only — resumption is \`live.sessionResumption\`.
|
|
11817
|
+
*/
|
|
10769
11818
|
turnBehaviour?: Pick<ProfileTurnBehaviourSpec, 'allowSteering'>;
|
|
10770
11819
|
};
|
|
10771
11820
|
/** What a host writes to define a decision profile. */
|
|
10772
11821
|
export type DecisionProfileDefinition = {
|
|
11822
|
+
/**
|
|
11823
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11824
|
+
* transcription, live, decision, embedding, or host.
|
|
11825
|
+
*/
|
|
10773
11826
|
type: 'decision';
|
|
11827
|
+
/**
|
|
11828
|
+
* The name this profile is registered and looked up by, at most 64 characters; registering the
|
|
11829
|
+
* same id again replaces it.
|
|
11830
|
+
*/
|
|
10774
11831
|
id: Profile['id'];
|
|
11832
|
+
/** The agent's display name and the system instruction it is given. */
|
|
10775
11833
|
identity: Pick<ProfileIdentity, 'handle'>;
|
|
10776
|
-
/**
|
|
11834
|
+
/**
|
|
11835
|
+
* The trained AI systems that turn input into results. Each entry binds a local name to an
|
|
11836
|
+
* upstream model and its call settings.
|
|
11837
|
+
*
|
|
11838
|
+
* @remarks Exactly one model.
|
|
11839
|
+
* @catalog models.* One model: how to reach it and the settings sent with it.
|
|
11840
|
+
*/
|
|
10777
11841
|
models: Record<ModelId, DecisionModelBinding>;
|
|
11842
|
+
/** What a turn may send (text, files, voice, choices), or on a decision, the state it reads. */
|
|
10778
11843
|
inputs: DecisionProfile['inputs'];
|
|
11844
|
+
/** Names the host decision this profile makes. */
|
|
10779
11845
|
decision: DecisionProfile['decision'];
|
|
11846
|
+
/**
|
|
11847
|
+
* Theorem checks what enters or leaves an agent’s context and generation against built-in or
|
|
11848
|
+
* custom rules at each configured boundary.
|
|
11849
|
+
*/
|
|
10780
11850
|
guardrails?: DecisionGuardrailsSpec;
|
|
11851
|
+
/** Where this profile's traces go and what they keep. */
|
|
10781
11852
|
observability?: ProfileObservabilitySpec;
|
|
11853
|
+
/**
|
|
11854
|
+
* This profile's own wording for error lines, notices, and notes to the model, by labels key.
|
|
11855
|
+
*
|
|
11856
|
+
* @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
|
|
11857
|
+
*/
|
|
10782
11858
|
labels?: LabelOverrides;
|
|
10783
11859
|
};
|
|
10784
11860
|
/** What a host writes to define a host profile, which runs tools and no model. */
|
|
10785
11861
|
export type HostProfileDefinition = {
|
|
11862
|
+
/**
|
|
11863
|
+
* What kind of agent this is, and so what each call gives back: text, image, speech,
|
|
11864
|
+
* transcription, live, decision, embedding, or host.
|
|
11865
|
+
*/
|
|
10786
11866
|
type: 'host';
|
|
11867
|
+
/**
|
|
11868
|
+
* The name this profile is registered and looked up by, at most 64 characters; registering the
|
|
11869
|
+
* same id again replaces it.
|
|
11870
|
+
*/
|
|
10787
11871
|
id: Profile['id'];
|
|
11872
|
+
/**
|
|
11873
|
+
* The registered tools this profile may use, and how they load. Built-in tools are set per model.
|
|
11874
|
+
*/
|
|
10788
11875
|
tools: HostProfileToolsSpec;
|
|
10789
|
-
/**
|
|
11876
|
+
/**
|
|
11877
|
+
* Theorem checks what enters or leaves an agent’s context and generation against built-in or
|
|
11878
|
+
* custom rules at each configured boundary.
|
|
11879
|
+
*
|
|
11880
|
+
* @remarks Only the guards that fire on the \`invokeTool\` path.
|
|
11881
|
+
*/
|
|
10790
11882
|
guardrails?: HostGuardrailsSpec;
|
|
11883
|
+
/** Where this profile's traces go and what they keep. */
|
|
10791
11884
|
observability?: ProfileObservabilitySpec;
|
|
11885
|
+
/**
|
|
11886
|
+
* This profile's own wording for error lines, notices, and notes to the model, by labels key.
|
|
11887
|
+
*
|
|
11888
|
+
* @catalog labels.* The wording for this labels key; canary.bind_note must keep its {canary} placeholder.
|
|
11889
|
+
*/
|
|
10792
11890
|
labels?: LabelOverrides;
|
|
10793
11891
|
};
|
|
10794
11892
|
/** Any profile definition, discriminated by \`type\`. */
|
|
10795
11893
|
export type ProfileDefinition = TextProfileDefinition | ImageProfileDefinition | SpeechProfileDefinition | LiveProfileDefinition | DecisionProfileDefinition | TranscriptionProfileDefinition | EmbeddingProfileDefinition | HostProfileDefinition;
|
|
10796
|
-
/**
|
|
11894
|
+
/**
|
|
11895
|
+
* Checks a profile and returns it; a field the profile type cannot take is a config error.
|
|
11896
|
+
*
|
|
11897
|
+
* @remarks Validate a definition and return the profile; throws on a malformed one.
|
|
11898
|
+
*/
|
|
10797
11899
|
declare function defineProfile(input: TextProfileDefinition): TextProfile;
|
|
10798
11900
|
/** Validate an image definition and return the profile. */
|
|
10799
11901
|
declare function defineProfile(input: ImageProfileDefinition): ImageProfile;
|
|
@@ -12313,7 +13415,11 @@ import { defaultKernelScope as scope } from './scope.js';
|
|
|
12313
13415
|
import type { ToolCallResult, ToolStepCallResult } from './tools/run.js';
|
|
12314
13416
|
import type { InvokeToolRequest, InvokeToolStepRequest, RegisteredTool, ToolDefinitionInput } from './tools/types.js';
|
|
12315
13417
|
import type { CompactHistoryRequest, CompactionResult, DecisionRequest, DecisionResult, EmbeddingRequest, EmbeddingResult, LiveSession, Profile, ProjectedProfile, SessionRequest, StructuredSpec, TurnEvent, TurnRequest } from './types.js';
|
|
12316
|
-
/**
|
|
13418
|
+
/**
|
|
13419
|
+
* Stores a tool under its name, so that a profile can list it in tools.allow.
|
|
13420
|
+
*
|
|
13421
|
+
* @remarks Register or replace a tool in the default scope.
|
|
13422
|
+
*/
|
|
12317
13423
|
declare function registerTool<TIn, TOut>(def: ToolDefinitionInput<TIn, TOut>): RegisteredTool<TIn, TOut>;
|
|
12318
13424
|
/** Register or replace several tools in the default scope. */
|
|
12319
13425
|
declare function registerTools(defs: ToolDefinitionInput[]): RegisteredTool[];
|
|
@@ -12327,7 +13433,11 @@ declare function hasTool(name: string): boolean;
|
|
|
12327
13433
|
declare function listTools(): RegisteredTool[];
|
|
12328
13434
|
/** Remove every tool from the default scope. */
|
|
12329
13435
|
declare function resetTools(): void;
|
|
12330
|
-
/**
|
|
13436
|
+
/**
|
|
13437
|
+
* Stores a profile under its id, so that a request can name it.
|
|
13438
|
+
*
|
|
13439
|
+
* @remarks Define, validate, and register a profile in the default scope.
|
|
13440
|
+
*/
|
|
12331
13441
|
declare function registerProfile(profile: Profile | ProfileDefinition): void;
|
|
12332
13442
|
/** Define, validate, and register several profiles in the default scope. */
|
|
12333
13443
|
declare function registerProfiles(profiles: Array<Profile | ProfileDefinition>): void;
|
|
@@ -12339,21 +13449,47 @@ declare function hasProfile(id: string): boolean;
|
|
|
12339
13449
|
declare function listProfiles(): Profile[];
|
|
12340
13450
|
/** Remove every profile from the default scope. */
|
|
12341
13451
|
declare function clearProfiles(): void;
|
|
12342
|
-
/**
|
|
13452
|
+
/**
|
|
13453
|
+
* Stores a JSON Schema under an id, so that a profile can name it in outputs.structured.
|
|
13454
|
+
*
|
|
13455
|
+
* @remarks Register a structured-output schema in the default scope under \`id\`.
|
|
13456
|
+
*/
|
|
12343
13457
|
declare function registerStructured(id: string, spec: StructuredSpec): void;
|
|
12344
13458
|
/** The default scope's schema \`id\`; throws when there is none. */
|
|
12345
13459
|
declare function getStructured(id: string): StructuredSpec;
|
|
12346
|
-
/**
|
|
13460
|
+
/**
|
|
13461
|
+
* Runs one turn of a text, image, or speech profile and yields its events.
|
|
13462
|
+
*
|
|
13463
|
+
* @remarks Run one turn of a profile in the default scope, streaming its events.
|
|
13464
|
+
*/
|
|
12347
13465
|
declare function runTurn(req: TurnRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
|
|
12348
|
-
/**
|
|
13466
|
+
/**
|
|
13467
|
+
* Runs a realtime voice or video session of a live profile.
|
|
13468
|
+
*
|
|
13469
|
+
* @remarks Open a live session for a live profile in the default scope.
|
|
13470
|
+
*/
|
|
12349
13471
|
declare function runSession(req: SessionRequest, options: RunSessionOptions, sinkOverride?: TraceSink): Promise<LiveSession>;
|
|
12350
|
-
/**
|
|
13472
|
+
/**
|
|
13473
|
+
* Shortens a conversation history with the compaction the profile sets.
|
|
13474
|
+
*
|
|
13475
|
+
* @remarks Compact a conversation history with the model, or \`undefined\` when there is nothing to
|
|
13476
|
+
* compact.
|
|
13477
|
+
*/
|
|
12351
13478
|
declare function compactHistory(req: CompactHistoryRequest, options?: ProviderHostOptions, sinkOverride?: TraceSink): Promise<CompactionResult | undefined>;
|
|
12352
|
-
/**
|
|
13479
|
+
/**
|
|
13480
|
+
* Runs one registered tool through a profile, with no model.
|
|
13481
|
+
*
|
|
13482
|
+
* @remarks Run a held tool call in the default scope, streaming the events of the turn it resumes.
|
|
13483
|
+
*/
|
|
12353
13484
|
declare function invokeTool(request: InvokeToolRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
|
|
12354
13485
|
/** Run the host's calls as one step in the default scope, streaming each call's events as they come. */
|
|
12355
13486
|
declare function invokeToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<TurnEvent>;
|
|
12356
|
-
/**
|
|
13487
|
+
/**
|
|
13488
|
+
* Runs one registered tool through a profile, with no model, and returns how the call settled.
|
|
13489
|
+
*
|
|
13490
|
+
* @remarks Run one tool call in the default scope to its end: how it settled, with every event it
|
|
13491
|
+
* emitted.
|
|
13492
|
+
*/
|
|
12357
13493
|
declare function runTool(request: InvokeToolRequest, sinkOverride?: TraceSink): Promise<ToolCallResult>;
|
|
12358
13494
|
/** Run the host's calls as one step in the default scope, giving each call's end as it settles. */
|
|
12359
13495
|
declare function runToolStep(request: InvokeToolStepRequest, sinkOverride?: TraceSink): AsyncGenerator<ToolStepCallResult>;
|
|
@@ -12362,12 +13498,20 @@ declare function resolveTurn(req: TurnRequest): ReturnType<typeof scope.resolveT
|
|
|
12362
13498
|
/** Each model of profile \`id\` in the default scope that cannot run a plain turn on its provider, and why. */
|
|
12363
13499
|
/** The profile \`id\` projected for a client, with server-only fields removed. */
|
|
12364
13500
|
declare function projectProfile(id: string): ProjectedProfile;
|
|
12365
|
-
/**
|
|
13501
|
+
/**
|
|
13502
|
+
* Asks a decision profile its questions about your JSON state and returns checked answers.
|
|
13503
|
+
*
|
|
13504
|
+
* @remarks Answer a decision request with the profile's model in the default scope.
|
|
13505
|
+
*/
|
|
12366
13506
|
declare function runDecision(request: DecisionRequest, options: RunDecisionOptions): Promise<DecisionResult>;
|
|
12367
13507
|
/** Create vectors for one or more inputs in the default scope. */
|
|
12368
13508
|
declare function runEmbedding(request: EmbeddingRequest, options?: RunEmbeddingOptions): Promise<EmbeddingResult>;
|
|
12369
13509
|
export { clearProfiles, compactHistory, getProfile, getStructured, getTool, hasProfile, hasTool, invokeTool, invokeToolStep, listProfiles, listTools, projectProfile, registerProfile, registerProfiles, registerStructured, registerTool, registerTools, requireTool, resetTools, resolveTurn, runDecision, runEmbedding, runSession, runTool, runToolStep, runTurn, };
|
|
12370
|
-
/**
|
|
13510
|
+
/**
|
|
13511
|
+
* Registers a provider instance before profiles reference its ID.
|
|
13512
|
+
*
|
|
13513
|
+
* @remarks Registers a provider in the default scope, with this project's connection and key slots.
|
|
13514
|
+
*/
|
|
12371
13515
|
export declare function registerProvider<C, K>(provider: Provider<C, K>, registration?: Registration<C>): RegisteredProvider;
|
|
12372
13516
|
export declare function getProvider(id: string): RegisteredProvider | undefined;
|
|
12373
13517
|
export declare function listProviders(): RegisteredProvider[];
|
|
@@ -12422,11 +13566,17 @@ declare function skipQuota(peer: string, req: Request): boolean;
|
|
|
12422
13566
|
/** Resolves the client identity, preferring Cloudflare's header for local peers. */
|
|
12423
13567
|
declare function clientIp(peer: string, req: Request): string;
|
|
12424
13568
|
/**
|
|
12425
|
-
*
|
|
12426
|
-
*
|
|
13569
|
+
* Takes a client's turn slot on a profile; it answers ok, busy, quota, or not_configured.
|
|
13570
|
+
*
|
|
13571
|
+
* @remarks Reserves one profile-and-client daily quota slot. The reservation stays busy until
|
|
13572
|
+
* \`releaseSlot\` is called, preventing concurrent turns from overspending.
|
|
12427
13573
|
*/
|
|
12428
13574
|
declare function takeSlot(profile: Profile, ip: string, now: number): QuotaSlotStatus;
|
|
12429
|
-
/**
|
|
13575
|
+
/**
|
|
13576
|
+
* Frees the turn slot that takeSlot gave.
|
|
13577
|
+
*
|
|
13578
|
+
* @remarks Releases an active quota reservation without decrementing its daily count.
|
|
13579
|
+
*/
|
|
12430
13580
|
declare function releaseSlot(profile: Profile, ip: string): void;
|
|
12431
13581
|
/** \`undefined\` when the profile has no quota configured. */
|
|
12432
13582
|
declare function quotaExhausted(profile: Profile): TheoremError | undefined;
|