@superxd-studio/adptr 0.5.0

package/source/reusable/core/index.ts

@@ -0,0 +1,417 @@
+/** Public, platform-neutral contract. No browser, React or runtime-vendor types. */
+export { AttachmentController } from "./attachments.js";
+export type {
+  AttachmentItem,
+  AttachmentIssue,
+  AttachmentSnapshot,
+  UploadAdapter,
+  UploadPolicy,
+  UploadSource,
+} from "./attachments.js";
+export type ChatStatus =
+  "idle" | "waiting" | "streaming" | "complete" | "cancelled" | "error" | "interrupted";
+export interface ChatMessage {
+  readonly id: string;
+  readonly role: "user" | "assistant";
+  readonly text: string;
+  readonly files?: readonly ChatFile[];
+  readonly metadata?: Readonly<Record<string, unknown>>;
+}
+export interface ChatCapabilities {
+  readonly send: boolean;
+  readonly cancel: boolean;
+  /** Restart a response, not continuation of an interrupted stream. */
+  readonly retry: boolean;
+  readonly attachments?: boolean;
+  /** Host explicitly permits replaying a question; this does not undo server work. */
+  readonly edit?: boolean;
+  readonly regenerate?: boolean;
+  readonly branches?: boolean;
+}
+export interface ChatBranch {
+  readonly index: number;
+  readonly count: number;
+}
+/** A verified reference from the consumer's upload service, never a browser File. */
+export interface ChatFile {
+  readonly id: string;
+  readonly name: string;
+  readonly mediaType: string;
+  readonly size: number;
+  readonly url: string;
+}
+export interface ChatSnapshot {
+  readonly messages: readonly ChatMessage[];
+  readonly status: ChatStatus;
+  readonly capabilities: ChatCapabilities;
+  readonly branches?: Readonly<Record<string, ChatBranch>>;
+}
+export interface ChatRequest {
+  readonly requestId: string;
+  readonly messages: readonly ChatMessage[];
+}
+export type ChatEvent =
+  | { type: "text"; text: string }
+  | { type: "replace-text"; text: string }
+  | { type: "metadata"; metadata: Readonly<Record<string, unknown>> }
+  | { type: "finish" }
+  | { type: "error" };
+export interface ChatAdapter {
+  readonly capabilities: ChatCapabilities;
+  run(request: ChatRequest, signal: AbortSignal): AsyncIterable<ChatEvent>;
+}
+export interface ChatActions {
+  send(text: string, files?: readonly ChatFile[]): boolean;
+  cancel(): void;
+  retry(): boolean;
+  edit?(messageId: string, text: string): boolean;
+  regenerate?(messageId: string): boolean;
+  selectBranch?(messageId: string, direction: "previous" | "next"): boolean;
+}
+
+export class ChatInterrupted extends Error {
+  constructor() {
+    super("The stream ended before its finish event.");
+  }
+}
+
+export function parseChatFile(value: unknown): ChatFile {
+  if (typeof value !== "object" || value === null) throw new Error("Invalid file");
+  const file = value as Record<string, unknown>;
+  if (
+    typeof file.id !== "string" ||
+    !/^[\w-]{1,100}$/.test(file.id) ||
+    typeof file.name !== "string" ||
+    !file.name.trim() ||
+    file.name.length > 255 ||
+    typeof file.mediaType !== "string" ||
+    !/^[\w.+-]+\/[\w.+-]+$/.test(file.mediaType) ||
+    typeof file.size !== "number" ||
+    !Number.isSafeInteger(file.size) ||
+    file.size < 1 ||
+    file.size > 10_000_000 ||
+    typeof file.url !== "string" ||
+    file.url.length > 2000
+  )
+    throw new Error("Invalid file");
+  const url = new URL(file.url);
+  if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+    throw new Error("Invalid file URL");
+  return {
+    id: file.id,
+    name: file.name,
+    mediaType: file.mediaType,
+    size: file.size,
+    url: file.url,
+  };
+}
+
+/** Validates the small wire protocol. Provider/server errors never become UI copy. */
+export function parseChatEvent(value: unknown): ChatEvent {
+  if (typeof value !== "object" || value === null || !("type" in value))
+    throw new Error("Invalid chat event");
+  if (
+    (value.type === "text" || value.type === "replace-text") &&
+    "text" in value &&
+    typeof value.text === "string" &&
+    value.text.length <= 100_000
+  )
+    return { type: value.type, text: value.text };
+  if (
+    value.type === "metadata" &&
+    "metadata" in value &&
+    typeof value.metadata === "object" &&
+    value.metadata !== null &&
+    !Array.isArray(value.metadata) &&
+    JSON.stringify(value.metadata).length <= 200_000
+  )
+    return { type: "metadata", metadata: value.metadata as Record<string, unknown> };
+  if (value.type === "finish" || value.type === "error") return { type: value.type };
+  throw new Error("Unsupported chat event");
+}
+
+export function parseChatRequest(value: unknown): ChatRequest {
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    !("requestId" in value) ||
+    typeof value.requestId !== "string" ||
+    !/^[\w-]{1,100}$/.test(value.requestId) ||
+    !("messages" in value) ||
+    !Array.isArray(value.messages) ||
+    value.messages.length < 1 ||
+    value.messages.length > 100
+  )
+    throw new Error("Invalid chat request");
+  const messages: ChatMessage[] = value.messages.map((message: unknown) => {
+    if (
+      typeof message !== "object" ||
+      message === null ||
+      !("id" in message) ||
+      typeof message.id !== "string" ||
+      message.id.length > 100 ||
+      !("role" in message) ||
+      (message.role !== "user" && message.role !== "assistant") ||
+      !("text" in message) ||
+      typeof message.text !== "string" ||
+      message.text.length > (message.role === "user" ? 20_000 : 100_000)
+    )
+      throw new Error("Invalid message");
+    const files =
+      "files" in message && message.files !== undefined
+        ? Array.isArray(message.files) && message.files.length <= 4
+          ? message.files.map(parseChatFile)
+          : (() => {
+              throw new Error("Invalid files");
+            })()
+        : undefined;
+    return {
+      id: message.id,
+      role: message.role,
+      text: message.text,
+      ...(files?.length ? { files } : {}),
+    };
+  });
+  if (
+    messages.at(-1)?.role !== "user" ||
+    new Set(messages.map((m) => m.id)).size !== messages.length
+  )
+    throw new Error("Invalid message order");
+  return { requestId: value.requestId, messages };
+}
+
+interface MessageNode {
+  message: ChatMessage;
+  parent: string | null;
+  status: ChatStatus;
+}
+
+/** One bounded, in-memory conversation tree. Snapshots contain only its selected path. */
+export class ChatController implements ChatActions {
+  private snapshot: ChatSnapshot;
+  private readonly listeners = new Set<() => void>();
+  private readonly nodes = new Map<string, MessageNode>();
+  private readonly children = new Map<string | null, string[]>();
+  private readonly selected = new Map<string | null, string>();
+  private active: AbortController | undefined;
+  private generation = 0;
+  constructor(
+    private readonly adapter: ChatAdapter,
+    private readonly id: () => string,
+  ) {
+    this.snapshot = { messages: [], status: "idle", capabilities: adapter.capabilities };
+  }
+  getSnapshot = (): ChatSnapshot => this.snapshot;
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+  private path(): MessageNode[] {
+    const path: MessageNode[] = [];
+    let current = this.selected.get(null);
+    while (current) {
+      const node = this.nodes.get(current);
+      if (!node) break;
+      path.push(node);
+      current = this.selected.get(current);
+    }
+    return path;
+  }
+  private publish() {
+    const path = this.path();
+    const branches: Record<string, ChatBranch> = {};
+    for (const node of path) {
+      const siblings = this.children.get(node.parent) ?? [];
+      if (siblings.length > 1)
+        branches[node.message.id] = {
+          index: siblings.indexOf(node.message.id),
+          count: siblings.length,
+        };
+    }
+    this.snapshot = {
+      ...this.snapshot,
+      messages: path.map((node) => node.message),
+      status: path.at(-1)?.status ?? "idle",
+      branches,
+    };
+    for (const listener of this.listeners) listener();
+  }
+  private add(message: ChatMessage, parent: string | null, status: ChatStatus) {
+    const node = { message, parent, status };
+    this.nodes.set(message.id, node);
+    this.children.set(parent, [...(this.children.get(parent) ?? []), message.id]);
+    this.selected.set(parent, message.id);
+    return node;
+  }
+  private room(parent: string | null, count = 1) {
+    return this.nodes.size + count <= 500 && (this.children.get(parent)?.length ?? 0) < 20;
+  }
+  send = (text: string, files: readonly ChatFile[] = []): boolean => {
+    const parent = this.snapshot.messages.at(-1)?.id ?? null;
+    if (
+      this.active ||
+      !this.adapter.capabilities.send ||
+      (!text.trim() && !files.length) ||
+      (files.length > 0 && !this.adapter.capabilities.attachments) ||
+      files.length > 4 ||
+      text.length > 20_000 ||
+      this.snapshot.messages.length >= 98 ||
+      !this.room(parent, 2)
+    )
+      return false;
+    let validated: ChatFile[];
+    try {
+      validated = files.map(parseChatFile);
+    } catch {
+      return false;
+    }
+    const user = this.add(
+      { id: this.id(), role: "user", text, ...(validated.length ? { files: validated } : {}) },
+      parent,
+      "idle",
+    );
+    this.begin(user);
+    return true;
+  };
+  edit = (messageId: string, text: string): boolean => {
+    const index = this.snapshot.messages.findIndex(
+      (message) => message.id === messageId && message.role === "user",
+    );
+    const source = this.nodes.get(messageId);
+    if (
+      this.active ||
+      !this.adapter.capabilities.send ||
+      !this.adapter.capabilities.edit ||
+      !source ||
+      index < 0 ||
+      text.length > 20_000 ||
+      (!text.trim() && !source.message.files?.length) ||
+      text === source.message.text ||
+      !this.room(source.parent, 2)
+    )
+      return false;
+    const user = this.add({ ...source.message, id: this.id(), text }, source.parent, "idle");
+    this.begin(user);
+    return true;
+  };
+  regenerate = (messageId: string): boolean => {
+    const source = this.nodes.get(messageId);
+    const index = this.snapshot.messages.findIndex(
+      (message) => message.id === messageId && message.role === "assistant",
+    );
+    const parent = source?.parent ? this.nodes.get(source.parent) : undefined;
+    if (
+      this.active ||
+      !this.adapter.capabilities.send ||
+      !this.adapter.capabilities.regenerate ||
+      index < 0 ||
+      parent?.message.role !== "user" ||
+      !this.room(parent.message.id)
+    )
+      return false;
+    this.begin(parent);
+    return true;
+  };
+  selectBranch = (messageId: string, direction: "previous" | "next"): boolean => {
+    const node = this.nodes.get(messageId);
+    if (
+      this.active ||
+      !this.adapter.capabilities.branches ||
+      !node ||
+      !this.snapshot.messages.some((message) => message.id === messageId)
+    )
+      return false;
+    const siblings = this.children.get(node.parent) ?? [];
+    const next = siblings[siblings.indexOf(messageId) + (direction === "previous" ? -1 : 1)];
+    if (!next) return false;
+    this.selected.set(node.parent, next);
+    this.publish();
+    return true;
+  };
+  retry = (): boolean => {
+    const response = this.nodes.get(this.snapshot.messages.at(-1)?.id ?? "");
+    const user = response?.parent ? this.nodes.get(response.parent) : undefined;
+    if (
+      this.active ||
+      !this.adapter.capabilities.retry ||
+      user?.message.role !== "user" ||
+      !["error", "interrupted", "cancelled"].includes(this.snapshot.status) ||
+      !this.room(user.message.id)
+    )
+      return false;
+    this.begin(user);
+    return true;
+  };
+  cancel = (): void => {
+    if (!this.active || !this.adapter.capabilities.cancel) return;
+    ++this.generation;
+    this.active.abort();
+    this.active = undefined;
+    const node = this.nodes.get(this.snapshot.messages.at(-1)?.id ?? "");
+    if (node) node.status = "cancelled";
+    this.publish();
+  };
+  dispose = (): void => {
+    ++this.generation;
+    this.active?.abort();
+    this.active = undefined;
+    this.listeners.clear();
+  };
+  private begin(user: MessageNode) {
+    const token = ++this.generation;
+    const abort = new AbortController();
+    this.active = abort;
+    const response = this.add(
+      { id: this.id(), role: "assistant", text: "" },
+      user.message.id,
+      "waiting",
+    );
+    this.publish();
+    const history = this.snapshot.messages.slice(0, -1);
+    void this.consume(history, response, token, abort);
+  }
+  private async consume(
+    history: readonly ChatMessage[],
+    response: MessageNode,
+    token: number,
+    abort: AbortController,
+  ) {
+    try {
+      let finished = false;
+      for await (const event of this.adapter.run(
+        { requestId: this.id(), messages: history },
+        abort.signal,
+      )) {
+        if (token !== this.generation || abort.signal.aborted) return;
+        if (event.type === "error") throw new Error("Response failed");
+        if (event.type === "finish") {
+          finished = true;
+          break;
+        }
+        if (event.type === "metadata")
+          response.message = { ...response.message, metadata: event.metadata };
+        else {
+          const text =
+            event.type === "replace-text" ? event.text : response.message.text + event.text;
+          if (text.length > 100_000) throw new Error("Response too large");
+          response.message = { ...response.message, text };
+          response.status = "streaming";
+        }
+        this.publish();
+      }
+      if (token !== this.generation) return;
+      if (!finished) throw new ChatInterrupted();
+      this.active = undefined;
+      response.status = "complete";
+      this.publish();
+    } catch (error) {
+      if (token !== this.generation) return;
+      this.active = undefined;
+      response.status = error instanceof ChatInterrupted ? "interrupted" : "error";
+      this.publish();
+    }
+  }
+}
+
+export * from "../review/types.js";
+export { ReviewController, reviewReducer } from "../review/controller.js";

package/source/reusable/custom/index.ts

@@ -0,0 +1,90 @@
+import {
+  ChatInterrupted,
+  parseChatEvent,
+  type ChatAdapter,
+  type ChatEvent,
+} from "../core/index.js";
+
+export interface HttpChatOptions {
+  endpoint: string;
+  /** Opt into editing, regeneration and versions. Restart is controlled separately by retry. */
+  conversationActions?: boolean;
+  /** Allow Restart as a new run. Defaults to true; disable for endpoints without replay safety. */
+  retry?: boolean;
+  /** Consumer-owned, evaluated each request so refreshed auth is used. */
+  headers?: () => HeadersInit | Promise<HeadersInit>;
+  credentials?: RequestCredentials;
+  fetch?: typeof globalThis.fetch;
+}
+
+/** Newline-delimited JSON over customer-owned HTTP. No hosted account required. */
+export function createHttpChatAdapter(options: HttpChatOptions): ChatAdapter {
+  return {
+    capabilities: {
+      send: true,
+      cancel: true,
+      retry: options.retry ?? true,
+      ...(options.conversationActions ? { edit: true, regenerate: true, branches: true } : {}),
+    },
+    async *run(request, signal): AsyncGenerator<ChatEvent> {
+      const response = await (options.fetch ?? globalThis.fetch)(options.endpoint, {
+        method: "POST",
+        signal,
+        credentials: options.credentials ?? "same-origin",
+        headers: {
+          ...Object.fromEntries(new Headers(await options.headers?.()).entries()),
+          "content-type": "application/json",
+        },
+        body: JSON.stringify(request),
+      });
+      if (
+        !response.ok ||
+        !response.body ||
+        !response.headers.get("content-type")?.startsWith("application/x-ndjson")
+      )
+        throw new Error("Response unavailable");
+      const reader = response.body.getReader();
+      const decoder = new TextDecoder();
+      let pending = "";
+      let finished = false;
+      const abort = () => {
+        void reader.cancel().catch(() => {});
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      try {
+        if (signal.aborted) return;
+        while (!finished) {
+          const { done, value } = await reader.read();
+          if (signal.aborted) return;
+          pending += decoder.decode(value, { stream: !done });
+          let newline: number;
+          while ((newline = pending.indexOf("\n")) !== -1) {
+            if (newline > 200_000) throw new Error("Stream frame too large");
+            const line = pending.slice(0, newline);
+            pending = pending.slice(newline + 1);
+            if (!line.trim()) continue;
+            const event = parseChatEvent(JSON.parse(line));
+            yield event;
+            if (event.type === "finish" || event.type === "error") {
+              finished = true;
+              break;
+            }
+          }
+          if (!finished && pending.length > 200_000) throw new Error("Stream frame too large");
+          if (done) {
+            if (!finished) throw new ChatInterrupted();
+            break;
+          }
+        }
+      } catch (error) {
+        if (signal.aborted) return;
+        if (error instanceof TypeError) throw new ChatInterrupted();
+        throw error;
+      } finally {
+        signal.removeEventListener("abort", abort);
+        await reader.cancel().catch(() => {});
+        reader.releaseLock();
+      }
+    },
+  };
+}

package/source/reusable/generative/actions.ts

@@ -0,0 +1,188 @@
+import { z } from "zod";
+import { actionSchema, assertBoundedJson, type StructuredAction } from "./schema.js";
+import { generativeCopy } from "./copy.js";
+
+export interface GenerativeRequest {
+  readonly key: string;
+  readonly action: StructuredAction;
+}
+export interface GenerativeReceipt {
+  key: string;
+  type: string;
+  state: "complete" | "not-applied";
+  message: string;
+}
+export interface GenerativeActionHandler {
+  /** Host-owned copy and intent. A model cannot mark an action safe or grant permission. */
+  label: string;
+  description: string;
+  kind: "inspect" | "mutate" | "dismiss";
+  /** Must enforce authorization and idempotency at the destination. The frozen request survives retries. */
+  execute: (request: GenerativeRequest, signal: AbortSignal) => Promise<GenerativeReceipt>;
+  /** Return null only if no receipt is available yet; this does not prove an action wasn't applied. */
+  lookup?: (request: GenerativeRequest, signal: AbortSignal) => Promise<GenerativeReceipt | null>;
+}
+export type GenerativeActions = Readonly<Record<string, GenerativeActionHandler>>;
+export type GenerativeStage =
+  | "ready"
+  | "confirm"
+  | "submitting"
+  | "failed"
+  | "uncertain"
+  | "checking"
+  | "complete"
+  | "dismissed";
+export interface GenerativeActionSnapshot {
+  stage: GenerativeStage;
+  request?: GenerativeRequest;
+  label?: string;
+  description?: string;
+  message?: string;
+  noReceipt?: boolean;
+}
+const receiptSchema = z.strictObject({
+  key: z.string().min(1).max(160),
+  type: z.string().min(1).max(160),
+  state: z.enum(["complete", "not-applied"]),
+  message: z.string().min(1).max(1000),
+});
+function freeze<T>(data: T): T {
+  if (data && typeof data === "object") {
+    Object.values(data).forEach(freeze);
+    Object.freeze(data);
+  }
+  return data;
+}
+
+/** One state owner. No execution before explicit confirmation of host-declared mutations. */
+export function createGenerativeActionController(
+  actions: GenerativeActions,
+  makeKey = () => crypto.randomUUID(),
+) {
+  const registry = Object.fromEntries(
+    Object.entries(actions).map(([type, handler]) => [type, { ...handler }]),
+  );
+  let snapshot: GenerativeActionSnapshot = { stage: "ready" };
+  let operation: AbortController | undefined;
+  let disposed = false;
+  const listeners = new Set<() => void>();
+  const update = (next: GenerativeActionSnapshot) => {
+    if (disposed) return;
+    snapshot = freeze(next);
+    listeners.forEach((l) => l());
+  };
+  const find = () =>
+    snapshot.request && Object.hasOwn(registry, snapshot.request.action.type)
+      ? registry[snapshot.request.action.type]
+      : undefined;
+  const apply = async (check = false) => {
+    const handler = find(),
+      request = snapshot.request;
+    if (disposed || !handler || !request || operation) return;
+    const prior = snapshot;
+    const abort = new AbortController();
+    operation = abort;
+    update({
+      ...prior,
+      stage: check ? "checking" : "submitting",
+      message: undefined,
+      noReceipt: false,
+    });
+    try {
+      const result = check
+        ? await handler.lookup?.(request, abort.signal)
+        : await handler.execute(request, abort.signal);
+      if (disposed || operation !== abort) return;
+      if (result == null) {
+        if (!check) throw new Error("Missing receipt");
+        update({ ...prior, stage: "uncertain", noReceipt: true });
+      } else {
+        const receipt = receiptSchema.parse(result);
+        if (receipt.key !== request.key || receipt.type !== request.action.type)
+          throw new Error("Receipt does not match");
+        update({
+          ...prior,
+          stage: receipt.state === "complete" ? "complete" : "failed",
+          message: receipt.message,
+          noReceipt: false,
+        });
+      }
+    } catch {
+      if (!disposed && operation === abort)
+        update({ ...prior, stage: "uncertain", message: undefined });
+    } finally {
+      if (operation === abort) operation = undefined;
+    }
+  };
+  return {
+    subscribe: (listener: () => void) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    getSnapshot: () => snapshot,
+    request: (input: unknown) => {
+      if (disposed || snapshot.stage !== "ready") return false;
+      try {
+        assertBoundedJson(input, 8000);
+      } catch {
+        return false;
+      }
+      const parsed = actionSchema.safeParse(input);
+      if (!parsed.success || JSON.stringify(parsed.data).length > 8000) return false;
+      const handler = Object.hasOwn(registry, parsed.data.type)
+        ? registry[parsed.data.type]
+        : undefined;
+      if (!handler) return false;
+      if (handler.kind === "dismiss") {
+        update({ stage: "dismissed", message: handler.label });
+        return true;
+      }
+      const key = makeKey();
+      if (typeof key !== "string" || !key || key.length > 160) return false;
+      const request = freeze({ key, action: structuredClone(parsed.data) });
+      update({
+        stage: handler.kind === "mutate" ? "confirm" : "ready",
+        request,
+        label: handler.label,
+        description: handler.description,
+      });
+      if (handler.kind === "inspect") void apply();
+      return true;
+    },
+    confirm: () => {
+      if (snapshot.stage !== "confirm") return false;
+      void apply();
+      return true;
+    },
+    back: () => {
+      if (!["confirm", "failed"].includes(snapshot.stage)) return false;
+      update({ stage: "ready" });
+      return true;
+    },
+    retry: () => {
+      if (!["failed", "uncertain"].includes(snapshot.stage)) return false;
+      void apply();
+      return true;
+    },
+    check: () => {
+      if (snapshot.stage !== "uncertain" || !find()?.lookup) return false;
+      void apply(true);
+      return true;
+    },
+    reset: () => {
+      if (!["complete", "dismissed"].includes(snapshot.stage)) return false;
+      update({ stage: "ready" });
+      return true;
+    },
+    dispose: () => {
+      disposed = true;
+      operation?.abort();
+      operation = undefined;
+      listeners.clear();
+    },
+  };
+}
+export type GenerativeActionController = ReturnType<typeof createGenerativeActionController>;
+export const unavailableActionMessage = generativeCopy.noHandler;