gemi 0.59.0 → 0.61.0

package/dist/ai/AgentController.d.ts

@@ -1,8 +1,277 @@
-import { Agent } from "./Agent";
-import { HttpRequest } from "../http";
-export declare class AgentController<T extends Agent<any> = Agent<any>> {
-    private agent;
-    constructor(agent: T);
-    stream(req: HttpRequest): void;
+import { Controller } from "../http/Controller";
+import { HttpRequest } from "../http/HttpRequest";
+import type { MiddlewareInput } from "../http/middlewareList";
+import type { AgentRun, AgentRunResult, AnyAgent, ToolShapesOf } from "./Agent";
+import { FrameCursorEvictedError, liveRuns as defaultLiveRuns, LiveRunNotFoundError, MemoryLiveRuns } from "./store/LiveRuns";
+import { defaultAgentStore, MemoryAgentStore } from "./store/MemoryAgentStore";
+import type { AgentError, AgentMessage, PendingToolCall, ToolShapes } from "./types";
+/**
+ * Where conversations live.
+ *
+ * Stateless is the default and nothing here is required to hold a conversation:
+ * the client can carry its own history, and a pending approval travels in it
+ * safely because the server signed it. What a store buys is a conversation that
+ * survives the browser — and, with `/attach`, one whose interrupted turn is
+ * still there after a refresh.
+ */
+export interface AgentStore {
+    /**
+     * Where a `threadId` comes from. `ApiRouter.agent()` mounts no route for
+     * this: the app writes one, calls it here, and hands the id to `useChat` —
+     * the mount is the app's because it is where ownership gets recorded, and a
+     * store that holds no user cannot do that for it. An id that did not come out
+     * of here is `null` from `loadThread` and a 404 from the controller, unless
+     * the store's ids are the client's by design (`MemoryAgentStore`'s
+     * `clientOwnedIds`).
+     */
+    createThread(params: {
+        userId?: string | number;
+    }): Promise<{
+        threadId: string;
+    }>;
+    /**
+     * The history, or `null` for a thread the store does not have.
+     *
+     * `null` and `[]` are different answers and the controller acts on the
+     * difference: an empty array is a conversation with nothing in it yet, and a
+     * turn on it runs; `null` is a 404 before anything runs. A store that answers
+     * `[]` for an id it has never seen turns an expired or mistyped thread into a
+     * fresh conversation with no signal, and persists the next turn under the
+     * dead id. Only a store whose ids are minted by the client should do that,
+     * and then on purpose — see `MemoryAgentStore`'s `clientOwnedIds`.
+     */
+    loadThread(threadId: string): Promise<AgentMessage[] | null>;
+    /**
+     * Upsert by message id: replace a message the thread already holds, append
+     * one it does not, and keep the order the thread had. Called with a thread
+     * `loadThread` just found; must not create one.
+     *
+     * The name says append because that is what almost every call is, but a
+     * turn that resolves a pending call reports the earlier assistant message
+     * again — same id, now with the result attached — and a store that only
+     * appends ends up with both versions. A table keyed by message id has the
+     * lookup already but still needs an insert-or-update rather than a plain
+     * insert, which would fail on the key; a store that is a list has to look
+     * before it pushes.
+     */
+    appendMessages(threadId: string, messages: AgentMessage[]): Promise<void>;
 }
+/** The default: conversations last as long as the process. */
+export { defaultAgentStore, MemoryAgentStore };
+/**
+ * The runs currently in flight, and their frames.
+ *
+ * A run outlives the request that started it, so something has to hold it while
+ * no one is listening, and hold what it emitted meanwhile so a returning client
+ * can catch up rather than start over. That is all this is: a per-process map
+ * plus a bounded buffer.
+ *
+ * Per-process is not an implementation shortcut that a better store fixes — a
+ * running generator lives in one process, and a second server cannot attach to
+ * it. Reattachment therefore needs the request to land where the run is: one
+ * server, sticky routing, or a proxy that forwards by `runId`. Worth saying out
+ * loud, because the failure mode behind a round-robin load balancer is a
+ * refresh that usually works.
+ *
+ * This is the read side, which is all `attach` and `stop` need. Registering a
+ * run and replaying its buffer are on `MemoryLiveRuns`, the only implementation
+ * there can be — see the note there for why a second one would not help.
+ */
+export interface LiveRuns {
+    /** What the client asks after a refresh: is anything still going here? */
+    find(params: {
+        threadId: string;
+    }): Promise<{
+        runId: string;
+        seq: number;
+    } | null>;
+    get(runId: string): AgentRun | null;
+    /** Kept for a short while after `run-end`, so a refresh a second late still
+     *  sees the tail instead of an empty screen. */
+    ttlMs: number;
+}
+export { FrameCursorEvictedError, LiveRunNotFoundError, MemoryLiveRuns, defaultLiveRuns as liveRuns, };
+export type AgentHookContext = {
+    req: HttpRequest<any, any>;
+    runId: string;
+    threadId?: string;
+};
+/**
+ * `Controller.kind` is typed as the literal `"controller"`, so a subclass that
+ * declares a `kind` of its own fails the static-side check (TS2417). Widening
+ * it belongs in `http/Controller.ts`, which this slice does not own; erasing
+ * the static side of the base here is the smaller change and costs nothing —
+ * `Controller.kind` has no reader, in this package or out of it.
+ */
+declare const ControllerBase: new () => Controller;
+export declare abstract class AgentController<A extends AnyAgent = AnyAgent> extends ControllerBase {
+    static kind: "agent-controller";
+    /** The agent this controller serves. A property rather than a constructor
+     *  argument so `Router.agent(ChatController)` can take the class, matching how
+     *  every other controller is mounted. */
+    abstract agent: A;
+    /**
+     * Defaults to the process-wide `MemoryAgentStore`.
+     *
+     * Whatever you put here, make it something that outlives the request: this
+     * controller is constructed fresh for every call, so `store = new
+     * MemoryAgentStore()` written here is an empty store on every turn and a
+     * threaded conversation silently reads back nothing. Assign a module-level
+     * instance, or a store whose state is somewhere else entirely.
+     */
+    store: AgentStore;
+    /**
+     * Defaults to the process-wide map. Overridable so a test — or an app running
+     * two agents that must not see each other's runs — can hold its own; not so
+     * that it can be moved off the process, which is not a thing that can be
+     * done. See `MemoryLiveRuns`.
+     */
+    liveRuns: MemoryLiveRuns;
+    /** Appended to the agent's static instructions for this request — the user's
+     *  name, tenant, today's date. */
+    instructions(req: HttpRequest<any, any>): string | Promise<string> | void;
+    /**
+     * `POST /<path>` — one route for every client turn. A first message, an
+     * approval, an answer to a question and a client tool's result are all just
+     * the next turn, so none of them gets an endpoint of its own.
+     */
+    stream(req?: HttpRequest<any, any>): Promise<Response>;
+    /**
+     * A thread holds one run at a time; a new turn on it ends the old one first.
+     *
+     * Since a dropped connection no longer stops a run, a user who sends again
+     * mid-answer used to leave the first run going. It could not see the new
+     * turn, the new run's `loadThread` could not see its answer, and both
+     * appended when they finished — in whichever order the model returned them,
+     * so the thread read `user2, assistant2, user1, assistant1`. `byThread` then
+     * named the second run while the first was still live and unstoppable by
+     * `threadId`.
+     *
+     * Stopping the old run and waiting for its transcript to land is chosen over
+     * refusing the new turn with a 409, because sending again *is* the stop: it
+     * is what `useChat.send` means, and a client that has to poll `/stop` until
+     * the run is really gone before it may post the turn it has already shown is
+     * a worse client for no better thread. The cost is that the new turn waits
+     * for the old run to unwind, which is as long as its slowest tool in flight —
+     * and that wait is the thing that puts `assistant1` before `user2`.
+     *
+     * The wait is on `persistRun`, not on `run.result()`. `result()` settling is
+     * the transcript being final, not stored: `appendMessages` runs after it, and
+     * a `loadThread` in that gap reads a history the old answer is missing from,
+     * which is the original bug by a shorter route. It is also *only* that:
+     * `persistRun` settles once the transcript is stored and lets the app's
+     * hooks run on without it, so a slow `onMessage` is not a slow thread and a
+     * hung one is not a hung thread.
+     *
+     * The lock around it is what makes a *third* turn wait for the second rather
+     * than for the first. Two turns arriving together both see the same live
+     * run, both stop it, both wait for it, and both start — the same race, one
+     * message later. Under the lock the later one finds the earlier one
+     * registered and stops that instead. Per process, like `LiveRuns`, and for
+     * the same reason: the run it guards lives here.
+     */
+    private withThread;
+    /**
+     * `POST /<path>/attach` — subscribe to a run already in progress, from a
+     * cursor. This is a read of a live run, not a continuation of a stopped one:
+     * the work never paused, the listener changed.
+     *
+     * The cursor is `from`, else the client's `cursor`, else `Last-Event-ID`,
+     * else the oldest frame still buffered — and it is honoured only for the run
+     * the client's `runId` names. A cursor the buffer has dropped is a 410 naming
+     * what survives; *no* cursor is the tail, because a page reattaching on mount
+     * has no transcript to leave a hole in. See `resolveCursor`.
+     */
+    attach(req?: HttpRequest<any, any>): Promise<Response>;
+    /**
+     * `POST /<path>/stop` — the explicit cancel. Since a dropped connection no
+     * longer stops a run, this and a later turn on the same thread are the only
+     * things that do, and it is why stopping cannot be a client-side concern:
+     * the tool loop is here, and a client that stops reading has not stopped
+     * step four from charging a card.
+     *
+     * Returns as soon as the run is aborted, not when it has finished unwinding.
+     * The terminal events — the stopped tool results, the aborted message — go
+     * out on the run's own stream, so whoever is watching it sees the ending,
+     * and `onMessage` records it whether anyone is watching or not.
+     *
+     * Answers `{ stopped }` normally, and a `Response` only to reject a request
+     * it could not read — the union is the error, not a second success shape.
+     */
+    stop(req?: HttpRequest<any, any>): Promise<{
+        stopped: boolean;
+    } | Response>;
+    /** `POST /<path>/files` — uploads an attachment and returns its file id. */
+    upload(req?: HttpRequest<any, any>): Promise<{
+        fileId: string;
+    }>;
+    /**
+     * Protected, not private: these exist to be overridden. `onMessage` fires for
+     * every completed message, user and assistant alike, and is the intended
+     * persistence point for an app that is not using `store`.
+     */
+    protected onMessage(message: AgentMessage, ctx: AgentHookContext): void | Promise<void>;
+    protected onToolCall(call: {
+        toolCallId: string;
+        name: string;
+        input: unknown;
+    }, ctx: AgentHookContext): void | Promise<void>;
+    /** Fires before the stream ends `awaiting-input` — where to notify whoever
+     *  has to approve, if they are not the person watching the stream. */
+    protected onAwaitingInput(pending: PendingToolCall[], ctx: AgentHookContext): void | Promise<void>;
+    protected onError(error: AgentError, ctx: AgentHookContext): void | Promise<void>;
+    protected onStreamComplete(result: AgentRunResult<ToolShapesOf<A["tools"]>, any>, ctx: AgentHookContext): void | Promise<void>;
+    /**
+     * WHAT HAPPENS WHEN A HOOK THROWS: it is reported and the run carries on.
+     *
+     * The alternative is to fail the run, and that trade is not close. These
+     * hooks are an app's persistence and notification points; the run is a model
+     * call the user has already been charged for and whose tools may already have
+     * charged a card. Letting a failed `INSERT` in `onMessage` abort a generation
+     * mid-sentence loses the answer as well as the row, and the user cannot
+     * retry into a better outcome. So the answer survives and the failure is
+     * logged.
+     *
+     * It is logged rather than routed to `onError`: `onError` is itself a hook,
+     * and a hook that throws inside the handler for hooks that throw is a loop.
+     * Override this to send it somewhere with a pager attached.
+     */
+    protected reportHookFailure(error: unknown): void;
+    private dispatchEvent;
+    /**
+     * Runs after the stream is over, whether or not anyone was still watching it.
+     *
+     * The messages come from `result()` rather than from the event stream because
+     * assembling a message out of deltas is the agent's job and doing it twice is
+     * how the two copies drift. It also means a stopped run persists the same way
+     * a finished one does: `stop()` finalizes the transcript, so by the time this
+     * resolves there is a valid history to store.
+     *
+     * Settles when the transcript is in the store, not when the app is done with
+     * it. The next turn on this thread waits on this (see `withThread`), and the
+     * hooks are the app's: an `onMessage` that writes to something slow would
+     * make every later turn wait for it, once per message of the old run, and
+     * one that never settles — which `safely` cannot catch — would hold the
+     * thread, and every turn queued on it, behind an open connection each. So
+     * the hooks run on after this on their own, reported the same way.
+     */
+    private persistRun;
+    /** The hooks on a finished run, in order. Never rejects: see `safely`. */
+    private notifyRun;
+    private safely;
+}
+export type AgentRouteMethod = "stream" | "attach" | "stop" | "upload";
+export type AgentMiddlewareConfig = Partial<Record<AgentRouteMethod, MiddlewareInput>>;
+export type AgentRoute<T extends new () => AgentController<any>> = {
+    __internal_brand: "AgentRoute";
+    controller: T;
+    middleware(config: AgentMiddlewareConfig): AgentRoute<T>;
+};
+/** What `CreateRPC` should produce for an agent route: enough for the client to
+ *  type its messages, and nothing that drags server code into the bundle. */
+export type AgentRouteRPC<T extends new () => AgentController<any>> = {
+    __agent: true;
+    tools: InstanceType<T>["agent"] extends AnyAgent ? ToolShapesOf<InstanceType<T>["agent"]["tools"]> : ToolShapes;
+    output: unknown;
+};
 //# sourceMappingURL=AgentController.d.ts.map

package/dist/ai/AgentController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AgentController.d.ts","sourceRoot":"","sources":["../../ai/AgentController.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,KAAK,EAAqB,MAAM,SAAS,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAEtC,qBAAa,eAAe,CAAC,CAAC,SAAS,KAAK,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC;IAChD,OAAO,CAAC,KAAK;gBAAL,KAAK,EAAE,CAAC;IAE5B,MAAM,CAAC,GAAG,EAAE,WAAW;CAGxB"}
+{"version":3,"file":"AgentController.d.ts","sourceRoot":"","sources":["../../ai/AgentController.ts"],"names":[],"mappings":"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"}

package/dist/ai/AgentProvider.d.ts

@@ -0,0 +1,255 @@
+import type { ReasoningEffort } from "./Agent";
+import { type ResponsesEndpoint } from "./providers/call";
+import type { JSONSchema } from "./Schema";
+import type { AgentError, AgentMessage, FinishReason, Usage } from "./types";
+/**
+ * A provider makes one model call. It does not run the tool loop.
+ *
+ * The split matters: approvals, `maxSteps`, deferred tools, skill loading and
+ * persistence are all provider-independent, and putting them in the provider
+ * would mean writing them again for the second provider. So the provider's
+ * whole job is to translate gemi's messages into a request, and the response
+ * stream back into `ProviderEvent`s. Everything above that lives in `Agent`.
+ *
+ * v1 targets OpenAI's Responses API — native reasoning items and strict
+ * structured output without reassembling them by hand. The interface is kept
+ * free of anything Responses-specific so a Chat Completions provider (for older
+ * Azure deployments and OpenAI-compatible gateways) can be added later without
+ * touching Agent, Controller or the client.
+ */
+/** What a provider will actually honour, so `Agent` can drop the rest rather
+ *  than have a request rejected at runtime. */
+export type ProviderCapabilities = {
+    reasoning: boolean;
+    structuredOutput: boolean;
+    fileInput: boolean;
+    parallelToolCalls: boolean;
+    /**
+     * Tool search, and with it deferred loading. Only recent models have it, so a
+     * provider that answers `false` is sent every schema inline and the agent
+     * runs identically — deferral is a token optimization, and an optimization
+     * that changed behaviour when unavailable would not be one.
+     */
+    toolSearch: boolean;
+};
+/** A tool as the model is shown it: schema only, no implementation. */
+export type ProviderToolSpec = {
+    name: string;
+    description: string;
+    parameters: JSONSchema;
+    strict: boolean;
+    /** `defer_loading`: send the name and description, withhold the schema until
+     *  the model searches for it. Ignored when `capabilities.toolSearch` is
+     *  false. */
+    deferred?: boolean;
+};
+/** Tools grouped for search. Flattened back to a list by a provider without
+ *  tool search, since the grouping exists to be searched. */
+export type ProviderToolNamespace = {
+    name: string;
+    description: string;
+    tools: ProviderToolSpec[];
+};
+export interface ProviderStreamParams {
+    messages: AgentMessage[];
+    systemPrompt?: string;
+    tools?: (ProviderToolSpec | ProviderToolNamespace)[];
+    /** Set when the agent declares an `output` schema; the provider turns it into
+     *  whatever its own strict-JSON parameter is. */
+    output?: {
+        name: string;
+        schema: JSONSchema;
+    };
+    /** Optional: silently dropped by a provider whose `capabilities.reasoning`
+     *  is false, since a model that cannot reason should not fail a request. */
+    reasoning?: ReasoningEffort;
+    temperature?: number;
+    maxOutputTokens?: number;
+    signal?: AbortSignal;
+}
+/**
+ * The events of a single model call. Deliberately smaller than
+ * `AgentStreamEvent`: no run, message, tool-result or approval events, because
+ * a provider knows about none of those.
+ */
+export type ProviderEvent = {
+    type: "text-delta";
+    delta: string;
+} | {
+    type: "reasoning-delta";
+    delta: string;
+    id?: string;
+}
+/** Arguments arrive as JSON fragments; the provider passes them through and
+ *  `Agent` assembles and validates against the tool's schema. */
+ | {
+    type: "tool-call-delta";
+    toolCallId: string;
+    name: string;
+    argsDelta: string;
+    namespace?: string;
+}
+/**
+ * `name` IS FLAT AND STAYS FLAT. This was an open question and the API has
+ * answered it: a call to a function that lives inside a namespace comes back
+ * as `{name: "getOrder", namespace: "crm"}`, not as `"crm.getOrder"` —
+ * recorded in `providers/__fixtures__/openai-tool-search.sse` and pinned by
+ * a test that reads that file. So `name` is already the key `Agent`'s tool
+ * registry is built on, which is what makes tool names having to be globally
+ * unique within an agent (see `ToolNamespace`) the right rule rather than an
+ * inconvenience.
+ *
+ * `namespace` is carried beside it, absent for a tool that was listed bare.
+ * It is provenance, not identity: it says which group the model chose to
+ * look in, which is worth recording next to the call and is worthless for
+ * finding the tool. Folding it into `name` would make a name that is
+ * sometimes qualified and sometimes not, and nothing could match on that.
+ */
+ | {
+    type: "tool-call";
+    toolCallId: string;
+    name: string;
+    args: string;
+    namespace?: string;
+}
+/**
+ * The model went looking for a deferred tool and pulled its schema in. Worth
+ * surfacing rather than swallowing: it is a step the user paid for, and the
+ * pause before it is otherwise unexplained.
+ *
+ * TWO FIELDS, not one. `loaded` is the function names — `["listOrders",
+ * "getOrder"]` — and `namespaces` is the groups they came out of —
+ * `["crm"]`. Search results arrive as a tree of namespaces containing
+ * functions, so a single flat list has to pick one level and throw the other
+ * away, and both levels are worth saying: "searched crm, loaded getOrder"
+ * reads better than either half, and the group is the thing the model
+ * actually chose between.
+ *
+ * `namespaces` is required rather than optional because the parser always
+ * knows the answer, and an optional field would let a future provider forget
+ * to fill it in silently. Empty means the search returned bare functions.
+ */
+ | {
+    type: "tool-search";
+    loaded: string[];
+    namespaces: string[];
+} | {
+    type: "output-delta";
+    delta: string;
+} | {
+    type: "finish";
+    reason: FinishReason;
+    usage: Usage;
+} | {
+    type: "error";
+    error: AgentError;
+};
+export type ProviderStream = AsyncIterable<ProviderEvent>;
+export type ProviderConfig = {
+    apiKey?: string;
+    baseURL?: string;
+    timeoutMs?: number;
+    maxRetries?: number;
+    headers?: Record<string, string>;
+};
+export declare abstract class AgentProvider {
+    abstract readonly model: string;
+    abstract readonly capabilities: ProviderCapabilities;
+    /** The model ids this provider knows about — for autocomplete only; any
+     *  string is still accepted, because a new model must not require a gemi
+     *  release to use. */
+    static models(): readonly string[];
+    abstract stream(params: ProviderStreamParams): ProviderStream;
+    /**
+     * Uploads a file and returns the id a `FilePart` carries. Message history
+     * therefore holds provider file ids, which is the trade for getting vision
+     * and PDF input without gemi owning a storage story in v1.
+     */
+    abstract upload(file: File): Promise<string>;
+    /**
+     * Maps a provider's error body onto the normalized codes, so an app can
+     * branch on `rate_limited` without knowing whose rate limit it was.
+     *
+     * Shared rather than abstract-in-practice: Azure answers the same error
+     * envelope as OpenAI, and the one place it differs — the content filter's
+     * code, buried in `innererror` — is handled by reading both.
+     */
+    normalizeError(error: unknown): AgentError;
+}
+export declare class OpenAIProvider extends AgentProvider {
+    readonly model: string;
+    readonly capabilities: ProviderCapabilities;
+    protected readonly config: ProviderConfig;
+    constructor(model: string, config?: ProviderConfig);
+    /** Config defaults come from gemi's config (`ai.openai`), so an app that has
+     *  set `OPENAI_API_KEY` writes only the model name. */
+    static model(model: string, config?: ProviderConfig): OpenAIProvider;
+    static models(): readonly string[];
+    stream(params: ProviderStreamParams): ProviderStream;
+    upload(file: File): Promise<string>;
+    protected baseURL(): string;
+    protected endpoint(): ResponsesEndpoint;
+}
+export type AzureConfig = ProviderConfig & {
+    /**
+     * The resource host, with or without a trailing `/openai`. Both spellings
+     * work — `https://<resource>.cognitiveservices.azure.com` and
+     * `https://<resource>.openai.azure.com` — and neither is rewritten, because
+     * only one of them exists for a resource that was not created as
+     * kind=OpenAI. See `azureBase` for what is done to it.
+     */
+    endpoint?: string;
+    /**
+     * Just the resource name, when there is no endpoint to hand. `<name>` is
+     * expanded to `https://<name>.cognitiveservices.azure.com/openai`.
+     */
+    resourceName?: string;
+    apiVersion?: string;
+    /**
+     * The deployment to call, when it is not named after the model. Azure lets
+     * whoever ran the template call it anything, and plenty of them are called
+     * `prod` — this is the override the class comment promises.
+     */
+    deployment?: string;
+    /**
+     * For Entra ID instead of a key. A function, not a token, because these
+     * expire mid-conversation.
+     */
+    getToken?: () => Promise<string>;
+};
+/**
+ * Its own class rather than a flag on `OpenAIProvider`: Azure names the
+ * deployment rather than the model, pins an api-version, authenticates with an
+ * `api-key` header or an Entra token, and puts the resource in the host. One
+ * class carrying both shapes means every field is conditionally meaningful.
+ *
+ * (It used to put the deployment in the URL as well. It does not: the Responses
+ * API serves no such path — see `azureBase` for the measurements.)
+ *
+ * The API stays symmetrical — `.model()`, not `.deployment()`. Apps name a
+ * model; mapping that onto a deployment is this class's problem, and an app
+ * that named its deployment differently overrides it in config.
+ */
+export declare class AzureOpenAIProvider extends AgentProvider {
+    readonly model: string;
+    readonly capabilities: ProviderCapabilities;
+    protected readonly config: AzureConfig;
+    constructor(model: string, config?: AzureConfig);
+    /** Defaults from gemi's config (`ai.azure`). */
+    static model(model: string, config?: AzureConfig): AzureOpenAIProvider;
+    static models(): readonly string[];
+    stream(params: ProviderStreamParams): ProviderStream;
+    upload(file: File): Promise<string>;
+    protected deployment(): string;
+    /**
+     * The resource base, `<host>/openai`, from whichever of the three ways it was
+     * configured. A bare resource name expands to the `cognitiveservices` host
+     * rather than the `openai.azure.com` one: both answer for a resource created
+     * as kind=OpenAI, only `cognitiveservices` answers for an AI Foundry or
+     * multi-service resource, so it is the spelling that is right more often. An
+     * app on the other one sets `endpoint` and nothing rewrites it.
+     */
+    protected base(): string;
+    protected endpoint(): ResponsesEndpoint;
+}
+//# sourceMappingURL=AgentProvider.d.ts.map

package/dist/ai/AgentProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AgentProvider.d.ts","sourceRoot":"","sources":["../../ai/AgentProvider.ts"],"names":[],"mappings":"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"}