@actioneer/ads 0.3.0 → 0.4.0

package/components/ai-elements/agent-trace.d.ts

@@ -0,0 +1,87 @@
+import { ReactNode } from 'react';
+import { ToolState } from './tool';
+/**
+ * AgentTrace — the ENTIRE agent reasoning trace as one component, so any
+ * consumer gets the complete, correct experience instead of hand-wiring it
+ * from ChainOfThought / Task / Tool primitives and getting a subset (a
+ * misaligned connector, no live line, no slow-call handoff).
+ *
+ * It is live-only and fully controlled: pass the current agent state, update
+ * it as the run progresses, and the component reflects it. There is no
+ * internal replay engine — the consuming app owns progression (and, if it
+ * wants a counting clock, ticks `elapsed`).
+ *
+ * What it renders, always:
+ *   1. Phases  — steps grouped by `group`, each a `Task` disclosure; finished
+ *                phases fold away while another is active.
+ *   2. Steps   — a `ChainOfThought connector="tree"` per phase; settled steps
+ *                hang off the phase on a measured tree connector.
+ *   3. Tools   — each call is a `Tool` card hung off its step as a branch.
+ * Plus the reason-first live line (the `active` step is narrated by
+ * `ResearchActivity` and joins the tree only once it settles) and, when an
+ * active step outruns `slowSeconds`, the handoff `Alert`.
+ */
+/** A single tool call within a step. */
+export interface AgentTraceCall {
+    name: string;
+    state: ToolState;
+    input?: unknown;
+    /** Rendered when the call succeeds. */
+    output?: unknown;
+    /** Rendered when the call errors. */
+    error?: string;
+}
+/**
+ * `active` is the in-flight step (there should be at most one) — it is owned
+ * by the live line, not the tree. `pending` steps are not shown yet.
+ */
+export type AgentTraceStepStatus = "complete" | "active" | "error" | "pending";
+export interface AgentTraceStep {
+    /** Stable identity — used for the review handoff and React keys. */
+    id: string;
+    /** Phase / section this step belongs to, e.g. "Research". */
+    group: string;
+    /** Icon for the phase header (only the first step in a group needs it). */
+    groupIcon?: ReactNode;
+    /** The step's own leading icon. */
+    icon?: ReactNode;
+    label: string;
+    /** Attribution — shown only when it differs from `mainAgent`. */
+    agent?: string;
+    /** The agent's own narration for this step. */
+    detail?: ReactNode;
+    /** Cubes / tables / sources this step touched, as chips. */
+    sources?: string[];
+    status: AgentTraceStepStatus;
+    /** Preformatted elapsed (e.g. "0:06"); falls back to `seconds`. */
+    elapsed?: ReactNode;
+    /** Wall clock in seconds — powers the phase total and slow detection. */
+    seconds?: number;
+    calls?: AgentTraceCall[];
+}
+export interface AgentTraceProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "onSelect"> {
+    steps: AgentTraceStep[];
+    /** Attribution equal to this is suppressed (it's the orchestrator). */
+    mainAgent?: string;
+    /** An active step past this many seconds shows the handoff. Default 60. */
+    slowSeconds?: number;
+    /** Ids already handed off — their button reads "Sent" and is disabled. */
+    reviewedStepIds?: string[];
+    /** Fires when the reader hands a slow step off for review. */
+    onSendForReview?: (step: AgentTraceStep) => void;
+    /** Override the handoff copy for a given stuck step. */
+    slowMessage?: (step: AgentTraceStep) => {
+        title: ReactNode;
+        detail: ReactNode;
+    };
+    /**
+     * Render a tool call yourself instead of the built-in card — for consumers
+     * with richer tool rendering (SQL extraction, custom payloads). Falls back
+     * to the default `Tool` card.
+     */
+    renderCall?: (call: AgentTraceCall) => ReactNode;
+}
+export declare const AgentTrace: {
+    ({ steps, mainAgent, slowSeconds, reviewedStepIds, onSendForReview, slowMessage, renderCall, className, ...props }: AgentTraceProps): import("react").JSX.Element;
+    displayName: string;
+};

package/components/ai-elements/agent-trace.js

@@ -0,0 +1,180 @@
+"use client";
+import { jsxs as a, jsx as t, Fragment as j } from "react/jsx-runtime";
+import { memo as b, useState as D, useRef as _, useEffect as z } from "react";
+import { cn as L } from "../../lib/cn.js";
+import { Clock as F } from "../../lib/icons.js";
+import { Alert as G, AlertTitle as H, AlertDescription as U } from "../alert.js";
+import { Button as B } from "../button.js";
+import { Text as K } from "../typography.js";
+import { ChainOfThoughtStep as P, ChainOfThoughtTrigger as W, ChainOfThoughtContent as q, ChainOfThoughtItem as J, ChainOfThoughtSearchResults as Q, ChainOfThoughtSearchResult as V, ChainOfThought as X } from "./chain-of-thought.js";
+import { ResearchActivity as Y } from "./research-activity.js";
+import { Task as Z, TaskTrigger as ee, TaskContent as te } from "./task.js";
+import { Tool as ne, ToolHeader as re, ToolContent as oe, ToolInput as se, ToolOutput as ie } from "./tool.js";
+const ae = "Main Agent", le = 60;
+function x(e) {
+  const o = Math.floor(e);
+  return `${Math.floor(o / 60)}:${String(o % 60).padStart(2, "0")}`;
+}
+function v(e) {
+  if (e.elapsed != null) return e.elapsed;
+  if (e.seconds != null) return x(e.seconds);
+}
+function y(e) {
+  const o = [];
+  for (const s of e) o.includes(s.group) || o.push(s.group);
+  return o;
+}
+function ce(e) {
+  const o = new Set(e.flatMap((i) => i.sources ?? [])).size, s = e.reduce((i, c) => i + (c.seconds ?? 0), 0), l = [];
+  return o && l.push(`${o} ${o === 1 ? "source" : "sources"}`), s && e.length > 1 && l.push(x(s)), l.join(" · ") || void 0;
+}
+function de(e) {
+  var i, c, h;
+  const o = (c = (i = e.calls) == null ? void 0 : i[0]) == null ? void 0 : c.name, s = (((h = e.calls) == null ? void 0 : h.length) ?? 0) - 1, l = s > 0 ? ` ${s} other call${s === 1 ? "" : "s"} in this step ${s === 1 ? "is" : "are"} waiting behind it.` : "";
+  return {
+    title: o ? `The ${o} call has not returned` : "This step has not finished",
+    detail: /* @__PURE__ */ a(j, { children: [
+      e.detail,
+      l,
+      " Send for review to the Actioneer team to help with future runs."
+    ] })
+  };
+}
+const A = b(({ call: e }) => /* @__PURE__ */ a(ne, { children: [
+  /* @__PURE__ */ t(re, { title: e.name, type: `tool-${e.name}`, state: e.state }),
+  /* @__PURE__ */ a(oe, { children: [
+    e.input !== void 0 && /* @__PURE__ */ t(se, { input: e.input }),
+    /* @__PURE__ */ t(
+      ie,
+      {
+        output: e.state === "output-available" ? e.output : void 0,
+        errorText: e.state === "output-error" ? e.error : void 0
+      }
+    )
+  ] })
+] }));
+A.displayName = "AgentTrace.ToolCard";
+const O = b(
+  ({
+    step: e,
+    mainAgent: o,
+    renderCall: s
+  }) => {
+    const l = v(e);
+    return /* @__PURE__ */ a(P, { status: e.status === "error" ? "error" : "complete", children: [
+      /* @__PURE__ */ a(W, { leftIcon: e.icon, endContent: l, children: [
+        /* @__PURE__ */ t("span", { children: e.label }),
+        e.agent && e.agent !== o && /* @__PURE__ */ t("span", { className: "ml-2 text-xs font-normal text-tertiary", children: e.agent })
+      ] }),
+      /* @__PURE__ */ t(q, { children: /* @__PURE__ */ a("div", { className: "-ml-5", style: { "--tree-rail-lead": "18px" }, children: [
+        e.detail != null && /* @__PURE__ */ t("div", { className: "ads-tree-rail pb-3", children: /* @__PURE__ */ t(J, { children: e.detail }) }),
+        e.sources && e.sources.length > 0 && /* @__PURE__ */ t("div", { className: "ads-tree-rail pb-3", children: /* @__PURE__ */ t(Q, { children: e.sources.map((i) => /* @__PURE__ */ t(V, { children: i }, i)) }) }),
+        (e.calls ?? []).map((i, c) => /* @__PURE__ */ t(
+          "div",
+          {
+            className: "ads-tree-branch pb-2 last:pb-0",
+            style: { "--tree-elbow": "23px" },
+            children: s ? s(i) : /* @__PURE__ */ t(A, { call: i })
+          },
+          c
+        ))
+      ] }) })
+    ] });
+  }
+);
+O.displayName = "AgentTrace.StepRow";
+const ue = ({
+  steps: e,
+  mainAgent: o = ae,
+  slowSeconds: s = le,
+  reviewedStepIds: l,
+  onSendForReview: i,
+  slowMessage: c = de,
+  renderCall: h,
+  className: $,
+  ...k
+}) => {
+  var S;
+  const n = e.find((r) => r.status === "active") ?? null, f = e.filter((r) => r.status === "complete" || r.status === "error"), p = new Set(l ?? []), [E, C] = D(/* @__PURE__ */ new Set()), w = _(null);
+  z(() => {
+    const r = (n == null ? void 0 : n.group) ?? null;
+    r == null || r === w.current || (w.current = r, C(new Set(y(e).filter((d) => d !== r))));
+  }, [n == null ? void 0 : n.group, e]);
+  const N = y(f).map((r) => {
+    var d;
+    return {
+      group: r,
+      icon: (d = f.find((u) => u.group === r)) == null ? void 0 : d.groupIcon,
+      steps: f.filter((u) => u.group === r)
+    };
+  }), M = (n == null ? void 0 : n.seconds) ?? 0, I = n != null && M >= s, g = n ? c(n) : null;
+  return /* @__PURE__ */ a("div", { "data-slot": "agent-trace", className: L("w-full", $), ...k, children: [
+    /* @__PURE__ */ t("div", { className: "flex flex-col gap-3", children: N.map(({ group: r, icon: d, steps: u }) => /* @__PURE__ */ a(
+      Z,
+      {
+        open: !E.has(r),
+        onOpenChange: (m) => C((R) => {
+          const T = new Set(R);
+          return m ? T.delete(r) : T.add(r), T;
+        }),
+        children: [
+          /* @__PURE__ */ t(ee, { title: r, icon: d, endContent: ce(u) }),
+          /* @__PURE__ */ t(te, { children: /* @__PURE__ */ t(X, { connector: "tree", children: u.map((m) => /* @__PURE__ */ t(
+            O,
+            {
+              step: m,
+              mainAgent: o,
+              renderCall: h
+            },
+            m.id
+          )) }) })
+        ]
+      },
+      r
+    )) }),
+    n && /* @__PURE__ */ a("div", { className: "mt-3", children: [
+      /* @__PURE__ */ t(
+        Y,
+        {
+          status: "active",
+          open: !0,
+          onOpenChange: () => {
+          },
+          elapsed: v(n) ?? "0:00",
+          sourceCount: ((S = n.sources) == null ? void 0 : S.length) ?? 0,
+          activity: n.label,
+          activityKey: n.id,
+          activityPlacement: "bottom",
+          collapsible: !1,
+          children: /* @__PURE__ */ t("span", {})
+        }
+      ),
+      I && g && /* @__PURE__ */ t(G, { variant: "warning", icon: /* @__PURE__ */ t(F, {}), className: "mt-3", children: /* @__PURE__ */ a("div", { className: "flex flex-wrap items-center justify-between gap-3", children: [
+        /* @__PURE__ */ a("div", { className: "min-w-0", children: [
+          /* @__PURE__ */ a(H, { children: [
+            g.title,
+            " —",
+            " ",
+            /* @__PURE__ */ t("span", { className: "tabular-nums text-tertiary", children: v(n) })
+          ] }),
+          /* @__PURE__ */ t(U, { children: g.detail })
+        ] }),
+        i && /* @__PURE__ */ t(
+          B,
+          {
+            size: "sm",
+            variant: p.has(n.id) ? "ghost" : "secondary",
+            disabled: p.has(n.id),
+            onClick: () => i(n),
+            children: p.has(n.id) ? "Sent" : "Skip and send"
+          }
+        )
+      ] }) })
+    ] }),
+    N.length === 0 && !n && /* @__PURE__ */ t(K, { size: "sm", className: "text-tertiary", children: "No steps yet." })
+  ] });
+};
+ue.displayName = "AgentTrace";
+export {
+  ue as AgentTrace
+};

package/components/ai-elements/chain-of-thought.d.ts

@@ -1,13 +1,23 @@
 import { Badge } from '../badge';
 import { Collapsible, CollapsibleContent, CollapsibleTrigger } from '../collapsible';
 import { ComponentProps, ReactNode } from 'react';
+/**
+ * How steps connect to one another.
+ * - `rail`  — a short vertical segment between icons (the default).
+ * - `tree`  — the Tree connector: a continuous rail with an elbow reaching
+ *             EVERY step, so a nested trace reads as branches of its parent.
+ * - `none`  — no connector; an outer structure carries the hierarchy.
+ */
+export type ChainOfThoughtConnector = "rail" | "tree" | "none";
 /**
  * A step-first reasoning trace. The root is intentionally only a list: each
  * step owns its own disclosure so the trace does not need a redundant global
  * "Chain of Thought" trigger above it.
  */
-export type ChainOfThoughtProps = ComponentProps<"div">;
-export declare const ChainOfThought: import('react').MemoExoticComponent<({ className, role, ...props }: ChainOfThoughtProps) => import("react").JSX.Element>;
+export type ChainOfThoughtProps = ComponentProps<"div"> & {
+    connector?: ChainOfThoughtConnector;
+};
+export declare const ChainOfThought: import('react').MemoExoticComponent<({ className, role, connector, children, ...props }: ChainOfThoughtProps) => import("react").JSX.Element>;
 /**
  * Step lifecycle mirrors the production work-trace statuses: steps stream in
  * as `active`, settle to `complete`, and surface failures as `error` — an
@@ -17,17 +27,27 @@ export type ChainOfThoughtStatus = "complete" | "active" | "pending" | "error";
 export type ChainOfThoughtStepProps = ComponentProps<typeof Collapsible> & {
     status?: ChainOfThoughtStatus;
 };
-export declare const ChainOfThoughtStep: import('react').MemoExoticComponent<({ className, defaultOpen, open: controlledOpen, onOpenChange, status, role, "aria-busy": ariaBusy, ...props }: ChainOfThoughtStepProps) => import("react").JSX.Element>;
+export declare const ChainOfThoughtStep: import('react').MemoExoticComponent<({ className, defaultOpen, open: controlledOpen, onOpenChange, status, role, "aria-busy": ariaBusy, children, ...props }: ChainOfThoughtStepProps) => import("react").JSX.Element>;
 export type ChainOfThoughtTriggerProps = Omit<ComponentProps<typeof CollapsibleTrigger>, "asChild" | "children"> & {
     children: ReactNode;
     /** Semantic icon rendered on the reasoning rail. */
     leftIcon?: ReactNode;
     /** Optional trailing metadata such as elapsed time. */
     endContent?: ReactNode;
-    /** Swap the semantic icon for a disclosure affordance on hover. */
+    /**
+     * Show the disclosure caret at the row's trailing edge, next to
+     * `endContent` — the same anatomy as `TaskTrigger`, so a nested trace reads
+     * consistently at both levels. With the caret on, the leading icon keeps its
+     * meaning instead of being swapped for an affordance.
+     */
+    caret?: boolean;
+    /**
+     * Swap the semantic icon for a disclosure affordance on hover. Ignored when
+     * `caret` is set — one affordance per row.
+     */
     swapIconOnHover?: boolean;
 };
-export declare const ChainOfThoughtTrigger: import('react').MemoExoticComponent<({ className, children, leftIcon, endContent, swapIconOnHover, ...props }: ChainOfThoughtTriggerProps) => import("react").JSX.Element>;
+export declare const ChainOfThoughtTrigger: import('react').MemoExoticComponent<({ className, children, leftIcon, endContent, caret, swapIconOnHover, ...props }: ChainOfThoughtTriggerProps) => import("react").JSX.Element>;
 export type ChainOfThoughtContentProps = ComponentProps<typeof CollapsibleContent>;
 export declare const ChainOfThoughtContent: import('react').MemoExoticComponent<({ className, children, ...props }: ChainOfThoughtContentProps) => import("react").JSX.Element>;
 export type ChainOfThoughtItemProps = ComponentProps<"div">;