@guuey/agent-client 0.4.0 → 0.6.0

package/dist/transport.d.ts

@@ -0,0 +1,90 @@
+/**
+ * The web SSE invoke transport, and the guest-identity wire pieces it shares
+ * with the read-plane adapters.
+ *
+ * Its own module (rather than living in `./web-adapters.ts`) for the same
+ * reason `AgentResponseError` lives in `./errors.ts`, one level down: the
+ * web-adapter bundle takes VALUE imports of `@guuey/mcp-apps-host` (the
+ * ui-resource reader / action-relay assemblies), so a consumer that only
+ * wants the transport — a custom chat surface with its own card layer, or
+ * none — would drag the whole host-role graph into its build, and any
+ * version skew between the two packages becomes that consumer's build
+ * failure (guuey#186 G2). This module's import closure is
+ * `types`/`errors`/`saturation-retry` only; `./web-adapters.ts` imports
+ * from HERE, never the reverse, and `@guuey/agent-client/transport`
+ * publishes exactly this graph.
+ */
+import type { InvokeRequest, InvokeTransport } from "./types.js";
+import { type ColdStartRetryOptions, type SaturationRetryOptions } from "./saturation-retry.js";
+/**
+ * Header carrying a caller-owned anonymous guest secret. A LOCAL MIRROR of the
+ * two server-side constants — the pod's `GUEST_HEADER_NAME`
+ * (`backend/services/nocode-runtime/src/identity.ts`) and the read plane's
+ * `GUEST_HEADER` (`backend/amplify/functions/publicApi/identity.ts`) — because
+ * this is a published npm package and cannot take a `@guuey-private` dep (same
+ * arrangement as `@guuey/host`'s mirrored fs-contract constants). The string is
+ * a wire contract: both planes already advertise it in
+ * `Access-Control-Allow-Headers`, so changing it is a breaking protocol change,
+ * not a rename.
+ */
+export declare const GUEST_HEADER = "x-guuey-guest";
+/**
+ * Narrow a caller-supplied guest secret to a value that is safe to put on the
+ * wire, or `null`. The single gate for the header: every write of
+ * {@link GUEST_HEADER} in this package goes through it, so a malformed secret
+ * can never reach a request. The value is never logged (here or anywhere on
+ * this path) — it IS the anonymous identity, so a leak is an impersonation.
+ */
+export declare function sendableGuestSecret(secret: string | null | undefined): string | null;
+/** Options for {@link fetchStreamTransport}. */
+export interface FetchStreamTransportOptions extends SaturationRetryOptions {
+    /**
+     * Bounded retry on cold-start 503s — the envelope-less refusal an embed
+     * eats for ~30–60s after the agent redeploys (guuey#186 Gap 3). ON by
+     * default (small budget: 3 attempts, 2s/4s/8s) for parity with guuey's
+     * first-party embeds; pass `false` to disable, or options to re-budget.
+     * See {@link withColdStartRetry} for exactly what matches (and what
+     * deliberately stays with the saturation policy instead).
+     */
+    coldStartRetry?: ColdStartRetryOptions | false;
+    /**
+     * Injectable bearer provider (guuey#186 Gap 4) — identity is a transport
+     * concern (see {@link InvokeTransport}: "owns headers + identity
+     * entirely"), and a harness or non-React host holds credentials in its own
+     * lifecycle, not in a closure minted once at page load. Resolved PER
+     * ATTEMPT, before each request — a retry after a backoff wait re-reads it,
+     * so a token that expired during the wait is refreshed rather than
+     * replayed. When present it takes precedence over the positional
+     * `accessToken`; resolving `null` falls through to the guest secret /
+     * cookie chain exactly as a null `accessToken` does (and carries the same
+     * silent-anonymous-downgrade hazard the `createWebAdapters` docs warn
+     * about). A throw propagates and fails the invoke — deliberately not
+     * caught, for the same reason as `getGuestSecret` there.
+     */
+    getBearer?: () => string | null | Promise<string | null>;
+}
+/**
+ * The web SSE transport: {@link streamInvokeOnce} under the shared
+ * {@link withSaturationRetry} wrapper, itself under {@link withColdStartRetry}.
+ * Every consumer of this transport (Studio, the widget, anything built on
+ * `createWebAdapters`) therefore inherits the single `POD_SATURATED` retry AND
+ * the bounded cold-start 503 retry, the same pair Portal's React-Native
+ * transport wears — see the wrappers' docblocks for which refusals retry,
+ * which deliberately do not, and why both retries are invisible to the hook.
+ * Both wrappers guard on "nothing yielded yet": once a chunk has streamed,
+ * NOTHING re-POSTs.
+ */
+export declare function fetchStreamTransport(req: InvokeRequest, accessToken?: string | null, guestSecret?: string | null, options?: FetchStreamTransportOptions): AsyncIterable<string>;
+/**
+ * Wrap a transport so every yielded chunk ALSO pings `onChunk` — the
+ * byte-level liveness signal `useAgentInvoke`'s stall watchdog runs on
+ * (guuey#192). Purely observational: chunks pass through unchanged, errors
+ * and completion propagate untouched, and the wrapper adds no timers of its
+ * own — the OBSERVER owns the clock, this module only reports activity. The
+ * first ping doubles as the "first byte seen" arming signal, which is why
+ * the watchdog never fires during a silent cold start: no bytes, no ping,
+ * no armed timer (that phase belongs to {@link withColdStartRetry} and the
+ * user's own abort).
+ */
+export declare function withActivityObserver(transport: InvokeTransport, onChunk: () => void): InvokeTransport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAEjE,OAAO,EAIL,KAAK,qBAAqB,EAC1B,KAAK,sBAAsB,EAC5B,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,kBAAkB,CAAC;AAgB5C;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAEpF;AAoHD,gDAAgD;AAChD,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IACzE;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,qBAAqB,GAAG,KAAK,CAAC;IAC/C;;;;;;;;;;;;;OAaG;IACH,SAAS,CAAC,EAAE,MAAM,MAAM,GAAG,IAAI,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,GAAG,EAAE,aAAa,EAClB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,EAC3B,OAAO,GAAE,2BAAgC,GACxC,aAAa,CAAC,MAAM,CAAC,CAcvB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,eAAe,EAC1B,OAAO,EAAE,MAAM,IAAI,GAClB,eAAe,CAOjB"}

package/dist/transport.js

@@ -0,0 +1,189 @@
+import { AgentResponseError } from "./errors.js";
+import { parseRetryAfterSeconds, withColdStartRetry, withSaturationRetry, } from "./saturation-retry.js";
+/**
+ * Header carrying a caller-owned anonymous guest secret. A LOCAL MIRROR of the
+ * two server-side constants — the pod's `GUEST_HEADER_NAME`
+ * (`backend/services/nocode-runtime/src/identity.ts`) and the read plane's
+ * `GUEST_HEADER` (`backend/amplify/functions/publicApi/identity.ts`) — because
+ * this is a published npm package and cannot take a `@guuey-private` dep (same
+ * arrangement as `@guuey/host`'s mirrored fs-contract constants). The string is
+ * a wire contract: both planes already advertise it in
+ * `Access-Control-Allow-Headers`, so changing it is a breaking protocol change,
+ * not a rename.
+ */
+export const GUEST_HEADER = "x-guuey-guest";
+/**
+ * A well-formed guest secret: exactly 32 bytes as 64 LOWERCASE hex chars —
+ * the shape `crypto.getRandomValues` + hex-encoding mints.
+ *
+ * Deliberately stricter than the server's `/^[a-f0-9]{64}$/i` (pod
+ * `identity.ts`, publicApi `identity.ts`): both sides lowercase before
+ * hashing, so an uppercase secret would in fact be accepted, but the only
+ * supported mint path emits lowercase and a non-canonical value means the
+ * caller's storage is not what this adapter expects. Anything that fails is
+ * IGNORED — the request falls through to cookie mode rather than sending a
+ * secret the two identity planes might key differently.
+ */
+const GUEST_SECRET_RE = /^[0-9a-f]{64}$/;
+/**
+ * Narrow a caller-supplied guest secret to a value that is safe to put on the
+ * wire, or `null`. The single gate for the header: every write of
+ * {@link GUEST_HEADER} in this package goes through it, so a malformed secret
+ * can never reach a request. The value is never logged (here or anywhere on
+ * this path) — it IS the anonymous identity, so a leak is an impersonation.
+ */
+export function sendableGuestSecret(secret) {
+    return typeof secret === "string" && GUEST_SECRET_RE.test(secret) ? secret : null;
+}
+/**
+ * Is this request a cross-origin call from a browser document? Only then can
+ * a fetch `TypeError` be a CORS refusal worth hinting about. `location` is
+ * read via `typeof` so Node and React Native (where CORS does not exist)
+ * answer false; an unparseable URL answers false rather than throwing from
+ * inside error handling.
+ */
+function isCrossOriginBrowserCall(url) {
+    if (typeof location === "undefined")
+        return false;
+    try {
+        return new URL(url).origin !== location.origin;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * One invoke attempt: opens the request and yields decoded SSE chunks.
+ * {@link fetchStreamTransport} wraps this with the shared saturation retry —
+ * every behaviour below is per-attempt.
+ *
+ * Exactly ONE identity carrier per request, in order:
+ *
+ *  1. `accessToken` → `Authorization: Bearer` — the pod identifies the caller
+ *     by their verified access token (the same identity the history read
+ *     plane uses, so persisted threads round-trip on reload).
+ *  2. a well-formed `guestSecret` → `x-guuey-guest` — the caller owns and
+ *     persists its own anonymous secret. The path for hosts with no usable
+ *     cookie jar: React-Native, and the embedded widget, whose third-party
+ *     iframe cannot rely on the pod's cookie surviving browser partitioning.
+ *     The pod never mints a cookie for a header client.
+ *  3. neither → `credentials: "include"`, which round-trips the HttpOnly
+ *     `guuey_guest` cookie the pod mints for anonymous browser callers.
+ *
+ * Never two at once: a bearer wins over a guest secret, and a request that
+ * carries either header does NOT also send cookie credentials.
+ *
+ * Reads the body via `ReadableStream.getReader()` (browser).
+ */
+async function* streamInvokeOnce(req, accessToken, guestSecret) {
+    const headers = {
+        "Content-Type": "application/json",
+        Accept: "text/event-stream",
+    };
+    const init = {
+        method: "POST",
+        signal: req.signal,
+        headers,
+        body: JSON.stringify(req.body),
+    };
+    const guest = sendableGuestSecret(guestSecret);
+    if (accessToken) {
+        headers.Authorization = `Bearer ${accessToken}`;
+    }
+    else if (guest) {
+        headers[GUEST_HEADER] = guest;
+    }
+    else {
+        init.credentials = "include";
+    }
+    let resp;
+    try {
+        resp = await fetch(req.url, init);
+    }
+    catch (err) {
+        // A network-level TypeError on a CROSS-ORIGIN invoke from a browser is,
+        // in practice, very often a missing allowedDomains entry — the CORS
+        // preflight failed and the web platform deliberately reports nothing
+        // more specific (guuey#186 Gap 2: the console.ggui.ai embed lost real
+        // time to an unexplained "Failed to fetch"). The error stays a
+        // TypeError with the original as `cause`; the added sentence is a HINT,
+        // not a diagnosis — offline, DNS and CSP failures throw the same shape.
+        // Same-origin calls and non-browser runtimes (no `location`) cannot be
+        // CORS refusals, so they pass through untouched.
+        if (err instanceof TypeError && isCrossOriginBrowserCall(req.url)) {
+            throw new TypeError(`${err.message} — if this is a browser embed, check the app's allowedDomains (the CORS allowlist must include this page's origin)`, { cause: err });
+        }
+        throw err;
+    }
+    if (!resp.ok || !resp.body) {
+        // Surface a structured pod error ({ code, message }) when present — e.g. a
+        // QUOTA_EXCEEDED 429 carries an upgrade message the UI should show. Fall
+        // back to the bare status for non-JSON failures.
+        const body = await resp.json().catch(() => null);
+        let message = `agent responded ${resp.status}`;
+        let code;
+        if (body !== null && typeof body === "object") {
+            if ("message" in body && typeof body.message === "string" && body.message) {
+                message = body.message;
+            }
+            if ("code" in body && typeof body.code === "string") {
+                code = body.code;
+            }
+        }
+        throw new AgentResponseError(message, resp.status, code, parseRetryAfterSeconds(resp.headers.get("Retry-After")));
+    }
+    const reader = resp.body.getReader();
+    const decoder = new TextDecoder();
+    for (;;) {
+        const { value, done } = await reader.read();
+        if (done)
+            break;
+        yield decoder.decode(value, { stream: true });
+    }
+}
+/**
+ * The web SSE transport: {@link streamInvokeOnce} under the shared
+ * {@link withSaturationRetry} wrapper, itself under {@link withColdStartRetry}.
+ * Every consumer of this transport (Studio, the widget, anything built on
+ * `createWebAdapters`) therefore inherits the single `POD_SATURATED` retry AND
+ * the bounded cold-start 503 retry, the same pair Portal's React-Native
+ * transport wears — see the wrappers' docblocks for which refusals retry,
+ * which deliberately do not, and why both retries are invisible to the hook.
+ * Both wrappers guard on "nothing yielded yet": once a chunk has streamed,
+ * NOTHING re-POSTs.
+ */
+export function fetchStreamTransport(req, accessToken, guestSecret, options = {}) {
+    const { getBearer } = options;
+    const once = async function* (attempt) {
+        // Per-attempt resolution: each retry re-asks the provider (fresh token
+        // after a backoff wait) instead of replaying a captured one.
+        const bearer = getBearer ? await getBearer() : accessToken;
+        yield* streamInvokeOnce(attempt, bearer, guestSecret);
+    };
+    const saturated = withSaturationRetry(once, { sleep: options.sleep });
+    if (options.coldStartRetry === false)
+        return saturated(req);
+    return withColdStartRetry(saturated, {
+        sleep: options.sleep,
+        ...options.coldStartRetry,
+    })(req);
+}
+/**
+ * Wrap a transport so every yielded chunk ALSO pings `onChunk` — the
+ * byte-level liveness signal `useAgentInvoke`'s stall watchdog runs on
+ * (guuey#192). Purely observational: chunks pass through unchanged, errors
+ * and completion propagate untouched, and the wrapper adds no timers of its
+ * own — the OBSERVER owns the clock, this module only reports activity. The
+ * first ping doubles as the "first byte seen" arming signal, which is why
+ * the watchdog never fires during a silent cold start: no bytes, no ping,
+ * no armed timer (that phase belongs to {@link withColdStartRetry} and the
+ * user's own abort).
+ */
+export function withActivityObserver(transport, onChunk) {
+    return async function* observed(req) {
+        for await (const chunk of transport(req)) {
+            onChunk();
+            yield chunk;
+        }
+    };
+}

package/dist/types.d.ts

@@ -17,6 +17,13 @@ import type { AgReduceResult, JsonValue } from "@silverprotocol/core";
 export interface AgentMessage {
     role: "user" | "assistant";
     text: string;
+    /**
+     * The invoke body's `clientMessageId`, present on user turns this client
+     * sent live (the optimistic push tags it). History-rehydrated entries and
+     * assistant turns omit it. The transcript renderer's R0 send-lifecycle
+     * join key (`UseAgentInvokeReturn.sendStates`).
+     */
+    clientMessageId?: string;
 }
 /**
  * A cross-app profile consent request surfaced mid-stream by the pod's
@@ -117,6 +124,22 @@ export interface AgentInvokeAdapters {
     /** Optional: rehydrate the transcript for a hydrated threadId. See {@link AgentInvokeHistoryAdapter}. */
     history?: AgentInvokeHistoryAdapter;
 }
+/** Tuning for the guuey#192 stall watchdog — see {@link UseAgentInvokeOptions.stallRecovery}. */
+export interface StallRecoveryOptions {
+    /**
+     * Byte-inactivity window (ms) before a history probe fires. Armed only
+     * AFTER the first byte of the turn — pre-first-byte silence is a legitimate
+     * cold start and never triggers. Every received chunk resets it.
+     * Default 25000.
+     */
+    windowMs?: number;
+    /**
+     * Fruitless probes (history shows the turn still in flight, or no probe is
+     * possible) before the turn fails with `CLIENT_ERROR_CODES.STREAM_STALLED`.
+     * Any received byte resets the count. Default 4.
+     */
+    probeAttempts?: number;
+}
 export interface UseAgentInvokeOptions {
     /** Pod base URL (with or without a trailing `/agent/invoke`). Chat is disabled when null. */
     endpointUrl: string | null;
@@ -131,6 +154,29 @@ export interface UseAgentInvokeOptions {
      * reducer is never constructed and the text behaviour is byte-identical.
      */
     preserveBlocks?: boolean;
+    /**
+     * Stall recovery for a half-dead stream (guuey#192). A connection that dies
+     * WITHOUT erroring (TCP alive, zero bytes, no `done`) would otherwise leave
+     * the turn suspended forever — a frozen cursor while the backend may have
+     * completed and persisted the reply. On by default; `false` restores the
+     * old hang-forever behaviour; an object tunes the window/attempts. Armed
+     * only after the first byte; probes are non-destructive (they read history
+     * WITHOUT touching the live stream) and adopt the finished reply from the
+     * history adapter when it is already persisted — see the watchdog notes in
+     * `useAgentInvoke`.
+     */
+    stallRecovery?: false | StallRecoveryOptions;
+    /**
+     * Optional external abort authority (guuey#186 Gap 4): a host lifecycle —
+     * route change, dialog close, screen unmount — that must be able to stop
+     * an in-flight turn without holding the hook's own `abort()`. Composed
+     * with (never replacing) the hook's internal per-turn controller: when
+     * this signal aborts, the current turn aborts exactly as `abort()` would;
+     * the hook's `abort()`/`reset()` keep working regardless. Already-aborted
+     * at send time means the send is refused before any request is made. The
+     * signal may span many turns — each send observes its CURRENT state.
+     */
+    signal?: AbortSignal;
 }
 /**
  * The per-turn lifecycle (guuey#91), derived ENTIRELY from frames the pod
@@ -185,7 +231,9 @@ export interface UseAgentInvokeReturn {
      *
      * It is a `string`, not the `AgentErrorCode` union: the pod may ship a new
      * code before a consumer upgrades this SDK, and a narrowed type would make
-     * that unrepresentable rather than merely unhandled.
+     * that unrepresentable rather than merely unhandled. ONE code is
+     * client-originated rather than a pod wire code: `STREAM_STALLED` (see
+     * `CLIENT_ERROR_CODES`), set when the guuey#192 stall watchdog gives up.
      */
     errorCode: string | null;
     threadId: string | null;
@@ -246,5 +294,29 @@ export interface UseAgentInvokeReturn {
     profileLinkRequest: ProfileLinkRequest | null;
     /** Dismiss the pending {@link profileLinkRequest} (back to `null`). */
     clearProfileLinkRequest: () => void;
+    /**
+     * The LAST turn ended by user abort (`abort()` or the external signal) —
+     * the transcript renderer's R1 aborted-partial + "Stopped." signal.
+     * Distinct from the #192 watchdog's internal stream abort, which never
+     * sets it. Cleared by the next `send()` and by `reset()`.
+     */
+    aborted: boolean;
+    /**
+     * The LAST turn was ADOPTED from persisted history by the guuey#192 stall
+     * watchdog (the reply was already durably written; the dead stream was
+     * discarded). Presentation contract: calm surfaces render an adopted turn
+     * identically to a streamed one; debug surfaces may mark it. Cleared by
+     * the next `send()` and by `reset()`.
+     */
+    adopted: boolean;
+    /**
+     * The optimistic-send lifecycle, keyed by each live user turn's
+     * `clientMessageId` (see {@link AgentMessage.clientMessageId}):
+     * `"sending"` until the pod's `session` frame admits the turn, `"failed"`
+     * when the turn errored BEFORE admission (the message never reached the
+     * agent — the R0 failed-to-send state with its retry affordance). Entries
+     * for admitted turns are removed (absent = sent). `reset()` clears it.
+     */
+    sendStates: Readonly<Record<string, "sending" | "failed">>;
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/useAgentInvoke.d.ts

@@ -16,5 +16,33 @@ export type HistoryApplication = {
  * mid-flight send always beats late-arriving history.
  */
 export declare function applyHistoryResult(result: HistoryLoadResult, currentMessages: AgentMessage[]): HistoryApplication;
+/** The guuey#192 stall watchdog's resolved tuning (see {@link stallProbeDecision}). */
+export declare const STALL_RECOVERY_DEFAULTS: {
+    readonly windowMs: 25000;
+    readonly probeAttempts: 4;
+};
+/**
+ * Pure decision seam for the guuey#192 stall probe: does a freshly-loaded
+ * transcript already contain THIS turn's finished reply?
+ *
+ * `adopt` requires BOTH signals, because each alone lies in a real case:
+ *
+ *  - **user-count**: history must hold at least as many user turns as the
+ *    local transcript (which includes the just-sent optimistic one). Without
+ *    it, a thread whose PREVIOUS turn ended in a completed assistant reply
+ *    would adopt that OLD transcript and silently drop the in-flight turn.
+ *  - **finished tail**: history's last message must be a non-empty assistant
+ *    reply. Without it, a history read that caught the persisted user row
+ *    before the assistant row would adopt a reply-less transcript.
+ *
+ * KNOWN LIMIT (documented, accepted): the runtime persists a turn's rows at
+ * completion — the guuey#192 evidence (a reload mid-stall renders the FULL
+ * reply) is only possible under that model, and the read plane carries no
+ * per-row clientMessageId to match against. If persistence ever becomes
+ * progressive (partial assistant rows), this heuristic needs the read plane
+ * to grow a turn-completion marker — do not "fix" it client-side by text
+ * comparison, which cannot distinguish a partial row from a finished one.
+ */
+export declare function stallProbeDecision(history: AgentMessage[], localUserCount: number): "adopt" | "in-flight";
 export declare function useAgentInvoke(opts: UseAgentInvokeOptions): UseAgentInvokeReturn;
 //# sourceMappingURL=useAgentInvoke.d.ts.map

package/dist/useAgentInvoke.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AAkCA,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAGjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAwVhF"}
+{"version":3,"file":"useAgentInvoke.d.ts","sourceRoot":"","sources":["../src/useAgentInvoke.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,EAGV,YAAY,EAEZ,iBAAiB,EAIjB,qBAAqB,EACrB,oBAAoB,EACrB,MAAM,YAAY,CAAC;AAMpB,yEAAyE;AACzE,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,YAAY,EAAE,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC;AAEtB;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,iBAAiB,EACzB,eAAe,EAAE,YAAY,EAAE,GAC9B,kBAAkB,CAIpB;AAED,uFAAuF;AACvF,eAAO,MAAM,uBAAuB;;;CAAkD,CAAC;AAYvF;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,kBAAkB,CAChC,OAAO,EAAE,YAAY,EAAE,EACvB,cAAc,EAAE,MAAM,GACrB,OAAO,GAAG,WAAW,CAOvB;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,qBAAqB,GAAG,oBAAoB,CAmehF"}