@stratusagent/agents 0.11.3 → 0.11.5

package/dist/index.js

@@ -1,1517 +1,17 @@
-import { isListensMode, LISTENS_MODES, AgentRegistry, isTaintedTrust, leastTrusted, memoryEntryTrust, SENDER_TRUST_METADATA_KEY, sessionTaintedBy, sessionTrustOf, sessionWriteTrust, } from '@stratusagent/core';
-// First names only — agents should feel like a teammate you call by name.
-// Uniqueness comes from the generated id suffix, never from the name.
-const AGENT_NAMES = [
-    'Ada', 'Amara', 'Arlo', 'Asha', 'August', 'Beatrix', 'Caleb', 'Camila',
-    'Dara', 'Devon', 'Eleni', 'Elio', 'Esme', 'Felix', 'Freya', 'Gideon',
-    'Hana', 'Hugo', 'Imani', 'Ines', 'Jasper', 'Juno', 'Kai', 'Kira',
-    'Leandro', 'Lucia', 'Mabel', 'Mateo', 'Nadia', 'Nico', 'Odessa', 'Otis',
-    'Priya', 'Quinn', 'Rafael', 'Romy', 'Sana', 'Silas', 'Tamsin', 'Theo',
-    'Uma', 'Vera', 'Wesley', 'Xiomara', 'Yusuf', 'Zadie',
-    'Alba', 'Bruno', 'Celia', 'Dashiell', 'Edie', 'Ferris', 'Greta', 'Hollis',
-    'Ida', 'Jules', 'Koa', 'Lior', 'Marisol', 'Nyla', 'Oren', 'Paloma',
-    'Reza', 'Sunny', 'Tobias', 'Vada', 'Wren', 'Yara', 'Zeke',
-];
-/**
- * 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 const AVATAR_STYLE = 'stratus';
-/** Deterministic 32-bit hash so the same seed always yields the same identity. */
-const hashSeed = (seed) => {
-    let hash = 2166136261;
-    for (let index = 0; index < seed.length; index += 1) {
-        hash ^= seed.charCodeAt(index);
-        hash = Math.imul(hash, 16777619);
-    }
-    return hash >>> 0;
-};
-const hslToHex = (hue, saturation, lightness) => {
-    const s = saturation / 100;
-    const l = lightness / 100;
-    const k = (n) => (n + hue / 30) % 12;
-    const a = s * Math.min(l, 1 - l);
-    const channel = (n) => {
-        const value = l - a * Math.max(-1, Math.min(k(n) - 3, Math.min(9 - k(n), 1)));
-        return Math.round(value * 255).toString(16).padStart(2, '0');
-    };
-    return `#${channel(0)}${channel(8)}${channel(4)}`;
-};
-/**
- * Generate a human-ish first name. Deterministic when a seed is supplied;
- * random otherwise.
- */
-export const generateAgentName = (seed) => {
-    const value = seed !== undefined
-        ? hashSeed(seed)
-        : Math.floor(Math.random() * 0xffffffff);
-    return AGENT_NAMES[value % AGENT_NAMES.length] ?? 'Quinn';
-};
-/**
- * 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 const generateAvatarTheme = (name) => {
-    const value = hashSeed(name);
-    const hue = value % 360;
-    return {
-        seed: name,
-        hue,
-        palette: [
-            hslToHex(hue, 70, 55),
-            hslToHex((hue + 30) % 360, 65, 70),
-            hslToHex((hue + 180) % 360, 60, 45),
-        ],
-        style: AVATAR_STYLE,
-    };
-};
-const slugify = (name) => name
-    .toLowerCase()
-    .replace(/[^a-z0-9]+/g, '-')
-    .replace(/^-+|-+$/g, '') || 'agent';
-/**
- * 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 const AGENT_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
-/**
- * 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 const MAX_AGENT_ID_LENGTH = 64;
-/**
- * What an id may never be, whatever else it is: anything that stops being
- * a single, addressable path segment. A separator escapes the directory,
- * a leading dot hides the file or walks up out of it (`..`), and a control
- * character is not typeable back.
- */
-const PATH_UNSAFE_ID = /[/\\]|[\u0000-\u001f\u007f]/;
-/**
- * The safety half of every id rule here, shared because agent ids and
- * session ids answer it identically and a second copy would drift from the
- * first the next time one of them learned something.
- *
- * Safety only: what an id may never be. Shape — the slug pattern, a length
- * bound — is per-kind and stays with the kind, because the reasons differ.
- */
-const isAddressableId = (id) => id.length > 0
-    // Invisible leading or trailing space cannot be typed back reliably, so
-    // an id that is not its own trimmed self is a mistake, not a legacy.
-    && id === id.trim()
-    && !id.startsWith('.')
-    && !PATH_UNSAFE_ID.test(id)
-    // An id keys plain objects too — `credentials.channels.slack[id]` among
-    // them — where an inherited name is not a free slot. `toString` reads as
-    // already connected with nothing stored, and `__proto__` assigns through
-    // to the prototype, so the write lands nowhere and `JSON.stringify` drops
-    // it. `in {}` names exactly that set, and names it by the property it
-    // has rather than by a list to keep in step.
-    && !(id in {});
-/**
- * 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 const isValidAgentId = (id) => isAddressableId(id);
-/**
- * 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 const MAX_SESSION_ID_LENGTH = 200;
-/**
- * Ids that are a client's bug rendered as text, not an address anyone chose.
- *
- * Each is what JavaScript prints when an id was never computed — an
- * unresolved variable, a null field, arithmetic that went sideways, an
- * object concatenated into a template. The dashboard shipped the first one:
- * `/sessions/undefined/messages`, accepted, and a durable conversation
- * literally named `undefined`.
- *
- * A blocklist rather than a pattern, because these are safe, well-formed
- * strings — nothing about their *shape* is wrong, which is exactly why no
- * shape rule catches them. Kept to the strings the language itself
- * produces: guessing at what else looks like a mistake would start refusing
- * ids people meant.
- */
-const STRINGIFIED_NOTHING = new Set(['undefined', 'null', 'NaN', '[object Object]']);
-/**
- * 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 const isValidSessionId = (id, agentId) => isAddressableId(id)
-    // The allowance is for an id that actually *spends* those characters on
-    // the agent id. Granting it merely because the request names a long-id
-    // agent would let that agent's existence buy an unrelated caller 300 more
-    // characters of junk — the durable-garbage case the bound is here to stop.
-    && id.length <= MAX_SESSION_ID_LENGTH
-        + (agentId !== undefined && id.includes(agentId) ? agentId.length : 0)
-    && !STRINGIFIED_NOTHING.has(id);
-/**
- * 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 const agentIdWithSuffix = (base, suffix) => {
-    const tail = suffix ? `-${suffix}` : '';
-    const room = Math.max(1, MAX_AGENT_ID_LENGTH - tail.length);
-    return `${base.slice(0, room).replace(/-+$/, '') || 'agent'}${tail}`;
-};
-// Ids for generated names carry a short unique suffix: the name pool is
-// small, and two agents that draw the same name must still be two people —
-// memory and access scopes are keyed by id. Deterministic when seeded.
-const generatedIdSuffix = (seed) => {
-    const value = seed !== undefined
-        ? hashSeed(`${seed}:id`)
-        : Math.floor(Math.random() * 0xffffffff);
-    return value.toString(36).padStart(4, '0').slice(0, 4);
-};
-/**
- * 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 !== 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.');
-    }
-    // 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.listens ? { listens: input.listens } : {}),
-    };
-};
-const SOUL_SCALAR_KEYS = ['name', 'id', 'provider', 'model', 'listens'];
-const SOUL_LIST_KEYS = ['tools', 'skills', 'credentials'];
-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.
-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}"`);
-                }
-                for (const item of (match[1] ?? '').split(',')) {
-                    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.
- */
-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),
-    };
-};
-/**
- * Parse a soul file (markdown with optional frontmatter) into an agent
- * definition. The body becomes the agent's instructions; a missing name is
- * generated, so the smallest possible soul is just prose.
- */
-export const parseSoul = (source, options = {}) => {
-    const { lines, body } = extractFrontmatter(source, 'soul');
-    const { scalars, lists } = lines
-        ? parseFrontmatterLines(lines, { kind: 'soul', scalarKeys: SOUL_SCALAR_KEYS, listKeys: SOUL_LIST_KEYS })
-        : { scalars: {}, lists: {}, maps: {}, unknownKeys: [] };
-    const instructions = body.trim();
-    // Strict, like every soul key: a misspelled mode would otherwise load as
-    // the default, and an agent that answers every reply when it was meant
-    // to judge is the failure this file is read to prevent.
-    if (scalars.listens !== undefined && !isListensMode(scalars.listens)) {
-        throw new Error(`Soul frontmatter listens: ${JSON.stringify(scalars.listens)} is not a listening mode; use one of ${LISTENS_MODES.join(', ')}.`);
-    }
-    const agent = defineAgent({
-        ...(scalars.name ? { name: scalars.name } : {}),
-        ...(scalars.id ? { id: scalars.id } : {}),
-        ...(instructions ? { instructions } : {}),
-        ...(lists.tools ? { tools: lists.tools } : {}),
-        ...(lists.skills ? { skills: lists.skills } : {}),
-        ...(lists.credentials ? { credentials: lists.credentials } : {}),
-        ...(isListensMode(scalars.listens) ? { listens: scalars.listens } : {}),
-        ...(options.seed !== undefined ? { seed: options.seed } : {}),
-    });
-    return {
-        agent,
-        ...(scalars.provider ? { provider: scalars.provider } : {}),
-        ...(scalars.model ? { model: scalars.model } : {}),
-    };
-};
-/**
- * Render an agent definition as a soul file, ready to save and edit. The
- * inverse of parseSoul for round-tripping `stratus agent new` output.
- */
-export const formatSoul = (soul) => {
-    const lines = ['---', `name: ${soul.agent.name}`, `id: ${soul.agent.id}`];
-    if (soul.provider) {
-        lines.push(`provider: ${soul.provider}`);
-    }
-    if (soul.model) {
-        lines.push(`model: ${soul.model}`);
-    }
-    if (soul.agent.listens) {
-        lines.push(`listens: ${soul.agent.listens}`);
-    }
-    for (const [key, values] of [
-        ['tools', soul.agent.tools],
-        ['skills', soul.agent.skills],
-        ['credentials', soul.agent.credentials],
-    ]) {
-        if (values && values.length > 0) {
-            lines.push(`${key}:`);
-            for (const value of values) {
-                lines.push(`  - ${value}`);
-            }
-        }
-    }
-    lines.push('---', '');
-    lines.push(soul.agent.instructions ?? 'Describe who this agent is and how they talk.');
-    lines.push('');
-    return lines.join('\n');
-};
-// ---- skills ----------------------------------------------------------------
-/**
- * The shape a skill id is written in — the Agent Skills spec's rule for
- * `name`, which is also the directory name: lowercase letters and digits
- * in hyphen-separated runs (`web-research`), at most 64 characters, no
- * leading, trailing, or doubled hyphen. One pattern for the manifest's
- * declared ids, the operator directory's folder names, and install-time
- * validation — two copies would drift into two answers to what a valid
- * id is.
- */
-export const SKILL_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
-/** The spec's ceiling on `name`, and so on a skill id. */
-export const SKILL_ID_MAX_LENGTH = 64;
-export const isValidSkillId = (id) => id.length <= SKILL_ID_MAX_LENGTH && SKILL_ID_PATTERN.test(id);
-// The rule before the spec's: any lowercase kebab-ish run, doubled and
-// trailing hyphens and all, no length cap. What a directory or manifest
-// id that loaded yesterday was checked against.
-const LEGACY_SKILL_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
-/**
- * Whether an id that is already on this machine — a directory under
- * `~/.stratus/skills/`, a plugin manifest's declared id — is served.
- * Wider than `isValidSkillId` on purpose: the spec's rule arrived after
- * some of these were written, and tightening the *loader* would silently
- * drop an enabled procedure from an agent on upgrade. Installing and
- * validating use the strict rule; loading uses this one, and warns.
- */
-export const isLoadableSkillId = (id) => LEGACY_SKILL_ID_PATTERN.test(id);
-/** What a skill id refusal says, everywhere one is refused. */
-export const SKILL_ID_RULE = 'Skill ids are lowercase letters, digits, and single hyphens (web-research), at most 64 characters.';
-/** The spec's ceiling on `description`. */
-export const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
-/** The spec's ceiling on `compatibility`. */
-export const SKILL_COMPATIBILITY_MAX_LENGTH = 500;
-// The frontmatter keys the Agent Skills spec defines. Everything else at
-// the top level belongs to some other host — read past, and reported by
-// `validateSkillDocument`. `allowed-tools` is read so it is not reported,
-// and then deliberately unused: it is another host's pre-approval list,
-// and here the two gates (a trusted config, a soul's allowlist) are the
-// only things that grant a tool.
-const SKILL_SPEC_KEYS = ['name', 'description', 'license', 'compatibility', 'metadata', 'allowed-tools'];
-// `version` and `requires` at the top level are the pre-spec Stratus form;
-// the spec keeps host extensions under `metadata:`, and that is where a
-// skill written today puts them. The old form still reads, so an installed
-// skill keeps working — and validation says which form it found.
-const SKILL_SCALAR_KEYS = ['name', 'description', 'license', 'compatibility', 'allowed-tools', 'version'];
-const SKILL_LIST_KEYS = ['requires'];
-const SKILL_MAP_KEYS = ['metadata'];
-const SKILL_LEGACY_KEYS = ['version', 'requires'];
-/**
- * Parse a `SKILL.md` — the same frontmatter dialect souls use (`key: value`
- * scalars, block lists), plus the spec's `metadata:` map. The body is the
- * procedure itself, markdown, untouched.
- *
- * `description` is required: it is the only thing the model sees before
- * deciding to load the body, and a skill without one is unreachable by the
- * mechanism that makes skills cheap. Everything the spec constrains beyond
- * presence — the name rule, the length ceilings — is
- * `validateSkillDocument`'s, so that loading what is already installed
- * stays lenient while installing is strict.
- */
-export const parseSkillDocument = (source) => {
-    const { lines, body } = extractFrontmatter(source, 'skill');
-    if (!lines) {
-        throw new Error('Skill file has no frontmatter. A SKILL.md starts with --- and needs at least a description.');
-    }
-    const { scalars, lists, maps, unknownKeys } = parseFrontmatterLines(lines, {
-        kind: 'skill',
-        scalarKeys: SKILL_SCALAR_KEYS,
-        listKeys: SKILL_LIST_KEYS,
-        mapKeys: SKILL_MAP_KEYS,
-        // Skills travel the wider agent-skills ecosystem (skills.sh and the
-        // registries behind it), whose frontmatter carries fields other hosts
-        // own. Those are metadata to skip, not defects to refuse — see
-        // FrontmatterShape.tolerant, and note souls do NOT set this.
-        tolerant: true,
-    });
-    const description = scalars.description;
-    if (!description) {
-        throw new Error('Skill frontmatter has no "description". The description is what an agent routes on — say when to reach for this skill.');
-    }
-    const metadata = maps.metadata;
-    const version = metadata?.version ?? scalars.version;
-    const requires = metadata?.requires !== undefined
-        ? metadata.requires.split(/\s+/).filter((entry) => entry.length > 0)
-        : lists.requires;
-    // The legacy keys are read, and still not the spec's: a validator names
-    // them so a skill written here can be moved to the form that ports.
-    const legacy = SKILL_LEGACY_KEYS.filter((key) => (key === 'requires' ? lists.requires : scalars[key]) !== undefined);
-    return {
-        ...(scalars.name ? { name: scalars.name } : {}),
-        description,
-        ...(scalars.license ? { license: scalars.license } : {}),
-        ...(scalars.compatibility ? { compatibility: scalars.compatibility } : {}),
-        ...(metadata ? { metadata } : {}),
-        ...(version ? { version } : {}),
-        ...(requires && requires.length > 0 ? { requires } : {}),
-        unknownKeys: [...legacy, ...unknownKeys.filter((key) => !SKILL_SPEC_KEYS.includes(key))],
-        body: body.trim(),
-    };
-};
-const characterCount = (text) => Array.from(text).length;
-/**
- * Check a parsed `SKILL.md` against the Agent Skills spec — the checks
- * `skills-ref validate` runs, so a skill that passes here passes there:
- * `name` present, shaped like an id, equal to the directory name;
- * `description` and `compatibility` under their ceilings. Errors are what
- * refuses an install. Top-level keys the spec does not define are
- * warnings, not errors: the reference validator refuses them, but the
- * ecosystem's skills carry other hosts' fields routinely, and refusing a
- * skill over a field that changes nothing here fails the whole point of
- * conforming. The legacy Stratus keys get their own warning, naming the
- * `metadata:` form that ports.
- *
- * Loading never calls this — an installed skill keeps loading whatever
- * the spec says today. Installing always does.
- */
-export const validateSkillDocument = (document, options = {}) => {
-    const errors = [];
-    const warnings = [];
-    if (document.name === undefined) {
-        const suggestion = options.suggestedName ?? options.directoryName;
-        errors.push(`frontmatter has no "name". The Agent Skills spec requires one, equal to the directory name${suggestion !== undefined ? ` — add: name: ${suggestion}` : ''}.`);
-    }
-    else if (!isValidSkillId(document.name)) {
-        errors.push(`name ${JSON.stringify(document.name)} is not a skill id. ${SKILL_ID_RULE}`);
-    }
-    else if (options.directoryName !== undefined && document.name !== options.directoryName) {
-        errors.push(`name ${JSON.stringify(document.name)} does not match the directory name ${JSON.stringify(options.directoryName)}. The spec requires the two to agree — rename one.`);
-    }
-    // Characters, as the spec and its Python reference count them — code
-    // points, not the UTF-16 units `.length` reports, which would count an
-    // emoji twice and refuse a description the reference validator passes.
-    const descriptionLength = characterCount(document.description);
-    if (descriptionLength > SKILL_DESCRIPTION_MAX_LENGTH) {
-        errors.push(`description is ${descriptionLength} characters, past the spec's ceiling of ${SKILL_DESCRIPTION_MAX_LENGTH}. Say when to reach for the skill, and move the rest into the body.`);
-    }
-    const compatibilityLength = document.compatibility !== undefined ? characterCount(document.compatibility) : 0;
-    if (compatibilityLength > SKILL_COMPATIBILITY_MAX_LENGTH) {
-        errors.push(`compatibility is ${compatibilityLength} characters, past the spec's ceiling of ${SKILL_COMPATIBILITY_MAX_LENGTH}.`);
-    }
-    const legacy = document.unknownKeys.filter((key) => SKILL_LEGACY_KEYS.includes(key));
-    const foreign = document.unknownKeys.filter((key) => !SKILL_LEGACY_KEYS.includes(key));
-    for (const key of legacy) {
-        warnings.push(key === 'requires'
-            ? 'top-level "requires" is the pre-spec Stratus form, and the reference validator refuses it. Write it as metadata.requires, one space-separated string: "browser.* fs.read".'
-            : 'top-level "version" is the pre-spec Stratus form, and the reference validator refuses it. Write it as metadata.version.');
-    }
-    if (foreign.length > 0) {
-        warnings.push(`frontmatter key${foreign.length > 1 ? 's' : ''} outside the Agent Skills spec: ${foreign.map((key) => JSON.stringify(key)).join(', ')}. Another host's; ignored here, and the reference validator refuses ${foreign.length > 1 ? 'them' : 'it'}.`);
-    }
-    return { errors, warnings };
-};
-/**
- * A `Skill` whose body stays on disk until somebody asks. The identity
- * comes from the load-time parse (which is also what validated the file);
- * `load()` re-reads rather than closing over the body, so an
- * enabled-but-unused skill costs its description line and nothing else —
- * in the prompt and in memory.
- */
-export const createLazySkill = ({ id, document, read }) => ({
-    id,
-    name: document.name ?? id,
-    description: document.description,
-    ...(document.requires ? { requires: document.requires } : {}),
-    load: async () => parseSkillDocument(await read()).body,
-});
-export const MEMORY_TOOL_NAME = 'memory.remember';
-/**
- * A tool that lets an agent write to its own long-term memory. Entries are
- * keyed by the session's agent id, so what one agent learns stays exclusively
- * that agent's knowledge — and follows it to every channel and thread.
- */
-export const createRememberTool = (store) => ({
-    name: MEMORY_TOOL_NAME,
-    description: 'Save a fact to your long-term memory so you can recall it in future conversations on any channel.',
-    // The agent's own memory, keyed to the agent and read by nobody else.
-    risk: 'safe',
-    parameters: {
-        type: 'object',
-        properties: {
-            fact: { type: 'string', description: 'The fact to remember, phrased so it makes sense later without context.' },
-        },
-        required: ['fact'],
-    },
-    async execute(input, session) {
-        const fact = typeof input.fact === 'string' ? input.fact.trim() : '';
-        if (!fact) {
-            throw new Error('memory.remember requires a non-empty "fact" string.');
-        }
-        // Per session, not per fact: the runner knows this session has seen
-        // untrusted content and cannot know which words of the fact came from
-        // it, so the write carries the least trusted label the session holds.
-        // Coarse and over-marking — the safe direction.
-        const taintedBy = sessionTaintedBy(session);
-        const origin = { sessionId: session.id, ...(taintedBy !== undefined ? { taintedBy } : {}) };
-        const entry = await store.append(session.agent.id, fact, { sessionId: session.id }, {
-            trust: sessionWriteTrust(session),
-            origin,
-        });
-        return { remembered: true, id: entry.id, trust: memoryEntryTrust(entry) };
-    },
-});
-export const RECALL_TOOL_NAME = 'memory.recall';
-/**
- * Searches the agent's own long-term memory. `safe` by the same rule as
- * `memory.remember`: reading what this agent already knows. The query is
- * literal text — the store does whatever escaping its backend needs, so no
- * query a model writes is ever a syntax error; matching nothing is a normal
- * result, because an agent that has learned nothing yet is the ordinary
- * starting state, not a broken tool.
- */
-export const createRecallTool = (store) => ({
-    name: RECALL_TOOL_NAME,
-    description: 'Search your long-term memory for facts you have remembered. Only your most recent memories appear in your prompt automatically — use this to find everything older.',
-    risk: 'safe',
-    parameters: {
-        type: 'object',
-        properties: {
-            query: { type: 'string', description: 'What to look for, as plain words. Every word must appear in a fact for it to match.' },
-            limit: { type: 'number', description: 'Maximum facts to return. Optional; the store bounds it either way.' },
-        },
-        required: ['query'],
-    },
-    async execute(input, session, context) {
-        if (typeof input.query !== 'string') {
-            throw new Error('memory.recall requires a "query" string.');
-        }
-        const limit = typeof input.limit === 'number' ? input.limit : undefined;
-        const result = await store.search(session.agent.id, input.query, limit);
-        // What enters the context taints the session, recalled as much as
-        // injected: an `external` entry surfacing here is a stranger's text
-        // in the prompt, and marking the call is what stops the store from
-        // laundering its own contents through a fresh session.
-        const lowest = leastTrusted(...result.entries.map(memoryEntryTrust));
-        if (isTaintedTrust(lowest)) {
-            context?.markTrust?.(lowest);
-        }
-        return {
-            results: result.entries.map((entry) => ({
-                id: entry.id,
-                content: entry.content,
-                createdAt: entry.createdAt,
-                trust: memoryEntryTrust(entry),
-            })),
-            truncated: result.truncated,
-        };
-    },
-});
-export const FORGET_TOOL_NAME = 'memory.forget';
-/**
- * Retires one of the agent's own memories, by id. Tombstoned rather than
- * deleted — which is what makes `safe` defensible for it: the entry stops
- * being live but does not stop existing, so an operator can still see what
- * an agent chose to drop.
- */
-export const createForgetTool = (store) => ({
-    name: FORGET_TOOL_NAME,
-    description: 'Forget one of your remembered facts by its id (from memory.recall or memory.remember). It stops informing future conversations.',
-    risk: 'safe',
-    parameters: {
-        type: 'object',
-        properties: {
-            id: { type: 'string', description: 'The id of the memory entry to forget.' },
-        },
-        required: ['id'],
-    },
-    async execute(input, session) {
-        const id = typeof input.id === 'string' ? input.id.trim() : '';
-        if (!id) {
-            throw new Error('memory.forget requires a non-empty "id" string.');
-        }
-        const forgotten = await store.forget(session.agent.id, id);
-        if (!forgotten) {
-            throw new Error(`No live memory entry with id ${id} belongs to this agent — nothing was forgotten.`);
-        }
-        return { forgotten: true, id };
-    },
-});
-export const DELEGATE_TOOL_NAME = 'agent.delegate';
-/**
- * Metadata a delegated sub-session carries: which agent delegated, and the
- * session at the root of the chain. Written by `agent.delegate` and read by
- * the gateway's restart sweep, which is why the keys are named here rather
- * than spelled twice — a sub-session's parent is a turn in some other
- * process's memory, and after a restart nothing can consume its reply.
- */
-export const DELEGATED_BY_METADATA_KEY = 'delegatedBy';
-export const ROOT_SESSION_ID_METADATA_KEY = 'rootSessionId';
-export const DELEGATION_DEPTH_METADATA_KEY = 'delegationDepth';
-/**
- * The segment `agent.delegate` mints into every sub-session's id —
- * `<parent>:delegate:<agent>:<depth>:<suffix>`. The second half of what
- * identifies a sub-session, beside the metadata above: the gateway refuses
- * the metadata keys at its public door, but rows written before it did
- * cannot be told apart by their metadata alone, and a caller who wrote
- * `delegatedBy` onto a session of its own would not also have minted an
- * id in this shape.
- */
-export const DELEGATED_SESSION_ID_MARKER = ':delegate:';
-/**
- * Whether this session is a delegated sub-session — one whose reply is
- * consumed by a parent turn's `agent.delegate` call and by nothing else.
- * Both halves are required: the metadata `agent.delegate` writes, and the
- * id shape it mints.
- */
-export const isDelegatedSession = (session) => typeof session.metadata?.[DELEGATED_BY_METADATA_KEY] === 'string'
-    && session.id.includes(DELEGATED_SESSION_ID_MARKER);
-/**
- * The id of the session whose `agent.delegate` call started this one, read
- * off the id shape above — the text before the last marker, since a nested
- * sub-session embeds its parent's id whole. Undefined for an id that was
- * not minted that way.
- */
-export const delegatingSessionIdOf = (sessionId) => {
-    const at = sessionId.lastIndexOf(DELEGATED_SESSION_ID_MARKER);
-    return at > 0 ? sessionId.slice(0, at) : undefined;
-};
-/**
- * The id of the `agent.delegate` call in `parent` that is still awaiting
- * `child`, or undefined when none is.
- *
- * The one thing about a delegation nothing outside the runner can forge:
- * a caller can name a session in the sub-session id shape and write the
- * metadata keys, but only the runner writes assistant tool calls, and only
- * a delegation in flight leaves one with no result behind it. Matched to
- * the child and not merely counted, because a parent can be inside one
- * delegation while an earlier sub-session of its — continued from outside
- * under a version that kept the markers — is parked on something of its
- * own. The call names its target and its prompt, and `agent.delegate`
- * made the prompt the child's first user message. Read against the
- * transcript order so a re-used call id cannot make a later call look
- * answered.
- */
-export const outstandingDelegationFor = (parent, child) => {
-    const firstMessage = child.messages.find((message) => message.role === 'user')?.content;
-    if (firstMessage === undefined) {
-        return undefined;
-    }
-    const answered = new Map();
-    for (const message of parent.messages) {
-        if (message.role === 'tool' && message.toolResult) {
-            answered.set(message.toolResult.callId, (answered.get(message.toolResult.callId) ?? 0) + 1);
-        }
-    }
-    const seen = new Map();
-    for (const message of parent.messages) {
-        if (message.role !== 'assistant' || !message.toolCalls) {
-            continue;
-        }
-        for (const call of message.toolCalls) {
-            const occurrence = (seen.get(call.id) ?? 0) + 1;
-            seen.set(call.id, occurrence);
-            if (call.toolName !== DELEGATE_TOOL_NAME || occurrence <= (answered.get(call.id) ?? 0)) {
-                continue;
-            }
-            const target = typeof call.input.agent === 'string' ? call.input.agent : '';
-            const prompt = typeof call.input.prompt === 'string' ? call.input.prompt.trim() : '';
-            if ((target === child.agent.id || target === child.agent.name) && prompt === firstMessage) {
-                return call.id;
-            }
-        }
-    }
-    return undefined;
-};
-/**
- * `metadata` with the delegation markers removed — what a sub-session
- * carries once it has been addressed from outside. The delegation ended
- * with the turn that awaited it; a conversation somebody continues on the
- * same id afterwards is an ordinary one, and must not be closed as an
- * orphan by a later restart.
- */
-export const withoutDelegation = (metadata) => {
-    const { [DELEGATED_BY_METADATA_KEY]: _delegatedBy, [ROOT_SESSION_ID_METADATA_KEY]: _root, [DELEGATION_DEPTH_METADATA_KEY]: _depth, ...rest } = metadata;
-    return rest;
-};
-const DEFAULT_MAX_DELEGATION_DEPTH = 3;
-/**
- * The orchestrator primitive: a tool that runs another agent in its own
- * sub-session (with that agent's memory, tool allowlist, and credentials)
- * and returns its final reply as the tool result.
- */
-export const createDelegateTool = ({ registry, runner, dispatch, maxDepth = DEFAULT_MAX_DELEGATION_DEPTH, }) => {
-    const runDelegated = dispatch ?? ((input) => runner.run(input));
-    // Sub-session ids must be unique even when one orchestrator delegates to
-    // the same target repeatedly, and must stay unique across tool rebuilds
-    // sharing one SessionStore — so a counter alone is not enough.
-    let delegationCount = 0;
-    const uniqueSuffix = () => `${delegationCount}-${Math.random().toString(36).slice(2, 10)}`;
-    return {
-        name: DELEGATE_TOOL_NAME,
-        description: 'Delegate a task to another agent by name and get their reply back.',
-        // Safe, and the call is arguable enough to record why. Delegation spends
-        // provider tokens and starts work as another agent, which reads like
-        // `gated` — but the money argument proves too much: the turn that decides
-        // to delegate was itself an unapproved provider call, so gating on spend
-        // gates the conversation. What delegation does NOT do is act outside
-        // Stratus. It stays in the fleet, the delegate's own tool calls face the
-        // policy again under the delegate's allowlist, and maxDepth bounds the
-        // chain.
-        //
-        // The practical half: `gated` here means a headless daemon refuses every
-        // delegation, and headless is what every installed service runs. That
-        // would remove the orchestrator pattern from the product until remote
-        // approval exists — a feature removal wearing a safety hat, with no way
-        // for an operator to say yes. Revisit when a human can actually be asked.
-        risk: 'safe',
-        parameters: {
-            type: 'object',
-            properties: {
-                agent: { type: 'string', description: 'Name or id of the agent to delegate to.' },
-                prompt: { type: 'string', description: 'The task or question for that agent.' },
-            },
-            required: ['agent', 'prompt'],
-        },
-        async execute(input, session, context) {
-            const targetRef = typeof input.agent === 'string' ? input.agent : '';
-            const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
-            if (!targetRef || !prompt) {
-                throw new Error('agent.delegate requires "agent" and "prompt" strings.');
-            }
-            const depth = typeof session.metadata?.[DELEGATION_DEPTH_METADATA_KEY] === 'number'
-                ? session.metadata[DELEGATION_DEPTH_METADATA_KEY]
-                : 0;
-            if (depth >= maxDepth) {
-                throw new Error(`Delegation depth limit reached (${maxDepth}).`);
-            }
-            const target = registry.get(targetRef) ?? registry.getByName(targetRef);
-            if (!target) {
-                throw new Error(`Agent not found: ${targetRef}`);
-            }
-            if (target.id === session.agent.id) {
-                throw new Error('An agent cannot delegate to itself.');
-            }
-            delegationCount += 1;
-            let result;
-            try {
-                result = await runDelegated({
-                    sessionId: `${session.id}${DELEGATED_SESSION_ID_MARKER}${target.id}:${depth + 1}:${uniqueSuffix()}`,
-                    agent: target,
-                    userMessage: prompt,
-                    metadata: {
-                        [DELEGATION_DEPTH_METADATA_KEY]: depth + 1,
-                        [DELEGATED_BY_METADATA_KEY]: session.agent.id,
-                        [ROOT_SESSION_ID_METADATA_KEY]: typeof session.metadata?.[ROOT_SESSION_ID_METADATA_KEY] === 'string'
-                            ? session.metadata[ROOT_SESSION_ID_METADATA_KEY]
-                            : session.id,
-                        // Outbound: the prompt is the parent's text, and the parent is its
-                        // "sender" — a tainted parent must not hand attacker text to a
-                        // teammate whose session has seen nothing. At most `agent`: the
-                        // prompt is something an agent wrote, whoever it was talking to.
-                        [SENDER_TRUST_METADATA_KEY]: sessionWriteTrust(session),
-                    },
-                    // A cancelled parent turn cancels the delegated run with it —
-                    // otherwise the parent cannot settle until the target gives up.
-                    ...(context?.signal ? { signal: context.signal } : {}),
-                });
-            }
-            catch (error) {
-                // A failed run has no session to read a label from here, and its
-                // error text is the target's — a provider quoting the request it
-                // refused, which is the target's prompt and injected memory, whatever
-                // label those carried. The parent sees that text as a tool error, so
-                // the call is marked at the label for provenance nobody can vouch
-                // for before it is rethrown. The parent's own cancellation is the
-                // exception: that error is this process's sentence, not the target's.
-                if (!context?.signal?.aborted) {
-                    context?.markTrust?.('unknown');
-                }
-                throw error;
-            }
-            // Inbound: the reply carries the target session's label, whatever it
-            // is — not only `external`. A target whose own injected memory was
-            // `unknown` replies from content the parent never saw and cannot
-            // assess; the parent takes the lower of its own label and this one,
-            // by the same ordering as everything else.
-            const targetTrust = sessionTrustOf(result);
-            context?.markTrust?.(targetTrust);
-            const reply = [...result.messages]
-                .reverse()
-                .find((message) => message.role === 'assistant' && message.content.length > 0);
-            return {
-                agent: target.name,
-                reply: reply?.content ?? '(no reply)',
-                sessionId: result.id,
-                trust: targetTrust,
-            };
-        },
-    };
-};
-/**
- * Route inbound work (a channel name, a message, a thread key) to an agent.
- * The Slack transport will feed channel/mention strings through this so the
- * same person consistently answers in the same places.
- */
-export const createAgentRouter = (rules, fallback) => {
-    // Global/sticky regexes mutate lastIndex on test(). Clone them (so the
-    // caller's regex is never touched) keeping all flags — sticky stays
-    // anchored — and reset lastIndex before every test for stable results.
-    const normalized = rules.map((rule) => ({
-        ...rule,
-        match: rule.match instanceof RegExp
-            ? new RegExp(rule.match.source, rule.match.flags)
-            : rule.match,
-    }));
-    return {
-        route(input) {
-            for (const rule of normalized) {
-                let matched;
-                if (rule.match instanceof RegExp) {
-                    rule.match.lastIndex = 0;
-                    matched = rule.match.test(input);
-                }
-                else {
-                    matched = rule.match(input);
-                }
-                if (matched) {
-                    return rule.agent;
-                }
-            }
-            return fallback;
-        },
-    };
-};
-/** Register a set of agents and get the registry back. */
-export const createAgentTeam = (agents) => {
-    const registry = new AgentRegistry();
-    for (const agent of agents) {
-        registry.register(agent);
-    }
-    return registry;
-};
-/**
- * The one string form of a destination, `<channel>:<native id>`, used
- * everywhere a destination is *compared*: `Tool.destinationFor`, the
- * permission policy's pre-authorization check, and the schedule row it is
- * checked against. One canonicalization, or two writers of `slack:C01` and
- * `SLACK:C01` would disagree about the same channel.
- */
-export const canonicalDestination = (destination) => `${destination.channel.trim().toLowerCase()}:${destination.to.trim()}`;
-/** `every` strings: a positive integer and one unit — `90s`, `10m`, `2h`, `1d`. */
-export const parseInterval = (text) => {
-    const match = /^(\d+)(s|m|h|d)$/.exec(text.trim());
-    if (!match) {
-        return undefined;
-    }
-    const amount = Number(match[1]);
-    if (!Number.isSafeInteger(amount) || amount <= 0) {
-        return undefined;
-    }
-    const unit = { s: 1_000, m: 60_000, h: 3_600_000, d: 86_400_000 }[match[2]];
-    return amount * unit;
-};
-const parseCronField = (field, min, max, label) => {
-    const values = new Set();
-    for (const part of field.split(',')) {
-        const stepMatch = /^([^/]+)(?:\/(\d+))?$/.exec(part);
-        if (!stepMatch || part.length === 0) {
-            throw new Error(`Invalid cron ${label} field: ${field}`);
-        }
-        const [, rangeText, stepText] = stepMatch;
-        const step = stepText === undefined ? 1 : Number(stepText);
-        if (!Number.isSafeInteger(step) || step < 1) {
-            throw new Error(`Invalid cron ${label} step: ${part}`);
-        }
-        let low;
-        let high;
-        if (rangeText === '*') {
-            low = min;
-            high = max;
-        }
-        else {
-            const rangeMatch = /^(\d+)(?:-(\d+))?$/.exec(rangeText);
-            if (!rangeMatch) {
-                throw new Error(`Invalid cron ${label} field: ${field} (numbers only — names are not supported)`);
-            }
-            low = Number(rangeMatch[1]);
-            high = rangeMatch[2] === undefined ? low : Number(rangeMatch[2]);
-            // A bare value with a step (`5/15`) reads to the end of the range,
-            // matching vixie cron.
-            if (rangeMatch[2] === undefined && stepText !== undefined) {
-                high = max;
-            }
-        }
-        if (low < min || high > max || low > high) {
-            throw new Error(`Cron ${label} value out of range ${min}-${max}: ${part}`);
-        }
-        for (let value = low; value <= high; value += step) {
-            values.add(value);
-        }
-    }
-    return values;
-};
-/**
- * Five fields — minute, hour, day-of-month, month, day-of-week — with `*`,
- * lists, ranges, and steps. Numbers only; day-of-week 0-7 with both 0 and 7
- * as Sunday. Evaluated in the daemon's local time, which is what "every
- * morning at 7" means to the person whose machine it is.
- */
-export const parseCronExpression = (expression) => {
-    const fields = expression.trim().split(/\s+/);
-    if (fields.length !== 5) {
-        throw new Error(`A cron expression has five fields (minute hour day-of-month month day-of-week); got ${fields.length} in "${expression}".`);
-    }
-    const [minute, hour, dom, month, dow] = fields;
-    const daysOfWeek = parseCronField(dow, 0, 7, 'day-of-week');
-    if (daysOfWeek.has(7)) {
-        daysOfWeek.delete(7);
-        daysOfWeek.add(0);
-    }
-    return {
-        minutes: parseCronField(minute, 0, 59, 'minute'),
-        hours: parseCronField(hour, 0, 23, 'hour'),
-        daysOfMonth: parseCronField(dom, 1, 31, 'day-of-month'),
-        months: parseCronField(month, 1, 12, 'month'),
-        daysOfWeek,
-        domRestricted: dom !== '*',
-        dowRestricted: dow !== '*',
-    };
-};
-/** How far a cron search looks before concluding the expression never fires. */
-const CRON_SEARCH_DAYS = 366 * 4;
-const nextCronFire = (fields, after) => {
-    // Strictly after `after`, at minute granularity.
-    const start = new Date(after.getTime());
-    start.setSeconds(0, 0);
-    start.setMinutes(start.getMinutes() + 1);
-    const dayMatches = (date) => {
-        if (!fields.months.has(date.getMonth() + 1)) {
-            return false;
-        }
-        const domMatch = fields.daysOfMonth.has(date.getDate());
-        const dowMatch = fields.daysOfWeek.has(date.getDay());
-        if (fields.domRestricted && fields.dowRestricted) {
-            return domMatch || dowMatch;
-        }
-        return fields.domRestricted ? domMatch : fields.dowRestricted ? dowMatch : true;
-    };
-    const hours = [...fields.hours].sort((a, b) => a - b);
-    const minutes = [...fields.minutes].sort((a, b) => a - b);
-    const day = new Date(start.getFullYear(), start.getMonth(), start.getDate());
-    for (let offset = 0; offset < CRON_SEARCH_DAYS; offset += 1) {
-        if (dayMatches(day)) {
-            for (const hour of hours) {
-                for (const minute of minutes) {
-                    const candidate = new Date(day.getFullYear(), day.getMonth(), day.getDate(), hour, minute);
-                    if (candidate >= start && candidate > after) {
-                        return candidate;
-                    }
-                }
-            }
-        }
-        day.setDate(day.getDate() + 1);
-    }
-    // Reachable: `0 0 31 2 *` matches no real date. Creation treats this as
-    // a refusal, not a schedule that quietly never runs.
-    return undefined;
-};
-/**
- * The slot after `after`, or undefined when there is none — a one-shot
- * already past, or a cron expression that matches no real date. One
- * implementation, because the scheduler advancing a fired slot and the
- * creation path computing the first one must never disagree.
- */
-export const nextFireAfter = (cadence, after) => {
-    switch (cadence.kind) {
-        case 'every':
-            return new Date(after.getTime() + cadence.intervalMs);
-        case 'cron':
-            return nextCronFire(parseCronExpression(cadence.expression), after);
-        case 'at': {
-            const at = new Date(cadence.at);
-            if (Number.isNaN(at.getTime())) {
-                return undefined;
-            }
-            return at.getTime() > after.getTime() ? at : undefined;
-        }
-        default:
-            return undefined;
-    }
-};
-/** One line for a human: `every 30m`, `cron 0 7 * * *`, `once at 2026-…`. */
-export const describeCadence = (cadence) => {
-    switch (cadence.kind) {
-        case 'every': {
-            const units = [[86_400_000, 'd'], [3_600_000, 'h'], [60_000, 'm'], [1_000, 's']];
-            for (const [ms, suffix] of units) {
-                if (cadence.intervalMs % ms === 0) {
-                    return `every ${cadence.intervalMs / ms}${suffix}`;
-                }
-            }
-            return `every ${cadence.intervalMs}ms`;
-        }
-        case 'cron':
-            return `cron ${cadence.expression}`;
-        case 'at':
-            return `once at ${cadence.at}`;
-        default:
-            return 'unknown';
-    }
-};
-/**
- * Metadata a firing's session carries. The schedule id is what the
- * permission carve-out resolves the approved destination from, and
- * `scheduled: true` is what lets a renderer say a turn arrived from a
- * schedule rather than a person.
- */
-export const SCHEDULE_ID_METADATA_KEY = 'scheduleId';
-export const SCHEDULED_TURN_METADATA_KEY = 'scheduled';
-// ---- schedule tools ---------------------------------------------------------
-export const SCHEDULE_EVERY_TOOL_NAME = 'schedule.every';
-export const SCHEDULE_AT_TOOL_NAME = 'schedule.at';
-export const SCHEDULE_LIST_TOOL_NAME = 'schedule.list';
-export const SCHEDULE_CANCEL_TOOL_NAME = 'schedule.cancel';
-export const MESSAGE_SEND_TOOL_NAME = 'message.send';
-/**
- * The tools only a running gateway registers. Each needs the dispatcher,
- * the store, or the channels, and nothing else in the tree has them — so a
- * soul naming one is correct while a host without them cannot call it,
- * which is a different thing from a name that does not exist. `stratus
- * run` reads this to say which it is rather than reporting a daemon soul's
- * `schedule.*` as a typo.
- *
- * It lives here, with the names, rather than in `@stratusagent/gateway`
- * where the registrations are: the CLI imports the gateway only through
- * `await import`, because `bin.ts` has to load the CLI to print the Node
- * version message and the gateway pulls in `node:sqlite` at module scope.
- * A static import for a list of strings would have made the floor guard
- * fail with the exact builtin-module error it exists to replace. The
- * gateway's own test pins this set against what it actually registers,
- * which holds the two together better than proximity would.
- */
-export const GATEWAY_ONLY_TOOL_NAMES = [
-    SCHEDULE_EVERY_TOOL_NAME,
-    SCHEDULE_AT_TOOL_NAME,
-    SCHEDULE_LIST_TOOL_NAME,
-    SCHEDULE_CANCEL_TOOL_NAME,
-    MESSAGE_SEND_TOOL_NAME,
-    DELEGATE_TOOL_NAME,
-];
-const parseDestinationInput = (raw) => {
-    if (typeof raw !== 'object' || raw === null || Array.isArray(raw)) {
-        return undefined;
-    }
-    const channel = raw.channel;
-    const to = raw.to;
-    if (typeof channel !== 'string' || channel.trim().length === 0
-        || typeof to !== 'string' || to.trim().length === 0) {
-        return undefined;
-    }
-    return { channel: channel.trim().toLowerCase(), to: to.trim() };
-};
-const DESTINATION_PARAMETER = {
-    type: 'object',
-    description: 'Where firings report. Omit for a schedule that does not speak — its sends will need approval like any other. The channel kind plus the channel-native conversation id (for Slack, a channel id like C0123456789 that your app is a member of).',
-    properties: {
-        channel: { type: 'string', description: "Channel kind, e.g. 'slack'." },
-        to: { type: 'string', description: 'Channel-native conversation id.' },
-    },
-    required: ['channel', 'to'],
-};
-/**
- * One schedule as a surface shows it — the CLI table, the control API's
- * listing, and the tool results all render this one projection, so the
- * operator's view and the agent's cannot drift.
- */
-export const describeSchedule = (record) => ({
-    id: record.id,
-    agentId: record.agentId,
-    cadence: describeCadence(record.cadence),
-    prompt: record.prompt,
-    trust: record.trust ?? 'unknown',
-    ...(record.destination ? { destination: canonicalDestination(record.destination) } : {}),
-    ...(record.nextFireAt ? { nextFireAt: record.nextFireAt } : {}),
-    ...(record.lastFiredAt ? { lastFiredAt: record.lastFiredAt } : {}),
-    createdAt: record.createdAt,
-});
-/**
- * The four `schedule.*` tools over one handle.
- *
- * Risk is split per tool, not per toolset: creating a schedule spends
- * future money unattended and (with a destination) mints a standing
- * permission to speak, so `schedule.every` and `schedule.at` are `gated` —
- * the approval of THAT call is the human decision the whole step leans on.
- * `schedule.list` is a read, and `schedule.cancel` only ever narrows
- * authority — it is the reversal the risk note in the spec names — so both
- * are `safe`: a headless agent that set a bad schedule must be able to
- * undo it without waiting for the human whose absence is the problem.
- */
-export const createScheduleTools = (scheduler) => {
-    const create = async (session, cadence, input) => {
-        const prompt = typeof input.prompt === 'string' ? input.prompt.trim() : '';
-        if (!prompt) {
-            throw new Error('A schedule needs a non-empty "prompt" — the instruction each firing runs.');
-        }
-        if (input.destination !== undefined && parseDestinationInput(input.destination) === undefined) {
-            throw new Error('"destination" must be { channel, to } with non-empty strings, or omitted.');
-        }
-        const destination = parseDestinationInput(input.destination);
-        const record = await scheduler.create({
-            agentId: session.agent.id,
-            cadence,
-            prompt,
-            ...(destination ? { destination } : {}),
-            createdBy: session.id,
-            trust: sessionWriteTrust(session),
-        });
-        return { created: true, schedule: describeSchedule(record) };
-    };
-    return [
-        {
-            name: SCHEDULE_EVERY_TOOL_NAME,
-            description: 'Set a recurring schedule for yourself: an interval ("30m", "1d") or a five-field cron expression, the prompt each firing runs, and optionally the destination your reports are pre-authorized to post to. Creating a schedule needs human approval once; its firings then run unattended.',
-            risk: 'gated',
-            parameters: {
-                type: 'object',
-                properties: {
-                    every: { type: 'string', description: 'Interval like "90s", "30m", "2h", "1d". Exactly one of "every" or "cron".' },
-                    cron: { type: 'string', description: 'Five-field cron expression (minute hour day-of-month month day-of-week), local time. Exactly one of "every" or "cron".' },
-                    prompt: { type: 'string', description: 'The instruction each firing runs, phrased to stand alone.' },
-                    destination: DESTINATION_PARAMETER,
-                },
-                required: ['prompt'],
-            },
-            async execute(input, session) {
-                const every = typeof input.every === 'string' ? input.every.trim() : '';
-                const cron = typeof input.cron === 'string' ? input.cron.trim() : '';
-                if ((every === '') === (cron === '')) {
-                    throw new Error('Pass exactly one of "every" (an interval) or "cron" (a cron expression).');
-                }
-                if (every) {
-                    const intervalMs = parseInterval(every);
-                    if (intervalMs === undefined) {
-                        throw new Error(`Not an interval: "${every}". Use a positive integer and one unit — "90s", "30m", "2h", "1d".`);
-                    }
-                    return create(session, { kind: 'every', intervalMs }, input);
-                }
-                parseCronExpression(cron); // Refuse a bad expression here, with its own message.
-                return create(session, { kind: 'cron', expression: cron }, input);
-            },
-        },
-        {
-            name: SCHEDULE_AT_TOOL_NAME,
-            description: 'Schedule a one-shot run of a prompt at a future time (ISO-8601). Needs human approval once; the firing then runs unattended.',
-            risk: 'gated',
-            parameters: {
-                type: 'object',
-                properties: {
-                    at: { type: 'string', description: 'When to fire, ISO-8601 (e.g. 2026-09-01T07:00:00). Must be in the future.' },
-                    prompt: { type: 'string', description: 'The instruction the firing runs, phrased to stand alone.' },
-                    destination: DESTINATION_PARAMETER,
-                },
-                required: ['at', 'prompt'],
-            },
-            async execute(input, session) {
-                const at = typeof input.at === 'string' ? input.at.trim() : '';
-                const parsed = new Date(at);
-                if (!at || Number.isNaN(parsed.getTime())) {
-                    throw new Error(`Not a timestamp: "${at}". Use ISO-8601, e.g. 2026-09-01T07:00:00.`);
-                }
-                if (parsed.getTime() <= Date.now()) {
-                    throw new Error(`${at} is in the past — a one-shot schedule must name a future time.`);
-                }
-                return create(session, { kind: 'at', at: parsed.toISOString() }, input);
-            },
-        },
-        {
-            name: SCHEDULE_LIST_TOOL_NAME,
-            description: 'List your own schedules: cadence, prompt, destination, and when each fires next.',
-            // A read of state this agent itself created.
-            risk: 'safe',
-            parameters: { type: 'object', properties: {} },
-            async execute(_input, session, context) {
-                const records = await scheduler.list(session.agent.id);
-                // Each prompt was written by the session that set the schedule, at
-                // that session's label — and a schedule from before labels existed
-                // has none. Listing puts those prompts in front of the model, so the
-                // call is marked at the lowest of them, as `memory.recall` marks a
-                // hit: a fresh session must not restate a tainted prompt as its own.
-                const lowest = leastTrusted(...records.map((record) => record.trust ?? 'unknown'));
-                if (records.length > 0 && isTaintedTrust(lowest)) {
-                    context?.markTrust?.(lowest);
-                }
-                return { schedules: records.map(describeSchedule) };
-            },
-        },
-        {
-            name: SCHEDULE_CANCEL_TOOL_NAME,
-            description: 'Cancel one of your schedules by id. Cancelling also revokes the pre-authorized destination that was approved with it.',
-            // Cancel only ever NARROWS authority — it destroys a human-minted
-            // grant — and it is the reversal that keeps schedule creation short
-            // of `dangerous`. Gating it would leave a headless agent unable to
-            // undo its own schedule for want of the human whose absence is the
-            // point of headless.
-            risk: 'safe',
-            parameters: {
-                type: 'object',
-                properties: {
-                    id: { type: 'string', description: 'The schedule id, from schedule.list or the creation result.' },
-                },
-                required: ['id'],
-            },
-            async execute(input, session) {
-                const id = typeof input.id === 'string' ? input.id.trim() : '';
-                if (!id) {
-                    throw new Error('schedule.cancel requires a non-empty "id".');
-                }
-                const cancelled = await scheduler.cancel(session.agent.id, id);
-                if (!cancelled) {
-                    throw new Error(`No schedule of yours has id ${id}. schedule.list shows what exists.`);
-                }
-                return { cancelled: true, id };
-            },
-        },
-    ];
-};
-/**
- * Post to a channel or DM outside the current conversation — what makes a
- * scheduled turn observable.
- *
- * `gated`, and deliberately not `safe` the way `agent.delegate` is: the
- * delegate stays inside the fleet, under every per-agent allowlist and the
- * same approval policy, while this speaks to people who did not ask. The
- * unattended path is the schedule carve-out — `destinationFor` names where
- * this call would speak, and the policy allows it exactly when the firing's
- * schedule was approved with that destination.
- */
-export const createMessageSendTool = (send) => ({
-    name: MESSAGE_SEND_TOOL_NAME,
-    description: 'Send a message to a channel or DM you are not currently talking in. Scheduled turns may post to their schedule\'s approved destination without asking; anywhere else needs approval.',
-    risk: 'gated',
-    parameters: {
-        type: 'object',
-        properties: {
-            destination: {
-                ...DESTINATION_PARAMETER,
-                description: 'Where to post: the channel kind plus the channel-native conversation id.',
-            },
-            text: { type: 'string', description: 'The message text.' },
-        },
-        required: ['destination', 'text'],
-    },
-    destinationFor(input) {
-        const destination = parseDestinationInput(input.destination);
-        return destination ? canonicalDestination(destination) : undefined;
-    },
-    async execute(input, session) {
-        const destination = parseDestinationInput(input.destination);
-        if (!destination) {
-            throw new Error('message.send requires "destination" as { channel, to } with non-empty strings.');
-        }
-        const text = typeof input.text === 'string' ? input.text.trim() : '';
-        if (!text) {
-            throw new Error('message.send requires a non-empty "text".');
-        }
-        await send({ agentId: session.agent.id, destination, text });
-        return { sent: true, destination: canonicalDestination(destination) };
-    },
-});
+// The package's one public surface: every export below is re-exported by
+// name from the module that owns it. What an agent *is* — its identity,
+// its soul file, its skills — sits at the top level; `tools/` holds the
+// tool factories an agent is given (memory, delegation, schedules,
+// message.send), each with the tool names it owns.
+export { AVATAR_STYLE, generateAgentName, generateAvatarTheme, AGENT_ID_PATTERN, MAX_AGENT_ID_LENGTH, isValidAgentId, isValidDelegateEntry, MAX_SESSION_ID_LENGTH, isValidSessionId, agentIdWithSuffix, } from "./identity.js";
+export { defineAgent } from "./define.js";
+export { isDelegateAllowed, parseSoul, formatSoul, } from "./soul.js";
+export { SKILL_ID_PATTERN, SKILL_ID_MAX_LENGTH, isValidSkillId, isLoadableSkillId, SKILL_ID_RULE, SKILL_DESCRIPTION_MAX_LENGTH, SKILL_COMPATIBILITY_MAX_LENGTH, parseSkillDocument, validateSkillDocument, createLazySkill, } from "./skills.js";
+export { canonicalDestination, parseInterval, parseCronExpression, nextFireAfter, describeCadence, SCHEDULE_ID_METADATA_KEY, SCHEDULED_TURN_METADATA_KEY, describeSchedule, } from "./schedules.js";
+export { createAgentRouter, createAgentTeam, } from "./router.js";
+export { MEMORY_TOOL_NAME, createRememberTool, RECALL_TOOL_NAME, createRecallTool, FORGET_TOOL_NAME, createForgetTool, PIN_TOOL_NAME, createPinTool, } from "./tools/memory.js";
+export { DELEGATE_TOOL_NAME, DELEGATED_BY_METADATA_KEY, ROOT_SESSION_ID_METADATA_KEY, DELEGATION_DEPTH_METADATA_KEY, DELEGATED_SESSION_ID_MARKER, isDelegatedSession, delegatingSessionIdOf, outstandingDelegationFor, withoutDelegation, createDelegateTool, } from "./tools/delegate.js";
+export { SCHEDULE_EVERY_TOOL_NAME, SCHEDULE_AT_TOOL_NAME, SCHEDULE_LIST_TOOL_NAME, SCHEDULE_CANCEL_TOOL_NAME, createScheduleTools, } from "./tools/schedule.js";
+export { MESSAGE_SEND_TOOL_NAME, createMessageSendTool, } from "./tools/message.js";
+export { GATEWAY_ONLY_TOOL_NAMES } from "./tools/gateway-only.js";
 //# sourceMappingURL=index.js.map