@stratusagent/agents 0.11.3 → 0.11.5

package/dist/skills.d.ts

@@ -0,0 +1,135 @@
+import type { Skill } from '@stratusagent/core';
+/**
+ * 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 declare const SKILL_ID_PATTERN: RegExp;
+/** The spec's ceiling on `name`, and so on a skill id. */
+export declare const SKILL_ID_MAX_LENGTH = 64;
+export declare const isValidSkillId: (id: string) => boolean;
+/**
+ * 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 declare const isLoadableSkillId: (id: string) => boolean;
+/** What a skill id refusal says, everywhere one is refused. */
+export declare 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 declare const SKILL_DESCRIPTION_MAX_LENGTH = 1024;
+/** The spec's ceiling on `compatibility`. */
+export declare const SKILL_COMPATIBILITY_MAX_LENGTH = 500;
+/**
+ * A parsed `SKILL.md`: the one-line identity that reaches the system
+ * prompt, and the body that only ever travels through `skill.read`.
+ */
+export interface ParsedSkillDocument {
+    /**
+     * The skill's name — under the spec, its id, and equal to its directory
+     * name. Optional here because loading stays tolerant of what is already
+     * installed; the registered skill falls back to its id.
+     */
+    name?: string;
+    /**
+     * When to reach for this skill — what routing runs on, so it earns its
+     * place by saying when, not what the body contains.
+     */
+    description: string;
+    /** The spec's `license`: a name, or a bundled file. Informational. */
+    license?: string;
+    /**
+     * The spec's `compatibility`: what the skill needs from its environment,
+     * in prose — for the operator installing it, since nothing here can act
+     * on it.
+     */
+    compatibility?: string;
+    /** The spec's `metadata:` map, verbatim — every value a string. */
+    metadata?: Record<string, string>;
+    /** `metadata.version`, or the legacy top-level key. Informational. */
+    version?: string;
+    /**
+     * Toolset globs the procedure expects (`browser.*`), from
+     * `metadata.requires` (space-separated) or the legacy top-level list.
+     * Advisory — see `Skill.requires`.
+     */
+    requires?: string[];
+    /**
+     * Top-level keys outside the spec, in file order — the legacy Stratus
+     * keys and other hosts' fields alike. What validation warns about.
+     */
+    unknownKeys: string[];
+    body: string;
+}
+/**
+ * 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 declare const parseSkillDocument: (source: string) => ParsedSkillDocument;
+export interface ValidateSkillDocumentOptions {
+    /**
+     * The directory the skill sits in (its basename), which the spec
+     * requires `name` to equal. Omit where the directory is circumstance
+     * rather than identity — a repository whose root is the skill, checked
+     * out wherever git put it.
+     */
+    directoryName?: string;
+    /**
+     * What to suggest when `name` is missing — the directory name, or for a
+     * root skill the repository's. Only ever read for the error text.
+     */
+    suggestedName?: string;
+}
+/** What `validateSkillDocument` found: errors refuse an install, warnings ride along. */
+export interface SkillValidation {
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * 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 declare const validateSkillDocument: (document: ParsedSkillDocument, options?: ValidateSkillDocumentOptions) => SkillValidation;
+export interface LazySkillInput {
+    /** The id the skill registers under — qualified for a plugin's skill. */
+    id: string;
+    /** The parsed document, from the load-time read that validated the file. */
+    document: ParsedSkillDocument;
+    /** Re-read the file's source. Called on demand; the registry caches. */
+    read: () => Promise<string>;
+}
+/**
+ * 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 declare const createLazySkill: ({ id, document, read }: LazySkillInput) => Skill;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAGhD;;;;;;;;GAQG;AACH,eAAO,MAAM,gBAAgB,QAA+B,CAAC;AAE7D,0DAA0D;AAC1D,eAAO,MAAM,mBAAmB,KAAK,CAAC;AAEtC,eAAO,MAAM,cAAc,GAAI,IAAI,MAAM,KAAG,OACmB,CAAC;AAOhE;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,IAAI,MAAM,KAAG,OAA2C,CAAC;AAE3F,+DAA+D;AAC/D,eAAO,MAAM,aAAa,uGAC4E,CAAC;AAEvG,2CAA2C;AAC3C,eAAO,MAAM,4BAA4B,OAAO,CAAC;AAEjD,6CAA6C;AAC7C,eAAO,MAAM,8BAA8B,MAAM,CAAC;AAsBlD;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,mEAAmE;IACnE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,kBAAkB,GAAI,QAAQ,MAAM,KAAG,mBAyCnD,CAAC;AAEF,MAAM,WAAW,4BAA4B;IAC3C;;;;;OAKG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,yFAAyF;AACzF,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,GAChC,UAAU,mBAAmB,EAC7B,UAAS,4BAAiC,KACzC,eAmDF,CAAC;AAEF,MAAM,WAAW,cAAc;IAC7B,yEAAyE;IACzE,EAAE,EAAE,MAAM,CAAC;IACX,4EAA4E;IAC5E,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,wEAAwE;IACxE,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,GAAI,wBAAwB,cAAc,KAAG,KAMvE,CAAC"}

package/dist/skills.js

@@ -0,0 +1,167 @@
+import { parseFrontmatterLines, extractFrontmatter } from "./frontmatter.js";
+/**
+ * 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,
+});
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

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

package/dist/soul.d.ts

@@ -0,0 +1,44 @@
+import { type AgentDefinition } from '@stratusagent/core';
+/**
+ * Whether `agent` may delegate to the agent with id `targetId`. Exact ids
+ * or `*`; no namespace globs, because agent ids have no namespaces. Omitted
+ * is nobody — see `AgentDefinition.delegates`.
+ */
+export declare const isDelegateAllowed: (agent: Pick<AgentDefinition, "delegates">, targetId: string) => boolean;
+/**
+ * A parsed soul file: the agent it defines plus optional runtime hints.
+ * Souls are markdown with frontmatter — the frontmatter carries structured
+ * identity (name, tools, credentials, provider, model) and the body is the
+ * persona itself, written in prose.
+ */
+export interface ParsedSoul {
+    agent: AgentDefinition;
+    /** Provider the soul prefers (e.g. "anthropic"). Runtimes may override. */
+    provider?: string;
+    /** Model the soul prefers (e.g. "claude-opus-5"). Runtimes may override. */
+    model?: string;
+}
+export interface ParseSoulOptions {
+    /** Seed for deterministic identity generation when the soul has no name. */
+    seed?: string;
+}
+/**
+ * The soul edit that grants one delegate, as the refusal suggests it. The
+ * inline form, `delegates: [a, "b, c"]`, quoted when the inline parser
+ * would otherwise split or unquote the id, in whichever quote it does not
+ * contain — and the block form when the id holds both quotes, since no
+ * inline spelling of `a"',b` reads back as one entry, while a block line
+ * is never split and is unquoted only for matching outer quotes, which
+ * {@link writeScalar} guards. Rendered this carefully because
+ * `delegates: [foo,bar]` is a grant to two agents and a refusal of the
+ * one the message was about.
+ */
+export declare const suggestedDelegatesEdit: (value: string) => string;
+/**
+ * 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 declare const parseSoul: (source: string, options?: ParseSoulOptions) => ParsedSoul;
+export declare const formatSoul: (soul: ParsedSoul) => string;
+//# sourceMappingURL=soul.d.ts.map

package/dist/soul.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"soul.d.ts","sourceRoot":"","sources":["../src/soul.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,KAAK,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAUxF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,OAAO,IAAI,CAAC,eAAe,EAAE,WAAW,CAAC,EAAE,UAAU,MAAM,KAAG,OAClB,CAAC;AAE/E;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,eAAe,CAAC;IACvB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,4EAA4E;IAC5E,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAMD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,GAAI,OAAO,MAAM,KAAG,MAWtD,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,QAAQ,MAAM,EAAE,UAAS,gBAAqB,KAAG,UAkC1E,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,MAAM,UAAU,KAAG,MA8B7C,CAAC"}

package/dist/soul.js

@@ -0,0 +1,98 @@
+import { isListensMode, LISTENS_MODES } from '@stratusagent/core';
+import { defineAgent } from "./define.js";
+import { unquote, parseFrontmatterLines, extractFrontmatter, writeScalar, } from "./frontmatter.js";
+/**
+ * Whether `agent` may delegate to the agent with id `targetId`. Exact ids
+ * or `*`; no namespace globs, because agent ids have no namespaces. Omitted
+ * is nobody — see `AgentDefinition.delegates`.
+ */
+export const isDelegateAllowed = (agent, targetId) => (agent.delegates ?? []).some((entry) => entry === '*' || entry === targetId);
+const SOUL_SCALAR_KEYS = ['name', 'id', 'provider', 'model', 'listens'];
+const SOUL_LIST_KEYS = ['tools', 'skills', 'credentials', 'delegates'];
+/**
+ * The soul edit that grants one delegate, as the refusal suggests it. The
+ * inline form, `delegates: [a, "b, c"]`, quoted when the inline parser
+ * would otherwise split or unquote the id, in whichever quote it does not
+ * contain — and the block form when the id holds both quotes, since no
+ * inline spelling of `a"',b` reads back as one entry, while a block line
+ * is never split and is unquoted only for matching outer quotes, which
+ * {@link writeScalar} guards. Rendered this carefully because
+ * `delegates: [foo,bar]` is a grant to two agents and a refusal of the
+ * one the message was about.
+ */
+export const suggestedDelegatesEdit = (value) => {
+    if (!/[,"'\s]/.test(value) && unquote(value) === value) {
+        return `delegates: [${value}]`;
+    }
+    if (!value.includes('"')) {
+        return `delegates: ["${value}"]`;
+    }
+    if (!value.includes("'")) {
+        return `delegates: ['${value}']`;
+    }
+    return `a delegates: list with the line "- ${writeScalar(value)}"`;
+};
+/**
+ * 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 } : {}),
+        ...(lists.delegates ? { delegates: lists.delegates } : {}),
+        ...(isListensMode(scalars.listens) ? { listens: scalars.listens } : {}),
+        ...(options.seed !== undefined ? { seed: options.seed } : {}),
+    });
+    return {
+        agent,
+        ...(scalars.provider ? { provider: scalars.provider } : {}),
+        ...(scalars.model ? { model: scalars.model } : {}),
+    };
+};
+export const formatSoul = (soul) => {
+    const lines = ['---', `name: ${writeScalar(soul.agent.name)}`, `id: ${writeScalar(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],
+        ['delegates', soul.agent.delegates],
+    ]) {
+        if (values && values.length > 0) {
+            lines.push(`${key}:`);
+            for (const value of values) {
+                lines.push(`  - ${writeScalar(value)}`);
+            }
+        }
+    }
+    lines.push('---', '');
+    lines.push(soul.agent.instructions ?? 'Describe who this agent is and how they talk.');
+    lines.push('');
+    return lines.join('\n');
+};
+//# sourceMappingURL=soul.js.map

package/dist/soul.js.map

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

package/dist/tools/delegate.d.ts

@@ -0,0 +1,93 @@
+import { AgentRegistry, type AgentDefinition, type AgentRunner, type JsonObject, type Session, type Tool } from '@stratusagent/core';
+export declare 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 declare const DELEGATED_BY_METADATA_KEY = "delegatedBy";
+export declare const ROOT_SESSION_ID_METADATA_KEY = "rootSessionId";
+export declare 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 declare 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 declare const isDelegatedSession: (session: Pick<Session, "id" | "metadata">) => boolean;
+/**
+ * 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 declare const delegatingSessionIdOf: (sessionId: string) => string | 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 declare const outstandingDelegationFor: (parent: Pick<Session, "messages">, child: Pick<Session, "agent" | "messages">) => string | 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 declare const withoutDelegation: (metadata: JsonObject) => JsonObject;
+/**
+ * Runs a delegated sub-session. A plain runner works when every agent
+ * shares one provider; a host with per-agent provider routing (the
+ * gateway) supplies its own dispatcher so the target runs on the
+ * target's resolved provider and credentials — never the delegator's.
+ */
+export type DelegateDispatch = (input: {
+    sessionId: string;
+    agent: AgentDefinition;
+    userMessage: string;
+    metadata: JsonObject;
+    /** The parent turn's abort signal — a cancelled parent cancels the delegated run too. */
+    signal?: AbortSignal;
+}) => Promise<Session>;
+export type DelegateToolOptions = {
+    registry: AgentRegistry;
+    /** Maximum delegation depth to stop orchestrator loops. Default 3. */
+    maxDepth?: number;
+} & ({
+    runner: AgentRunner;
+    dispatch?: never;
+} | {
+    dispatch: DelegateDispatch;
+    runner?: never;
+});
+/**
+ * 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 declare const createDelegateTool: ({ registry, runner, dispatch, maxDepth, }: DelegateToolOptions) => Tool;
+//# sourceMappingURL=delegate.d.ts.map

package/dist/tools/delegate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.d.ts","sourceRoot":"","sources":["../../src/tools/delegate.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EAIb,KAAK,eAAe,EACpB,KAAK,WAAW,EAChB,KAAK,UAAU,EACf,KAAK,OAAO,EACZ,KAAK,IAAI,EACV,MAAM,oBAAoB,CAAC;AAG5B,eAAO,MAAM,kBAAkB,mBAAmB,CAAC;AAEnD;;;;;;GAMG;AACH,eAAO,MAAM,yBAAyB,gBAAgB,CAAC;AAEvD,eAAO,MAAM,4BAA4B,kBAAkB,CAAC;AAE5D,eAAO,MAAM,6BAA6B,oBAAoB,CAAC;AAE/D;;;;;;;;GAQG;AACH,eAAO,MAAM,2BAA2B,eAAe,CAAC;AAExD;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,UAAU,CAAC,KAAG,OAE1B,CAAC;AAEtD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,GAAI,WAAW,MAAM,KAAG,MAAM,GAAG,SAGlE,CAAC;AAEF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,wBAAwB,GACnC,QAAQ,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,EACjC,OAAO,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,UAAU,CAAC,KACzC,MAAM,GAAG,SA8BX,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,GAAI,UAAU,UAAU,KAAG,UAQxD,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,eAAe,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,UAAU,CAAC;IACrB,yFAAyF;IACzF,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,EAAE,aAAa,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB,GAAG,CAAC;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,QAAQ,EAAE,gBAAgB,CAAC;IAAC,MAAM,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC,CAAC;AAIjG;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,GAAI,2CAKhC,mBAAmB,KAAG,IA6HxB,CAAC"}