@stratusagent/agents 0.11.4 → 0.11.5

package/dist/define.d.ts

@@ -0,0 +1,22 @@
+import type { ListensMode, AgentDefinition, AvatarTheme } from '@stratusagent/core';
+export interface DefineAgentInput {
+    name?: string;
+    id?: string;
+    instructions?: string;
+    tools?: string[];
+    skills?: string[];
+    credentials?: string[];
+    delegates?: string[];
+    /** See `AgentDefinition.listens`. */
+    listens?: ListensMode;
+    avatar?: AvatarTheme;
+    /** Seed for deterministic identity generation (used in tests). */
+    seed?: string;
+}
+/**
+ * One-call agent creation. Everything is optional: with no input you get a
+ * fresh identity with a human-ish name and a matching avatar theme.
+ * Explicitly named agents keep a clean, predictable slug id.
+ */
+export declare const defineAgent: (input?: DefineAgentInput) => AgentDefinition;
+//# sourceMappingURL=define.d.ts.map

package/dist/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAWpF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;IACrB,qCAAqC;IACrC,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;;;GAIG;AACH,eAAO,MAAM,WAAW,GAAI,QAAO,gBAAqB,KAAG,eA8D1D,CAAC"}

package/dist/define.js

@@ -0,0 +1,64 @@
+import { generateAgentName, generateAvatarTheme, slugify, isValidAgentId, isValidDelegateEntry, agentIdWithSuffix, generatedIdSuffix, } from "./identity.js";
+/**
+ * One-call agent creation. Everything is optional: with no input you get a
+ * fresh identity with a human-ish name and a matching avatar theme.
+ * Explicitly named agents keep a clean, predictable slug id.
+ */
+export const defineAgent = (input = {}) => {
+    const nameWasGenerated = input.name === undefined;
+    const name = input.name ?? generateAgentName(input.seed);
+    // Only an explicit id is checked: a derived one comes out of slugify,
+    // which cannot produce anything unsafe.
+    if (input.id === '*') {
+        // The wildcard was an accepted id until `delegates` gave it a meaning,
+        // so a soul written before then can still carry it. The path-safety
+        // message would be wrong for it — `*` breaks none of those rules — and
+        // the roster reports this error with the file's path, so name the real
+        // reason and the fix rather than leaving the operator to guess why an
+        // agent that loaded yesterday is skipped today.
+        throw new Error('Invalid agent id: "*". * is the delegates wildcard (delegates: [\'*\'] means any agent on the roster), '
+            + 'so no agent may have it as an id — give this agent another id. Its sessions, memory, and credentials '
+            + 'are keyed by the old id and stay on disk.');
+    }
+    if (input.id !== undefined && !isValidAgentId(input.id)) {
+        throw new Error(`Invalid agent id: ${JSON.stringify(input.id)}. An id becomes a path segment, so it may not start with `
+            + 'a dot or contain a slash, a backslash, a control character, or leading or trailing whitespace — '
+            + 'it keys files and credentials, not just labels.');
+    }
+    // Each entry is an id or the wildcard. Refused here, not in the tool: a
+    // list holding a value no agent can have would be a grant to nobody
+    // that read as a grant.
+    for (const entry of input.delegates ?? []) {
+        if (!isValidDelegateEntry(entry)) {
+            throw new Error(`Invalid delegates entry: ${JSON.stringify(entry)}. Each entry is an agent id, or * for any agent on the roster.`);
+        }
+    }
+    // A chosen name's slug is used whole. It is not this function's to
+    // shorten: the same name has resolved to the same id in every release,
+    // and two long names that differ only past the bound are two agents,
+    // not one roster-refusing collision.
+    const derived = nameWasGenerated
+        ? agentIdWithSuffix(slugify(name), generatedIdSuffix(input.seed))
+        : slugify(name);
+    return {
+        // Derived ids are safe by construction with one exception: `constructor`
+        // is a perfectly ordinary slug and an Object.prototype key, so the name
+        // "Constructor" reaches a rule that only ran on explicit ids. Checked
+        // rather than special-cased, so what this returns is *an id that
+        // validates* — not one that passes the cases anyone thought of. The
+        // suffix is seeded by the slug, so the name still answers the same way
+        // every time.
+        id: input.id ?? (isValidAgentId(derived)
+            ? derived
+            : agentIdWithSuffix(derived, generatedIdSuffix(derived))),
+        name,
+        ...(input.instructions ? { instructions: input.instructions } : {}),
+        avatar: input.avatar ?? generateAvatarTheme(name),
+        ...(input.tools ? { tools: input.tools } : {}),
+        ...(input.skills ? { skills: input.skills } : {}),
+        ...(input.credentials ? { credentials: input.credentials } : {}),
+        ...(input.delegates ? { delegates: input.delegates } : {}),
+        ...(input.listens ? { listens: input.listens } : {}),
+    };
+};
+//# sourceMappingURL=define.js.map

package/dist/define.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.js","sourceRoot":"","sources":["../src/define.ts"],"names":[],"mappings":"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"}

package/dist/frontmatter.d.ts

@@ -0,0 +1,65 @@
+export declare const unquote: (value: string) => string;
+interface FrontmatterShape {
+    /** Lowercased document kind for error messages ("soul", "skill"). */
+    kind: string;
+    scalarKeys: readonly string[];
+    listKeys: readonly string[];
+    /**
+     * Keys whose value is a block of `key: value` string pairs (the Agent
+     * Skills spec's `metadata:`). Read only in tolerant mode, which is the
+     * only dialect that writes one.
+     */
+    mapKeys?: readonly string[];
+    /**
+     * Ignore what the shape does not name instead of refusing it — unknown
+     * keys, whatever indented block sits under one, and the YAML block and
+     * multi-line scalars other ecosystems write.
+     *
+     * Skills opt in: they travel an ecosystem whose frontmatter carries
+     * fields other hosts own (`license`, `metadata`, `allowed-tools`), and
+     * refusing those would refuse most published skills over metadata that
+     * changes nothing here. Souls stay strict, deliberately — an unknown
+     * soul key can be a typo'd allowlist, and a soul that loads with
+     * silently weaker access is the worse failure.
+     */
+    tolerant?: boolean;
+}
+export interface ParsedFrontmatter {
+    scalars: Partial<Record<string, string>>;
+    lists: Partial<Record<string, string[]>>;
+    maps: Partial<Record<string, Record<string, string>>>;
+    /**
+     * Top-level keys the shape does not name, in file order. Tolerant mode
+     * skips them; this is how a validator still gets to say which ones it
+     * skipped, so a misspelled field is a warning somebody reads instead of
+     * silence.
+     */
+    unknownKeys: string[];
+}
+export declare const parseFrontmatterLines: (lines: string[], shape: FrontmatterShape) => ParsedFrontmatter;
+/**
+ * Split a markdown document into its `---`-fenced frontmatter lines (if
+ * any) and the body after them. Shared by souls and skills — one reading
+ * of what the fences mean, wherever the dialect appears.
+ */
+export declare const extractFrontmatter: (source: string, kind: string) => {
+    lines: string[] | undefined;
+    body: string;
+};
+/**
+ * Render an agent definition as a soul file, ready to save and edit. The
+ * inverse of parseSoul for round-tripping `stratus agent new` output.
+ */
+/**
+ * A scalar or list entry as the soul writer emits it. The parser strips
+ * one layer of matching quotes from every value, so a value that begins
+ * and ends with the same quote — an agent id like `'bea'`, which
+ * {@link isValidAgentId} allows — would come back as `bea`: for a
+ * `delegates` entry that is a permission changed by an unrelated edit,
+ * since the control API renders a soul through here on every field edit.
+ * Such a value is wrapped in the other quote, which the parser strips
+ * back off; so is one the parser's trim would alter.
+ */
+export declare const writeScalar: (value: string) => string;
+export {};
+//# sourceMappingURL=frontmatter.d.ts.map

package/dist/frontmatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.d.ts","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"AAqCA,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MAUvC,CAAC;AAEF,UAAU,gBAAgB;IACxB,qEAAqE;IACrE,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IAC9B,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IACzC,IAAI,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC;IACtD;;;;;OAKG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAOD,eAAO,MAAM,qBAAqB,GAAI,OAAO,MAAM,EAAE,EAAE,OAAO,gBAAgB,KAAG,iBA4LhF,CAAC;AAIF;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAC7B,QAAQ,MAAM,EACd,MAAM,MAAM,KACX;IAAE,KAAK,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAe7C,CAAC;AAEF;;;GAGG;AACH;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAC8C,CAAC"}

package/dist/frontmatter.js

@@ -0,0 +1,260 @@
+/**
+ * The entries of an inline list, `[a, 'b,c', "d"]`, split on the commas
+ * that are outside quotes. Splitting on every comma and unquoting after
+ * turned `['foo,bar']` into the two entries `'foo` and `bar'` — for a
+ * `delegates` list, a grant to two agents nobody meant and none to the
+ * one they did, from a soul that loaded without complaint.
+ */
+const splitInlineList = (inline) => {
+    const entries = [];
+    let current = '';
+    let quote;
+    for (const character of inline) {
+        // A quote opens an entry only at the entry's start (after any leading
+        // space): an apostrophe inside an unquoted id — o'brien — is part of
+        // the id, and reading it as an opening quote would swallow every comma
+        // after it into one entry no agent has.
+        if (quote === undefined && (character === '"' || character === "'") && current.trim().length === 0) {
+            quote = character;
+        }
+        else if (character === quote) {
+            quote = undefined;
+        }
+        else if (character === ',' && quote === undefined) {
+            entries.push(current);
+            current = '';
+            continue;
+        }
+        current += character;
+    }
+    // A quote left open would have swallowed every comma after it into one
+    // entry no agent has — for a delegates list, a typo that changes who is
+    // authorized while the soul loads without complaint. Refused instead.
+    if (quote !== undefined) {
+        return undefined;
+    }
+    entries.push(current);
+    return entries;
+};
+export const unquote = (value) => {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 &&
+        ((trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+            (trimmed.startsWith("'") && trimmed.endsWith("'")))) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+};
+// A deliberately tiny frontmatter dialect: `key: value` scalars and block
+// lists of `- item` lines. Enough for souls and skills, no YAML dependency.
+// Tolerant mode (see FrontmatterShape) additionally reads the block-scalar
+// forms (`description: >-` and friends) and plain multi-line scalars, and
+// skips unknown keys with their nested blocks.
+export const parseFrontmatterLines = (lines, shape) => {
+    const scalars = {};
+    const lists = {};
+    const maps = {};
+    const unknownKeys = [];
+    const tolerant = shape.tolerant ?? false;
+    let currentList;
+    let currentMap;
+    // Tolerant-mode line context: an unknown key whose indented block is
+    // being skipped, or a known scalar whose value continues on indented
+    // lines (a YAML block scalar, or a plain scalar that wraps). Inside
+    // either, blank lines and lines starting with # are content or skipped
+    // block — never the comments the top level treats them as — so both are
+    // handled before the comment filter below.
+    let skippingUnknownBlock = false;
+    let continuation;
+    const isIndented = (line) => /^\s/.test(line);
+    for (const rawLine of lines) {
+        const line = rawLine.trimEnd();
+        const blank = line.trim().length === 0;
+        if (tolerant && skippingUnknownBlock && (blank || isIndented(line))) {
+            continue;
+        }
+        if (tolerant && continuation) {
+            if (blank) {
+                // A blank line is a line break in a literal block and a paragraph
+                // break in a folded or plain one — never the end of the value.
+                if (continuation.literal) {
+                    const existing = scalars[continuation.key] ?? '';
+                    if (existing.length > 0) {
+                        scalars[continuation.key] = `${existing}\n`;
+                    }
+                }
+                else {
+                    continuation.pendingBreak = true;
+                }
+                continue;
+            }
+            if (isIndented(line)) {
+                const existing = scalars[continuation.key] ?? '';
+                const separator = continuation.literal || continuation.pendingBreak ? '\n' : ' ';
+                continuation.pendingBreak = false;
+                // The raw content, not unquote(): inside a block scalar a quote or
+                // a # is text, and YAML agrees.
+                const piece = line.trim();
+                scalars[continuation.key] = existing.length > 0 ? `${existing}${separator}${piece}` : piece;
+                continue;
+            }
+            // A non-indented line ends the value; fall through to read it.
+        }
+        if (blank || line.trim().startsWith('#')) {
+            continue;
+        }
+        if (currentMap && isIndented(line)) {
+            // One level of `key: value` pairs, every value a string — the
+            // spec's shape for `metadata`. Anything deeper is not a string
+            // value, and refusing it beats reading the wrong half of it.
+            // Any string is a key — quoted (`"vendor/key": v`), or bare up to
+            // the first colon — since the spec types the map as string to
+            // string and says nothing about what a key looks like.
+            const pair = /^\s+(?:"([^"]*)"|'([^']*)'|([^\s"'#][^:]*?))\s*:\s*(.*)$/.exec(line);
+            const mapKey = pair?.[1] ?? pair?.[2] ?? pair?.[3]?.trim();
+            if (!pair || mapKey === undefined || mapKey.length === 0 || pair[4] === undefined || unquote(pair[4]).length === 0) {
+                throw new Error(`${capitalize(shape.kind)} frontmatter metadata entries must be "key: value" strings, one per line: "${line.trim()}"`);
+            }
+            currentMap[mapKey] = unquote(pair[4]);
+            continue;
+        }
+        const listItem = /^\s+-\s*(.*)$/.exec(line);
+        if (listItem) {
+            if (!currentList) {
+                throw new Error(`${capitalize(shape.kind)} frontmatter has a list item outside a list: "${line.trim()}"`);
+            }
+            const item = unquote(listItem[1] ?? '');
+            if (item.length > 0) {
+                currentList.push(item);
+            }
+            continue;
+        }
+        const entry = /^([A-Za-z][A-Za-z0-9_-]*)\s*:\s*(.*)$/.exec(line);
+        if (!entry) {
+            throw new Error(`${capitalize(shape.kind)} frontmatter line is not "key: value": "${line.trim()}"`);
+        }
+        const key = entry[1] ?? '';
+        const value = entry[2] ?? '';
+        currentList = undefined;
+        currentMap = undefined;
+        skippingUnknownBlock = false;
+        continuation = undefined;
+        if (tolerant && shape.mapKeys?.includes(key)) {
+            const inline = value.trim();
+            if (inline.length > 0 && inline !== '{}') {
+                throw new Error(`${capitalize(shape.kind)} frontmatter "${key}" must be a block of indented "key: value" lines: "${inline}"`);
+            }
+            const map = {};
+            maps[key] = map;
+            currentMap = map;
+            continue;
+        }
+        if (shape.listKeys.includes(key)) {
+            const list = [];
+            lists[key] = list;
+            const inline = value.trim();
+            if (inline.length > 0) {
+                // Inline form: tools: [a, b]
+                const match = /^\[(.*)\]$/.exec(inline);
+                if (!match) {
+                    throw new Error(`${capitalize(shape.kind)} frontmatter list "${key}" must be a block list or [a, b]: "${inline}"`);
+                }
+                const items = splitInlineList(match[1] ?? '');
+                if (items === undefined) {
+                    throw new Error(`${capitalize(shape.kind)} frontmatter list "${key}" has an unterminated quote: "${inline}"`);
+                }
+                for (const item of items) {
+                    const cleaned = unquote(item);
+                    if (cleaned.length > 0) {
+                        list.push(cleaned);
+                    }
+                }
+            }
+            else {
+                currentList = list;
+            }
+            continue;
+        }
+        if (!shape.scalarKeys.includes(key)) {
+            if (tolerant) {
+                // The key and anything nested under it belong to some other host.
+                // Remembered, not refused: a validator reports them.
+                unknownKeys.push(key);
+                skippingUnknownBlock = true;
+                continue;
+            }
+            throw new Error(`Unknown ${shape.kind} frontmatter key: "${key}". Supported keys: ${[...shape.scalarKeys, ...shape.listKeys].join(', ')}.`);
+        }
+        const inline = value.trim();
+        // YAML block-scalar headers: `>` folds continuation lines with spaces,
+        // `|` keeps their line breaks; either may carry an indentation digit
+        // and a chomping sign in either order, and a trailing comment. Only
+        // meaningful in tolerant mode — the strict dialect never wrote them.
+        if (tolerant && /^[>|](?:[1-9][+-]?|[+-][1-9]?)?(?:\s+#.*)?$/.test(inline)) {
+            scalars[key] = '';
+            continuation = { key, literal: inline.startsWith('|'), pendingBreak: false };
+            continue;
+        }
+        const scalar = unquote(value);
+        if (scalar.length === 0) {
+            if (tolerant) {
+                // May be a plain scalar continuing on indented lines; empty stays
+                // empty and is dropped below if nothing follows.
+                scalars[key] = '';
+                continuation = { key, literal: false, pendingBreak: false };
+                continue;
+            }
+            throw new Error(`${capitalize(shape.kind)} frontmatter key "${key}" has no value.`);
+        }
+        scalars[key] = scalar;
+        if (tolerant) {
+            continuation = { key, literal: false, pendingBreak: false };
+        }
+    }
+    // A tolerant block scalar that never got a body reads as absent, not as
+    // an empty string that would satisfy a required-field check.
+    for (const [key, value] of Object.entries(scalars)) {
+        if (value !== undefined && value.length === 0) {
+            delete scalars[key];
+        }
+    }
+    return { scalars, lists, maps, unknownKeys };
+};
+const capitalize = (word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`;
+/**
+ * Split a markdown document into its `---`-fenced frontmatter lines (if
+ * any) and the body after them. Shared by souls and skills — one reading
+ * of what the fences mean, wherever the dialect appears.
+ */
+export const extractFrontmatter = (source, kind) => {
+    const normalized = source.replace(/\r\n/g, '\n');
+    const opener = /^---[ \t]*\n/.exec(normalized);
+    if (!opener) {
+        return { lines: undefined, body: normalized };
+    }
+    const closer = /\n---[ \t]*(\n|$)/.exec(normalized.slice(opener[0].length - 1));
+    if (!closer || closer.index === undefined) {
+        throw new Error(`${capitalize(kind)} frontmatter opened with --- but never closed.`);
+    }
+    const frontmatterEnd = opener[0].length - 1 + closer.index;
+    return {
+        lines: normalized.slice(opener[0].length, frontmatterEnd).split('\n'),
+        body: normalized.slice(frontmatterEnd + closer[0].length),
+    };
+};
+/**
+ * Render an agent definition as a soul file, ready to save and edit. The
+ * inverse of parseSoul for round-tripping `stratus agent new` output.
+ */
+/**
+ * A scalar or list entry as the soul writer emits it. The parser strips
+ * one layer of matching quotes from every value, so a value that begins
+ * and ends with the same quote — an agent id like `'bea'`, which
+ * {@link isValidAgentId} allows — would come back as `bea`: for a
+ * `delegates` entry that is a permission changed by an unrelated edit,
+ * since the control API renders a soul through here on every field edit.
+ * Such a value is wrapped in the other quote, which the parser strips
+ * back off; so is one the parser's trim would alter.
+ */
+export const writeScalar = (value) => unquote(value) === value ? value : (value.startsWith('"') ? `'${value}'` : `"${value}"`);
+//# sourceMappingURL=frontmatter.js.map

package/dist/frontmatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontmatter.js","sourceRoot":"","sources":["../src/frontmatter.ts"],"names":[],"mappings":"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"}

package/dist/identity.d.ts

@@ -0,0 +1,139 @@
+import type { AvatarTheme } from '@stratusagent/core';
+/**
+ * The one house style every Stratus agent avatar is drawn in. Surfaces
+ * (CLI, web, macOS) render this style; agents differ by their name-derived
+ * hue and palette, so the team looks cohesive while each member is
+ * recognizable.
+ */
+export declare const AVATAR_STYLE = "stratus";
+/**
+ * Generate a human-ish first name. Deterministic when a seed is supplied;
+ * random otherwise.
+ */
+export declare const generateAgentName: (seed?: string) => string;
+/**
+ * Derive an avatar theme from a name: a stable hue and a small palette in
+ * the shared Stratus house style. Consumers (CLI, web, macOS) draw the
+ * actual image from this so the agent looks the same on every surface.
+ */
+export declare const generateAvatarTheme: (name: string) => AvatarTheme;
+export declare const slugify: (name: string) => string;
+/**
+ * The shape an id is *minted* in: lowercase alphanumerics and internal
+ * hyphens, starting with an alphanumeric. Everything `slugify` produces
+ * matches it, so every id this module derives does.
+ *
+ * Not what validation enforces. A hand-written `id:` predates any shape
+ * rule and `Ava_1` was as valid as `ava` — see `isValidAgentId`.
+ */
+export declare const AGENT_ID_PATTERN: RegExp;
+/**
+ * How long an id we *build* is allowed to get. A construction bound, not a
+ * validation rule — `isValidAgentId` deliberately does not check it.
+ *
+ * Every id derived from a long name predates this bound, and enforcing it
+ * retroactively drops working agents off the roster, while trimming them
+ * silently re-keys their sessions, memory, and credentials to an id nobody
+ * has ever used. So the bound applies where an id is minted fresh and
+ * nothing is keyed to it yet, and nowhere else. File systems still have
+ * limits, and an id long enough to hit them fails at the join with a name
+ * that says so.
+ */
+export declare const MAX_AGENT_ID_LENGTH = 64;
+/**
+ * Whether `id` is safe to key an agent's resources and paths by.
+ *
+ * Ids are not labels. They key sessions, memory, credentials, Slack channel
+ * tokens, and every per-agent path on disk — and an explicit frontmatter
+ * `id` is untrusted input: a soul file travels with a repository, and in
+ * the hosted profile it comes from a tenant. `id: ../../escape` reaches
+ * every one of those joins intact, so it is stopped once here rather than
+ * defended at each of them.
+ *
+ * **Unsafe is the rule, not un-sluglike.** Nothing before this checked an
+ * explicit id at all, so `Ava_1`, `team.alpha`, and `AVA` are all out there
+ * keying real sessions and real credentials. Holding them to the shape ids
+ * are minted in would not make anything safer — none of them can leave
+ * their directory — and `loadRosterSouls` degrades a soul that will not
+ * parse to a warning, so the only thing it would accomplish is dropping
+ * those agents off the roster on upgrade, quietly, while their data stays
+ * behind under the old id. Reserving the slug shape for ids nobody has
+ * chosen yet costs nothing; imposing it on ids people are already using
+ * costs them their agent.
+ *
+ * Rejected, never sanitized: rewriting `../../escape` into `escape` hands
+ * back an agent nobody asked for, keyed to resources nobody named.
+ */
+export declare const isValidAgentId: (id: string) => boolean;
+/**
+ * Whether a `delegates` entry is one the soul can hold: any agent id, or
+ * the wildcard — the same rule as {@link isValidAgentId}, so every agent a
+ * roster can hold can be named as a target. Exported so the control API
+ * refuses a bad entry as the client's error rather than discovering it in
+ * the soul round-trip.
+ */
+export declare const isValidDelegateEntry: (entry: string) => boolean;
+/**
+ * How much of a new session id is the *client's* to spend, on top of the
+ * agent id it addresses.
+ *
+ * Every id in circulation is a colon-joined address that embeds the agent
+ * id — `web:<agentId>:<uuid>` from the dashboard, a channel key of
+ * `<channel>:<agentId>:<team>:<conversation>:<thread>`, with a bare UUID
+ * from the CLI the one exception. So a flat cap is the wrong shape: agent
+ * ids are deliberately unbounded (see {@link isValidAgentId}), and a flat
+ * 200 refused every dashboard conversation for an agent whose id ran past
+ * 159 characters — an agent that stays on the roster and simply stops being
+ * chattable, which is the quiet-breakage failure the unbounded rule exists
+ * to avoid.
+ *
+ * Budgeting the composition instead keeps the bound meaningful without
+ * capping the agent id through the back door. It cannot be gamed to widen
+ * itself: the allowance comes from an agent id already checked against the
+ * roster, not from the caller's own string.
+ */
+export declare const MAX_SESSION_ID_LENGTH = 200;
+/**
+ * Whether `id` may open a *new* conversation.
+ *
+ * Session ids are client-minted and a `POST` to an unknown one creates it,
+ * so this is the only thing standing between an HTTP caller and a durable
+ * row. `undefined`, `null`, and a bare space have all reached the session
+ * table through that door — the dashboard shipped the first of them.
+ *
+ * **Checked where an id is minted, never where one is used.** An id already
+ * in the store addresses a real conversation, whatever shape it is, and
+ * re-validating on read would lock someone out of their own history to
+ * enforce a rule that postdates it. Same reasoning as
+ * {@link MAX_AGENT_ID_LENGTH}, which is why the length bound lives here and
+ * not in {@link isValidAgentId}.
+ *
+ * `agentId` is the agent the id addresses, when the caller knows it — every
+ * client convention embeds it, so its length is part of the budget rather
+ * than something the bound gets to cap. The allowance applies only to an id
+ * that actually contains it, since those are the characters being paid for;
+ * a bare UUID and an unrelated string are both held to
+ * {@link MAX_SESSION_ID_LENGTH} alone, as they are when `agentId` is
+ * omitted.
+ *
+ * Shape is deliberately not enforced. Every id above is a legitimate
+ * address, and no pattern admitting all of them excludes `undefined` — so
+ * the safety rule, a bound, and {@link STRINGIFIED_NOTHING} are what catch
+ * the real mistakes. Rejected, never sanitized: trimming an id hands the
+ * caller back a conversation at an address it never asked for.
+ */
+export declare const isValidSessionId: (id: string, agentId?: string) => boolean;
+/**
+ * A freshly minted id, bounded — `base` trimmed so that appending `suffix`
+ * still fits, with any hyphen left dangling by the trim removed.
+ *
+ * Only for ids nothing is keyed to yet: a generated agent's
+ * name-plus-suffix, and `agent new` retrying a filename collision. Both mint
+ * an id in the same breath as the agent, so trimming takes nothing away.
+ * Shared rather than re-derived so the two do not each own half of the bound
+ * and drift. An id derived from a name someone chose does *not* come through
+ * here — that name may already have an agent behind it.
+ */
+export declare const agentIdWithSuffix: (base: string, suffix?: string) => string;
+export declare const generatedIdSuffix: (seed?: string) => string;
+//# sourceMappingURL=identity.d.ts.map

package/dist/identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../src/identity.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgBtD;;;;;GAKG;AACH,eAAO,MAAM,YAAY,YAAY,CAAC;AAwBtC;;;GAGG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MAKjD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,GAAI,MAAM,MAAM,KAAG,WAalD,CAAC;AAEF,eAAO,MAAM,OAAO,GAAI,MAAM,MAAM,KAAG,MAIA,CAAC;AAExC;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,QAAyB,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAiCtC;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,eAAO,MAAM,cAAc,GAAI,IAAI,MAAM,KAAG,OAA4C,CAAC;AAEzF;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,GAAI,OAAO,MAAM,KAAG,OACb,CAAC;AAEzC;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,qBAAqB,MAAM,CAAC;AAmBzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,GAAI,IAAI,MAAM,EAAE,UAAU,MAAM,KAAG,OAQ/B,CAAC;AAElC;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MAIjE,CAAC;AAKF,eAAO,MAAM,iBAAiB,GAAI,OAAO,MAAM,KAAG,MAKjD,CAAC"}