@echothink-ui/agent 0.1.0

package/src/components/AgentApprovalGate.tsx

@@ -0,0 +1,165 @@
+import * as React from "react";
+import clsx from "clsx";
+import { Button, InlineNotification, Surface, Textarea } from "@echothink-ui/core";
+import { ExternalLinkIcon } from "@echothink-ui/icons";
+import type { SurfaceComponentProps } from "@echothink-ui/core";
+import type { AgentApprovalAction, AgentCitation } from "../types";
+import { riskSeverity } from "./utils";
+
+export interface AgentApprovalGateProps extends Omit<SurfaceComponentProps, "children"> {
+  action: AgentApprovalAction;
+  evidence?: AgentCitation[];
+  onApprove?: (reason?: string) => void;
+  onReject?: (reason?: string) => void;
+  state?: "idle" | "pending" | "approved" | "rejected";
+}
+
+export function AgentApprovalGate({
+  action,
+  evidence = [],
+  onApprove,
+  onReject,
+  state = "idle",
+  title = "Approval required",
+  className,
+  ...props
+}: AgentApprovalGateProps) {
+  const [reason, setReason] = React.useState("");
+  const severity = riskSeverity(action.riskLevel);
+  const locked = state === "pending" || state === "approved" || state === "rejected";
+  const stateLabel = approvalStateLabel(state);
+
+  return (
+    <Surface
+      {...props}
+      className={clsx("eth-agent-approval-gate", `eth-agent-approval-gate--${state}`, className)}
+      data-eth-component="AgentApprovalGate"
+      severity={severity}
+      status={approvalStatus(state)}
+      title={title}
+      subtitle={action.label}
+    >
+      <div className="eth-agent-approval-gate__layout">
+        <InlineNotification
+          severity={severity}
+          title={`${riskLabel(action.riskLevel)} risk action`}
+        >
+          {action.description}
+        </InlineNotification>
+
+        <dl className="eth-agent-approval-gate__summary" aria-label="Approval action details">
+          <div>
+            <dt>Action</dt>
+            <dd>{action.id}</dd>
+          </div>
+          <div>
+            <dt>Risk</dt>
+            <dd>{riskLabel(action.riskLevel)}</dd>
+          </div>
+          <div>
+            <dt>Status</dt>
+            <dd>{stateLabel}</dd>
+          </div>
+        </dl>
+
+        {evidence.length ? (
+          <section className="eth-agent-approval-gate__evidence">
+            <div className="eth-agent-approval-gate__section-header">
+              <h3>Evidence</h3>
+              <span>
+                {evidence.length} reference{evidence.length === 1 ? "" : "s"}
+              </span>
+            </div>
+            <div className="eth-agent-approval-gate__evidence-list">
+              {evidence.map((item) => (
+                <EvidenceItem key={item.id} item={item} />
+              ))}
+            </div>
+          </section>
+        ) : null}
+
+        <Textarea
+          className="eth-agent-approval-gate__reason"
+          aria-label="Approval reason"
+          disabled={locked}
+          labelText="Approval rationale"
+          placeholder="Optional reason"
+          rows={2}
+          value={reason}
+          onChange={(event) => setReason(event.currentTarget.value)}
+        />
+
+        <div className="eth-agent-approval-gate__actions">
+          <Button
+            density="default"
+            intent="success"
+            loading={state === "pending"}
+            disabled={locked}
+            onClick={() => onApprove?.(reason || undefined)}
+          >
+            {state === "approved" ? "Approved" : "Approve"}
+          </Button>
+          <Button
+            density="default"
+            intent="danger"
+            disabled={locked}
+            onClick={() => onReject?.(reason || undefined)}
+          >
+            {state === "rejected" ? "Rejected" : "Reject"}
+          </Button>
+        </div>
+      </div>
+    </Surface>
+  );
+}
+
+function EvidenceItem({ item }: { item: AgentCitation }) {
+  const content = (
+    <>
+      <span className="eth-agent-approval-gate__evidence-copy">
+        <span className="eth-agent-approval-gate__evidence-label">{item.label}</span>
+        {item.description ? (
+          <span className="eth-agent-approval-gate__evidence-description">{item.description}</span>
+        ) : null}
+      </span>
+      {item.meta ? (
+        <span className="eth-agent-approval-gate__evidence-meta">{item.meta}</span>
+      ) : null}
+      {item.href ? (
+        <ExternalLinkIcon className="eth-agent-approval-gate__evidence-icon" size={16} />
+      ) : null}
+    </>
+  );
+
+  if (item.href) {
+    return (
+      <a
+        className="eth-agent-approval-gate__evidence-item eth-agent-approval-gate__evidence-item--link"
+        href={item.href}
+      >
+        {content}
+      </a>
+    );
+  }
+
+  return <div className="eth-agent-approval-gate__evidence-item">{content}</div>;
+}
+
+function riskLabel(riskLevel: AgentApprovalAction["riskLevel"]) {
+  if (!riskLevel) return "Low";
+  return riskLevel.charAt(0).toUpperCase() + riskLevel.slice(1);
+}
+
+function approvalStateLabel(state: AgentApprovalGateProps["state"]) {
+  if (state === "pending") return "Submitting";
+  if (state === "approved") return "Approved";
+  if (state === "rejected") return "Rejected";
+  return "Awaiting decision";
+}
+
+function approvalStatus(state: AgentApprovalGateProps["state"]) {
+  if (state === "pending") return "running";
+  if (state === "approved") return "completed";
+  if (state === "rejected") return "blocked";
+  return "approval-required";
+}

package/src/components/AgentContextViewer.tsx

@@ -0,0 +1,161 @@
+import * as React from "react";
+import clsx from "clsx";
+import { Badge, EmptyState, Surface } from "@echothink-ui/core";
+import {
+  AgentRunningIcon,
+  ChevronRightIcon,
+  DocumentIcon,
+  ExternalLinkIcon,
+  MessageIcon,
+  SearchIcon,
+  type EthIconProps
+} from "@echothink-ui/icons";
+import type { SurfaceComponentProps } from "@echothink-ui/core";
+import type { AgentContextSource } from "../types";
+
+export interface AgentContextViewerProps extends Omit<
+  SurfaceComponentProps,
+  "children" | "onSelect"
+> {
+  sources: AgentContextSource[];
+  onSelect?: (source: AgentContextSource) => void;
+}
+
+export function AgentContextViewer({
+  sources,
+  onSelect,
+  title = "Context sources",
+  className,
+  ...props
+}: AgentContextViewerProps) {
+  const sourceListLabel = typeof title === "string" ? title : "Context sources";
+  const sortedSources = React.useMemo(
+    () => [...sources].sort((a, b) => (b.relevance ?? -1) - (a.relevance ?? -1)),
+    [sources]
+  );
+
+  return (
+    <Surface
+      {...props}
+      className={clsx("eth-agent-context-viewer", className)}
+      data-eth-component="AgentContextViewer"
+      title={title}
+    >
+      {!sortedSources.length ? (
+        <EmptyState title="No context sources" />
+      ) : (
+        <ul className="eth-agent-context-viewer__sources" aria-label={sourceListLabel}>
+          {sortedSources.map((source) => {
+            const SourceIcon = sourceIcon(source.type);
+            const relevance = source.relevance == null ? null : formatRelevance(source.relevance);
+            const relevanceValue =
+              source.relevance == null ? null : normalizedRelevance(source.relevance);
+            const isInteractive = Boolean(source.href || onSelect);
+
+            const content = (
+              <>
+                <span className="eth-agent-context-viewer__kind-icon" aria-hidden="true">
+                  <SourceIcon size={18} />
+                </span>
+                <span className="eth-agent-context-viewer__main">
+                  <span className="eth-agent-context-viewer__topline">
+                    <strong className="eth-agent-context-viewer__label">{source.label}</strong>
+                    <Badge severity="neutral">{typeLabel(source.type)}</Badge>
+                  </span>
+                  {source.excerpt ? (
+                    <span className="eth-agent-context-viewer__excerpt">{source.excerpt}</span>
+                  ) : null}
+                </span>
+                <span className="eth-agent-context-viewer__aside">
+                  {relevance != null && relevanceValue != null ? (
+                    <span
+                      className="eth-agent-context-viewer__relevance"
+                      aria-label={`Relevance ${relevance}`}
+                    >
+                      <span className="eth-agent-context-viewer__relevance-value">
+                        Relevance {relevance}
+                      </span>
+                      <span
+                        className="eth-agent-context-viewer__relevance-meter"
+                        aria-hidden="true"
+                      >
+                        <span style={{ inlineSize: `${relevanceValue}%` }} />
+                      </span>
+                    </span>
+                  ) : (
+                    <span className="eth-agent-context-viewer__unranked">Unranked</span>
+                  )}
+                  {source.href ? (
+                    <ExternalLinkIcon className="eth-agent-context-viewer__indicator" size={16} />
+                  ) : isInteractive ? (
+                    <ChevronRightIcon className="eth-agent-context-viewer__indicator" size={16} />
+                  ) : null}
+                </span>
+              </>
+            );
+
+            return (
+              <li key={source.id}>
+                {source.href ? (
+                  <a
+                    className={clsx(
+                      "eth-agent-context-viewer__source",
+                      "eth-agent-context-viewer__source--interactive"
+                    )}
+                    href={source.href}
+                    onClick={() => onSelect?.(source)}
+                  >
+                    {content}
+                  </a>
+                ) : onSelect ? (
+                  <button
+                    type="button"
+                    className={clsx(
+                      "eth-agent-context-viewer__source",
+                      "eth-agent-context-viewer__source--interactive"
+                    )}
+                    onClick={() => onSelect(source)}
+                  >
+                    {content}
+                  </button>
+                ) : (
+                  <article className="eth-agent-context-viewer__source">{content}</article>
+                )}
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </Surface>
+  );
+}
+
+function sourceIcon(type: AgentContextSource["type"]): React.ComponentType<EthIconProps> {
+  switch (type) {
+    case "document":
+      return DocumentIcon;
+    case "query":
+      return SearchIcon;
+    case "tool-result":
+      return AgentRunningIcon;
+    case "message":
+    default:
+      return MessageIcon;
+  }
+}
+
+function typeLabel(type: AgentContextSource["type"]) {
+  return type
+    .split("-")
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join(" ");
+}
+
+function formatRelevance(relevance: number) {
+  return `${normalizedRelevance(relevance)}%`;
+}
+
+function normalizedRelevance(relevance: number) {
+  const normalized = relevance <= 1 ? relevance * 100 : relevance;
+  return Math.min(100, Math.max(0, Math.round(normalized)));
+}

package/src/components/AgentGeneratedArtifactPanel.tsx

@@ -0,0 +1,224 @@
+import * as React from "react";
+import clsx from "clsx";
+import { Drawer, EmptyState, LinkButton, Surface } from "@echothink-ui/core";
+import type { SurfaceComponentProps } from "@echothink-ui/core";
+import type { AgentGeneratedArtifact } from "../types";
+import { formatDateTime } from "./utils";
+
+export interface AgentGeneratedArtifactPanelProps extends Omit<
+  SurfaceComponentProps,
+  "children" | "onSelect"
+> {
+  artifacts: AgentGeneratedArtifact[];
+  onSelect?: (artifact: AgentGeneratedArtifact) => void;
+  selectedId?: string;
+}
+
+export function AgentGeneratedArtifactPanel({
+  artifacts,
+  onSelect,
+  selectedId,
+  density,
+  title = "Generated artifacts",
+  className,
+  ...props
+}: AgentGeneratedArtifactPanelProps) {
+  const [internalSelectedId, setInternalSelectedId] = React.useState<string | undefined>(
+    selectedId ?? artifacts[0]?.id
+  );
+  const [previewOpen, setPreviewOpen] = React.useState(false);
+  const selectedArtifact =
+    artifacts.find((artifact) => artifact.id === (selectedId ?? internalSelectedId)) ??
+    artifacts[0];
+  const compact = density === "compact";
+
+  const selectArtifact = (artifact: AgentGeneratedArtifact) => {
+    setInternalSelectedId(artifact.id);
+    setPreviewOpen(true);
+    onSelect?.(artifact);
+  };
+
+  return (
+    <>
+      <Surface
+        {...props}
+        density={density}
+        className={clsx("eth-agent-generated-artifact-panel", className)}
+        data-eth-component="AgentGeneratedArtifactPanel"
+        title={title}
+      >
+        {!artifacts.length ? (
+          <EmptyState title="No artifacts generated" />
+        ) : (
+          <div
+            className="eth-agent-generated-artifact-panel__layout"
+            style={{
+              gridTemplateColumns: compact ? "1fr" : "minmax(220px, 320px) minmax(0, 1fr)"
+            }}
+          >
+            <ArtifactList
+              artifacts={artifacts}
+              selectedId={selectedArtifact?.id}
+              onSelect={selectArtifact}
+            />
+            {!compact ? <ArtifactPreview artifact={selectedArtifact} /> : null}
+          </div>
+        )}
+      </Surface>
+      {compact ? (
+        <Drawer
+          open={previewOpen && Boolean(selectedArtifact)}
+          title={selectedArtifact?.label ?? "Artifact preview"}
+          onClose={() => setPreviewOpen(false)}
+        >
+          <ArtifactPreview artifact={selectedArtifact} />
+        </Drawer>
+      ) : null}
+    </>
+  );
+}
+
+function ArtifactList({
+  artifacts,
+  selectedId,
+  onSelect
+}: {
+  artifacts: AgentGeneratedArtifact[];
+  selectedId?: string;
+  onSelect: (artifact: AgentGeneratedArtifact) => void;
+}) {
+  return (
+    <div
+      className="eth-agent-generated-artifact-panel__list"
+      role="group"
+      aria-label="Generated artifacts"
+    >
+      {artifacts.map((artifact) => {
+        const selected = selectedId === artifact.id;
+
+        return (
+          <button
+            key={artifact.id}
+            type="button"
+            aria-pressed={selected}
+            className={clsx(
+              "eth-agent-generated-artifact-panel__item",
+              selected && "eth-agent-generated-artifact-panel__item--selected"
+            )}
+            onClick={() => onSelect(artifact)}
+          >
+            <span className="eth-agent-generated-artifact-panel__item-topline">
+              <span className="eth-agent-generated-artifact-panel__item-title">
+                {artifact.label}
+              </span>
+              <span className="eth-agent-generated-artifact-panel__kind">
+                {artifactKindLabel(artifact.kind)}
+              </span>
+            </span>
+            <span className="eth-agent-generated-artifact-panel__item-meta">
+              {artifactMeta(artifact).join(" · ")}
+            </span>
+            <span className="eth-agent-generated-artifact-panel__item-status">
+              {artifactPreviewStatus(artifact)}
+            </span>
+          </button>
+        );
+      })}
+    </div>
+  );
+}
+
+function ArtifactPreview({ artifact }: { artifact?: AgentGeneratedArtifact }) {
+  const headingId = React.useId();
+  if (!artifact) return <EmptyState title="Select an artifact" />;
+
+  return (
+    <section className="eth-agent-generated-artifact-panel__preview" aria-labelledby={headingId}>
+      <header className="eth-agent-generated-artifact-panel__preview-header">
+        <div className="eth-agent-generated-artifact-panel__preview-heading">
+          <h3 id={headingId}>{artifact.label}</h3>
+          <div className="eth-agent-generated-artifact-panel__preview-meta">
+            {artifactMeta(artifact).map((item) => (
+              <span key={item}>{item}</span>
+            ))}
+            {artifact.mimeType ? <span>{artifact.mimeType}</span> : null}
+          </div>
+        </div>
+        {artifact.href ? (
+          <LinkButton href={artifact.href} density="compact" intent="secondary">
+            Open
+          </LinkButton>
+        ) : null}
+      </header>
+
+      <div className="eth-agent-generated-artifact-panel__preview-body">
+        <ArtifactPreviewBody artifact={artifact} />
+      </div>
+    </section>
+  );
+}
+
+function ArtifactPreviewBody({ artifact }: { artifact: AgentGeneratedArtifact }) {
+  const content = artifact.content?.trim();
+
+  if (artifact.kind === "image" && artifact.previewUrl) {
+    return <img alt={artifact.label} src={artifact.previewUrl} />;
+  }
+
+  if (artifact.kind === "code" && content) {
+    return (
+      <pre>
+        <code>{content}</code>
+      </pre>
+    );
+  }
+
+  if (artifact.previewUrl) {
+    return <iframe title={artifact.label} src={artifact.previewUrl} />;
+  }
+
+  if (content) {
+    return <div className="eth-agent-generated-artifact-panel__text-preview">{content}</div>;
+  }
+
+  return (
+    <div className="eth-agent-generated-artifact-panel__empty-preview" role="status">
+      <p className="eth-agent-generated-artifact-panel__empty-title">Preview unavailable</p>
+      <p className="eth-agent-generated-artifact-panel__empty-description">
+        {artifact.href
+          ? "Open the artifact to inspect the generated output."
+          : "Artifact saved without an inline preview."}
+      </p>
+    </div>
+  );
+}
+
+function artifactMeta(artifact: AgentGeneratedArtifact) {
+  return [artifact.size, formatDateTime(artifact.createdAt)].filter((item): item is string =>
+    Boolean(item)
+  );
+}
+
+function artifactKindLabel(kind: AgentGeneratedArtifact["kind"]) {
+  switch (kind) {
+    case "chart":
+      return "Chart";
+    case "code":
+      return "Code";
+    case "doc":
+      return "Doc";
+    case "file":
+      return "File";
+    case "image":
+      return "Image";
+  }
+}
+
+function artifactPreviewStatus(artifact: AgentGeneratedArtifact) {
+  if (artifact.kind === "image" && artifact.previewUrl) return "Inline image preview";
+  if (artifact.kind === "code" && artifact.content?.trim()) return "Inline code preview";
+  if (artifact.previewUrl) return "Embedded preview";
+  if (artifact.content?.trim()) return "Inline text preview";
+  if (artifact.href) return "Open externally";
+  return "No inline preview";
+}

package/src/components/AgentHandoffPanel.tsx

@@ -0,0 +1,154 @@
+import * as React from "react";
+import clsx from "clsx";
+import {
+  Badge,
+  Button,
+  EmptyState,
+  FormField,
+  StatusDot,
+  Surface,
+  Textarea
+} from "@echothink-ui/core";
+import type { SurfaceComponentProps } from "@echothink-ui/core";
+import type { AgentHandoffTarget } from "../types";
+
+export interface AgentHandoffPanelProps
+  extends Omit<SurfaceComponentProps, "children" | "onChange" | "onSubmit"> {
+  itemRef?: string;
+  agentRef?: string;
+  assigneeOptions?: AgentHandoffTarget[];
+  selectedAssigneeId?: string;
+  reason?: string;
+  reasonSchema?: { label?: string; placeholder?: string; required?: boolean };
+  disabled?: boolean;
+  onAssigneeChange?: (id: string) => void;
+  onReasonChange?: (reason: string) => void;
+  onSubmit?: (handoff: { assigneeId?: string; reason: string }) => void;
+}
+
+export function AgentHandoffPanel({
+  itemRef,
+  agentRef,
+  assigneeOptions = [],
+  selectedAssigneeId,
+  reason,
+  reasonSchema,
+  disabled,
+  onAssigneeChange,
+  onReasonChange,
+  onSubmit,
+  title = "Agent handoff",
+  className,
+  ...props
+}: AgentHandoffPanelProps) {
+  const [internalAssigneeId, setInternalAssigneeId] = React.useState(selectedAssigneeId);
+  const [internalReason, setInternalReason] = React.useState(reason ?? "");
+  const assigneeId = selectedAssigneeId ?? internalAssigneeId;
+  const handoffReason = reason ?? internalReason;
+  const reasonRequired = reasonSchema?.required ?? true;
+  const canSubmit = Boolean(assigneeId) && (!reasonRequired || Boolean(handoffReason.trim()));
+
+  const selectAssignee = (id: string) => {
+    setInternalAssigneeId(id);
+    onAssigneeChange?.(id);
+  };
+
+  const changeReason = (value: string) => {
+    setInternalReason(value);
+    onReasonChange?.(value);
+  };
+  const reasonId = React.useId();
+
+  return (
+    <Surface
+      {...props}
+      className={clsx("eth-agent-handoff-panel", className)}
+      data-eth-component="AgentHandoffPanel"
+      title={title}
+      subtitle={[agentRef, itemRef].filter(Boolean).join(" · ") || undefined}
+    >
+      <div className="eth-agent-handoff-panel__body">
+        {!assigneeOptions.length ? (
+          <EmptyState title="No handoff targets" />
+        ) : (
+          <div
+            className="eth-agent-handoff-panel__target-list"
+            role="listbox"
+            aria-label="Handoff targets"
+          >
+            {assigneeOptions.map((target) => (
+              <button
+                key={target.id}
+                type="button"
+                role="option"
+                aria-selected={assigneeId === target.id}
+                className={clsx(
+                  "eth-agent-handoff-panel__target",
+                  assigneeId === target.id && "eth-agent-handoff-panel__target--selected"
+                )}
+                disabled={disabled}
+                onClick={() => selectAssignee(target.id)}
+              >
+                <span className="eth-agent-handoff-panel__target-main">
+                  <span className="eth-agent-handoff-panel__target-copy">
+                    <strong className="eth-agent-handoff-panel__target-label">
+                      {target.label}
+                    </strong>
+                    {target.description ? (
+                      <span className="eth-agent-handoff-panel__target-description">
+                        {target.description}
+                      </span>
+                    ) : null}
+                  </span>
+                  <span className="eth-agent-handoff-panel__target-meta">
+                    <Badge severity="neutral">{target.type}</Badge>
+                    {target.status ? (
+                      <StatusDot
+                        status={target.status}
+                        label={formatHandoffStatus(target.status)}
+                      />
+                    ) : null}
+                  </span>
+                </span>
+              </button>
+            ))}
+          </div>
+        )}
+
+        <FormField
+          id={reasonId}
+          label={reasonSchema?.label ?? "Handoff reason"}
+          required={reasonRequired}
+        >
+          <Textarea
+            className="eth-agent-handoff-panel__reason"
+            disabled={disabled}
+            placeholder={reasonSchema?.placeholder ?? "Explain what the next owner should do."}
+            required={reasonRequired}
+            rows={3}
+            value={handoffReason}
+            onChange={(event) => changeReason(event.currentTarget.value)}
+          />
+        </FormField>
+
+        <div className="eth-agent-handoff-panel__actions">
+          <Button
+            disabled={disabled || !canSubmit}
+            onClick={() => onSubmit?.({ assigneeId, reason: handoffReason })}
+          >
+            Handoff
+          </Button>
+        </div>
+      </div>
+    </Surface>
+  );
+}
+
+function formatHandoffStatus(status: AgentHandoffTarget["status"]) {
+  return status
+    ? status
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ")
+    : undefined;
+}