cortena-ui 1.4.2 → 1.6.0

package/src/agent-chat/types.ts

@@ -0,0 +1,308 @@
+/**
+ * The transport contract `AgentChat` is written against.
+ *
+ * Everything the chat surface needs from a server is behind `AgentChatClient`,
+ * and nothing in the interface names AG-UI, HTTP or React. That is what makes
+ * the surface testable — `test/agent-chat.test.tsx` drives it from a fake that
+ * replays scripted event sequences — and it is what keeps `@ag-ui/client` out
+ * of every module except `./agui-client.ts`.
+ *
+ * The three sinks are subscriptions rather than constructor callbacks so one
+ * client can outlive several mounts of the component, which is what a pop-up
+ * that collapses and reopens mid-run does.
+ */
+
+import type { A2UIChatBlock } from "./a2ui-block";
+
+/* ── what a session is ───────────────────────────────────────────────────── */
+
+/**
+ * A row of `sessions.list`.
+ *
+ * Titles fall back in a fixed order (§17.2 of the extension how-to):
+ * `label`, `autoTitle`, `derivedTitle`, `displayName`, `lastMessagePreview`,
+ * then "New conversation". `sessionTitle` below is that order, in one place.
+ */
+export interface AgentSession {
+  /** The session key, verbatim — this is also the AG-UI `threadId`. */
+  key: string;
+  label?: string | null;
+  autoTitle?: string | null;
+  derivedTitle?: string | null;
+  displayName?: string | null;
+  lastMessagePreview?: string | null;
+  updatedAt?: number | null;
+}
+
+/** The title to show for a session row. */
+export function sessionTitle(session: AgentSession): string {
+  for (const candidate of [
+    session.label,
+    session.autoTitle,
+    session.derivedTitle,
+    session.displayName,
+    session.lastMessagePreview,
+  ]) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  return "New conversation";
+}
+
+/* ── what a message is ───────────────────────────────────────────────────── */
+
+export interface AgentChatMessage {
+  id: string;
+  role: "user" | "assistant";
+  text: string;
+  timestamp: number;
+  attachments?: string[];
+  /** The chain of thought behind this turn, collapsed by default. */
+  thinkingText?: string;
+  isError?: boolean;
+  /** True when the wire record was a tool call or a tool result; hidden. */
+  isToolMessage?: boolean;
+  /**
+   * The run that produced this message. Absent on anything loaded from
+   * history. A `final` folds into the previous bubble only when the two share
+   * this value, so one run's answer cannot be rewritten by the next one's.
+   */
+  runId?: string;
+  /** UI the agent drew, carried outside the prose. */
+  a2ui?: A2UIChatBlock[];
+}
+
+/* ── what a step is ──────────────────────────────────────────────────────── */
+
+/**
+ * One tool call of the turn, in plain words (SKILLS-9).
+ *
+ * A step and an `AgentToolEntry` are the same call seen from two distances.
+ * The entry is the record — name, arguments, output, the `ui://` resource an
+ * MCP App is mounted from — and it is what `renderToolCall` is handed. The step
+ * is the sentence: what the agent is doing, now, for someone who is waiting and
+ * is not going to open a JSON blob to find out.
+ *
+ * `label` is stored rather than derived at render time because it is derived
+ * from the arguments, and the arguments arrive AFTER the start event. Keeping
+ * the computed sentence on the step means the strip is a pure function of state
+ * and the recompute happens once, where the arguments land.
+ */
+export interface AgentChatStep {
+  /** The AG-UI `toolCallId`; the same id the tool strip's entry carries. */
+  id: string;
+  toolName: string;
+  /**
+   * The call's input, when it parsed as an object. Absent until it arrives.
+   *
+   * In memory only. It is NOT persisted — see `storedStep` in `session.ts` —
+   * because a tool call's arguments are the user's data: a search intent, a
+   * customer id, the body of a record being written.
+   */
+  args?: Record<string, unknown>;
+  /** The plain sentence. See `step-label.ts` for the map that produces it. */
+  label: string;
+  startedAt: number;
+  /**
+   * `stopped` is the user's Stop button, and is deliberately not `error`:
+   * nothing failed, the answer was simply no longer wanted, and a red cross
+   * against a call the user cancelled reads as a fault they caused.
+   *
+   * `paused` is the run ending on an interrupt with the call still OPEN — the
+   * producer is waiting for an approval or for a frontend tool to run — and it
+   * is deliberately not `done`: nothing has happened yet, and a tick against a
+   * write the user has not agreed to is a lie about their data. It stops the
+   * spinner and the elapsed counter, resolves to `done` or `error` when the
+   * run resumes and the result arrives, and becomes `stopped` on a deny.
+   */
+  status: "running" | "done" | "error" | "stopped" | "paused";
+  endedAt?: number;
+  /** The failure to show, on a step that failed. Bounded and sanitised. */
+  errorMessage?: string;
+}
+
+/** The result detail cortenacore puts on `TOOL_CALL_RESULT.metadata.meta`. */
+export interface AgentToolResultMeta {
+  status?: number;
+  code?: string;
+  message?: string;
+}
+
+/**
+ * `TOOL_CALL_RESULT.metadata`, normalised.
+ *
+ * This is the ONLY thing that says whether a tool call failed. `content` is
+ * the result as the model sees it — for a Cortena tool, a JSON string of
+ * `{ content: [{ type: "text", text }], details }` — and reading an envelope
+ * out of it means guessing at a shape the producer never promised. The client
+ * did guess, for `ok: false` at the top level, and the guess was simply wrong:
+ * the top level is the tool-result wrapper, so every failed call was drawn as
+ * a success.
+ *
+ * `meta` is optional, and where it is absent only `isError` can be trusted.
+ */
+export interface AgentToolResultMetadata {
+  toolName?: string;
+  isError: boolean;
+  meta?: AgentToolResultMeta;
+}
+
+/* ── the three sinks ─────────────────────────────────────────────────────── */
+
+/**
+ * One chat event. The same `{ state: "delta" | "final" | "error" }` shape
+ * cortenacore broadcasts, so a client for a different transport has a
+ * documented target to hit.
+ *
+ * `delta` carries a SNAPSHOT, not an increment: every delta repeats all the
+ * text, all the thinking and every A2UI block seen so far. Two transports that
+ * disagree about this leave the store in different states for the same run.
+ */
+export interface AgentChatEvent {
+  runId: string;
+  sessionKey: string;
+  seq: number;
+  state: "delta" | "final" | "error";
+  /**
+   * Set on a `final` that came from a `RUN_FINISHED` carrying
+   * `outcome.type === "interrupt"`.
+   *
+   * The run has stopped, but it has not FINISHED: cortenacore pauses it for an
+   * approval or for a frontend tool and leaves the tool call open, and the
+   * continuation is a second run that ends the same call. Without this the
+   * store read every interrupt as a success and ticked a write nobody had
+   * approved yet.
+   */
+  interrupted?: boolean;
+  message?: {
+    role?: string;
+    content?: Array<{ type: string; text?: string; thinking?: string; a2ui?: unknown }>;
+    timestamp?: number;
+  };
+  errorMessage?: string;
+}
+
+/** One step of the tool strip. */
+export interface AgentToolEvent {
+  event: "tool.start" | "tool.args" | "tool.progress" | "tool.complete" | "tool.error";
+  data: {
+    id?: string;
+    name?: string;
+    /** `tool.args`: the call's input, parsed when it was valid JSON. */
+    input?: unknown;
+    output?: unknown;
+    /**
+     * `TOOL_CALL_RESULT.metadata`, forwarded verbatim on an end event.
+     *
+     * Untyped on purpose: it crosses a transport, so it is whatever arrived.
+     * `readResultMetadata` in `store.ts` is what turns it into an
+     * `AgentToolResultMetadata`, and it is the one place that decides whether
+     * a call failed.
+     */
+    metadata?: Record<string, unknown>;
+    startedAt?: number;
+    completedAt?: number;
+  };
+}
+
+/** Decisions cortenacore accepts on `POST /agui/approval`. */
+export type AgentApprovalDecision = "allow-once" | "allow-always" | "deny";
+
+export interface AgentApprovalRequest {
+  id: string;
+  /** The command, or the tool, the approval is about. */
+  toolName: string;
+  args: Record<string, unknown>;
+  timestamp: number;
+  /**
+   * The run and the session this request arrived on, captured when it arrived.
+   *
+   * A decision is bound to them rather than resolved against whatever run
+   * happens to be in flight when the user presses a button. The two come
+   * apart routinely: an approval pauses a run, the user opens another session
+   * in the drawer or starts a second turn, and the client's idea of "the
+   * current thread" has moved on. Answering "allow" against the wrong thread
+   * is a command approved in a conversation nobody was asked about.
+   */
+  runId: string;
+  sessionKey: string;
+  /** Set when a decision was made and the server would not take it. */
+  error?: string;
+}
+
+/** Where an approval came from, and therefore where the decision must go. */
+export interface AgentApprovalContext {
+  runId: string;
+  sessionKey: string;
+}
+
+export type AgentApprovalEvent =
+  | { type: "request"; request: AgentApprovalRequest }
+  /** `decision: null` is an expiry. It is treated as a denial. */
+  | { type: "resolved"; id: string; decision: AgentApprovalDecision | null };
+
+/* ── the client ──────────────────────────────────────────────────────────── */
+
+export interface AgentChatSendInput {
+  /** The session key to run in. `threadId` is this value verbatim. */
+  sessionKey: string;
+  /** What the user typed. Empty for an action sent by rendered UI. */
+  message: string;
+  /** The run id; also the idempotency key. */
+  runId: string;
+  attachments?: unknown[];
+  thinking?: "low" | "medium" | "high";
+  model?: { provider: string; model: string };
+  /** A click inside an A2UI surface. Never a sentence the user appears to type. */
+  a2uiAction?: { surfaceId: string; componentId: string; name: string; payload: Record<string, unknown> };
+  /** The same, from inside a rendered MCP App. */
+  mcpAppAction?: Record<string, unknown>;
+}
+
+/**
+ * Everything `AgentChat` needs from a server.
+ *
+ * `request` is deliberately a method name plus params rather than a URL: the
+ * two calls the chat makes — `sessions.list` and `chat.history` — are control
+ * plane methods, and a host that proxies them through its own gateway chooses
+ * its own paths.
+ */
+export interface AgentChatClient {
+  /** The agent this client talks to. Session keys are `agent:<agentId>:…`. */
+  readonly agentId: string;
+  /** Start a run. Resolves when the run has been accepted, not when it ends. */
+  send(input: AgentChatSendInput): Promise<void>;
+  /** Stop the run in flight. Best-effort; local state resets either way. */
+  abort(params?: { runId?: string; sessionKey?: string }): Promise<void>;
+  /**
+   * Answer an approval. `context` is the `{ runId, sessionKey }` the request
+   * carried, not the run in flight — see `AgentApprovalRequest`. Rejects when
+   * the server refuses the decision, so the caller can put the card back.
+   */
+  resolveApproval(
+    id: string,
+    decision: AgentApprovalDecision,
+    context: AgentApprovalContext,
+  ): Promise<void>;
+  /** `sessions.list` and `chat.history`. */
+  request<T = unknown>(method: string, params: Record<string, unknown>): Promise<T>;
+  /** Chat deltas, finals and errors. Returns an unsubscribe. */
+  onChat(sink: (event: AgentChatEvent) => void): () => void;
+  /** Tool starts, arguments, progress and results. Returns an unsubscribe. */
+  onTool(sink: (event: AgentToolEvent) => void): () => void;
+  /** Approval requests and resolutions. Returns an unsubscribe. */
+  onApproval(sink: (event: AgentApprovalEvent) => void): () => void;
+}
+
+/** What `sessions.list` answers. */
+export interface AgentSessionsListResponse {
+  sessions?: AgentSession[];
+}
+
+/** What `chat.history` answers. `messages` are raw transcript records. */
+export interface AgentChatHistoryResponse {
+  messages?: unknown[];
+  hasMore?: boolean;
+  total?: number;
+}

package/src/components/admin-permissions/admin-permissions.tsx

@@ -0,0 +1,130 @@
+"use client";
+
+import * as React from "react";
+import { PageHeader } from "@/components/page-header";
+import { Tabs, TabsList, TabsTrigger } from "@/components/tabs";
+import { cn } from "@/lib/cn";
+import { AdminPermissionsProvider } from "./context";
+import { AdminLicenceScreen } from "./licence";
+import { AdminMatrix } from "./matrix";
+import { AdminMembers } from "./members";
+import { AdminRoles } from "./roles";
+import {
+  ADMIN_ROUTES,
+  ADMIN_ROUTE_LABELS,
+  type AdminPermissionsApi,
+  type AdminRoute,
+} from "./types";
+
+export interface AdminPermissionsProps
+  extends Omit<React.ComponentProps<"div">, "children" | "title"> {
+  /** Everything the screen reads and writes. The extension's, entirely. */
+  api: AdminPermissionsApi;
+  /**
+   * The screen to show. Pass it and the host's router owns the URL; omit it
+   * and the composition keeps the current screen in its own state.
+   */
+  route?: AdminRoute;
+  /** The screen to open with when `route` is not passed. @default "members" */
+  defaultRoute?: AdminRoute;
+  /**
+   * Fired when the administrator picks another screen. Always fired, whether
+   * or not `route` is controlled, so a host can push the URL without also
+   * having to hold the state.
+   */
+  onNavigate?: (route: AdminRoute) => void;
+  /** `false` hides the title block, for a host that renders its own. */
+  header?: boolean;
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+}
+
+/**
+ * AdminPermissions — the consistent admin screen for every Cortena extension
+ * (§13, DESIGN-D11 as amended by DESIGN-D22; audit rules P-14, P-42, P-43).
+ *
+ * Four screens behind `admin/*`: `/admin/members`, `/admin/roles`,
+ * `/admin/licence`, `/admin/permissions`. It renders whatever roles and
+ * actions the extension declares and **defines none of its own** — there is
+ * not one role name, action name or grant in this folder. That is exactly what
+ * lets a verification workflow and a work tracker have completely different
+ * role models and still look like one product.
+ *
+ * ```tsx
+ * <Route path="admin/*" element={
+ *   <AdminPermissions
+ *     api={adminApi}
+ *     route={screenFromPath(location.pathname)}
+ *     onNavigate={(next) => navigate(`/admin/${next}`)}
+ *   />
+ * } />
+ * ```
+ *
+ * **Router-agnostic, by a `route` prop plus `onNavigate`.** The component
+ * imports no router and never touches `history` or `location`. Those four
+ * paths are real URLs — deep-linkable, bookmarkable, and answerable to the
+ * back button — and only the host's router can own a URL; a component that
+ * pushed history itself would fight whichever router the extension chose.
+ * `onNavigate` reports the intent, the host turns it into a navigation, and
+ * `route` comes back as the answer.
+ *
+ * An internal fallback exists for the case with no router in it — the guide,
+ * a test, a small app: omit `route` and the composition keeps the screen in
+ * its own state. `onNavigate` still fires, so a host can start uncontrolled
+ * and add a router later without changing anything else.
+ *
+ * The navigation is a real tablist rather than a row of links, because the
+ * choice is between panels of one screen; the host is free to hide it with
+ * `header={false}` and drive `route` from its own chrome.
+ */
+export function AdminPermissions({
+  api,
+  route,
+  defaultRoute = "members",
+  onNavigate,
+  header = true,
+  title = "Administration",
+  description = "Who is in this organisation, what your roles let them do, and the licence behind it.",
+  className,
+  ...props
+}: AdminPermissionsProps) {
+  const [internal, setInternal] = React.useState<AdminRoute>(defaultRoute);
+  const active = route ?? internal;
+
+  const go = (next: AdminRoute) => {
+    if (route === undefined) setInternal(next);
+    onNavigate?.(next);
+  };
+
+  return (
+    <AdminPermissionsProvider api={api}>
+      <div
+        data-slot="admin-permissions"
+        data-route={active}
+        className={cn("flex flex-col gap-5", className)}
+        {...props}
+      >
+        {header ? <PageHeader title={title} description={description} /> : null}
+        <Tabs
+          value={active}
+          onValueChange={(value) => go(value as AdminRoute)}
+          data-slot="admin-permissions-nav"
+        >
+          <TabsList aria-label="Administration screens">
+            {ADMIN_ROUTES.map((item) => (
+              <TabsTrigger key={item} value={item} data-route={item}>
+                {ADMIN_ROUTE_LABELS[item]}
+              </TabsTrigger>
+            ))}
+          </TabsList>
+        </Tabs>
+        <div data-slot="admin-permissions-screen">
+          {active === "members" ? <AdminMembers /> : null}
+          {active === "roles" ? <AdminRoles /> : null}
+          {active === "licence" ? <AdminLicenceScreen /> : null}
+          {active === "permissions" ? <AdminMatrix /> : null}
+        </div>
+      </div>
+    </AdminPermissionsProvider>
+  );
+}