Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

8.5 KB
Raw Blame
/**
 * Semantic ids (services/semantic-id.ts): how a create dialog's name becomes the id of an
 * organization, a channel, a Project, an Agent or a Benchmark, when the model is not asked or
 * its answer is unusable.
 *
 * - A name folds to a lowercase id behind the kind's prefix: diacritics folded, words joined,
 *   the prefix never doubled; a name with no ASCII letter or digit yields nothing; the ASCII
 *   part of a mixed name is kept.
 * - An id is capped at 64 characters with its prefix kept, never ending in a separator, and a
 *   taken id gets a numeric suffix (compared after prefixing) that stays inside the cap.
 * - A model's answer is read from its first non-empty line, quotes and code marks stripped,
 *   prefixed once; an answer with no ASCII yields nothing.
 * - A placeholder is a valid, dated, obviously temporary id that avoids the taken ones.
 * - Projects and Agents take a bare snake_case id, repaired behind the noun when it would start
 *   with a digit or be one letter; a Benchmark takes a kebab-case id; a non-admin's Project
 *   lives in the owner's namespace; every kind accepts its own placeholder.
 */
import { describe, expect, it } from "vitest";
import {
  SEMANTIC_ID_RULES,
  fallbackSemanticId,
  placeholderSemanticId,
  prefixSemanticId,
  projectIdRule,
  sanitizeSuggestedId,
  uniqueSemanticId,
} from "../src/services/semantic-id.js";

const { org, channel } = SEMANTIC_ID_RULES;

describe("fallbackSemanticId", () => {
  it("folds a name to a lowercase id behind the kind's prefix", () => {
    const cases = [
      ["Plugin Marketplace", org, "co_plugin_marketplace"],
      // Diacritics fold, and punctuation runs collapse to one separator.
      ["  Café--Site!! ", channel, "ch_cafe_site"],
      // The prefix is what makes a name starting with a digit a valid id…
      ["2026 plan", org, "co_2026_plan"],
      ["3d", channel, "ch_3d"],
      // …and what makes a one-character name long enough.
      ["x", org, "co_x"],
      // A core that already carries the prefix is not prefixed twice.
      ["co_acme", org, "co_acme"],
      ["Ch Site", channel, "ch_site"],
      // The ASCII part of a mixed name is kept.
      ["科研 Lab 2", org, "co_lab_2"],
    ] as const;
    for (const [name, rule, id] of cases) expect(fallbackSemanticId(name, rule), name).toBe(id);
  });

  it("yields nothing for a name with no ASCII letters or digits", () => {
    for (const name of ["科研公司", "   ", "!!!"]) {
      expect(fallbackSemanticId(name, org), name).toBeNull();
    }
  });

  it("caps the length at 64 with the prefix kept, and never ends in an underscore", () => {
    expect(fallbackSemanticId("a".repeat(70) + " tail words", org)).toBe(`co_${"a".repeat(61)}`);
  });

  it("avoids taken ids with a numeric suffix, compared after prefixing", () => {
    expect(fallbackSemanticId("Site", channel, ["ch_site"])).toBe("ch_site_2");
    expect(fallbackSemanticId("Site", channel, ["ch_site", "ch_site_2"])).toBe("ch_site_3");
    // The bare core is not the id, so holding it takes nothing.
    expect(fallbackSemanticId("Site", channel, ["site"])).toBe("ch_site");
    // The suffix stays inside the length cap.
    expect(uniqueSemanticId("b".repeat(64), ["b".repeat(64)], "_", 64)).toBe("b".repeat(62) + "_2");
  });
});

describe("prefixSemanticId", () => {
  it("puts the kind's prefix in front exactly once", () => {
    expect(prefixSemanticId("marketing", channel)).toBe("ch_marketing");
    expect(prefixSemanticId("ch_marketing", channel)).toBe("ch_marketing");
    expect(prefixSemanticId("marketing", org)).toBe("co_marketing");
  });
});

describe("sanitizeSuggestedId", () => {
  it("reads the first non-empty line, strips quotes and code marks, and prefixes it once", () => {
    expect(sanitizeSuggestedId("\n`research_lab`\n", org)).toBe("co_research_lab");
    expect(sanitizeSuggestedId('"Research Lab".', org)).toBe("co_research_lab");
    expect(sanitizeSuggestedId("co_research_lab", org)).toBe("co_research_lab");
    // An answer with no ASCII names nothing.
    expect(sanitizeSuggestedId("科研实验室", org)).toBeNull();
  });
});

describe("placeholderSemanticId", () => {
  const day = new Date(2026, 8, 9); // 2026-09-09, local — the stamp is the host's own date.

  it("is a valid, dated, obviously-temporary id, prefixed by kind, with a padded date", () => {
    expect(placeholderSemanticId(org, [], day)).toBe("co_org_20260909");
    expect(placeholderSemanticId(channel, [], day)).toBe("ch_channel_20260909");
    expect(placeholderSemanticId(org, [], new Date(2026, 0, 3))).toBe("co_org_20260103");
  });

  it("avoids the ids already taken, so pressing the button twice gives two ids", () => {
    expect(placeholderSemanticId(org, ["co_org_20260909"], day)).toBe("co_org_20260909_2");
    expect(placeholderSemanticId(org, ["co_org_20260909", "co_org_20260909_2"], day)).toBe(
      "co_org_20260909_3",
    );
  });
});

describe("the kind table", () => {
  const day = new Date(2026, 8, 9);
  const alice = projectIdRule({ userId: "alice", isAdmin: false });

  it("gives Projects and Agents a bare snake_case id, repaired behind the noun when it would start with a digit or be one letter", () => {
    expect(fallbackSemanticId("Plugin Marketplace", SEMANTIC_ID_RULES.project)).toBe(
      "plugin_marketplace",
    );
    expect(fallbackSemanticId("Report Writer", SEMANTIC_ID_RULES.agent)).toBe("report_writer");
    expect(fallbackSemanticId("3D Viewer", SEMANTIC_ID_RULES.agent)).toBe("agent_3d_viewer");
    expect(fallbackSemanticId("x", SEMANTIC_ID_RULES.agent)).toBe("agent_x");
    expect(fallbackSemanticId("2026 Plan", SEMANTIC_ID_RULES.project)).toBe("project_2026_plan");
    expect(fallbackSemanticId("报告写手", SEMANTIC_ID_RULES.agent)).toBeNull();
    for (const kind of ["project", "agent"] as const) {
      expect(SEMANTIC_ID_RULES[kind].accepts("report_writer")).toBe(true);
      expect(SEMANTIC_ID_RULES[kind].accepts("2026_plan")).toBe(false);
    }
  });

  it("gives a Benchmark a kebab-case id, suffixed with a hyphen", () => {
    expect(fallbackSemanticId("Report Writing (hard) v1", SEMANTIC_ID_RULES.benchmark)).toBe(
      "report-writing-hard-v1",
    );
    // A model that answers in snake_case is folded into the kind's spelling.
    expect(sanitizeSuggestedId("`report_writing`", SEMANTIC_ID_RULES.benchmark)).toBe(
      "report-writing",
    );
    // Nothing to repair: a Benchmark id may start with a digit.
    expect(fallbackSemanticId("2026 eval", SEMANTIC_ID_RULES.benchmark)).toBe("2026-eval");
    expect(
      fallbackSemanticId("Report Writing", SEMANTIC_ID_RULES.benchmark, ["report-writing"]),
    ).toBe("report-writing-2");
    expect(uniqueSemanticId("a".repeat(64), ["a".repeat(64)], "-", 64)).toBe(`${"a".repeat(62)}-2`);
    expect(SEMANTIC_ID_RULES.benchmark.accepts("Report_writing-v1")).toBe(true);
    expect(SEMANTIC_ID_RULES.benchmark.accepts("../escape")).toBe(false);
  });

  it("puts a non-admin's Project in the owner's namespace, and leaves the admin's bare", () => {
    expect(projectIdRule({ userId: "root", isAdmin: true })).toBe(SEMANTIC_ID_RULES.project);
    expect(fallbackSemanticId("Research Lab", alice)).toBe("alice-research_lab");
    // The suffix may start with a digit: the namespace already starts the id with a letter.
    expect(fallbackSemanticId("2026 Plan", alice)).toBe("alice-2026_plan");
    expect(sanitizeSuggestedId("research_lab", alice, ["alice-research_lab"])).toBe(
      "alice-research_lab_2",
    );
    // The whole id stays within the Project id's cap, namespace included.
    const long = fallbackSemanticId("word ".repeat(30), alice);
    expect(long?.startsWith("alice-")).toBe(true);
    expect(long?.length).toBeLessThanOrEqual(64);
    expect(alice.accepts(long!)).toBe(true);
    expect(alice.accepts("bob-research_lab")).toBe(false);
    expect(alice.accepts("research_lab")).toBe(false);
  });

  it("dates a placeholder behind every kind's own noun and prefix", () => {
    expect(placeholderSemanticId(SEMANTIC_ID_RULES.project, [], day)).toBe("project_20260909");
    expect(placeholderSemanticId(alice, [], day)).toBe("alice-project_20260909");
    expect(placeholderSemanticId(SEMANTIC_ID_RULES.agent, ["agent_20260909"], day)).toBe(
      "agent_20260909_2",
    );
    expect(placeholderSemanticId(SEMANTIC_ID_RULES.benchmark, ["benchmark-20260909"], day)).toBe(
      "benchmark-20260909-2",
    );
    for (const kind of ["org", "channel", "project", "agent", "benchmark"] as const) {
      expect(
        SEMANTIC_ID_RULES[kind].accepts(placeholderSemanticId(SEMANTIC_ID_RULES[kind], [], day)),
        kind,
      ).toBe(true);
    }
  });
});