@songsid/agend 2.2.1 → 2.2.5

package/dist/web-mod-agent.js

@@ -0,0 +1,207 @@
+/**
+ * #1629 r4 §4 (r4-5b): an agent and mods — export_web_mod and propose_web_mod. Neither takes a target: the caller is
+ * the instance its IPC connection or agent token belongs to.
+ *
+ * - export_web_mod { name, version, title? }: its own look as a bundle — its theme with its pictures, its own card
+ *   text (the agent's fields, never a person's), and the widgets it placed. Never custom CSS and never the sidebar: no
+ *   agent path reaches a person's. The fleet builds the bytes; the daemon (or agend-agent) writes them to
+ *   `.agend/mods/<name>-<version>.agendmod.json` in the agent's working directory — whole, or fetched in parts.
+ * - propose_web_mod { file }: a bundle from its working directory (read on its side; sent in parts), checked whole and
+ *   kept as a proposal a person reviews in Settings → Appearance → Mods. Anything carrying custom CSS is refused
+ *   (owner_css_not_from_agent): provenance is the path the bytes came in by, never what the file says. It counts as an
+ *   upload, and the fleet switch and a person's lock refuse it. Agents never import.
+ */
+import { createHash, randomBytes } from "node:crypto";
+import { ASSET_PART_BYTES, MOD_UPLOAD_MAX_BYTES } from "./web-asset-parts.js";
+import { agentAppearanceEditAllowed } from "./web-appearance-policy.js";
+import { checkModBundle } from "./web-mod-bundle.js";
+import { buildModBundle } from "./web-mod-export.js";
+import { AGENT_WIDGET_SLOTS } from "./web-widget.js";
+import { canonicalText } from "./web-theme.js";
+import { filesPlayInChat } from "./web-effect.js";
+/** An exported mod that fits one message is sent whole; a larger one is fetched in parts (as a preview is). */
+export const MOD_INLINE_BYTES = 600 * 1024;
+export const MOD_IDLE_MS = 60_000;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const SEMVER = /^(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})\.(0|[1-9]\d{0,5})$/;
+export class AgentMods {
+    deps;
+    built = new Map();
+    uploads = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    now() { return (this.deps.clock ?? (() => performance.now()))(); }
+    handle(instance, tool, args) {
+        const now = this.now();
+        for (const [k, b] of this.built)
+            if (now - b.last > MOD_IDLE_MS)
+                this.built.delete(k);
+        for (const [k, u] of this.uploads)
+            if (now - u.last > MOD_IDLE_MS && k !== instance)
+                this.uploads.delete(k);
+        if (tool === "export_web_mod")
+            return args.part !== undefined ? this.exportPart(instance, args.part, now) : this.exportMod(instance, args, now);
+        if (tool === "propose_web_mod")
+            return this.propose(instance, args, now);
+        return { error: "unknown_tool" };
+    }
+    /** export_web_mod: the caller's own look, as a bundle file. */
+    exportMod(instance, args, now) {
+        if (typeof args.name !== "string" || !SLUG.test(args.name))
+            return { error: "name", message: "name: a-z, 0-9 and - (1..64)" };
+        if (typeof args.version !== "string" || !SEMVER.test(args.version))
+            return { error: "version", message: "version: MAJOR.MINOR.PATCH" };
+        // The importer's own rule (#1897 review): what is exported always imports.
+        const title = canonicalText(args.title === undefined ? args.name : args.title, 1, 60);
+        if (title === null)
+            return { error: "title", message: "title: 1..60 characters on one line" };
+        const rec = this.deps.themes.get(instance);
+        const parts = {};
+        const { card, ...look } = rec.theme;
+        let omitted = 0;
+        if (Object.keys(look).length > 1 || rec.placements.effects.length) {
+            // #2017: an older placement of an effect that doesn't play in chat stays out (a mod can't place it): counted.
+            const effects = rec.placements.effects.flatMap(p => { const e = this.deps.readOwnEffect?.(instance, p.id); if (!e || !filesPlayInChat(e.files)) {
+                omitted++;
+                return [];
+            } return [{ name: e.name, files: e.files, params: p.params ?? {} }]; });
+            // A default look whose placed effects are all someone else's has nothing of its own to carry (#1910 review).
+            if (Object.keys(look).length > 1 || effects.length)
+                parts.theme = { theme: { ...look, v: 1 }, picture: id => { const a = rec.assets.find(x => x.id === id); const b = this.deps.themes.asset(instance, id); return a && b ? { bytes: b.bytes, kind: a.kind } : null; }, effects };
+        }
+        // Its own card text: the agent's fields (a person's card fields are theirs, kept elsewhere, and never exported here).
+        if (card?.tagline || card?.bio)
+            parts.identity = { ...(card.tagline ? { tagline: card.tagline } : {}), ...(card.bio ? { bio: card.bio } : {}) };
+        for (const slot of AGENT_WIDGET_SLOTS) {
+            const w = rec.placements.widgets[slot];
+            if (w && w.by === "agent")
+                (parts.widgets ??= {})[slot] = { spec: w.spec, data: w.data };
+        }
+        // #2117: the ambients it set itself (one a person set is theirs).
+        const ambient = Object.fromEntries(Object.entries(rec.placements.ambient).flatMap(([k, a]) => a && a.by === "agent" ? [[k, a.spec]] : []));
+        if (Object.keys(ambient).length)
+            parts.ambient = { specs: ambient, picture: id => { const a = rec.assets.find(x => x.id === id); const b = this.deps.themes.asset(instance, id); return a && b ? { bytes: b.bytes, kind: a.kind } : null; } };
+        const built = buildModBundle({ name: args.name, version: args.version, title }, parts);
+        if (!built.ok)
+            return { error: built.error, message: built.error === "nothing_to_export" ? "You have no theme, card text, widgets or ambient effect of your own to export." : "A picture your theme names is missing.", ...(omitted ? { effects_omitted: omitted } : {}) };
+        const data = Buffer.from(built.text, "utf8");
+        const sha256 = createHash("sha256").update(data).digest("hex");
+        const omittedNote = omitted ? { effects_omitted: omitted } : {};
+        if (data.length <= MOD_INLINE_BYTES)
+            return { files: [{ name: built.filename, data_b64: data.toString("base64") }], ...omittedNote };
+        const b = { id: randomBytes(8).toString("hex"), name: built.filename, data, sha256, last: now };
+        this.built.set(instance, b); // one per instance: a new export replaces it
+        return { transfer: b.id, files: [{ name: b.name, bytes: data.length, sha256, parts: Math.ceil(data.length / ASSET_PART_BYTES) }], ...omittedNote };
+    }
+    exportPart(instance, raw, now) {
+        const p = raw;
+        const b = this.built.get(instance);
+        if (!p || typeof p !== "object" || !b || p.transfer !== b.id || p.name !== b.name)
+            return { error: "export", message: "No such export: ask for it again." };
+        const count = Math.ceil(b.data.length / ASSET_PART_BYTES);
+        if (!Number.isSafeInteger(p.index) || p.index < 0 || p.index >= count)
+            return { error: "part", message: "No such part." };
+        b.last = now;
+        const i = p.index;
+        return { data_b64: b.data.subarray(i * ASSET_PART_BYTES, (i + 1) * ASSET_PART_BYTES).toString("base64") };
+    }
+    /** Why the caller may not propose now, or null: the fleet switch, a person's lock (uploads are not counted: the user's decision). */
+    refusal(instance) {
+        if (!agentAppearanceEditAllowed(this.deps.webConfig()))
+            return { error: "theme_editing_off", message: "Agent theme and effect changes are turned off for this fleet (web.themes.agent_edit: false)." };
+        if (this.deps.themes.get(instance).locked)
+            return { error: "locked", message: "Theme and effects are locked by a person." };
+        return null;
+    }
+    /** propose_web_mod: the bytes the daemon or agend-agent read on the agent's side — whole, or in parts. */
+    propose(instance, args, now) {
+        if (typeof args.data_b64 !== "string" || !/^[A-Za-z0-9+/]*={0,2}$/.test(args.data_b64))
+            return { error: "data", message: "The file's bytes are missing." };
+        const fail = (error, message) => { this.uploads.delete(instance); return { error, message }; };
+        if (args.part === undefined) {
+            const refused = this.refusal(instance);
+            if (refused)
+                return refused;
+            const bytes = Buffer.from(args.data_b64, "base64");
+            if (bytes.length > MOD_UPLOAD_MAX_BYTES)
+                return { error: "mod_too_large", message: "at most 8 MiB" };
+            return this.finish(instance, bytes);
+        }
+        const p = args.part;
+        if (!p || typeof p !== "object" || Array.isArray(p))
+            return fail("part", "part: { index, count, bytes, sha256, upload? }");
+        const { index, count, bytes, sha256 } = p;
+        if (!Number.isSafeInteger(index) || !Number.isSafeInteger(count) || !Number.isSafeInteger(bytes) || typeof sha256 !== "string" || !/^[0-9a-f]{64}$/.test(sha256))
+            return fail("part", "part: { index, count, bytes, sha256, upload? }");
+        const chunk = Buffer.from(args.data_b64, "base64");
+        if (chunk.length < 1 || chunk.length > ASSET_PART_BYTES)
+            return fail("part", `each part is 1..${ASSET_PART_BYTES} bytes`);
+        if (index === 0) {
+            const refused = this.refusal(instance);
+            if (refused) {
+                this.uploads.delete(instance);
+                return refused;
+            }
+            if (bytes < 1 || bytes > MOD_UPLOAD_MAX_BYTES)
+                return fail("mod_too_large", "at most 8 MiB");
+            if (count !== Math.ceil(bytes / ASSET_PART_BYTES))
+                return fail("part", "count does not match bytes");
+            this.uploads.set(instance, { id: randomBytes(8).toString("hex"), count: count, next: 0, bytes: bytes, sha256, parts: [], received: 0, last: now });
+        }
+        const up = this.uploads.get(instance);
+        if (!up || (index !== 0 && p.upload !== up.id))
+            return fail("upload", "No such upload in progress: start again from part 0.");
+        if (now - up.last > MOD_IDLE_MS)
+            return fail("upload", "The upload waited too long between parts: start again from part 0.");
+        if (index !== up.next || count !== up.count || bytes !== up.bytes || sha256 !== up.sha256)
+            return fail("part", `expected part ${up.next} of the same upload`);
+        if (up.received + chunk.length > up.bytes)
+            return fail("part", "more bytes than declared");
+        up.parts.push(chunk);
+        up.received += chunk.length;
+        up.next += 1;
+        up.last = now;
+        if (up.next < up.count)
+            return { upload: up.id, received: up.received };
+        this.uploads.delete(instance);
+        const all = Buffer.concat(up.parts);
+        if (all.length !== up.bytes || createHash("sha256").update(all).digest("hex") !== up.sha256)
+            return { error: "part", message: "The parts do not add up to the declared file." };
+        const refused = this.refusal(instance);
+        if (refused)
+            return refused;
+        return this.finish(instance, all);
+    }
+    finish(instance, bytes) {
+        let text;
+        try {
+            text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+        }
+        catch {
+            return { error: "mod_invalid", errors: [{ path: "", problem: "not UTF-8" }] };
+        }
+        // By the path it came in by: an agent's file never brings custom CSS, whatever else it says (checked first).
+        let carriesCss = false;
+        try {
+            const doc = JSON.parse(text);
+            carriesCss = !!doc?.manifest?.contents && Object.hasOwn(doc.manifest.contents, "ownerCss");
+        }
+        catch { /* the check below says why */ }
+        if (carriesCss)
+            return { error: "owner_css_not_from_agent", message: "A mod an agent proposes can't carry custom CSS: that is a person's own, set only by them." };
+        const checked = checkModBundle(text, this.deps.context());
+        if (!checked.ok)
+            return { error: "mod_invalid", errors: checked.problems };
+        const w = this.deps.mods.propose(instance, text, checked.mod);
+        if (!w.ok)
+            return { error: w.error, ...(w.detail ? { detail: w.detail } : {}) };
+        const m = checked.mod.manifest;
+        this.deps.notice(instance, `Proposed a mod: ${m.title} (${m.name} ${m.version}). A person can review it in Settings → Web appearance → Mods.`);
+        this.deps.changed();
+        return { proposed: { id: checked.mod.id, name: m.name, version: m.version, title: m.title, bytes: checked.mod.bytes }, message: "A person reviews it in Settings → Web appearance → Mods; nothing changes until they install it." };
+    }
+    /** An instance was removed. */
+    forget(instance) { this.built.delete(instance); this.uploads.delete(instance); }
+}
+//# sourceMappingURL=web-mod-agent.js.map

package/dist/web-mod-agent.js.map

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

package/dist/web-mod-bundle.d.ts

@@ -0,0 +1,157 @@
+import type { AppearanceLimits } from "./web-appearance-limits.js";
+import { type MediaKind } from "./web-image-meta.js";
+import { type Theme } from "./web-theme.js";
+import { type AmbientKind, type AmbientSpec } from "./web-ambient.js";
+import { type WidgetData, type WidgetSlot, type WidgetSpec } from "./web-widget.js";
+export declare const MOD_FORMAT = "agend-mod";
+export declare const MOD_MAX_BYTES: number;
+export declare const MOD_MAX_FILES = 128;
+export declare const MOD_MAX_EFFECTS = 8;
+/** A path inside a bundle: lowercase, no leading dot or slash, no `..` segment, no empty segment. */
+export declare const MOD_PATH: RegExp;
+export interface ModProblem {
+    path: string;
+    problem: string;
+}
+export interface ModManifest {
+    name: string;
+    version: string;
+    title: string;
+    description?: string;
+    author?: string;
+    requires?: {
+        agend: string;
+    };
+    contents: {
+        theme?: string;
+        identity?: string;
+        widgets?: Partial<Record<WidgetSlot, string>>;
+        /** #2117: `{ loop?, click? }`, each a set_web_ambient spec whose glyph pictures are `{ asset: <path in the bundle> }`. */
+        ambient?: string;
+        effects?: string[];
+        ownerCss?: {
+            css: string;
+            assets?: string[];
+        };
+    };
+}
+/** An effect entry's files (relative to its directory), as the effect runtime's checker takes them. */
+export type EffectFiles = ReadonlyMap<string, Uint8Array>;
+/** What the plan shows of an effect entry (the runtime's checker says it). */
+export interface EffectSummary {
+    id: string;
+    title: string;
+    bytes: number;
+    regions: string[];
+    wants: string[];
+    params: string[];
+}
+/**
+ * The effect runtime's side, as the bundle needs it (CW1, Sol's B2): the pure entry checker and param resolver. Null
+ * while this fleet has no effect runtime: a bundle with effects is then refused (effects_unavailable).
+ */
+export interface ModEffectChecker {
+    check(files: EffectFiles): {
+        ok: true;
+        summary: EffectSummary;
+        manifest: unknown;
+    } | {
+        ok: false;
+        problems: ModProblem[];
+    };
+    /** Resolve a placement's overrides against the entry's params: the non-default ones, or refused. */
+    params(manifest: unknown, overrides: unknown): {
+        ok: true;
+        overrides: Record<string, unknown>;
+    } | {
+        ok: false;
+        error: string;
+    };
+}
+export interface ModPicture {
+    path: string;
+    slot: "background" | "avatar" | "glyph";
+    id: string;
+    kind: MediaKind;
+    kept: Uint8Array;
+}
+export interface CheckedMod {
+    id: string;
+    manifest: ModManifest;
+    /** The raw file's size. */
+    bytes: number;
+    theme?: {
+        theme: Theme;
+        pictures: ModPicture[];
+        effects: Array<{
+            effect: string;
+            params: Record<string, unknown>;
+        }>;
+    };
+    identity?: {
+        tagline?: string;
+        bio?: string;
+    };
+    widgets: Partial<Record<WidgetSlot, {
+        spec: WidgetSpec;
+        data: WidgetData;
+    }>>;
+    /** #2117: the ambients (one per kind) and the glyph pictures they name. */
+    ambient?: {
+        specs: Partial<Record<AmbientKind, AmbientSpec>>;
+        pictures: ModPicture[];
+    };
+    effects: Array<{
+        path: string;
+        files: EffectFiles;
+        summary: EffectSummary;
+        manifest: unknown;
+    }>;
+    ownerCss?: {
+        text: string;
+        assets: Array<{
+            path: string;
+            id: string;
+            kind: MediaKind;
+            kept: Uint8Array;
+        }>;
+    };
+}
+export interface ModContext {
+    /** The running AgEnD version (`requires.agend` is checked against it); null: unknown, a `requires` is refused. */
+    agendVersion: string | null;
+    limits: AppearanceLimits;
+    effects: ModEffectChecker | null;
+    /**
+     * #2017: whether a theme's placements must name effects that play in chat. On for a new import or proposal (the
+     * default); off when an installed mod's file is read again — what was installed before the rule stays as it was.
+     */
+    placementRegions?: boolean;
+}
+/** Stable JSON: keys sorted at every level. */
+export declare function canonicalJson(v: unknown): string;
+/** A bundle's identity: the first 32 hex of the sha256 of its canonical manifest and sorted [path, sha256] list. */
+export declare function modBundleId(manifest: unknown, files: Iterable<[string, string]>): string;
+/**
+ * Parse and check a whole bundle. `text` is the file as uploaded (UTF-8 JSON). All or nothing: the first problems are
+ * returned (at most 20), and nothing in a refused bundle is ever used.
+ */
+export declare function checkModBundle(text: string, ctx: ModContext): {
+    ok: true;
+    mod: CheckedMod;
+} | {
+    ok: false;
+    problems: ModProblem[];
+};
+/** A file's entry for a bundle being built (export). */
+export declare function modFile(bytes: Uint8Array): {
+    sha256: string;
+    b64: string;
+};
+/** The extension a picture or CSS asset is exported under. */
+export declare function modAssetName(base: string, kind: MediaKind): string;
+/**
+ * The effect runtime's checker (CW1: Sol's src/web-effect-bundle.ts and src/web-effect.ts) as a bundle uses it. Used
+ * once the fleet has an effect library to install into; until then the fleet passes null and effects are refused.
+ */
+export declare function cw1EffectChecker(): ModEffectChecker;