cortena-ui 1.5.0 → 1.7.0

package/dist/agent-chat/store.d.ts

@@ -1,6 +1,6 @@
 "use client";
 import { A2UIChatBlock } from "./a2ui-block.js";
-import { AgentApprovalDecision, AgentApprovalRequest, AgentChatClient, AgentChatMessage, AgentSession } from "./types.js";
+import { AgentApprovalDecision, AgentApprovalRequest, AgentChatClient, AgentChatMessage, AgentChatSendInput, AgentChatStep, AgentSession, AgentToolResultMetadata } from "./types.js";
 //#region src/agent-chat/store.d.ts
 export interface AgentToolEntry {
   id: string;
@@ -23,6 +23,26 @@ export interface AgentChatState {
   loadingHistory: boolean;
   toolOrder: string[];
   tools: Record<string, AgentToolEntry>;
+  /**
+   * The turn's tool calls in plain words, in arrival order (SKILLS-9).
+   *
+   * The same calls as `tools`, worded rather than dumped, and rendered under
+   * the assistant turn instead of in the strip at the foot. Cleared when the
+   * next run starts, so the list is always "what is happening now" or "what
+   * just happened", never a transcript.
+   */
+  steps: AgentChatStep[];
+  /**
+   * Ids of steps the `STEP_LIMIT` cap has already dropped.
+   *
+   * A runaway turn pushes the first calls off the front of the list, and their
+   * results arrive afterwards. Without this the store saw an id it did not
+   * know, took it for a call nobody announced, and appended a fresh
+   * "Working: tool" line at the BOTTOM of the strip — the oldest call in the
+   * turn, drawn as the newest, with no words on it. Bounded, because it exists
+   * to recognise a handful of stragglers, not to keep a transcript.
+   */
+  retiredSteps: string[];
   approvals: AgentApprovalRequest[];
   /**
    * Transcript RECORDS loaded, which is not `messages.length`.
@@ -40,6 +60,21 @@ export interface AgentChatState {
   /** A failure the user has to be told about, e.g. no template for the slug. */
   error: string | null;
 }
+/**
+ * `TOOL_CALL_RESULT.metadata`, read defensively.
+ *
+ * `null` when nothing usable arrived, which a transport that predates the
+ * contract will produce. A step with no metadata at all is treated as a
+ * success by `tool.complete` and as a failure by `tool.error`, which is the
+ * most either event can honestly claim on its own.
+ *
+ * Note what is NOT here: any reading of `content`. The result text is the
+ * model's copy of the reply, in whatever shape the tool returned, and the
+ * client's previous attempt to find `ok: false` in it matched nothing real —
+ * a Cortena tool result is `{ content: [...], details }`, so the envelope it
+ * was looking for was two levels down when it existed at all.
+ */
+export declare function readResultMetadata(raw: unknown): AgentToolResultMetadata | null;
 export interface UseAgentChatOptions {
   client: AgentChatClient;
   /**
@@ -51,17 +86,68 @@ export interface UseAgentChatOptions {
   /** Skip reading and writing `sessionStorage`; for a transient mount. */
   ephemeral?: boolean;
   thinking?: "low" | "medium" | "high";
+  /**
+   * Mint the key for a brand-new session. Defaults to `mintSessionKey(client.agentId)`,
+   * which binds the session to this client's agent template. A host whose
+   * sessions are bound some other way — cortenaweb lets the user pick an agent
+   * per chat, and a chat with no pick is bound server-side to the default —
+   * supplies its own.
+   */
+  mintSessionKey?: () => string;
+  /**
+   * Read the stored session key back on mount. Default `true`. A host whose
+   * URL names the session — `/chat/<key>` — is the source of truth itself and
+   * passes `false`: the key is still WRITTEN, so the rule "one window, one
+   * session" holds, but nothing is restored under the URL's feet and no
+   * history is fetched for a session the page is about to leave.
+   */
+  restoreSession?: boolean;
+  /**
+   * Fetch `sessions.list` on mount and after each send. Default `true`. A host
+   * with its own session list — cortenaweb's sidebar — passes `false` and the
+   * hook makes no session calls at all; `sessions` stays empty.
+   */
+  listSessions?: boolean;
+}
+/** What `send` accepts beside the text and the attachments. */
+export interface AgentChatSendOptions {
+  /** The model for this run; the composer's selector. */
+  model?: AgentChatSendInput["model"];
+  /** Overrides the hook-level `thinking` for this run. */
+  thinking?: AgentChatSendInput["thinking"];
 }
 export interface UseAgentChatResult extends AgentChatState {
-  send: (text: string, attachments?: unknown[]) => void;
+  send: (text: string, attachments?: unknown[], options?: AgentChatSendOptions) => void;
   sendAction: (action: NonNullable<Parameters<AgentChatClient["send"]>[0]["a2uiAction"]>) => void;
+  /** A click inside a rendered MCP App, as the next run's input. No user bubble. */
+  sendMcpAppAction: (action: NonNullable<AgentChatSendInput["mcpAppAction"]>) => void;
   abort: () => void;
   resolveApproval: (id: string, decision: AgentApprovalDecision) => void;
   newSession: () => void;
   resumeSession: (key: string) => void;
-  loadOlder: () => void;
+  /**
+   * Leave the session without starting another. The transcript empties, the
+   * stored key is removed and the next `send` mints a fresh key — which is
+   * what a host's "New chat" wants when the URL should not change until the
+   * first message goes out. `newSession` mints immediately; this does not.
+   */
+  clearSession: () => void;
+  /**
+   * Ask again for the message this one answered: the bubble is dropped and the
+   * user turn before it is sent again, so the new answer takes its place. Also
+   * the Retry on a failed turn. A no-op while a run is live or when nothing
+   * precedes the message.
+   */
+  regenerate: (messageId: string) => void;
+  /**
+   * Ask for the next page of older history. `true` when a load was started;
+   * `false` when there is nothing to do — no session, a load already in
+   * flight, or no more history — so a caller that saves scroll position
+   * before a prepend knows whether one is coming.
+   */
+  loadOlder: () => boolean;
   refreshSessions: () => void;
 }
-export declare function useAgentChat({ client, storageScope, ephemeral, thinking }: UseAgentChatOptions): UseAgentChatResult;
+export declare function useAgentChat({ client, storageScope, ephemeral, thinking, mintSessionKey: mintKey, restoreSession, listSessions }: UseAgentChatOptions): UseAgentChatResult;
 //#endregion
 //# sourceMappingURL=store.d.ts.map