@jitsusama/agentic-harness.core 0.1.0

package/dist/internal/lsp/registry.d.ts

@@ -0,0 +1,12 @@
+/**
+ * LSP backend registry: process-global map from backend name to
+ * `LspBackendEntry`. Mirrors the refs, terminal and tree
+ * libraries; uses the same shared `createGlobalSymbolRegistry`
+ * helper.
+ */
+import type { LspBackendEntry } from "../../lsp/types.js";
+export declare const register: (entry: LspBackendEntry) => void;
+export declare const unregister: (name: string) => void;
+export declare const clear: () => void;
+export declare const get: (name: string) => LspBackendEntry | undefined;
+export declare const list: () => LspBackendEntry[];

package/dist/internal/lsp/registry.js

@@ -0,0 +1,16 @@
+/**
+ * LSP backend registry: process-global map from backend name to
+ * `LspBackendEntry`. Mirrors the refs, terminal and tree
+ * libraries; uses the same shared `createGlobalSymbolRegistry`
+ * helper.
+ */
+import { createGlobalSymbolRegistry } from "../registry/global-symbol-registry.js";
+const registry = createGlobalSymbolRegistry({
+    slot: "pi:agentic-harness:lsp-backends",
+    getId: (entry) => entry.name,
+});
+export const register = (entry) => registry.register(entry);
+export const unregister = (name) => registry.unregister(name);
+export const clear = () => registry.clear();
+export const get = (name) => registry.get(name);
+export const list = () => registry.list();

package/dist/internal/notes/discovery.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Notes discovery: walk a notes root on disk and build an
+ * in-memory index.
+ *
+ * Canonical disk layout (within `notesRoot`):
+ *
+ *     NOTE-20130120-3MX6UQ/
+ *       README.md
+ *       attachment-1.jpg
+ *     NOTE-20260822-AJ1W97/           (parent of the note
+ *       README.md                       above, via its own
+ *                                        `parent:` field --
+ *                                        lives flat at the
+ *                                        notes root, not
+ *                                        nested in its
+ *                                        parent's directory)
+ *
+ * All notes live as immediate children of `notesRoot`.
+ * Hierarchy is expressed by the `parent:` front-matter field
+ * on each note, not by directory nesting -- the same
+ * invariant quest enforces for its own tree
+ * (`internal/quest/discovery.ts`), and for the same reason:
+ * a note's location on disk should never need to change just
+ * because its place in a hierarchy does.
+ *
+ * A directory whose name doesn't match the `NOTE-*` id shape
+ * is skipped, not an error -- `.git`, `.claude`, scratch
+ * directories and the like are expected to sit alongside the
+ * notes.
+ */
+import type { NoteDoc } from "../../notes/types.js";
+/** One discovered note. */
+export interface NoteEntry {
+    /** The note's directory name, equal to its id. */
+    dir: string;
+    doc: NoteDoc;
+}
+/** The whole tree, indexed for lookup and hierarchy traversal. */
+export interface NoteIndex {
+    /** Every discovered note by id. */
+    notes: Map<string, NoteEntry>;
+    /**
+     * Parent-to-children adjacency. The empty key `""` holds
+     * every note with no `parent` set.
+     */
+    children: Map<string, string[]>;
+}
+interface DiscoveryError {
+    dir: string;
+    message: string;
+}
+/** Result of a discovery walk. */
+export interface DiscoveryResult {
+    index: NoteIndex;
+    errors: DiscoveryError[];
+}
+/** Walk `notesRoot` and build a `NoteIndex` of every note found. */
+export declare function discoverNotes(notesRoot: string): DiscoveryResult;
+export {};

package/dist/internal/notes/discovery.js

@@ -0,0 +1,91 @@
+/**
+ * Notes discovery: walk a notes root on disk and build an
+ * in-memory index.
+ *
+ * Canonical disk layout (within `notesRoot`):
+ *
+ *     NOTE-20130120-3MX6UQ/
+ *       README.md
+ *       attachment-1.jpg
+ *     NOTE-20260822-AJ1W97/           (parent of the note
+ *       README.md                       above, via its own
+ *                                        `parent:` field --
+ *                                        lives flat at the
+ *                                        notes root, not
+ *                                        nested in its
+ *                                        parent's directory)
+ *
+ * All notes live as immediate children of `notesRoot`.
+ * Hierarchy is expressed by the `parent:` front-matter field
+ * on each note, not by directory nesting -- the same
+ * invariant quest enforces for its own tree
+ * (`internal/quest/discovery.ts`), and for the same reason:
+ * a note's location on disk should never need to change just
+ * because its place in a hierarchy does.
+ *
+ * A directory whose name doesn't match the `NOTE-*` id shape
+ * is skipped, not an error -- `.git`, `.claude`, scratch
+ * directories and the like are expected to sit alongside the
+ * notes.
+ */
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseNoteFrontMatter } from "./frontmatter.js";
+import { isId } from "./id.js";
+function readMaybe(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Walk `notesRoot` and build a `NoteIndex` of every note found. */
+export function discoverNotes(notesRoot) {
+    const notes = new Map();
+    const children = new Map();
+    const errors = [];
+    let entries;
+    try {
+        entries = readdirSync(notesRoot, { withFileTypes: true })
+            .filter((e) => e.isDirectory() && isId(e.name))
+            .map((e) => e.name);
+    }
+    catch (err) {
+        errors.push({
+            dir: notesRoot,
+            message: err instanceof Error ? err.message : String(err),
+        });
+        return { index: { notes, children }, errors };
+    }
+    for (const dir of entries) {
+        const readmePath = join(notesRoot, dir, "README.md");
+        const text = readMaybe(readmePath);
+        if (text === undefined) {
+            errors.push({ dir, message: `missing ${readmePath}` });
+            continue;
+        }
+        const parsed = parseNoteFrontMatter(text);
+        if (!parsed) {
+            errors.push({ dir, message: "invalid or missing front matter" });
+            continue;
+        }
+        if (parsed.frontMatter.id !== dir) {
+            errors.push({
+                dir,
+                message: `front-matter id "${parsed.frontMatter.id}" does not match directory name`,
+            });
+            continue;
+        }
+        notes.set(dir, { dir, doc: parsed });
+    }
+    for (const entry of notes.values()) {
+        const parentKey = entry.doc.frontMatter.parent ?? "";
+        const list = children.get(parentKey) ?? [];
+        list.push(entry.dir);
+        children.set(parentKey, list);
+    }
+    for (const list of children.values())
+        list.sort();
+    return { index: { notes, children }, errors };
+}

package/dist/internal/notes/frontmatter.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Front-matter parser and serializer for note READMEs.
+ *
+ * The block is YAML between two `---` fences. We use the
+ * `yaml` library for both directions rather than hand-rolled
+ * regex parsing, the same choice quest's own frontmatter
+ * module makes (`internal/quest/frontmatter.ts`) and for the
+ * same reason: a title or source string containing a colon,
+ * a quote, or a backslash is exactly the kind of value a
+ * regex-based reader/writer round-trips incorrectly, and
+ * silently -- an earlier prototype of this library hand-rolled
+ * its own escaping and produced titles with accumulating
+ * doubled backslashes on repeated edits before this was
+ * caught. A real YAML parser has no such failure mode.
+ *
+ * Validation rules:
+ *
+ * - `id`, `type`, `title`, `created`, `updated` are
+ *   required; a missing or invalid one makes the whole parse
+ *   fail so callers surface a clean error instead of writing
+ *   back a corrupted file.
+ * - `type` is a strict enum; an unrecognised value fails
+ *   the parse rather than being coerced to a guess.
+ * - `tags` defaults to `[]` rather than being omitted, so
+ *   callers never have to distinguish "no tags" from "tags
+ *   field missing".
+ * - `parent` and `source` are optional and only appear in
+ *   the serialized output when set.
+ */
+import { type NoteFrontMatter } from "../../notes/types.js";
+/** Split a note's text into its raw front-matter YAML and body. */
+export declare function splitFrontMatter(text: string): {
+    fmText: string;
+    body: string;
+} | undefined;
+/** Reasons a front-matter block might fail to parse, for a caller to surface. */
+export declare function noteFrontMatterProblem(text: string): string | undefined;
+/** Parse a note's full text into front matter plus body, or `undefined` if invalid. */
+export declare function parseNoteFrontMatter(text: string): {
+    frontMatter: NoteFrontMatter;
+    body: string;
+} | undefined;
+/**
+ * Serialize front matter back to a YAML block, in a fixed
+ * field order (id, type, title, created, updated, tags,
+ * parent, source) so a diff on a note that only changed one
+ * field's value shows one changed line, not a reordered
+ * block.
+ */
+export declare function serializeNoteFrontMatter(fm: NoteFrontMatter): string;
+/** Assemble a note's full file text from front matter and body. */
+export declare function serializeNote(fm: NoteFrontMatter, body: string): string;

package/dist/internal/notes/frontmatter.js

@@ -0,0 +1,163 @@
+/**
+ * Front-matter parser and serializer for note READMEs.
+ *
+ * The block is YAML between two `---` fences. We use the
+ * `yaml` library for both directions rather than hand-rolled
+ * regex parsing, the same choice quest's own frontmatter
+ * module makes (`internal/quest/frontmatter.ts`) and for the
+ * same reason: a title or source string containing a colon,
+ * a quote, or a backslash is exactly the kind of value a
+ * regex-based reader/writer round-trips incorrectly, and
+ * silently -- an earlier prototype of this library hand-rolled
+ * its own escaping and produced titles with accumulating
+ * doubled backslashes on repeated edits before this was
+ * caught. A real YAML parser has no such failure mode.
+ *
+ * Validation rules:
+ *
+ * - `id`, `type`, `title`, `created`, `updated` are
+ *   required; a missing or invalid one makes the whole parse
+ *   fail so callers surface a clean error instead of writing
+ *   back a corrupted file.
+ * - `type` is a strict enum; an unrecognised value fails
+ *   the parse rather than being coerced to a guess.
+ * - `tags` defaults to `[]` rather than being omitted, so
+ *   callers never have to distinguish "no tags" from "tags
+ *   field missing".
+ * - `parent` and `source` are optional and only appear in
+ *   the serialized output when set.
+ */
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { NOTE_TYPES } from "../../notes/types.js";
+/** Split a note's text into its raw front-matter YAML and body. */
+export function splitFrontMatter(text) {
+    const lines = text.split("\n");
+    if (lines[0]?.trim() !== "---")
+        return undefined;
+    let end = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === "---") {
+            end = i;
+            break;
+        }
+    }
+    if (end === -1)
+        return undefined;
+    const fmText = lines.slice(1, end).join("\n");
+    let body = lines.slice(end + 1).join("\n");
+    if (body.startsWith("\n"))
+        body = body.slice(1);
+    return { fmText, body };
+}
+function parseFrontMatterBlock(text) {
+    const split = splitFrontMatter(text);
+    if (!split)
+        return undefined;
+    let raw;
+    try {
+        raw = parseYaml(split.fmText) ?? {};
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return undefined;
+    }
+    return raw;
+}
+function asEnum(value, options) {
+    if (typeof value !== "string")
+        return undefined;
+    return options.includes(value) ? value : undefined;
+}
+function asString(value) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    // created/updated timestamps and ids are always strings on write, but
+    // a hand-edited file could plausibly leave one unquoted; YAML would
+    // then hand back a number or Date for some shapes. Round-trip those
+    // back to string rather than failing the whole parse over it.
+    if (typeof value === "number")
+        return String(value);
+    return undefined;
+}
+function asStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((v) => typeof v === "string" && v.length > 0);
+}
+/** Reasons a front-matter block might fail to parse, for a caller to surface. */
+export function noteFrontMatterProblem(text) {
+    const raw = parseFrontMatterBlock(text);
+    if (!raw)
+        return "no valid front-matter block (missing --- fences or invalid YAML)";
+    if (!asString(raw.id))
+        return "missing or invalid id";
+    if (!asEnum(raw.type, NOTE_TYPES)) {
+        return `missing or invalid type (must be one of: ${NOTE_TYPES.join(", ")})`;
+    }
+    if (!asString(raw.title))
+        return "missing or invalid title";
+    if (!asString(raw.created))
+        return "missing or invalid created";
+    if (!asString(raw.updated))
+        return "missing or invalid updated";
+    return undefined;
+}
+/** Parse a note's full text into front matter plus body, or `undefined` if invalid. */
+export function parseNoteFrontMatter(text) {
+    const split = splitFrontMatter(text);
+    if (!split)
+        return undefined;
+    const raw = parseFrontMatterBlock(text);
+    if (!raw)
+        return undefined;
+    const id = asString(raw.id);
+    const type = asEnum(raw.type, NOTE_TYPES);
+    const title = asString(raw.title);
+    const created = asString(raw.created);
+    const updated = asString(raw.updated);
+    if (!id || !type || !title || !created || !updated)
+        return undefined;
+    const frontMatter = {
+        id,
+        type,
+        title,
+        created,
+        updated,
+        tags: asStringArray(raw.tags),
+    };
+    const parent = asString(raw.parent);
+    if (parent)
+        frontMatter.parent = parent;
+    const source = asString(raw.source);
+    if (source)
+        frontMatter.source = source;
+    return { frontMatter, body: split.body };
+}
+/**
+ * Serialize front matter back to a YAML block, in a fixed
+ * field order (id, type, title, created, updated, tags,
+ * parent, source) so a diff on a note that only changed one
+ * field's value shows one changed line, not a reordered
+ * block.
+ */
+export function serializeNoteFrontMatter(fm) {
+    const ordered = {
+        id: fm.id,
+        type: fm.type,
+        title: fm.title,
+        created: fm.created,
+        updated: fm.updated,
+        tags: fm.tags,
+    };
+    if (fm.parent)
+        ordered.parent = fm.parent;
+    if (fm.source)
+        ordered.source = fm.source;
+    return stringifyYaml(ordered, { lineWidth: 0 }).trimEnd();
+}
+/** Assemble a note's full file text from front matter and body. */
+export function serializeNote(fm, body) {
+    return `---\n${serializeNoteFrontMatter(fm)}\n---\n\n${body.replace(/^\n+/, "")}`;
+}

package/dist/internal/notes/id.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Note ID minting and validation.
+ *
+ * IDs are deterministic in shape, random in suffix, the same
+ * pattern quest uses for its own ids (see
+ * `internal/quest/id.ts`):
+ *
+ *     NOTE-YYYYMMDD-XXXXXX
+ *
+ * `YYYYMMDD` is the note's creation date (local timezone, or
+ * whatever the original source recorded) so ids sort
+ * chronologically by construction. `XXXXXX` is a
+ * six-character base-36 (upper) random suffix, giving
+ * roughly 2.18 billion distinct ids per day -- collisions in
+ * practice require an explicit check, not a probability
+ * argument.
+ *
+ * Unlike quest, there is exactly one prefix here: a note
+ * owns no child documents of a different kind, so there is
+ * nothing for a second prefix to distinguish.
+ */
+/**
+ * Mint a fresh id. `date` defaults to now; tests and
+ * backdated imports pass a fixed date so the `YYYYMMDD`
+ * portion reflects the note's real creation date rather than
+ * the moment it was minted.
+ */
+export declare function mintId(date?: Date): string;
+/**
+ * Mint a fresh id from an already-formatted `YYYYMMDD` (or
+ * longer, e.g. `YYYYMMDDTHHMMSSZ`) string, the shape a note's
+ * own `created` front-matter field is in. Falls back to
+ * today's date when the string doesn't start with eight
+ * digits, rather than throwing -- a malformed or missing
+ * `created` field on import is a data-quality problem to
+ * flag separately, not a reason to refuse minting an id.
+ */
+export declare function mintIdFromDateString(dateString: string | undefined): string;
+/** Quick validation: is this string a valid note id? */
+export declare function isId(text: string): boolean;
+/** Extract the `YYYYMMDD` date portion from an id, or `undefined`. */
+export declare function dateOf(id: string): string | undefined;

package/dist/internal/notes/id.js

@@ -0,0 +1,80 @@
+/**
+ * Note ID minting and validation.
+ *
+ * IDs are deterministic in shape, random in suffix, the same
+ * pattern quest uses for its own ids (see
+ * `internal/quest/id.ts`):
+ *
+ *     NOTE-YYYYMMDD-XXXXXX
+ *
+ * `YYYYMMDD` is the note's creation date (local timezone, or
+ * whatever the original source recorded) so ids sort
+ * chronologically by construction. `XXXXXX` is a
+ * six-character base-36 (upper) random suffix, giving
+ * roughly 2.18 billion distinct ids per day -- collisions in
+ * practice require an explicit check, not a probability
+ * argument.
+ *
+ * Unlike quest, there is exactly one prefix here: a note
+ * owns no child documents of a different kind, so there is
+ * nothing for a second prefix to distinguish.
+ */
+import { randomBytes } from "node:crypto";
+const PREFIX = "NOTE";
+// YYYY: 1900-2999. MM: 01-12. DD: 01-31. Shape check, not a
+// calendar validator -- rejects the obvious garbage
+// (00000000, 20261345) a bare `\d{8}` would accept, without
+// the cost of real calendar math nothing here needs.
+const DATE_PATTERN = "(?:19|2[0-9])\\d{2}(?:0[1-9]|1[0-2])(?:0[1-9]|[12]\\d|3[01])";
+const ID_REGEX = new RegExp(`^${PREFIX}-(${DATE_PATTERN})-([0-9A-Z]{6})$`);
+function pad(n) {
+    return String(n).padStart(2, "0");
+}
+function ymd(date) {
+    return `${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}`;
+}
+/** Build a six-character base-36 uppercase random suffix. */
+function randomSuffix() {
+    const bytes = randomBytes(6);
+    const out = [];
+    for (let i = 0; i < 6; i++) {
+        out.push((bytes[i] % 36).toString(36).toUpperCase());
+    }
+    return out.join("");
+}
+/**
+ * Mint a fresh id. `date` defaults to now; tests and
+ * backdated imports pass a fixed date so the `YYYYMMDD`
+ * portion reflects the note's real creation date rather than
+ * the moment it was minted.
+ */
+export function mintId(date = new Date()) {
+    return `${PREFIX}-${ymd(date)}-${randomSuffix()}`;
+}
+/**
+ * Mint a fresh id from an already-formatted `YYYYMMDD` (or
+ * longer, e.g. `YYYYMMDDTHHMMSSZ`) string, the shape a note's
+ * own `created` front-matter field is in. Falls back to
+ * today's date when the string doesn't start with eight
+ * digits, rather than throwing -- a malformed or missing
+ * `created` field on import is a data-quality problem to
+ * flag separately, not a reason to refuse minting an id.
+ */
+export function mintIdFromDateString(dateString) {
+    const match = dateString?.match(/^(\d{8})/);
+    const datePart = match?.[1];
+    if (!datePart)
+        return mintId();
+    const year = Number(datePart.slice(0, 4));
+    const month = Number(datePart.slice(4, 6));
+    const day = Number(datePart.slice(6, 8));
+    return mintId(new Date(year, month - 1, day));
+}
+/** Quick validation: is this string a valid note id? */
+export function isId(text) {
+    return ID_REGEX.test(text);
+}
+/** Extract the `YYYYMMDD` date portion from an id, or `undefined`. */
+export function dateOf(id) {
+    return ID_REGEX.exec(id)?.[1];
+}

package/dist/internal/notes/io.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Atomic file writes for note READMEs.
+ *
+ * The "read text, parse, mutate, write text" sequence every
+ * mutating verb runs is not atomic against a concurrent
+ * reader on a slow disk: a naive write can leave a reader
+ * seeing half a file. We write to a sibling temp file, fsync,
+ * then rename over the target, so an observer always sees
+ * the old or the new file in full -- the same pattern quest
+ * uses (`internal/quest/io.ts`).
+ *
+ * Unlike quest, there is no cross-process lock here. Quest
+ * needs one because two pi sessions can legitimately attach
+ * to and mutate the same quest concurrently; a notes archive
+ * has no equivalent multi-writer scenario -- it's a single
+ * user's single-writer CLI. If that ever changes, port
+ * quest's `withQuestLock` rather than inventing a new one.
+ */
+/**
+ * Write `data` to `path` atomically: write to a sibling temp
+ * file in the same directory, fsync, then rename. The rename
+ * is atomic on POSIX filesystems for files on the same
+ * volume, which a sibling temp file always is.
+ */
+export declare function atomicWriteFile(path: string, data: string): void;

package/dist/internal/notes/io.js

@@ -0,0 +1,51 @@
+/**
+ * Atomic file writes for note READMEs.
+ *
+ * The "read text, parse, mutate, write text" sequence every
+ * mutating verb runs is not atomic against a concurrent
+ * reader on a slow disk: a naive write can leave a reader
+ * seeing half a file. We write to a sibling temp file, fsync,
+ * then rename over the target, so an observer always sees
+ * the old or the new file in full -- the same pattern quest
+ * uses (`internal/quest/io.ts`).
+ *
+ * Unlike quest, there is no cross-process lock here. Quest
+ * needs one because two pi sessions can legitimately attach
+ * to and mutate the same quest concurrently; a notes archive
+ * has no equivalent multi-writer scenario -- it's a single
+ * user's single-writer CLI. If that ever changes, port
+ * quest's `withQuestLock` rather than inventing a new one.
+ */
+import { closeSync, fsyncSync, openSync, renameSync, unlinkSync, writeSync, } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Write `data` to `path` atomically: write to a sibling temp
+ * file in the same directory, fsync, then rename. The rename
+ * is atomic on POSIX filesystems for files on the same
+ * volume, which a sibling temp file always is.
+ */
+export function atomicWriteFile(path, data) {
+    const dir = dirname(path);
+    const tmp = join(dir, `.${path.split("/").pop()}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 10)}`);
+    const fd = openSync(tmp, "w");
+    try {
+        writeSync(fd, data);
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    try {
+        renameSync(tmp, path);
+    }
+    catch (err) {
+        try {
+            unlinkSync(tmp);
+        }
+        catch {
+            // Best-effort cleanup; the temp's leftover state is
+            // safe to leave in place and is not user-visible.
+        }
+        throw err;
+    }
+}

package/dist/internal/notes/sanitize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Filesystem-safe filename sanitizing.
+ *
+ * Unrelated to quest's `internal/quest/sanitize.ts`, which
+ * defends against prompt injection in text the agent reads
+ * back. This one has a narrower, mechanical job: take a
+ * human title (from an import, or typed by a caller) and
+ * produce something every filesystem this tool runs on can
+ * actually name a file, without silently truncating or
+ * colliding.
+ */
+/**
+ * Sanitize a string for use as a filename component (not a
+ * full path -- callers add their own extension/directory).
+ * Collapses whitespace, strips characters invalid on
+ * Windows/macOS/Linux filesystems, trims trailing dots and
+ * spaces (Windows rejects both), and clamps length.
+ */
+export declare function sanitizeFilename(name: string, maxLen?: number): string;

package/dist/internal/notes/sanitize.js

@@ -0,0 +1,35 @@
+/**
+ * Filesystem-safe filename sanitizing.
+ *
+ * Unrelated to quest's `internal/quest/sanitize.ts`, which
+ * defends against prompt injection in text the agent reads
+ * back. This one has a narrower, mechanical job: take a
+ * human title (from an import, or typed by a caller) and
+ * produce something every filesystem this tool runs on can
+ * actually name a file, without silently truncating or
+ * colliding.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: intentionally stripping control characters from filenames, not matching them as text
+const INVALID_CHARS_RE = /[/\\:*?"<>|\x00-\x1f]/g;
+const WHITESPACE_RE = /\s+/g;
+/**
+ * Sanitize a string for use as a filename component (not a
+ * full path -- callers add their own extension/directory).
+ * Collapses whitespace, strips characters invalid on
+ * Windows/macOS/Linux filesystems, trims trailing dots and
+ * spaces (Windows rejects both), and clamps length.
+ */
+export function sanitizeFilename(name, maxLen = 150) {
+    // Whitespace normalizes first: \x00-\x1f in INVALID_CHARS_RE
+    // includes tab, so running that pass first would turn each tab
+    // into its own literal "-" (two tabs -> "--") instead of
+    // collapsing the run into a single space the way a space or
+    // newline run does.
+    const cleaned = name
+        .trim()
+        .replace(WHITESPACE_RE, " ")
+        .replace(INVALID_CHARS_RE, "-")
+        .trim()
+        .replace(/[. ]+$/, "");
+    return (cleaned || "file").slice(0, maxLen);
+}

package/dist/internal/process-global.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Process-global singletons shared across module instances.
+ *
+ * A host that loads a library's modules more than once per process
+ * (pi loads each extension as its own module instance) does not get
+ * one registry from a module-level `const registry = new Map()`: each
+ * loader that imports the module gets its own. Anything one caller
+ * writes and another reads (a recorder sink, a prompt contributor, an
+ * LSP backend, the shared browser) must therefore live on
+ * `globalThis` under a shared key rather than in a module variable.
+ * `Symbol.for` gives every module instance the same key, and
+ * `globalThis` is shared across them, so the value is genuinely one
+ * per process.
+ */
+/**
+ * Get the process-global value for `key`, creating it once with
+ * `create` on first access. Every caller in the process, in any
+ * module instance, receives the same value.
+ */
+export declare function processGlobal<T>(key: string, create: () => T): T;