A local-first multi-agent app development platform, built on PenguinHarness
/**
* A semantic id derived from a display name without a model (pure, unit tested): the ASCII
* fallback of `suggest-id`, and the sanitizer every model answer passes through before it is
* offered. Diacritics are folded (`Café` → `cafe`), every run of anything but a letter or digit
* becomes one separator, and the result is lowercased. What the id then has to look like is
* the kind's, and one table says it for every kind a create dialog names:
*
* | kind | prefix | words joined | the id the create route accepts |
* | ----------- | -------------------- | ------------ | ---------------------------------------- |
* | `org` | `co_` | `_` | `^[a-z][a-z0-9_]{1,63}$` |
* | `channel` | `ch_` | `_` | `^[a-z][a-z0-9_]{1,63}$` |
* | `project` | none (admin) | `_` | `^[a-z][a-z0-9_]{1,63}$` |
* | `project` | `<username>-` (user) | `_` | `<username>-[a-z0-9_]+`, 64 at most |
* | `agent` | none | `_` | `^[a-z][a-z0-9_]{1,63}$` |
* | `benchmark` | none | `-` | letters, digits, `_` and `-`; 100 at most |
*
* The organization's and the channel's prefix says what an id names and makes every core a
* valid id; a core that already carries it is not prefixed twice. A non-admin's Project id
* lives in its owner's namespace, so that prefix is the username the route already demands,
* not a convention. A Benchmark id is kebab-case, like the ones the evaluation Skills write.
* The prefixes are a generator's convention, not a rule the server enforces: an id typed by
* hand is accepted as written, and ids that predate them keep working.
*
* A core the kind still rejects — an unprefixed id that would start with a digit, or a
* one-letter one — is tried once more behind the kind's noun (`3D Viewer` → `agent_3d_viewer`),
* which keeps the words rather than discarding a name that did carry ASCII. A name with no
* ASCII letters or digits at all (a Chinese name) yields null: nothing mechanical can name it,
* and that is exactly the case the model exists for. When the model cannot name it either,
* `placeholderSemanticId` is the floor — a valid, dated, obviously-temporary id, so the dialog
* is never left with nothing to put in the box.
*/
import { isValidId } from "@adelie/core";
import type { SemanticIdKind } from "../api/types.js";
import { PROJECT_ID_MAX_LENGTH, PROJECT_SUFFIX_PATTERN, SEMANTIC_ID_PATTERN } from "./ids.js";
/** What a kind's id looks like: everything the generator, the sanitizer and the prompt need. */
export interface SemanticIdRule {
/** Put in front of every generated id; "" for none. */
prefix: string;
/** What joins the words of an id: `_` (snake_case) or `-` (kebab-case). */
separator: "_" | "-";
/** The longest id the generator produces (never longer than the create route accepts). */
maxLength: number;
/** Whether the create route accepts an id. */
accepts: (id: string) => boolean;
/** The word a placeholder carries, and the word a core the rule rejects is put behind. */
noun: string;
/** The prompt's examples, in this kind's own spelling (see semantic-id-suggest.ts). */
examples: string;
}
const snakeCaseId = (id: string): boolean => SEMANTIC_ID_PATTERN.test(id);
const SNAKE_EXAMPLES =
"Plugin Marketplace → plugin_marketplace; 科研论文公司 → research_paper_lab; 市场推广 → marketing; Site → site.";
/** The kind table (see the module header); a non-admin's Project rule is {@link projectIdRule}. */
export const SEMANTIC_ID_RULES: Record<SemanticIdKind, SemanticIdRule> = {
org: {
prefix: "co_",
separator: "_",
maxLength: 64,
accepts: snakeCaseId,
noun: "org",
examples: SNAKE_EXAMPLES,
},
channel: {
prefix: "ch_",
separator: "_",
maxLength: 64,
accepts: snakeCaseId,
noun: "channel",
examples: SNAKE_EXAMPLES,
},
project: {
prefix: "",
separator: "_",
maxLength: 64,
accepts: snakeCaseId,
noun: "project",
examples:
"Plugin Marketplace → plugin_marketplace; 科研论文项目 → research_papers; 官网改版 → website_redesign; Site → site.",
},
agent: {
prefix: "",
separator: "_",
maxLength: 64,
accepts: snakeCaseId,
noun: "agent",
examples:
"Report Writer → report_writer; 金融助手 → finance_copilot; 深度研究报告智能体 → deep_research_reporter; Notes → notes.",
},
benchmark: {
prefix: "",
separator: "-",
maxLength: 64,
accepts: (id) => id.length <= 100 && isValidId(id),
noun: "benchmark",
examples:
"Report Writing → report-writing; 代码审查能力 → code-review; 深度研究 v2 → deep-research-v2; SQL → sql.",
},
};
/**
* A Project id as `userId` may create it: the admin's is a plain semantic id, anyone else's is
* `<userId>-<suffix>` within the length cap — the rule `POST /api/projects` enforces.
*/
export function projectIdRule(user: { userId: string; isAdmin: boolean }): SemanticIdRule {
const base = SEMANTIC_ID_RULES.project;
if (user.isAdmin) return base;
const prefix = `${user.userId}-`;
return {
...base,
prefix,
maxLength: PROJECT_ID_MAX_LENGTH,
accepts: (id) =>
id.startsWith(prefix) &&
PROJECT_SUFFIX_PATTERN.test(id.slice(prefix.length)) &&
id.length <= PROJECT_ID_MAX_LENGTH,
};
}
/** The ASCII core of a name: folded, lowercased, joined by `separator`; "" when nothing survives. */
function asciiCore(name: string, separator: "_" | "-"): string {
return name
.normalize("NFKD")
.replace(/[̀-ͯ]/g, "")
.toLowerCase()
.replace(/[^a-z0-9]+/g, separator)
.replace(/^[_-]+|[_-]+$/g, "");
}
/**
* `base`, or the first `base_2`, `base_3`, … (`base-2` for a kebab-case kind) that `taken` does
* not hold; the suffix never pushes the id past the length cap.
*/
export function uniqueSemanticId(
base: string,
taken: Iterable<string>,
separator: "_" | "-",
maxLength: number,
): string {
const used = new Set(taken);
if (!used.has(base)) return base;
for (let n = 2; ; n += 1) {
const suffix = `${separator}${n}`;
const candidate = `${base.slice(0, maxLength - suffix.length)}${suffix}`;
if (!used.has(candidate)) return candidate;
}
}
/** The core with the rule's prefix in front, or unchanged when it already starts with it. */
export function prefixSemanticId(core: string, rule: SemanticIdRule): string {
return core.startsWith(rule.prefix) ? core : `${rule.prefix}${core}`;
}
/** The prefixed core capped at the kind's length — prefix first, so it survives a long name — with no trailing separator. */
function capped(core: string, rule: SemanticIdRule): string {
return prefixSemanticId(core, rule)
.slice(0, rule.maxLength)
.replace(/[_-]+$/, "");
}
/**
* A valid semantic id for a name, or null when the name carries nothing an ASCII id can be
* built from. Never returns an id in `taken`.
*/
export function fallbackSemanticId(
name: string,
rule: SemanticIdRule,
taken: Iterable<string> = [],
): string | null {
const core = asciiCore(name, rule.separator);
if (core === "") return null;
let id = capped(core, rule);
if (!rule.accepts(id)) id = capped(`${rule.noun}${rule.separator}${core}`, rule);
if (!rule.accepts(id)) return null;
return uniqueSemanticId(id, taken, rule.separator, rule.maxLength);
}
/**
* What a model's answer becomes: its first line, stripped of quotes and code marks, run
* through the same folding and prefixing as a name — so a model that answers `research_lab`
* yields `co_research_lab`, one that answers `` `Research Lab` `` yields the same, one that
* answers `co_research_lab` is not prefixed twice, and one that answers in Chinese yields
* null and the caller falls back.
*/
export function sanitizeSuggestedId(
answer: string,
rule: SemanticIdRule,
taken: Iterable<string> = [],
): string | null {
const line = answer
.split("\n")
.map((l) => l.trim())
.find((l) => l !== "");
if (line === undefined) return null;
return fallbackSemanticId(line.replace(/^[`"'“”‘’]+|[`"'“”‘’.]+$/g, ""), rule, taken);
}
/** `yyyymmdd` in the host's own local date, the stamp a placeholder id carries. */
function dateStamp(now: Date): string {
const pad = (n: number): string => String(n).padStart(2, "0");
return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}`;
}
/**
* The id a name that neither the model nor the ASCII fallback can name gets: the kind's noun
* and the date behind its prefix — `co_org_<yyyymmdd>`, `ch_channel_<yyyymmdd>`,
* `agent_<yyyymmdd>`, `benchmark-<yyyymmdd>` — made unique against `taken`. It names nothing —
* that is the point. It is valid, so the dialog can go on, and it reads as temporary at a
* glance, so the surface that fills it in can ask for a meaningful name in its place. Refusing
* instead would leave the user of a Chinese-named object with no model configured staring at
* a dialog that cannot be completed.
*/
export function placeholderSemanticId(
rule: SemanticIdRule,
taken: Iterable<string> = [],
now: Date = new Date(),
): string {
return uniqueSemanticId(
prefixSemanticId(`${rule.noun}${rule.separator}${dateStamp(now)}`, rule),
taken,
rule.separator,
rule.maxLength,
);
}