@nebutra/agent-runtime 0.2.0 → 0.2.2

package/src/design-context.test.ts

@@ -1,195 +0,0 @@
-import { describe, expect, it } from "vitest";
-
-import {
-  type DesignContext,
-  ingestDesignContext,
-  normalizeScrapeResult,
-  type RawScrapeResult,
-  type ScrapeProvider,
-  toGenerationSeed,
-} from "./design-context.js";
-
-const FIXED_ISO = "2026-05-17T00:00:00.000Z";
-const fixedClock = () => new Date(FIXED_ISO);
-
-function fakeProvider(result: RawScrapeResult): ScrapeProvider & {
-  calls: Array<{ url: string; formats: string[] }>;
-} {
-  const calls: Array<{ url: string; formats: string[] }> = [];
-  return {
-    calls,
-    async scrape(url, opts) {
-      calls.push({ url, formats: [...opts.formats] });
-      return result;
-    },
-  };
-}
-
-describe("normalizeScrapeResult", () => {
-  it("prefers markdown over html for content", () => {
-    const ctx = normalizeScrapeResult(
-      "org_1",
-      "https://example.com",
-      { markdown: "# Hello MD", html: "<h1>Hello HTML</h1>" },
-      { clock: fixedClock },
-    );
-    expect(ctx.content).toBe("# Hello MD");
-  });
-
-  it("strips tags from html when markdown absent", () => {
-    const ctx = normalizeScrapeResult(
-      "org_1",
-      "https://example.com",
-      { html: "<div><h1>Title</h1><p>Body &amp; more</p></div>" },
-      { clock: fixedClock },
-    );
-    expect(ctx.content).not.toContain("<");
-    expect(ctx.content).toContain("Title");
-    expect(ctx.content).toContain("Body");
-  });
-
-  it("dedups and validates colors, drops junk", () => {
-    const ctx = normalizeScrapeResult(
-      "org_1",
-      "https://example.com",
-      {
-        markdown: "x",
-        branding: {
-          colors: ["#fff", "#fff", "#FFFFFF", "rgb(0,0,0)", "not-a-color", "", "  "],
-          fonts: ["Inter", "Inter", "  Roboto  ", ""],
-        },
-      },
-      { clock: fixedClock },
-    );
-    expect(ctx.brand.colors).toEqual(["#fff", "#FFFFFF", "rgb(0,0,0)"]);
-    expect(ctx.brand.fonts).toEqual(["Inter", "Roboto"]);
-  });
-
-  it("degrades gracefully on empty raw (no throw, empty brand)", () => {
-    const ctx = normalizeScrapeResult("org_1", "https://example.com", {}, { clock: fixedClock });
-    expect(ctx.content).toBe("");
-    expect(ctx.brand.colors).toEqual([]);
-    expect(ctx.brand.fonts).toEqual([]);
-    expect(ctx.screenshotRef).toBeUndefined();
-    expect(ctx.title).toBeUndefined();
-  });
-
-  it("passes screenshot and title through", () => {
-    const ctx = normalizeScrapeResult(
-      "org_1",
-      "https://example.com",
-      { markdown: "x", screenshot: "https://cdn/shot.png", metadata: { title: "My Site" } },
-      { clock: fixedClock },
-    );
-    expect(ctx.screenshotRef).toBe("https://cdn/shot.png");
-    expect(ctx.title).toBe("My Site");
-  });
-
-  it("treats null screenshot as undefined", () => {
-    const ctx = normalizeScrapeResult(
-      "org_1",
-      "https://example.com",
-      { markdown: "x", screenshot: null },
-      { clock: fixedClock },
-    );
-    expect(ctx.screenshotRef).toBeUndefined();
-  });
-
-  it("uses injectable clock for fetchedAt", () => {
-    const ctx = normalizeScrapeResult(
-      "org_1",
-      "https://example.com",
-      { markdown: "x" },
-      {
-        clock: fixedClock,
-      },
-    );
-    expect(ctx.fetchedAt).toBe(FIXED_ISO);
-  });
-
-  it("carries tenantId through", () => {
-    const ctx = normalizeScrapeResult(
-      "org_xyz",
-      "https://example.com",
-      { markdown: "x" },
-      {
-        clock: fixedClock,
-      },
-    );
-    expect(ctx.tenantId).toBe("org_xyz");
-  });
-
-  it("fails closed on empty tenantId", () => {
-    expect(() =>
-      normalizeScrapeResult("", "https://example.com", { markdown: "x" }, { clock: fixedClock }),
-    ).toThrow();
-  });
-
-  it("fails closed on empty url", () => {
-    expect(() =>
-      normalizeScrapeResult("org_1", "", { markdown: "x" }, { clock: fixedClock }),
-    ).toThrow();
-  });
-});
-
-describe("ingestDesignContext", () => {
-  it("delegates to the injected provider (no real network)", async () => {
-    const provider = fakeProvider({ markdown: "seed", metadata: { title: "T" } });
-    const ctx = await ingestDesignContext("org_1", "https://example.com", provider, {
-      clock: fixedClock,
-    });
-    expect(provider.calls).toHaveLength(1);
-    expect(provider.calls[0]?.url).toBe("https://example.com");
-    expect(ctx.content).toBe("seed");
-    expect(ctx.title).toBe("T");
-    expect(ctx.tenantId).toBe("org_1");
-  });
-
-  it("passes requested formats to provider", async () => {
-    const provider = fakeProvider({ markdown: "x" });
-    await ingestDesignContext("org_1", "https://example.com", provider, {
-      formats: ["markdown", "branding"],
-      clock: fixedClock,
-    });
-    expect(provider.calls[0]?.formats).toEqual(["markdown", "branding"]);
-  });
-
-  it("fails closed on empty tenantId", async () => {
-    const provider = fakeProvider({ markdown: "x" });
-    await expect(
-      ingestDesignContext("", "https://example.com", provider, { clock: fixedClock }),
-    ).rejects.toThrow();
-    expect(provider.calls).toHaveLength(0);
-  });
-});
-
-describe("toGenerationSeed", () => {
-  const base: DesignContext = {
-    tenantId: "org_1",
-    sourceUrl: "https://example.com",
-    content: "Lorem ipsum dolor sit amet ".repeat(500),
-    brand: { colors: ["#fff", "rgb(0,0,0)"], fonts: ["Inter"] },
-    screenshotRef: undefined,
-    title: "Example",
-    fetchedAt: FIXED_ISO,
-  };
-
-  it("is deterministic", () => {
-    expect(toGenerationSeed(base)).toBe(toGenerationSeed(base));
-  });
-
-  it("is length-bounded by default", () => {
-    expect(toGenerationSeed(base).length).toBeLessThanOrEqual(4000);
-  });
-
-  it("respects injectable max chars", () => {
-    expect(toGenerationSeed(base, { maxChars: 200 }).length).toBeLessThanOrEqual(200);
-  });
-
-  it("includes title, palette and fonts", () => {
-    const seed = toGenerationSeed({ ...base, content: "short" });
-    expect(seed).toContain("Example");
-    expect(seed).toContain("#fff");
-    expect(seed).toContain("Inter");
-  });
-});

package/src/design-context.ts

@@ -1,198 +0,0 @@
-import { z } from "zod";
-
-/**
- * Design-context ingestion: turn an existing website into a structured
- * generation seed for a codegen turn.
- *
- * The scrape implementation is provider-specific and injected via a port;
- * this module never performs network I/O itself.
- */
-
-/** Structured generation seed extracted from an existing site. */
-export interface DesignContext {
-  tenantId: string;
-  sourceUrl: string;
-  content: string;
-  brand: {
-    colors: string[];
-    fonts: string[];
-  };
-  screenshotRef?: string | undefined;
-  title?: string | undefined;
-  fetchedAt: string;
-}
-
-/** Loose shape returned by a scrape provider (providers vary widely). */
-export interface RawScrapeResult {
-  markdown?: string | undefined;
-  html?: string | undefined;
-  screenshot?: string | null | undefined;
-  metadata?: { title?: string | undefined } | undefined;
-  branding?:
-    | {
-        colors?: string[] | undefined;
-        fonts?: string[] | undefined;
-      }
-    | undefined;
-}
-
-export type ScrapeFormat = "markdown" | "screenshot" | "branding";
-
-/** Injected provider port — callers wire a concrete scrape implementation. */
-export interface ScrapeProvider {
-  scrape(url: string, opts: { formats: ScrapeFormat[] }): Promise<RawScrapeResult>;
-}
-
-/** Clock injection for deterministic tests. */
-export type Clock = () => Date;
-
-const tenantSchema = z.string().trim().min(1, "tenantId is required");
-const urlSchema = z.string().trim().min(1, "sourceUrl is required");
-
-const DEFAULT_FORMATS: readonly ScrapeFormat[] = ["markdown", "screenshot", "branding"];
-const DEFAULT_MAX_CHARS = 4000;
-
-/** Permissive colour matcher: hex (3/4/6/8) or rgb/rgba/hsl(...)-ish. */
-const COLOR_RE = /^(#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})|(?:rgb|rgba|hsl|hsla)\([^)]+\))$/i;
-
-function stripTags(html: string): string {
-  const withoutTags = html.replace(/<[^>]*>/g, " ");
-  const decoded = withoutTags
-    .replace(/&amp;/g, "&")
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&nbsp;/g, " ");
-  return decoded.replace(/\s+/g, " ").trim();
-}
-
-function dedupe(values: readonly string[]): string[] {
-  const seen = new Set<string>();
-  const out: string[] = [];
-  for (const v of values) {
-    if (!seen.has(v)) {
-      seen.add(v);
-      out.push(v);
-    }
-  }
-  return out;
-}
-
-function normalizeColors(colors: readonly string[] | undefined): string[] {
-  if (!colors) return [];
-  const cleaned = colors
-    .map((c) => (typeof c === "string" ? c.trim() : ""))
-    .filter((c) => c.length > 0 && COLOR_RE.test(c));
-  return dedupe(cleaned);
-}
-
-function normalizeFonts(fonts: readonly string[] | undefined): string[] {
-  if (!fonts) return [];
-  const cleaned = fonts
-    .map((f) => (typeof f === "string" ? f.trim() : ""))
-    .filter((f) => f.length > 0);
-  return dedupe(cleaned);
-}
-
-function resolveContent(raw: RawScrapeResult): string {
-  if (typeof raw.markdown === "string" && raw.markdown.length > 0) {
-    return raw.markdown;
-  }
-  if (typeof raw.html === "string" && raw.html.length > 0) {
-    return stripTags(raw.html);
-  }
-  return "";
-}
-
-/**
- * Pure transform from a loose provider result to a {@link DesignContext}.
- * Never throws on missing fields — degrades gracefully. Fails closed on
- * empty tenantId / url.
- */
-export function normalizeScrapeResult(
-  tenantId: string,
-  url: string,
-  raw: RawScrapeResult,
-  opts?: { clock?: Clock | undefined },
-): DesignContext {
-  const safeTenant = tenantSchema.parse(tenantId);
-  const safeUrl = urlSchema.parse(url);
-  const clock = opts?.clock ?? (() => new Date());
-
-  const screenshot =
-    typeof raw.screenshot === "string" && raw.screenshot.length > 0 ? raw.screenshot : undefined;
-  const title =
-    typeof raw.metadata?.title === "string" && raw.metadata.title.length > 0
-      ? raw.metadata.title
-      : undefined;
-
-  return {
-    tenantId: safeTenant,
-    sourceUrl: safeUrl,
-    content: resolveContent(raw),
-    brand: {
-      colors: normalizeColors(raw.branding?.colors),
-      fonts: normalizeFonts(raw.branding?.fonts),
-    },
-    screenshotRef: screenshot,
-    title,
-    fetchedAt: clock().toISOString(),
-  };
-}
-
-/**
- * Validate inputs, call the injected provider, normalize the result.
- * tenantId is mandatory and validated before the provider is invoked
- * (fail-closed: no provider call for an invalid tenant).
- */
-export async function ingestDesignContext(
-  tenantId: string,
-  url: string,
-  provider: ScrapeProvider,
-  opts?: {
-    formats?: ScrapeFormat[] | undefined;
-    clock?: Clock | undefined;
-  },
-): Promise<DesignContext> {
-  const safeTenant = tenantSchema.parse(tenantId);
-  const safeUrl = urlSchema.parse(url);
-  const formats = opts?.formats ?? [...DEFAULT_FORMATS];
-  const raw = await provider.scrape(safeUrl, { formats });
-  return normalizeScrapeResult(safeTenant, safeUrl, raw, {
-    clock: opts?.clock,
-  });
-}
-
-/**
- * Render a compact, deterministic prompt-seed block suitable for
- * prepending to a codegen turn. Pure; output length is bounded.
- */
-export function toGenerationSeed(
-  ctx: DesignContext,
-  opts?: { maxChars?: number | undefined },
-): string {
-  const maxChars =
-    typeof opts?.maxChars === "number" && opts.maxChars > 0 ? opts.maxChars : DEFAULT_MAX_CHARS;
-
-  const header: string[] = ["## Design Context", `Source: ${ctx.sourceUrl}`];
-  if (ctx.title) header.push(`Title: ${ctx.title}`);
-  if (ctx.brand.colors.length > 0) {
-    header.push(`Palette: ${ctx.brand.colors.join(", ")}`);
-  }
-  if (ctx.brand.fonts.length > 0) {
-    header.push(`Fonts: ${ctx.brand.fonts.join(", ")}`);
-  }
-  if (ctx.screenshotRef) header.push(`Screenshot: ${ctx.screenshotRef}`);
-
-  const headerBlock = header.join("\n");
-  const contentLabel = "\n\nContent:\n";
-  const budget = maxChars - headerBlock.length - contentLabel.length;
-
-  if (budget <= 0) {
-    return headerBlock.slice(0, maxChars);
-  }
-
-  const truncated = ctx.content.slice(0, budget);
-  return `${headerBlock}${contentLabel}${truncated}`;
-}

package/src/dispatcher.test.ts

@@ -1,234 +0,0 @@
-import { describe, expect, it, vi } from "vitest";
-import { ProtocolDispatcher } from "./dispatcher";
-
-function envelope(over: Record<string, unknown> = {}) {
-  return {
-    jsonrpc: "2.0",
-    id: 1,
-    method: "model/list",
-    tenantId: "org_123",
-    ...over,
-  };
-}
-
-describe("ProtocolDispatcher — envelope validation (fail-closed)", () => {
-  it("rejects an envelope missing tenantId with a JSON-RPC error (never throws)", async () => {
-    const d = new ProtocolDispatcher();
-    const res = await d.dispatch({ jsonrpc: "2.0", id: 7, method: "model/list" });
-    expect(res).toMatchObject({ jsonrpc: "2.0", id: 7 });
-    expect("error" in res && res.error.code).toBe(-32600);
-    expect("result" in res).toBe(false);
-  });
-
-  it("rejects an empty tenantId fail-closed", async () => {
-    const d = new ProtocolDispatcher();
-    const res = await d.dispatch(envelope({ tenantId: "" }));
-    expect("error" in res && res.error.code).toBe(-32600);
-  });
-
-  it("rejects a completely malformed envelope without throwing", async () => {
-    const d = new ProtocolDispatcher();
-    const res = await d.dispatch("not-an-object");
-    expect("error" in res && res.error.code).toBe(-32600);
-    // id falls back to null when unparseable
-    expect((res as { id: unknown }).id).toBeNull();
-  });
-});
-
-describe("ProtocolDispatcher — method lookup", () => {
-  it("returns -32601 for an unknown method", async () => {
-    const d = new ProtocolDispatcher();
-    const res = await d.dispatch(envelope({ method: "does/not-exist" }));
-    expect("error" in res && res.error.code).toBe(-32601);
-  });
-
-  it("returns -32601 when no handler is registered for a known method", async () => {
-    const d = new ProtocolDispatcher();
-    const res = await d.dispatch(envelope({ method: "model/list" }));
-    expect("error" in res && res.error.code).toBe(-32601);
-  });
-
-  it("invokes a registered handler and returns its result", async () => {
-    const d = new ProtocolDispatcher();
-    d.register("model/list", async () => ({ models: ["a"] }));
-    const res = await d.dispatch(envelope());
-    expect(res).toMatchObject({
-      jsonrpc: "2.0",
-      id: 1,
-      result: { models: ["a"] },
-    });
-  });
-});
-
-describe("ProtocolDispatcher — scope resolution (fail-closed)", () => {
-  it("returns a JSON-RPC error when a thread-scoped method is missing threadId", async () => {
-    const d = new ProtocolDispatcher();
-    d.register("turn/start", async () => "ok");
-    const res = await d.dispatch(envelope({ method: "turn/start", params: {} }));
-    expect("error" in res && res.error.code).toBe(-32602);
-    expect("result" in res).toBe(false);
-  });
-
-  it("passes the resolved thread scope to the handler", async () => {
-    const d = new ProtocolDispatcher();
-    let seenScope: unknown;
-    d.register("turn/start", async (_p, scope) => {
-      seenScope = scope;
-      return "ok";
-    });
-    await d.dispatch(envelope({ method: "turn/start", params: { threadId: "th_1" } }));
-    expect(seenScope).toEqual({
-      tenantId: "org_123",
-      kind: "thread",
-      threadId: "th_1",
-    });
-  });
-});
-
-describe("ProtocolDispatcher — serialization semantics", () => {
-  it("serializes same-scope requests in FIFO order", async () => {
-    const d = new ProtocolDispatcher();
-    const order: string[] = [];
-    d.register("turn/start", async (params) => {
-      const p = params as { tag: string; delay: number };
-      await new Promise((r) => setTimeout(r, p.delay));
-      order.push(p.tag);
-      return p.tag;
-    });
-
-    const a = d.dispatch(
-      envelope({
-        method: "turn/start",
-        id: "a",
-        params: { threadId: "th_same", tag: "A", delay: 40 },
-      }),
-    );
-    const b = d.dispatch(
-      envelope({
-        method: "turn/start",
-        id: "b",
-        params: { threadId: "th_same", tag: "B", delay: 1 },
-      }),
-    );
-
-    await Promise.all([a, b]);
-    // B is fast but must wait for A because they share tenant+thread scope.
-    expect(order).toEqual(["A", "B"]);
-  });
-
-  it("runs distinct-scope requests concurrently", async () => {
-    const d = new ProtocolDispatcher();
-    const order: string[] = [];
-    d.register("turn/start", async (params) => {
-      const p = params as { tag: string; delay: number };
-      await new Promise((r) => setTimeout(r, p.delay));
-      order.push(p.tag);
-      return p.tag;
-    });
-
-    const slow = d.dispatch(
-      envelope({
-        method: "turn/start",
-        id: "slow",
-        params: { threadId: "th_slow", tag: "SLOW", delay: 40 },
-      }),
-    );
-    const fast = d.dispatch(
-      envelope({
-        method: "turn/start",
-        id: "fast",
-        params: { threadId: "th_fast", tag: "FAST", delay: 1 },
-      }),
-    );
-
-    await Promise.all([slow, fast]);
-    // Different threads → different scope keys → concurrent; FAST finishes first.
-    expect(order).toEqual(["FAST", "SLOW"]);
-  });
-
-  it("isolates same-thread ids across different tenants (cross-tenant concurrency)", async () => {
-    const d = new ProtocolDispatcher();
-    const order: string[] = [];
-    d.register("turn/start", async (params) => {
-      const p = params as { tag: string; delay: number };
-      await new Promise((r) => setTimeout(r, p.delay));
-      order.push(p.tag);
-      return p.tag;
-    });
-
-    const t1 = d.dispatch(
-      envelope({
-        tenantId: "org_A",
-        method: "turn/start",
-        id: "t1",
-        params: { threadId: "th_shared", tag: "A", delay: 40 },
-      }),
-    );
-    const t2 = d.dispatch(
-      envelope({
-        tenantId: "org_B",
-        method: "turn/start",
-        id: "t2",
-        params: { threadId: "th_shared", tag: "B", delay: 1 },
-      }),
-    );
-
-    await Promise.all([t1, t2]);
-    expect(order).toEqual(["B", "A"]);
-  });
-});
-
-describe("ProtocolDispatcher — handler errors", () => {
-  it("maps a thrown handler error to JSON-RPC -32603 without leaking a stack", async () => {
-    const d = new ProtocolDispatcher();
-    d.register("model/list", async () => {
-      throw new Error("boom internal");
-    });
-    const res = await d.dispatch(envelope());
-    expect("error" in res && res.error.code).toBe(-32603);
-    const msg = ("error" in res && res.error.message) || "";
-    expect(msg).toBe("boom internal");
-    expect(msg).not.toContain("at ");
-  });
-
-  it("recovers the serial lane after a handler throws", async () => {
-    const d = new ProtocolDispatcher();
-    let calls = 0;
-    d.register("turn/start", async () => {
-      calls += 1;
-      if (calls === 1) throw new Error("first fails");
-      return "second ok";
-    });
-    const first = await d.dispatch(
-      envelope({ method: "turn/start", id: "f1", params: { threadId: "th_x" } }),
-    );
-    const second = await d.dispatch(
-      envelope({ method: "turn/start", id: "f2", params: { threadId: "th_x" } }),
-    );
-    expect("error" in first && first.error.code).toBe(-32603);
-    expect("result" in second && second.result).toBe("second ok");
-  });
-});
-
-describe("ProtocolDispatcher — notifications", () => {
-  it("emits to registered listeners for a valid notification name", () => {
-    const d = new ProtocolDispatcher();
-    const spy = vi.fn();
-    d.onNotification("turn/completed", spy);
-    d.emitNotification("turn/completed", { turnId: "t1" });
-    expect(spy).toHaveBeenCalledWith({ turnId: "t1" });
-  });
-
-  it("throws for an unknown notification name (validate name ∈ NOTIFICATIONS)", () => {
-    const d = new ProtocolDispatcher();
-    expect(() => d.emitNotification("not/a/real/notification" as never, {})).toThrow();
-  });
-
-  it("does not invoke listeners bound to a different notification", () => {
-    const d = new ProtocolDispatcher();
-    const spy = vi.fn();
-    d.onNotification("turn/started", spy);
-    d.emitNotification("turn/completed", {});
-    expect(spy).not.toHaveBeenCalled();
-  });
-});