@koalaauto/agentchannel 0.0.0-stage → 3.0.0

package/dist/src/attachments.js

@@ -0,0 +1,227 @@
+import { createWriteStream, mkdirSync, openAsBlob, realpathSync, statSync } from 'node:fs';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+/** What the hub accepts (it re-checks the type from the file content). */
+export const ATTACH_TYPES = {
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    webp: 'image/webp',
+    gif: 'image/gif',
+    mp4: 'video/mp4',
+    webm: 'video/webm',
+    mov: 'video/quicktime',
+    // §17: text and code (≤ 2 MB each, previewed as escaped text) and .html reports
+    // (previewed only in a sandboxed iframe; downloaded as text/plain).
+    txt: 'text/plain',
+    md: 'text/markdown',
+    json: 'application/json',
+    ts: 'text/plain',
+    js: 'text/plain',
+    py: 'text/plain',
+    go: 'text/plain',
+    sh: 'text/plain',
+    diff: 'text/plain',
+    patch: 'text/plain',
+    log: 'text/plain',
+    csv: 'text/csv',
+    yaml: 'text/plain',
+    yml: 'text/plain',
+    sql: 'text/plain',
+    html: 'text/html',
+    htm: 'text/html',
+};
+export const TEXT_MAX_BYTES = 2 * 1024 * 1024;
+const MEDIA_EXT = new Set(['png', 'jpg', 'jpeg', 'webp', 'gif', 'mp4', 'webm', 'mov']);
+export const MAX_ATTACHMENTS = 10;
+/** An `--attach`/`--attach-url` entry that references an object by URL instead of uploading it. */
+export function isLinkRef(p) {
+    return /^https:\/\//i.test(p);
+}
+/** A link reference for `attachment_refs` ({url, name}); throws AttachError on anything but a plain https URL. */
+export function linkRef(p) {
+    let u;
+    try {
+        u = new URL(p);
+    }
+    catch {
+        throw new AttachError(`attachment link ${p} is not a URL`);
+    }
+    if (u.protocol !== 'https:' || u.username || u.password)
+        throw new AttachError(`attachment link ${p}: only https URLs without credentials`);
+    const seg = u.pathname.split('/').pop() || u.hostname;
+    let name = seg;
+    try {
+        name = decodeURIComponent(seg);
+    }
+    catch {
+        /* keep raw */
+    }
+    return { url: p, name };
+}
+export class AttachError extends Error {
+}
+const SAFE_NAME = /^[A-Za-z0-9._-]{1,255}$/;
+export function typeOf(path) {
+    const m = /\.([A-Za-z0-9]+)$/.exec(path);
+    return (m && ATTACH_TYPES[m[1].toLowerCase()]) || '';
+}
+/**
+ * Resolve `--attach` paths. Inside a spawned agent (run token) every file must
+ * resolve through realpath inside the working directory, like `--result-file`
+ * (S2): an agent cannot upload ~/.config/agentchannel/config.json as a "frame".
+ */
+export function resolveAttachments(paths, io) {
+    const list = (paths ?? []).filter((p) => typeof p === 'string' && p.length);
+    if (!list.length)
+        return [];
+    if (list.length > MAX_ATTACHMENTS)
+        throw new AttachError(`at most ${MAX_ATTACHMENTS} attachments`);
+    const cwd = io.cwd ?? process.cwd();
+    return list.map((p) => {
+        // §20 v1.1: an https URL is a reference (R2/S3/OSS/TOS presigned or public); nothing is read or uploaded
+        if (isLinkRef(p))
+            return linkRef(p).url;
+        let real;
+        try {
+            real = realpathSync(resolve(cwd, p));
+        }
+        catch {
+            throw new AttachError(`cannot read attachment ${p}`);
+        }
+        if (io.env.ACH_RUN_TOKEN) {
+            const rel = relative(realpathSync(cwd), real);
+            if (rel.startsWith('..') || isAbsolute(rel)) {
+                throw new AttachError(`refusing to attach ${p}: inside a spawned agent, files must be inside the working directory`);
+            }
+        }
+        if (!statSync(real).isFile())
+            throw new AttachError(`attachment ${p} is not a file`);
+        if (!typeOf(real))
+            throw new AttachError(`attachment ${p}: only ${Object.keys(ATTACH_TYPES).join(', ')} files are accepted`);
+        const ext = (/\.([A-Za-z0-9]+)$/.exec(real)?.[1] ?? '').toLowerCase();
+        if (!MEDIA_EXT.has(ext) && statSync(real).size > TEXT_MAX_BYTES)
+            throw new AttachError(`attachment ${p}: text files are limited to 2 MB`);
+        return real;
+    });
+}
+/** Multipart body: the JSON body in field "json", files in "attachments". */
+export async function attachmentForm(json, files) {
+    const fd = new FormData();
+    fd.append('json', JSON.stringify(json ?? {}));
+    for (const f of files) {
+        const blob = await openAsBlob(f, { type: typeOf(f) || 'application/octet-stream' });
+        fd.append('attachments', blob, basename(f));
+    }
+    return fd;
+}
+const UPLOAD_URL = /^\/api\/ach\/uploads\/[a-z0-9]{15}\/raw$/;
+export function attachmentsOf(v) {
+    if (!Array.isArray(v))
+        return [];
+    return v.filter((a) => {
+        if (!a || typeof a.url !== 'string' || typeof a.name !== 'string')
+            return false;
+        if (a.ref === 'link')
+            return /^https:\/\//i.test(a.url);
+        if (a.ref === 'upload')
+            return UPLOAD_URL.test(a.url);
+        return SAFE_NAME.test(a.name);
+    });
+}
+/** A path-safe local file name for an attachment (references keep their upload id as prefix). */
+export function localName(a) {
+    if (!a.ref)
+        return a.name;
+    const safe = String(a.original || a.name).replace(/[^A-Za-z0-9._-]+/g, '_').replace(/^[._-]+/, '').slice(0, 120) || 'file';
+    return a.ref === 'upload' && a.upload ? `${a.upload}_${safe}` : safe;
+}
+function author(m) {
+    if (m.author_type === 'human')
+        return `human ${String(m.author_name ?? '')}`.trim();
+    if (m.author_type === 'system')
+        return 'system';
+    return `agent ${String(m.author_name ?? m.author_agent ?? '?')}`;
+}
+/** Every attachment on a task: current handoff first, then messages (oldest first). */
+export function taskFiles(bundle) {
+    const out = [];
+    const seen = new Set();
+    const add = (a, from) => {
+        if (seen.has(a.url))
+            return;
+        seen.add(a.url);
+        out.push({ ...a, from });
+    };
+    const v = bundle.task.handoff_version ?? 1;
+    for (const a of attachmentsOf(bundle.handoffAttachments))
+        add(a, `handoff v${v}`);
+    for (const h of bundle.history)
+        for (const a of attachmentsOf(h.attachments))
+            add(a, `handoff v${h.version}`);
+    for (const m of bundle.messages)
+        for (const a of attachmentsOf(m.attachments))
+            add(a, `${m.kind} ${m.id} by ${author(m)}`);
+    return out;
+}
+/** Download to `dir/<stored name>` (stored names are unique and path-safe). Skips files already there with the same size. */
+export async function downloadFile(fetchFn, url, headers, dir, a) {
+    if (a.ref === 'link')
+        throw new AttachError(`${a.original || a.name} is a link (${a.url}), not stored on the hub`);
+    const name = localName(a);
+    if (!SAFE_NAME.test(name))
+        throw new AttachError(`unsafe file name ${name}`);
+    mkdirSync(dir, { recursive: true });
+    const dest = join(dir, name);
+    try {
+        if (a.size && statSync(dest).size === a.size)
+            return dest;
+    }
+    catch {
+        /* not there yet */
+    }
+    let res = await fetchFn(url, { method: 'GET', headers, ...(a.ref === 'upload' ? { redirect: 'manual' } : {}) });
+    // direct uploads: the hub answers with a presigned bucket URL; fetch it without our credentials
+    if (a.ref === 'upload' && res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+        res = await fetchFn(String(res.headers.get('location')), { method: 'GET' });
+    }
+    if (!res.ok || !res.body)
+        throw new AttachError(`download ${a.original || a.name}: ${res.status} ${res.statusText}`);
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(dest, { mode: 0o600 }));
+    return dest;
+}
+export function humanSize(n) {
+    if (!n)
+        return '?';
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    if (n < 1024 ** 3)
+        return `${(n / 1048576).toFixed(1)} MB`;
+    return `${(n / 1024 ** 3).toFixed(2)} GB`;
+}
+/** The upload target for a hub route: task:<id>, post:<id>, channel:<name>, or new_task (POST /tasks). */
+export function uploadTarget(path) {
+    const p = path.replace(/^https?:\/\/[^/]+/, '').replace(/^\/api\/ach/, '').split('?')[0];
+    let m = /^\/tasks\/([^/]+)\/[a-z-]+$/.exec(p);
+    if (m)
+        return `task:${decodeURIComponent(m[1])}`;
+    if (p === '/tasks')
+        return 'new_task';
+    m = /^\/posts\/([^/]+)\/replies$/.exec(p);
+    if (m)
+        return `post:${decodeURIComponent(m[1])}`;
+    m = /^\/channels\/([^/]+)\/posts$/.exec(p);
+    if (m)
+        return `channel:${decodeURIComponent(m[1])}`;
+    return null;
+}
+/** Files that should go straight to the bucket: media over the hub's threshold. */
+export function bigFiles(files, cfg) {
+    if (!cfg || !cfg.direct_upload)
+        return [];
+    const min = cfg.direct_threshold_mb * 1048576;
+    return files.filter((f) => !isLinkRef(f) && MEDIA_EXT.has((/\.([A-Za-z0-9]+)$/.exec(f)?.[1] ?? '').toLowerCase()) && statSync(f).size > min);
+}

package/dist/src/attention.d.ts

@@ -0,0 +1,85 @@
+export type Request = (method: string, path: string) => Promise<any>;
+/** Kinds in notice order. */
+export declare const ATTENTION_KINDS: readonly ["question", "decision", "mention", "reply", "task", "item"];
+export type AttentionKind = (typeof ATTENTION_KINDS)[number];
+export interface Attention {
+    total: number;
+    counts: Partial<Record<AttentionKind, number>>;
+    /** Stable ids of the items (what was already noticed is never noticed again). */
+    ids: string[];
+}
+/** A hub item type / notification event -> a notice kind. Pure. */
+export declare function attentionKind(type: unknown): AttentionKind;
+/**
+ * Normalizes what the hub says needs the owner. Accepts GET /me/attention
+ * (`{needs_reply_count, by_kind: {decision, question, mention, reply}}`, or a
+ * list `{items:[{id,type}]}`) and, as a fallback,
+ * GET /me/notifications?all=1 (rows with reply_needed / needs_me). Pure.
+ */
+export declare function normalizeAttention(r: any, fromNotifications?: boolean): Attention;
+/** What needs the owner now (agent key: the owner's view). */
+export declare function fetchAttention(request: Request): Promise<Attention>;
+/** The one line. Counts only, never content. Pure. */
+export declare function noticeText(a: Attention, lang?: 'en' | 'zh'): string;
+export declare const NOTICE_GAP_MS: number;
+export interface AttentionNotifierOptions {
+    fetch: () => Promise<Attention>;
+    /** Shows the line; resolves false when it could not (unsupported: stays silent). */
+    deliver: (text: string) => Promise<boolean>;
+    lang?: 'en' | 'zh';
+    gapMs?: number;
+    now?: () => number;
+    log?: (s: string) => void;
+}
+export declare class AttentionNotifier {
+    private o;
+    private noticed;
+    private lastCounts;
+    private lastAt;
+    private timer;
+    private busy;
+    readonly sent: string[];
+    constructor(o: AttentionNotifierOptions);
+    private now;
+    /** Something changed: notice new items now, or once at the end of the rate window. */
+    check(): Promise<string | null>;
+    private run;
+    stop(): void;
+}
+export interface ChangeFeedOptions {
+    request: Request;
+    onChange: () => unknown;
+    /** Long-poll wait (s), ≤ 25. */
+    waitS?: number;
+    /** Fallback polling interval. */
+    pollMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    log?: (s: string) => void;
+}
+/**
+ * Follows GET /api/ach/changes (long poll). Falls back to polling (onChange
+ * every pollMs) when the hub refuses the route (403/404: an older hub, or
+ * person sessions only) — permanently — or after an error (one interval, then
+ * the long poll again).
+ */
+export declare class ChangeFeed {
+    private o;
+    mode: 'longpoll' | 'poll';
+    private stopped;
+    private cursor;
+    constructor(o: ChangeFeedOptions);
+    stop(): void;
+    private fire;
+    /** Runs until stop(). `rounds` bounds the loop (tests). */
+    run(rounds?: number): Promise<void>;
+}
+export type Exec = (cmd: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const defaultExec: Exec;
+/** The Codex session this `ach mcp` runs in, when known (env set by Codex, or ACH_CODEX_THREAD_ID). */
+export declare function codexThreadId(env: NodeJS.ProcessEnv): string | undefined;
+/** `codex queue --thread <id> --message <notice>`: the notice as a queued message in that session. */
+export declare function codexQueue(text: string, env: NodeJS.ProcessEnv, exec?: Exec): Promise<boolean>;

package/dist/src/attention.js

@@ -0,0 +1,262 @@
+/**
+ * Reminders, never content. Two pieces shared by `ach mcp` (an open Claude
+ * Code / Codex session) and `ach run --notify` (the background helper):
+ *
+ * - ChangeFeed: follows the hub's change stream. GET /api/ach/changes long-poll
+ *   (wait ≈ 25 s); when the hub refuses it (older hub: person sessions only) or
+ *   it errors, falls back to polling every 15 s.
+ * - AttentionNotifier: on a change, counts what needs the owner (questions,
+ *   decisions, mentions...) and, when something new arrived, delivers ONE line
+ *   ("AgentChannel: 2 items need you (1 question, 1 decision) — say 'check my
+ *   inbox'"). At most one notice per 10 minutes; changes inside the window are
+ *   coalesced into one notice at its end. Message bodies are never fetched or
+ *   sent here: content comes only when the person asks (the inbox tools).
+ */
+import { execFile } from 'node:child_process';
+import { HubError } from './client.js';
+/** Kinds in notice order. */
+export const ATTENTION_KINDS = ['question', 'decision', 'mention', 'reply', 'task', 'item'];
+/** A hub item type / notification event -> a notice kind. Pure. */
+export function attentionKind(type) {
+    const t = String(type ?? '').toLowerCase();
+    if (/decision/.test(t))
+        return 'decision';
+    if (/question|escalat|ask|memory_held/.test(t))
+        return 'question';
+    if (/mention|assigned/.test(t))
+        return 'mention';
+    if (/repl|change_request|changes_requested/.test(t))
+        return 'reply';
+    if (/task/.test(t))
+        return 'task';
+    return 'item';
+}
+/**
+ * Normalizes what the hub says needs the owner. Accepts GET /me/attention
+ * (`{needs_reply_count, by_kind: {decision, question, mention, reply}}`, or a
+ * list `{items:[{id,type}]}`) and, as a fallback,
+ * GET /me/notifications?all=1 (rows with reply_needed / needs_me). Pure.
+ */
+export function normalizeAttention(r, fromNotifications = false) {
+    const counts = {};
+    const ids = [];
+    let items = Array.isArray(r?.items) ? r.items : Array.isArray(r) ? r : [];
+    if (fromNotifications)
+        items = items.filter((x) => x && (x.reply_needed || x.pending));
+    else
+        items = items.filter((x) => x && x.pending !== false);
+    for (const x of items) {
+        const k = attentionKind(x.type ?? x.kind ?? x.event);
+        counts[k] = (counts[k] ?? 0) + 1;
+        ids.push(String(x.id ?? x.event_id ?? x.message_id ?? `${k}:${ids.length}`));
+    }
+    const byKind = r?.by_kind ?? r?.counts;
+    if (!items.length && byKind && typeof byKind === 'object') {
+        // GET /me/attention: counts only (no ids); "new" = a count went up (AttentionNotifier)
+        for (const [key, n] of Object.entries(byKind)) {
+            const c = Number(n);
+            if (!(c > 0))
+                continue;
+            const k = attentionKind(key);
+            counts[k] = (counts[k] ?? 0) + c;
+        }
+    }
+    const total = Object.values(counts).reduce((a, b) => a + (b ?? 0), 0);
+    return { total, counts, ids };
+}
+/** What needs the owner now (agent key: the owner's view). */
+export async function fetchAttention(request) {
+    try {
+        return normalizeAttention(await request('GET', '/api/ach/me/attention'));
+    }
+    catch (e) {
+        if (!(e instanceof HubError) || (e.status !== 404 && e.status !== 403 && e.status !== 405))
+            throw e;
+    }
+    return normalizeAttention(await request('GET', '/api/ach/me/notifications?all=1&limit=100'), true);
+}
+const EN = {
+    question: ['question', 'questions'],
+    decision: ['decision', 'decisions'],
+    mention: ['mention', 'mentions'],
+    reply: ['reply', 'replies'],
+    task: ['task', 'tasks'],
+    item: ['other', 'other'],
+};
+const ZH = { question: '个问题', decision: '个决定', mention: '次提及', reply: '条回复', task: '个任务', item: '项其他' };
+/** The one line. Counts only, never content. Pure. */
+export function noticeText(a, lang = 'en') {
+    const parts = ATTENTION_KINDS.filter((k) => (a.counts[k] ?? 0) > 0).map((k) => {
+        const n = a.counts[k];
+        return lang === 'zh' ? `${n} ${ZH[k]}` : `${n} ${EN[k][n === 1 ? 0 : 1]}`;
+    });
+    if (lang === 'zh')
+        return `AgentChannel：有 ${a.total} 件事等你处理（${parts.join('，')}）— 说「查看我的收件箱」`;
+    return `AgentChannel: ${a.total} ${a.total === 1 ? 'item needs' : 'items need'} you (${parts.join(', ')}) — say 'check my inbox'`;
+}
+export const NOTICE_GAP_MS = 10 * 60_000;
+export class AttentionNotifier {
+    o;
+    noticed = new Set();
+    lastCounts = {};
+    lastAt = -Infinity;
+    timer = null;
+    busy = null;
+    sent = [];
+    constructor(o) {
+        this.o = o;
+    }
+    now() {
+        return (this.o.now ?? Date.now)();
+    }
+    /** Something changed: notice new items now, or once at the end of the rate window. */
+    check() {
+        if (this.busy)
+            return this.busy;
+        this.busy = this.run().finally(() => {
+            this.busy = null;
+        });
+        return this.busy;
+    }
+    async run() {
+        let a;
+        try {
+            a = await this.o.fetch();
+        }
+        catch (e) {
+            this.o.log?.(`notice: ${String(e?.message ?? e).slice(0, 200)}`);
+            return null;
+        }
+        // items that went away may come back as new ones later: keep only current ids
+        const freshIds = a.ids.filter((id) => !this.noticed.has(id));
+        const rose = ATTENTION_KINDS.some((k) => (a.counts[k] ?? 0) > (this.lastCounts[k] ?? 0));
+        if (a.total <= 0 || (!freshIds.length && !(a.ids.length === 0 && rose))) {
+            // fewer items now: a later increase is new again
+            this.lastCounts = { ...a.counts };
+            return null;
+        }
+        const wait = this.lastAt + (this.o.gapMs ?? NOTICE_GAP_MS) - this.now();
+        if (wait > 0) {
+            // coalesce: one check when the window ends
+            if (!this.timer) {
+                this.timer = setTimeout(() => {
+                    this.timer = null;
+                    void this.check();
+                }, wait);
+                this.timer.unref?.();
+            }
+            return null;
+        }
+        const text = noticeText(a, this.o.lang ?? 'en');
+        this.lastAt = this.now();
+        for (const id of a.ids)
+            this.noticed.add(id);
+        this.lastCounts = { ...a.counts };
+        let ok = false;
+        try {
+            ok = await this.o.deliver(text);
+        }
+        catch {
+            ok = false;
+        }
+        if (ok)
+            this.sent.push(text);
+        return ok ? text : null;
+    }
+    stop() {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = null;
+    }
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms).unref?.());
+/**
+ * Follows GET /api/ach/changes (long poll). Falls back to polling (onChange
+ * every pollMs) when the hub refuses the route (403/404: an older hub, or
+ * person sessions only) — permanently — or after an error (one interval, then
+ * the long poll again).
+ */
+export class ChangeFeed {
+    o;
+    mode = 'longpoll';
+    stopped = false;
+    cursor = '';
+    constructor(o) {
+        this.o = o;
+    }
+    stop() {
+        this.stopped = true;
+    }
+    async fire() {
+        try {
+            await this.o.onChange();
+        }
+        catch {
+            /* the consumer logs its own errors */
+        }
+    }
+    /** Runs until stop(). `rounds` bounds the loop (tests). */
+    async run(rounds = Infinity) {
+        const sleep = this.o.sleep ?? realSleep;
+        const poll = this.o.pollMs ?? 15_000;
+        const wait = Math.min(25, this.o.waitS ?? 25);
+        let errors = 0;
+        for (let i = 0; i < rounds && !this.stopped; i++) {
+            if (this.mode === 'poll') {
+                await this.fire();
+                await sleep(poll);
+                continue;
+            }
+            const t0 = Date.now();
+            try {
+                const q = new URLSearchParams({ wait: String(wait) });
+                if (this.cursor)
+                    q.set('since', this.cursor);
+                const r = await this.o.request('GET', `/api/ach/changes?${q}`);
+                errors = 0;
+                const first = !this.cursor;
+                if (r?.cursor)
+                    this.cursor = String(r.cursor);
+                if (r?.changed || first)
+                    await this.fire();
+                // a hub that ignores `wait` must not be hammered
+                if (Date.now() - t0 < 1000)
+                    await sleep(1000);
+            }
+            catch (e) {
+                if (e instanceof HubError && (e.status === 403 || e.status === 404 || e.status === 405)) {
+                    this.mode = 'poll';
+                    this.o.log?.(`change stream not available (${e.status}); polling every ${Math.round(poll / 1000)} s`);
+                    continue;
+                }
+                if (e instanceof HubError && e.status === 401) {
+                    this.o.log?.('change stream: key refused (401); stopping');
+                    return;
+                }
+                errors++;
+                if (errors === 1)
+                    this.o.log?.(`change stream: ${String(e?.message ?? e).slice(0, 200)}; retrying`);
+                await this.fire();
+                await sleep(poll);
+            }
+        }
+    }
+}
+export const defaultExec = (cmd, args) => new Promise((resolve) => {
+    execFile(cmd, args, { timeout: 15_000 }, (err, stdout, stderr) => {
+        resolve({ code: err ? (typeof err.code === 'number' ? err.code : 127) : 0, stdout: String(stdout ?? ''), stderr: String(stderr ?? '') });
+    });
+});
+/** The Codex session this `ach mcp` runs in, when known (env set by Codex, or ACH_CODEX_THREAD_ID). */
+export function codexThreadId(env) {
+    const v = env.ACH_CODEX_THREAD_ID || env.CODEX_THREAD_ID || env.CODEX_SESSION_ID;
+    return v && /^[A-Za-z0-9_.:-]{1,200}$/.test(v) ? v : undefined;
+}
+/** `codex queue --thread <id> --message <notice>`: the notice as a queued message in that session. */
+export async function codexQueue(text, env, exec = defaultExec) {
+    const thread = codexThreadId(env);
+    if (!thread)
+        return false;
+    const r = await exec(env.ACH_CODEX_BIN || 'codex', ['queue', '--thread', thread, '--message', text]);
+    return r.code === 0;
+}

package/dist/src/avatars.d.ts

@@ -0,0 +1,40 @@
+import type { Client, FetchLike } from './client.js';
+import type { Exec } from './import.js';
+/**
+ * Feishu avatars are fetched on the admin's machine (lark-cli is logged in
+ * there, the hub is not) and uploaded to the hub, which caches them; the panel
+ * only ever loads avatars from the hub. GitHub and Gravatar are fetched by the
+ * hub itself (POST /api/ach/admin/avatars/refresh, and weekly).
+ */
+export declare const AVATAR_MAX_BYTES: number;
+export declare const AVATAR_SOURCES: string[];
+/** png | jpeg | gif | webp from the first bytes, else '' (never SVG). */
+export declare function imageKind(b: Uint8Array): string;
+/** The best avatar URL in a Feishu user object (search or contact result). */
+export declare function feishuAvatarUrl(u: any): string;
+/** Look a person up in Feishu by email (or open_id) with lark-cli; returns the avatar URL or ''. */
+export declare function feishuAvatarFor(exec: Exec, p: {
+    email?: string;
+    feishu_open_id?: string;
+    name?: string;
+}): Promise<string>;
+/** Download an image (<= 200 KB, PNG/JPEG/GIF/WebP). */
+export declare function downloadImage(url: string, fetchFn: FetchLike): Promise<{
+    bytes: Uint8Array;
+    ext: string;
+}>;
+/**
+ * Upload Feishu avatars for these people (hub ids). Returns how many were
+ * uploaded; problems are logged, never fatal (an avatar is cosmetic).
+ */
+export declare function syncFeishuAvatars(admin: Client, people: {
+    id: string;
+    name?: string;
+    email?: string;
+    feishu_open_id?: string;
+}[], o: {
+    exec: Exec;
+    fetch?: FetchLike;
+    log: (s: string) => void;
+}): Promise<number>;
+export declare function parsePriority(s: string): string[];