sideby 0.16.0 → 0.17.0

package/dist/src/panel/page-logic.d.ts

@@ -77,6 +77,15 @@ export declare function attentionReasons(a: LogicAccount, health: {
     fail: number;
     warn: number;
 } | null, now: number, warn: number): string[];
+/**
+ * The one status badge an account row shows after its name (spec §3.27), most important first: `health-fail`
+ * (needs fixing), `quota-high` (running low), the other attention labels (`signed-out`, `not-installed`,
+ * `health-warn`), then `next` (recommended) and last `api`. Null when none applies. `reasons` are attentionReasons'.
+ */
+export declare function rowBadge(reasons: string[], opts: {
+    next?: boolean;
+    api?: boolean;
+}): string | null;
 /**
  * The most serious reason an Account needs a look, as a message key and its values for the Panel to show where the
  * attention count is: `why.<reason>`; for `quota-high` the fullest live window at or over `warn`, with its label and
@@ -177,6 +186,24 @@ export declare function panelHint(hint: string, fixable: boolean, action: string
  * Whether the Panel fixes Finding `f` with a button of its own: a sideby skill behind this version while the
  * Update plan says sideby may update it (`skillUpdatable`). Such Findings stay out of the prompt for an AI agent.
  */
+/**
+ * A Local Build the Panel can leave for npm itself (ADR-0024): the global `sideby` still runs it and the Panel may
+ * write. Then switching to the release is the update, offered as a button instead of the `pnpm local --off` command.
+ */
+export declare function canLeaveLocal(u: {
+    localSwitch?: {
+        running: string | null;
+    };
+} | null, readOnly: boolean): boolean;
+/**
+ * What a failed Local Build switch request means (ADR-0024): a lost connection (a background Panel restarting) or a
+ * Portal's 5xx (it moved to the new code mid-request) may follow a switch that happened, so the state decides;
+ * anything else is the server saying it did not switch.
+ */
+export declare function switchFailure(e: {
+    network?: boolean;
+    status?: number;
+}): 'wait' | 'check' | 'fail';
 export declare function panelFixes(f: {
     code?: string;
 }, skillUpdatable: boolean): boolean;
@@ -284,5 +311,192 @@ export declare function remoteControlSummary(groups: readonly {
 export declare function remoteControlTodo<G extends {
     state: string;
 }>(groups: readonly G[], to: 'on' | 'off'): G[];
+/**
+ * Where a menu or popover goes next to its anchor, all in viewport pixels. It opens below when its whole height fits
+ * there, else above when it fits there, else on the side with more room, its height capped at that room so it scrolls
+ * inside. Below `margin` from each edge and `gap` from the anchor. When neither side has even `min` pixels (a tiny
+ * window, an anchor near an edge), it takes the whole height of the window instead, over the anchor. Horizontally it
+ * lines up with the anchor's left edge (`start`) or right edge (`end`), kept inside the window.
+ */
+export declare function menuPlacement(anchor: {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}, size: {
+    width: number;
+    height: number;
+}, view: {
+    width: number;
+    height: number;
+}, align: 'start' | 'end', gap?: number, margin?: number, min?: number): {
+    left: number;
+    top: number;
+    maxHeight: number;
+    above: boolean;
+};
 /** The key a Same Login group keeps its folded state under: its members, in a fixed order. */
 export declare function loginKey(refs: readonly string[]): string;
+/**
+ * `text` without key-shaped strings (spec §3.28), each replaced by `[key removed]`. First, anywhere in a word, URLs
+ * and query strings included: a known key prefix (`sk-`, which covers `sk-ant-` and `sk-proj-`, `xai-`, `gsk_`,
+ * `AIza`, `ghp_`, `github_pat_`) followed by 16 or more token characters, an AWS access key id (`AKIA` or `ASIA` and
+ * 16 capitals or digits), and a JWT (three base64url parts joined by dots, the first starting `eyJ`). Then any run of
+ * 32 or more letters, digits, `_`, `-` or `+` that mixes letters and digits, unless the whitespace-free word it sits
+ * in is a URL or a file path (it has a `/`); a 40-character git SHA is such a run. Everything else, whitespace and
+ * newlines included, stays as it was. `removed` says whether anything was taken out, so the caller can point the
+ * user to the key box.
+ */
+export declare function stripSecrets(text: string): {
+    text: string;
+    removed: boolean;
+};
+/** The kinds of AI Task (spec §3.28); anything else is refused. */
+export declare const AI_TASK_KINDS: readonly ['free', 'fix', 'quota', 'account', 'host', 'plugin', 'terminal', 'handoff'];
+export type AiTaskKind = (typeof AI_TASK_KINDS)[number];
+/**
+ * The message keys of the AI dialog for `task` (spec §3.28 "每个入口的提示"): its title, the text box placeholder and
+ * the example chips. Each comes from the task's own key (`ask.title.<task>`, `ask.ph.<task>`, `ask.ex.<task>.1` to
+ * `.3`) when `has` knows it, otherwise from `free`'s: `ask.title`, `ask.ph.free` and `freeChips`.
+ */
+export declare function askCopy(task: string, has: (key: string) => boolean, freeChips: readonly string[]): {
+    title: string;
+    placeholder: string;
+    chips: string[];
+};
+/**
+ * The Task Prompt of an AI Task (spec §3.28), in `lang` (`zh`, otherwise English): what to do, the context given,
+ * the fixed rules, pointers for the task and the invitation to contribute. For `free` the user's `text` is what to
+ * do; for the other tasks it follows the task's own sentence. `text` and every context string go through `strip`
+ * (pass `stripSecrets`), so no key-shaped string reaches the prompt; the caller still checks `text` itself to warn
+ * the user. Context carries only what the caller passes, never a credential value.
+ */
+export declare function taskPrompt(input: {
+    task: string;
+    text?: string;
+    context?: {
+        account?: string;
+        family?: string;
+        findings?: readonly {
+            code?: string;
+            account?: string;
+            item?: string;
+            message: string;
+            hint?: string;
+        }[];
+        quotaReason?: string;
+        version?: string;
+        /** The custom terminal command saved now (`terminal` task). */
+        terminalCustom?: string;
+        /** Names of the supported terminals installed on this computer (`terminal` task). */
+        terminals?: readonly string[];
+        /** Auto Handoff facts, one per line, as `handoffTaskFacts` gives them (`handoff` task). */
+        handoff?: readonly string[];
+    };
+    /** Files saved for the task (spec §3.28 "附件"): absolute paths and their kind. */
+    attachments?: readonly {
+        path: string;
+        kind: string;
+    }[];
+    lang: string;
+}, strip: (text: string) => {
+    text: string;
+    removed: boolean;
+}): string;
+/**
+ * The accounts an AI Task can start (spec §3.28), in the order the dialog lists them: signed-in subscription
+ * accounts first, then API accounts, each by ref. A subscription that is not signed in cannot start one.
+ */
+export declare function aiTaskAccounts<A extends {
+    ref: string;
+    kind?: string;
+    login?: string;
+}>(accounts: readonly A[]): A[];
+/**
+ * Whether a quota cell offers "Ask AI why" (spec §3.28): it shows no data or an error the user cannot fix with a
+ * button of its own. Quota that is off (it has its own switch), an API account and a Family without a public source
+ * do not.
+ */
+export declare function quotaAskable(reason: string | undefined): boolean;
+/** A file size for an attachment tile (spec §3.28 "附件"): KB below 1 MB, MB with one decimal from there. */
+export declare function fileSize(bytes: number): string;
+/** Findings as an AI Task's context carries them: only the fields a Task Prompt shows. */
+export declare function taskFindings(findings: readonly {
+    code?: string;
+    account?: string;
+    item?: string;
+    message: string;
+    hint?: string;
+}[]): {
+    code?: string;
+    account?: string;
+    item?: string;
+    message: string;
+    hint?: string;
+}[];
+/**
+ * The theme and language the Panel shows (spec §3.29). A Panel that can write takes them from config `panel`; a
+ * read-only one from what this browser saved. `language` is empty for the browser's own language.
+ */
+export declare function panelPrefs(config: {
+    theme?: string;
+    language?: string;
+}, local: {
+    theme: string;
+    lang: string;
+}, fromConfig: boolean): {
+    theme: string;
+    language: string;
+};
+/**
+ * What this browser's own choice adds to config `panel` the first time this version opens (spec §3.29): only keys
+ * config does not have yet, and only a choice the person made, not a default. Null when nothing is to be written.
+ */
+export declare function panelMigration(config: {
+    theme?: string;
+    language?: string;
+}, local: {
+    theme: string;
+    lang: string;
+}): {
+    theme?: string;
+    language?: string;
+} | null;
+/**
+ * The line under the start-at-login switch (spec §3.29) as a message key, whether it is on, whether the switch can
+ * be moved, and the action beside it: `fix` turns it on again so it starts this sideby. Read-only: no switch, no action.
+ */
+export declare function autostartNote(s: {
+    supported: boolean;
+    state: string;
+    current: boolean;
+} | null, readOnly: boolean): {
+    key: string;
+    on: boolean;
+    toggle: boolean;
+    action: 'fix' | null;
+};
+/**
+ * The facts an Auto Handoff AI Task carries (spec §3.29), one per line, named as `sideby handoff status --json`
+ * names them: the settings, the order per Family, and where each account's quota comes from. Account refs only,
+ * never an email. `status` is the readiness, when the page has it.
+ */
+export declare function handoffTaskFacts(settings: {
+    auto: boolean;
+    sameFamily: boolean;
+    threshold: number;
+    prepareAt: number;
+    waitIfResetWithinMinutes?: number;
+    countdownSeconds?: number;
+    families?: Record<string, {
+        policy: string;
+        order: readonly string[];
+    }>;
+}, starters: readonly string[], accounts: readonly LogicAccount[], now: number, status?: {
+    families?: readonly {
+        family: string;
+        ready: boolean;
+        problems: readonly string[];
+    }[];
+    nextSteps?: readonly string[];
+} | null): string[];

package/dist/src/panel/page-logic.js

@@ -87,6 +87,21 @@ export function attentionReasons(a, health, now, warn) {
         out.push('health-warn');
     return out;
 }
+/**
+ * The one status badge an account row shows after its name (spec §3.27), most important first: `health-fail`
+ * (needs fixing), `quota-high` (running low), the other attention labels (`signed-out`, `not-installed`,
+ * `health-warn`), then `next` (recommended) and last `api`. Null when none applies. `reasons` are attentionReasons'.
+ */
+export function rowBadge(reasons, opts) {
+    for (const r of ['health-fail', 'quota-high', 'signed-out', 'not-installed', 'health-warn'])
+        if (reasons.includes(r))
+            return r;
+    if (opts.next)
+        return 'next';
+    if (opts.api)
+        return 'api';
+    return null;
+}
 /**
  * The most serious reason an Account needs a look, as a message key and its values for the Panel to show where the
  * attention count is: `why.<reason>`; for `quota-high` the fullest live window at or over `warn`, with its label and
@@ -361,6 +376,23 @@ export function panelHint(hint, fixable, action) {
  * Whether the Panel fixes Finding `f` with a button of its own: a sideby skill behind this version while the
  * Update plan says sideby may update it (`skillUpdatable`). Such Findings stay out of the prompt for an AI agent.
  */
+/**
+ * A Local Build the Panel can leave for npm itself (ADR-0024): the global `sideby` still runs it and the Panel may
+ * write. Then switching to the release is the update, offered as a button instead of the `pnpm local --off` command.
+ */
+export function canLeaveLocal(u, readOnly) {
+    return !readOnly && !!u?.localSwitch && u.localSwitch.running === 'local';
+}
+/**
+ * What a failed Local Build switch request means (ADR-0024): a lost connection (a background Panel restarting) or a
+ * Portal's 5xx (it moved to the new code mid-request) may follow a switch that happened, so the state decides;
+ * anything else is the server saying it did not switch.
+ */
+export function switchFailure(e) {
+    if (e.network)
+        return 'wait';
+    return (e.status ?? 0) >= 500 ? 'check' : 'fail';
+}
 export function panelFixes(f, skillUpdatable) {
     return skillUpdatable && f.code === 'skill.outdated';
 }
@@ -525,7 +557,369 @@ export function remoteControlSummary(groups, apiRefs) {
 export function remoteControlTodo(groups, to) {
     return groups.filter((g) => g.state === 'default' || g.state === (to === 'on' ? 'off' : 'on'));
 }
+/**
+ * Where a menu or popover goes next to its anchor, all in viewport pixels. It opens below when its whole height fits
+ * there, else above when it fits there, else on the side with more room, its height capped at that room so it scrolls
+ * inside. Below `margin` from each edge and `gap` from the anchor. When neither side has even `min` pixels (a tiny
+ * window, an anchor near an edge), it takes the whole height of the window instead, over the anchor. Horizontally it
+ * lines up with the anchor's left edge (`start`) or right edge (`end`), kept inside the window.
+ */
+export function menuPlacement(anchor, size, view, align, gap = 4, margin = 8, min = 120) {
+    const x = align === 'start' ? anchor.left : anchor.right - size.width;
+    const left = Math.max(margin, Math.min(view.width - size.width - margin, x));
+    const below = Math.floor(view.height - margin - anchor.bottom - gap);
+    const above = Math.floor(anchor.top - gap - margin);
+    if (size.height <= below)
+        return { left, top: anchor.bottom + gap, maxHeight: below, above: false };
+    if (size.height <= above)
+        return { left, top: anchor.top - gap - size.height, maxHeight: above, above: true };
+    if (Math.max(below, above) < Math.min(size.height, min)) {
+        return { left, top: margin, maxHeight: Math.max(0, Math.floor(view.height - 2 * margin)), above: false };
+    }
+    if (below >= above)
+        return { left, top: anchor.bottom + gap, maxHeight: below, above: false };
+    return { left, top: margin, maxHeight: above, above: true };
+}
 /** The key a Same Login group keeps its folded state under: its members, in a fixed order. */
 export function loginKey(refs) {
     return `login:${[...refs].sort().join(',')}`;
 }
+/**
+ * `text` without key-shaped strings (spec §3.28), each replaced by `[key removed]`. First, anywhere in a word, URLs
+ * and query strings included: a known key prefix (`sk-`, which covers `sk-ant-` and `sk-proj-`, `xai-`, `gsk_`,
+ * `AIza`, `ghp_`, `github_pat_`) followed by 16 or more token characters, an AWS access key id (`AKIA` or `ASIA` and
+ * 16 capitals or digits), and a JWT (three base64url parts joined by dots, the first starting `eyJ`). Then any run of
+ * 32 or more letters, digits, `_`, `-` or `+` that mixes letters and digits, unless the whitespace-free word it sits
+ * in is a URL or a file path (it has a `/`); a 40-character git SHA is such a run. Everything else, whitespace and
+ * newlines included, stays as it was. `removed` says whether anything was taken out, so the caller can point the
+ * user to the key box.
+ */
+export function stripSecrets(text) {
+    const mark = '[key removed]';
+    let removed = false;
+    const out = String(text || '').replace(/\S+/g, (word) => {
+        let w = word.replace(/(?<![A-Za-z0-9_-])(?:(?:sk-proj-|sk-|xai-|gsk_|AIza|ghp_|github_pat_)[A-Za-z0-9_-]{16,}|(?:AKIA|ASIA)[0-9A-Z]{16}(?![A-Za-z0-9])|eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*)/g, () => {
+            removed = true;
+            return mark;
+        });
+        if (w.includes('/'))
+            return w;
+        w = w.replace(/[A-Za-z0-9_+-]{32,}=*/g, (run) => {
+            if (!/[A-Za-z]/.test(run) || !/[0-9]/.test(run))
+                return run;
+            removed = true;
+            return mark;
+        });
+        return w;
+    });
+    return { text: out, removed };
+}
+/** The kinds of AI Task (spec §3.28); anything else is refused. */
+export const AI_TASK_KINDS = [
+    'free',
+    'fix',
+    'quota',
+    'account',
+    'host',
+    'plugin',
+    'terminal',
+    'handoff',
+];
+/**
+ * The message keys of the AI dialog for `task` (spec §3.28 "每个入口的提示"): its title, the text box placeholder and
+ * the example chips. Each comes from the task's own key (`ask.title.<task>`, `ask.ph.<task>`, `ask.ex.<task>.1` to
+ * `.3`) when `has` knows it, otherwise from `free`'s: `ask.title`, `ask.ph.free` and `freeChips`.
+ */
+export function askCopy(task, has, freeChips) {
+    const own = task !== 'free';
+    const title = own && has('ask.title.' + task) ? 'ask.title.' + task : 'ask.title';
+    const placeholder = own && has('ask.ph.' + task) ? 'ask.ph.' + task : 'ask.ph.free';
+    const chips = own ? [1, 2, 3].map((n) => 'ask.ex.' + task + '.' + n).filter(has) : [];
+    return { title, placeholder, chips: chips.length ? chips : freeChips.slice() };
+}
+/**
+ * The Task Prompt of an AI Task (spec §3.28), in `lang` (`zh`, otherwise English): what to do, the context given,
+ * the fixed rules, pointers for the task and the invitation to contribute. For `free` the user's `text` is what to
+ * do; for the other tasks it follows the task's own sentence. `text` and every context string go through `strip`
+ * (pass `stripSecrets`), so no key-shaped string reaches the prompt; the caller still checks `text` itself to warn
+ * the user. Context carries only what the caller passes, never a credential value.
+ */
+export function taskPrompt(input, strip) {
+    const zh = input.lang === 'zh';
+    const clean = (s) => strip(String(s || '')).text.trim();
+    const c = input.context || {};
+    const text = clean(input.text);
+    const account = clean(c.account);
+    const family = clean(c.family);
+    const L = zh
+        ? {
+            task: '要做的事',
+            context: '上下文',
+            rules: '规则',
+            pointers: '提示',
+            says: '我的原话：',
+            free: '问我想用 sideby 做什么，然后帮我做。',
+            fix: 'sideby 的体检发现了下面这些不能自动修复的问题，请帮我修好。',
+            quota: '额度格没有显示' + (account ? ' ' + account + ' 的' : '') + '额度，请找出原因并让它显示出来。',
+            account: '帮我在 sideby 里加一个' +
+                (family ? ' ' + family + ' ' : '') +
+                '账号（订阅账号，或者用 API 地址的账号）。',
+            host: '帮我给 sideby 加一个它还不支持的 AI 编程工具（宿主），先做成本机的 Family 插件。',
+            plugin: '帮我写一个 sideby 插件或 hook。',
+            terminal: '帮我让 sideby 能在我用的终端里打开 AI 任务：写一条自定义终端命令。',
+            handoff: '帮我调好 sideby 的自动接力：根据我的账号推荐什么时候接力（阈值）和接力的顺序。',
+            cHandoff: '自动接力现在的设置（来自 `sideby handoff status --json`）：',
+            pHandoff: '先运行 `sideby handoff status --json` 和 `sideby quota --json`，看清每个账号的额度来源和用量。只用 `sideby handoff enable …` 或 `sideby config set handoff.<键> <值>` 改设置；先不加 `--yes` 给我看预览，我同意后再加 `--yes`。没有额度数据的账号排在顺序后面，并告诉我怎么让它显示额度。',
+            cAccount: '账号：',
+            cFamily: '家族：',
+            cFindings: '体检发现：',
+            cQuota: '额度原因：',
+            cVersion: 'sideby 版本：',
+            cCustom: '现在的自定义终端命令：',
+            cTerminals: '本机装了的、sideby 支持的终端：',
+            cNoTerminals: '本机没找到 sideby 支持的终端',
+            cLang: '面板语言：中文（请用中文和我交流）',
+            r1: '先用 sideby skill，怎么做见它的 references/ai-tasks.md。没装 skill 就先问我，我同意后运行 `npx skills add Adonis0123/sideby -g`。',
+            r2: '会改文件的命令先给我看预览，我同意后才加 `--yes`。',
+            r3: '不要替我登录，也不要让我把密钥发给你：密钥由我自己用 `sideby key <账号>` 输入。',
+            pFix: '先运行 `sideby doctor --json` 看清问题；能自动修的交给 `sideby doctor --fix`。修完再跑一次 `sideby doctor`，告诉我还剩什么。',
+            pQuota: '用 `sideby quota --json` 和 `sideby doctor --json` 看原因。',
+            pAccount: '地址、模型名、环境变量以厂商的官方文档为准。账号建好后，让我用 `sideby key <账号>` 输入密钥，再用 `sideby try <账号>` 试一次。订阅账号要登录时，让我点面板上的「登录」，或者自己运行 `sideby login <账号>`。',
+            pHost: '用 `sideby plugins new <id>` 生成插件骨架；收集事实时写明宿主的版本和日期；用 `sideby plugins check <id>` 检查，并在演示 HOME 里试一遍。',
+            pPlugin: '照 sideby 仓库的插件指南 docs/guide/plugins.zh-CN.md 写；写完用 `sideby plugins check <id>` 检查。',
+            pTerminal: "先问我用的是什么终端。只看这个终端的官方文档和它的 `--help`，找出「在指定目录新开一个窗口运行一条命令」的写法，写明你看的版本。写成一个模板：`{cmd}` 是要运行的命令，`{cwd}` 是文件夹，sideby 按参数填入，不经过 shell。保存要用 `sideby terminal --custom '<模板>'`，它会改 sideby 的设置，先问我。保存后让我在面板上点一次「让 AI 帮我」试一下，打不开就一起看错误再改。",
+            attached: '附件',
+            image: '图片',
+            video: '视频',
+            videoHint: '需要看视频内容时，用 ffmpeg 抽几帧再看，例如 `ffmpeg -i <视频> -vf fps=1 -frames:v 5 frame-%d.png`。',
+            share: '做好之后，问我愿不愿意把这次的改进分享给 sideby。我同意后，按 sideby 仓库的 CONTRIBUTING.md 提一个 pull request，提交前去掉我自己的账号名、路径和邮箱。',
+            shareTerminal: '跑通之后，问我愿不愿意把这个终端做成 sideby 的内置终端。我同意后，在 sideby 仓库 src/core/terminal.ts 的终端表里加一行并补上测试，按 CONTRIBUTING.md 提一个 pull request，提交前去掉我自己的账号名、路径和邮箱。',
+        }
+        : {
+            task: 'What to do',
+            context: 'Context',
+            rules: 'Rules',
+            pointers: 'Pointers',
+            says: 'In my words: ',
+            free: 'Ask me what I want to do with sideby, then do it for me.',
+            fix: "Fix the problems below that sideby's health check cannot fix by itself.",
+            quota: 'sideby shows no quota' + (account ? ' for ' + account : '') + '. Find out why and make it show.',
+            account: 'Help me add a ' +
+                (family ? family + ' ' : '') +
+                'account to sideby (a subscription, or an API address).',
+            host: 'Help me add an AI coding tool (Host) that sideby does not support yet, first as a local Family Plugin.',
+            plugin: 'Help me write a sideby plugin or hook.',
+            terminal: 'Help sideby open AI Tasks in the terminal I use: write a custom terminal command.',
+            handoff: "Help me tune sideby's Auto Handoff: from my accounts, recommend when to hand over (the threshold) and in what order.",
+            cHandoff: 'Auto Handoff now (from `sideby handoff status --json`):',
+            pHandoff: 'Run `sideby handoff status --json` and `sideby quota --json` first to see where each account gets its quota and how much is used. Change settings only with `sideby handoff enable …` or `sideby config set handoff.<key> <value>`; show me the preview without `--yes` first, and add `--yes` only after I agree. Put accounts without quota data last in the order, and tell me how to make them show it.',
+            cAccount: 'Account: ',
+            cFamily: 'Family: ',
+            cFindings: 'Health check findings:',
+            cQuota: 'Quota reason: ',
+            cVersion: 'sideby version: ',
+            cCustom: 'Custom terminal command now: ',
+            cTerminals: 'Supported terminals installed here: ',
+            cNoTerminals: 'No supported terminal is installed here',
+            cLang: 'Panel language: English (talk to me in English)',
+            r1: 'Use the sideby skill; its references/ai-tasks.md says how. If the skill is not installed, ask me first, and with my yes run `npx skills add Adonis0123/sideby -g`.',
+            r2: 'Show me the preview of any command that changes files; add `--yes` only after I agree.',
+            r3: 'Never sign in for me and never ask me to send you an API key: I enter keys myself with `sideby key <account>`.',
+            pFix: 'Run `sideby doctor --json` first; `sideby doctor --fix` fixes what it can by itself. When you are done, run `sideby doctor` and tell me what is left.',
+            pQuota: 'Use `sideby quota --json` and `sideby doctor --json` to see why.',
+            pAccount: "Take addresses, model names and variables from the vendor's official docs. When the account exists, have me enter the key with `sideby key <account>`, then try it with `sideby try <account>`. For a subscription sign-in, have me click Sign in in the Panel or run `sideby login <account>` myself.",
+            pHost: 'Start with `sideby plugins new <id>`; note the Host version and the date with every fact you gather; check it with `sideby plugins check <id>` and try it in a demo HOME.',
+            pPlugin: 'Follow the plugins guide in the sideby repository (docs/guide/plugins.md); check it with `sideby plugins check <id>`.',
+            pTerminal: "Ask me which terminal I use first. Read only that terminal's official docs and its `--help` to find how it opens a new window that runs one command in a given folder, and note the version you read. Write it as a template: `{cmd}` is the command and `{cwd}` the folder; sideby fills them in as separate arguments, no shell runs it. Save it with `sideby terminal --custom '<template>'`, which changes sideby's settings, so ask me first. Then have me click Let AI do it in the Panel once to try it; if it does not open, look at the error with me and fix the template.",
+            attached: 'Attached files',
+            image: 'image',
+            video: 'video',
+            videoHint: 'To see what a video shows, extract a few frames with ffmpeg first, for example `ffmpeg -i <video> -vf fps=1 -frames:v 5 frame-%d.png`.',
+            share: 'When it works, ask me whether to share the improvement with sideby. Only with my yes, follow the CONTRIBUTING.md of the sideby repository to open a pull request, and first remove my own account names, paths and emails.',
+            shareTerminal: 'When it works, ask me whether to make this terminal built into sideby. Only with my yes, add a row to the terminal table in src/core/terminal.ts of the sideby repository with tests, follow its CONTRIBUTING.md to open a pull request, and first remove my own account names, paths and emails.',
+        };
+    const task = AI_TASK_KINDS.indexOf(input.task) >= 0 ? input.task : 'free';
+    const sentence = L[task] || L.free;
+    const what = task === 'free' ? text || sentence : text ? sentence + '\n' + L.says + text : sentence;
+    const facts = [];
+    if (account)
+        facts.push('- ' + L.cAccount + account);
+    if (family)
+        facts.push('- ' + L.cFamily + family);
+    const findings = c.findings || [];
+    if (findings.length) {
+        facts.push('- ' + L.cFindings);
+        findings.forEach((f, i) => {
+            const where = [clean(f.account), clean(f.item)].filter(Boolean).join(' · ');
+            const code = clean(f.code);
+            facts.push('  ' +
+                (i + 1) +
+                '. ' +
+                (code ? '[' + code + '] ' : '') +
+                (where ? where + ': ' : '') +
+                clean(f.message));
+            const hint = clean(f.hint);
+            if (hint)
+                facts.push('     ' + hint);
+        });
+    }
+    const reason = clean(c.quotaReason);
+    if (reason)
+        facts.push('- ' + L.cQuota + reason);
+    if (task === 'terminal') {
+        const custom = clean(c.terminalCustom);
+        if (custom)
+            facts.push('- ' + L.cCustom + custom);
+        const terms = (c.terminals || []).map(clean).filter(Boolean);
+        facts.push('- ' + (terms.length ? L.cTerminals + terms.join(', ') : L.cNoTerminals));
+    }
+    if (task === 'handoff') {
+        const lines = (c.handoff || []).map(clean).filter(Boolean);
+        if (lines.length)
+            facts.push('- ' + L.cHandoff, ...lines.map((l) => '  - ' + l));
+    }
+    const version = clean(c.version);
+    if (version)
+        facts.push('- ' + L.cVersion + version);
+    facts.push('- ' + L.cLang);
+    const pointer = L['p' + task.charAt(0).toUpperCase() + task.slice(1)];
+    const parts = [L.task + '\n' + what, L.context + '\n' + facts.join('\n')];
+    const files = input.attachments || [];
+    if (files.length) {
+        const lines = files.map((f) => '- ' + f.path + ' (' + (f.kind === 'video' ? L.video : L.image) + ')');
+        if (files.some((f) => f.kind === 'video'))
+            lines.push(L.videoHint);
+        parts.push(L.attached + '\n' + lines.join('\n'));
+    }
+    parts.push(L.rules + '\n- ' + L.r1 + '\n- ' + L.r2 + '\n- ' + L.r3);
+    if (pointer)
+        parts.push(L.pointers + '\n' + pointer);
+    parts.push(task === 'terminal' ? L.shareTerminal : L.share);
+    return parts.join('\n\n');
+}
+/**
+ * The accounts an AI Task can start (spec §3.28), in the order the dialog lists them: signed-in subscription
+ * accounts first, then API accounts, each by ref. A subscription that is not signed in cannot start one.
+ */
+export function aiTaskAccounts(accounts) {
+    const by = (x, y) => (x.ref < y.ref ? -1 : x.ref > y.ref ? 1 : 0);
+    const subs = accounts.filter((a) => a.kind !== 'api' && a.login === 'logged-in').sort(by);
+    const apis = accounts.filter((a) => a.kind === 'api').sort(by);
+    return subs.concat(apis);
+}
+/**
+ * Whether a quota cell offers "Ask AI why" (spec §3.28): it shows no data or an error the user cannot fix with a
+ * button of its own. Quota that is off (it has its own switch), an API account and a Family without a public source
+ * do not.
+ */
+export function quotaAskable(reason) {
+    if (!reason)
+        return false;
+    return ['not-enabled', 'api-account', 'no-source'].indexOf(reason) < 0;
+}
+/** A file size for an attachment tile (spec §3.28 "附件"): KB below 1 MB, MB with one decimal from there. */
+export function fileSize(bytes) {
+    if (bytes < 1024 * 1024)
+        return Math.max(1, Math.round(bytes / 1024)) + ' KB';
+    const mb = bytes / (1024 * 1024);
+    return (mb < 10 ? Math.round(mb * 10) / 10 : Math.round(mb)) + ' MB';
+}
+/** Findings as an AI Task's context carries them: only the fields a Task Prompt shows. */
+export function taskFindings(findings) {
+    return findings.map((f) => {
+        const out = {
+            message: String(f.message),
+        };
+        if (f.code)
+            out.code = f.code;
+        if (f.account)
+            out.account = f.account;
+        if (f.item)
+            out.item = f.item;
+        if (f.hint)
+            out.hint = f.hint;
+        return out;
+    });
+}
+/**
+ * The theme and language the Panel shows (spec §3.29). A Panel that can write takes them from config `panel`; a
+ * read-only one from what this browser saved. `language` is empty for the browser's own language.
+ */
+export function panelPrefs(config, local, fromConfig) {
+    if (!fromConfig)
+        return { theme: local.theme, language: local.lang };
+    const theme = config.theme === 'light' || config.theme === 'dark' ? config.theme : 'system';
+    const language = config.language === 'en' || config.language === 'zh' ? config.language : '';
+    return { theme, language };
+}
+/**
+ * What this browser's own choice adds to config `panel` the first time this version opens (spec §3.29): only keys
+ * config does not have yet, and only a choice the person made, not a default. Null when nothing is to be written.
+ */
+export function panelMigration(config, local) {
+    const patch = {};
+    if (config.theme === undefined && (local.theme === 'light' || local.theme === 'dark'))
+        patch.theme = local.theme;
+    if (config.language === undefined && (local.lang === 'en' || local.lang === 'zh'))
+        patch.language = local.lang;
+    return patch.theme || patch.language ? patch : null;
+}
+/**
+ * The line under the start-at-login switch (spec §3.29) as a message key, whether it is on, whether the switch can
+ * be moved, and the action beside it: `fix` turns it on again so it starts this sideby. Read-only: no switch, no action.
+ */
+export function autostartNote(s, readOnly) {
+    if (!s)
+        return { key: 'as.checking', on: false, toggle: false, action: null };
+    if (!s.supported)
+        return { key: 'as.unsupported', on: false, toggle: false, action: null };
+    if (s.state === 'foreign')
+        return { key: 'as.foreign', on: false, toggle: false, action: null };
+    const on = s.state === 'on' || s.state === 'stale';
+    const fix = s.state === 'stale' ? 'as.stale' : on && !s.current ? 'as.other' : null;
+    return { key: fix || 'as.hint', on, toggle: !readOnly, action: fix && !readOnly ? 'fix' : null };
+}
+/**
+ * The facts an Auto Handoff AI Task carries (spec §3.29), one per line, named as `sideby handoff status --json`
+ * names them: the settings, the order per Family, and where each account's quota comes from. Account refs only,
+ * never an email. `status` is the readiness, when the page has it.
+ */
+export function handoffTaskFacts(settings, starters, accounts, now, status) {
+    const out = [
+        'auto: ' + settings.auto,
+        'sameFamily: ' + settings.sameFamily,
+        'threshold: ' + settings.threshold,
+        'prepareAt: ' + settings.prepareAt,
+    ];
+    if (settings.waitIfResetWithinMinutes !== undefined)
+        out.push('waitIfResetWithinMinutes: ' + settings.waitIfResetWithinMinutes);
+    if (settings.countdownSeconds !== undefined)
+        out.push('countdownSeconds: ' + settings.countdownSeconds);
+    out.push('families that can start a handoff: ' + (starters.length ? starters.join(', ') : 'none'));
+    const fams = settings.families || {};
+    for (const f of Object.keys(fams).sort()) {
+        const o = fams[f];
+        out.push('order of ' + f + ': ' + o.policy + (o.order.length ? ' [' + o.order.join(', ') + ']' : ''));
+    }
+    for (const a of accounts) {
+        const q = a.quota;
+        let line;
+        if (a.kind === 'api')
+            line = 'API account, no quota';
+        else if (q && q.status === 'ok') {
+            const p = quotaPressure(a, now);
+            line = 'quota from ' + (q.source || 'unknown') + (p >= 0 ? ', ' + Math.round(p) + '% used' : '');
+        }
+        else
+            line = 'no quota data' + (q?.reason ? ' (' + q.reason + ')' : '');
+        if (a.kind !== 'api' && a.login && a.login !== 'logged-in')
+            line += ', ' + a.login;
+        out.push(a.ref + ': ' + line);
+    }
+    for (const f of status?.families || [])
+        if (!f.ready && f.problems.length)
+            out.push('not ready, ' + f.family + ': ' + f.problems.join('; '));
+    if (status?.nextSteps?.length)
+        out.push('next steps: ' + status.nextSteps.join('; '));
+    return out;
+}