@superxd-studio/adptr 0.5.0

package/source/reusable/interactions/feedback.ts

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { InteractionStore, identity, newIdentity } from "./store.js";
+const feedbackSchema = z.strictObject({
+  requestId: identity,
+  responseId: identity,
+  rating: z.enum(["helpful", "unhelpful"]),
+  comment: z.string().max(5000),
+});
+export type FeedbackRequest = z.infer<typeof feedbackSchema>;
+export interface FeedbackAdapter {
+  /** Upsert feedback for responseId and deduplicate retries by requestId. Resolve only after storage acknowledges. */
+  save(
+    request: FeedbackRequest,
+    signal: AbortSignal,
+  ): Promise<{ requestId: string; responseId: string }>;
+}
+export interface FeedbackSnapshot {
+  responseId: string;
+  rating: "helpful" | "unhelpful" | null;
+  comment: string;
+  phase: "editing" | "saving" | "saved" | "error";
+  request?: FeedbackRequest;
+}
+export class FeedbackController extends InteractionStore<FeedbackSnapshot> {
+  constructor(
+    private adapter: FeedbackAdapter,
+    responseId: string,
+    private id: () => string = newIdentity,
+  ) {
+    super({ responseId: identity.parse(responseId), rating: null, comment: "", phase: "editing" });
+  }
+  edit(rating: FeedbackSnapshot["rating"], comment = this.state.comment) {
+    if (
+      this.disposed ||
+      ["saving", "error"].includes(this.state.phase) ||
+      !(rating === null || rating === "helpful" || rating === "unhelpful") ||
+      typeof comment !== "string" ||
+      comment.length > 5000
+    )
+      return false;
+    this.publish({ ...this.state, rating, comment, phase: "editing", request: undefined });
+    return true;
+  }
+  save() {
+    if (this.disposed || !this.state.rating || !["editing", "error"].includes(this.state.phase))
+      return false;
+    const request =
+      this.state.request ??
+      Object.freeze(
+        feedbackSchema.parse({
+          requestId: this.requestIdentity(this.id),
+          responseId: this.state.responseId,
+          rating: this.state.rating,
+          comment: this.state.comment,
+        }),
+      );
+    const { token, signal } = this.request();
+    this.publish({ ...this.state, phase: "saving", request });
+    void (async () => {
+      try {
+        const result = z
+          .strictObject({ requestId: identity, responseId: identity })
+          .parse(await this.adapter.save(request, signal));
+        if (result.requestId !== request.requestId || result.responseId !== request.responseId)
+          throw new Error("Wrong feedback receipt");
+        if (this.current(token)) this.publish({ ...this.state, phase: "saved" });
+      } catch {
+        if (this.current(token)) this.publish({ ...this.state, phase: "error" });
+      }
+    })();
+    return true;
+  }
+}

package/source/reusable/interactions/index.ts

@@ -0,0 +1,11 @@
+export * from "./agent.js";
+export * from "./artifact.js";
+export * from "./feedback.js";
+export * from "./threads.js";
+export * from "./presentation.js";
+export * from "./web.js";
+export { interactionCopy } from "./copy.js";
+export { jsonSchema } from "./store.js";
+
+export { InteractionProvider } from "./context.js";
+export type { InteractionCopy, InteractionCopyOverrides } from "./context.js";

package/source/reusable/interactions/presentation.tsx

@@ -0,0 +1,483 @@
+import { useInteractionCopy } from "./context.js";
+import type { ReactNode } from "react";
+import { Link } from "react-aria-components";
+import { z } from "zod";
+import {
+  Accordion,
+  Badge,
+  Card,
+  Select,
+  CheckboxGroup,
+  Menu,
+  Tabs,
+} from "../../reusable/ui/index.js";
+import type { Choice, MenuCommand } from "../ui/index.js";
+import { Button } from "../../components/button.js";
+import { Callout } from "../../components/callout.js";
+import { Spinner } from "../../components/spinner.js";
+import { CodeBlock } from "../web/message/index.js";
+import type { interactionCopy as copy } from "./copy.js";
+import { jsonSchema, identity, shortText, bodyText, type JsonValue } from "./store.js";
+
+/** Evidence links may navigate only to explicit HTTP(S) destinations, without embedded credentials. */
+export function evidenceUrl(value: unknown): string | undefined {
+  if (typeof value !== "string" || value.length > 2000) return;
+  try {
+    const url = new URL(value);
+    if (["https:", "http:"].includes(url.protocol) && !url.username && !url.password)
+      return url.href;
+  } catch {
+    /* unavailable */
+  }
+}
+const sourceSchema = z.strictObject({
+  id: identity,
+  title: shortText,
+  url: z.string().max(2000).optional(),
+  excerpt: bodyText.optional(),
+  claim: shortText.optional(),
+});
+export type SourceDocument = z.infer<typeof sourceSchema>;
+export function Sources({
+  sources,
+  label,
+}: {
+  sources: readonly SourceDocument[];
+  label?: string;
+}) {
+  const copy = useInteractionCopy();
+  label ??= copy.sources;
+
+  const parsed = z.array(sourceSchema).max(100).safeParse(sources);
+  if (!parsed.success) return <Callout tone="error">{copy.invalid}</Callout>;
+  return (
+    <section aria-label={label} className="min-w-0">
+      <h3 className="mb-3 type-heading text-fg-emphasis">{label}</h3>
+      {!parsed.data.length && <p className="type-body text-fg-subtle">{copy.noSources}</p>}
+      <ol className="flex flex-col gap-4">
+        {parsed.data.map((source, index) => {
+          const href = evidenceUrl(source.url);
+          return (
+            <li
+              key={`${source.id}-${index}`}
+              className="min-w-0 rounded-control border border-line-subtle bg-surface p-4"
+            >
+              <span className="mr-2 font-mono type-caption text-fg-subtle">{index + 1}</span>
+              {href ? (
+                <Link
+                  href={href}
+                  target="_blank"
+                  rel="noopener noreferrer"
+                  aria-label={copy.source(index + 1, source.title)}
+                  className="rounded-cell type-label break-words text-fg-emphasis underline outline-none data-focus-visible:focus-ring"
+                >
+                  {source.title}
+                </Link>
+              ) : (
+                <span className="type-label text-fg-emphasis">
+                  {source.title}
+                  <span className="ml-2 type-caption text-fg-subtle">{copy.unavailable}</span>
+                </span>
+              )}
+              {source.claim && <p className="mt-2 type-body text-fg">{source.claim}</p>}
+              {source.excerpt && (
+                <blockquote className="mt-2 border-l-2 border-line-emphasis pl-3 type-body whitespace-pre-wrap text-fg-subtle">
+                  {source.excerpt}
+                </blockquote>
+              )}
+            </li>
+          );
+        })}
+      </ol>
+    </section>
+  );
+}
+export function Citation({ source, index }: { source: SourceDocument; index: number }) {
+  const copy = useInteractionCopy();
+
+  const href = evidenceUrl(source.url);
+  return href ? (
+    <Link
+      href={href}
+      target="_blank"
+      rel="noopener noreferrer"
+      aria-label={copy.source(index, source.title)}
+      className="rounded-cell font-mono type-caption text-info underline outline-none data-focus-visible:focus-ring"
+    >
+      [{index}]
+    </Link>
+  ) : (
+    <span aria-label={copy.unavailable} className="font-mono type-caption text-fg-subtle">
+      [{index}]
+    </span>
+  );
+}
+export function RetrievalInspection({
+  documents,
+}: {
+  documents: readonly (SourceDocument & { included: boolean })[];
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <Accordion
+      label={copy.retrieval}
+      items={[
+        {
+          id: "context",
+          title: copy.retrieval,
+          content: (
+            <div className="flex flex-col gap-4">
+              {documents.map((document, index) => (
+                <div key={`${document.id}-${index}`}>
+                  <Badge>{document.included ? copy.included : copy.excluded}</Badge>
+                  <Sources
+                    label={document.title}
+                    sources={[
+                      {
+                        id: document.id,
+                        title: document.title,
+                        url: document.url,
+                        excerpt: document.excerpt,
+                        claim: document.claim,
+                      },
+                    ]}
+                  />
+                </div>
+              ))}
+            </div>
+          ),
+        },
+      ]}
+    />
+  );
+}
+export function Reasoning({
+  text,
+  status = "complete",
+  label,
+}: {
+  text: string;
+  status?: "working" | "complete";
+  label?: string;
+}) {
+  const copy = useInteractionCopy();
+  label ??= copy.explanation;
+
+  return (
+    <div className="min-w-0">
+      <div className="flex items-center gap-2 type-caption text-fg-subtle">
+        {status === "working" && <Spinner />}
+        {copy.supplied}
+      </div>
+      <Accordion
+        label={label}
+        items={[
+          {
+            id: "explanation",
+            title: label,
+            content: <p className="type-body break-words whitespace-pre-wrap">{text}</p>,
+          },
+        ]}
+      />
+    </div>
+  );
+}
+export type ToolStatus = keyof typeof copy.toolStates;
+export function ToolCall({
+  title,
+  status,
+  input,
+  output,
+}: {
+  title: string;
+  status: ToolStatus;
+  input: JsonValue;
+  output?: string;
+}) {
+  const copy = useInteractionCopy();
+
+  const parsed = jsonSchema.safeParse(input);
+  if (!parsed.success) return <Callout tone="error">{copy.invalid}</Callout>;
+  return (
+    <Card aria-label={title}>
+      <div className="mb-3 flex flex-wrap items-center justify-between gap-3">
+        <h3 className="type-heading text-fg-emphasis">{title}</h3>
+        <Badge
+          tone={status === "completed" ? "success" : status === "unknown" ? "attention" : "neutral"}
+        >
+          {status === "running" && <Spinner />}
+          {copy.toolStates[status]}
+        </Badge>
+      </div>
+      <Accordion
+        label={copy.tool}
+        items={[
+          {
+            id: "input",
+            title: copy.inputs,
+            content: <CodeBlock code={JSON.stringify(parsed.data, null, 2)} language="json" />,
+          },
+          ...(output === undefined
+            ? []
+            : [
+                {
+                  id: "output",
+                  title: copy.output,
+                  content: <p className="type-body break-words whitespace-pre-wrap">{output}</p>,
+                },
+              ]),
+        ]}
+        allowsMultipleExpanded
+      />
+    </Card>
+  );
+}
+export function Confidence({ claim, explanation }: { claim: string; explanation: string }) {
+  const copy = useInteractionCopy();
+
+  return (
+    <Callout tone="attention" title={copy.checkClaim}>
+      <p>{claim}</p>
+      <p className="mt-2">{explanation}</p>
+    </Callout>
+  );
+}
+export function Guardrail({
+  reason,
+  alternatives,
+  onChoose,
+}: {
+  reason: string;
+  alternatives: readonly { id: string; label: string }[];
+  onChoose: (id: string) => void;
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <Callout
+      tone="attention"
+      title={copy.blocked}
+      actions={alternatives.map((item) => (
+        <Button key={item.id} size="sm" onPress={() => onChoose(item.id)}>
+          {item.label}
+        </Button>
+      ))}
+    >
+      {reason}
+    </Callout>
+  );
+}
+export function ConnectionStatus({
+  state,
+  onReconnect,
+}: {
+  state: "connected" | "reconnecting" | "disconnected";
+  onReconnect?: () => void;
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <Callout
+      tone={state === "connected" ? "neutral" : "attention"}
+      title={copy.connection[state]}
+      actions={
+        state === "disconnected" && onReconnect ? (
+          <Button size="sm" onPress={onReconnect}>
+            {copy.reconnect}
+          </Button>
+        ) : undefined
+      }
+    >
+      {state !== "connected" && copy.disconnected}
+    </Callout>
+  );
+}
+export function ComposerTools({
+  models,
+  model,
+  onModelChange,
+  contexts = [],
+  selectedContext = [],
+  onContextChange,
+  commands = [],
+  onCommand,
+}: {
+  models: readonly Choice[];
+  model: string;
+  onModelChange: (id: string) => void;
+  contexts?: readonly Choice[];
+  selectedContext?: readonly string[];
+  onContextChange?: (ids: string[]) => void;
+  commands?: readonly MenuCommand[];
+  onCommand?: (id: string) => void;
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <div className="flex min-w-0 flex-col gap-4">
+      <Select
+        label={copy.model}
+        options={models}
+        selectedKey={model}
+        onSelectionChange={(key) => {
+          if (key !== null) onModelChange(String(key));
+        }}
+      />
+      {contexts.length > 0 && onContextChange && (
+        <CheckboxGroup
+          label={copy.context}
+          options={contexts}
+          value={[...selectedContext]}
+          onChange={onContextChange}
+        />
+      )}{" "}
+      {commands.length > 0 && onCommand && (
+        <Menu label={copy.commands} items={commands} onAction={onCommand} />
+      )}
+    </div>
+  );
+}
+export interface Quote {
+  text: string;
+  sourceId: string;
+  sourceTitle: string;
+}
+export function QuotedExcerpt({
+  quote,
+  onReply,
+}: {
+  quote: Quote;
+  onReply?: (quote: Quote) => void;
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <Card aria-label={copy.quote}>
+      <blockquote className="border-l-2 border-line-emphasis pl-3 type-body break-words whitespace-pre-wrap">
+        {quote.text}
+      </blockquote>
+      <p className="mt-3 type-caption text-fg-subtle">{quote.sourceTitle}</p>
+      {onReply && (
+        <Button size="sm" className="mt-4" onPress={() => onReply({ ...quote })}>
+          {copy.reply}
+        </Button>
+      )}
+    </Card>
+  );
+}
+export function ExecutionInspector({
+  code,
+  files,
+  output,
+  tests,
+}: {
+  code?: string;
+  files?: readonly string[];
+  output?: string;
+  tests?: readonly { name: string; passed: boolean }[];
+}) {
+  const copy = useInteractionCopy();
+
+  const items = [
+    ...(code === undefined
+      ? []
+      : [{ id: "code", label: copy.code, content: <CodeBlock code={code} /> }]),
+    ...(files === undefined
+      ? []
+      : [
+          {
+            id: "files",
+            label: copy.files,
+            content: (
+              <ul className="flex flex-col gap-2 font-mono type-caption">
+                {files.map((file, index) => (
+                  <li key={index} className="break-words">
+                    {file}
+                  </li>
+                ))}
+              </ul>
+            ),
+          },
+        ]),
+    ...(output === undefined
+      ? []
+      : [
+          {
+            id: "output",
+            label: copy.output,
+            content: <pre className="type-caption break-words whitespace-pre-wrap">{output}</pre>,
+          },
+        ]),
+    ...(tests === undefined
+      ? []
+      : [
+          {
+            id: "tests",
+            label: copy.checks,
+            content: (
+              <ul className="flex flex-col gap-3">
+                {tests.map((test, index) => (
+                  <li key={index} className="flex flex-wrap gap-2">
+                    <Badge tone={test.passed ? "success" : "error"}>
+                      {test.passed ? copy.passed : copy.failed}
+                    </Badge>
+                    <span className="type-body">{test.name}</span>
+                  </li>
+                ))}
+              </ul>
+            ),
+          },
+        ]),
+  ];
+  return <Tabs label={copy.tool} items={items} />;
+}
+export function Observability({
+  measurements,
+}: {
+  measurements: readonly { label: string; value?: string | number; unit?: string }[];
+}) {
+  const copy = useInteractionCopy();
+
+  return (
+    <section aria-label={copy.trace}>
+      <h3 className="mb-3 type-heading text-fg-emphasis">{copy.trace}</h3>
+      <dl className="grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-2 type-body">
+        {measurements.map((measurement, index) => (
+          <div key={index} className="contents">
+            <dt className="text-fg-subtle">{measurement.label}</dt>
+            <dd className="text-right break-words numeric">
+              {measurement.value === undefined ? (
+                copy.notReported
+              ) : (
+                <>
+                  {measurement.value}
+                  {measurement.unit && ` ${measurement.unit}`}
+                </>
+              )}
+            </dd>
+          </div>
+        ))}
+      </dl>
+    </section>
+  );
+}
+export function AgentStatus({
+  label,
+  status,
+  children,
+}: {
+  label: string;
+  status: string;
+  children?: ReactNode;
+}) {
+  return (
+    <div className="flex min-w-0 flex-col gap-2">
+      <div className="flex flex-wrap items-center justify-between gap-3">
+        <h3 className="type-heading text-fg-emphasis">{label}</h3>
+        <Badge>{status}</Badge>
+      </div>
+      {children}
+    </div>
+  );
+}

package/source/reusable/interactions/store.ts

@@ -0,0 +1,74 @@
+import { z } from "zod";
+export type JsonValue =
+  string | number | boolean | null | { [key: string]: JsonValue } | JsonValue[];
+function isJson(value: unknown, depth = 0, budget = { nodes: 0 }): value is JsonValue {
+  if (++budget.nodes > 10_000 || depth > 20) return false;
+  if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+  if (typeof value === "number") return Number.isFinite(value);
+  if (Array.isArray(value)) return value.every((item) => isJson(item, depth + 1, budget));
+  if (typeof value === "object" && Object.getPrototypeOf(value) === Object.prototype)
+    return Object.entries(value).every(
+      ([key, item]) => key.length <= 200 && isJson(item, depth + 1, budget),
+    );
+  return false;
+}
+export const jsonSchema = z.custom<JsonValue>(
+  (value) => isJson(value) && JSON.stringify(value).length <= 100_000,
+);
+export const identity = z
+  .string()
+  .min(1)
+  .max(200)
+  .refine((value) => value === value.trim(), "Identity must be canonical");
+export const shortText = z.string().trim().min(1).max(2000);
+export const bodyText = z.string().max(100_000);
+export const newIdentity = () => crypto.randomUUID();
+function freeze<T>(value: T): T {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(freeze);
+    Object.freeze(value);
+  }
+  return value;
+}
+/** Small external store shared by the concrete interaction owners. No execution is hidden here. */
+export class InteractionStore<S> {
+  protected state: S;
+  protected disposed = false;
+  protected generation = 0;
+  protected abort?: AbortController;
+  private usedIds = new Set<string>();
+  protected requestIdentity(create: () => string = newIdentity) {
+    const id = identity.parse(create());
+    if (this.usedIds.has(id)) throw new Error("Request identity must be unique");
+    this.usedIds.add(id);
+    return id;
+  }
+  private listeners = new Set<() => void>();
+  constructor(initial: S) {
+    this.state = freeze(structuredClone(initial));
+  }
+  getSnapshot = (): S => this.state;
+  subscribe = (listener: () => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  protected publish(state: S) {
+    if (this.disposed) return;
+    this.state = freeze(structuredClone(state));
+    this.listeners.forEach((listener) => listener());
+  }
+  protected request() {
+    this.abort?.abort();
+    this.abort = new AbortController();
+    return { token: ++this.generation, signal: this.abort.signal };
+  }
+  protected current(token: number) {
+    return !this.disposed && token === this.generation;
+  }
+  dispose() {
+    this.disposed = true;
+    ++this.generation;
+    this.abort?.abort();
+    this.listeners.clear();
+  }
+}