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

package/packages/core/dist/widgets.d.ts

@@ -0,0 +1,206 @@
+/**
+ * Widgets: small live panels a plugin exports for the dashboard's Home.
+ *
+ * The glance card (`home.ts`, `card` on a glance) generalised. A widget is a
+ * named, read-only function that answers a **body** from a small fixed
+ * vocabulary — a figure, a few rows, a strip of tiles, a bar, a sentence —
+ * with every value already formatted in the plugin's own units. The page owns
+ * the frame (title, menu, stale and error states) and six renderers; it
+ * draws no plugin HTML and knows no plugin by name. The owner picks which
+ * widgets sit on Home, in which order and at which size.
+ *
+ * Three rules, the metric's (`metrics.ts`):
+ *
+ *  1. **It only reads.** `produce` is handed a context whose `db` is the
+ *     read-only pool a page query runs in.
+ *  2. **`null` is an answer**: nothing to show right now. The frame says so.
+ *  3. **A broken widget is not a broken Home.** One that throws, times out or
+ *     answers a body the page cannot draw shows its own error state (with the
+ *     last good body when there is one) and nothing else is touched.
+ */
+import type { CoreToolContext, ToolContext } from './tools.js';
+import { type WidgetSettingField, type WidgetSettingOption, type WidgetSettings } from './widget-settings.js';
+import { type TileIcon } from './views.js';
+import { type HomeGlanceCard } from './home.js';
+/** Small takes one column of Home's grid, medium two. One row height for both. */
+export declare const WIDGET_SIZES: readonly ["small", "medium"];
+export type WidgetSize = (typeof WIDGET_SIZES)[number];
+/** The vocabulary. A new kind is a host API minor and a renderer in the page. */
+export declare const WIDGET_BODY_KINDS: readonly ["stat", "list", "strip", "progress", "text", "clocks"];
+export type WidgetBodyKind = (typeof WIDGET_BODY_KINDS)[number];
+/** How often a widget is produced again, at most and at least, and by default. */
+export declare const WIDGET_REFRESH_MIN_S = 60;
+export declare const WIDGET_REFRESH_MAX_S = 86400;
+export declare const WIDGET_REFRESH_DEFAULT_S = 600;
+/** Lengths past which text is cut with an ellipsis, and how many of a thing are kept. */
+export declare const WIDGET_TITLE_MAX = 40;
+export declare const WIDGET_VALUE_MAX = 12;
+export declare const WIDGET_LINE_MAX = 40;
+export declare const WIDGET_TEXT_MAX = 160;
+export declare const WIDGET_TREND_MAX = 48;
+export declare const WIDGET_ROWS_MAX = 3;
+export declare const WIDGET_ITEMS_MAX = 8;
+/** Faces a clocks body keeps: medium draws four, small two. */
+export declare const WIDGET_CLOCKS_MAX = 4;
+/** A face's label is short: it sits under a face a quarter of a medium widget wide. */
+export declare const WIDGET_CLOCK_LABEL_MAX = 24;
+/** A figure, a quiet line, a short run of numbers drawn as a sparkline, a foot. The weather card. */
+export interface WidgetStat {
+    kind: 'stat';
+    icon?: TileIcon;
+    /** Already formatted: "18°C", "3". At most `WIDGET_VALUE_MAX` characters. */
+    value: string;
+    caption?: string;
+    /** Two to `WIDGET_TREND_MAX` finite numbers, in order; no axis is drawn. */
+    trend?: {
+        label?: string;
+        points: number[];
+    };
+    foot?: string;
+}
+export interface WidgetListRow {
+    title: string;
+    sub?: string;
+    /** The right-hand figure, already formatted: "20:00", "€42". */
+    side?: string;
+    tone?: 'good' | 'critical';
+}
+/** Up to `WIDGET_ROWS_MAX` rows (a small widget draws them without `sub`), and a foot. */
+export interface WidgetList {
+    kind: 'list';
+    rows: WidgetListRow[];
+    /** "2 more tomorrow". */
+    more?: string;
+}
+export interface WidgetStripItem {
+    /** "14:00", "Thu". */
+    label: string;
+    icon?: TileIcon;
+    value: string;
+}
+/** A headline and a row of tiles: the next hours, the next days. Small draws four, medium six. */
+export interface WidgetStrip {
+    kind: 'strip';
+    icon?: TileIcon;
+    value?: string;
+    caption?: string;
+    items: WidgetStripItem[];
+}
+/** A figure and how far along it is: spent of a budget, done of a list. */
+export interface WidgetProgress {
+    kind: 'progress';
+    value: string;
+    caption?: string;
+    /** 0 to 1; outside is clamped. */
+    ratio: number;
+    foot?: string;
+    tone?: 'accent' | 'good' | 'warning' | 'critical';
+}
+/** A glyph and a sentence, for what has no number. */
+export interface WidgetText {
+    kind: 'text';
+    icon?: TileIcon;
+    /** At most `WIDGET_TEXT_MAX` characters. */
+    text: string;
+    sub?: string;
+}
+/**
+ * Analog faces side by side (since 1.21): zones and labels only. The page
+ * reads each zone's time from the device's clock, so the faces tick without a
+ * new answer, and works out the rest itself — the hands, a light face by day
+ * (6:00–18:00 there) and a dark one at night, Today/Tomorrow/Yesterday and the
+ * offset against `home`. Medium draws the first four, small the first two; a
+ * first face in `home` reads as the owner's own ("Here").
+ */
+export interface WidgetClocks {
+    kind: 'clocks';
+    /** The owner's zone, an IANA name: what days and offsets are counted from. */
+    home: string;
+    /** One to `WIDGET_CLOCKS_MAX`; each label at most `WIDGET_CLOCK_LABEL_MAX` characters. */
+    clocks: Array<{
+        label: string;
+        zone: string;
+    }>;
+    /** How a screen reader and the hover say each time; the device's way when left out. */
+    time?: '12h' | '24h';
+}
+export type WidgetBody = WidgetStat | WidgetList | WidgetStrip | WidgetProgress | WidgetText | WidgetClocks;
+/** Where a placement sits: Home's grid, or the lock screen's compact row. */
+export declare const WIDGET_SURFACES: readonly ["home", "lock"];
+export type WidgetSurface = (typeof WIDGET_SURFACES)[number];
+/**
+ * What `produce` is told: the size the owner put it at, so a medium can say
+ * more, and (since 1.19) this placement's settings, resolved — every declared
+ * key present, defaults filled, places with their coordinates and zone, a time
+ * format with the owner's Profile applied (`widget-settings.ts`). A widget
+ * placed twice is produced once per placement's settings.
+ */
+export interface WidgetRequest {
+    size: WidgetSize;
+    /** Since 1.19 (`{}` for a widget that declares none); absent on an older buddi, so read it with `?? {}`. */
+    settings?: WidgetSettings;
+}
+export interface WidgetDefinition {
+    /** `<plugin>.<name>`, stable: what the owner's layout remembers. */
+    id: string;
+    /** The frame's title and the gallery's name: "Weather at home". At most `WIDGET_TITLE_MAX`. */
+    title: string;
+    /** The sizes it can be drawn at; the first is where it starts. */
+    sizes: WidgetSize[];
+    /** Seconds between productions; clamped to 60–86400, ten minutes when left out. */
+    refreshSeconds?: number;
+    /** A page of the same plugin the body opens. */
+    link?: {
+        page: string;
+    };
+    /** Hidden on screen until the owner asks, and never on a lock screen: a balance, not the weather. */
+    sensitive?: boolean;
+    /**
+     * What the owner can set per placement (since 1.19): at most eight fields
+     * from a fixed vocabulary the page draws (`widget-settings.ts`). Each
+     * placement keeps its own; `produce` reads them resolved in `settings`.
+     */
+    settings?: WidgetSettingField[];
+    /** The body for now, or null when there is nothing to show. Read-only. */
+    produce(ctx: ToolContext, request: WidgetRequest): Promise<WidgetBody | null>;
+}
+/** A widget, the plugin that contributed it, and its refresh made concrete. */
+export interface RegisteredWidget extends Omit<WidgetDefinition, 'produce'> {
+    plugin: string;
+    refreshSeconds: number;
+    produce(ctx: CoreToolContext, request: WidgetRequest): Promise<WidgetBody | null>;
+    /** A select's or multiselect's choices, read through the plugin's host when they are not fixed. */
+    options?(key: string, ctx: CoreToolContext): Promise<WidgetSettingOption[]>;
+}
+/**
+ * Check a manifest's widgets at register, the way pages and metrics are
+ * checked: a bad declaration is a startup error naming the plugin, not an
+ * empty frame on a Tuesday. Returns them with the refresh made concrete.
+ */
+export declare function parseWidgets(plugin: string, widgets: unknown, opts: {
+    pages: readonly string[];
+    taken: (id: string) => boolean;
+}): Array<Omit<RegisteredWidget, 'produce'> & {
+    produce: WidgetDefinition['produce'];
+}>;
+/** A line cut to `max` characters with an ellipsis; nothing for a blank or a non-string. */
+export declare function cutLine(value: unknown, max: number): string | undefined;
+/**
+ * A plugin's body, as the page may draw it, or a reason it cannot be drawn.
+ * Lines are cut to size, lists to their count, numbers checked; a body with
+ * no figure, no rows or an unknown kind is refused rather than drawn wrong.
+ */
+export declare function widgetBodyOf(raw: unknown): {
+    ok: true;
+    body: WidgetBody;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * An older plugin's glance card, as a stat body: the same figure, line,
+ * sparkline and foot. How a glance that still sends `card` keeps its card
+ * now that Home draws cards as widgets.
+ */
+export declare function statOfGlanceCard(card: HomeGlanceCard | undefined, icon: string): WidgetStat | undefined;
+//# sourceMappingURL=widgets.d.ts.map

package/packages/core/dist/widgets.d.ts.map

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

package/packages/core/dist/widgets.js

@@ -0,0 +1,247 @@
+import { parseWidgetSettings } from './widget-settings.js';
+import { TILE_ICONS } from './views.js';
+import { HOME_CARD_LINE_MAX, HOME_CARD_TREND_MAX, HOME_CARD_VALUE_MAX } from './home.js';
+/** Small takes one column of Home's grid, medium two. One row height for both. */
+export const WIDGET_SIZES = ['small', 'medium'];
+/** The vocabulary. A new kind is a host API minor and a renderer in the page. */
+export const WIDGET_BODY_KINDS = ['stat', 'list', 'strip', 'progress', 'text', 'clocks'];
+/** How often a widget is produced again, at most and at least, and by default. */
+export const WIDGET_REFRESH_MIN_S = 60;
+export const WIDGET_REFRESH_MAX_S = 86_400;
+export const WIDGET_REFRESH_DEFAULT_S = 600;
+/** Lengths past which text is cut with an ellipsis, and how many of a thing are kept. */
+export const WIDGET_TITLE_MAX = 40;
+export const WIDGET_VALUE_MAX = HOME_CARD_VALUE_MAX;
+export const WIDGET_LINE_MAX = HOME_CARD_LINE_MAX;
+export const WIDGET_TEXT_MAX = 160;
+export const WIDGET_TREND_MAX = HOME_CARD_TREND_MAX;
+export const WIDGET_ROWS_MAX = 3;
+export const WIDGET_ITEMS_MAX = 8;
+/** Faces a clocks body keeps: medium draws four, small two. */
+export const WIDGET_CLOCKS_MAX = 4;
+/** A face's label is short: it sits under a face a quarter of a medium widget wide. */
+export const WIDGET_CLOCK_LABEL_MAX = 24;
+/** Where a placement sits: Home's grid, or the lock screen's compact row. */
+export const WIDGET_SURFACES = ['home', 'lock'];
+const WIDGET_NAME = /^[a-z][a-z0-9_]*$/;
+/**
+ * Check a manifest's widgets at register, the way pages and metrics are
+ * checked: a bad declaration is a startup error naming the plugin, not an
+ * empty frame on a Tuesday. Returns them with the refresh made concrete.
+ */
+export function parseWidgets(plugin, widgets, opts) {
+    const fail = (message) => {
+        throw new Error(`plugin ${plugin}: ${message}`);
+    };
+    if (!Array.isArray(widgets))
+        fail('widgets must be an array');
+    const seen = new Set();
+    return widgets.map((raw, index) => {
+        if (!raw || typeof raw !== 'object')
+            return fail(`widgets[${index}] is not an object`);
+        const w = raw;
+        const id = typeof w.id === 'string' ? w.id : '';
+        const [owner, name, ...rest] = id.split('.');
+        if (owner !== plugin || !name || rest.length > 0 || !WIDGET_NAME.test(name)) {
+            fail(`widget ${JSON.stringify(w.id)} must be named ${plugin}.<name> (lowercase letters, digits, _)`);
+        }
+        if (seen.has(id) || opts.taken(id))
+            fail(`widget ${id} is declared twice`);
+        seen.add(id);
+        const title = typeof w.title === 'string' ? w.title.trim() : '';
+        if (title === '' || title.length > WIDGET_TITLE_MAX)
+            fail(`widget ${id} needs a title of 1 to ${WIDGET_TITLE_MAX} characters`);
+        const sizes = w.sizes;
+        if (!Array.isArray(sizes) || sizes.length === 0 || new Set(sizes).size !== sizes.length ||
+            !sizes.every((s) => WIDGET_SIZES.includes(s))) {
+            fail(`widget ${id}: sizes must list ${WIDGET_SIZES.join(' and/or ')}, each once`);
+        }
+        if (typeof w.produce !== 'function')
+            fail(`widget ${id} needs a produce function`);
+        const refresh = w.refreshSeconds;
+        if (refresh !== undefined && (typeof refresh !== 'number' || !Number.isFinite(refresh))) {
+            fail(`widget ${id}: refreshSeconds must be a number`);
+        }
+        const link = w.link;
+        if (link !== undefined && (typeof link?.page !== 'string' || !opts.pages.includes(link.page))) {
+            fail(`widget ${id} links to ${JSON.stringify(link?.page)}, which is not a page of this plugin`);
+        }
+        if (w.sensitive !== undefined && typeof w.sensitive !== 'boolean')
+            fail(`widget ${id}: sensitive must be true or false`);
+        const settings = parseWidgetSettings(plugin, id, w.settings);
+        return {
+            id,
+            plugin,
+            title,
+            sizes: sizes,
+            refreshSeconds: Math.min(WIDGET_REFRESH_MAX_S, Math.max(WIDGET_REFRESH_MIN_S, Math.round(refresh ?? WIDGET_REFRESH_DEFAULT_S))),
+            ...(link ? { link: { page: link.page } } : {}),
+            ...(w.sensitive === true ? { sensitive: true } : {}),
+            ...(settings ? { settings } : {}),
+            produce: w.produce,
+        };
+    });
+}
+/* ------------------------------------------------------------------ *
+ * Bodies, as the page may draw them
+ * ------------------------------------------------------------------ */
+const ICONS = new Set(TILE_ICONS);
+/** A line cut to `max` characters with an ellipsis; nothing for a blank or a non-string. */
+export function cutLine(value, max) {
+    if (typeof value !== 'string' || value.trim() === '')
+        return undefined;
+    const text = value.trim().replace(/\s+/g, ' ');
+    return text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
+}
+/** A glyph from the pinned set; one outside it is left off rather than guessed at. */
+function iconOf(value) {
+    return typeof value === 'string' && ICONS.has(value) ? { icon: value } : {};
+}
+function opt(key, value) {
+    return value === undefined ? {} : { [key]: value };
+}
+/** An IANA zone this runtime knows ("Europe/Paris"); offsets like "+02:00" are refused, they ignore summer time. */
+function isZone(value) {
+    if (typeof value !== 'string' || !/^[A-Za-z][A-Za-z0-9_+\-]*(\/[A-Za-z0-9_+\-]+)*$/.test(value))
+        return false;
+    try {
+        new Intl.DateTimeFormat('en-US', { timeZone: value });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const TONES_ROW = new Set(['good', 'critical']);
+const TONES_BAR = new Set(['accent', 'good', 'warning', 'critical']);
+/**
+ * A plugin's body, as the page may draw it, or a reason it cannot be drawn.
+ * Lines are cut to size, lists to their count, numbers checked; a body with
+ * no figure, no rows or an unknown kind is refused rather than drawn wrong.
+ */
+export function widgetBodyOf(raw) {
+    if (!raw || typeof raw !== 'object')
+        return { ok: false, reason: 'the widget answered something that is not a body' };
+    const b = raw;
+    switch (b.kind) {
+        case 'stat': {
+            const value = cutLine(b.value, WIDGET_VALUE_MAX);
+            if (!value)
+                return { ok: false, reason: 'a stat needs a value' };
+            const t = b.trend;
+            const points = t && Array.isArray(t.points)
+                ? t.points.slice(0, WIDGET_TREND_MAX).filter((n) => typeof n === 'number' && Number.isFinite(n))
+                : [];
+            const label = t ? cutLine(t.label, WIDGET_LINE_MAX) : undefined;
+            return {
+                ok: true,
+                body: {
+                    kind: 'stat', ...iconOf(b.icon), value,
+                    ...opt('caption', cutLine(b.caption, WIDGET_LINE_MAX)),
+                    ...(points.length >= 2 ? { trend: { ...opt('label', label), points } } : {}),
+                    ...opt('foot', cutLine(b.foot, WIDGET_LINE_MAX)),
+                },
+            };
+        }
+        case 'list': {
+            const rows = (Array.isArray(b.rows) ? b.rows : [])
+                .map((r) => {
+                if (!r || typeof r !== 'object')
+                    return null;
+                const row = r;
+                const title = cutLine(row.title, WIDGET_LINE_MAX);
+                if (!title)
+                    return null;
+                return {
+                    title,
+                    ...opt('sub', cutLine(row.sub, WIDGET_LINE_MAX)),
+                    ...opt('side', cutLine(row.side, WIDGET_VALUE_MAX)),
+                    ...(typeof row.tone === 'string' && TONES_ROW.has(row.tone) ? { tone: row.tone } : {}),
+                };
+            })
+                .filter((r) => r !== null)
+                .slice(0, WIDGET_ROWS_MAX);
+            if (rows.length === 0)
+                return { ok: false, reason: 'a list needs at least one row with a title' };
+            return { ok: true, body: { kind: 'list', rows, ...opt('more', cutLine(b.more, WIDGET_LINE_MAX)) } };
+        }
+        case 'strip': {
+            const items = (Array.isArray(b.items) ? b.items : [])
+                .map((i) => {
+                if (!i || typeof i !== 'object')
+                    return null;
+                const item = i;
+                const label = cutLine(item.label, WIDGET_VALUE_MAX);
+                const value = cutLine(item.value, WIDGET_VALUE_MAX);
+                return label && value ? { label, ...iconOf(item.icon), value } : null;
+            })
+                .filter((i) => i !== null)
+                .slice(0, WIDGET_ITEMS_MAX);
+            if (items.length === 0)
+                return { ok: false, reason: 'a strip needs at least one tile with a label and a value' };
+            return {
+                ok: true,
+                body: {
+                    kind: 'strip', ...iconOf(b.icon),
+                    ...opt('value', cutLine(b.value, WIDGET_VALUE_MAX)),
+                    ...opt('caption', cutLine(b.caption, WIDGET_LINE_MAX)),
+                    items,
+                },
+            };
+        }
+        case 'progress': {
+            const value = cutLine(b.value, WIDGET_VALUE_MAX);
+            if (!value)
+                return { ok: false, reason: 'a progress needs a value' };
+            if (typeof b.ratio !== 'number' || !Number.isFinite(b.ratio))
+                return { ok: false, reason: 'a progress needs a ratio between 0 and 1' };
+            return {
+                ok: true,
+                body: {
+                    kind: 'progress', value,
+                    ...opt('caption', cutLine(b.caption, WIDGET_LINE_MAX)),
+                    ratio: Math.min(1, Math.max(0, b.ratio)),
+                    ...opt('foot', cutLine(b.foot, WIDGET_LINE_MAX)),
+                    ...(typeof b.tone === 'string' && TONES_BAR.has(b.tone) ? { tone: b.tone } : {}),
+                },
+            };
+        }
+        case 'text': {
+            const text = cutLine(b.text, WIDGET_TEXT_MAX);
+            if (!text)
+                return { ok: false, reason: 'a text needs text' };
+            return { ok: true, body: { kind: 'text', ...iconOf(b.icon), text, ...opt('sub', cutLine(b.sub, WIDGET_LINE_MAX)) } };
+        }
+        case 'clocks': {
+            if (!isZone(b.home))
+                return { ok: false, reason: 'clocks need home, the owner\'s zone as an IANA name' };
+            const clocks = (Array.isArray(b.clocks) ? b.clocks : [])
+                .map((c) => {
+                if (!c || typeof c !== 'object')
+                    return null;
+                const face = c;
+                const label = cutLine(face.label, WIDGET_CLOCK_LABEL_MAX);
+                return label && isZone(face.zone) ? { label, zone: face.zone } : null;
+            })
+                .filter((c) => c !== null)
+                .slice(0, WIDGET_CLOCKS_MAX);
+            if (clocks.length === 0)
+                return { ok: false, reason: 'clocks need at least one face with a label and an IANA zone' };
+            return { ok: true, body: { kind: 'clocks', home: b.home, clocks, ...(b.time === '12h' || b.time === '24h' ? { time: b.time } : {}) } };
+        }
+        default:
+            return { ok: false, reason: `the page draws ${WIDGET_BODY_KINDS.join(', ')}, not ${JSON.stringify(b.kind)}` };
+    }
+}
+/**
+ * An older plugin's glance card, as a stat body: the same figure, line,
+ * sparkline and foot. How a glance that still sends `card` keeps its card
+ * now that Home draws cards as widgets.
+ */
+export function statOfGlanceCard(card, icon) {
+    if (!card)
+        return undefined;
+    const checked = widgetBodyOf({ kind: 'stat', icon, ...card });
+    return checked.ok && checked.body.kind === 'stat' ? checked.body : undefined;
+}
+//# sourceMappingURL=widgets.js.map

package/packages/core/dist/widgets.js.map

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

package/packages/core/migrations/059_dashboard_lock.sql

@@ -0,0 +1,33 @@
+-- The dashboard's lock screen (docs/dashboard.md, "Lock screen").
+--
+-- A privacy screen over a signed-in session, opened with a PIN. The PIN's
+-- hash and its tries live in core.web_settings under `lock.pin`, the delay
+-- and the background under `lock` (packages/core/src/lock.ts); what is per
+-- session lives on the session row:
+--
+-- locked_at:   when this session locked; null while it is open. A locked
+--              session's API calls are answered 423 except the lock screen's
+--              own (packages/gateway/src/web/lock.ts).
+-- lock_reason: why: `owner` (Lock now), `idle` (nobody used it for the
+--              delay), `start` (a session that began while a PIN was set).
+-- active_at:   when the owner last used this session, as the page reports
+--              it. The server locks a session idle past the delay whether or
+--              not the page says so.
+-- client:      `browser`, or `mcp` for buddi's own command-line clients
+--              (`buddi mcp`, `buddi connections`), which a lock never covers.
+alter table core.dashboard_sessions
+  add column if not exists locked_at timestamptz,
+  add column if not exists lock_reason text check (lock_reason in ('owner', 'idle', 'start')),
+  add column if not exists active_at timestamptz,
+  add column if not exists client text not null default 'browser' check (client in ('browser', 'mcp'));
+
+-- The owner's picture behind the lock screen: one JPEG this server encoded,
+-- at most 2560 pixels on its long side. One row or none.
+create table if not exists core.lock_background (
+  id smallint primary key default 1 check (id = 1),
+  jpeg bytea not null,
+  sha256 text not null,
+  width integer not null,
+  height integer not null,
+  updated_at timestamptz not null default now()
+);

package/packages/core/migrations/060_owner_places.sql

@@ -0,0 +1,30 @@
+-- The owner's places (docs/dashboard.md, Settings → Profile; docs/plugins.md
+-- §9b, owner.places).
+--
+-- Home, Work and any other place the owner names, beside the timezone: a
+-- label, the address as they typed it, what the geocoder matched it to (a
+-- town, with its region and country), coordinates and the place's own zone.
+-- Plugins that declare `owner:places` read them through ctx.buddi; nothing
+-- here is written by a plugin.
+create table if not exists core.owner_places (
+  id text primary key,
+  label text not null check (length(label) between 1 and 40),
+  address text check (address is null or length(address) <= 200),
+  place_name text not null,
+  latitude double precision not null check (latitude between -90 and 90),
+  longitude double precision not null check (longitude between -180 and 180),
+  timezone text,
+  position integer not null default 0,
+  created_at timestamptz not null default now(),
+  updated_at timestamptz not null default now()
+);
+create unique index if not exists owner_places_label on core.owner_places (lower(label));
+
+-- Places brought in once from somewhere they used to live (the weather
+-- plugin's Home and Work). One row per source: present means done, so a place
+-- the owner removes afterwards is not brought back at the next start.
+create table if not exists core.owner_place_imports (
+  source text primary key,
+  imported integer not null default 0,
+  at timestamptz not null default now()
+);

package/packages/core/migrations/061_owner_formats.sql

@@ -0,0 +1,10 @@
+-- How the owner reads times and dates (docs/dashboard.md, Settings → Profile).
+--
+-- time_format: `12h` (2:05 PM) or `24h` (14:05); null is Auto, the browser's
+--              own locale.
+-- date_format: `short` (Thu, Oct 1), `long` (Thursday, 1 October) or `iso`
+--              (2026-10-01); null is Auto.
+-- Every date and time the dashboard draws goes through one formatter that
+-- reads these, and every agent is told them beside the timezone.
+alter table core.owner add column if not exists time_format text check (time_format in ('12h', '24h'));
+alter table core.owner add column if not exists date_format text check (date_format in ('short', 'long', 'iso'));

package/packages/core/migrations/062_group_deleted.sql

@@ -0,0 +1,7 @@
+-- Deleting a group, with a short way back (docs/groups.md, "Deleting a group").
+--
+-- A delete marks the row first: the group leaves every list at once and can
+-- be restored for a minute. After that the gateway removes it for good — its
+-- conversations, their messages and requests, its members, and what the room
+-- remembered. The agents themselves are never touched.
+alter table core.groups add column if not exists deleted_at timestamptz null;

package/packages/core/migrations/063_provider_account_limits.sql

@@ -0,0 +1,20 @@
+-- A model account a provider has rate-limited (docs/providers.md, "Rate limits").
+--
+-- One row per account while a limit stands: a spent daily quota (scope 'day',
+-- until the provider's reset) or a burst window a provider named (scope
+-- 'burst'). Calls to an account under a daily limit are refused here instead
+-- of hammering the provider; the row goes when the window passes, when a call
+-- succeeds, or when the account is edited. Never a key, never a body: the
+-- facts are the ones the owner reads ("Gemini's free tier allows 20 requests
+-- a day").
+create table if not exists core.provider_account_limits (
+  account_id text primary key references core.provider_accounts(id) on delete cascade,
+  scope text not null check (scope in ('day', 'burst')),
+  until timestamptz not null,
+  quota integer null,
+  unit text null check (unit is null or unit in ('requests', 'tokens')),
+  free_tier boolean not null default false,
+  provider text null,
+  model text null,
+  recorded_at timestamptz not null default now()
+);

package/packages/core/migrations/064_mission_coalesce.sql

@@ -0,0 +1,12 @@
+-- Coalescing a mission's event-driven runs (docs/architecture.md, "Sentinels").
+--
+-- A mission that opts in gathers the occurrences enqueued for the same agent
+-- within a short window into one run carrying all of them: the first one
+-- waits `coalesce_window_seconds` for company, each arrival pushes the run
+-- back by the window again, and none waits longer than
+-- `coalesce_max_wait_seconds` after the first. Null is the default: one run
+-- per occurrence, as before.
+alter table core.missions add column if not exists coalesce_window_seconds integer null
+  check (coalesce_window_seconds is null or coalesce_window_seconds between 1 and 3600);
+alter table core.missions add column if not exists coalesce_max_wait_seconds integer null
+  check (coalesce_max_wait_seconds is null or coalesce_max_wait_seconds between 1 and 86400);

package/packages/core/migrations/065_api_tokens.sql

@@ -0,0 +1,28 @@
+-- Owner API tokens (docs/api.md, "Authentication").
+--
+-- A token lets a script or another program call the dashboard's HTTP API as
+-- the owner, with `Authorization: Bearer <token>`, without a browser session.
+-- Made and revoked from Settings → API tokens or `buddi api-token`.
+--
+-- token_hash: sha256 of the token, hex. The token itself is shown once, when
+--             it is made, and never stored: a copy of this table cannot be
+--             replayed. Tokens are 32 random bytes, so a plain digest is
+--             enough; there is nothing to brute-force.
+-- hint:       the token's last four characters, so the owner can tell two
+--             apart in a list. Not enough to guess the rest.
+-- scope:      what it may do. Only 'owner' exists: the owner, minus what
+--             api-routes.ts refuses a token (deciding approvals, grants,
+--             installing code, access and secrets).
+-- created_via: where it was made.
+-- last_used_at: written at most once a minute.
+-- A revoked token's row is deleted.
+create table if not exists core.api_tokens (
+  id uuid primary key,
+  name text not null check (char_length(name) between 1 and 60),
+  token_hash text not null unique check (token_hash ~ '^[0-9a-f]{64}$'),
+  hint text not null check (char_length(hint) = 4),
+  scope text not null default 'owner' check (scope in ('owner')),
+  created_via text not null check (created_via in ('dashboard', 'cli')),
+  created_at timestamptz not null,
+  last_used_at timestamptz
+);