@getfamiliar/shared 0.1.16 → 0.1.18

package/build/AssistantAvatar.d.ts

@@ -0,0 +1,72 @@
+/**
+ * The assistant's avatar (`core.assistantAvatar` in `config.yml`): an
+ * Avataaars face described by one value per option. Plain data and
+ * validation only — rendering lives in `@getfamiliar/avatar`.
+ *
+ * Kept free of node imports: browser bundles import it through the
+ * `@getfamiliar/shared/avatar` subpath.
+ */
+/** Config key of the assistant's avatar. */
+export declare const ASSISTANT_AVATAR_CONFIG_KEY = "core.assistantAvatar";
+/** Allowed values per avatar option (the Avataaars option values). */
+export declare const AVATAR_OPTION_VALUES: {
+    readonly topType: readonly ["NoHair", "Eyepatch", "Hat", "Hijab", "Turban", "WinterHat1", "WinterHat2", "WinterHat3", "WinterHat4", "LongHairBigHair", "LongHairBob", "LongHairBun", "LongHairCurly", "LongHairCurvy", "LongHairDreads", "LongHairFrida", "LongHairFro", "LongHairFroBand", "LongHairNotTooLong", "LongHairShavedSides", "LongHairMiaWallace", "LongHairStraight", "LongHairStraight2", "LongHairStraightStrand", "ShortHairDreads01", "ShortHairDreads02", "ShortHairFrizzle", "ShortHairShaggyMullet", "ShortHairShortCurly", "ShortHairShortFlat", "ShortHairShortRound", "ShortHairShortWaved", "ShortHairSides", "ShortHairTheCaesar", "ShortHairTheCaesarSidePart"];
+    readonly accessoriesType: readonly ["Blank", "Kurt", "Prescription01", "Prescription02", "Round", "Sunglasses", "Wayfarers"];
+    readonly hairColor: readonly ["Auburn", "Black", "Blonde", "BlondeGolden", "Brown", "BrownDark", "PastelPink", "Blue", "Platinum", "Red", "SilverGray"];
+    readonly hatColor: readonly ["Black", "Blue01", "Blue02", "Blue03", "Gray01", "Gray02", "Heather", "PastelBlue", "PastelGreen", "PastelOrange", "PastelRed", "PastelYellow", "Pink", "Red", "White"];
+    readonly facialHairType: readonly ["Blank", "BeardLight", "BeardMajestic", "BeardMedium", "MoustacheFancy", "MoustacheMagnum"];
+    readonly facialHairColor: readonly ["Auburn", "Black", "Blonde", "BlondeGolden", "Brown", "BrownDark", "Platinum", "Red", "SilverGray"];
+    readonly clotheType: readonly ["BlazerShirt", "BlazerSweater", "CollarSweater", "GraphicShirt", "Hoodie", "Overall", "ShirtCrewNeck", "ShirtScoopNeck", "ShirtVNeck"];
+    readonly clotheColor: readonly ["Black", "Blue01", "Blue02", "Blue03", "Gray01", "Gray02", "Heather", "PastelBlue", "PastelGreen", "PastelOrange", "PastelRed", "PastelYellow", "Pink", "Red", "White"];
+    readonly graphicType: readonly ["Bat", "Bear", "Cumbia", "Deer", "Diamond", "Hola", "Pizza", "Resist", "Selena", "Skull", "SkullOutline"];
+    readonly eyeType: readonly ["Close", "Cry", "Default", "Dizzy", "EyeRoll", "Happy", "Hearts", "Side", "Squint", "Surprised", "Wink", "WinkWacky"];
+    readonly eyebrowType: readonly ["Angry", "AngryNatural", "Default", "DefaultNatural", "FlatNatural", "FrownNatural", "RaisedExcited", "RaisedExcitedNatural", "SadConcerned", "SadConcernedNatural", "UnibrowNatural", "UpDown", "UpDownNatural"];
+    readonly mouthType: readonly ["Concerned", "Default", "Disbelief", "Eating", "Grimace", "Sad", "ScreamOpen", "Serious", "Smile", "Tongue", "Twinkle", "Vomit"];
+    readonly skinColor: readonly ["Tanned", "Yellow", "Pale", "Light", "Brown", "DarkBrown", "Black"];
+};
+/** An avatar option with a fixed set of values. */
+export type AvatarOptionField = keyof typeof AVATAR_OPTION_VALUES;
+/** A complete avatar: one value per option plus the background color. */
+export type AvatarConfig = {
+    readonly [Field in AvatarOptionField]: (typeof AVATAR_OPTION_VALUES)[Field][number];
+} & {
+    /** Background color as `#rrggbb`. */
+    readonly backgroundColor: string;
+};
+/** Value of the `topType` option (hair, hats). */
+export type AvatarTopType = AvatarConfig["topType"];
+/** Value of the `eyeType` option. */
+export type AvatarEyeType = AvatarConfig["eyeType"];
+/** Value of the `eyebrowType` option. */
+export type AvatarEyebrowType = AvatarConfig["eyebrowType"];
+/** Value of the `mouthType` option. */
+export type AvatarMouthType = AvatarConfig["mouthType"];
+/** The avatar used while `core.assistantAvatar` is unset. */
+export declare const DEFAULT_AVATAR: AvatarConfig;
+/**
+ * Whether an option has a visible effect for the rest of the avatar,
+ * e.g. the hat color only matters for a hat. Editors hide the others.
+ *
+ * @param field The option.
+ * @param config The avatar.
+ * @returns `true` when changing the option changes the picture.
+ */
+export declare function isAvatarOptionRelevant(field: AvatarOptionField, config: AvatarConfig): boolean;
+/**
+ * List what is wrong with a stored avatar: not a mapping, unknown
+ * options, values outside the allowed set, a malformed background color.
+ * Missing options are fine (they fall back to {@link DEFAULT_AVATAR}).
+ *
+ * @param value Raw value of `core.assistantAvatar`.
+ * @returns Human-readable problems, empty when the value is usable as is.
+ */
+export declare function findAvatarConfigProblems(value: unknown): string[];
+/**
+ * Turn a stored avatar into a complete one: every missing or invalid
+ * option takes its {@link DEFAULT_AVATAR} value. Never throws, so a
+ * hand-edited config cannot break rendering.
+ *
+ * @param value Raw value of `core.assistantAvatar`.
+ * @returns A complete avatar.
+ */
+export declare function normalizeAvatarConfig(value: unknown): AvatarConfig;

package/build/AssistantAvatar.js

@@ -0,0 +1,337 @@
+/**
+ * The assistant's avatar (`core.assistantAvatar` in `config.yml`): an
+ * Avataaars face described by one value per option. Plain data and
+ * validation only — rendering lives in `@getfamiliar/avatar`.
+ *
+ * Kept free of node imports: browser bundles import it through the
+ * `@getfamiliar/shared/avatar` subpath.
+ */
+/** Config key of the assistant's avatar. */
+export const ASSISTANT_AVATAR_CONFIG_KEY = "core.assistantAvatar";
+/** Colors of fabric (clothes and hats). */
+const FABRIC_COLORS = [
+    "Black",
+    "Blue01",
+    "Blue02",
+    "Blue03",
+    "Gray01",
+    "Gray02",
+    "Heather",
+    "PastelBlue",
+    "PastelGreen",
+    "PastelOrange",
+    "PastelRed",
+    "PastelYellow",
+    "Pink",
+    "Red",
+    "White",
+];
+/** Allowed values per avatar option (the Avataaars option values). */
+export const AVATAR_OPTION_VALUES = {
+    topType: [
+        "NoHair",
+        "Eyepatch",
+        "Hat",
+        "Hijab",
+        "Turban",
+        "WinterHat1",
+        "WinterHat2",
+        "WinterHat3",
+        "WinterHat4",
+        "LongHairBigHair",
+        "LongHairBob",
+        "LongHairBun",
+        "LongHairCurly",
+        "LongHairCurvy",
+        "LongHairDreads",
+        "LongHairFrida",
+        "LongHairFro",
+        "LongHairFroBand",
+        "LongHairNotTooLong",
+        "LongHairShavedSides",
+        "LongHairMiaWallace",
+        "LongHairStraight",
+        "LongHairStraight2",
+        "LongHairStraightStrand",
+        "ShortHairDreads01",
+        "ShortHairDreads02",
+        "ShortHairFrizzle",
+        "ShortHairShaggyMullet",
+        "ShortHairShortCurly",
+        "ShortHairShortFlat",
+        "ShortHairShortRound",
+        "ShortHairShortWaved",
+        "ShortHairSides",
+        "ShortHairTheCaesar",
+        "ShortHairTheCaesarSidePart",
+    ],
+    accessoriesType: [
+        "Blank",
+        "Kurt",
+        "Prescription01",
+        "Prescription02",
+        "Round",
+        "Sunglasses",
+        "Wayfarers",
+    ],
+    hairColor: [
+        "Auburn",
+        "Black",
+        "Blonde",
+        "BlondeGolden",
+        "Brown",
+        "BrownDark",
+        "PastelPink",
+        "Blue",
+        "Platinum",
+        "Red",
+        "SilverGray",
+    ],
+    hatColor: FABRIC_COLORS,
+    facialHairType: [
+        "Blank",
+        "BeardLight",
+        "BeardMajestic",
+        "BeardMedium",
+        "MoustacheFancy",
+        "MoustacheMagnum",
+    ],
+    facialHairColor: [
+        "Auburn",
+        "Black",
+        "Blonde",
+        "BlondeGolden",
+        "Brown",
+        "BrownDark",
+        "Platinum",
+        "Red",
+        "SilverGray",
+    ],
+    clotheType: [
+        "BlazerShirt",
+        "BlazerSweater",
+        "CollarSweater",
+        "GraphicShirt",
+        "Hoodie",
+        "Overall",
+        "ShirtCrewNeck",
+        "ShirtScoopNeck",
+        "ShirtVNeck",
+    ],
+    clotheColor: FABRIC_COLORS,
+    graphicType: [
+        "Bat",
+        "Bear",
+        "Cumbia",
+        "Deer",
+        "Diamond",
+        "Hola",
+        "Pizza",
+        "Resist",
+        "Selena",
+        "Skull",
+        "SkullOutline",
+    ],
+    eyeType: [
+        "Close",
+        "Cry",
+        "Default",
+        "Dizzy",
+        "EyeRoll",
+        "Happy",
+        "Hearts",
+        "Side",
+        "Squint",
+        "Surprised",
+        "Wink",
+        "WinkWacky",
+    ],
+    eyebrowType: [
+        "Angry",
+        "AngryNatural",
+        "Default",
+        "DefaultNatural",
+        "FlatNatural",
+        "FrownNatural",
+        "RaisedExcited",
+        "RaisedExcitedNatural",
+        "SadConcerned",
+        "SadConcernedNatural",
+        "UnibrowNatural",
+        "UpDown",
+        "UpDownNatural",
+    ],
+    mouthType: [
+        "Concerned",
+        "Default",
+        "Disbelief",
+        "Eating",
+        "Grimace",
+        "Sad",
+        "ScreamOpen",
+        "Serious",
+        "Smile",
+        "Tongue",
+        "Twinkle",
+        "Vomit",
+    ],
+    skinColor: ["Tanned", "Yellow", "Pale", "Light", "Brown", "DarkBrown", "Black"],
+};
+/** The avatar used while `core.assistantAvatar` is unset. */
+export const DEFAULT_AVATAR = {
+    topType: "LongHairStraight2",
+    accessoriesType: "Blank",
+    hairColor: "Auburn",
+    hatColor: "Blue02",
+    facialHairType: "Blank",
+    facialHairColor: "Black",
+    clotheType: "BlazerSweater",
+    clotheColor: "Pink",
+    graphicType: "Cumbia",
+    eyeType: "Squint",
+    eyebrowType: "Default",
+    mouthType: "Default",
+    skinColor: "Light",
+    backgroundColor: "#65c9ff",
+};
+/** Tops drawn with the hair color. */
+const TOPS_WITH_HAIR_COLOR = new Set([
+    "LongHairBigHair",
+    "LongHairBob",
+    "LongHairBun",
+    "LongHairCurly",
+    "LongHairCurvy",
+    "LongHairDreads",
+    "LongHairFro",
+    "LongHairFroBand",
+    "LongHairNotTooLong",
+    "LongHairMiaWallace",
+    "LongHairStraight",
+    "LongHairStraight2",
+    "LongHairStraightStrand",
+    "ShortHairDreads01",
+    "ShortHairDreads02",
+    "ShortHairFrizzle",
+    "ShortHairShaggyMullet",
+    "ShortHairShortCurly",
+    "ShortHairShortFlat",
+    "ShortHairShortRound",
+    "ShortHairShortWaved",
+    "ShortHairSides",
+    "ShortHairTheCaesar",
+    "ShortHairTheCaesarSidePart",
+]);
+/** Tops drawn with the hat color. */
+const TOPS_WITH_HAT_COLOR = new Set([
+    "Hijab",
+    "Turban",
+    "WinterHat1",
+    "WinterHat2",
+    "WinterHat3",
+    "WinterHat4",
+]);
+/** Clothes drawn with the fabric color. */
+const CLOTHES_WITH_COLOR = new Set([
+    "CollarSweater",
+    "GraphicShirt",
+    "Hoodie",
+    "Overall",
+    "ShirtCrewNeck",
+    "ShirtScoopNeck",
+    "ShirtVNeck",
+]);
+/** `#rrggbb`. */
+const HEX_COLOR_PATTERN = /^#[0-9a-fA-F]{6}$/;
+/**
+ * Whether an option has a visible effect for the rest of the avatar,
+ * e.g. the hat color only matters for a hat. Editors hide the others.
+ *
+ * @param field The option.
+ * @param config The avatar.
+ * @returns `true` when changing the option changes the picture.
+ */
+export function isAvatarOptionRelevant(field, config) {
+    switch (field) {
+        case "hairColor":
+            return TOPS_WITH_HAIR_COLOR.has(config.topType);
+        case "hatColor":
+            return TOPS_WITH_HAT_COLOR.has(config.topType);
+        case "facialHairColor":
+            return config.facialHairType !== "Blank";
+        case "clotheColor":
+            return CLOTHES_WITH_COLOR.has(config.clotheType);
+        case "graphicType":
+            return config.clotheType === "GraphicShirt";
+        default:
+            return true;
+    }
+}
+/**
+ * Whether `value` is an allowed value of `field`.
+ *
+ * @param field The option.
+ * @param value Candidate value.
+ * @returns `true` for an allowed value.
+ */
+function isAllowedValue(field, value) {
+    return AVATAR_OPTION_VALUES[field].includes(value);
+}
+/**
+ * List what is wrong with a stored avatar: not a mapping, unknown
+ * options, values outside the allowed set, a malformed background color.
+ * Missing options are fine (they fall back to {@link DEFAULT_AVATAR}).
+ *
+ * @param value Raw value of `core.assistantAvatar`.
+ * @returns Human-readable problems, empty when the value is usable as is.
+ */
+export function findAvatarConfigProblems(value) {
+    if (value === undefined || value === null) {
+        return [];
+    }
+    if (typeof value !== "object" || Array.isArray(value)) {
+        return ["must be a mapping of avatar options"];
+    }
+    const problems = [];
+    for (const [key, entry] of Object.entries(value)) {
+        if (key === "backgroundColor") {
+            if (typeof entry !== "string" || !HEX_COLOR_PATTERN.test(entry)) {
+                problems.push(`backgroundColor must be a #rrggbb color (got ${String(entry)})`);
+            }
+            continue;
+        }
+        if (!(key in AVATAR_OPTION_VALUES)) {
+            problems.push(`unknown option ${key}`);
+            continue;
+        }
+        const field = key;
+        if (!isAllowedValue(field, entry)) {
+            problems.push(`${key} must be one of ${AVATAR_OPTION_VALUES[field].join(", ")} (got ${String(entry)})`);
+        }
+    }
+    return problems;
+}
+/**
+ * Turn a stored avatar into a complete one: every missing or invalid
+ * option takes its {@link DEFAULT_AVATAR} value. Never throws, so a
+ * hand-edited config cannot break rendering.
+ *
+ * @param value Raw value of `core.assistantAvatar`.
+ * @returns A complete avatar.
+ */
+export function normalizeAvatarConfig(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return DEFAULT_AVATAR;
+    }
+    const raw = value;
+    const result = { ...DEFAULT_AVATAR };
+    for (const field of Object.keys(AVATAR_OPTION_VALUES)) {
+        if (isAllowedValue(field, raw[field])) {
+            result[field] = raw[field];
+        }
+    }
+    const background = raw.backgroundColor;
+    if (typeof background === "string" && HEX_COLOR_PATTERN.test(background)) {
+        result.backgroundColor = background.toLowerCase();
+    }
+    return result;
+}

package/build/BannerBus.d.ts

@@ -0,0 +1,100 @@
+import type { PostgresConnection } from "./PostgresConnection.js";
+/** Longest banner text accepted, in characters. Keeps every prompt bounded. */
+export declare const BANNER_MAX_TEXT_CHARS = 500;
+/** Most banners that may be active at the same time. */
+export declare const BANNER_MAX_ACTIVE = 20;
+/**
+ * Longest lifetime of a banner, in days. Anything that stays true longer
+ * belongs into the long-term memory (wiki), not into every prompt.
+ */
+export declare const BANNER_MAX_LIFETIME_DAYS = 30;
+/** One persisted banner. */
+export interface BannerRow {
+    /** Numeric id as string (`bigserial`, as `pg` returns it). */
+    readonly id: string;
+    /** The note itself. */
+    readonly text: string;
+    /** UTC ISO-8601 instant at which the banner disappears. */
+    readonly expiresAt: string;
+    /** UTC ISO-8601 creation instant. */
+    readonly createdAt: string;
+    /** Agentrun that created the banner, or `null` (CLI, deleted run). */
+    readonly createdByAgentrunId: string | null;
+    /** Topic of the creating agentrun, or `null`. */
+    readonly createdByTopic: string | null;
+}
+/** Input to {@link BannerBus.create}. */
+export interface NewBanner {
+    readonly text: string;
+    /** UTC ISO-8601 expiry instant. */
+    readonly expiresAt: string;
+    readonly createdByAgentrunId?: string | null;
+    readonly createdByTopic?: string | null;
+}
+/**
+ * Domain client for the `banners` table — short-lived notes the agent
+ * leaves for every later agentrun. Used by the container (the
+ * `banner_*` tools and the `{BANNER_LIST}` prompt placeholder) and by the
+ * host CLI (`familiar banners`).
+ *
+ * Expiry is enforced on read: every listing deletes expired rows first,
+ * so a banner "disappears" without a dedicated sweep job. All times are
+ * stored and returned as UTC; agent-facing surfaces project them into
+ * `core.timezone` (see {@link formatBannerList}).
+ */
+export declare class BannerBus {
+    private readonly connection;
+    constructor(connection: PostgresConnection);
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle every
+     * other bus client installs.
+     */
+    installSchema(): Promise<void>;
+    /**
+     * Insert a banner. Validation (length, lifetime, active count) is the
+     * caller's job — see the `banner_create` tool.
+     *
+     * @param banner The banner to persist.
+     * @returns The persisted row.
+     */
+    create(banner: NewBanner): Promise<BannerRow>;
+    /**
+     * Delete banners by id.
+     *
+     * @param ids Banner ids (numeric strings).
+     * @returns The ids that existed and were deleted.
+     */
+    remove(ids: readonly string[]): Promise<string[]>;
+    /**
+     * List every banner that has not expired yet, oldest first. Deletes
+     * expired banners before reading.
+     *
+     * @returns The active banners.
+     */
+    listActive(): Promise<BannerRow[]>;
+    /**
+     * Delete every banner whose expiry has passed.
+     *
+     * @returns Number of deleted rows.
+     */
+    purgeExpired(): Promise<number>;
+}
+/**
+ * Render a UTC instant as compact local wall-clock `YYYY-MM-DD HH:mm`.
+ * Falls back to the input on an unparsable instant or unknown zone.
+ *
+ * @param utcIso UTC ISO-8601 instant.
+ * @param zone IANA zone (typically `core.timezone`).
+ * @returns The local wall-clock string.
+ */
+export declare function formatBannerTime(utcIso: string, zone: string): string;
+/**
+ * Render banners as the markdown bullet list the prompt shows, one
+ * `* [ID:<id>] <created> (until <expires>): <text>` line each. Newlines
+ * inside a banner text are collapsed so one banner stays one bullet.
+ *
+ * @param banners Active banners, in display order.
+ * @param zone IANA zone the times are shown in.
+ * @returns The list, or `(none)` when there are no banners.
+ */
+export declare function formatBannerList(banners: readonly BannerRow[], zone: string): string;

package/build/BannerBus.js

@@ -0,0 +1,133 @@
+import { DateTime } from "luxon";
+import { SCHEMA_SQL } from "./Schema.js";
+/** Longest banner text accepted, in characters. Keeps every prompt bounded. */
+export const BANNER_MAX_TEXT_CHARS = 500;
+/** Most banners that may be active at the same time. */
+export const BANNER_MAX_ACTIVE = 20;
+/**
+ * Longest lifetime of a banner, in days. Anything that stays true longer
+ * belongs into the long-term memory (wiki), not into every prompt.
+ */
+export const BANNER_MAX_LIFETIME_DAYS = 30;
+/**
+ * Domain client for the `banners` table — short-lived notes the agent
+ * leaves for every later agentrun. Used by the container (the
+ * `banner_*` tools and the `{BANNER_LIST}` prompt placeholder) and by the
+ * host CLI (`familiar banners`).
+ *
+ * Expiry is enforced on read: every listing deletes expired rows first,
+ * so a banner "disappears" without a dedicated sweep job. All times are
+ * stored and returned as UTC; agent-facing surfaces project them into
+ * `core.timezone` (see {@link formatBannerList}).
+ */
+export class BannerBus {
+    connection;
+    constructor(connection) {
+        this.connection = connection;
+    }
+    /**
+     * Apply the bus-state schema (idempotent). Same SQL bundle every
+     * other bus client installs.
+     */
+    async installSchema() {
+        await this.connection.getPool().query(SCHEMA_SQL);
+    }
+    /**
+     * Insert a banner. Validation (length, lifetime, active count) is the
+     * caller's job — see the `banner_create` tool.
+     *
+     * @param banner The banner to persist.
+     * @returns The persisted row.
+     */
+    async create(banner) {
+        await this.purgeExpired();
+        const result = await this.connection.getPool().query(`INSERT INTO banners (text, expires_at, created_by_agentrun_id, created_by_topic)
+             VALUES ($1, $2, $3, $4)
+             RETURNING *`, [
+            banner.text,
+            banner.expiresAt,
+            banner.createdByAgentrunId ?? null,
+            banner.createdByTopic ?? null,
+        ]);
+        return mapRow(result.rows[0]);
+    }
+    /**
+     * Delete banners by id.
+     *
+     * @param ids Banner ids (numeric strings).
+     * @returns The ids that existed and were deleted.
+     */
+    async remove(ids) {
+        if (ids.length === 0) {
+            return [];
+        }
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM banners WHERE id = ANY($1::bigint[]) RETURNING id`, [ids]);
+        return result.rows.map((row) => row.id);
+    }
+    /**
+     * List every banner that has not expired yet, oldest first. Deletes
+     * expired banners before reading.
+     *
+     * @returns The active banners.
+     */
+    async listActive() {
+        await this.purgeExpired();
+        const result = await this.connection
+            .getPool()
+            .query(`SELECT * FROM banners WHERE expires_at > now() ORDER BY created_at ASC, id ASC`);
+        return result.rows.map(mapRow);
+    }
+    /**
+     * Delete every banner whose expiry has passed.
+     *
+     * @returns Number of deleted rows.
+     */
+    async purgeExpired() {
+        const result = await this.connection
+            .getPool()
+            .query(`DELETE FROM banners WHERE expires_at <= now()`);
+        return result.rowCount ?? 0;
+    }
+}
+/** Convert a snake_case raw row into the camelCase domain shape. */
+function mapRow(raw) {
+    return {
+        id: String(raw.id),
+        text: raw.text,
+        expiresAt: raw.expires_at.toISOString(),
+        createdAt: raw.created_at.toISOString(),
+        createdByAgentrunId: raw.created_by_agentrun_id === null ? null : String(raw.created_by_agentrun_id),
+        createdByTopic: raw.created_by_topic,
+    };
+}
+/**
+ * Render a UTC instant as compact local wall-clock `YYYY-MM-DD HH:mm`.
+ * Falls back to the input on an unparsable instant or unknown zone.
+ *
+ * @param utcIso UTC ISO-8601 instant.
+ * @param zone IANA zone (typically `core.timezone`).
+ * @returns The local wall-clock string.
+ */
+export function formatBannerTime(utcIso, zone) {
+    const local = DateTime.fromISO(utcIso, { zone: "utc" }).setZone(zone);
+    return local.isValid ? local.toFormat("yyyy-MM-dd HH:mm") : utcIso;
+}
+/**
+ * Render banners as the markdown bullet list the prompt shows, one
+ * `* [ID:<id>] <created> (until <expires>): <text>` line each. Newlines
+ * inside a banner text are collapsed so one banner stays one bullet.
+ *
+ * @param banners Active banners, in display order.
+ * @param zone IANA zone the times are shown in.
+ * @returns The list, or `(none)` when there are no banners.
+ */
+export function formatBannerList(banners, zone) {
+    if (banners.length === 0) {
+        return "(none)";
+    }
+    return banners
+        .map((banner) => `* [ID:${banner.id}] ${formatBannerTime(banner.createdAt, zone)} (until ${formatBannerTime(banner.expiresAt, zone)}): ${banner.text.replace(/\s*\n\s*/g, " ").trim()}`)
+        .join("\n");
+}

package/build/Config.d.ts

@@ -24,6 +24,18 @@
  * the workspace globs the agent may write to, which are never handlers.
  */
 export declare const DEFAULT_WRITABLE_PATHS: readonly string[];
+/** Config key of the assistant's name (web UI branding, `{ASSISTANT_NAME}`). */
+export declare const ASSISTANT_NAME_CONFIG_KEY = "core.assistantName";
+/** Assistant name when `core.assistantName` is unset or empty. */
+export declare const DEFAULT_ASSISTANT_NAME = "Familiar";
+/**
+ * Resolve the assistant's name from a raw config value: a non-blank
+ * string (trimmed), otherwise {@link DEFAULT_ASSISTANT_NAME}.
+ *
+ * @param value Raw value of `core.assistantName`, or undefined.
+ * @returns The name to show and to render into prompts.
+ */
+export declare function resolveAssistantName(value: unknown): string;
 export interface ConfigService {
     /**
      * Read a string under a dotted path. Throws when the key is
@@ -85,4 +97,11 @@ export interface ConfigService {
      *   atomic write fails.
      */
     set(key: string, value: unknown): Promise<void>;
+    /**
+     * Read the raw value under a dotted path, without shape checks — for
+     * structured values (mappings) whose reader validates them itself.
+     *
+     * @returns The raw value, or `undefined` when absent.
+     */
+    getValue(key: string): unknown;
 }

package/build/Config.js

@@ -24,3 +24,21 @@
  * the workspace globs the agent may write to, which are never handlers.
  */
 export const DEFAULT_WRITABLE_PATHS = ["wiki/**", "files/**"];
+/** Config key of the assistant's name (web UI branding, `{ASSISTANT_NAME}`). */
+export const ASSISTANT_NAME_CONFIG_KEY = "core.assistantName";
+/** Assistant name when `core.assistantName` is unset or empty. */
+export const DEFAULT_ASSISTANT_NAME = "Familiar";
+/**
+ * Resolve the assistant's name from a raw config value: a non-blank
+ * string (trimmed), otherwise {@link DEFAULT_ASSISTANT_NAME}.
+ *
+ * @param value Raw value of `core.assistantName`, or undefined.
+ * @returns The name to show and to render into prompts.
+ */
+export function resolveAssistantName(value) {
+    if (typeof value !== "string") {
+        return DEFAULT_ASSISTANT_NAME;
+    }
+    const trimmed = value.trim();
+    return trimmed === "" ? DEFAULT_ASSISTANT_NAME : trimmed;
+}

package/build/Plugin.d.ts

@@ -1,6 +1,8 @@
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import type { CommandDef } from "citty";
 import type { AgentRunRow } from "./AgentRun.js";
+import type { AvatarConfig } from "./AssistantAvatar.js";
+import type { BannerRow } from "./BannerBus.js";
 import type { CalendarApi } from "./Calendar.js";
 import type { ChatFilter, ChatHistoryQuery, ChatMessage } from "./ChatMessage.js";
 import type { ChatHandler, ChatUnsubscribe } from "./ChatMessageBus.js";
@@ -258,6 +260,21 @@ export interface HostContext {
          */
         listMessages(query: ChatHistoryQuery): Promise<readonly ChatMessage[]>;
     };
+    /**
+     * Read access to the banners — the short-lived notes every agentrun
+     * sees through `{BANNER_LIST}`. Read-only on purpose: banners are the
+     * agent's notes, created through its `banner_create` tool. For
+     * plugins that build prompts of their own (e.g. the voice model's
+     * instructions) and should show the same notes.
+     */
+    readonly banners: {
+        /**
+         * The banners that have not expired, oldest first (expired ones
+         * are deleted on the way). Times are UTC; render them with
+         * `formatBannerList(banners, timezone)`.
+         */
+        listActive(): Promise<readonly BannerRow[]>;
+    };
     /**
      * Per-event scratch directory operations. Each event the bus
      * persists has a private scratch dir at `/scratch/<event-id>/`
@@ -319,6 +336,17 @@ export interface HostContext {
     readonly isDevMode: boolean;
     /** Version of the running familiar host (the `@getfamiliar/host` package version, e.g. `0.4.2`). */
     readonly familiarVersion: string;
+    /**
+     * The assistant's name (`core.assistantName`, default `Familiar`),
+     * read on every access so it follows `familiar config reload`. Use it
+     * wherever the assistant names itself to the user (UI branding, voice).
+     */
+    readonly assistantName: string;
+    /**
+     * The assistant's avatar (`core.assistantAvatar`, completed with
+     * defaults), read on every access. Render it with `@getfamiliar/avatar`.
+     */
+    readonly assistantAvatar: AvatarConfig;
     /**
      * Absolute host path of the project's `data/` directory.
      *
@@ -882,14 +910,24 @@ export interface PluginManifest {
     /** Host-side surface (CLI commands, daemons, cronjobs, tools). */
     readonly host?: PluginHostManifest;
     /**
-     * Absolute path to a directory of files copied into
-     * the workspace (`<home>/workspace/`) on first install. Existing files are left
-     * alone — diff/merge on plugin updates is a separate concern.
-     * Plugins typically derive this with
-     * `path.join(__dirname, "..", "workspace-template")` (or the ESM
-     * `import.meta.url` equivalent).
+     * Absolute path to a directory of default workspace files (handlers,
+     * skills). Missing files are seeded into `<home>/workspace/`; later
+     * template changes reach the workspace through the workspace updater
+     * (fast-forward when the user never edited the file, otherwise the
+     * `update:merge-file` agent run). Plugins typically derive this with
+     * `path.join(import.meta.dirname, "..", "workspace-template")`.
      */
     readonly workspaceTemplate?: string;
+    /**
+     * Absolute path to a directory of update notes (`YYYY-MM-DD-<slug>.md`):
+     * one-off instructions for changes a template diff cannot express —
+     * renamed placeholders, moved files, conventions that affect files the
+     * user created. Each note is applied once by an `update:apply-note`
+     * agent run and then recorded as done; a fresh install marks every
+     * existing note done. Conventionally
+     * `path.join(import.meta.dirname, "..", "workspace-updates")`.
+     */
+    readonly workspaceUpdates?: string;
 }
 /**
  * Identity function used by plugins to declare their manifest:

package/build/PromptPlaceholders.js

@@ -43,6 +43,11 @@ export const CORE_PROMPT_PLACEHOLDERS = [
         description: "Workspace-relative path of the handler file, e.g. `chat/telegram.md`.",
         kind: "static",
     },
+    {
+        name: "ASSISTANT_NAME",
+        description: "The assistant's name from `core.assistantName` (default `Familiar`).",
+        kind: "static",
+    },
     {
         name: "SKILL_LIST",
         description: "Bullet list of the skills in `skills/` (id and description).",
@@ -83,6 +88,11 @@ export const CORE_PROMPT_PLACEHOLDERS = [
         description: "`yes` when the run stems from the system owner, otherwise `no`.",
         kind: "dynamic",
     },
+    {
+        name: "BANNER_LIST",
+        description: "Bullet list of active banners (short-lived notes runs left via `banner_create`), one `* [ID:<id>] <created> (until <expires>): <text>` line each.",
+        kind: "dynamic",
+    },
     {
         name: "STAGED_FILE_LIST",
         description: "Bullet list of files staged in this event's `/scratch/<event-id>/` folder.",

package/build/RuntimeTime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Format a `Date` for the runtime facts:
+ * `Friday, 2026-05-19T18:43:12 in timezone Europe/Berlin`.
+ *
+ * Weekday name + ISO-like local time + the IANA tz label, all relative
+ * to `timezone`. Built from `Intl.DateTimeFormat.formatToParts` so we
+ * control the separators directly — the locale-default formatter
+ * inserts AM/PM and locale punctuation we don't want.
+ *
+ * @param date The instant to format.
+ * @param timezone IANA timezone.
+ * @returns The formatted string.
+ */
+export declare function formatRuntimeTime(date: Date, timezone: string): string;

package/build/RuntimeTime.js

@@ -0,0 +1,38 @@
+/**
+ * Format a `Date` for the runtime facts:
+ * `Friday, 2026-05-19T18:43:12 in timezone Europe/Berlin`.
+ *
+ * Weekday name + ISO-like local time + the IANA tz label, all relative
+ * to `timezone`. Built from `Intl.DateTimeFormat.formatToParts` so we
+ * control the separators directly — the locale-default formatter
+ * inserts AM/PM and locale punctuation we don't want.
+ *
+ * @param date The instant to format.
+ * @param timezone IANA timezone.
+ * @returns The formatted string.
+ */
+export function formatRuntimeTime(date, timezone) {
+    const parts = new Intl.DateTimeFormat("en-US", {
+        timeZone: timezone,
+        weekday: "long",
+        year: "numeric",
+        month: "2-digit",
+        day: "2-digit",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        hour12: false,
+    }).formatToParts(date);
+    const lookup = new Map(parts.map((p) => [p.type, p.value]));
+    const weekday = lookup.get("weekday") ?? "";
+    const year = lookup.get("year") ?? "";
+    const month = lookup.get("month") ?? "";
+    const day = lookup.get("day") ?? "";
+    // `hour: '2-digit'` with `hour12: false` can yield "24" at midnight
+    // on some implementations; normalise to "00".
+    const rawHour = lookup.get("hour") ?? "";
+    const hour = rawHour === "24" ? "00" : rawHour;
+    const minute = lookup.get("minute") ?? "";
+    const second = lookup.get("second") ?? "";
+    return `${weekday}, ${year}-${month}-${day}T${hour}:${minute}:${second} in timezone ${timezone}`;
+}

package/build/Schema.d.ts

@@ -62,7 +62,7 @@ export declare const SCHEDULED_SUBAGENTS_CHANNEL = "scheduled_subagents_changed"
  * match exactly (see `HandlerResolution.ts`).
  */
 export declare const TOPIC_PATTERN = "^[\\w-]+(:[\\w-]+)*$";
-export declare const SCHEMA_SQL = "\n-- Drop legacy single-table artifacts from before the events/agentruns\n-- split. Safe no-ops on fresh databases. The current schema reuses the\n-- name events_notify_new() for its own NOTIFY function, so we do NOT\n-- drop it here (CREATE OR REPLACE FUNCTION below handles the update);\n-- dropping would fail anyway once the current events_new_trg exists.\nDROP TRIGGER IF EXISTS events_notify_changed_trg ON events;\nDROP TRIGGER IF EXISTS events_notify_new_trg ON events;\nDROP FUNCTION IF EXISTS events_notify_changed();\nDROP INDEX IF EXISTS events_pending_priority_idx;\nDROP INDEX IF EXISTS events_state_priority_idx;\n\nCREATE TABLE IF NOT EXISTS events (\n  id              bigserial PRIMARY KEY,\n  topic           text NOT NULL,\n  priority        smallint NOT NULL DEFAULT 50,\n  state           text NOT NULL DEFAULT 'pending',\n  payload         jsonb NOT NULL DEFAULT '{}'::jsonb,\n  idempotency_key text UNIQUE,\n  privileged      boolean NOT NULL DEFAULT false,\n  created_at      timestamptz NOT NULL DEFAULT now(),\n  updated_at      timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT events_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$')\n);\n\n-- Drop legacy columns from earlier schema generations. Single-instance\n-- project; column drops are fine.\nALTER TABLE events DROP COLUMN IF EXISTS supervisor_prompt;\nALTER TABLE events DROP COLUMN IF EXISTS causation_chain;\n\n-- Chat-aware event metadata. `is_chat` opts into automatic user-message\n-- persistence in EventBus.add; `preferred_chat_channel_id` names the\n-- channel an assistant reply should reach the user on. The container is\n-- channel-blind \u2014 both fields are read host-side (for routing) or via\n-- JOIN inside the chatmessages NOTIFY trigger.\nALTER TABLE events ADD COLUMN IF NOT EXISTS is_chat boolean NOT NULL DEFAULT false;\nALTER TABLE events ADD COLUMN IF NOT EXISTS preferred_chat_channel_id text;\n-- Required for non-chat events (validated at `EventBus.add` time and at\n-- the type level via `NewEvent`'s discriminated union); always null for\n-- chat events because the user's text in `chatmessages` already serves\n-- as the agent-visible \"what happened\" message. The EventWatcher copies\n-- this verbatim into the root `agentruns.prompt` so the agent sees the\n-- emitter's framing without the EventWatcher having to reach into the\n-- payload schema.\nALTER TABLE events ADD COLUMN IF NOT EXISTS prompt text;\n-- The topic is the handler's whole address now; the separate start\n-- handler basename is gone.\nALTER TABLE events DROP COLUMN IF EXISTS start_handler;\n-- When true the topic must name an existing handler file exactly; when\n-- false (world events) handler resolution falls back up the topic chain.\n-- Copied onto the root agentrun by the input-event watcher.\nALTER TABLE events ADD COLUMN IF NOT EXISTS is_exact_topic boolean NOT NULL DEFAULT false;\n-- Privileged events originate from a trusted user-input source (operator\n-- at the local terminal via cli-chat, operator on Telegram). The flag\n-- propagates verbatim to the root agentrun and to every child agentrun\n-- spawned via schedule_subagent / start_subagent, so future system tools can\n-- gate risky reads / writes (editing SOUL.md etc.) on whether the run\n-- descends from a trusted input. Default false: any plugin that doesn't\n-- explicitly opt in produces non-privileged events.\nALTER TABLE events ADD COLUMN IF NOT EXISTS privileged boolean NOT NULL DEFAULT false;\n-- When true and the event ends in 'failed', `HostContextImpl.emitAndAwait`\n-- writes a role='assistant' chatmessage with the failure text before\n-- rejecting handle.settled. Default false: only chat plugins (cli-chat,\n-- telegram) opt in. See [[outputChatOnFailure]] on NewEvent for the\n-- rationale.\nALTER TABLE events ADD COLUMN IF NOT EXISTS output_chat_on_failure boolean NOT NULL DEFAULT false;\n\nCREATE INDEX IF NOT EXISTS events_state_priority_idx\n  ON events (state, priority DESC, id ASC);\nCREATE INDEX IF NOT EXISTS events_topic_idx ON events (topic);\n\nCREATE TABLE IF NOT EXISTS agentruns (\n  id                 bigserial PRIMARY KEY,\n  event_id           bigint NOT NULL REFERENCES events(id) ON DELETE CASCADE,\n  parent_agentrun_id bigint REFERENCES agentruns(id) ON DELETE CASCADE,\n  topic              text NOT NULL,\n  priority           smallint NOT NULL DEFAULT 50,\n  state              text NOT NULL DEFAULT 'pending',\n  prompt             text,\n  payload            jsonb NOT NULL DEFAULT '{}'::jsonb,\n  result             jsonb,\n  result_text        text,\n  error              text,\n  privileged         boolean NOT NULL DEFAULT false,\n  created_at         timestamptz NOT NULL DEFAULT now(),\n  updated_at         timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT agentruns_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$')\n);\n\n-- Forward-compat ALTER for databases created before result_text landed.\n-- Safe no-op on fresh databases where the column already exists.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS result_text text;\n-- The topic is the handler's whole address; the basename column is gone.\nALTER TABLE agentruns DROP COLUMN IF EXISTS handler;\n-- Whether handler resolution must match the topic exactly. Root\n-- agentruns copy the event's flag; spawned children are always exact.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS is_exact_topic boolean NOT NULL DEFAULT true;\n-- Inherited from the originating event (root agentrun) or parent\n-- agentrun (children spawned via schedule_subagent / start_subagent). See\n-- the matching ALTER on the events table for the trust-model rationale.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS privileged boolean NOT NULL DEFAULT false;\n-- Number of retry attempts already made on this agentrun. Bumped each\n-- time AgentRunner postpones the row due to a retryable inference\n-- error (APICallError.isRetryable). Capped per-handler via maxRetries\n-- (frontmatter override) or globally via inference.maxRetries.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS retry_count int NOT NULL DEFAULT 0;\n-- Earliest moment the agentrun watcher is allowed to re-claim this\n-- row. NULL = claim immediately (default for fresh rows). A future\n-- timestamp = leave the row alone until then; the watcher's claim\n-- query gates on this so a parked row doesn't waste the slot while\n-- other agentruns (potentially using different models) can still run.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS not_before timestamptz;\n-- Resolved model id for this agentrun, of the form\n-- `<provider>/<modelId>` (e.g. `featherless/zai-org/GLM-5.1`).\n-- Populated by AgentRunner once it builds the model client; stays\n-- NULL for any agentrun that never reached generate() (failed at\n-- handler-load time, etc.).\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS model text;\n-- Resolved prompt (rendered prompt template: system prompt, then\n-- user-message head) used for this agentrun. Populated by AgentRunner\n-- only when core.logSystemPrompt is true; otherwise NULL. Surfaced\n-- by the report layer's Agentrun Start section when the consumer\n-- opts into withDetails.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS system_prompt text;\n-- Verbatim model-message array assembled for the first agent.generate()\n-- call (prior history + the run's leading user turn). Populated by\n-- AgentRunner only when inference.captureInitialMessageHistory is true;\n-- otherwise NULL. Surfaced by the report layer's -vv view so an operator\n-- can see exactly what was sent into the model loop.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS initial_messages jsonb;\n\n-- Distinguishes how a child agentrun was spawned.\n--   NULL        \u2014 root agentrun (created by the input-event watcher, no parent).\n--   'scheduled' \u2014 fire-and-forget child spawned by `schedule_subagent` without\n--                 a future `when` (immediate dispatch under the same event).\n--   'started'   \u2014 synchronous child spawned via the `start_subagent` tool; the\n--                 parent is parked in state='waiting' until this row settles.\n-- The Scheduler reads this column to decide whether settling a row should\n-- wake a waiting parent.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS calltype text;\nALTER TABLE agentruns DROP CONSTRAINT IF EXISTS agentruns_calltype_format;\nALTER TABLE agentruns ADD CONSTRAINT agentruns_calltype_format\n  CHECK (calltype IS NULL OR calltype IN ('scheduled','started'));\n\n-- Partial index for the \"are all started children of $parent settled?\"\n-- check the Scheduler runs after every 'started' child settles. Indexes\n-- only the rows that actually participate in the question.\nCREATE INDEX IF NOT EXISTS agentruns_parent_calltype_state_idx\n  ON agentruns (parent_agentrun_id, state)\n  WHERE calltype = 'started';\n\n-- Forward-compat: relax the topic CHECK constraint to allow arbitrarily\n-- deep `a:b:c:\u2026` topics. CREATE TABLE IF NOT EXISTS above doesn't\n-- update existing constraints, so we drop+re-add unconditionally. The\n-- DROP IF EXISTS / ADD pair is idempotent.\nALTER TABLE events DROP CONSTRAINT IF EXISTS events_topic_format;\nALTER TABLE events ADD CONSTRAINT events_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$');\nALTER TABLE agentruns DROP CONSTRAINT IF EXISTS agentruns_topic_format;\nALTER TABLE agentruns ADD CONSTRAINT agentruns_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$');\n\nCREATE INDEX IF NOT EXISTS agentruns_state_priority_idx\n  ON agentruns (state, priority DESC, id ASC);\nCREATE INDEX IF NOT EXISTS agentruns_event_id_idx ON agentruns (event_id);\nCREATE INDEX IF NOT EXISTS agentruns_parent_idx ON agentruns (parent_agentrun_id);\n\nCREATE TABLE IF NOT EXISTS stepresults (\n  id              bigserial PRIMARY KEY,\n  agent_run_id    bigint NOT NULL REFERENCES agentruns(id) ON DELETE CASCADE,\n  event_id        bigint NOT NULL REFERENCES events(id) ON DELETE CASCADE,\n  step_number     int    NOT NULL,\n  finish_reason   text   NOT NULL,\n  result_text     text,\n  reasoning_text  text,\n  input_tokens    int,\n  output_tokens   int,\n  total_tokens    int,\n  tool_call_count int    NOT NULL DEFAULT 0,\n  tool_calls      jsonb  NOT NULL DEFAULT '[]'::jsonb,\n  tool_results    jsonb  NOT NULL DEFAULT '[]'::jsonb,\n  created_at      timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT stepresults_step_number_unique UNIQUE (agent_run_id, step_number)\n);\n\nCREATE INDEX IF NOT EXISTS stepresults_agent_run_id_idx ON stepresults (agent_run_id);\nCREATE INDEX IF NOT EXISTS stepresults_event_id_idx     ON stepresults (event_id);\n\n-- AI SDK per-step usage breakdown\n-- (LanguageModelUsage.inputTokenDetails / outputTokenDetails). Each\n-- column is NULL when the provider doesn't report that detail.\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS input_tokens_no_cache    int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS input_tokens_cache_read  int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS input_tokens_cache_write int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS output_tokens_text       int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS output_tokens_reasoning  int;\n-- Full step object snapshot, populated only when the operator opts\n-- in via inference.captureRawStepResultToDatabase: true. Used to\n-- inspect provider-specific fields (Anthropic cache control,\n-- OpenAI logprobs, ...) that don't fit dedicated columns.\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS raw_result jsonb;\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 chatmessages \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Persistent chat history across all channels. Each row links to the\n-- event whose lifecycle the message belongs to:\n--   * For role='user': the event the host plugin emitted with isChat=true.\n--   * For role='assistant': the event whose agentrun called send_chat.\n-- The channel is reachable via JOIN to events.preferred_chat_channel_id;\n-- there is intentionally no channel_id column here \u2014 channel routing is\n-- a host-side concern, the container never names a channel.\n--\n-- delivered_at is set when ANY listener returns true from its async\n-- handler. New subscribers replay all undelivered matching rows on\n-- registration so a message produced when nobody was listening is still\n-- delivered later.\nCREATE TABLE IF NOT EXISTS chatmessages (\n  id           bigserial PRIMARY KEY,\n  event_id     bigint NOT NULL REFERENCES events(id) ON DELETE CASCADE,\n  role         text NOT NULL CHECK (role IN ('user','assistant')),\n  text_content text NOT NULL,\n  created_at   timestamptz NOT NULL DEFAULT now(),\n  delivered_at timestamptz\n);\n\nCREATE INDEX IF NOT EXISTS chatmessages_event_idx\n  ON chatmessages (event_id);\nCREATE INDEX IF NOT EXISTS chatmessages_undelivered_idx\n  ON chatmessages (created_at) WHERE delivered_at IS NULL;\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 NOTIFY triggers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nCREATE OR REPLACE FUNCTION events_notify_new() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify('events_new', NEW.id::text);\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS events_new_trg ON events;\nCREATE TRIGGER events_new_trg\n  AFTER INSERT ON events\n  FOR EACH ROW EXECUTE FUNCTION events_notify_new();\n\nCREATE OR REPLACE FUNCTION events_notify_state() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify('events_state', NEW.id::text || ':' || NEW.state);\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS events_state_trg ON events;\nCREATE TRIGGER events_state_trg\n  AFTER UPDATE OF state ON events\n  FOR EACH ROW EXECUTE FUNCTION events_notify_state();\n\nCREATE OR REPLACE FUNCTION agentruns_notify_changed() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify(\n    'agentruns_changed',\n    NEW.event_id::text || ':' || NEW.id::text\n  );\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS agentruns_notify_changed_trg ON agentruns;\nCREATE TRIGGER agentruns_notify_changed_trg\n  AFTER INSERT OR UPDATE OF state ON agentruns\n  FOR EACH ROW EXECUTE FUNCTION agentruns_notify_changed();\n\nCREATE OR REPLACE FUNCTION stepresults_notify_new() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify(\n    'stepresults_new',\n    NEW.event_id::text || ':' || NEW.agent_run_id::text || ':' || NEW.id::text\n  );\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS stepresults_new_trg ON stepresults;\nCREATE TRIGGER stepresults_new_trg\n  AFTER INSERT ON stepresults\n  FOR EACH ROW EXECUTE FUNCTION stepresults_notify_new();\n\n-- chatmessages NOTIFY: payload is \"<channel_id>:<role>:<id>\". Channel\n-- comes from the parent event's preferred_chat_channel_id, JOINed at\n-- trigger time. Empty channel becomes empty prefix \u2014 listeners will\n-- filter it out unless they explicitly subscribe to channelId=\"\".\nCREATE OR REPLACE FUNCTION chatmessages_notify_new() RETURNS trigger AS $$\nDECLARE\n  channel text;\nBEGIN\n  SELECT preferred_chat_channel_id INTO channel FROM events WHERE id = NEW.event_id;\n  PERFORM pg_notify(\n    'chatmessages_new',\n    COALESCE(channel, '') || ':' || NEW.role || ':' || NEW.id::text\n  );\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS chatmessages_new_trg ON chatmessages;\nCREATE TRIGGER chatmessages_new_trg\n  AFTER INSERT ON chatmessages\n  FOR EACH ROW EXECUTE FUNCTION chatmessages_notify_new();\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 calendars + calendar_events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Plugin-agnostic calendar data layer. `calendars` lists every\n-- subscription (own or shared) any provider plugin (ms365, future\n-- google/caldav) has surfaced; `calendar_events` stores every\n-- instance. Providers persist every occurrence of a recurring\n-- series independently (no master-expansion in core).\n--\n-- Identity:\n--   * `calendars.unique_key` is the provider's stable id. Uniqueness\n--     within `(plugin_id, unique_key)` lets multiple providers\n--     coexist.\n--   * `calendar_events.id` is provider-prefixed (e.g. `ms365:<graph-id>`)\n--     so collisions across providers are impossible by construction.\n--\n-- Refresh reconciliation uses a scan-generation tag: a refresh walk\n-- bumps `calendars.scan_generation`, upserts every event in window\n-- with the new value, then DELETEs events whose generation is older\n-- than the calendar's current value.\n\nCREATE TABLE IF NOT EXISTS calendars (\n  id              bigserial PRIMARY KEY,\n  plugin_id       text NOT NULL,\n  unique_key      text NOT NULL,\n  name            text NOT NULL,\n  type            text NOT NULL CHECK (type IN ('own','shared')),\n  owner_name      text,\n  scan_generation int  NOT NULL DEFAULT 0,\n  created_at      timestamptz NOT NULL DEFAULT now(),\n  UNIQUE (plugin_id, unique_key)\n);\n\n-- The provider's own \"default calendar\" flag (Graph's\n-- `isDefaultCalendar`). Used by `CalendarService.resolveDefaultCalendar`\n-- as the fallback when `core.defaultCalendar` is unset \u2014 we pick the\n-- first registered calendar (lowest id) flagged here. Added via\n-- ALTER so existing databases don't need a schema reset.\nALTER TABLE calendars ADD COLUMN IF NOT EXISTS is_default smallint NOT NULL DEFAULT 0;\n\nCREATE INDEX IF NOT EXISTS calendars_plugin_id_idx ON calendars (plugin_id);\n\nCREATE TABLE IF NOT EXISTS calendar_events (\n  id                  text PRIMARY KEY,\n  calendar_id         bigint NOT NULL REFERENCES calendars(id) ON DELETE CASCADE,\n  series_master_id    text,\n  type                text NOT NULL CHECK (type IN ('singleInstance','occurrence','exception','seriesMaster')),\n  subject             text,\n  start_dt            text NOT NULL,\n  end_dt              text NOT NULL,\n  event_tz            text,\n  is_all_day          smallint NOT NULL DEFAULT 0,\n  is_cancelled        smallint NOT NULL DEFAULT 0,\n  show_as             text,\n  sensitivity         text,\n  importance          text,\n  location            text,\n  is_online_meeting   smallint NOT NULL DEFAULT 0,\n  online_meeting_url  text,\n  organizer_name      text,\n  organizer_email     text,\n  response_status     text,\n  attendees_json      jsonb,\n  body                text,\n  attachments         jsonb,\n  scan_generation     int  NOT NULL,\n  created_at          timestamptz NOT NULL DEFAULT now(),\n  updated_at          timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS calendar_events_window_idx\n  ON calendar_events (calendar_id, start_dt);\nCREATE INDEX IF NOT EXISTS calendar_events_series_idx\n  ON calendar_events (series_master_id);\nCREATE INDEX IF NOT EXISTS calendar_events_generation_idx\n  ON calendar_events (calendar_id, scan_generation);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 scheduled_subagents \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- One-off agent-scheduled wake-ups. Each row is upserted by the\n-- container's `schedule_subagent` tool and read by the host-side\n-- `ScheduledSubagentScheduler`, which installs a Croner job per row\n-- and atomically deletes the row when it fires. `key` is the\n-- agent-supplied unique id used for replace-on-conflict semantics\n-- (\"rescheduling a key overwrites the previous timing\"). `fire_at`\n-- is the UTC firing time; the agent passes wall-clock-in-`core.timezone`\n-- and the container projects to UTC before insert. On daemon startup,\n-- past-due rows are deleted with a warn log; future rows are\n-- reinstalled. See [[feedback_agent_facing_format]] \u2014 UTC storage,\n-- local-tz projection at every agent-facing edge.\nCREATE TABLE IF NOT EXISTS scheduled_subagents (\n  key         text PRIMARY KEY,\n  fire_at     timestamptz NOT NULL,\n  topic       text NOT NULL,\n  prompt      text,\n  payload     jsonb NOT NULL DEFAULT '{}'::jsonb,\n  priority    smallint NOT NULL DEFAULT 50,\n  privileged  boolean NOT NULL DEFAULT false,\n  created_at  timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT scheduled_subagents_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$')\n);\n\n-- The topic is the handler's whole address; the basename column is gone.\nALTER TABLE scheduled_subagents DROP COLUMN IF EXISTS handler;\n-- Re-add the topic CHECK so a widened TOPIC_PATTERN reaches existing tables.\nALTER TABLE scheduled_subagents DROP CONSTRAINT IF EXISTS scheduled_subagents_topic_format;\nALTER TABLE scheduled_subagents ADD CONSTRAINT scheduled_subagents_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$');\n\nCREATE INDEX IF NOT EXISTS scheduled_subagents_fire_at_idx\n  ON scheduled_subagents (fire_at);\n\nCREATE OR REPLACE FUNCTION scheduled_subagents_notify_changed() RETURNS trigger AS $$\nDECLARE\n  payload_key text;\n  op text;\nBEGIN\n  IF TG_OP = 'DELETE' THEN\n    payload_key := OLD.key;\n    op := 'd';\n  ELSE\n    payload_key := NEW.key;\n    op := 'u';\n  END IF;\n  PERFORM pg_notify('scheduled_subagents_changed', payload_key || ':' || op);\n  RETURN COALESCE(NEW, OLD);\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS scheduled_subagents_notify_changed_trg ON scheduled_subagents;\nCREATE TRIGGER scheduled_subagents_notify_changed_trg\n  AFTER INSERT OR UPDATE OR DELETE ON scheduled_subagents\n  FOR EACH ROW EXECUTE FUNCTION scheduled_subagents_notify_changed();\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 inference_events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Append-only audit trail of every upstream model HTTP call attempt.\n-- Written by AgentRunner on each generate() outcome (success / retryable /\n-- fatal). Read by the host-side `inference_status` reflection tool to\n-- answer \"is this model misbehaving right now?\". One row per attempt;\n-- retries write multiple rows. NULL agent_run_id is kept for runs whose\n-- row was later deleted (parent event cascade) so the historical signal\n-- survives.\nCREATE TABLE IF NOT EXISTS inference_events (\n  id            bigserial PRIMARY KEY,\n  provider      text NOT NULL,\n  model         text NOT NULL,\n  agent_run_id  bigint REFERENCES agentruns(id) ON DELETE SET NULL,\n  outcome       text NOT NULL CHECK (outcome IN ('success','retryable','fatal')),\n  status_code   int,\n  error_excerpt text,\n  occurred_at   timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS inference_events_model_time_idx\n  ON inference_events (model, occurred_at DESC);\nCREATE INDEX IF NOT EXISTS inference_events_occurred_at_idx\n  ON inference_events (occurred_at DESC);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 tool_calls \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Append-only record of every tool invocation an agentrun attempted,\n-- tagged with the resolved handler markdown path and whether the call\n-- threw. Written by the tool wrapper in the container's ToolsFactory on\n-- each execute() outcome. Read by the heuristic tool-preloader\n-- (ToolCallBus.topToolsForHandler): the tools a handler successfully\n-- used across its recent non-error runs get loaded up front on the next\n-- run, so warm handlers rarely need a tool_list / tool_call round-trip.\n-- NULL agent_run_id survives a parent-event cascade so the historical\n-- usage signal outlives the run row.\nCREATE TABLE IF NOT EXISTS tool_calls (\n  id           bigserial PRIMARY KEY,\n  agent_run_id bigint REFERENCES agentruns(id) ON DELETE SET NULL,\n  handler_path text NOT NULL,\n  tool_name    text NOT NULL,\n  successful   boolean NOT NULL,\n  created_at   timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS tool_calls_handler_run_idx\n  ON tool_calls (handler_path, agent_run_id DESC);\nCREATE INDEX IF NOT EXISTS tool_calls_created_at_idx\n  ON tool_calls (created_at DESC);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 web_login_tokens / web_sessions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Authentication state of the host webserver (host-only; the container\n-- never reads these). A login token is a one-time link minted by\n-- `familiar web login`; redeeming it deletes the row and creates a\n-- session. Only sha256 hashes of tokens are stored, never the tokens.\nCREATE TABLE IF NOT EXISTS web_login_tokens (\n  token_hash  text PRIMARY KEY,\n  login       text NOT NULL,\n  expires_at  timestamptz NOT NULL,\n  created_at  timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE TABLE IF NOT EXISTS web_sessions (\n  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  token_hash    text NOT NULL UNIQUE,\n  login         text NOT NULL,\n  user_agent    text,\n  created_at    timestamptz NOT NULL DEFAULT now(),\n  last_seen_at  timestamptz NOT NULL DEFAULT now(),\n  expires_at    timestamptz NOT NULL\n);\n";
+export declare const SCHEMA_SQL = "\n-- Drop legacy single-table artifacts from before the events/agentruns\n-- split. Safe no-ops on fresh databases. The current schema reuses the\n-- name events_notify_new() for its own NOTIFY function, so we do NOT\n-- drop it here (CREATE OR REPLACE FUNCTION below handles the update);\n-- dropping would fail anyway once the current events_new_trg exists.\nDROP TRIGGER IF EXISTS events_notify_changed_trg ON events;\nDROP TRIGGER IF EXISTS events_notify_new_trg ON events;\nDROP FUNCTION IF EXISTS events_notify_changed();\nDROP INDEX IF EXISTS events_pending_priority_idx;\nDROP INDEX IF EXISTS events_state_priority_idx;\n\nCREATE TABLE IF NOT EXISTS events (\n  id              bigserial PRIMARY KEY,\n  topic           text NOT NULL,\n  priority        smallint NOT NULL DEFAULT 50,\n  state           text NOT NULL DEFAULT 'pending',\n  payload         jsonb NOT NULL DEFAULT '{}'::jsonb,\n  idempotency_key text UNIQUE,\n  privileged      boolean NOT NULL DEFAULT false,\n  created_at      timestamptz NOT NULL DEFAULT now(),\n  updated_at      timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT events_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$')\n);\n\n-- Drop legacy columns from earlier schema generations. Single-instance\n-- project; column drops are fine.\nALTER TABLE events DROP COLUMN IF EXISTS supervisor_prompt;\nALTER TABLE events DROP COLUMN IF EXISTS causation_chain;\n\n-- Chat-aware event metadata. `is_chat` opts into automatic user-message\n-- persistence in EventBus.add; `preferred_chat_channel_id` names the\n-- channel an assistant reply should reach the user on. The container is\n-- channel-blind \u2014 both fields are read host-side (for routing) or via\n-- JOIN inside the chatmessages NOTIFY trigger.\nALTER TABLE events ADD COLUMN IF NOT EXISTS is_chat boolean NOT NULL DEFAULT false;\nALTER TABLE events ADD COLUMN IF NOT EXISTS preferred_chat_channel_id text;\n-- Required for non-chat events (validated at `EventBus.add` time and at\n-- the type level via `NewEvent`'s discriminated union); always null for\n-- chat events because the user's text in `chatmessages` already serves\n-- as the agent-visible \"what happened\" message. The EventWatcher copies\n-- this verbatim into the root `agentruns.prompt` so the agent sees the\n-- emitter's framing without the EventWatcher having to reach into the\n-- payload schema.\nALTER TABLE events ADD COLUMN IF NOT EXISTS prompt text;\n-- The topic is the handler's whole address now; the separate start\n-- handler basename is gone.\nALTER TABLE events DROP COLUMN IF EXISTS start_handler;\n-- When true the topic must name an existing handler file exactly; when\n-- false (world events) handler resolution falls back up the topic chain.\n-- Copied onto the root agentrun by the input-event watcher.\nALTER TABLE events ADD COLUMN IF NOT EXISTS is_exact_topic boolean NOT NULL DEFAULT false;\n-- Privileged events originate from a trusted user-input source (operator\n-- at the local terminal via cli-chat, operator on Telegram). The flag\n-- propagates verbatim to the root agentrun and to every child agentrun\n-- spawned via schedule_subagent / start_subagent, so future system tools can\n-- gate risky reads / writes (editing SOUL.md etc.) on whether the run\n-- descends from a trusted input. Default false: any plugin that doesn't\n-- explicitly opt in produces non-privileged events.\nALTER TABLE events ADD COLUMN IF NOT EXISTS privileged boolean NOT NULL DEFAULT false;\n-- When true and the event ends in 'failed', `HostContextImpl.emitAndAwait`\n-- writes a role='assistant' chatmessage with the failure text before\n-- rejecting handle.settled. Default false: only chat plugins (cli-chat,\n-- telegram) opt in. See [[outputChatOnFailure]] on NewEvent for the\n-- rationale.\nALTER TABLE events ADD COLUMN IF NOT EXISTS output_chat_on_failure boolean NOT NULL DEFAULT false;\n\nCREATE INDEX IF NOT EXISTS events_state_priority_idx\n  ON events (state, priority DESC, id ASC);\nCREATE INDEX IF NOT EXISTS events_topic_idx ON events (topic);\n\nCREATE TABLE IF NOT EXISTS agentruns (\n  id                 bigserial PRIMARY KEY,\n  event_id           bigint NOT NULL REFERENCES events(id) ON DELETE CASCADE,\n  parent_agentrun_id bigint REFERENCES agentruns(id) ON DELETE CASCADE,\n  topic              text NOT NULL,\n  priority           smallint NOT NULL DEFAULT 50,\n  state              text NOT NULL DEFAULT 'pending',\n  prompt             text,\n  payload            jsonb NOT NULL DEFAULT '{}'::jsonb,\n  result             jsonb,\n  result_text        text,\n  error              text,\n  privileged         boolean NOT NULL DEFAULT false,\n  created_at         timestamptz NOT NULL DEFAULT now(),\n  updated_at         timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT agentruns_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$')\n);\n\n-- Forward-compat ALTER for databases created before result_text landed.\n-- Safe no-op on fresh databases where the column already exists.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS result_text text;\n-- The topic is the handler's whole address; the basename column is gone.\nALTER TABLE agentruns DROP COLUMN IF EXISTS handler;\n-- Whether handler resolution must match the topic exactly. Root\n-- agentruns copy the event's flag; spawned children are always exact.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS is_exact_topic boolean NOT NULL DEFAULT true;\n-- Inherited from the originating event (root agentrun) or parent\n-- agentrun (children spawned via schedule_subagent / start_subagent). See\n-- the matching ALTER on the events table for the trust-model rationale.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS privileged boolean NOT NULL DEFAULT false;\n-- Number of retry attempts already made on this agentrun. Bumped each\n-- time AgentRunner postpones the row due to a retryable inference\n-- error (APICallError.isRetryable). Capped per-handler via maxRetries\n-- (frontmatter override) or globally via inference.maxRetries.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS retry_count int NOT NULL DEFAULT 0;\n-- Earliest moment the agentrun watcher is allowed to re-claim this\n-- row. NULL = claim immediately (default for fresh rows). A future\n-- timestamp = leave the row alone until then; the watcher's claim\n-- query gates on this so a parked row doesn't waste the slot while\n-- other agentruns (potentially using different models) can still run.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS not_before timestamptz;\n-- Resolved model id for this agentrun, of the form\n-- `<provider>/<modelId>` (e.g. `featherless/zai-org/GLM-5.1`).\n-- Populated by AgentRunner once it builds the model client; stays\n-- NULL for any agentrun that never reached generate() (failed at\n-- handler-load time, etc.).\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS model text;\n-- Resolved prompt (rendered prompt template: system prompt, then\n-- user-message head) used for this agentrun. Populated by AgentRunner\n-- only when core.logSystemPrompt is true; otherwise NULL. Surfaced\n-- by the report layer's Agentrun Start section when the consumer\n-- opts into withDetails.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS system_prompt text;\n-- Verbatim model-message array assembled for the first agent.generate()\n-- call (prior history + the run's leading user turn). Populated by\n-- AgentRunner only when inference.captureInitialMessageHistory is true;\n-- otherwise NULL. Surfaced by the report layer's -vv view so an operator\n-- can see exactly what was sent into the model loop.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS initial_messages jsonb;\n\n-- Distinguishes how a child agentrun was spawned.\n--   NULL        \u2014 root agentrun (created by the input-event watcher, no parent).\n--   'scheduled' \u2014 fire-and-forget child spawned by `schedule_subagent` without\n--                 a future `when` (immediate dispatch under the same event).\n--   'started'   \u2014 synchronous child spawned via the `start_subagent` tool; the\n--                 parent is parked in state='waiting' until this row settles.\n-- The Scheduler reads this column to decide whether settling a row should\n-- wake a waiting parent.\nALTER TABLE agentruns ADD COLUMN IF NOT EXISTS calltype text;\nALTER TABLE agentruns DROP CONSTRAINT IF EXISTS agentruns_calltype_format;\nALTER TABLE agentruns ADD CONSTRAINT agentruns_calltype_format\n  CHECK (calltype IS NULL OR calltype IN ('scheduled','started'));\n\n-- Partial index for the \"are all started children of $parent settled?\"\n-- check the Scheduler runs after every 'started' child settles. Indexes\n-- only the rows that actually participate in the question.\nCREATE INDEX IF NOT EXISTS agentruns_parent_calltype_state_idx\n  ON agentruns (parent_agentrun_id, state)\n  WHERE calltype = 'started';\n\n-- Forward-compat: relax the topic CHECK constraint to allow arbitrarily\n-- deep `a:b:c:\u2026` topics. CREATE TABLE IF NOT EXISTS above doesn't\n-- update existing constraints, so we drop+re-add unconditionally. The\n-- DROP IF EXISTS / ADD pair is idempotent.\nALTER TABLE events DROP CONSTRAINT IF EXISTS events_topic_format;\nALTER TABLE events ADD CONSTRAINT events_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$');\nALTER TABLE agentruns DROP CONSTRAINT IF EXISTS agentruns_topic_format;\nALTER TABLE agentruns ADD CONSTRAINT agentruns_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$');\n\nCREATE INDEX IF NOT EXISTS agentruns_state_priority_idx\n  ON agentruns (state, priority DESC, id ASC);\nCREATE INDEX IF NOT EXISTS agentruns_event_id_idx ON agentruns (event_id);\nCREATE INDEX IF NOT EXISTS agentruns_parent_idx ON agentruns (parent_agentrun_id);\n\nCREATE TABLE IF NOT EXISTS stepresults (\n  id              bigserial PRIMARY KEY,\n  agent_run_id    bigint NOT NULL REFERENCES agentruns(id) ON DELETE CASCADE,\n  event_id        bigint NOT NULL REFERENCES events(id) ON DELETE CASCADE,\n  step_number     int    NOT NULL,\n  finish_reason   text   NOT NULL,\n  result_text     text,\n  reasoning_text  text,\n  input_tokens    int,\n  output_tokens   int,\n  total_tokens    int,\n  tool_call_count int    NOT NULL DEFAULT 0,\n  tool_calls      jsonb  NOT NULL DEFAULT '[]'::jsonb,\n  tool_results    jsonb  NOT NULL DEFAULT '[]'::jsonb,\n  created_at      timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT stepresults_step_number_unique UNIQUE (agent_run_id, step_number)\n);\n\nCREATE INDEX IF NOT EXISTS stepresults_agent_run_id_idx ON stepresults (agent_run_id);\nCREATE INDEX IF NOT EXISTS stepresults_event_id_idx     ON stepresults (event_id);\n\n-- AI SDK per-step usage breakdown\n-- (LanguageModelUsage.inputTokenDetails / outputTokenDetails). Each\n-- column is NULL when the provider doesn't report that detail.\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS input_tokens_no_cache    int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS input_tokens_cache_read  int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS input_tokens_cache_write int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS output_tokens_text       int;\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS output_tokens_reasoning  int;\n-- Full step object snapshot, populated only when the operator opts\n-- in via inference.captureRawStepResultToDatabase: true. Used to\n-- inspect provider-specific fields (Anthropic cache control,\n-- OpenAI logprobs, ...) that don't fit dedicated columns.\nALTER TABLE stepresults ADD COLUMN IF NOT EXISTS raw_result jsonb;\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 chatmessages \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Persistent chat history across all channels. Each row links to the\n-- event whose lifecycle the message belongs to:\n--   * For role='user': the event the host plugin emitted with isChat=true.\n--   * For role='assistant': the event whose agentrun called send_chat.\n-- The channel is reachable via JOIN to events.preferred_chat_channel_id;\n-- there is intentionally no channel_id column here \u2014 channel routing is\n-- a host-side concern, the container never names a channel.\n--\n-- delivered_at is set when ANY listener returns true from its async\n-- handler. New subscribers replay all undelivered matching rows on\n-- registration so a message produced when nobody was listening is still\n-- delivered later.\nCREATE TABLE IF NOT EXISTS chatmessages (\n  id           bigserial PRIMARY KEY,\n  event_id     bigint NOT NULL REFERENCES events(id) ON DELETE CASCADE,\n  role         text NOT NULL CHECK (role IN ('user','assistant')),\n  text_content text NOT NULL,\n  created_at   timestamptz NOT NULL DEFAULT now(),\n  delivered_at timestamptz\n);\n\nCREATE INDEX IF NOT EXISTS chatmessages_event_idx\n  ON chatmessages (event_id);\nCREATE INDEX IF NOT EXISTS chatmessages_undelivered_idx\n  ON chatmessages (created_at) WHERE delivered_at IS NULL;\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 NOTIFY triggers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nCREATE OR REPLACE FUNCTION events_notify_new() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify('events_new', NEW.id::text);\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS events_new_trg ON events;\nCREATE TRIGGER events_new_trg\n  AFTER INSERT ON events\n  FOR EACH ROW EXECUTE FUNCTION events_notify_new();\n\nCREATE OR REPLACE FUNCTION events_notify_state() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify('events_state', NEW.id::text || ':' || NEW.state);\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS events_state_trg ON events;\nCREATE TRIGGER events_state_trg\n  AFTER UPDATE OF state ON events\n  FOR EACH ROW EXECUTE FUNCTION events_notify_state();\n\nCREATE OR REPLACE FUNCTION agentruns_notify_changed() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify(\n    'agentruns_changed',\n    NEW.event_id::text || ':' || NEW.id::text\n  );\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS agentruns_notify_changed_trg ON agentruns;\nCREATE TRIGGER agentruns_notify_changed_trg\n  AFTER INSERT OR UPDATE OF state ON agentruns\n  FOR EACH ROW EXECUTE FUNCTION agentruns_notify_changed();\n\nCREATE OR REPLACE FUNCTION stepresults_notify_new() RETURNS trigger AS $$\nBEGIN\n  PERFORM pg_notify(\n    'stepresults_new',\n    NEW.event_id::text || ':' || NEW.agent_run_id::text || ':' || NEW.id::text\n  );\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS stepresults_new_trg ON stepresults;\nCREATE TRIGGER stepresults_new_trg\n  AFTER INSERT ON stepresults\n  FOR EACH ROW EXECUTE FUNCTION stepresults_notify_new();\n\n-- chatmessages NOTIFY: payload is \"<channel_id>:<role>:<id>\". Channel\n-- comes from the parent event's preferred_chat_channel_id, JOINed at\n-- trigger time. Empty channel becomes empty prefix \u2014 listeners will\n-- filter it out unless they explicitly subscribe to channelId=\"\".\nCREATE OR REPLACE FUNCTION chatmessages_notify_new() RETURNS trigger AS $$\nDECLARE\n  channel text;\nBEGIN\n  SELECT preferred_chat_channel_id INTO channel FROM events WHERE id = NEW.event_id;\n  PERFORM pg_notify(\n    'chatmessages_new',\n    COALESCE(channel, '') || ':' || NEW.role || ':' || NEW.id::text\n  );\n  RETURN NEW;\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS chatmessages_new_trg ON chatmessages;\nCREATE TRIGGER chatmessages_new_trg\n  AFTER INSERT ON chatmessages\n  FOR EACH ROW EXECUTE FUNCTION chatmessages_notify_new();\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 calendars + calendar_events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Plugin-agnostic calendar data layer. `calendars` lists every\n-- subscription (own or shared) any provider plugin (ms365, future\n-- google/caldav) has surfaced; `calendar_events` stores every\n-- instance. Providers persist every occurrence of a recurring\n-- series independently (no master-expansion in core).\n--\n-- Identity:\n--   * `calendars.unique_key` is the provider's stable id. Uniqueness\n--     within `(plugin_id, unique_key)` lets multiple providers\n--     coexist.\n--   * `calendar_events.id` is provider-prefixed (e.g. `ms365:<graph-id>`)\n--     so collisions across providers are impossible by construction.\n--\n-- Refresh reconciliation uses a scan-generation tag: a refresh walk\n-- bumps `calendars.scan_generation`, upserts every event in window\n-- with the new value, then DELETEs events whose generation is older\n-- than the calendar's current value.\n\nCREATE TABLE IF NOT EXISTS calendars (\n  id              bigserial PRIMARY KEY,\n  plugin_id       text NOT NULL,\n  unique_key      text NOT NULL,\n  name            text NOT NULL,\n  type            text NOT NULL CHECK (type IN ('own','shared')),\n  owner_name      text,\n  scan_generation int  NOT NULL DEFAULT 0,\n  created_at      timestamptz NOT NULL DEFAULT now(),\n  UNIQUE (plugin_id, unique_key)\n);\n\n-- The provider's own \"default calendar\" flag (Graph's\n-- `isDefaultCalendar`). Used by `CalendarService.resolveDefaultCalendar`\n-- as the fallback when `core.defaultCalendar` is unset \u2014 we pick the\n-- first registered calendar (lowest id) flagged here. Added via\n-- ALTER so existing databases don't need a schema reset.\nALTER TABLE calendars ADD COLUMN IF NOT EXISTS is_default smallint NOT NULL DEFAULT 0;\n\nCREATE INDEX IF NOT EXISTS calendars_plugin_id_idx ON calendars (plugin_id);\n\nCREATE TABLE IF NOT EXISTS calendar_events (\n  id                  text PRIMARY KEY,\n  calendar_id         bigint NOT NULL REFERENCES calendars(id) ON DELETE CASCADE,\n  series_master_id    text,\n  type                text NOT NULL CHECK (type IN ('singleInstance','occurrence','exception','seriesMaster')),\n  subject             text,\n  start_dt            text NOT NULL,\n  end_dt              text NOT NULL,\n  event_tz            text,\n  is_all_day          smallint NOT NULL DEFAULT 0,\n  is_cancelled        smallint NOT NULL DEFAULT 0,\n  show_as             text,\n  sensitivity         text,\n  importance          text,\n  location            text,\n  is_online_meeting   smallint NOT NULL DEFAULT 0,\n  online_meeting_url  text,\n  organizer_name      text,\n  organizer_email     text,\n  response_status     text,\n  attendees_json      jsonb,\n  body                text,\n  attachments         jsonb,\n  scan_generation     int  NOT NULL,\n  created_at          timestamptz NOT NULL DEFAULT now(),\n  updated_at          timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS calendar_events_window_idx\n  ON calendar_events (calendar_id, start_dt);\nCREATE INDEX IF NOT EXISTS calendar_events_series_idx\n  ON calendar_events (series_master_id);\nCREATE INDEX IF NOT EXISTS calendar_events_generation_idx\n  ON calendar_events (calendar_id, scan_generation);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 scheduled_subagents \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- One-off agent-scheduled wake-ups. Each row is upserted by the\n-- container's `schedule_subagent` tool and read by the host-side\n-- `ScheduledSubagentScheduler`, which installs a Croner job per row\n-- and atomically deletes the row when it fires. `key` is the\n-- agent-supplied unique id used for replace-on-conflict semantics\n-- (\"rescheduling a key overwrites the previous timing\"). `fire_at`\n-- is the UTC firing time; the agent passes wall-clock-in-`core.timezone`\n-- and the container projects to UTC before insert. On daemon startup,\n-- past-due rows are deleted with a warn log; future rows are\n-- reinstalled. See [[feedback_agent_facing_format]] \u2014 UTC storage,\n-- local-tz projection at every agent-facing edge.\nCREATE TABLE IF NOT EXISTS scheduled_subagents (\n  key         text PRIMARY KEY,\n  fire_at     timestamptz NOT NULL,\n  topic       text NOT NULL,\n  prompt      text,\n  payload     jsonb NOT NULL DEFAULT '{}'::jsonb,\n  priority    smallint NOT NULL DEFAULT 50,\n  privileged  boolean NOT NULL DEFAULT false,\n  created_at  timestamptz NOT NULL DEFAULT now(),\n  CONSTRAINT scheduled_subagents_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$')\n);\n\n-- The topic is the handler's whole address; the basename column is gone.\nALTER TABLE scheduled_subagents DROP COLUMN IF EXISTS handler;\n-- Re-add the topic CHECK so a widened TOPIC_PATTERN reaches existing tables.\nALTER TABLE scheduled_subagents DROP CONSTRAINT IF EXISTS scheduled_subagents_topic_format;\nALTER TABLE scheduled_subagents ADD CONSTRAINT scheduled_subagents_topic_format CHECK (topic ~ '^[\\w-]+(:[\\w-]+)*$');\n\nCREATE INDEX IF NOT EXISTS scheduled_subagents_fire_at_idx\n  ON scheduled_subagents (fire_at);\n\nCREATE OR REPLACE FUNCTION scheduled_subagents_notify_changed() RETURNS trigger AS $$\nDECLARE\n  payload_key text;\n  op text;\nBEGIN\n  IF TG_OP = 'DELETE' THEN\n    payload_key := OLD.key;\n    op := 'd';\n  ELSE\n    payload_key := NEW.key;\n    op := 'u';\n  END IF;\n  PERFORM pg_notify('scheduled_subagents_changed', payload_key || ':' || op);\n  RETURN COALESCE(NEW, OLD);\nEND;\n$$ LANGUAGE plpgsql;\n\nDROP TRIGGER IF EXISTS scheduled_subagents_notify_changed_trg ON scheduled_subagents;\nCREATE TRIGGER scheduled_subagents_notify_changed_trg\n  AFTER INSERT OR UPDATE OR DELETE ON scheduled_subagents\n  FOR EACH ROW EXECUTE FUNCTION scheduled_subagents_notify_changed();\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 inference_events \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Append-only audit trail of every upstream model HTTP call attempt.\n-- Written by AgentRunner on each generate() outcome (success / retryable /\n-- fatal). Read by the host-side `inference_status` reflection tool to\n-- answer \"is this model misbehaving right now?\". One row per attempt;\n-- retries write multiple rows. NULL agent_run_id is kept for runs whose\n-- row was later deleted (parent event cascade) so the historical signal\n-- survives.\nCREATE TABLE IF NOT EXISTS inference_events (\n  id            bigserial PRIMARY KEY,\n  provider      text NOT NULL,\n  model         text NOT NULL,\n  agent_run_id  bigint REFERENCES agentruns(id) ON DELETE SET NULL,\n  outcome       text NOT NULL CHECK (outcome IN ('success','retryable','fatal')),\n  status_code   int,\n  error_excerpt text,\n  occurred_at   timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS inference_events_model_time_idx\n  ON inference_events (model, occurred_at DESC);\nCREATE INDEX IF NOT EXISTS inference_events_occurred_at_idx\n  ON inference_events (occurred_at DESC);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 tool_calls \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Append-only record of every tool invocation an agentrun attempted,\n-- tagged with the resolved handler markdown path and whether the call\n-- threw. Written by the tool wrapper in the container's ToolsFactory on\n-- each execute() outcome. Read by the heuristic tool-preloader\n-- (ToolCallBus.topToolsForHandler): the tools a handler successfully\n-- used across its recent non-error runs get loaded up front on the next\n-- run, so warm handlers rarely need a tool_list / tool_call round-trip.\n-- NULL agent_run_id survives a parent-event cascade so the historical\n-- usage signal outlives the run row.\nCREATE TABLE IF NOT EXISTS tool_calls (\n  id           bigserial PRIMARY KEY,\n  agent_run_id bigint REFERENCES agentruns(id) ON DELETE SET NULL,\n  handler_path text NOT NULL,\n  tool_name    text NOT NULL,\n  successful   boolean NOT NULL,\n  created_at   timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS tool_calls_handler_run_idx\n  ON tool_calls (handler_path, agent_run_id DESC);\nCREATE INDEX IF NOT EXISTS tool_calls_created_at_idx\n  ON tool_calls (created_at DESC);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 web_login_tokens / web_sessions \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Authentication state of the host webserver (host-only; the container\n-- never reads these). A login token is a one-time link minted by\n-- `familiar web login`; redeeming it deletes the row and creates a\n-- session. Only sha256 hashes of tokens are stored, never the tokens.\nCREATE TABLE IF NOT EXISTS web_login_tokens (\n  token_hash  text PRIMARY KEY,\n  login       text NOT NULL,\n  expires_at  timestamptz NOT NULL,\n  created_at  timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE TABLE IF NOT EXISTS web_sessions (\n  id            uuid PRIMARY KEY DEFAULT gen_random_uuid(),\n  token_hash    text NOT NULL UNIQUE,\n  login         text NOT NULL,\n  user_agent    text,\n  created_at    timestamptz NOT NULL DEFAULT now(),\n  last_seen_at  timestamptz NOT NULL DEFAULT now(),\n  expires_at    timestamptz NOT NULL\n);\n\n-- \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 banners \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n--\n-- Short-lived notes the agent leaves for every later agentrun (e.g. \"the\n-- user is setting up a new phone today\"). Active banners are rendered\n-- into each prompt via the core {BANNER_LIST} placeholder; a banner\n-- disappears once `expires_at` passes (expired rows are deleted lazily\n-- by `BannerBus` on read / create). The created_by_* columns are the\n-- audit trail: which run (and topic) left the note.\nCREATE TABLE IF NOT EXISTS banners (\n  id                      bigserial PRIMARY KEY,\n  text                    text NOT NULL,\n  expires_at              timestamptz NOT NULL,\n  created_by_agentrun_id  bigint REFERENCES agentruns(id) ON DELETE SET NULL,\n  created_by_topic        text,\n  created_at              timestamptz NOT NULL DEFAULT now()\n);\n\nCREATE INDEX IF NOT EXISTS banners_expires_at_idx\n  ON banners (expires_at);\n";
 /**
  * SQL fragment that flips the parent event's terminal state when the
  * **root** agentrun settles. Run inside the same transaction as the

package/build/Schema.js

@@ -572,6 +572,26 @@ CREATE TABLE IF NOT EXISTS web_sessions (
   last_seen_at  timestamptz NOT NULL DEFAULT now(),
   expires_at    timestamptz NOT NULL
 );
+
+-- ───────── banners ─────────
+--
+-- Short-lived notes the agent leaves for every later agentrun (e.g. "the
+-- user is setting up a new phone today"). Active banners are rendered
+-- into each prompt via the core {BANNER_LIST} placeholder; a banner
+-- disappears once \`expires_at\` passes (expired rows are deleted lazily
+-- by \`BannerBus\` on read / create). The created_by_* columns are the
+-- audit trail: which run (and topic) left the note.
+CREATE TABLE IF NOT EXISTS banners (
+  id                      bigserial PRIMARY KEY,
+  text                    text NOT NULL,
+  expires_at              timestamptz NOT NULL,
+  created_by_agentrun_id  bigint REFERENCES agentruns(id) ON DELETE SET NULL,
+  created_by_topic        text,
+  created_at              timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE INDEX IF NOT EXISTS banners_expires_at_idx
+  ON banners (expires_at);
 `;
 /**
  * SQL fragment that flips the parent event's terminal state when the

package/build/WebPlugin.d.ts

@@ -8,6 +8,7 @@
  * `/plugins/<plugin-id>`.
  */
 import type { Hono } from "hono";
+import type { AvatarConfig } from "./AssistantAvatar.js";
 import type { WebPrincipal, WebUiEnv } from "./WebAuth.js";
 /** Where a plugin page's ES module comes from. */
 export interface WebPageModule {
@@ -124,9 +125,18 @@ export interface WebPageContext {
     readonly pathname: string;
     /** The signed-in user. */
     readonly user: WebPrincipal;
+    /** The assistant's name and avatar, as configured (render with `@getfamiliar/avatar`). */
+    readonly assistant: WebAssistantIdentity;
     /** Navigate the web UI to another route. */
     navigate(to: string): void;
 }
+/** How the assistant presents itself in the web UI. */
+export interface WebAssistantIdentity {
+    /** `core.assistantName`, default `Familiar`. */
+    readonly name: string;
+    /** `core.assistantAvatar`, completed with defaults. */
+    readonly avatar: AvatarConfig;
+}
 /**
  * Default export of a page module: render the page into `container`
  * (the web UI's content area) and return a function that unmounts it.

package/build/index.d.ts

@@ -1,11 +1,13 @@
 export type { AgentRunCallType, AgentRunPatch, AgentRunRow, AgentRunState, NewAgentRun, } from "./AgentRun.js";
 export { AgentRunBus, type AgentRunUnsubscribe } from "./AgentRunBus.js";
+export { ASSISTANT_AVATAR_CONFIG_KEY, AVATAR_OPTION_VALUES, type AvatarConfig, type AvatarEyebrowType, type AvatarEyeType, type AvatarMouthType, type AvatarOptionField, type AvatarTopType, DEFAULT_AVATAR, findAvatarConfigProblems, isAvatarOptionRelevant, normalizeAvatarConfig, } from "./AssistantAvatar.js";
+export { BANNER_MAX_ACTIVE, BANNER_MAX_LIFETIME_DAYS, BANNER_MAX_TEXT_CHARS, BannerBus, type BannerRow, formatBannerList, formatBannerTime, type NewBanner, } from "./BannerBus.js";
 export { BASTION_TOKEN_HEADER } from "./BastionAuth.js";
 export { buildCalendarEventId, type CalendarApi, type CalendarAttachmentMeta, type CalendarAttendee, type CalendarChangePayload, type CalendarEventRow, type CalendarEventType, type CalendarImportance, type CalendarProvider, type CalendarResponseStatus, type CalendarRow, type CalendarSensitivity, type CalendarShowAs, type CalendarType, type CreateEventInput, type FindEventsQuery, type NewCalendarEvent, parseCalendarEventId, type UpdateEventInput, type UpsertCalendarInput, } from "./Calendar.js";
 export { type ParsedChatInput, parseChatInput } from "./ChatInput.js";
 export { type ChatFilter, type ChatHistoryQuery, type ChatMessage, type ChatRole, MAX_CHAT_HISTORY_PAGE, type NewChatMessage, } from "./ChatMessage.js";
 export { type ChatHandler, ChatMessageBus, type ChatUnsubscribe } from "./ChatMessageBus.js";
-export { type ConfigService, DEFAULT_WRITABLE_PATHS } from "./Config.js";
+export { ASSISTANT_NAME_CONFIG_KEY, type ConfigService, DEFAULT_ASSISTANT_NAME, DEFAULT_WRITABLE_PATHS, resolveAssistantName, } from "./Config.js";
 export type { ContainerToolInfo } from "./ContainerTool.js";
 export { type ParsedCron, parseCron } from "./CronExpression.js";
 export { buildNetworkCreateArgs, connectNetwork, type DockerCaptureResult, type DockerExecOptions, dockerCapture, dockerExec, dockerInteractive, ensureNetwork, hostGatewayArgs, ISOLATED_NETWORK_NAME, isContainerRunning, isImagePresent, isNetworkPresent, type NetworkCreateOptions, removeContainer, SHARED_NETWORK_NAME, stopContainer, } from "./DockerTools.js";
@@ -30,6 +32,7 @@ export { DaemonStoppedError, definePlugin } from "./Plugin.js";
 export { type NotificationHandler, POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConnection, type PostgresConnectionConfig, } from "./PostgresConnection.js";
 export { CACHE_MARKER_PLACEHOLDER, CORE_PROMPT_PLACEHOLDERS, isCorePromptPlaceholder, PROMPT_PLACEHOLDER_NAME_PATTERN, PROMPT_TEMPLATE_FILE, PromptPlaceholderConflictError, type PromptPlaceholderDefinition, type PromptPlaceholderKind, } from "./PromptPlaceholders.js";
 export { isSafeIncludePath, MAX_TEMPLATE_DEPTH, type ParsedTemplate, type ParseTemplateOptions, type PlaceholderUse, parseTemplate, type RenderedTemplate, renderTemplate, type TemplateNode, } from "./PromptTemplate.js";
+export { formatRuntimeTime } from "./RuntimeTime.js";
 export type { NewScheduledSubagent, ScheduledSubagentRow } from "./ScheduledSubagent.js";
 export { ScheduledSubagentBus, type ScheduledSubagentNotification, type ScheduledSubagentOp, type ScheduledSubagentUnsubscribe, } from "./ScheduledSubagentBus.js";
 export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
@@ -45,7 +48,7 @@ export { DEFAULT_TOOL_CALL_OFFLOADING_LIMIT, type OffloadedJson, runJsonLinesToo
 export { ALL_GROUP_NAME, CORE_PLUGIN_ID, IDENT_PATTERN, MCP_GROUP_NAME, matchesAnyToolPattern, NONE_GROUP_NAME, RESERVED_GROUP_NAMES, toolPatternMatches, validateGroupName, } from "./ToolsExpressionUtils.js";
 export { MIN_PROXY_SECRET_LENGTH, PROXY_SECRET_HEADER, type TrustedProxyRegistration, type WebApi, type WebAuthPageView, type WebPrincipal, type WebUi, type WebUiBindings, type WebUiEnv, } from "./WebAuth.js";
 export { firstMenuRoute, WEB_MENU_ICON_PATTERN, type WebMenuContribution, type WebMenuEntry, type WebMenuItem, type WebMenuSubItem, } from "./WebMenu.js";
-export { type MountWebPage, type WebPageContext, type WebPageEntry, type WebPageModule, type WebPluginSocket, type WebPluginUi, type WebSocketConnectionInfo, type WebSocketPeer, webPluginBasePath, } from "./WebPlugin.js";
+export { type MountWebPage, type WebAssistantIdentity, type WebPageContext, type WebPageEntry, type WebPageModule, type WebPluginSocket, type WebPluginUi, type WebSocketConnectionInfo, type WebSocketPeer, webPluginBasePath, } from "./WebPlugin.js";
 export { DEFAULT_WEBSERVER_HOST, DEFAULT_WEBSERVER_PORT } from "./WebServerDefaults.js";
 export { contentTypeForFile, WebStaticAssets, type WebStaticAssetsOptions, } from "./WebStaticAssets.js";
 export type { WorkspaceFile, WorkspaceFileFilter, WorkspaceWatcherApi, } from "./WorkspaceFile.js";

package/build/index.js

@@ -1,10 +1,12 @@
 export { AgentRunBus } from "./AgentRunBus.js";
+export { ASSISTANT_AVATAR_CONFIG_KEY, AVATAR_OPTION_VALUES, DEFAULT_AVATAR, findAvatarConfigProblems, isAvatarOptionRelevant, normalizeAvatarConfig, } from "./AssistantAvatar.js";
+export { BANNER_MAX_ACTIVE, BANNER_MAX_LIFETIME_DAYS, BANNER_MAX_TEXT_CHARS, BannerBus, formatBannerList, formatBannerTime, } from "./BannerBus.js";
 export { BASTION_TOKEN_HEADER } from "./BastionAuth.js";
 export { buildCalendarEventId, parseCalendarEventId, } from "./Calendar.js";
 export { parseChatInput } from "./ChatInput.js";
 export { MAX_CHAT_HISTORY_PAGE, } from "./ChatMessage.js";
 export { ChatMessageBus } from "./ChatMessageBus.js";
-export { DEFAULT_WRITABLE_PATHS } from "./Config.js";
+export { ASSISTANT_NAME_CONFIG_KEY, DEFAULT_ASSISTANT_NAME, DEFAULT_WRITABLE_PATHS, resolveAssistantName, } from "./Config.js";
 export { parseCron } from "./CronExpression.js";
 export { buildNetworkCreateArgs, connectNetwork, dockerCapture, dockerExec, dockerInteractive, ensureNetwork, hostGatewayArgs, ISOLATED_NETWORK_NAME, isContainerRunning, isImagePresent, isNetworkPresent, removeContainer, SHARED_NETWORK_NAME, stopContainer, } from "./DockerTools.js";
 export { EVENT_PRIORITY } from "./Event.js";
@@ -25,6 +27,7 @@ export { DaemonStoppedError, definePlugin } from "./Plugin.js";
 export { POSTGRES_DB, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_USER, PostgresConnection, } from "./PostgresConnection.js";
 export { CACHE_MARKER_PLACEHOLDER, CORE_PROMPT_PLACEHOLDERS, isCorePromptPlaceholder, PROMPT_PLACEHOLDER_NAME_PATTERN, PROMPT_TEMPLATE_FILE, PromptPlaceholderConflictError, } from "./PromptPlaceholders.js";
 export { isSafeIncludePath, MAX_TEMPLATE_DEPTH, parseTemplate, renderTemplate, } from "./PromptTemplate.js";
+export { formatRuntimeTime } from "./RuntimeTime.js";
 export { ScheduledSubagentBus, } from "./ScheduledSubagentBus.js";
 export { AGENTRUNS_CHANNEL, CHATMESSAGES_NEW_CHANNEL, EVENT_TERMINAL_UPDATE_SQL, EVENTS_NEW_CHANNEL, EVENTS_STATE_CHANNEL, SCHEDULED_SUBAGENTS_CHANNEL, SCHEMA_SQL, STEPRESULTS_NEW_CHANNEL, TOPIC_PATTERN, } from "./Schema.js";
 export { isHiddenScratchFile, scratchSpillFileName } from "./Scratch.js";

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@getfamiliar/shared",
   "type": "module",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "description": "Familiar — shared types and bus-state client between host and container.",
   "publishConfig": {
     "access": "public"
@@ -13,6 +13,10 @@
       "types": "./build/index.d.ts",
       "default": "./build/index.js"
     },
+    "./avatar": {
+      "types": "./build/AssistantAvatar.d.ts",
+      "default": "./build/AssistantAvatar.js"
+    },
     "./testing": {
       "types": "./build/testing/index.d.ts",
       "default": "./build/testing/index.js"