cortena-ui 1.4.2 → 1.6.0

package/dist/agent-chat/step-label.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"step-label.js","names":[],"sources":["../../src/agent-chat/step-label.ts"],"sourcesContent":["/**\n * The wording map: one plain sentence per tool call (SKILLS-9).\n *\n * A run is a sequence of tool calls, and what the user sees of it today is a\n * tool name and a JSON blob. `engram_describe {\"id\":\"tasks.task.list\"}` is an\n * accurate description of nothing anybody asked for. This module turns the\n * three native tools — `engram_search`, `engram_describe`, `broker_invoke` —\n * into sentences a person can read while they wait.\n *\n * It is a pure function of the tool name and the arguments, in its own module,\n * for two reasons. It is the part most likely to be edited by someone who is\n * not editing the store, and it is the part worth testing exhaustively: the\n * store's job is start/end pairing, and the wording's job is being readable.\n *\n * Deliberately NOT here: anything that needs the result. The client cannot know\n * whether a `broker_invoke` is a read or a write before the reply comes back —\n * only the catalogue knows, and the model only carries `confirmed` once the\n * user has said yes — so an unconfirmed invoke is worded \"Fetching …\", which is\n * true of a read and harmless of a write that has not happened yet. The one\n * result-dependent wording, a 409 `confirmation_required`, is\n * `confirmationRequiredLabel` and the store applies it when the envelope\n * arrives.\n */\n\n/**\n * Which end of the step the label is for.\n *\n * Nearly every sentence reads the same either way, because it describes the\n * step rather than claiming an outcome — \"Reading skill: alerts\" is as true of\n * a finished read as of one in flight, and rewriting it on completion makes the\n * strip jump under the reader's eye for no gain. The exception is the confirmed\n * write, where \"Doing: tasks task create\" and \"Done: tasks task create\" are\n * genuinely different facts and the user needs the second one.\n */\nexport type AgentStepPhase = \"running\" | \"done\";\n\n/** Longest intent or title carried into a label, ellipsis included. */\nconst TEXT_LIMIT = 80;\n\n/**\n * An id as words: `tasks.task.list` -> \"tasks task list\".\n *\n * Deterministic and dumb on purpose. A cleverer mapping — reordering to \"list\n * tasks\", pluralising, looking up a display name — needs a table that has to be\n * maintained for every capability in every extension, and a table that is one\n * release out of date reads worse than the id did.\n */\nexport function humaniseId(id: string): string {\n  return id\n    .split(/[.\\-_]+/)\n    .filter(Boolean)\n    .join(\" \")\n    .toLowerCase();\n}\n\n/** The topic of a skill id: `skill.platform.using-extensions` -> \"using extensions\". */\nfunction skillTopic(id: string): string {\n  const parts = id.split(\".\").filter(Boolean);\n  const last = parts[parts.length - 1];\n  return last ? humaniseId(last) : humaniseId(id);\n}\n\n/**\n * One line of it, sanitised and bounded, with the ellipsis inside the limit.\n *\n * Everything interpolated into a label goes through this, including the ones\n * that look safe: a tool name, an operation id, a server's `message`. All three\n * arrive from outside — a catalogue entry, a broker reply — and none is worth\n * trusting with the length of a line or with the direction of it. Control and\n * format characters are stripped BEFORE the length check, so a run of\n * invisibles cannot eat the budget and a U+202E cannot flip the rest of the\n * strip right-to-left. Newlines have already become spaces by then, so the\n * strip does not silently join two words.\n */\nexport function truncate(text: string, limit: number = TEXT_LIMIT): string {\n  const collapsed = text\n    .replace(/\\s+/g, \" \")\n    .trim()\n    .replace(/[\\p{Cf}\\p{Cc}]/gu, \"\");\n  return collapsed.length <= limit ? collapsed : `${collapsed.slice(0, limit - 1)}…`;\n}\n\n/**\n * The line for a call nothing better can be said about yet.\n *\n * Its own function because two other places have to RECOGNISE it: the store\n * re-words a step that finished on this line if its arguments turn up late, and\n * the strip holds it out of the live region rather than announcing\n * \"Working: broker_invoke\" to a screen reader a moment before the real sentence\n * replaces it.\n */\nexport function genericLabel(toolName: string): string {\n  return `Working: ${truncate(toolName)}`;\n}\n\n/** Is this label the fallback rather than something the arguments produced? */\nexport function isGenericLabel(toolName: string, label: string): boolean {\n  return label === genericLabel(toolName);\n}\n\nfunction readString(args: Record<string, unknown> | undefined, key: string): string {\n  const value = args?.[key];\n  return typeof value === \"string\" && value.trim() ? value : \"\";\n}\n\n/**\n * The line shown for one tool call.\n *\n * | tool | label |\n * | --- | --- |\n * | `engram_search` | Looking for a way to \\<intent\\> |\n * | `engram_describe`, `skill.*` | Reading skill: \\<title, or the topic\\> |\n * | `engram_describe`, anything else | Checking how to \\<id as words\\> |\n * | `broker_invoke`, `confirmed: true` | Doing: \\<operation\\> / Done: \\<operation\\> |\n * | `broker_invoke`, otherwise | Fetching \\<operation\\> |\n * | anything else | Working: \\<tool name\\> |\n *\n * The key argument missing falls through to the last row rather than inventing\n * a sentence about nothing: arguments arrive in a second event\n * (`TOOL_CALL_ARGS`), so \"no arguments yet\" is a state every call passes\n * through, and the generic line is what it should read as until they land.\n */\nexport function stepLabel(\n  toolName: string,\n  args: Record<string, unknown> | undefined,\n  phase: AgentStepPhase,\n): string {\n  switch (toolName) {\n    case \"engram_search\": {\n      const intent = readString(args, \"intent\");\n      if (intent) {\n        return `Looking for a way to ${truncate(intent)}`;\n      }\n      break;\n    }\n    case \"engram_describe\": {\n      const id = readString(args, \"id\");\n      if (!id) {\n        break;\n      }\n      if (id.startsWith(\"skill.\")) {\n        // Ingest carries the title on the row, not on the call, so it is only\n        // here when the model has already seen the index and repeated it.\n        const title = readString(args, \"title\");\n        return `Reading skill: ${truncate(title ? title : skillTopic(id))}`;\n      }\n      return `Checking how to ${truncate(humaniseId(id))}`;\n    }\n    case \"broker_invoke\": {\n      const operation = readString(args, \"operation\");\n      if (!operation) {\n        break;\n      }\n      const label = truncate(humaniseId(operation));\n      if (args?.confirmed === true) {\n        return phase === \"done\" ? `Done: ${label}` : `Doing: ${label}`;\n      }\n      return `Fetching ${label}`;\n    }\n    default:\n      break;\n  }\n  return genericLabel(toolName);\n}\n\n/**\n * The label for a call the broker refused pending a yes.\n *\n * A 409 `confirmation_required` is not a failure — it is the broker doing its\n * job on a write the user has not approved — so the step keeps its tick and\n * changes its words. Drawn as an error it reads as \"the agent broke\"; drawn as\n * \"Fetching …\", completed, it reads as though the write went through.\n */\nexport function confirmationRequiredLabel(args: Record<string, unknown> | undefined): string {\n  const operation = readString(args, \"operation\");\n  return `Needs your confirmation: ${operation ? truncate(humaniseId(operation)) : \"that action\"}`;\n}\n"],"mappings":";;;AAqCA,MAAM,aAAa;;;;;;;;;AAUnB,SAAgB,WAAW,IAAoB;CAC7C,OAAO,GACJ,MAAM,SAAS,CAAC,CAChB,OAAO,OAAO,CAAC,CACf,KAAK,GAAG,CAAC,CACT,YAAY;AACjB;;AAGA,SAAS,WAAW,IAAoB;CACtC,MAAM,QAAQ,GAAG,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO;CAC1C,MAAM,OAAO,MAAM,MAAM,SAAS;CAClC,OAAO,OAAO,WAAW,IAAI,IAAI,WAAW,EAAE;AAChD;;;;;;;;;;;;;AAcA,SAAgB,SAAS,MAAc,QAAgB,YAAoB;CACzE,MAAM,YAAY,KACf,QAAQ,QAAQ,GAAG,CAAC,CACpB,KAAK,CAAC,CACN,QAAQ,oBAAoB,EAAE;CACjC,OAAO,UAAU,UAAU,QAAQ,YAAY,GAAG,UAAU,MAAM,GAAG,QAAQ,CAAC,EAAE;AAClF;;;;;;;;;;AAWA,SAAgB,aAAa,UAA0B;CACrD,OAAO,YAAY,SAAS,QAAQ;AACtC;;AAGA,SAAgB,eAAe,UAAkB,OAAwB;CACvE,OAAO,UAAU,aAAa,QAAQ;AACxC;AAEA,SAAS,WAAW,MAA2C,KAAqB;CAClF,MAAM,QAAQ,OAAO;CACrB,OAAO,OAAO,UAAU,YAAY,MAAM,KAAK,IAAI,QAAQ;AAC7D;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,UACd,UACA,MACA,OACQ;CACR,QAAQ,UAAR;EACE,KAAK,iBAAiB;GACpB,MAAM,SAAS,WAAW,MAAM,QAAQ;GACxC,IAAI,QACF,OAAO,wBAAwB,SAAS,MAAM;GAEhD;EACF;EACA,KAAK,mBAAmB;GACtB,MAAM,KAAK,WAAW,MAAM,IAAI;GAChC,IAAI,CAAC,IACH;GAEF,IAAI,GAAG,WAAW,QAAQ,GAAG;IAG3B,MAAM,QAAQ,WAAW,MAAM,OAAO;IACtC,OAAO,kBAAkB,SAAS,QAAQ,QAAQ,WAAW,EAAE,CAAC;GAClE;GACA,OAAO,mBAAmB,SAAS,WAAW,EAAE,CAAC;EACnD;EACA,KAAK,iBAAiB;GACpB,MAAM,YAAY,WAAW,MAAM,WAAW;GAC9C,IAAI,CAAC,WACH;GAEF,MAAM,QAAQ,SAAS,WAAW,SAAS,CAAC;GAC5C,IAAI,MAAM,cAAc,MACtB,OAAO,UAAU,SAAS,SAAS,UAAU,UAAU;GAEzD,OAAO,YAAY;EACrB;CAGF;CACA,OAAO,aAAa,QAAQ;AAC9B;;;;;;;;;AAUA,SAAgB,0BAA0B,MAAmD;CAC3F,MAAM,YAAY,WAAW,MAAM,WAAW;CAC9C,OAAO,4BAA4B,YAAY,SAAS,WAAW,SAAS,CAAC,IAAI;AACnF"}

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

@@ -0,0 +1,102 @@
+"use client";
+import { A2UIChatBlock } from "./a2ui-block.js";
+import { AgentApprovalDecision, AgentApprovalRequest, AgentChatClient, AgentChatMessage, AgentChatStep, AgentSession, AgentToolResultMetadata } from "./types.js";
+//#region src/agent-chat/store.d.ts
+export interface AgentToolEntry {
+  id: string;
+  name: string;
+  status: "running" | "complete" | "error";
+  input?: unknown;
+  output?: unknown;
+  startedAt: number;
+  completedAt?: number;
+}
+export interface AgentChatState {
+  sessionKey: string | null;
+  messages: AgentChatMessage[];
+  streaming: boolean;
+  streamText: string;
+  streamThinkingText: string;
+  streamA2ui: A2UIChatBlock[];
+  runId: string | null;
+  hasMoreHistory: boolean;
+  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`.
+   *
+   * `parseHistoryMessages` folds a turn — an assistant preamble, the tool call,
+   * the tool result, the answer — into one visible message, so the two numbers
+   * diverge on the very first agent turn. `offset` is an offset into the
+   * server's records, and paging with the folded count asked for records the
+   * screen already had and skipped the ones it did not: "load older" silently
+   * lost messages the further back a user read.
+   */
+  historyCount: number;
+  sessions: AgentSession[];
+  loadingSessions: boolean;
+  /** 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;
+  /**
+   * Names the `sessionStorage` slot the current session key lives in. Two
+   * pop-ups with different scopes never share a key, which is what keeps one
+   * extension's chat out of another's.
+   */
+  storageScope: string;
+  /** Skip reading and writing `sessionStorage`; for a transient mount. */
+  ephemeral?: boolean;
+  thinking?: "low" | "medium" | "high";
+}
+export interface UseAgentChatResult extends AgentChatState {
+  send: (text: string, attachments?: unknown[]) => void;
+  sendAction: (action: NonNullable<Parameters<AgentChatClient["send"]>[0]["a2uiAction"]>) => void;
+  abort: () => void;
+  resolveApproval: (id: string, decision: AgentApprovalDecision) => void;
+  newSession: () => void;
+  resumeSession: (key: string) => void;
+  loadOlder: () => void;
+  refreshSessions: () => void;
+}
+export declare function useAgentChat({ client, storageScope, ephemeral, thinking }: UseAgentChatOptions): UseAgentChatResult;
+//#endregion
+//# sourceMappingURL=store.d.ts.map