@superxd-studio/adptr 0.5.0

package/core/index.js

@@ -0,0 +1,4 @@
+import { a as e, i as t, n, o as r, r as i, t as a } from "../chunks/core-BCqVRLUy.js";
+import { a as o, i as s, n as c, o as l, r as u, t as d } from "../chunks/types-BGF7r1my.js";
+import { n as f, t as p } from "../chunks/controller-Cfpg0C7v.js";
+export { r as AttachmentController, a as ChatController, n as ChatInterrupted, p as ReviewController, d as ReviewFault, i as parseChatEvent, t as parseChatFile, e as parseChatRequest, c as parseReviewDecision, u as parseReviewProposal, s as parseReviewReceipt, o as parseReviewRecord, l as parseReviewRecovery, f as reviewReducer };

package/custom/index.js

@@ -0,0 +1,64 @@
+import { n as e, r as t } from "../chunks/core-BCqVRLUy.js";
+//#region src/reusable/custom/index.ts
+function n(n) {
+	return {
+		capabilities: {
+			send: !0,
+			cancel: !0,
+			retry: n.retry ?? !0,
+			...n.conversationActions ? {
+				edit: !0,
+				regenerate: !0,
+				branches: !0
+			} : {}
+		},
+		async *run(r, i) {
+			let a = await (n.fetch ?? globalThis.fetch)(n.endpoint, {
+				method: "POST",
+				signal: i,
+				credentials: n.credentials ?? "same-origin",
+				headers: {
+					...Object.fromEntries(new Headers(await n.headers?.()).entries()),
+					"content-type": "application/json"
+				},
+				body: JSON.stringify(r)
+			});
+			if (!a.ok || !a.body || !a.headers.get("content-type")?.startsWith("application/x-ndjson")) throw Error("Response unavailable");
+			let o = a.body.getReader(), s = new TextDecoder(), c = "", l = !1, u = () => {
+				o.cancel().catch(() => {});
+			};
+			i.addEventListener("abort", u, { once: !0 });
+			try {
+				if (i.aborted) return;
+				for (; !l;) {
+					let { done: n, value: r } = await o.read();
+					if (i.aborted) return;
+					c += s.decode(r, { stream: !n });
+					let a;
+					for (; (a = c.indexOf("\n")) !== -1;) {
+						if (a > 2e5) throw Error("Stream frame too large");
+						let e = c.slice(0, a);
+						if (c = c.slice(a + 1), !e.trim()) continue;
+						let n = t(JSON.parse(e));
+						if (yield n, n.type === "finish" || n.type === "error") {
+							l = !0;
+							break;
+						}
+					}
+					if (!l && c.length > 2e5) throw Error("Stream frame too large");
+					if (n) {
+						if (!l) throw new e();
+						break;
+					}
+				}
+			} catch (t) {
+				if (i.aborted) return;
+				throw t instanceof TypeError ? new e() : t;
+			} finally {
+				i.removeEventListener("abort", u), await o.cancel().catch(() => {}), o.releaseLock();
+			}
+		}
+	};
+}
+//#endregion
+export { n as createHttpChatAdapter };

package/examples/ai-sdk-backend/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "superxd-sdk-server-example",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "start": "node server.mjs"
+  },
+  "dependencies": {
+    "ai": "7.0.126"
+  }
+}

package/examples/ai-sdk-backend/server.mjs

@@ -0,0 +1,316 @@
+import { createServer } from "node:http";
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { randomUUID, createHash } from "node:crypto";
+import { createUIMessageStream, pipeUIMessageStreamToResponse, safeValidateUIMessages } from "ai";
+import { parseChatRequest } from "../../core/index.js";
+
+const allowedTypes = ["image/png", "image/jpeg", "application/pdf", "text/plain"];
+const maxFileBytes = 5_000_000;
+const maxStoredBytes = 20_000_000;
+const lifetime = 15 * 60_000;
+
+async function readBody(request, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    size += chunk.length;
+    if (size > limit) throw new Error("Body too large");
+    chunks.push(chunk);
+  }
+  return Buffer.concat(chunks);
+}
+function contentMatches(bytes, mediaType) {
+  if (!bytes.length) return false;
+  if (mediaType === "image/png")
+    return bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]));
+  if (mediaType === "image/jpeg") return bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255;
+  if (mediaType === "application/pdf") return bytes.subarray(0, 5).toString() === "%PDF-";
+  if (mediaType === "text/plain") {
+    try {
+      new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+      return !bytes.includes(0);
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Executable SDK + upload integration. Temporary loopback storage; no model or production auth. */
+export function createAiSdkServer({ wait = 100 } = {}) {
+  const stored = new Map();
+  const uploadIds = new Map();
+  const pendingUploads = new Set();
+  const seen = new Set();
+  const failed = new Set();
+  // Keep the most recent fixture identities instead of forgetting the entire window at once.
+  const remember = (set, key) => {
+    set.add(key);
+    if (set.size > 500) set.delete(set.values().next().value);
+  };
+  let storedBytes = 0;
+  let reservedBytes = 0;
+  const forget = (id) => {
+    const entry = stored.get(id);
+    if (entry) {
+      uploadIds.delete(entry.uploadId);
+      storedBytes -= entry.bytes.length;
+      stored.delete(id);
+    }
+  };
+  const prune = () => {
+    for (const [id, entry] of stored) if (entry.expires < Date.now()) forget(id);
+  };
+  const server = createServer(async (request, response) => {
+    if (request.headers.host !== `127.0.0.1:${request.socket.localPort}`) {
+      response.writeHead(403).end();
+      return;
+    }
+    prune();
+    const origin = request.headers.origin;
+    if (
+      origin &&
+      !["http://127.0.0.1:5190", "http://127.0.0.1:5300", "http://127.0.0.1:5301"].includes(origin)
+    ) {
+      response.writeHead(403).end();
+      return;
+    }
+    if (origin) response.setHeader("access-control-allow-origin", origin);
+    response.setHeader("vary", "Origin");
+    response.setHeader("cache-control", "no-store");
+    response.setHeader("x-content-type-options", "nosniff");
+    if (request.method === "OPTIONS") {
+      response
+        .writeHead(204, {
+          "access-control-allow-methods": "POST,GET,DELETE",
+          "access-control-allow-headers":
+            "content-type,x-file-name,x-upload-id,x-demo-scenario,x-demo-session,x-upload-scenario",
+        })
+        .end();
+      return;
+    }
+    if (request.url === "/health" && request.method === "GET") {
+      response.end("ready");
+      return;
+    }
+    const fileId = /^\/files\/([\w-]{1,100})$/.exec(request.url)?.[1];
+    if (fileId && ["GET", "DELETE"].includes(request.method)) {
+      const entry = stored.get(fileId);
+      if (!entry) {
+        response.writeHead(404).end();
+        return;
+      }
+      if (request.method === "DELETE") {
+        if (entry.claimed) {
+          response.writeHead(409).end();
+          return;
+        }
+        forget(fileId);
+        response.writeHead(204).end();
+        return;
+      }
+      response.setHeader("content-type", entry.file.mediaType);
+      response.setHeader(
+        "content-disposition",
+        `attachment; filename*=UTF-8''${encodeURIComponent(entry.file.name)}`,
+      );
+      response.end(entry.bytes);
+      return;
+    }
+    const abort = new AbortController();
+    response.on("close", () => abort.abort());
+    if (request.url === "/uploads" && request.method === "POST") {
+      const uploadId = String(request.headers["x-upload-id"] ?? "");
+      if (!/^[\w-]{1,100}$/.test(uploadId)) {
+        response.writeHead(400).end();
+        return;
+      }
+      if (pendingUploads.has(uploadId)) {
+        response.writeHead(409).end();
+        return;
+      }
+      const length = Number(request.headers["content-length"]);
+      const mediaType = request.headers["content-type"];
+      if (
+        !allowedTypes.includes(mediaType) ||
+        !Number.isSafeInteger(length) ||
+        length < 1 ||
+        length > maxFileBytes
+      ) {
+        response.writeHead(415).end();
+        return;
+      }
+      if (
+        storedBytes + reservedBytes + length > maxStoredBytes ||
+        stored.size + pendingUploads.size >= 100
+      ) {
+        response.writeHead(503).end();
+        return;
+      }
+      reservedBytes += length;
+      pendingUploads.add(uploadId);
+      try {
+        const name = decodeURIComponent(String(request.headers["x-file-name"] ?? ""));
+        if (
+          !name.trim() ||
+          name.length > 255 ||
+          Array.from(name).some((char) => char.charCodeAt(0) < 32)
+        )
+          throw new Error("Invalid filename");
+        const bytes = await readBody(request, maxFileBytes);
+        if (bytes.length !== length || !contentMatches(bytes, mediaType))
+          throw new Error("Invalid content");
+        const digest = createHash("sha256").update(bytes).digest("hex");
+        const existing = stored.get(uploadIds.get(uploadId));
+        if (existing) {
+          if (
+            existing.digest !== digest ||
+            existing.file.name !== name ||
+            existing.file.mediaType !== mediaType
+          )
+            throw new Error("Upload identifier mismatch");
+          response
+            .writeHead(200, { "content-type": "application/json" })
+            .end(JSON.stringify(existing.file));
+          return;
+        }
+        await delay(request.headers["x-upload-scenario"] === "slow" ? wait * 20 : wait, undefined, {
+          signal: abort.signal,
+        });
+        const key = `upload:${request.headers["x-demo-session"]}:${name}`;
+        if (request.headers["x-upload-scenario"] === "fail-once" && !failed.has(key)) {
+          remember(failed, key);
+          response.writeHead(503).end();
+          return;
+        }
+        if (abort.signal.aborted) return;
+        const id = randomUUID();
+        const file = {
+          id,
+          name,
+          mediaType,
+          size: bytes.length,
+          url: `http://127.0.0.1:${server.address().port}/files/${id}`,
+        };
+        stored.set(id, {
+          file,
+          bytes,
+          expires: Date.now() + lifetime,
+          claimed: false,
+          uploadId,
+          digest,
+        });
+        uploadIds.set(uploadId, id);
+        storedBytes += bytes.length;
+        response.writeHead(201, { "content-type": "application/json" }).end(JSON.stringify(file));
+      } catch {
+        if (!abort.signal.aborted) response.writeHead(400).end();
+      } finally {
+        reservedBytes -= length;
+        pendingUploads.delete(uploadId);
+      }
+      return;
+    }
+    if (request.url !== "/chat" || request.method !== "POST") {
+      response.writeHead(404).end();
+      return;
+    }
+    try {
+      const body = JSON.parse((await readBody(request, 512_000)).toString("utf8"));
+      const validated = await safeValidateUIMessages({ messages: body.messages });
+      if (!validated.success) throw new Error("Invalid SDK messages");
+      const input = parseChatRequest({
+        requestId: body.requestId,
+        messages: validated.data.map((message) => {
+          if (message.parts.some((part) => !["text", "file"].includes(part.type)))
+            throw new Error("Unsupported part");
+          const files = message.metadata?.superxdFiles ?? [];
+          const parts = message.parts.filter((part) => part.type === "file");
+          if (
+            !Array.isArray(files) ||
+            parts.length !== files.length ||
+            parts.some(
+              (part, index) =>
+                part.url !== files[index]?.url ||
+                part.filename !== files[index]?.name ||
+                part.mediaType !== files[index]?.mediaType,
+            )
+          )
+            throw new Error("Invalid file parts");
+          return {
+            id: message.id,
+            role: message.role,
+            text: message.parts
+              .filter((part) => part.type === "text")
+              .map((part) => part.text)
+              .join(""),
+            files,
+          };
+        }),
+      });
+      for (const message of input.messages)
+        for (const file of message.files ?? []) {
+          const entry = stored.get(file.id);
+          if (!entry || JSON.stringify(entry.file) !== JSON.stringify(file))
+            throw new Error("Unknown file");
+        }
+      if (seen.has(input.requestId)) {
+        response.writeHead(409).end();
+        return;
+      }
+      remember(seen, input.requestId);
+      for (const message of input.messages)
+        for (const file of message.files ?? []) stored.get(file.id).claimed = true;
+      const last = input.messages.at(-1);
+      const scenario = request.headers["x-demo-scenario"];
+      const key = `chat:${request.headers["x-demo-session"]}:${last.id}`;
+      const stream = createUIMessageStream({
+        onError: () => "The response could not finish.",
+        execute: async ({ writer }) => {
+          writer.write({
+            type: "start",
+            messageId: randomUUID(),
+            messageMetadata: { integration: "sdk-example", receivedFiles: last.files?.length ?? 0 },
+          });
+          writer.write({ type: "text-start", id: "response" });
+          const chunks = [
+            "Start with the person and the task they need to finish.\n\n",
+            ...(last.files?.length
+              ? [
+                  `Received ${last.files.length} verified file reference${last.files.length === 1 ? "" : "s"}: ${last.files.map((file) => file.name).join(", ")}.\n\n`,
+                ]
+              : []),
+            last.text || "Review the attached files.",
+            "\n\nThis is a deterministic SDK response; no model is connected.",
+          ];
+          for (let index = 0; index < chunks.length; index++) {
+            await delay(scenario === "slow" ? wait * 8 : wait, undefined, { signal: abort.signal });
+            if (index === 1 && scenario === "fail-once" && !failed.has(key)) {
+              remember(failed, key);
+              throw new Error("Demo failure");
+            }
+            // No finish event: the client must retain an interrupted response, not claim success.
+            if (index === 1 && scenario === "interrupted") return;
+            writer.write({ type: "text-delta", id: "response", delta: chunks[index] });
+          }
+          writer.write({ type: "text-end", id: "response" });
+          writer.write({ type: "finish", finishReason: "stop" });
+        },
+      });
+      await pipeUIMessageStreamToResponse({ response, stream });
+    } catch {
+      if (abort.signal.aborted) return;
+      if (!response.headersSent) response.writeHead(400).end();
+      else response.end();
+    }
+  });
+  return server;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  const port = Number(process.env.SUPERXD_EXAMPLE_PORT ?? 5193);
+  createAiSdkServer().listen(port, "127.0.0.1", () =>
+    console.log(`Local SDK/upload example ready at http://127.0.0.1:${port}`),
+  );
+}

package/examples/custom-backend/copy.mjs

@@ -0,0 +1,7 @@
+/** Sample content for the executable library example. No provider or generated content. */
+export const exampleCopy = {
+  alternate:
+    '## Start with their unfinished work\n\nA second way to frame the same brief is to focus on what people can return to.\n\n1. **Keep their draft.** Save the useful work they have already done.\n2. **Name the next step.** Help them continue without starting again.\n3. **Show what changed.** Make progress easy to recognize.\n\n```ts\nconst nextStep = draft.completed ? "review" : "continue";\n```\n\nThis is another sample response; no model is connected.',
+  response:
+    '## A clearer first step\n\nHelp people finish one useful action before asking them to configure everything.\n\n### What to include\n\n1. A clear next step\n2. A useful default they can change\n3. A way to return to unfinished work\n\n> Keep the person’s progress when they leave and return.\n\nAn example of the state you might preserve:\n\n```ts\nconst draft = {\n  step: "first-action",\n  completed: false,\n  title: "My first project",\n};\n```\n\nUse `completed` to distinguish a draft from finished work.\n\n| Moment | Keep available |\n| --- | --- |\n| Working | The next useful action |\n| Returning | Their unfinished draft |\n\nSee [React’s state guide](https://react.dev/learn/state-a-components-memory) for the implementation pattern.\n\nThis is a sample response; no model is connected.',
+};

package/examples/custom-backend/server.mjs

@@ -0,0 +1,118 @@
+import { createServer } from "node:http";
+import { setTimeout as delay } from "node:timers/promises";
+import { pathToFileURL } from "node:url";
+import { realpathSync } from "node:fs";
+import { parseChatRequest } from "../../core/index.js";
+import { exampleCopy } from "./copy.mjs";
+
+/** Deterministic integration server. Loopback only, no model, auth, tools or side effects. */
+export function createChatServer({ wait = 100 } = {}) {
+  const seen = new Set();
+  const failed = new Set();
+  const richRuns = new Map();
+  return createServer(async (request, response) => {
+    const origin = request.headers.origin;
+    if (
+      origin &&
+      !["http://127.0.0.1:5190", "http://127.0.0.1:5300", "http://127.0.0.1:5301"].includes(origin)
+    ) {
+      response.writeHead(403).end();
+      return;
+    }
+    if (origin) response.setHeader("access-control-allow-origin", origin);
+    response.setHeader("vary", "Origin");
+    if (request.method === "OPTIONS") {
+      response
+        .writeHead(204, {
+          "access-control-allow-methods": "POST",
+          "access-control-allow-headers":
+            "content-type,x-demo-scenario,x-demo-session,x-demo-format",
+        })
+        .end();
+      return;
+    }
+    if (request.url === "/health" && request.method === "GET") {
+      response.end("ready");
+      return;
+    }
+    if (request.url !== "/chat" || request.method !== "POST") {
+      response.writeHead(404).end();
+      return;
+    }
+    const controller = new AbortController();
+    response.on("close", () => controller.abort());
+    try {
+      const parts = [];
+      let size = 0;
+      for await (const chunk of request) {
+        parts.push(chunk);
+        size += chunk.length;
+        if (size > 128_000) {
+          response.writeHead(413).end();
+          return;
+        }
+      }
+      const body = Buffer.concat(parts).toString("utf8");
+      const input = parseChatRequest(JSON.parse(body));
+      if (seen.has(input.requestId)) {
+        response.writeHead(409).end();
+        return;
+      }
+      // Bounded process-local deduplication for this side-effect-free example only.
+      if (seen.size > 500) seen.clear();
+      seen.add(input.requestId);
+      const text = input.messages.at(-1).text;
+      const scenario = request.headers["x-demo-scenario"];
+      const key = String(request.headers["x-demo-session"]) + text;
+      const run = (richRuns.get(key) ?? 0) + 1;
+      if (request.headers["x-demo-format"] === "rich") {
+        if (richRuns.size > 500) richRuns.clear();
+        richRuns.set(key, run);
+      }
+      response.writeHead(200, {
+        "content-type": "application/x-ndjson; charset=utf-8",
+        "cache-control": "no-store",
+        "x-content-type-options": "nosniff",
+      });
+      await delay(wait, undefined, { signal: controller.signal });
+      const chunks =
+        request.headers["x-demo-format"] === "rich"
+          ? ((run % 2 === 0 ? exampleCopy.alternate : exampleCopy.response).match(
+              /[\s\S]{1,80}/g,
+            ) ?? [])
+          : [
+              "Start with the person and the task they need to finish.\n\n",
+              "Choose one useful improvement for: ",
+              text,
+              "\n\nKeep the first release small enough to learn from.",
+            ];
+      for (let index = 0; index < chunks.length; index++) {
+        if (index === 1 && scenario === "fail-once" && !failed.has(key)) {
+          if (failed.size > 500) failed.clear();
+          failed.add(key);
+          response.end(JSON.stringify({ type: "error" }) + "\n");
+          return;
+        }
+        if (index === 1 && scenario === "interrupted") {
+          response.end();
+          return;
+        }
+        response.write(JSON.stringify({ type: "text", text: chunks[index] }) + "\n");
+        await delay(scenario === "slow" ? wait * 8 : wait, undefined, {
+          signal: controller.signal,
+        });
+      }
+      response.end(JSON.stringify({ type: "finish" }) + "\n");
+    } catch {
+      if (controller.signal.aborted) return;
+      if (!response.headersSent) response.writeHead(400).end();
+      else response.end(JSON.stringify({ type: "error" }) + "\n");
+    }
+  });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) {
+  createChatServer().listen(5192, "127.0.0.1", () =>
+    console.log("Local integration example ready at http://127.0.0.1:5192"),
+  );
+}