@withbuddi/buddi 0.1.0-pre.30 → 0.1.0-pre.32

package/packages/gateway/dist/agents/platform-catalogue.js

@@ -0,0 +1,1021 @@
+/**
+ * The agent catalogue on the platform's side (agent-catalogue.md §5, §7, §8):
+ * where a listed package stands on this installation, and the gated tool that
+ * adds one, or updates one already added.
+ *
+ * Adding a package is accepting a proposal by another name, so it is built on
+ * the very same pieces `platform.accept_plugin_agent` is: `buildCreateEnvelope`
+ * (the id and handle checks, `checkTools`, the "would this file load" parse),
+ * the account the accepting agent speaks through, the same create preview
+ * naming the whole grant. On top: the v1 denylist, the package's integrity
+ * (checked when the listing was read), the picks rendered as "## For this
+ * owner", the missions created off unless chosen, the picture, and a sidecar
+ * recording `source: market`.
+ *
+ * Updating is the same tool with `agent`: an agent whose file is untouched is
+ * written again from the new package with the same picks; one the owner
+ * edited is never touched unless they ask to replace their changes, and then
+ * their file goes to the trash first. Existing missions are the owner's rows
+ * and are never edited; new suggested ones arrive off.
+ *
+ * Nothing here reaches the network: the listings, the picks' choices and the
+ * picture come through a `CatalogueService` the gateway binds
+ * (`web/catalogue-source.ts`), so this module never imports a web route and a
+ * test hands in a fixture.
+ */
+import { existsSync, readdirSync, readFileSync, rmSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { AGENT_FILE, applyFrontmatterPatch, assertApprovedEffect, getMission, HANDLE_MAX, hashEnvelope, parseAgentFile, parseSkillFile, satisfiesRange, setSchedule, SKILLS_DIR, STARTER_MAX, upsertMission, } from '@buddi/core';
+import { z } from 'zod';
+import { composePackagePersona, cronAt, cronClock, deniedTools, fileHash, parseClock, } from './catalogue-package.js';
+import { composeProvenance, fileEdited, packageOwnedText, readProvenance, PROVENANCE_FILE } from '../plugins/provenance.js';
+import { composeAgentFile, composeSkillFile, createAgentDirAtomic, trashStamp, writeFilesAtomic } from './platform-files.js';
+import { diffGrant, grantChangeBlock } from './platform-grant.js';
+import { agentMissionId, describeCadence } from '../missions/reminders.js';
+import { normaliseAvatar } from './avatar-image.js';
+import { readAvatar, writeAvatar } from './avatars.js';
+/** Said when there is neither a fresh list nor a copy. */
+export const CATALOGUE_OFFLINE = "The catalogue needs withbuddi.com; try again when you're online.";
+/**
+ * The skills written with this agent that the owner has changed or deleted
+ * since, by name. Only the skills the sidecar recorded: one the owner added
+ * is theirs and no update touches it.
+ */
+export function editedSkills(dir, provenance) {
+    const out = [];
+    for (const [name, hash] of Object.entries(provenance.skills ?? {})) {
+        const file = path.join(dir, SKILLS_DIR, `${name}.md`);
+        try {
+            if (fileHash(readFileSync(file, 'utf8')) !== hash)
+                out.push(name);
+        }
+        catch {
+            out.push(name);
+        }
+    }
+    return out;
+}
+/** Every agent directory with a sidecar, read once. */
+export function addedAgents(agentsDir) {
+    if (!existsSync(agentsDir))
+        return [];
+    const out = [];
+    for (const name of readdirSync(agentsDir).sort()) {
+        if (name.startsWith('.'))
+            continue;
+        const dir = path.join(agentsDir, name);
+        const file = path.join(dir, AGENT_FILE);
+        try {
+            if (!statSync(dir).isDirectory() || !existsSync(file))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const provenance = readProvenance(dir);
+        if (!provenance)
+            continue;
+        let edited = true;
+        try {
+            // The `skills:` grants are the owner's, not the package's: they never count here.
+            edited = fileEdited(provenance.file, readFileSync(file, 'utf8')) || editedSkills(dir, provenance).length > 0;
+        }
+        catch {
+            edited = true;
+        }
+        out.push({ agentId: name, dir, file, provenance, edited });
+    }
+    return out;
+}
+/** Is this added agent a copy of the package, directly or by `replaces`? */
+export function matchesPackage(pkg, added) {
+    const p = added.provenance;
+    if (p.source === 'market' && p.package === pkg.manifest.name)
+        return 'package';
+    if (pkg.manifest.replaces.includes(`${p.plugin}/${p.agent}`))
+        return 'replaces';
+    return null;
+}
+export function installedAsFor(pkg, added, handleOf) {
+    const direct = added.find((a) => matchesPackage(pkg, a) === 'package');
+    const match = direct ?? added.find((a) => matchesPackage(pkg, a) === 'replaces');
+    if (!match)
+        return undefined;
+    const via = direct ? undefined : `${match.provenance.plugin}/${match.provenance.agent}`;
+    const moved = via !== undefined || match.provenance.proposal !== pkg.manifest.integrity;
+    const drift = match.edited ? (moved && via === undefined ? 'edited-update' : 'edited') : moved ? 'update' : 'current';
+    return {
+        agentId: match.agentId,
+        handle: handleOf(match.agentId),
+        version: match.provenance.version,
+        drift,
+        ...(via === undefined ? {} : { via }),
+    };
+}
+/** The plugins a package requires that are not loaded here in range, each with its fix. */
+export function missingPlugins(pkg, ctx) {
+    const loaded = new Map(ctx.registry.manifests().map((m) => [m.name, m.version]));
+    const out = [];
+    for (const [name, range] of Object.entries(pkg.manifest.requires)) {
+        const version = loaded.get(name);
+        if (version !== undefined) {
+            if (satisfiesRange(version, range) === false)
+                out.push({ kind: 'plugin', name, range, fix: 'update', installed: version });
+            continue;
+        }
+        const record = ctx.plugins.find((p) => p.name === name);
+        if (!record)
+            out.push({ kind: 'plugin', name, range, fix: 'install' });
+        else if (satisfiesRange(record.version, range) === false)
+            out.push({ kind: 'plugin', name, range, fix: 'update', installed: record.version });
+        else
+            out.push({ kind: 'plugin', name, range, fix: 'enable' });
+    }
+    return out;
+}
+/** The version a `buddi` range is read against: a checkout's "0.1.0 (v0.1.0-3-g…)" is its first word. */
+export function plainVersion(version) {
+    return version.trim().split(/\s+/)[0] ?? version;
+}
+export function packageState(pkg, ctx) {
+    const installed = installedAsFor(pkg, ctx.added, ctx.handleOf);
+    if (installed)
+        return { state: 'installed', installed };
+    if (satisfiesRange(plainVersion(ctx.version), pkg.manifest.buddi) === false) {
+        return { state: 'unavailable', reason: `Needs buddi ${pkg.manifest.buddi}; this is ${plainVersion(ctx.version)}. Update buddi first.` };
+    }
+    const missing = [...missingPlugins(pkg, ctx)];
+    for (const need of pkg.manifest.needs) {
+        // `mailbox?` makes it better and never holds it back.
+        if (need === 'mailbox?')
+            continue;
+        if (!ctx.needs[need])
+            missing.push({ kind: 'need', name: need, fix: need === 'mailbox' ? 'mailbox' : 'accounts' });
+    }
+    return missing.length === 0 ? { state: 'ready' } : { state: 'needs', missing };
+}
+export class CatalogueRefusal extends Error {
+    code;
+    name = 'PlatformRefusal';
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function refuse(code, message) {
+    throw new CatalogueRefusal(code, message);
+}
+export const installAgentInput = z
+    .object({
+    name: z.string().min(1).describe('The package, as platform.catalogue lists it: "chef".'),
+    version: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The version the owner saw. Refused when the catalogue has moved on, so they approve what they read.'),
+    handle: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A handle the owner asked for. Leave it out for the package\'s own, or a free one beside it (chef-2).'),
+    fills: z
+        .record(z.string(), z.string())
+        .optional()
+        .describe('The picks platform.catalogue lists for it, by id: a mailbox address, calendar names (comma-separated, empty for ' +
+        'all), a saved place, a mission hour as HH:MM, or one line of text. Leave a pick out for its default.'),
+    missionsOn: z
+        .array(z.string().min(1))
+        .optional()
+        .describe('The package missions the owner asked to turn on now, by id. Every other mission arrives off.'),
+    account: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('A named model account the owner picked. Leave it out and it speaks through the same account you do.'),
+    agent: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('Update this agent, already added from the package (or an older one it replaces), instead of adding a new one: ' +
+        'by id or handle.'),
+    replaceEdits: z
+        .literal(true)
+        .optional()
+        .describe('Only when the owner said to replace their own changes to that agent\'s file. Their file goes to the trash first.'),
+    plan: z
+        .string()
+        .min(1)
+        .optional()
+        .describe('The plan fingerprint the dashboard or `buddi agents` showed the owner. Refused when anything it covers moved ' +
+        '(the package, the grant, the files on disk). Leave it out from chat: your approval card is the preview.'),
+})
+    .strict();
+function freeName(base, taken, max) {
+    if (!taken(base))
+        return base;
+    for (let n = 2; n < 100; n += 1) {
+        const suffix = `-${n}`;
+        const candidate = `${base.slice(0, max - suffix.length).replace(/-+$/, '')}${suffix}`;
+        if (!taken(candidate))
+            return candidate;
+    }
+    refuse('no-free-name', `every name from ${base} to ${base}-99 is taken`);
+}
+/** The picks answered, with each default filled in (§7). */
+export function resolvePicks(pkg, given, choices) {
+    const answers = given ?? {};
+    const known = new Set(pkg.manifest.fills.map((f) => f.id));
+    const stray = Object.keys(answers).filter((id) => !known.has(id));
+    if (stray.length > 0) {
+        refuse('unknown-pick', `${pkg.manifest.title} asks no "${stray.join('", "')}". Its picks: ${pkg.manifest.fills.map((f) => f.id).join(', ') || 'none'}.`);
+    }
+    return pkg.manifest.fills.map((fill) => {
+        const raw = answers[fill.id]?.trim();
+        let value;
+        switch (fill.kind) {
+            case 'mailbox': {
+                value = raw ?? choices.mailboxes[0] ?? '';
+                if (raw !== undefined && raw !== '' && choices.mailboxes.length > 0 && !choices.mailboxes.some((m) => m.toLowerCase() === raw.toLowerCase())) {
+                    refuse('bad-pick', `"${raw}" is not one of your mailboxes (${choices.mailboxes.join(', ')}).`);
+                }
+                break;
+            }
+            case 'calendar': {
+                value = raw ?? '';
+                const names = value.split(',').map((s) => s.trim()).filter(Boolean);
+                const unknown = choices.calendars.length === 0 ? [] : names.filter((n) => !choices.calendars.includes(n));
+                if (raw !== undefined && unknown.length > 0) {
+                    refuse('bad-pick', `${unknown.join(', ')} ${unknown.length === 1 ? 'is not a linked calendar' : 'are not linked calendars'} (${choices.calendars.join(', ')}).`);
+                }
+                value = names.join(', ');
+                break;
+            }
+            case 'place': {
+                const fallback = choices.places.find((p) => p.id === 'home')?.label ?? choices.places[0]?.label ?? '';
+                const wanted = raw;
+                if (wanted === undefined || wanted === '') {
+                    value = raw === '' ? '' : fallback;
+                }
+                else {
+                    const match = choices.places.find((p) => p.id === wanted.toLowerCase() || p.label.toLowerCase() === wanted.toLowerCase());
+                    if (!match && raw !== undefined && choices.places.length > 0) {
+                        refuse('bad-pick', `"${raw}" is not one of your saved places (${choices.places.map((p) => p.label).join(', ')}).`);
+                    }
+                    value = match?.label ?? wanted;
+                }
+                break;
+            }
+            case 'time': {
+                const mission = pkg.manifest.missions.find((m) => m.id === fill.mission);
+                value = raw ?? (mission ? cronClock(mission.cron) : null) ?? '';
+                if (value !== '' && parseClock(value) === null)
+                    refuse('bad-pick', `"${value}" is not a time of day (HH:MM, like 07:30).`);
+                if (value !== '') {
+                    const [h, m] = parseClock(value);
+                    value = `${String(h).padStart(2, '0')}:${String(m).padStart(2, '0')}`;
+                }
+                break;
+            }
+            case 'text': {
+                value = raw ?? '';
+                if (/[\r\n]/.test(value))
+                    refuse('bad-pick', `"${fill.label}" takes one line.`);
+                if (value.length > 200)
+                    refuse('bad-pick', `"${fill.label}" takes at most 200 characters.`);
+                break;
+            }
+        }
+        return { id: fill.id, kind: fill.kind, label: fill.label, value };
+    });
+}
+/** Lines that differ, `- ` removed and `+ ` added, from a plain longest-common-subsequence. */
+export function lineDiff(before, after) {
+    const a = before.trim().split('\n');
+    const b = after.trim().split('\n');
+    const n = a.length;
+    const m = b.length;
+    const table = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i -= 1) {
+        for (let j = m - 1; j >= 0; j -= 1) {
+            table[i][j] = a[i] === b[j] ? table[i + 1][j + 1] + 1 : Math.max(table[i + 1][j], table[i][j + 1]);
+        }
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < n && j < m) {
+        if (a[i] === b[j]) {
+            i += 1;
+            j += 1;
+        }
+        else if (table[i + 1][j] >= table[i][j + 1]) {
+            out.push(`- ${a[i]}`);
+            i += 1;
+        }
+        else {
+            out.push(`+ ${b[j]}`);
+            j += 1;
+        }
+    }
+    while (i < n)
+        out.push(`- ${a[i++]}`);
+    while (j < m)
+        out.push(`+ ${b[j++]}`);
+    return out;
+}
+/** The package the input names, read from the catalogue the gateway keeps; a refusal otherwise. */
+export async function findPackage(service, name) {
+    if (!service)
+        refuse('no-catalogue', 'this process has no catalogue bound, so no package can be added from it');
+    const loaded = await service.load();
+    if ('unavailable' in loaded)
+        refuse('offline', `${CATALOGUE_OFFLINE} (${loaded.unavailable})`);
+    const pkg = loaded.packages.find((p) => p.manifest.name === name.trim().toLowerCase());
+    if (!pkg) {
+        const refused = loaded.problems.find((p) => p.startsWith(`${name.trim().toLowerCase()}:`));
+        if (refused)
+            refuse('refused-listing', refused);
+        refuse('unknown-package', `the catalogue lists no agent "${name}". Listed: ${loaded.packages.map((p) => p.manifest.name).join(', ') || 'nothing'}. ` +
+            'Call platform.catalogue to see them.');
+    }
+    return pkg;
+}
+/** The example asks the agent file can carry as its starters (each at most STARTER_MAX characters). */
+function starters(pkg) {
+    return pkg.manifest.examples.filter((example) => example.trim().length <= STARTER_MAX).map((example) => example.trim());
+}
+function pickRecord(picks) {
+    return Object.fromEntries(picks.map((p) => [p.id, p.value]));
+}
+function missionPlans(pkg, agentId, picks, timezone, on) {
+    return pkg.manifest.missions.map((m) => {
+        const time = pkg.manifest.fills.find((f) => f.kind === 'time' && f.mission === m.id);
+        const clock = time ? picks.find((p) => p.id === time.id)?.value : undefined;
+        return {
+            id: agentMissionId(agentId, m.id),
+            slug: m.id,
+            name: m.name,
+            cron: clock ? cronAt(m.cron, clock) : m.cron,
+            timezone,
+            prompt: m.prompt,
+            enabled: on.has(m.id),
+            ...(m.alwaysDeliver === undefined ? {} : { alwaysDeliver: m.alwaysDeliver }),
+            ...(m.misfirePolicy === undefined ? {} : { misfirePolicy: m.misfirePolicy }),
+        };
+    });
+}
+function packageSkills(pkg, agentDir) {
+    return pkg.skills.map((skill) => {
+        const content = composeSkillFile({
+            name: skill.name,
+            description: skill.description,
+            provenance: 'imported',
+            source: `catalogue/${pkg.manifest.name}@${pkg.manifest.version}`,
+            body: skill.body,
+        });
+        try {
+            parseSkillFile(content, { fileName: skill.name });
+        }
+        catch (err) {
+            refuse('would-not-load', `${pkg.manifest.title} carries a skill the loader refuses: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        return { name: skill.name, description: skill.description, file: path.join(agentDir, SKILLS_DIR, `${skill.name}.md`), content };
+    });
+}
+function checkDenied(pkg, resolvedTools) {
+    const denied = deniedTools(pkg.manifest.tools, resolvedTools);
+    if (denied.length > 0) {
+        refuse('denied-tool', `${pkg.manifest.title} asks for ${denied.join(', ')}, which no catalogue agent may be given. ` +
+            'You can add any of them by hand after it is added.');
+    }
+}
+/**
+ * The plan the owner was shown, as one fingerprint: the whole envelope but who
+ * proposed it — the package's integrity, the resolved grant, the file's and
+ * every affected skill's hash as they are now, the missions. The dashboard and
+ * `buddi agents` send it back with the click, so the approval the route
+ * records is the plan the owner read, or nothing (agent-catalogue.md §8).
+ */
+export function planFingerprint(envelope) {
+    const { proposedBy: _proposedBy, created, ...rest } = envelope;
+    const bound = created ? { ...rest, created: { ...created, proposedBy: '' } } : rest;
+    return hashEnvelope(bound);
+}
+/**
+ * Build the envelope for adding (or, with `agent`, updating) a package, and
+ * refuse it when the plan the owner was shown (`plan`) is no longer it.
+ */
+export async function buildInstallEnvelope(input, deps) {
+    const envelope = await composeInstallEnvelope(input, deps);
+    if (input.plan !== undefined && planFingerprint(envelope) !== input.plan) {
+        refuse('plan-moved', `what ${envelope.mode === 'update' ? `updating @${envelope.handle}` : `adding ${envelope.package.title}`} would do changed since ` +
+            'it was shown (the package, the tools it gets, or a file on disk). Look at it again before you approve it.');
+    }
+    return envelope;
+}
+/**
+ * Compose the envelope. Everything knowable is checked here, before any
+ * approval exists.
+ */
+async function composeInstallEnvelope(input, deps) {
+    const { registry, helpers } = deps;
+    const service = helpers.service(registry);
+    const pkg = await findPackage(service, input.name);
+    const m = pkg.manifest;
+    if (input.version !== undefined && input.version.trim() !== m.version) {
+        refuse('version-moved', `the catalogue now lists ${m.title} ${m.version}, not ${input.version}. Look at it again before adding it.`);
+    }
+    const version = await service.version();
+    if (satisfiesRange(plainVersion(version), m.buddi) === false) {
+        refuse('buddi-too-old', `${m.title} needs buddi ${m.buddi}; this is ${plainVersion(version)}. Update buddi first.`);
+    }
+    const missing = missingPlugins(pkg, { registry, plugins: service.plugins() });
+    if (missing.length > 0) {
+        refuse('missing-plugin', `${m.title} needs ${missing.map((p) => `the ${p.name} plugin${p.fix === 'update' ? ` ${p.range} (${p.installed} is installed)` : p.fix === 'enable' ? ' (installed, but off)' : ''}`).join(' and ')}. ` +
+            'Adding it from the catalogue installs a missing by-buddi plugin on the way; from here, install it first.');
+    }
+    const needs = await service.needs();
+    const unmet = m.needs.filter((need) => need !== 'mailbox?' && !needs[need]);
+    if (unmet.length > 0 && input.agent === undefined) {
+        refuse('missing-need', `${m.title} needs ${unmet.map((n) => (n === 'mailbox' ? 'a mailbox (Settings → Email)' : 'an account that draws (Settings → Model accounts)')).join(' and ')} first.`);
+    }
+    const binding = helpers.resolved(registry);
+    const choices = m.fills.some((f) => f.kind === 'mailbox' || f.kind === 'calendar' || f.kind === 'place')
+        ? await service.choices()
+        : { mailboxes: [], calendars: [], places: [] };
+    const known = new Set(m.missions.map((mission) => mission.id));
+    const strayMissions = (input.missionsOn ?? []).filter((id) => !known.has(id));
+    if (strayMissions.length > 0) {
+        refuse('unknown-mission', `${m.title} has no mission "${strayMissions.join('", "')}". Its missions: ${[...known].join(', ') || 'none'}.`);
+    }
+    const avatar = pkg.avatar && pkg.avatarSha256 ? { url: pkg.avatar, sha256: pkg.avatarSha256 } : null;
+    const packageInfo = { name: m.name, version: m.version, integrity: m.integrity, title: m.title, changes: m.changes };
+    if (input.agent !== undefined)
+        return buildUpdate(input, deps, pkg, binding, choices, packageInfo, avatar);
+    if (input.replaceEdits !== undefined)
+        refuse('not-an-update', '`replaceEdits` goes with `agent`, the agent being updated');
+    const already = installedAsFor(pkg, addedAgents(binding.agentsDir), (id) => binding.catalog.get(id)?.handle ?? id);
+    if (already) {
+        refuse('already-added', `${m.title} is already on the team as @${already.handle}${already.via ? ` (from ${already.via})` : ''}. ` +
+            (already.drift === 'update' ? `To bring it to ${m.version}, update it (agent: "${already.agentId}").` : 'Nothing to add.'));
+    }
+    const takenId = (id) => binding.catalog.get(id) !== undefined || existsSync(path.join(binding.agentsDir, id));
+    const takenHandle = (handle) => binding.catalog.list().some((a) => a.handle.toLowerCase() === handle.toLowerCase());
+    const id = freeName(m.name, takenId, 40);
+    const handle = input.handle !== undefined ? input.handle.trim().replace(/^@/, '').toLowerCase() : freeName(m.handle, takenHandle, HANDLE_MAX);
+    const picks = resolvePicks(pkg, input.fills, choices);
+    const speaks = input.account === undefined ? helpers.speakingAccount(registry, deps.proposedBy) : null;
+    const created = helpers.buildCreate({
+        id,
+        handle,
+        name: m.title,
+        description: m.description,
+        persona: composePackagePersona(pkg.persona, picks),
+        tools: [...m.tools],
+        ...(m.language === undefined ? {} : { language: m.language }),
+        ...(m.idleRollover === undefined ? {} : { idleRollover: m.idleRollover }),
+        ...(starters(pkg).length === 0 ? {} : { starters: starters(pkg) }),
+        ...(m.roles === undefined || m.roles.length === 0 ? {} : { roles: [...m.roles] }),
+        ...(input.account !== undefined ? { account: input.account } : speaks ? { account: speaks.account.label, model: speaks.account.model } : {}),
+    }, { registry, proposedBy: deps.proposedBy });
+    checkDenied(pkg, created.tools);
+    const agentDir = path.dirname(created.file);
+    return {
+        tool: 'platform.install_agent',
+        mode: 'install',
+        proposedBy: deps.proposedBy,
+        package: packageInfo,
+        id: created.id,
+        handle: created.handle,
+        name: created.name,
+        description: created.description,
+        file: created.file,
+        tools: created.tools,
+        declaredTools: created.declaredTools,
+        account: created.account,
+        inheritedFrom: created.account === null ? null : (speaks?.from ?? null),
+        content: created.content,
+        skills: packageSkills(pkg, agentDir),
+        missions: missionPlans(pkg, created.id, picks, deps.timezone, new Set(input.missionsOn ?? [])),
+        picks,
+        avatar,
+        created,
+    };
+}
+async function buildUpdate(input, deps, pkg, binding, choices, packageInfo, avatar) {
+    const { registry, helpers } = deps;
+    const m = pkg.manifest;
+    const wanted = input.agent.trim().replace(/^@/, '');
+    const agent = binding.catalog.get(wanted) ?? binding.catalog.byHandle(wanted);
+    if (!agent)
+        refuse('unknown-agent', `there is no agent "${input.agent}" here`);
+    const dir = path.dirname(agent.file);
+    const added = addedAgents(path.dirname(dir)).find((a) => a.agentId === path.basename(dir));
+    const how = added ? matchesPackage(pkg, added) : null;
+    if (!added || how === null) {
+        refuse('not-from-package', `@${agent.handle} did not come from ${m.title} in the catalogue, so there is nothing to update; it is yours as it is.`);
+    }
+    const via = how === 'replaces' ? `${added.provenance.plugin}/${added.provenance.agent}` : null;
+    if (how === 'package' && added.provenance.proposal === m.integrity && !added.edited) {
+        refuse('up-to-date', `@${agent.handle} is already ${m.title} ${m.version}, unchanged on both sides.`);
+    }
+    // Every skill file the update touches, as it is now. A file of the same name the
+    // earlier version never wrote is the owner's (or a learned one): replacing it is
+    // replacing their work. A skill the earlier version wrote and this one dropped
+    // goes to the trash, or it would keep running with nobody's provenance on it.
+    const skills = packageSkills(pkg, dir);
+    const tracked = added.provenance.skills ?? {};
+    const readNow = (file) => {
+        try {
+            return readFileSync(file, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    };
+    const skillsBefore = {};
+    const replacesOwn = [];
+    for (const skill of skills) {
+        const now = readNow(skill.file);
+        skillsBefore[skill.name] = now === null ? null : fileHash(now);
+        if (now !== null && !(skill.name in tracked) && now !== skill.content)
+            replacesOwn.push(skill.name);
+    }
+    const retires = [];
+    for (const name of Object.keys(tracked).sort()) {
+        if (skills.some((skill) => skill.name === name))
+            continue;
+        const now = readNow(path.join(dir, SKILLS_DIR, `${name}.md`));
+        skillsBefore[name] = now === null ? null : fileHash(now);
+        if (now !== null)
+            retires.push(name);
+    }
+    const edited = added.edited || replacesOwn.length > 0;
+    if (edited && input.replaceEdits !== true) {
+        refuse('owner-edited', replacesOwn.length > 0 && !added.edited
+            ? `@${agent.handle} has ${replacesOwn.length === 1 ? 'a skill' : 'skills'} of your own (${replacesOwn.join(', ')}) that ` +
+                `${m.title} ${m.version} would replace with ${replacesOwn.length === 1 ? 'one' : 'ones'} of the same name, so nothing will ` +
+                'touch it. To replace them, the owner has to say so (replaceEdits), and theirs go to the trash first.'
+            : `you have changed @${agent.handle}'s file or one of its skills, so nothing will touch it. ${m.title} ${m.version} is out; ` +
+                'to replace your changes with it, the owner has to say so (replaceEdits), and their file goes to the trash first.');
+    }
+    if (input.handle !== undefined)
+        refuse('not-a-field', 'an update keeps the handle; rename it on the Agents page');
+    if (input.missionsOn !== undefined && input.missionsOn.length > 0) {
+        refuse('not-a-field', 'an update adds new missions off and never turns one on; switch them on under Agents → Missions');
+    }
+    const current = readFileSync(agent.file, 'utf8');
+    const before = parseAgentFile(current, { file: agent.file });
+    const remembered = added.provenance.fills ?? {};
+    const keep = Object.fromEntries(Object.entries(remembered).filter(([id]) => m.fills.some((f) => f.id === id)));
+    const picks = resolvePicks(pkg, { ...keep, ...(input.fills ?? {}) }, choices);
+    const persona = composePackagePersona(pkg.persona, picks);
+    const declared = [...m.tools];
+    const tools = helpers.checkTools(declared, registry, agent.id);
+    checkDenied(pkg, tools);
+    const composed = composeAgentFile({
+        id: agent.id,
+        handle: agent.handle,
+        name: m.title,
+        description: m.description,
+        tools: declared,
+        ...(m.language === undefined ? {} : { language: m.language }),
+        ...(m.idleRollover === undefined ? {} : { idleRollover: m.idleRollover }),
+        ...(starters(pkg).length === 0 ? {} : { starters: starters(pkg) }),
+        ...(m.roles === undefined || m.roles.length === 0 ? {} : { roles: [...m.roles] }),
+        persona,
+    });
+    // The skills the owner granted it are theirs, not the package's: an update keeps them.
+    const granted = before.frontmatter.skills ?? [];
+    const content = granted.length === 0 ? composed : applyFrontmatterPatch(composed, { skills: [...granted] }, agent.file);
+    try {
+        parseAgentFile(content, { dirName: agent.id });
+    }
+    catch (err) {
+        refuse('would-not-load', `this would write a file the loader refuses: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const grant = diffGrant(agent.tools, tools);
+    const existing = new Set();
+    if (deps.db) {
+        for (const mission of m.missions) {
+            const row = await getMission(deps.db, agentMissionId(agent.id, mission.id)).catch(() => null);
+            if (row)
+                existing.add(mission.id);
+        }
+    }
+    const missions = missionPlans(pkg, agent.id, picks, deps.timezone, new Set()).filter((plan) => !existing.has(plan.slug));
+    return {
+        tool: 'platform.install_agent',
+        mode: 'update',
+        proposedBy: deps.proposedBy,
+        package: packageInfo,
+        id: agent.id,
+        handle: agent.handle,
+        name: m.title,
+        description: m.description,
+        file: agent.file,
+        tools,
+        declaredTools: declared,
+        account: null,
+        inheritedFrom: null,
+        content,
+        skills,
+        missions,
+        picks,
+        avatar,
+        update: {
+            fromVersion: added.provenance.version,
+            via,
+            edited,
+            previousFile: fileHash(current),
+            skillsBefore,
+            replacesOwn,
+            retires,
+            toolsBefore: [...agent.tools],
+            added: grant.added,
+            removed: grant.removed,
+            widened: grant.widened,
+            personaDiff: lineDiff(before.body, persona),
+        },
+    };
+}
+function missionLines(missions) {
+    return missions.map((mission) => `  ${mission.name}, ${describeCadence(mission.cron, mission.timezone)} — ` +
+        (mission.enabled ? 'ON from the start' : 'off until you turn it on'));
+}
+export function renderInstallPreview(envelope, specs, renderCreate) {
+    const picks = envelope.picks.filter((p) => p.kind !== 'time' && p.value !== '');
+    if (envelope.mode === 'update' && envelope.update) {
+        const u = envelope.update;
+        return [
+            `Update @${envelope.handle} from the catalogue: ${envelope.package.title} ${envelope.package.version}` +
+                ` (you have ${u.via ? `${u.via} ${u.fromVersion}` : u.fromVersion}).`,
+            `What changed: ${envelope.package.changes}`,
+            '',
+            ...(u.edited
+                ? [
+                    u.replacesOwn.length > 0
+                        ? `YOUR OWN SKILL${u.replacesOwn.length === 1 ? '' : 'S'} ${u.replacesOwn.join(', ')} would be replaced by the ` +
+                            `catalogue's of the same name. Approving replaces ${u.replacesOwn.length === 1 ? 'it' : 'them'} (and any change you made ` +
+                            'to its file); your versions are kept in the trash beside your agents, and moving them back restores them.'
+                        : `YOU CHANGED THIS FILE. Approving replaces your changes with the catalogue's; your version is kept in ` +
+                            'the trash beside your agents, and moving it back restores it.',
+                    '',
+                ]
+                : []),
+            ...(u.retires.length > 0
+                ? [
+                    `This version no longer carries ${u.retires.length === 1 ? 'the skill' : 'the skills'} ${u.retires.join(', ')}: ` +
+                        `${u.retires.length === 1 ? 'it goes' : 'they go'} to the trash beside your agents.`,
+                    '',
+                ]
+                : []),
+            ...grantChangeBlock(envelope.handle, { ...diffGrant(u.toolsBefore, envelope.tools) }, specs),
+            '',
+            ...(u.personaDiff.length === 0
+                ? ['Its persona is unchanged.']
+                : ['Its persona changes:', ...u.personaDiff.slice(0, 80).map((line) => `  ${line}`), ...(u.personaDiff.length > 80 ? [`  … and ${u.personaDiff.length - 80} more lines`] : [])]),
+            ...(envelope.missions.length === 0
+                ? []
+                : ['', 'New missions it suggests, each off until you turn it on:', ...missionLines(envelope.missions)]),
+            '',
+            'Missions it already has are yours and stay exactly as they are. Its handle, its account and its memory do not change.',
+            `File:  ${envelope.file}`,
+            `Proposed by ${envelope.proposedBy}.`,
+        ].join('\n');
+    }
+    return [
+        `Add ${envelope.package.title} ${envelope.package.version} from the catalogue (made by buddi).`,
+        '',
+        renderCreate(envelope.created, specs),
+        '',
+        ...(envelope.account === null
+            ? []
+            : [
+                `Speaks through ${envelope.account.label} with ${envelope.account.model}` +
+                    `${envelope.inheritedFrom === null ? '' : ` (from @${envelope.inheritedFrom})`}; change it on the Agents page.`,
+                '',
+            ]),
+        ...(picks.length === 0
+            ? []
+            : ['For this owner (written after its persona):', ...picks.map((p) => `  ${p.label.replace(/[?:.\s]+$/, '')}: ${p.value}`), '']),
+        ...(envelope.skills.length === 0
+            ? []
+            : [
+                `It arrives with ${envelope.skills.length} skill${envelope.skills.length === 1 ? '' : 's'} of its own ` +
+                    '(a procedure in its prompt; it grants no tool and lowers no tier):',
+                ...envelope.skills.map((s) => `  ${s.name} — ${s.description}`),
+                '',
+            ]),
+        ...(envelope.missions.length === 0
+            ? []
+            : [`Its missions (pause or start any of them under Agents → Missions):`, ...missionLines(envelope.missions), '']),
+        `Once you approve, this file is YOURS: an update from the catalogue is always offered, never written`,
+        'without your approval, and a file you change is never touched.',
+    ].join('\n');
+}
+export function entryView(pkg, state, timezone, defaults) {
+    const m = pkg.manifest;
+    return {
+        name: m.name,
+        version: m.version,
+        handle: m.handle,
+        title: m.title,
+        pitch: m.pitch,
+        description: m.description,
+        about: m.about,
+        category: m.category,
+        trust: m.trust,
+        author: m.author,
+        requires: m.requires,
+        optional: m.optional,
+        needs: m.needs,
+        tools: m.tools,
+        missions: m.missions.map((mission) => ({
+            id: mission.id,
+            name: mission.name,
+            cron: mission.cron,
+            when: describeCadence(mission.cron, timezone),
+            prompt: mission.prompt,
+        })),
+        fills: m.fills.map((fill) => ({
+            id: fill.id,
+            kind: fill.kind,
+            label: fill.label,
+            optional: fill.optional === true,
+            default: defaults?.find((d) => d.id === fill.id)?.value ?? '',
+        })),
+        examples: m.examples,
+        skills: pkg.skills.map((s) => s.name),
+        changes: m.changes,
+        replaces: m.replaces,
+        avatar: pkg.avatar,
+        page: pkg.page,
+        ...(m.claims === undefined ? {} : { claims: m.claims }),
+        state: state.state,
+        ...(state.state === 'needs' ? { missing: state.missing } : {}),
+        ...(state.state === 'installed' ? { installed: state.installed } : {}),
+        ...(state.state === 'unavailable' ? { reason: state.reason } : {}),
+    };
+}
+/** A context for `packageState`, read once for a whole list. */
+export async function stateContext(registry, service, binding) {
+    return {
+        registry,
+        version: await service.version(),
+        needs: await service.needs(),
+        plugins: service.plugins(),
+        added: addedAgents(binding.agentsDir),
+        handleOf: (id) => binding.catalog.get(id)?.handle ?? id,
+    };
+}
+export function createCatalogueTools(registry, helpers) {
+    const catalogue = {
+        name: 'platform.catalogue',
+        description: 'The agent catalogue: ready-made teammates buddi publishes on withbuddi.com (a chef, a researcher, a CFO…), ' +
+            'each with what it is for, its category, the picks it asks, its missions (they arrive off) and where it stands ' +
+            'here: ready, needs a plugin or a mailbox, already added (with an update when one is out), or unavailable. ' +
+            'Read this before you offer one, and before you make an agent from scratch: the owner may want one already listed.',
+        tier: 'auto',
+        input: z.object({}).strict(),
+        async execute(_input, ctx) {
+            const service = helpers.service(registry);
+            if (!service)
+                return { unavailable: 'this process has no catalogue bound', agents: [] };
+            const loaded = await service.load();
+            if ('unavailable' in loaded)
+                return { unavailable: CATALOGUE_OFFLINE, agents: [] };
+            const binding = helpers.resolved(registry);
+            const state = await stateContext(registry, service, binding);
+            const choices = loaded.packages.some((p) => p.manifest.fills.length > 0) ? await service.choices() : null;
+            return {
+                fetchedAt: loaded.fetchedAt,
+                ...(loaded.stale ? { stale: true } : {}),
+                agents: loaded.packages.map((pkg) => {
+                    const view = entryView(pkg, packageState(pkg, state), ctx.timezone);
+                    return {
+                        name: view.name,
+                        version: view.version,
+                        title: view.title,
+                        handle: view.handle,
+                        pitch: view.pitch,
+                        category: view.category,
+                        about: view.about,
+                        state: view.state,
+                        ...(view.missing ? { missing: view.missing } : {}),
+                        ...(view.installed ? { installed: view.installed } : {}),
+                        ...(view.reason ? { reason: view.reason } : {}),
+                        picks: pkg.manifest.fills.map((fill) => ({
+                            id: fill.id,
+                            kind: fill.kind,
+                            question: fill.label,
+                            optional: fill.optional === true,
+                            ...(choices && fill.kind === 'mailbox' ? { choices: choices.mailboxes } : {}),
+                            ...(choices && fill.kind === 'calendar' ? { choices: choices.calendars } : {}),
+                            ...(choices && fill.kind === 'place' ? { choices: choices.places.map((p) => p.label) } : {}),
+                        })),
+                        missions: view.missions.map((mission) => ({ id: mission.id, name: mission.name, when: mission.when })),
+                        examples: view.examples,
+                        tools: view.tools,
+                    };
+                }),
+                fromPlugins: helpers
+                    .proposals(registry)
+                    .filter(({ plugin, agent }) => !loaded.packages.some((p) => p.manifest.replaces.includes(`${plugin}/${agent.id}`)))
+                    .map(({ plugin, agent }) => ({
+                    plugin,
+                    id: agent.id,
+                    name: agent.name,
+                    description: agent.description,
+                    accepted: binding.catalog.get(agent.id) !== undefined,
+                })),
+                note: 'Add one with platform.install_agent: ask the owner each pick in a sentence first (a missing answer takes its ' +
+                    'default), and which missions to turn on now. Agents "from" a plugin are added with platform.accept_plugin_agent.',
+            };
+        },
+    };
+    const install = {
+        name: 'platform.install_agent',
+        description: 'Add an agent from the catalogue (platform.catalogue) to the owner\'s team, or update one already added (`agent`). ' +
+            'Its persona is written verbatim with the owner\'s picks after it; it gets exactly the tools the package asks for, ' +
+            'shown to the owner tool by tool; its missions arrive off unless the owner asked for them. Needs the owner\'s ' +
+            'approval, and the file is theirs once written. A package whose plugin is not installed is refused here: the ' +
+            'dashboard\'s catalogue installs a by-buddi plugin on the way, so send the owner there, or install the plugin first.',
+        tier: 'gated',
+        input: installAgentInput,
+        async describe(input, ctx) {
+            const envelope = await buildInstallEnvelope(input, {
+                registry,
+                helpers,
+                proposedBy: ctx.agentId ?? 'unknown',
+                timezone: ctx.timezone,
+                ...(ctx.db ? { db: ctx.db } : {}),
+            });
+            return { envelope, preview: renderInstallPreview(envelope, registry.list(), helpers.renderCreatePreview) };
+        },
+        async execute(input, ctx) {
+            const envelope = await buildInstallEnvelope(input, {
+                registry,
+                helpers,
+                proposedBy: ctx.agentId ?? 'unknown',
+                timezone: ctx.timezone,
+                ...(ctx.db ? { db: ctx.db } : {}),
+            });
+            assertApprovedEffect(ctx, envelope);
+            const binding = helpers.resolved(registry);
+            const dir = path.dirname(envelope.file);
+            const sidecar = composeProvenance({
+                source: 'market',
+                plugin: 'market',
+                package: envelope.package.name,
+                version: envelope.package.version,
+                agent: envelope.package.name,
+                acceptedAt: ctx.now(),
+                proposal: envelope.package.integrity,
+                // Hashed without the owner's `skills:` grants, which an update carries over.
+                file: packageOwnedText(envelope.content),
+                fills: pickRecord(envelope.picks),
+                skills: Object.fromEntries(envelope.skills.map((skill) => [skill.name, skill.content])),
+            });
+            let trashed = null;
+            /** Put the tree back as it was, when the catalogue will not load with the change. */
+            let undo;
+            if (envelope.mode === 'install') {
+                createAgentDirAtomic(dir, {
+                    [AGENT_FILE]: envelope.content,
+                    [PROVENANCE_FILE]: sidecar,
+                    ...Object.fromEntries(envelope.skills.map((skill) => [path.join(SKILLS_DIR, `${skill.name}.md`), skill.content])),
+                });
+                undo = () => rmSync(dir, { recursive: true, force: true });
+            }
+            else {
+                const u = envelope.update;
+                const retiredFile = (name) => path.join(dir, SKILLS_DIR, `${name}.md`);
+                // Every path this touches, as it is now: what an undo writes back.
+                const before = new Map();
+                for (const file of [envelope.file, path.join(dir, PROVENANCE_FILE), ...envelope.skills.map((s) => s.file), ...u.retires.map(retiredFile)]) {
+                    before.set(file, existsSync(file) ? readFileSync(file, 'utf8') : null);
+                }
+                // What goes to the trash, where a deleted agent goes: moving it back restores it.
+                // The owner's file when they changed it; any skill of theirs a package skill
+                // replaces; every skill this version retires.
+                const aside = path.join(binding.trashRoot, 'agents', `${envelope.id}-${trashStamp(ctx.now())}-replaced`);
+                const kept = [];
+                if (u.edited) {
+                    trashed = path.join(aside, AGENT_FILE);
+                    kept.push({ path: trashed, content: before.get(envelope.file) ?? '' });
+                }
+                for (const skill of envelope.skills) {
+                    const now = before.get(skill.file);
+                    if (now !== null && now !== undefined && now !== skill.content)
+                        kept.push({ path: path.join(aside, SKILLS_DIR, `${skill.name}.md`), content: now });
+                }
+                for (const name of u.retires) {
+                    const now = before.get(retiredFile(name));
+                    if (now !== null && now !== undefined)
+                        kept.push({ path: path.join(aside, SKILLS_DIR, `${name}.md`), content: now });
+                }
+                if (kept.length > 0)
+                    writeFilesAtomic(kept);
+                writeFilesAtomic([
+                    { path: envelope.file, content: envelope.content },
+                    { path: path.join(dir, PROVENANCE_FILE), content: sidecar },
+                    ...envelope.skills.map((skill) => ({ path: skill.file, content: skill.content })),
+                ]);
+                for (const name of u.retires)
+                    rmSync(retiredFile(name), { force: true });
+                undo = () => {
+                    writeFilesAtomic([...before].filter((e) => e[1] !== null).map(([file, content]) => ({ path: file, content })));
+                    for (const [file, content] of before)
+                        if (content === null)
+                            rmSync(file, { force: true });
+                    if (kept.length > 0)
+                        rmSync(aside, { recursive: true, force: true });
+                };
+            }
+            const reload = helpers.reload(registry);
+            if (!reload.reloaded) {
+                // A tree the catalogue refuses would not boot either: nothing stays written.
+                undo();
+                helpers.reload(registry);
+                refuse('would-not-load', `${envelope.mode === 'install' ? `${envelope.package.title} was not added` : `@${envelope.handle} was not updated`}, and ` +
+                    `nothing was changed: the agents would not load with it (${reload.error ?? reload.message}).`);
+            }
+            const assigned = envelope.mode === 'install' ? await helpers.assignAccount(registry, envelope.id, envelope.account) : '';
+            let pictured = false;
+            // The package's picture is kept in the database at install, so every page draws it without asking
+            // the market again. An update gives one only to an agent that has none (the fetch failed at install,
+            // or it came through `replaces`); a face the owner chose is never replaced.
+            const wantsPicture = envelope.mode === 'install' || (ctx.db ? (await readAvatar(ctx.db, envelope.id).catch(() => null)) === null : false);
+            if (wantsPicture && envelope.avatar && ctx.db) {
+                // Best effort: an agent without its face is still the agent the owner approved.
+                try {
+                    const service = helpers.service(registry);
+                    const pkg = service ? await findPackage(service, envelope.package.name) : null;
+                    const bytes = pkg ? await service.avatar(pkg) : null;
+                    if (bytes) {
+                        await writeAvatar(ctx.db, envelope.id, await normaliseAvatar(bytes));
+                        pictured = true;
+                    }
+                }
+                catch {
+                    pictured = false;
+                }
+            }
+            const created = [];
+            if (ctx.db) {
+                for (const mission of envelope.missions) {
+                    if (envelope.mode === 'update' && (await getMission(ctx.db, mission.id).catch(() => null)))
+                        continue;
+                    await upsertMission(ctx.db, {
+                        id: mission.id,
+                        name: mission.name,
+                        agentId: envelope.id,
+                        prompt: mission.prompt,
+                        enabled: mission.enabled,
+                        alwaysDeliver: mission.alwaysDeliver ?? false,
+                    });
+                    await setSchedule(ctx.db, mission.id, {
+                        cron: mission.cron,
+                        timezone: mission.timezone,
+                        // The owner's zone of the moment: it follows the owner.
+                        timezoneExplicit: false,
+                        misfirePolicy: mission.misfirePolicy ?? 'coalesce',
+                    });
+                    created.push(mission.id);
+                }
+            }
+            return {
+                ok: true,
+                mode: envelope.mode,
+                id: envelope.id,
+                handle: envelope.handle,
+                file: envelope.file,
+                package: { name: envelope.package.name, version: envelope.package.version },
+                tools: envelope.tools,
+                skills: envelope.skills.map((s) => s.name),
+                missions: created,
+                ...(pictured ? { picture: true } : {}),
+                ...(trashed ? { previousFile: trashed } : {}),
+                live: reload.reloaded,
+                message: (envelope.mode === 'install'
+                    ? `@${envelope.handle} is on the team, and the file is the owner's now. `
+                    : `@${envelope.handle} is ${envelope.package.title} ${envelope.package.version} now${trashed ? `; the owner's previous file is at ${trashed}` : ''}. `) +
+                    `${reload.message}${assigned}`,
+            };
+        },
+    };
+    return [catalogue, install];
+}
+/** The plan the dashboard's sheet draws: the envelope and its preview, nothing written. */
+export async function planInstall(registry, helpers, input, ctx) {
+    const envelope = await buildInstallEnvelope(input, {
+        registry,
+        helpers,
+        proposedBy: ctx.agentId ?? 'owner',
+        timezone: ctx.timezone,
+        ...(ctx.db ? { db: ctx.db } : {}),
+    });
+    return { envelope, preview: renderInstallPreview(envelope, registry.list(), helpers.renderCreatePreview), plan: planFingerprint(envelope) };
+}
+//# sourceMappingURL=platform-catalogue.js.map