@12-apps/llm 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +141 -2
- package/dist/index.d.ts +231 -3
- package/dist/index.js +349 -7
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -16,6 +16,8 @@ interface onto the provider's official SDK and maps the answer back.
|
|
|
16
16
|
refresh hook, both behind one interface.
|
|
17
17
|
- **A tool-use loop** that reports every turn's usage.
|
|
18
18
|
- **Typed errors** and one retry hook the host supplies.
|
|
19
|
+
- **A support ladder**: automation, then model tiers that escalate, then a
|
|
20
|
+
person, with least-privilege tools per tier bound to the host's scope.
|
|
19
21
|
|
|
20
22
|
Only chat ships today. The `Capability` union leaves room for others (a
|
|
21
23
|
transcription capability is planned), and an adapter declares what it can do.
|
|
@@ -260,7 +262,7 @@ const outcome = await runToolLoop({
|
|
|
260
262
|
onUsage: (usage, turn) => meter.record(usage), // once per turn, refused turns included
|
|
261
263
|
});
|
|
262
264
|
|
|
263
|
-
outcome.status; // "completed" | "refused" | "max_turns" | "max_tokens" | "stopped"
|
|
265
|
+
outcome.status; // "completed" | "refused" | "max_turns" | "max_tokens" | "stopped" | "halted"
|
|
264
266
|
outcome.messages; // the conversation with every turn and tool result appended
|
|
265
267
|
outcome.usage; // the summed usage
|
|
266
268
|
outcome.refusal; // set when status is "refused"
|
|
@@ -269,7 +271,143 @@ outcome.refusal; // set when status is "refused"
|
|
|
269
271
|
The loop runs every tool call of a turn and sends all the results back
|
|
270
272
|
together. An unknown tool, or an executor that throws, becomes an error result
|
|
271
273
|
the model can read and recover from. When the turn limit is reached, the loop
|
|
272
|
-
stops without running the last turn's calls.
|
|
274
|
+
stops without running the last turn's calls. An executor that returns
|
|
275
|
+
`{ output, halt: true }` ends the loop with `status: "halted"` once every call
|
|
276
|
+
of that turn has its result, and no further model call is made.
|
|
277
|
+
|
|
278
|
+
## The support ladder
|
|
279
|
+
|
|
280
|
+
`createSupportLadder` routes each customer message up a ladder. Automation
|
|
281
|
+
answers what the host recognises with no model call. Anything else goes to
|
|
282
|
+
the first model tier, which answers or escalates. A tier escalates to the next
|
|
283
|
+
tier, which runs on the same message in the same call, or to a person. The
|
|
284
|
+
ladder carries no domain: tiers, tools, copy and the person are all the host's.
|
|
285
|
+
|
|
286
|
+
```ts
|
|
287
|
+
import { createSupportLadder, mcpTools } from "@12-apps/llm";
|
|
288
|
+
|
|
289
|
+
const ladder = createSupportLadder<{ accountId: string }, { locale: string }>({
|
|
290
|
+
automation: {
|
|
291
|
+
greeting: () => "Hi! Reply 1 for opening hours, 2 to reset your password.",
|
|
292
|
+
match: (message) => (message.trim() === "1" ? { reply: "We answer 9 to 5, Monday to Friday." } : null),
|
|
293
|
+
},
|
|
294
|
+
tiers: [
|
|
295
|
+
{
|
|
296
|
+
id: "triage",
|
|
297
|
+
client: { provider: "openai", model: "gpt-5-mini", credentials }, // or a ModelClient
|
|
298
|
+
instructions: "You answer simple helpdesk questions from the knowledge base.",
|
|
299
|
+
tools: [searchArticles], // read-only
|
|
300
|
+
},
|
|
301
|
+
{
|
|
302
|
+
id: "specialist",
|
|
303
|
+
client: { provider: "anthropic", model: "claude-opus-5-5", credentials },
|
|
304
|
+
instructions: "You resolve account problems, or hand them to a person.",
|
|
305
|
+
tools: [
|
|
306
|
+
searchArticles,
|
|
307
|
+
mcpTools({
|
|
308
|
+
connect: (scope) => accountServer.connectAs(scope.accountId), // the scope's own token
|
|
309
|
+
allow: ["reset_password"], // nothing else of the server's
|
|
310
|
+
}),
|
|
311
|
+
],
|
|
312
|
+
},
|
|
313
|
+
],
|
|
314
|
+
person: { handOff: ({ conversationId, reason, fromTier }) => queue.push({ conversationId, reason, fromTier }) },
|
|
315
|
+
state: {
|
|
316
|
+
get: (id) => levels.get(id),
|
|
317
|
+
// ATOMIC compare-and-set: store `to` only while the level is still `from`.
|
|
318
|
+
raise: (id, from, to) => levels.compareAndSet(id, from, to), // true when it moved
|
|
319
|
+
},
|
|
320
|
+
scopeFields: ["accountId"], // the model may never set these
|
|
321
|
+
onUsage: (tier, usage) => meter.record(tier, usage),
|
|
322
|
+
});
|
|
323
|
+
|
|
324
|
+
const result = await ladder.handle({
|
|
325
|
+
conversationId: "conv-42",
|
|
326
|
+
message: "I can't sign in",
|
|
327
|
+
transcript, // the conversation before this message
|
|
328
|
+
context: { locale: "en" },
|
|
329
|
+
scope: { accountId: "acct-7" }, // from the host's session, never from the model
|
|
330
|
+
});
|
|
331
|
+
|
|
332
|
+
switch (result.kind) {
|
|
333
|
+
case "automation": send(result.reply); break; // source: "greeting" | "match"
|
|
334
|
+
case "model": send(result.reply); break; // result.tier answered
|
|
335
|
+
case "person": notifyAgent(result); break; // fromTier, reason, handedOff
|
|
336
|
+
}
|
|
337
|
+
result.usage; // [{ tier, turns, usage }] per tier that ran, to meter each model separately
|
|
338
|
+
result.escalations; // [{ from, to, reason }]
|
|
339
|
+
```
|
|
340
|
+
|
|
341
|
+
- **Each tier answers or escalates.** Every tier gets the ladder's `escalate`
|
|
342
|
+
tool, `{ to: "next" | "person", reason }`; `"next"` is not offered on the last
|
|
343
|
+
tier. A refusal escalates with reason `"refused"`, and a turn with no words
|
|
344
|
+
with `"no_answer"`: to the next tier, or to a person from the last. A turn
|
|
345
|
+
that calls `escalate` leaves the tier: the other tools it called in that
|
|
346
|
+
turn are answered "not run" and never execute, and when it calls `escalate`
|
|
347
|
+
more than once, the FIRST call (in the model's order) decides and the rest
|
|
348
|
+
are ignored.
|
|
349
|
+
- **The next tier hears why.** The escalating tier's reason reaches the next
|
|
350
|
+
tier as a delimited USER-role note just before the customer's message
|
|
351
|
+
(`<handover from="…">…</handover>`, at most 500 characters, angle brackets
|
|
352
|
+
removed), never as a system block: it is the prior model's words, derived
|
|
353
|
+
from the customer's. The note is left out of the `messages` a result returns.
|
|
354
|
+
- **A conversation stays where it reached.** The `state` port stores the tier
|
|
355
|
+
that answered, or `"person"` (`WITH_PERSON`). The next message goes straight
|
|
356
|
+
to that tier; automation is consulted only before a conversation reached a
|
|
357
|
+
tier. Once a person has it, `handle` returns `{ kind: "person", handedOff:
|
|
358
|
+
false }` and never calls a model or `handOff` again.
|
|
359
|
+
- **Two messages in flight.** A customer can send two lines before the first
|
|
360
|
+
is answered, so the ladder never writes a level blindly. The port's one
|
|
361
|
+
write is `raise(conversationId, from, to) → boolean`, which the host makes
|
|
362
|
+
ATOMIC (a conditional `UPDATE … WHERE level = $from`, a Redis `WATCH`/Lua
|
|
363
|
+
compare-and-set, a Map on one event loop). The ladder only raises: an answer
|
|
364
|
+
from a lower tier leaves a higher stored level alone, and an answer that
|
|
365
|
+
finishes after the conversation reached a person returns `{ kind: "person",
|
|
366
|
+
handedOff: false, fromTier: null }` instead of the model's reply. Only the
|
|
367
|
+
call whose raise to `"person"` wins calls `handOff`, once, after the raise.
|
|
368
|
+
A raise that loses re-reads and retries; a port whose level keeps moving
|
|
369
|
+
is refused (`state_conflict`).
|
|
370
|
+
- **Resetting a conversation.** The host resets one by deleting its stored
|
|
371
|
+
level, so `get` returns nothing: the next message starts at automation and
|
|
372
|
+
the first tier again. The ladder has no reset of its own and never lowers a
|
|
373
|
+
level. A conversation stored on a tier id that no longer exists (a tier
|
|
374
|
+
renamed or removed) starts again at the first tier, skipping automation.
|
|
375
|
+
- **Least privilege per tier.** A tier's model sees exactly that tier's tools
|
|
376
|
+
plus `escalate`. A call to another tier's tool is answered as an unknown
|
|
377
|
+
tool and never runs.
|
|
378
|
+
- **Tools from MCP.** `mcpTools({ connect, allow, overrides? })` connects for
|
|
379
|
+
each call's scope and offers ONLY the allow-listed tools; the rest of the
|
|
380
|
+
server's list is never shown, and a call to one never reaches the server.
|
|
381
|
+
An allowed tool the server lacks is refused (`tool_missing`; the
|
|
382
|
+
conversation then goes to a person, see "A tool source that fails"). The client is
|
|
383
|
+
structural (`listTools`, `callTool`, as the official MCP SDK's `Client`), so
|
|
384
|
+
the package depends on no MCP SDK. Tool schemas must be strict; `overrides`
|
|
385
|
+
replaces a description or schema the server ships loose.
|
|
386
|
+
- **What `mcpTools` costs.** Every `handle` call, for every tier that runs,
|
|
387
|
+
calls `connect(scope)` and lists the server's tools (every page). Nothing is
|
|
388
|
+
cached inside the package, on purpose, so one scope's client never serves
|
|
389
|
+
another's. Cache on the host's side, keyed by the scope: have `connect`
|
|
390
|
+
return a client kept per scope (an LRU of connections, with the scope's own
|
|
391
|
+
credentials), and close it when the scope's session ends.
|
|
392
|
+
- **A tool source that fails.** When a source throws (`connect` fails, an
|
|
393
|
+
allowed tool is missing, a server tool clashes with `escalate` or exposes a
|
|
394
|
+
scope field), the conversation goes to a person with reason
|
|
395
|
+
`"tool_error"`, and `usage` still lists the tiers that already ran.
|
|
396
|
+
- **Scope binding.** `scope` is opaque to the ladder. Every tool's `run` gets
|
|
397
|
+
it in its context, and an MCP server gets it through the host's `connect`,
|
|
398
|
+
never through the model. For a server whose tools take the tenant as an
|
|
399
|
+
ARGUMENT, `mcpTools({ …, bindArgs: (scope, toolName) => ({ tenantId:
|
|
400
|
+
scope.tenantId }) })` merges those arguments AFTER the model's input (the
|
|
401
|
+
host's value wins), removes their names from the schema the model sees, and
|
|
402
|
+
refuses, without reaching the server, a model call that sets one. A tool
|
|
403
|
+
whose schema declares a `scopeFields` name is refused (`scope_exposed`), and a model call whose arguments carry one is
|
|
404
|
+
refused without running, so a conversation for one account cannot reach
|
|
405
|
+
another's data even when both use the same tools.
|
|
406
|
+
- **Refused configurations** throw `SupportLadderError` (an
|
|
407
|
+
`InvalidRequestError`) with a `code`: `empty_tiers`, `duplicate_tier` (a tier
|
|
408
|
+
id listed twice), `reserved_tier` (a tier named `"person"`), `tool_conflict`,
|
|
409
|
+
`tool_missing`, `scope_exposed`; and `state_conflict` when the state port's
|
|
410
|
+
level keeps changing while the ladder raises it.
|
|
273
411
|
|
|
274
412
|
## Errors and retries
|
|
275
413
|
|
|
@@ -282,6 +420,7 @@ stops without running the last turn's calls.
|
|
|
282
420
|
| `InvalidResponseError` | an answer the adapter cannot read (tool arguments that are not JSON) |
|
|
283
421
|
| `RefusalError` | thrown only by `ensureNotRefused` |
|
|
284
422
|
| `UnsupportedError` | an unknown provider, an undeclared credential kind, a missing optional SDK |
|
|
423
|
+
| `SupportLadderError` | a support ladder's configuration or state refused; see `code` |
|
|
285
424
|
|
|
286
425
|
All of them extend `LlmError`, which has `kind`, `provider` and `status`. The
|
|
287
426
|
SDKs' own retries are switched off. The host's `retry` hook is the whole
|
package/dist/index.d.ts
CHANGED
|
@@ -460,6 +460,18 @@ declare class InvalidResponseError extends LlmError {
|
|
|
460
460
|
declare class UnsupportedError extends LlmError {
|
|
461
461
|
constructor(provider: string, message: string);
|
|
462
462
|
}
|
|
463
|
+
/** Why a support ladder refused its configuration or a state it was handed. */
|
|
464
|
+
type SupportLadderErrorCode = "empty_tiers" | "duplicate_tier" | "state_conflict" | "reserved_tier" | "tool_conflict" | "tool_missing" | "scope_exposed";
|
|
465
|
+
/**
|
|
466
|
+
* A support ladder refused a configuration (no tier, a tier id used twice, a
|
|
467
|
+
* tier named like the person level, a tool name clash, a tool whose schema
|
|
468
|
+
* exposes a scope-bound field, an allow-listed tool the source does not have),
|
|
469
|
+
* or the host's state port kept moving a level while the ladder raised it.
|
|
470
|
+
*/
|
|
471
|
+
declare class SupportLadderError extends InvalidRequestError {
|
|
472
|
+
readonly code: SupportLadderErrorCode;
|
|
473
|
+
constructor(code: SupportLadderErrorCode, message: string);
|
|
474
|
+
}
|
|
463
475
|
/** `retry-after-ms`, else `retry-after` in seconds or as an HTTP date. */
|
|
464
476
|
declare function retryAfterFrom(headers: unknown, now?: () => number): number | undefined;
|
|
465
477
|
/**
|
|
@@ -522,6 +534,10 @@ declare function createModelClient(options: ModelClientOptions): ModelClient;
|
|
|
522
534
|
* loop. A refusal is a typed RESULT (`status: "refused"`), never an error, so
|
|
523
535
|
* the host can hand the conversation to a person.
|
|
524
536
|
*
|
|
537
|
+
* An executor may HALT the loop (`{ output, halt: true }`): the turn's tool
|
|
538
|
+
* results are appended and the loop ends with `status: "halted"` without
|
|
539
|
+
* another model call. A hand-off tool uses it to leave the conversation.
|
|
540
|
+
*
|
|
525
541
|
* The returned `messages` are always a valid request for the NEXT turn (B2):
|
|
526
542
|
* a turn the loop ends on keeps its text but never a tool call that was not
|
|
527
543
|
* run (no tool_use without its tool_result), and a turn with neither text nor
|
|
@@ -529,14 +545,20 @@ declare function createModelClient(options: ModelClientOptions): ModelClient;
|
|
|
529
545
|
* the provider reject the host's next request with a 400.
|
|
530
546
|
*/
|
|
531
547
|
|
|
532
|
-
/**
|
|
548
|
+
/**
|
|
549
|
+
* What an executor returns: the output text, or the text marked as an error.
|
|
550
|
+
* `halt` ends the loop once this turn's calls have all run.
|
|
551
|
+
*/
|
|
533
552
|
type ToolOutput = string | {
|
|
534
553
|
output: string;
|
|
535
554
|
isError?: boolean;
|
|
555
|
+
halt?: boolean;
|
|
536
556
|
};
|
|
557
|
+
/** `calls` is every call of the same turn, `call` among them, in the model's order. */
|
|
537
558
|
type ToolExecutor = (input: unknown, context: {
|
|
538
559
|
call: ToolCall;
|
|
539
560
|
turn: number;
|
|
561
|
+
calls: readonly ToolCall[];
|
|
540
562
|
}) => Promise<ToolOutput> | ToolOutput;
|
|
541
563
|
interface ToolLoopOptions {
|
|
542
564
|
client: ModelClient;
|
|
@@ -548,7 +570,7 @@ interface ToolLoopOptions {
|
|
|
548
570
|
/** Called once per turn with that turn's usage, turn numbers from 1. */
|
|
549
571
|
onUsage?: (usage: Usage, turn: number, result: ChatResult) => void | Promise<void>;
|
|
550
572
|
}
|
|
551
|
-
type ToolLoopStatus = "completed" | "refused" | "max_turns" | "max_tokens" | "stopped";
|
|
573
|
+
type ToolLoopStatus = "completed" | "refused" | "max_turns" | "max_tokens" | "stopped" | "halted";
|
|
552
574
|
interface ToolLoopResult {
|
|
553
575
|
status: ToolLoopStatus;
|
|
554
576
|
/** The conversation, with every turn and tool result appended. */
|
|
@@ -565,6 +587,212 @@ declare function runToolLoop(options: ToolLoopOptions): Promise<ToolLoopResult>;
|
|
|
565
587
|
/** Throw a `RefusalError` when a turn was refused; return it otherwise. */
|
|
566
588
|
declare function ensureNotRefused(result: ChatResult): ChatResult;
|
|
567
589
|
|
|
590
|
+
/** The level a conversation is at once a person has it. */
|
|
591
|
+
declare const WITH_PERSON = "person";
|
|
592
|
+
type Awaitable$1<T> = T | Promise<T>;
|
|
593
|
+
/** Where the host keeps the level each conversation reached. */
|
|
594
|
+
interface SupportStatePort {
|
|
595
|
+
/** A tier id, `"person"`, or nothing for a conversation that reached no tier. */
|
|
596
|
+
get(conversationId: string): Awaitable$1<string | null | undefined>;
|
|
597
|
+
/**
|
|
598
|
+
* ATOMIC on the host's side: when the stored level is still `from` (`null`:
|
|
599
|
+
* nothing stored), store `to` and return true; otherwise change nothing and
|
|
600
|
+
* return false. One conditional write, e.g. `UPDATE … SET level = $to WHERE
|
|
601
|
+
* id = $id AND level = $from` (an insert that loses on the key when `from`
|
|
602
|
+
* is null) and true when it touched a row. The ladder only ever raises.
|
|
603
|
+
*/
|
|
604
|
+
raise(conversationId: string, from: string | null, to: string): Awaitable$1<boolean>;
|
|
605
|
+
}
|
|
606
|
+
|
|
607
|
+
/** What a tool's `run` is told, all of it from the host, none from the model. */
|
|
608
|
+
interface SupportToolContext<Scope = unknown, Context = unknown> {
|
|
609
|
+
scope: Scope;
|
|
610
|
+
context: Context;
|
|
611
|
+
conversationId: string;
|
|
612
|
+
/** The id of the tier whose model called the tool. */
|
|
613
|
+
tier: string;
|
|
614
|
+
call: ToolCall;
|
|
615
|
+
}
|
|
616
|
+
/** A tool a tier offers its model: a strict definition and its handler. */
|
|
617
|
+
interface SupportTool<Scope = unknown, Context = unknown> {
|
|
618
|
+
definition: ToolDefinition;
|
|
619
|
+
run(input: unknown, context: SupportToolContext<Scope, Context>): ToolOutput | Promise<ToolOutput>;
|
|
620
|
+
}
|
|
621
|
+
/**
|
|
622
|
+
* Tools resolved per `handle()` call for that call's scope, such as an MCP
|
|
623
|
+
* server reached with the scope's own credentials (`mcpTools`).
|
|
624
|
+
*/
|
|
625
|
+
interface SupportToolSource<Scope = unknown, Context = unknown> {
|
|
626
|
+
resolve(scope: Scope): readonly SupportTool<Scope, Context>[] | Promise<readonly SupportTool<Scope, Context>[]>;
|
|
627
|
+
}
|
|
628
|
+
type SupportToolEntry<Scope = unknown, Context = unknown> = SupportTool<Scope, Context> | SupportToolSource<Scope, Context>;
|
|
629
|
+
/** The ladder's own tool. */
|
|
630
|
+
declare const ESCALATE_TOOL = "escalate";
|
|
631
|
+
type EscalationTarget = "next" | "person";
|
|
632
|
+
interface EscalationRequest {
|
|
633
|
+
to: EscalationTarget;
|
|
634
|
+
reason: string;
|
|
635
|
+
}
|
|
636
|
+
|
|
637
|
+
/**
|
|
638
|
+
* The support ladder: automation first, then model tiers, then a person.
|
|
639
|
+
*
|
|
640
|
+
* 1. `automation` answers what the host recognises (a greeting on the first
|
|
641
|
+
* contact, an option the customer picked) with no model call.
|
|
642
|
+
* 2. Anything else goes to the first model tier. Each tier answers, which
|
|
643
|
+
* means "I handle it", or calls the ladder's `escalate` tool: to the next
|
|
644
|
+
* tier, which runs on the same message in the same call, or to a person.
|
|
645
|
+
* A refusal, or a turn with no words, escalates too.
|
|
646
|
+
* 3. A person: the host's `handOff` is called once, and from then on the
|
|
647
|
+
* ladder never calls a model for that conversation.
|
|
648
|
+
*
|
|
649
|
+
* A conversation STAYS at the level it reached (the host's `state` port, only
|
|
650
|
+
* ever raised, atomically: see ./state.ts) until the host resets it;
|
|
651
|
+
* automation is consulted only before a conversation reached any tier. The
|
|
652
|
+
* ladder carries no domain: tiers, tools, copy and the person are all the
|
|
653
|
+
* host's.
|
|
654
|
+
*/
|
|
655
|
+
|
|
656
|
+
type Awaitable<T> = T | Promise<T>;
|
|
657
|
+
interface SupportAutomation<Context = unknown> {
|
|
658
|
+
/** The first contact's message (the transcript is empty), e.g. the options on offer. */
|
|
659
|
+
greeting?(context: Context): Awaitable<string | null | undefined>;
|
|
660
|
+
/** An option the host recognises, answered with no model call. */
|
|
661
|
+
match?(message: string, context: Context): Awaitable<{
|
|
662
|
+
reply: string;
|
|
663
|
+
} | null | undefined>;
|
|
664
|
+
}
|
|
665
|
+
interface SupportTier<Scope = unknown, Context = unknown> {
|
|
666
|
+
/** Unique; the level the state port stores. Not `"person"`. */
|
|
667
|
+
id: string;
|
|
668
|
+
/** A client, or what `createModelClient` takes, so providers stay interchangeable. */
|
|
669
|
+
client: ModelClient | ModelClientOptions;
|
|
670
|
+
instructions: string | readonly SystemBlock[];
|
|
671
|
+
/** EXACTLY this tier's tools; nothing is shared with another tier. */
|
|
672
|
+
tools?: readonly SupportToolEntry<Scope, Context>[];
|
|
673
|
+
/** Default 1024. */
|
|
674
|
+
maxOutputTokens?: number;
|
|
675
|
+
/** Default 8 (the tool loop's). */
|
|
676
|
+
maxTurns?: number;
|
|
677
|
+
effort?: Effort;
|
|
678
|
+
}
|
|
679
|
+
interface SupportHandOff<Scope = unknown, Context = unknown> {
|
|
680
|
+
conversationId: string;
|
|
681
|
+
/** The transcript plus the message that was escalated. */
|
|
682
|
+
conversation: Message[];
|
|
683
|
+
reason: string;
|
|
684
|
+
fromTier: string;
|
|
685
|
+
scope: Scope;
|
|
686
|
+
context: Context;
|
|
687
|
+
}
|
|
688
|
+
interface SupportPerson<Scope = unknown, Context = unknown> {
|
|
689
|
+
/** Called once per conversation, by the call whose raise to "person" won, after that raise. */
|
|
690
|
+
handOff(handOff: SupportHandOff<Scope, Context>): Awaitable<void>;
|
|
691
|
+
}
|
|
692
|
+
interface SupportLadderOptions<Scope = unknown, Context = unknown> {
|
|
693
|
+
automation?: SupportAutomation<Context>;
|
|
694
|
+
/** In escalation order, at least one. */
|
|
695
|
+
tiers: readonly SupportTier<Scope, Context>[];
|
|
696
|
+
person: SupportPerson<Scope, Context>;
|
|
697
|
+
/** Read and atomically RAISED, never lowered (see `SupportStatePort.raise`). */
|
|
698
|
+
state: SupportStatePort;
|
|
699
|
+
/** Argument names the host binds to the scope; the model may never set one. */
|
|
700
|
+
scopeFields?: readonly string[];
|
|
701
|
+
/** Live metering: every model turn's usage, with its tier. */
|
|
702
|
+
onUsage?: (tier: string, usage: Usage, turn: number) => Awaitable<void>;
|
|
703
|
+
}
|
|
704
|
+
interface SupportRequest<Scope = unknown, Context = unknown> {
|
|
705
|
+
conversationId: string;
|
|
706
|
+
message: string;
|
|
707
|
+
/** The conversation before `message`. */
|
|
708
|
+
transcript: readonly Message[];
|
|
709
|
+
context: Context;
|
|
710
|
+
/** Opaque to the ladder; handed to every tool, never to or from the model. */
|
|
711
|
+
scope: Scope;
|
|
712
|
+
}
|
|
713
|
+
interface TierUsage {
|
|
714
|
+
tier: string;
|
|
715
|
+
turns: number;
|
|
716
|
+
usage: Omit<Usage, "raw">;
|
|
717
|
+
}
|
|
718
|
+
interface Escalation {
|
|
719
|
+
from: string;
|
|
720
|
+
to: string;
|
|
721
|
+
reason: string;
|
|
722
|
+
}
|
|
723
|
+
type SupportResult = {
|
|
724
|
+
kind: "automation";
|
|
725
|
+
source: "greeting" | "match";
|
|
726
|
+
reply: string;
|
|
727
|
+
usage: TierUsage[];
|
|
728
|
+
escalations: Escalation[];
|
|
729
|
+
} | {
|
|
730
|
+
kind: "model";
|
|
731
|
+
tier: string;
|
|
732
|
+
reply: string;
|
|
733
|
+
messages: Message[];
|
|
734
|
+
usage: TierUsage[];
|
|
735
|
+
escalations: Escalation[];
|
|
736
|
+
} | {
|
|
737
|
+
kind: "person";
|
|
738
|
+
/** Null when another call (or an earlier message) handed the conversation off. */
|
|
739
|
+
fromTier: string | null;
|
|
740
|
+
reason: string | null;
|
|
741
|
+
/** True when THIS call handed the conversation off. */
|
|
742
|
+
handedOff: boolean;
|
|
743
|
+
usage: TierUsage[];
|
|
744
|
+
escalations: Escalation[];
|
|
745
|
+
};
|
|
746
|
+
interface SupportLadder<Scope = unknown, Context = unknown> {
|
|
747
|
+
handle(request: SupportRequest<Scope, Context>): Promise<SupportResult>;
|
|
748
|
+
}
|
|
749
|
+
declare function createSupportLadder<Scope = unknown, Context = unknown>(options: SupportLadderOptions<Scope, Context>): SupportLadder<Scope, Context>;
|
|
750
|
+
|
|
751
|
+
interface McpToolInfo {
|
|
752
|
+
name: string;
|
|
753
|
+
description?: string;
|
|
754
|
+
inputSchema: JsonSchema;
|
|
755
|
+
}
|
|
756
|
+
interface McpListToolsResult {
|
|
757
|
+
tools: McpToolInfo[];
|
|
758
|
+
nextCursor?: string;
|
|
759
|
+
}
|
|
760
|
+
/** The two calls this source makes; the official SDK's `Client` has both. */
|
|
761
|
+
interface McpClientLike {
|
|
762
|
+
listTools(params?: {
|
|
763
|
+
cursor?: string;
|
|
764
|
+
}): Promise<McpListToolsResult>;
|
|
765
|
+
callTool(params: {
|
|
766
|
+
name: string;
|
|
767
|
+
arguments?: Record<string, unknown>;
|
|
768
|
+
}): Promise<unknown>;
|
|
769
|
+
}
|
|
770
|
+
interface McpToolsOptions<Scope> {
|
|
771
|
+
/**
|
|
772
|
+
* A client for this scope. Put the scope's credentials or headers on its
|
|
773
|
+
* transport here; cache connections per scope if they are costly.
|
|
774
|
+
*/
|
|
775
|
+
connect(scope: Scope): McpClientLike | Promise<McpClientLike>;
|
|
776
|
+
/** The ONLY tools offered, by name. Every one must exist on the server. */
|
|
777
|
+
allow: readonly string[];
|
|
778
|
+
/**
|
|
779
|
+
* Replace an allowed tool's description or input schema, for a server
|
|
780
|
+
* whose schema is not strict (every tool schema must be; see `assertStrictTools`).
|
|
781
|
+
*/
|
|
782
|
+
overrides?: Readonly<Record<string, Partial<Pick<ToolDefinition, "description" | "inputSchema">>>>;
|
|
783
|
+
/**
|
|
784
|
+
* Arguments the HOST supplies, for a server whose tools take the tenant (or
|
|
785
|
+
* any scope field) as an argument. They are merged AFTER the model's input,
|
|
786
|
+
* so the host's value always wins; their names are removed from the schema
|
|
787
|
+
* the model sees, and a model call that sets one is refused without
|
|
788
|
+
* reaching the server.
|
|
789
|
+
*/
|
|
790
|
+
bindArgs?(scope: Scope, toolName: string): Readonly<Record<string, unknown>>;
|
|
791
|
+
}
|
|
792
|
+
/** An MCP `CallToolResult` as tool output: its text parts, else its structured content. */
|
|
793
|
+
declare function mcpResultToOutput(result: unknown): ToolOutput;
|
|
794
|
+
declare function mcpTools<Scope = unknown, Context = unknown>(options: McpToolsOptions<Scope>): SupportToolSource<Scope, Context>;
|
|
795
|
+
|
|
568
796
|
/**
|
|
569
797
|
* The strict-schema rule every tool input schema meets, whatever the provider.
|
|
570
798
|
*
|
|
@@ -583,4 +811,4 @@ declare function toolSchemaProblems(tools: readonly ToolDefinition[]): string[];
|
|
|
583
811
|
/** Throws a TypeError naming every problem in every tool's input schema. */
|
|
584
812
|
declare function assertStrictTools(tools: readonly ToolDefinition[]): void;
|
|
585
813
|
|
|
586
|
-
export { ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_PROVIDER, type AdapterRegistry, type AnthropicAdapterOptions, type AnthropicClientLike, type ApiKeyCredentials, type AssistantMessage, AuthError, type CacheTtl, type Capability, type ChatCall, type ChatRequest, type ChatResult, type CredentialKind, CredentialRevokedError, type CredentialSession, type CredentialSessionOptions, type Credentials, type Effort, GEMINI_PROVIDER, type GeminiAdapterOptions, type GeminiClientLike, InvalidRequestError, InvalidResponseError, type JsonSchema, LlmError, type LlmErrorKind, type Message, type ModelClient, type ModelClientOptions, type OAuthCredentials, type OAuthToken, OPENAI_PROVIDER, type OpenAIAdapterOptions, type OpenAIClientLike, type ProviderAdapter, ProviderUnavailableError, RateLimitError, type RefreshReason, type Refusal, RefusalError, type RegisterOptions, ResolvedCredential, type RetryPolicy, type StopReason, type SystemBlock, type ToolCall, type ToolChoice, type ToolDefinition, type ToolExecutor, type ToolLoopOptions, type ToolLoopResult, type ToolLoopStatus, type ToolOutput, type ToolResult, type ToolResultsMessage, UnsupportedError, type Usage, type UserMessage, XAI_PROVIDER, type XaiAdapterOptions, anthropicAdapter, assertStrictTools, builtInAdapters, createAdapterRegistry, createCredentialSession, createModelClient, ensureNotRefused, geminiAdapter, mapProviderError, openaiAdapter, retryAfterFrom, retryTransient, runToolLoop, strictSchemaProblems, toolSchemaProblems, xaiAdapter };
|
|
814
|
+
export { ANTHROPIC_DEFAULT_MODEL, ANTHROPIC_PROVIDER, type AdapterRegistry, type AnthropicAdapterOptions, type AnthropicClientLike, type ApiKeyCredentials, type AssistantMessage, AuthError, type CacheTtl, type Capability, type ChatCall, type ChatRequest, type ChatResult, type CredentialKind, CredentialRevokedError, type CredentialSession, type CredentialSessionOptions, type Credentials, ESCALATE_TOOL, type Effort, type Escalation, type EscalationRequest, type EscalationTarget, GEMINI_PROVIDER, type GeminiAdapterOptions, type GeminiClientLike, InvalidRequestError, InvalidResponseError, type JsonSchema, LlmError, type LlmErrorKind, type McpClientLike, type McpListToolsResult, type McpToolInfo, type McpToolsOptions, type Message, type ModelClient, type ModelClientOptions, type OAuthCredentials, type OAuthToken, OPENAI_PROVIDER, type OpenAIAdapterOptions, type OpenAIClientLike, type ProviderAdapter, ProviderUnavailableError, RateLimitError, type RefreshReason, type Refusal, RefusalError, type RegisterOptions, ResolvedCredential, type RetryPolicy, type StopReason, type SupportAutomation, type SupportHandOff, type SupportLadder, SupportLadderError, type SupportLadderErrorCode, type SupportLadderOptions, type SupportPerson, type SupportRequest, type SupportResult, type SupportStatePort, type SupportTier, type SupportTool, type SupportToolContext, type SupportToolEntry, type SupportToolSource, type SystemBlock, type TierUsage, type ToolCall, type ToolChoice, type ToolDefinition, type ToolExecutor, type ToolLoopOptions, type ToolLoopResult, type ToolLoopStatus, type ToolOutput, type ToolResult, type ToolResultsMessage, UnsupportedError, type Usage, type UserMessage, WITH_PERSON, XAI_PROVIDER, type XaiAdapterOptions, anthropicAdapter, assertStrictTools, builtInAdapters, createAdapterRegistry, createCredentialSession, createModelClient, createSupportLadder, ensureNotRefused, geminiAdapter, mapProviderError, mcpResultToOutput, mcpTools, openaiAdapter, retryAfterFrom, retryTransient, runToolLoop, strictSchemaProblems, toolSchemaProblems, xaiAdapter };
|