gemi 0.59.0 → 0.61.0

package/dist/ai/useChat.d.ts

@@ -1,12 +1,258 @@
-type Agent = {};
-interface UseChatParams {
-    agent: Agent;
+import type { RPC } from "../client/rpc";
+import type { AgentError, AgentMessage, ClientTurn, PendingToolCall, ToolShapes } from "./types";
+/**
+ * The agent routes, picked out of the same `RPC` interface `useQuery` and
+ * `useMutation` read. An agent is not a second kind of thing to register — it is
+ * a route, so its key is its path and its types arrive the way every other
+ * route's types do.
+ */
+type AgentRoutes = {
+    [K in keyof RPC as RPC[K] extends {
+        __agent: true;
+    } ? K : never]: RPC[K];
+};
+type ToolsOf<P extends keyof AgentRoutes> = AgentRoutes[P] extends {
+    tools: infer T;
+} ? T extends ToolShapes ? T : ToolShapes : ToolShapes;
+type OutputOf<P extends keyof AgentRoutes> = AgentRoutes[P] extends {
+    output: infer O;
+} ? O : unknown;
+/**
+ * What the UI is waiting on.
+ *
+ * `awaiting-input` is its own state rather than a flavour of idle: the run is
+ * over, but the conversation is holding a question, and a UI that cannot tell
+ * the difference will either look hung or look finished.
+ */
+export type ChatStatus = "idle" | "submitted" | "streaming" | "awaiting-input" | "error";
+export interface UseChatParams<P extends keyof AgentRoutes> {
+    /** Continues a server-side thread. Omitted, the hook keeps history itself and
+     *  sends it with each request — the stateless default.
+     *
+     *  The id is the store's, not the client's: an app route calls
+     *  `store.createThread` and hands the result to this hook, and an id the
+     *  store never minted — or has since expired — is a `thread_not_found` error
+     *  on the first turn. Only a store built with client-owned ids
+     *  (`new MemoryAgentStore({ clientOwnedIds: true })`) takes one the client
+     *  made up. */
+    threadId?: string;
+    /** Server-rendered or restored history. */
+    initialMessages?: AgentMessage<ToolsOf<P>, OutputOf<P>>[];
+    /**
+     * Where the client that produced `initialMessages` left off, so `/attach` can
+     * be asked for the tail rather than the whole run.
+     *
+     * Without it the hook has to say "I have seen nothing", and a run kept alive
+     * past `run-end` — which `LiveRuns` does on purpose, so a refresh a second
+     * late still sees the ending — replays from the top onto a transcript that
+     * already has it. Take it from `cursor` on the previous mount and persist it
+     * beside the messages; the two belong together, and restoring one without the
+     * other is what produces a doubled answer.
+     *
+     * `runId` is half of it rather than decoration: frames number from zero in
+     * every run, so a bare number cannot say whether it describes the run that is
+     * live now. Given both, the server resumes when they match and replays from
+     * the start when they do not.
+     */
+    cursor?: {
+        runId: string;
+        seq: number;
+    };
+    /**
+     * On mount, ask whether a run is still going on this thread and pick it back
+     * up from where this client left off. Needs a `threadId` — that is the handle
+     * that survives a refresh, which is why the client is never asked to stash a
+     * `runId` of its own. Defaults to true.
+     */
+    attach?: boolean;
+    /** Merged into the request body, for anything the agent's controller reads
+     *  off the request that is not a message. */
+    body?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    onFinish?: (message: AgentMessage<ToolsOf<P>, OutputOf<P>>) => void;
+    onError?: (error: AgentError) => void;
+    onAwaitingInput?: (pending: PendingToolCall<ToolsOf<P>>[]) => void;
+    /**
+     * The mount probe found no run to attach to.
+     *
+     * On one server this means what it says, and there is nothing to do. On more
+     * than one it is ambiguous in a way neither end can resolve: a run lives in
+     * the process that started it, `find` only ever searches that process, and a
+     * refresh routed to a different instance gets the same answer as a thread
+     * with nothing running. The server cannot tell the two apart, so it does not
+     * pretend to.
+     *
+     * What an app can do is re-read the thread — the run is still going wherever
+     * it is, and its messages land in the store when it finishes, so refetching
+     * shows the answer that the stream would have shown arriving. Without this
+     * the client simply sits on its own history, and the reply appears only when
+     * something else happens to reload it.
+     *
+     * The better fix is upstream: route a session to one instance (on Azure App
+     * Service that is ARR affinity, which is on by default) so the refresh lands
+     * where its run is. This is the fallback for when it does not — a scale-in,
+     * a new device, a cleared cookie.
+     */
+    onAttachMiss?: (params: {
+        threadId: string;
+    }) => void;
 }
-interface MessagePayload {
+export interface UseChatResult<P extends keyof AgentRoutes> {
+    /**
+     * The transcript, tools and all.
+     *
+     * A `tool-call` part narrows on `name`, and with it `input`, `output` and
+     * `progress` — the tool's own yields, in order, typed by what its `execute`
+     * yields rather than as `unknown`. `nested` on that same part holds the
+     * sub-agent runs the tool drove, each an ordinary `AgentMessage[]` with a
+     * name and a label, so a component walks into it and renders it with whatever
+     * it already renders `messages` with:
+     *
+     *   {part.type === "tool-call" && part.nested?.map((run) => (
+     *     <Transcript key={run.runId} title={run.label ?? run.agent} messages={run.messages} />
+     *   ))}
+     *
+     * Those inner messages are typed with the default `ToolShapes`, not this
+     * route's: a sub-agent's tools are its own, and typing its transcript with
+     * the parent's tool names would be a lie the compiler tells.
+     */
+    messages: AgentMessage<ToolsOf<P>, OutputOf<P>>[];
+    status: ChatStatus;
+    /** Cleared by the next successful send, so a retry does not have to clear it. */
+    error: AgentError | null;
+    /** Set once the server has assigned one. */
+    threadId?: string;
+    /** The run being streamed or attached to, if any. */
+    runId?: string;
+    /**
+     * How far this client has got, to hand back as `cursor` on the next mount.
+     *
+     * Persist it with `messages`: a restored transcript whose cursor was not
+     * restored asks `/attach` for a run it already has, and additive deltas
+     * arriving a second time are how an answer ends up printed twice. `runId` is
+     * undefined until a run has named itself, and the pair is meaningless until
+     * then — there is nothing to resume.
+     */
+    cursor: {
+        runId?: string;
+        seq: number;
+    };
+    /**
+     * The one way to advance the conversation. A string is shorthand for
+     * `{ text }`; answers to pending calls go in the same turn, and may travel
+     * with text.
+     */
+    sendMessage(turn: ClientTurn | string): Promise<void>;
+    /**
+     * Explicit cancel — a closed tab no longer stops a run, so this is what does.
+     *
+     * The UI stops immediately; the server call is what actually ends the
+     * generation and any tool mid-flight. `messages` keeps the interrupted turn
+     * with everything it had produced, marked `aborted`, so the transcript shows
+     * where it was cut rather than losing text the user already read.
+     */
+    stop(): Promise<void>;
+    /** Drops the last assistant turn and re-runs from the user turn before it. */
+    regenerate(): Promise<void>;
+    setMessages(messages: AgentMessage<ToolsOf<P>, OutputOf<P>>[]): void;
+    /**
+     * Non-empty exactly when `status === "awaiting-input"`.
+     *
+     * A call a *sub*-agent made arrives here too, with `path` naming the chain of
+     * tool calls it is nested under. Nothing else about it is different, and that
+     * is the point: it is answered by `approve`/`answer` like any other, and
+     * `path` is there only so a UI can say which agent is asking.
+     */
+    pending: PendingToolCall<ToolsOf<P>>[];
+    /**
+     * The deferred tools the model has pulled in during the run in flight.
+     *
+     * Somewhere for a UI to put "…looking for the right tool" instead of an
+     * unexplained pause. Run-scoped and not part of the transcript: it says what
+     * is happening now, and is empty again on the next `run-start`, so it is not
+     * something to persist beside `messages`.
+     */
+    loadedTools: string[];
+    /**
+     * Sugar over `sendMessage`. The hook carries each pending call's signature —
+     * and its `path`, if the question came from a sub-agent — and hands both back
+     * untouched, so an app answers with a boolean and never sees the mechanism
+     * that makes answering trustworthy. Answering a nested question is the same
+     * call as answering a top-level one.
+     */
+    approve(toolCallId: string, approve: boolean, reason?: string): Promise<void>;
+    /** The same, for a `question` or `client` tool: the value is checked against
+     *  the tool's output schema server-side before the model sees it. */
+    answer(toolCallId: string, output: unknown): Promise<void>;
+    /** Uploads through the agent's own upload route and returns the id to put in
+     *  `sendMessage({ files })`. Here rather than in app code because the route is
+     *  derived from the same path. */
+    attach(file: File): Promise<{
+        fileId: string;
+        name: string;
+        mimeType: string;
+    }>;
 }
-export declare function useChat(params: UseChatParams): {
-    messages: any[];
-    sendMessage: (payload: MessagePayload) => Promise<void>;
+/**
+ * What `POST /api<path>` receives.
+ *
+ * One route for every client turn, so the body has to say which mode it is in:
+ * with a `threadId` the server owns the history, without one the client carries
+ * it and sends the transcript *before* this turn — the turn itself is never in
+ * `messages`, or the server would see it twice.
+ */
+export type AgentRequestBody = {
+    turn: ClientTurn;
+    threadId?: string;
+    messages?: AgentMessage[];
+    /**
+     * A handle on this run, minted before the run has one.
+     *
+     * `stop` needs something to name, and the server's own `runId` does not reach
+     * the client until `run-start` — a gap covering the network round trip and
+     * the provider's time to first token, which is precisely the window a user
+     * cancels in. A thread id would do it where there is one, but the stateless
+     * first turn has neither. So the client names the run it is starting, and the
+     * server is expected to remember the mapping for as long as the run lives.
+     */
+    clientRunId: string;
+} & Record<string, unknown>;
+/**
+ * What `POST /api<path>/attach` receives: which thread, and how far this client
+ * already got.
+ *
+ * `runId` says which run the cursor counts within. Absent, or naming a run that
+ * is not the live one, the cursor cannot be honoured and the run has to be
+ * replayed from the start.
+ */
+export type AgentAttachBody = {
+    threadId: string;
+    cursor: number;
+    runId?: string;
+};
+/**
+ * What `POST /api<path>/stop` receives.
+ *
+ * Every field is optional because the client stops runs it cannot always name:
+ * before `run-start` there is no `runId`, and a stateless first turn has no
+ * `threadId` either. Whichever handle is present is enough — resolve by
+ * `runId`, else by `clientRunId`, else the live run on `threadId`.
+ */
+export type AgentStopBody = {
+    runId?: string;
+    threadId?: string;
+    clientRunId?: string;
 };
+/**
+ * The path is the agent's route, exactly as mounted:
+ *
+ *   const { messages, sendMessage } = useChat("/chat")
+ *
+ * and a tool part inside `messages` narrows on `name`, giving `input` and
+ * `output` their real types — which is the whole reason the tool tuple is
+ * carried through `Agent`, `AgentRoute` and `RPC` instead of being erased at the
+ * first boundary.
+ */
+export declare function useChat<P extends keyof AgentRoutes>(path: P, params?: UseChatParams<P>): UseChatResult<P>;
 export {};
 //# sourceMappingURL=useChat.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"useChat.d.ts","sourceRoot":"","sources":["../../ai/useChat.tsx"],"names":[],"mappings":"AAOA,KAAK,KAAK,GAAG,EAAE,CAAC;AAMhB,UAAU,aAAa;IACrB,KAAK,EAAE,KAAK,CAAC;CACd;AAED,UAAU,cAAc;CAAG;AAE3B,wBAAgB,OAAO,CAAC,MAAM,EAAE,aAAa;;2BAGZ,cAAc;EAE9C"}
+{"version":3,"file":"useChat.d.ts","sourceRoot":"","sources":["../../ai/useChat.tsx"],"names":[],"mappings":"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"}