getpatter 0.6.4 → 0.6.5

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.
@@ -6610,6 +6610,14 @@ var StreamHandler = class _StreamHandler {
6610
6610
  chunker.reset();
6611
6611
  getLogger().error(`LLM loop error (${label}):`, e);
6612
6612
  this.metricsAcc.recordTurnInterrupted();
6613
+ const fallback = this.deps.agent.llmErrorMessage;
6614
+ if (fallback && !ttsFirstByteSent.value && this.isSpeaking) {
6615
+ try {
6616
+ await this.synthesizeSentence(fallback, hookExecutor, hookCtx, ttsFirstByteSent);
6617
+ } catch (err) {
6618
+ getLogger().error(`llmErrorMessage fallback synthesis failed (${label}):`, err);
6619
+ }
6620
+ }
6613
6621
  }
6614
6622
  }
6615
6623
  this.metricsAcc.recordLlmComplete();
@@ -9893,12 +9901,14 @@ ${systemPrompt}` : DEFAULT_PHONE_PREAMBLE;
9893
9901
  const hasAfterLlmResponse = Boolean(hookExecutor?.hasAfterLlmResponse() && hookCtx);
9894
9902
  const hasAfterLlmChunk = Boolean(hookExecutor?.hasAfterLlmChunk());
9895
9903
  const allEmittedText = [];
9904
+ const callId = callContext.call_id;
9905
+ const streamOpts = typeof callId === "string" && callId.length > 0 ? { ...opts, callId } : opts;
9896
9906
  for (let iter = 0; iter < maxIterations; iter++) {
9897
9907
  const toolCallsAccumulated = /* @__PURE__ */ new Map();
9898
9908
  const textParts = [];
9899
9909
  let hasToolCalls = false;
9900
9910
  let usageChunkReceived = false;
9901
- for await (const chunk of this.provider.stream(messages, this.openaiTools, opts)) {
9911
+ for await (const chunk of this.provider.stream(messages, this.openaiTools, streamOpts)) {
9902
9912
  if (chunk.type === "text" && chunk.content) {
9903
9913
  const content = hasAfterLlmChunk && hookExecutor ? hookExecutor.runAfterLlmChunk(chunk.content) : chunk.content;
9904
9914
  textParts.push(content);
package/dist/index.d.mts CHANGED
@@ -2254,6 +2254,18 @@ interface LLMChunk {
2254
2254
  */
2255
2255
  interface LLMStreamOptions {
2256
2256
  signal?: AbortSignal;
2257
+ /**
2258
+ * Stable per-call id (the same value the stream handler builds into
2259
+ * ``callCtx.call_id``). Threaded through purely so session-aware providers
2260
+ * — currently {@link OpenAICompatibleLLMProvider} and its Hermes / OpenClaw
2261
+ * presets — can emit the OpenAI ``user`` field as ``patter-call-<callId>``,
2262
+ * giving the upstream agent runtime one durable session per phone call.
2263
+ *
2264
+ * Additive and optional: every existing provider reads only ``signal`` and
2265
+ * is unaffected. When unset (or when a provider has no session-continuity
2266
+ * config) no ``user`` field is sent — fully backward compatible.
2267
+ */
2268
+ callId?: string;
2257
2269
  }
2258
2270
  interface LLMProvider {
2259
2271
  stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
@@ -2947,6 +2959,18 @@ interface AgentOptions {
2947
2959
  */
2948
2960
  readonly language?: string;
2949
2961
  readonly firstMessage?: string;
2962
+ /**
2963
+ * Opt-in spoken fallback for pipeline mode when the per-turn LLM stream
2964
+ * throws (gateway-down / 120 s timeout) BEFORE any assistant text was
2965
+ * spoken. Agent-runtime providers (Hermes / OpenClaw) run tools+memory
2966
+ * internally so a turn can take 30-90 s; on failure the caller currently
2967
+ * hears SILENCE then a silent turn-end. When set to a non-empty string,
2968
+ * the SDK synthesizes and speaks this line through the normal TTS turn
2969
+ * lifecycle (subject to barge-in). ``undefined`` (default) preserves
2970
+ * today's behaviour: nothing is spoken on LLM error. Pipeline mode only.
2971
+ * Mirrors Python ``llm_error_message`` on ``Patter.agent()`` / ``Agent``.
2972
+ */
2973
+ readonly llmErrorMessage?: string;
2950
2974
  /** Tool definitions — ``Tool`` class instances from ``getpatter``. */
2951
2975
  readonly tools?: ReadonlyArray<Tool>;
2952
2976
  /**
@@ -6973,7 +6997,7 @@ interface OpenAILLMOptions {
6973
6997
  * const llm = new openai.LLM({ apiKey: "sk-...", model: "gpt-4o-mini", temperature: 0.4 });
6974
6998
  * ```
6975
6999
  */
6976
- declare class LLM$4 extends OpenAILLMProvider {
7000
+ declare class LLM$7 extends OpenAILLMProvider {
6977
7001
  static readonly providerKey = "openai";
6978
7002
  constructor(opts?: OpenAILLMOptions);
6979
7003
  }
@@ -7084,7 +7108,7 @@ interface AnthropicLLMOptions {
7084
7108
  * const llm = new anthropic.LLM({ promptCaching: false }); // opt out of caching
7085
7109
  * ```
7086
7110
  */
7087
- declare class LLM$3 extends AnthropicLLMProvider {
7111
+ declare class LLM$6 extends AnthropicLLMProvider {
7088
7112
  static readonly providerKey = "anthropic";
7089
7113
  constructor(opts?: AnthropicLLMOptions);
7090
7114
  }
@@ -7192,7 +7216,7 @@ interface GroqLLMOptions {
7192
7216
  * const llm = new groq.LLM({ apiKey: "gsk_...", model: "llama-3.3-70b-versatile" });
7193
7217
  * ```
7194
7218
  */
7195
- declare class LLM$2 extends GroqLLMProvider {
7219
+ declare class LLM$5 extends GroqLLMProvider {
7196
7220
  static readonly providerKey = "groq";
7197
7221
  constructor(opts?: GroqLLMOptions);
7198
7222
  }
@@ -7337,7 +7361,7 @@ interface CerebrasLLMOptions {
7337
7361
  * const llm = new cerebras.LLM({ apiKey: "csk-...", model: "llama3.1-8b" });
7338
7362
  * ```
7339
7363
  */
7340
- declare class LLM$1 extends CerebrasLLMProvider {
7364
+ declare class LLM$4 extends CerebrasLLMProvider {
7341
7365
  static readonly providerKey = "cerebras";
7342
7366
  constructor(opts?: CerebrasLLMOptions);
7343
7367
  }
@@ -7419,11 +7443,365 @@ interface GoogleLLMOptions {
7419
7443
  * const llm = new google.LLM({ apiKey: "AIza...", model: "gemini-2.5-flash" });
7420
7444
  * ```
7421
7445
  */
7422
- declare class LLM extends GoogleLLMProvider {
7446
+ declare class LLM$3 extends GoogleLLMProvider {
7423
7447
  static readonly providerKey = "google";
7424
7448
  constructor(opts?: GoogleLLMOptions);
7425
7449
  }
7426
7450
 
7451
+ /**
7452
+ * Generic OpenAI-compatible LLM provider for Patter's pipeline mode.
7453
+ *
7454
+ * Drives *any* OpenAI-compatible ``/chat/completions`` endpoint — an agent
7455
+ * runtime (Hermes, OpenClaw) or a local inference gateway (Ollama, vLLM,
7456
+ * LM Studio). Patter owns the carrier + STT + turn-taking + TTS; this
7457
+ * provider turns each conversation turn into a single
7458
+ * ``POST {baseUrl}/chat/completions`` request and speaks the response.
7459
+ *
7460
+ * PARITY NOTE (internal divergence, allowed by ``sdk-parity.md``): on the
7461
+ * Python side this provider subclasses ``OpenAILLMProvider`` and merely swaps
7462
+ * the ``AsyncOpenAI`` client (passing ``timeout=`` / ``base_url=``). The TS
7463
+ * base ``OpenAILLMProvider`` is a raw-``fetch`` class with a HARDCODED 30 s
7464
+ * timeout and ``baseUrl`` exposed as a ``protected get`` rather than a
7465
+ * constructor field, so the "swap the client" trick is impossible here.
7466
+ * Instead this is a STANDALONE ``implements LLMProvider`` class (same shape as
7467
+ * {@link GroqLLMProvider} / {@link CerebrasLLMProvider}) that owns its own
7468
+ * configurable timeout and reuses {@link parseOpenAISseStream}. Observably
7469
+ * identical to Python (same 60 s / 120 s ceilings, same ``user`` field, same
7470
+ * headers); only the timeout *mechanism* differs.
7471
+ *
7472
+ * Two additions over the base OpenAI provider:
7473
+ *
7474
+ * - **Long timeout.** Agent runtimes execute tools / memory / skills before
7475
+ * replying, so a turn can take 30-90 s. The default is 60 s here (the
7476
+ * presets raise it to 120 s), REPLACING the base provider's hardcoded 30 s.
7477
+ * - **Session continuity.** Three independent, opt-in signals — each gated on
7478
+ * its own config, none coupled to another:
7479
+ * - ``sessionUserPrefix`` → emits the OpenAI ``user`` field as
7480
+ * ``` `${sessionUserPrefix}${callId}` ```. Used by runtimes that derive
7481
+ * a session from ``user`` (e.g. OpenClaw's gateway).
7482
+ * - ``sessionIdHeader`` (+ optional ``sessionIdPrefix``) → emits a per-call
7483
+ * header carrying ``` `${sessionIdPrefix}${callId}` ``` for per-call
7484
+ * session / transcript continuity on stateless runtimes that key off
7485
+ * headers (e.g. Hermes' ``X-Hermes-Session-Id``).
7486
+ * - ``sessionKeyHeader`` (+ ``sessionKey``) → emits a STATIC header for
7487
+ * long-term memory scoping (e.g. Hermes' ``X-Hermes-Session-Key``); the
7488
+ * value is the raw ``sessionKey``, never interpolated with the call id.
7489
+ * All three are OFF by default — fully backward compatible. ``sessionKey`` is
7490
+ * a credential-grade memory scope and is NEVER logged.
7491
+ *
7492
+ * Keyless gateways (Ollama / vLLM / LM Studio accept no key) are supported:
7493
+ * the ``Authorization`` header is simply omitted from the request (sending a
7494
+ * ``Bearer EMPTY`` placeholder breaks some gateways).
7495
+ */
7496
+
7497
+ /** Constructor options for {@link OpenAICompatibleLLMProvider}. */
7498
+ interface OpenAICompatibleLLMOptions {
7499
+ /**
7500
+ * Bearer token. If omitted and ``apiKeyEnv`` is given, read from that
7501
+ * environment variable. May resolve to undefined for keyless local
7502
+ * gateways — the ``Authorization`` header is then omitted entirely.
7503
+ */
7504
+ apiKey?: string;
7505
+ /**
7506
+ * Environment variable to read the bearer from when ``apiKey`` is not given
7507
+ * (e.g. ``"OPENCLAW_API_KEY"``).
7508
+ */
7509
+ apiKeyEnv?: string;
7510
+ /**
7511
+ * OpenAI-compatible base URL ending in ``/v1`` — the whole point of this
7512
+ * provider, so it is **required**. Operator-controlled config, never derived
7513
+ * from caller / transcript input.
7514
+ */
7515
+ baseUrl: string;
7516
+ /** Model / agent target — **required**. */
7517
+ model: string;
7518
+ /**
7519
+ * Per-request timeout in **seconds**. Default ``60`` (the base OpenAI
7520
+ * provider hardcodes 30 s — raised here because agent runtimes run tools
7521
+ * before replying). Converted to ``AbortSignal.timeout(timeout * 1000)``.
7522
+ */
7523
+ timeout?: number;
7524
+ /**
7525
+ * Extra headers merged into the request *after* the ``User-Agent`` so the
7526
+ * SDK attribution is not silently clobbered (a caller can still override
7527
+ * ``User-Agent`` explicitly).
7528
+ */
7529
+ extraHeaders?: Record<string, string>;
7530
+ /**
7531
+ * When set, emits the OpenAI ``user`` field as
7532
+ * ``` `${sessionUserPrefix}${callId}` ``` for per-call session continuity.
7533
+ * ``undefined`` (default) means no ``user`` field is sent. Independent of the
7534
+ * session headers below.
7535
+ */
7536
+ sessionUserPrefix?: string;
7537
+ /**
7538
+ * Optional header NAME carrying a per-call session id, e.g.
7539
+ * ``"X-Hermes-Session-Id"`` or ``"x-openclaw-session-key"``. When set AND a
7540
+ * ``callId`` is available, the header VALUE is
7541
+ * ``` `${sessionIdPrefix}${callId}` ```. ``undefined`` (default) means off.
7542
+ */
7543
+ sessionIdHeader?: string;
7544
+ /**
7545
+ * Prefix for the session-id header VALUE. Defaults to ``""`` (raw call id).
7546
+ * Only meaningful when ``sessionIdHeader`` is set.
7547
+ */
7548
+ sessionIdPrefix?: string;
7549
+ /**
7550
+ * Optional STATIC header NAME for long-term memory scoping, e.g.
7551
+ * ``"X-Hermes-Session-Key"``. Emitted with the raw ``sessionKey`` value (no
7552
+ * call-id interpolation) only when BOTH ``sessionKeyHeader`` and
7553
+ * ``sessionKey`` are set. ``undefined`` (default) means off.
7554
+ */
7555
+ sessionKeyHeader?: string;
7556
+ /**
7557
+ * Static value emitted in ``sessionKeyHeader``. Credential-grade memory
7558
+ * scope — NEVER logged. ``undefined`` (default) means the header is omitted.
7559
+ */
7560
+ sessionKey?: string;
7561
+ /** Sampling temperature [0, 2]. */
7562
+ temperature?: number;
7563
+ /** Max tokens in the assistant response (sent as ``max_completion_tokens``). */
7564
+ maxTokens?: number;
7565
+ /** OpenAI-style ``response_format`` for JSON mode / structured outputs. */
7566
+ responseFormat?: Record<string, unknown>;
7567
+ /** Whether to allow parallel tool calls. */
7568
+ parallelToolCalls?: boolean;
7569
+ /** ``"auto" | "none" | "required"`` or a specific tool object. */
7570
+ toolChoice?: string | Record<string, unknown>;
7571
+ /** Sampling seed for reproducible outputs. */
7572
+ seed?: number;
7573
+ /** Nucleus sampling cutoff in [0, 1]. */
7574
+ topP?: number;
7575
+ /** Penalty in [-2, 2] applied to repeated tokens. */
7576
+ frequencyPenalty?: number;
7577
+ /** Penalty in [-2, 2] applied to seen tokens. */
7578
+ presencePenalty?: number;
7579
+ /** Stop sequence(s). */
7580
+ stop?: string | string[];
7581
+ }
7582
+ /**
7583
+ * LLM provider for any OpenAI-compatible ``/chat/completions`` endpoint.
7584
+ *
7585
+ * Streams in the same ``{ type: "text" | "tool_call" | "usage" }`` chunk
7586
+ * format as the base OpenAI provider via the shared {@link parseOpenAISseStream}.
7587
+ */
7588
+ declare class OpenAICompatibleLLMProvider implements LLMProvider {
7589
+ /**
7590
+ * Stable pricing/dashboard key — read by stream-handler/metrics. Typed as
7591
+ * ``string`` (not the narrowed literal) so the Hermes / OpenClaw presets can
7592
+ * override it with their own key while still extending this class.
7593
+ */
7594
+ static readonly providerKey: string;
7595
+ /** Resolved bearer; undefined for keyless gateways. */
7596
+ private readonly apiKey?;
7597
+ readonly model: string;
7598
+ private readonly baseUrl;
7599
+ private readonly timeoutMs;
7600
+ private readonly extraHeaders?;
7601
+ private readonly sessionUserPrefix?;
7602
+ private readonly sessionIdHeader?;
7603
+ private readonly sessionIdPrefix?;
7604
+ private readonly sessionKeyHeader?;
7605
+ private readonly sessionKey?;
7606
+ private readonly temperature?;
7607
+ private readonly maxTokens?;
7608
+ private readonly responseFormat?;
7609
+ private readonly parallelToolCalls?;
7610
+ private readonly toolChoice?;
7611
+ private readonly seed?;
7612
+ private readonly topP?;
7613
+ private readonly frequencyPenalty?;
7614
+ private readonly presencePenalty?;
7615
+ private readonly stop?;
7616
+ constructor(options: OpenAICompatibleLLMOptions);
7617
+ /**
7618
+ * Assemble the request headers. ``User-Agent`` is set first so any
7619
+ * ``extraHeaders`` (and the per-call session headers) layer on top without
7620
+ * silently dropping the SDK attribution, and the ``Authorization`` header is
7621
+ * only added when a key is present (keyless gateways omit it).
7622
+ *
7623
+ * The two session headers are emitted INDEPENDENTLY, each gated on its own
7624
+ * config (decoupled from ``sessionUserPrefix`` and from each other):
7625
+ * - ``sessionIdHeader`` (+ ``callId``) → ``` `${sessionIdPrefix}${callId}` ```
7626
+ * - ``sessionKeyHeader`` (+ ``sessionKey``) → the static ``sessionKey`` value.
7627
+ * ``sessionKey`` is a credential-grade memory scope and is never logged.
7628
+ */
7629
+ private buildHeaders;
7630
+ /**
7631
+ * Pre-call DNS / TLS warmup for the configured endpoint. Best-effort:
7632
+ * 5 s timeout, all exceptions swallowed at debug level. The ``Authorization``
7633
+ * header is only sent when a key is present so the operator-grade bearer is
7634
+ * never echoed for keyless gateways (and the key is never logged).
7635
+ */
7636
+ warmup(): Promise<void>;
7637
+ /**
7638
+ * Build the request body. Mirrors the base OpenAI provider's sampling-kwarg
7639
+ * assembly and additionally sets ``user`` for session continuity when
7640
+ * ``sessionUserPrefix`` is set AND a ``callId`` is available — so the default
7641
+ * (prefix unset) behaviour is byte-identical to the base provider.
7642
+ */
7643
+ private buildBody;
7644
+ /** Stream Patter-format LLM chunks from the configured chat completions API. */
7645
+ stream(messages: Array<Record<string, unknown>>, tools?: Array<Record<string, unknown>> | null, opts?: LLMStreamOptions): AsyncGenerator<LLMChunk, void, unknown>;
7646
+ }
7647
+ /**
7648
+ * Public alias of {@link OpenAICompatibleLLMProvider} for the
7649
+ * ``getpatter/llm/openai-compatible`` namespace.
7650
+ *
7651
+ * @example
7652
+ * ```ts
7653
+ * import * as openaiCompatible from "getpatter/llm/openai-compatible";
7654
+ * // Ollama / vLLM / LM Studio (keyless local gateway):
7655
+ * const llm = new openaiCompatible.LLM({
7656
+ * baseUrl: "http://127.0.0.1:11434/v1",
7657
+ * model: "llama3.1",
7658
+ * });
7659
+ * ```
7660
+ */
7661
+ declare class LLM$2 extends OpenAICompatibleLLMProvider {
7662
+ static readonly providerKey = "openai_compatible";
7663
+ }
7664
+
7665
+ /**
7666
+ * Hermes agent-runtime LLM preset for Patter's pipeline mode.
7667
+ *
7668
+ * Thin preset over {@link OpenAICompatibleLLMProvider}: defaults the base URL,
7669
+ * model, env-key name, timeout, and session-continuity prefix for the Hermes
7670
+ * agent runtime so a user just writes ``phone.agent({ llm: new hermes.LLM() })``.
7671
+ *
7672
+ * Hermes runs tools / memory / skills internally before replying, so a single
7673
+ * conversation turn can take 30-90 s — hence the 120 s default timeout. Hermes
7674
+ * is stateless and keys continuity off HEADERS, not the OpenAI ``user`` field:
7675
+ * the preset sends ``X-Hermes-Session-Id: patter-call-<callId>`` on every turn
7676
+ * for per-call session / transcript continuity (on by default), and optionally
7677
+ * ``X-Hermes-Session-Key: <sessionKey>`` for long-term memory scoping when you
7678
+ * pass ``sessionKey``. (It also still emits ``user=patter-call-<callId>`` for
7679
+ * upstream-log correlation, but that is not what drives the session.)
7680
+ */
7681
+
7682
+ /** Constructor options for the Hermes ``LLM`` preset. */
7683
+ interface HermesLLMOptions {
7684
+ /** Bearer token. Falls back to ``API_SERVER_KEY`` env var when omitted. */
7685
+ apiKey?: string;
7686
+ /** Override the Hermes base URL (rarely needed). */
7687
+ baseUrl?: string;
7688
+ /** Model id. Falls back to ``API_SERVER_MODEL_NAME`` env, then ``"hermes-agent"``. */
7689
+ model?: string;
7690
+ /** Per-request timeout in seconds. Default ``120``. */
7691
+ timeout?: number;
7692
+ /**
7693
+ * Long-term memory scope. When set, emits ``X-Hermes-Session-Key`` so Hermes
7694
+ * scopes durable memory to this value across calls. ``undefined`` (default)
7695
+ * means the header is not sent. Credential-grade — never logged.
7696
+ */
7697
+ sessionKey?: string;
7698
+ /** Extra headers merged after the SDK ``User-Agent``. */
7699
+ extraHeaders?: Record<string, string>;
7700
+ /** Sampling temperature [0, 2]. */
7701
+ temperature?: number;
7702
+ /** Max tokens in the assistant response (sent as ``max_completion_tokens``). */
7703
+ maxTokens?: number;
7704
+ /** OpenAI-style ``response_format`` for JSON mode / structured outputs. */
7705
+ responseFormat?: Record<string, unknown>;
7706
+ /** Whether to allow parallel tool calls. */
7707
+ parallelToolCalls?: boolean;
7708
+ /** ``"auto" | "none" | "required"`` or a specific tool object. */
7709
+ toolChoice?: string | Record<string, unknown>;
7710
+ /** Sampling seed for reproducible outputs. */
7711
+ seed?: number;
7712
+ /** Nucleus sampling cutoff in [0, 1]. */
7713
+ topP?: number;
7714
+ /** Penalty in [-2, 2] applied to repeated tokens. */
7715
+ frequencyPenalty?: number;
7716
+ /** Penalty in [-2, 2] applied to seen tokens. */
7717
+ presencePenalty?: number;
7718
+ /** Stop sequence(s). */
7719
+ stop?: string | string[];
7720
+ }
7721
+ /**
7722
+ * Hermes agent-runtime LLM provider (OpenAI-compatible, streaming).
7723
+ *
7724
+ * @example
7725
+ * ```ts
7726
+ * import * as hermes from "getpatter/llm/hermes";
7727
+ * const llm = new hermes.LLM(); // env-defaulted, keyless OK
7728
+ * const llm = new hermes.LLM({ apiKey: "...", model: "hermes-7b" });
7729
+ * ```
7730
+ */
7731
+ declare class LLM$1 extends OpenAICompatibleLLMProvider {
7732
+ static readonly providerKey = "hermes";
7733
+ constructor(opts?: HermesLLMOptions);
7734
+ }
7735
+
7736
+ /**
7737
+ * OpenClaw agent-runtime LLM preset for Patter's pipeline mode.
7738
+ *
7739
+ * Thin preset over {@link OpenAICompatibleLLMProvider}, aligned with the
7740
+ * shipped ``openclawConsult`` builder in ``src/consult.ts``: same loopback
7741
+ * base URL (``:18789/v1``), same ``OPENCLAW_API_KEY`` env var, same
7742
+ * ``model="openclaw/<agent>"`` pass-through convention, same agent-id charset
7743
+ * rule, and the same ``x-openclaw-session-key`` session header. Takes an
7744
+ * ``agent`` id (not a raw model string), exactly like ``openclawConsult``.
7745
+ *
7746
+ * OpenClaw runs tools / memory / skills internally before replying, so a turn
7747
+ * can take 30-90 s — hence the 120 s default timeout (unlike the consult
7748
+ * preset's phone-safe 30 s filler default; here the runtime IS the per-turn
7749
+ * brain, not an on-demand escalation). It keys sessions off BOTH the OpenAI
7750
+ * ``user`` field and the ``x-openclaw-session-key`` header, so the preset
7751
+ * enables both for one runtime session per phone call.
7752
+ */
7753
+
7754
+ /** Constructor options for the OpenClaw ``LLM`` preset. */
7755
+ interface OpenClawLLMOptions {
7756
+ /**
7757
+ * OpenClaw agent id (e.g. ``"receptionist"``). Mapped to
7758
+ * ``model="openclaw/<agent>"``; an already-namespaced id (``"openclaw/x"``,
7759
+ * ``"agent:x"``) is passed through unchanged. **Required.**
7760
+ */
7761
+ agent: string;
7762
+ /** Override the OpenClaw base URL (rarely needed). */
7763
+ baseUrl?: string;
7764
+ /** Bearer token. Falls back to ``OPENCLAW_API_KEY`` env var when omitted. */
7765
+ apiKey?: string;
7766
+ /** Per-request timeout in seconds. Default ``120``. */
7767
+ timeout?: number;
7768
+ /** Extra headers merged after the SDK ``User-Agent``. */
7769
+ extraHeaders?: Record<string, string>;
7770
+ /** Sampling temperature [0, 2]. */
7771
+ temperature?: number;
7772
+ /** Max tokens in the assistant response (sent as ``max_completion_tokens``). */
7773
+ maxTokens?: number;
7774
+ /** OpenAI-style ``response_format`` for JSON mode / structured outputs. */
7775
+ responseFormat?: Record<string, unknown>;
7776
+ /** Whether to allow parallel tool calls. */
7777
+ parallelToolCalls?: boolean;
7778
+ /** ``"auto" | "none" | "required"`` or a specific tool object. */
7779
+ toolChoice?: string | Record<string, unknown>;
7780
+ /** Sampling seed for reproducible outputs. */
7781
+ seed?: number;
7782
+ /** Nucleus sampling cutoff in [0, 1]. */
7783
+ topP?: number;
7784
+ /** Penalty in [-2, 2] applied to repeated tokens. */
7785
+ frequencyPenalty?: number;
7786
+ /** Penalty in [-2, 2] applied to seen tokens. */
7787
+ presencePenalty?: number;
7788
+ /** Stop sequence(s). */
7789
+ stop?: string | string[];
7790
+ }
7791
+ /**
7792
+ * OpenClaw agent-runtime LLM provider (OpenAI-compatible, streaming).
7793
+ *
7794
+ * @example
7795
+ * ```ts
7796
+ * import * as openclaw from "getpatter/llm/openclaw";
7797
+ * const llm = new openclaw.LLM({ agent: "receptionist" }); // reads OPENCLAW_API_KEY
7798
+ * ```
7799
+ */
7800
+ declare class LLM extends OpenAICompatibleLLMProvider {
7801
+ static readonly providerKey = "openclaw";
7802
+ constructor(opts: OpenClawLLMOptions);
7803
+ }
7804
+
7427
7805
  /**
7428
7806
  * Silero VAD provider.
7429
7807
  *
@@ -8829,4 +9207,4 @@ interface CallEvent {
8829
9207
  readonly direction?: string;
8830
9208
  }
8831
9209
 
8832
- export { type AgentOptions, type AgentState, AllProvidersFailedError, type AnthropicConversion, LLM$3 as AnthropicLLM, type AnthropicLLMOptions, type AnthropicMessage, AssemblyAIEncoding, AssemblyAIModel, STT$1 as AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, type EvaluateContext as BargeInEvaluateContext, type BargeInStrategy, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type CallControl, type CallEvent, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOutcome, type CallRecord, type CallResult, type CarrierKind, type CartesiaEncoding, STT$3 as CartesiaSTT, type CartesiaSTTOptions, TTS$3 as CartesiaTTS, CartesiaTTSModel, type CartesiaTTSOptions, CartesiaTTSVoiceMode, LLM$1 as CerebrasLLM, type CerebrasLLMOptions, ChatContext, type ChatMessage, type ChatRole, CloudflareTunnel, type ConsultConfig, type ConversationStateSnapshot, type CostBreakdown, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, DeepFilterNetFilter, type DeepFilterNetOptions, DeepgramModel, STT$6 as DeepgramSTT, type DeepgramSTTOptions, DefaultToolExecutor, type DefaultToolExecutorOptions, type DefineToolInput, type DtmfEvent, ConvAI as ElevenLabsConvAI, ElevenLabsConvAIAdapter, type ConvAIOptions as ElevenLabsConvAIOptions, ElevenLabsModel, ElevenLabsOutputFormat, ElevenLabsTTS as ElevenLabsRestTTS, TTS$6 as ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketOptions, TTS$5 as ElevenLabsWebSocketTTS, type EouTrigger, ErrorCode, EventBus, FallbackLLMProvider, type FallbackLLMProviderOptions, type FilePcmSource, GEMINI_DEFAULT_INPUT_SR, GEMINI_DEFAULT_OUTPUT_SR, GeminiLiveAdapter, type GeminiLiveEventHandler, LLM as GoogleLLM, type GoogleLLMOptions, LLM$2 as GroqLLM, type GroqLLMOptions, Guardrail$1 as Guardrail, type GuardrailOptions, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type InitTracingOptions, TTS as InworldTTS, type InworldTTSOptions, type JobCallback, KrispFrameDuration, KrispSampleRate, KrispVivaFilter, type KrispVivaFilterOptions, type LLMChunk, LLMLoop, type LLMProvider, LMNTAudioFormat, LMNTModel, LMNTSampleRate, TTS$1 as LMNTTTS, type LMNTTTSOptions, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type LoopCallback, type MessageHandler, MetricsStore, MinWordsStrategy, type MinWordsStrategyOptions, type ModelPricing, Ngrok, type OpenAICompatibleConsult, LLM$4 as OpenAILLM, type OpenAILLMOptions, OpenAILLMProvider, type OpenAIMessage, Realtime as OpenAIRealtime, Realtime2 as OpenAIRealtime2, OpenAIRealtime2Adapter, type Realtime2Options as OpenAIRealtime2Options, OpenAIRealtimeAdapter, OpenAIRealtimeAudioFormat, OpenAIRealtimeModel, type RealtimeOptions as OpenAIRealtimeOptions, OpenAIRealtimeVADType, TTS$4 as OpenAITTS, type OpenAITTSOptions, STT$4 as OpenAITranscribeSTT, type OpenAITranscribeSTTOptions, OpenAITranscriptionModel, OpenAIVoice, PRICING_LAST_UPDATED, PRICING_VERSION, type ParamSpec, PartialStreamError, Patter, PatterConfigError, PatterConnectionError, PatterError, type PatterEventType, PatterTool, type PatterToolExecuteArgs, type PatterToolOptions, type PatterToolResult, PcmCarry, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, Carrier as Plivo, PlivoAdapter, type PlivoCarrierOptions, type InitiateCallOptions as PlivoInitiateCallOptions, type InitiateCallResult as PlivoInitiateCallResult, PricingUnit, type PricingUnitValue, type ProviderPricing, ProvisionError, RateLimitError, type RawPcmSource, type RealtimeConfig, type RealtimeTurnDetection, RemoteMessageHandler, RimeAudioFormat, RimeModel, TTS$2 as RimeTTS, type RimeTTSOptions, SPAN_BARGEIN, SPAN_CALL, SPAN_ENDPOINT, SPAN_LLM, SPAN_STT, SPAN_TOOL, SPAN_TTS, type SSEEvent, type STTConfig, type ScheduleHandle, SentenceChunker, type ServeOptions, type SilenceCallback, type SileroSampleRate, SileroVAD, type SileroVADOptions, STT$2 as SonioxSTT, type SonioxSTTOptions$1 as SonioxSTTOptions, type Span, type SpeechEventCallback, SpeechEvents, SpeechmaticsAudioEncoding, SpeechmaticsOperatingPoint, STT as SpeechmaticsSTT, type SpeechmaticsSTTOptions, SpeechmaticsSampleRate, SpeechmaticsServerMessage, TurnDetectionMode as SpeechmaticsTurnDetectionMode, StatefulResampler, type StatefulResamplerOptions, Static as StaticTunnel, type TTSConfig, Carrier$1 as Telnyx, TelnyxAdapter, type TelnyxCarrierOptions, type ConfigureNumberOptions as TelnyxConfigureNumberOptions, type EndCallOptions as TelnyxEndCallOptions, type InitiateCallOptions$1 as TelnyxInitiateCallOptions, type InitiateCallResult$1 as TelnyxInitiateCallResult, type ProvisionNumberOptions as TelnyxProvisionNumberOptions, type ProvisionNumberResult as TelnyxProvisionNumberResult, TelnyxSTT, TelnyxSTTInputFormat, TelnyxSTTSampleRate, type Transcript as TelnyxSTTTranscript, TelnyxTTS, TelnyxTTSSampleRate, TelnyxTTSVoice, type TelnyxTranscriptionEngine, TestSession, TfidfLoopDetector, type TfidfLoopDetectorOptions, Tool, type ToolDefinition, type ToolExecutor, type ToolHandler, type ToolOptions, type TunnelHandle, type TurnMetrics, Carrier$2 as Twilio, TwilioAdapter, type TwilioAdapterOptions, type TwilioCarrierOptions, type ConfigureNumberOptions$1 as TwilioConfigureNumberOptions, type InitiateCallOptions$2 as TwilioInitiateCallOptions, type InitiateCallResult$2 as TwilioInitiateCallResult, type ProvisionNumberOptions$1 as TwilioProvisionNumberOptions, type ProvisionNumberResult$1 as TwilioProvisionNumberResult, ULTRAVOX_DEFAULT_API_BASE, ULTRAVOX_DEFAULT_SR, type UltravoxEventHandler, UltravoxRealtimeAdapter, type UserState, STT$5 as WhisperSTT, type WhisperSTTOptions, assemblyai, builtinClipPath, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, cartesia, createResampler16kTo8k, createResampler24kTo16k, createResampler24kTo8k, createResampler8kTo16k, deepgram, defineTool, elevenlabs, evaluateStrategies as evaluateBargeInStrategies, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, geminiLive, getLogger, guardrail, initTracing, isRemoteUrl, isTracingEnabled, isWebSocketUrl, lmnt, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiTts, openclawConsult, openclawPostCallNotifier, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, resetStrategies as resetBargeInStrategies, rime, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, soniox, speechmatics, startSpan, startTunnel, tool, ultravox, whisper };
9210
+ export { type AgentOptions, type AgentState, AllProvidersFailedError, type AnthropicConversion, LLM$6 as AnthropicLLM, type AnthropicLLMOptions, type AnthropicMessage, AssemblyAIEncoding, AssemblyAIModel, STT$1 as AssemblyAISTT, type AssemblyAISTTOptions, type AudioConfig, type AudioSource, AuthenticationError, type BackgroundAudioOptions, BackgroundAudioPlayer, type EvaluateContext as BargeInEvaluateContext, type BargeInStrategy, BuiltinAudioClip, type BuiltinAudioClipName, type BuiltinPcmSource, type CallControl, type CallEvent, type CallEventHandler, type CallMetrics, CallMetricsAccumulator, type CallOutcome, type CallRecord, type CallResult, type CarrierKind, type CartesiaEncoding, STT$3 as CartesiaSTT, type CartesiaSTTOptions, TTS$3 as CartesiaTTS, CartesiaTTSModel, type CartesiaTTSOptions, CartesiaTTSVoiceMode, LLM$4 as CerebrasLLM, type CerebrasLLMOptions, ChatContext, type ChatMessage, type ChatRole, CloudflareTunnel, type ConsultConfig, type ConversationStateSnapshot, type CostBreakdown, DEFAULT_MIN_SENTENCE_LEN, DEFAULT_PRICING, DTMF_EVENTS, DeepFilterNetFilter, type DeepFilterNetOptions, DeepgramModel, STT$6 as DeepgramSTT, type DeepgramSTTOptions, DefaultToolExecutor, type DefaultToolExecutorOptions, type DefineToolInput, type DtmfEvent, ConvAI as ElevenLabsConvAI, ElevenLabsConvAIAdapter, type ConvAIOptions as ElevenLabsConvAIOptions, ElevenLabsModel, ElevenLabsOutputFormat, ElevenLabsTTS as ElevenLabsRestTTS, TTS$6 as ElevenLabsTTS, type ElevenLabsTTSOptions, type ElevenLabsWebSocketOptions, TTS$5 as ElevenLabsWebSocketTTS, type EouTrigger, ErrorCode, EventBus, FallbackLLMProvider, type FallbackLLMProviderOptions, type FilePcmSource, GEMINI_DEFAULT_INPUT_SR, GEMINI_DEFAULT_OUTPUT_SR, GeminiLiveAdapter, type GeminiLiveEventHandler, LLM$3 as GoogleLLM, type GoogleLLMOptions, LLM$5 as GroqLLM, type GroqLLMOptions, Guardrail$1 as Guardrail, type GuardrailOptions, LLM$1 as HermesLLM, type HermesLLMOptions, type HookContext, IVRActivity, type IVRActivityOptions, type IVRToolDefinition, type IncomingMessage, type InitTracingOptions, TTS as InworldTTS, type InworldTTSOptions, type JobCallback, KrispFrameDuration, KrispSampleRate, KrispVivaFilter, type KrispVivaFilterOptions, type LLMChunk, LLMLoop, type LLMProvider, LMNTAudioFormat, LMNTModel, LMNTSampleRate, TTS$1 as LMNTTTS, type LMNTTTSOptions, type LatencyBreakdown, type LocalCallOptions, type LocalConfig, type LocalOptions, type Logger, type LoopCallback, type MessageHandler, MetricsStore, MinWordsStrategy, type MinWordsStrategyOptions, type ModelPricing, Ngrok, type OpenAICompatibleConsult, LLM$2 as OpenAICompatibleLLM, type OpenAICompatibleLLMOptions, OpenAICompatibleLLMProvider, LLM$7 as OpenAILLM, type OpenAILLMOptions, OpenAILLMProvider, type OpenAIMessage, Realtime as OpenAIRealtime, Realtime2 as OpenAIRealtime2, OpenAIRealtime2Adapter, type Realtime2Options as OpenAIRealtime2Options, OpenAIRealtimeAdapter, OpenAIRealtimeAudioFormat, OpenAIRealtimeModel, type RealtimeOptions as OpenAIRealtimeOptions, OpenAIRealtimeVADType, TTS$4 as OpenAITTS, type OpenAITTSOptions, STT$4 as OpenAITranscribeSTT, type OpenAITranscribeSTTOptions, OpenAITranscriptionModel, OpenAIVoice, LLM as OpenClawLLM, type OpenClawLLMOptions, PRICING_LAST_UPDATED, PRICING_VERSION, type ParamSpec, PartialStreamError, Patter, PatterConfigError, PatterConnectionError, PatterError, type PatterEventType, PatterTool, type PatterToolExecuteArgs, type PatterToolOptions, type PatterToolResult, PcmCarry, PipelineHookExecutor, type PipelineHooks, type PipelineMessageHandler, Carrier as Plivo, PlivoAdapter, type PlivoCarrierOptions, type InitiateCallOptions as PlivoInitiateCallOptions, type InitiateCallResult as PlivoInitiateCallResult, PricingUnit, type PricingUnitValue, type ProviderPricing, ProvisionError, RateLimitError, type RawPcmSource, type RealtimeConfig, type RealtimeTurnDetection, RemoteMessageHandler, RimeAudioFormat, RimeModel, TTS$2 as RimeTTS, type RimeTTSOptions, SPAN_BARGEIN, SPAN_CALL, SPAN_ENDPOINT, SPAN_LLM, SPAN_STT, SPAN_TOOL, SPAN_TTS, type SSEEvent, type STTConfig, type ScheduleHandle, SentenceChunker, type ServeOptions, type SilenceCallback, type SileroSampleRate, SileroVAD, type SileroVADOptions, STT$2 as SonioxSTT, type SonioxSTTOptions$1 as SonioxSTTOptions, type Span, type SpeechEventCallback, SpeechEvents, SpeechmaticsAudioEncoding, SpeechmaticsOperatingPoint, STT as SpeechmaticsSTT, type SpeechmaticsSTTOptions, SpeechmaticsSampleRate, SpeechmaticsServerMessage, TurnDetectionMode as SpeechmaticsTurnDetectionMode, StatefulResampler, type StatefulResamplerOptions, Static as StaticTunnel, type TTSConfig, Carrier$1 as Telnyx, TelnyxAdapter, type TelnyxCarrierOptions, type ConfigureNumberOptions as TelnyxConfigureNumberOptions, type EndCallOptions as TelnyxEndCallOptions, type InitiateCallOptions$1 as TelnyxInitiateCallOptions, type InitiateCallResult$1 as TelnyxInitiateCallResult, type ProvisionNumberOptions as TelnyxProvisionNumberOptions, type ProvisionNumberResult as TelnyxProvisionNumberResult, TelnyxSTT, TelnyxSTTInputFormat, TelnyxSTTSampleRate, type Transcript as TelnyxSTTTranscript, TelnyxTTS, TelnyxTTSSampleRate, TelnyxTTSVoice, type TelnyxTranscriptionEngine, TestSession, TfidfLoopDetector, type TfidfLoopDetectorOptions, Tool, type ToolDefinition, type ToolExecutor, type ToolHandler, type ToolOptions, type TunnelHandle, type TurnMetrics, Carrier$2 as Twilio, TwilioAdapter, type TwilioAdapterOptions, type TwilioCarrierOptions, type ConfigureNumberOptions$1 as TwilioConfigureNumberOptions, type InitiateCallOptions$2 as TwilioInitiateCallOptions, type InitiateCallResult$2 as TwilioInitiateCallResult, type ProvisionNumberOptions$1 as TwilioProvisionNumberOptions, type ProvisionNumberResult$1 as TwilioProvisionNumberResult, ULTRAVOX_DEFAULT_API_BASE, ULTRAVOX_DEFAULT_SR, type UltravoxEventHandler, UltravoxRealtimeAdapter, type UserState, STT$5 as WhisperSTT, type WhisperSTTOptions, assemblyai, builtinClipPath, calculateRealtimeCost, calculateSttCost, calculateTelephonyCost, calculateTtsCost, callsToCsv, callsToJson, cartesia, createResampler16kTo8k, createResampler24kTo16k, createResampler24kTo8k, createResampler8kTo16k, deepgram, defineTool, elevenlabs, evaluateStrategies as evaluateBargeInStrategies, filterEmoji, filterForTTS, filterMarkdown, formatDtmf, geminiLive, getLogger, guardrail, initTracing, isRemoteUrl, isTracingEnabled, isWebSocketUrl, lmnt, makeAuthMiddleware, mergePricing, mixPcm, mountApi, mountDashboard, mulawToPcm16, notifyDashboard, openaiTts, openclawConsult, openclawPostCallNotifier, pcm16ToMulaw, resample16kTo8k, resample24kTo16k, resample8kTo16k, resamplePcm, resetStrategies as resetBargeInStrategies, rime, scheduleCron, scheduleInterval, scheduleOnce, selectSoundFromList, setLogger, soniox, speechmatics, startSpan, startTunnel, tool, ultravox, whisper };