@meetquinn/animactl 0.1.1-canary.21.1.cd63d38

package/dist/server/kb/kb.helper.js

@@ -0,0 +1,112 @@
+import { homedir } from 'node:os';
+import { join, posix } from 'node:path';
+import { kbFileExtension } from '../../shared/kb-file-types.js';
+// Error carrying an HTTP status; the API layer translates `statusCode` to the
+// response code.
+export class KbError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+// Text content larger than this is not inlined in the file API; the client
+// falls back to the raw route. Keeps a giant tracked file from bloating a JSON
+// response.
+export const INLINE_TEXT_CAP = 2 * 1024 * 1024;
+// Short cache so an HTML report pulling many relative assets doesn't rescan the
+// KB per asset. Visibility rarely changes within a page load; staleness
+// self-heals on the next tick.
+export const CACHE_TTL_MS = 5_000;
+export const KB_ID = /^[A-Za-z0-9._-]+$/;
+export function normalizeRelPath(raw) {
+    if (!raw || raw.includes('\0') || raw.includes('\\') || raw.startsWith('/')) {
+        throw new KbError(400, 'bad_path');
+    }
+    const normalized = posix.normalize(raw).replace(/^\/+/, '');
+    if (!normalized || normalized === '.' || normalized === '..') {
+        throw new KbError(400, 'bad_path');
+    }
+    if (normalized.startsWith('../') || normalized.includes('/../')) {
+        throw new KbError(400, 'bad_path');
+    }
+    return normalized;
+}
+export function kbView(kb) {
+    return { id: kb.id, label: kb.label };
+}
+export function requiredString(value, field) {
+    if (typeof value !== 'string' || !value.trim()) {
+        throw new KbError(400, `${field} is required`);
+    }
+    return value.trim();
+}
+export function expandHome(path) {
+    if (path === '~')
+        return homedir();
+    return path.startsWith('~/') ? join(homedir(), path.slice(2)) : path;
+}
+// Build a nested dir/file tree from a flat list of repo-relative POSIX paths.
+export function buildTree(paths) {
+    const rootNodes = [];
+    const dirIndex = new Map();
+    dirIndex.set('', rootNodes);
+    for (const filePath of paths.sort()) {
+        const segments = filePath.split('/');
+        let prefix = '';
+        for (let i = 0; i < segments.length; i += 1) {
+            const segment = segments[i];
+            const isLeaf = i === segments.length - 1;
+            const currentPath = prefix ? `${prefix}/${segment}` : segment;
+            const siblings = dirIndex.get(prefix) ?? rootNodes;
+            let node = siblings.find((n) => n.name === segment && n.type === (isLeaf ? 'file' : 'dir'));
+            if (!node) {
+                node = { name: segment, path: currentPath, type: isLeaf ? 'file' : 'dir' };
+                if (!isLeaf)
+                    node.children = [];
+                siblings.push(node);
+                if (!isLeaf)
+                    dirIndex.set(currentPath, node.children);
+            }
+            prefix = currentPath;
+        }
+    }
+    sortTree(rootNodes);
+    return rootNodes;
+}
+export function contentTypeFor(relPath) {
+    return RAW_CONTENT_TYPES[kbFileExtension(relPath)] ?? 'application/octet-stream';
+}
+// Dirs before files, each group alphabetical (case-insensitive).
+function sortTree(nodes) {
+    nodes.sort((a, b) => {
+        if (a.type !== b.type)
+            return a.type === 'dir' ? -1 : 1;
+        return a.name.toLowerCase().localeCompare(b.name.toLowerCase());
+    });
+    for (const node of nodes) {
+        if (node.children)
+            sortTree(node.children);
+    }
+}
+const RAW_CONTENT_TYPES = {
+    html: 'text/html; charset=utf-8',
+    htm: 'text/html; charset=utf-8',
+    css: 'text/css; charset=utf-8',
+    js: 'application/javascript; charset=utf-8',
+    mjs: 'application/javascript; charset=utf-8',
+    json: 'application/json; charset=utf-8',
+    svg: 'image/svg+xml',
+    png: 'image/png',
+    jpg: 'image/jpeg',
+    jpeg: 'image/jpeg',
+    gif: 'image/gif',
+    webp: 'image/webp',
+    ico: 'image/x-icon',
+    bmp: 'image/bmp',
+    avif: 'image/avif',
+    woff2: 'font/woff2',
+    woff: 'font/woff',
+    md: 'text/markdown; charset=utf-8',
+    txt: 'text/plain; charset=utf-8',
+};

package/dist/server/kb/kb.service.d.ts

@@ -0,0 +1,41 @@
+import type { KbCreateRequest, KbFile, KbRenameRequest, KbTree, KbView } from '../../shared/kb.js';
+import { KbRegistryStore, KbStore } from '../storage/schema/kb.store.js';
+import { type KbDirectoryBrowse } from './kb.helper.js';
+export declare class KbRegistryService {
+    private readonly registry;
+    private kbsCache;
+    private readonly services;
+    constructor(registry?: KbRegistryStore);
+    clearCaches(): void;
+    listKbs(): Promise<KbView[]>;
+    browseKbDirectories(rawPath: string | undefined): Promise<KbDirectoryBrowse>;
+    addKb(input: KbCreateRequest): Promise<KbView[]>;
+    ensureDefaultTeamKbForAgentHome(homePath: string): Promise<void>;
+    serviceFor(id: string): KbService;
+    private resolvedKbs;
+}
+export declare class KbService {
+    private readonly id;
+    private readonly store;
+    private readonly onMutation;
+    private visibleFilesCache;
+    constructor(id: string, store?: KbStore, onMutation?: () => void);
+    clearCaches(): void;
+    getKb(): Promise<KbView>;
+    rename(input: KbRenameRequest): Promise<KbView>;
+    remove(): Promise<void>;
+    buildTree(): Promise<KbTree>;
+    readFile(rawPath: string): Promise<KbFile>;
+    resolveRawFile(rawPath: string): Promise<{
+        absPath: string;
+        contentType: string;
+    }>;
+    private resolvedKb;
+    private resolveTrackedPath;
+    private resolveVisibleKbPath;
+    private visibleKbFiles;
+    private rootGitignoreFilter;
+    private collectVisibleFiles;
+}
+export declare const defaultKbRegistryService: KbRegistryService;
+//# sourceMappingURL=kb.service.d.ts.map

package/dist/server/kb/kb.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kb.service.d.ts","sourceRoot":"","sources":["../../../server/kb/kb.service.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,+BAA+B,CAAC;AACzE,OAAO,EAUL,KAAK,iBAAiB,EAEvB,MAAM,gBAAgB,CAAC;AAExB,qBAAa,iBAAiB;IAIhB,OAAO,CAAC,QAAQ,CAAC,QAAQ;IAHrC,OAAO,CAAC,QAAQ,CAA0D;IAC1E,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAgC;gBAE5B,QAAQ,GAAE,eAAuC;IAI9E,WAAW,IAAI,IAAI;IAKb,OAAO,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC;IAK5B,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAoB5E,KAAK,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAiBhD,+BAA+B,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAetE,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,SAAS;YAQnB,WAAW;CAsB1B;AAOD,qBAAa,SAAS;IAIlB,OAAO,CAAC,QAAQ,CAAC,EAAE;IACnB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAL7B,OAAO,CAAC,iBAAiB,CAAuD;gBAG7D,EAAE,EAAE,MAAM,EACV,KAAK,GAAE,OAAyB,EAChC,UAAU,GAAE,MAAM,IAAe;IAGpD,WAAW,IAAI,IAAI;IAIb,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAKxB,MAAM,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC;IAO/C,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAMvB,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC;IAM5B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAuB1C,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,CAAC;YAK1E,UAAU;YAaV,kBAAkB;YAOlB,oBAAoB;YAoCpB,cAAc;YAYd,mBAAmB;YAQnB,mBAAmB;CAqBlC;AAED,eAAO,MAAM,wBAAwB,mBAA0B,CAAC"}

package/dist/server/kb/kb.service.js

@@ -0,0 +1,282 @@
+import { lstat, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join, posix, relative, resolve, sep } from 'node:path';
+import ignore from 'ignore';
+import { DEFAULT_TEAM_KB_ROOT } from '../../shared/agent-home.js';
+import { kbCodeLanguage, kbFileKind } from '../../shared/kb-file-types.js';
+import { KbRegistryStore, KbStore } from '../storage/schema/kb.store.js';
+import { buildTree, CACHE_TTL_MS, contentTypeFor, expandHome, INLINE_TEXT_CAP, KB_ID, KbError, kbView, normalizeRelPath, } from './kb.helper.js';
+export class KbRegistryService {
+    registry;
+    kbsCache;
+    services = new Map();
+    constructor(registry = new KbRegistryStore()) {
+        this.registry = registry;
+    }
+    // Test hook: the root/visibility caches have a TTL, so a test switching
+    // ANIMA_HOME within the TTL window would otherwise see stale roots.
+    clearCaches() {
+        this.kbsCache = undefined;
+        this.services.forEach((service) => service.clearCaches());
+    }
+    async listKbs() {
+        const kbs = await this.resolvedKbs();
+        return kbs.map((kb) => kbView(kb));
+    }
+    async browseKbDirectories(rawPath) {
+        const home = await realpath(homedir());
+        const requested = rawPath?.trim() ? expandHome(rawPath.trim()) : home;
+        const requestedRealpath = await realpath(resolve(requested)).catch(() => undefined);
+        if (!requestedRealpath)
+            throw new KbError(404, 'path_not_found');
+        if (requestedRealpath !== home && !requestedRealpath.startsWith(home + sep)) {
+            throw new KbError(400, 'path outside browse root');
+        }
+        const currentStat = await stat(requestedRealpath).catch(() => undefined);
+        if (!currentStat?.isDirectory())
+            throw new KbError(400, 'path must be an existing directory');
+        const entries = await readdir(requestedRealpath, { withFileTypes: true });
+        return {
+            path: requestedRealpath,
+            entries: entries
+                .filter((entry) => entry.isDirectory() && !entry.name.startsWith('.'))
+                .map((entry) => ({ name: entry.name, path: join(requestedRealpath, entry.name) }))
+                .sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase())),
+        };
+    }
+    async addKb(input) {
+        const id = input.id;
+        const label = input.label;
+        const rootPath = expandHome(input.path);
+        if (!KB_ID.test(id))
+            throw new KbError(400, 'id must be a URL-safe slug');
+        const absolutePath = resolve(rootPath);
+        const rootStat = await stat(absolutePath).catch(() => undefined);
+        if (!rootStat?.isDirectory())
+            throw new KbError(400, 'path must be an existing directory');
+        const store = new KbStore(id);
+        if (store.exists()) {
+            throw new KbError(409, `kb already exists: ${id}`);
+        }
+        await store.write({ id, label, path: absolutePath });
+        this.clearCaches();
+        return this.listKbs();
+    }
+    async ensureDefaultTeamKbForAgentHome(homePath) {
+        const teamRoot = resolve(expandHome(DEFAULT_TEAM_KB_ROOT));
+        const resolvedHome = resolve(expandHome(homePath));
+        if (!isPathInside(resolvedHome, teamRoot))
+            return;
+        const configured = await this.registry.list();
+        if (configured.some((kb) => resolve(expandHome(kb.path)) === teamRoot))
+            return;
+        await this.addKb({
+            id: nextKbId(configured.map((kb) => kb.id), 'team'),
+            label: 'Team',
+            path: teamRoot,
+        });
+    }
+    serviceFor(id) {
+        if (!KB_ID.test(id))
+            throw new KbError(400, 'bad kb id');
+        if (!this.services.has(id)) {
+            this.services.set(id, new KbService(id, new KbStore(id), () => this.clearCaches()));
+        }
+        return this.services.get(id);
+    }
+    async resolvedKbs() {
+        const now = Date.now();
+        if (this.kbsCache && now - this.kbsCache.loadedAt < CACHE_TTL_MS) {
+            return this.kbsCache.kbs;
+        }
+        // Let config-validation errors propagate. Swallowing them here would turn
+        // malformed KB config into a silent empty surface, hiding the exact config
+        // boundary we want explicit.
+        const configured = await this.registry.list();
+        const kbs = [];
+        for (const entry of configured) {
+            const path = resolve(entry.path);
+            const kbStat = await stat(path).catch(() => undefined);
+            if (kbStat?.isDirectory()) {
+                kbs.push({ id: entry.id, label: entry.label, path });
+            }
+            else {
+                console.error(`kb "${entry.id}" path is not an existing directory, skipping: ${path}`);
+            }
+        }
+        this.kbsCache = { kbs, loadedAt: now };
+        return kbs;
+    }
+}
+// Read-only web view over one Knowledge Base directory. If the KB root has
+// a root `.gitignore`, those patterns are the exposure filter; otherwise every
+// file under the root is visible. `.git/` is VCS metadata, not content, and is
+// always skipped. Every request resolves to a root-relative POSIX path that must
+// be an exact member of the visible file set before any byte is read.
+export class KbService {
+    id;
+    store;
+    onMutation;
+    visibleFilesCache;
+    constructor(id, store = new KbStore(id), onMutation = () => { }) {
+        this.id = id;
+        this.store = store;
+        this.onMutation = onMutation;
+    }
+    clearCaches() {
+        this.visibleFilesCache = undefined;
+    }
+    async getKb() {
+        const kb = await this.resolvedKb();
+        return kbView(kb);
+    }
+    async rename(input) {
+        if (!this.store.exists())
+            throw new KbError(404, `kb not found: ${this.id}`);
+        await this.store.update((kb) => ({ ...kb, label: input.label }));
+        this.onMutation();
+        return this.getKb();
+    }
+    async remove() {
+        if (!this.store.exists())
+            throw new KbError(404, `kb not found: ${this.id}`);
+        await this.store.remove();
+        this.onMutation();
+    }
+    async buildTree() {
+        const kb = await this.resolvedKb();
+        const files = await this.visibleKbFiles(kb);
+        return { kb: kbView(kb), nodes: buildTree([...files]) };
+    }
+    async readFile(rawPath) {
+        const { kb, relPath, absPath } = await this.resolveTrackedPath(rawPath);
+        const name = posix.basename(relPath);
+        const kind = kbFileKind(relPath);
+        const fileStat = await lstat(absPath);
+        const meta = { kbId: kb.id, path: relPath, name, kind, size: fileStat.size };
+        if (kind === 'code') {
+            const language = kbCodeLanguage(relPath);
+            if (language)
+                meta.language = language;
+        }
+        // Image / HTML / binary render via the raw route (img src / iframe src), so
+        // we don't inline their bytes here. Text-ish kinds carry their content for
+        // the client renderer, capped.
+        if (kind === 'markdown' || kind === 'json' || kind === 'code' || kind === 'text') {
+            if (fileStat.size > INLINE_TEXT_CAP) {
+                meta.truncated = true;
+            }
+            else {
+                meta.content = await readFile(absPath, 'utf8');
+            }
+        }
+        return meta;
+    }
+    async resolveRawFile(rawPath) {
+        const { relPath, absPath } = await this.resolveTrackedPath(rawPath);
+        return { absPath, contentType: contentTypeFor(relPath) };
+    }
+    async resolvedKb() {
+        if (!KB_ID.test(this.id))
+            throw new KbError(400, 'bad kb id');
+        if (!this.store.exists())
+            throw new KbError(404, 'kb_not_found');
+        const entry = await this.store.read();
+        const path = resolve(entry.path);
+        const kbStat = await stat(path).catch(() => undefined);
+        if (!kbStat?.isDirectory()) {
+            console.error(`kb "${entry.id}" path is not an existing directory, skipping: ${path}`);
+            throw new KbError(404, 'kb_not_found');
+        }
+        return { id: entry.id, label: entry.label, path };
+    }
+    async resolveTrackedPath(rawPath) {
+        const kb = await this.resolvedKb();
+        const relPath = normalizeRelPath(rawPath);
+        const files = await this.visibleKbFiles(kb);
+        return this.resolveVisibleKbPath(kb, relPath, files);
+    }
+    async resolveVisibleKbPath(kb, relPath, files) {
+        if (!files.has(relPath)) {
+            throw new KbError(404, 'not_found');
+        }
+        let absPath = join(kb.path, relPath);
+        // Defensive lexical containment assert (normalizeRelPath already strips `..`).
+        const kbResolved = resolve(kb.path);
+        const absResolved = resolve(absPath);
+        if (absResolved !== kbResolved && !absResolved.startsWith(kbResolved + sep)) {
+            throw new KbError(404, 'not_found');
+        }
+        let fileStat = await lstat(absPath);
+        if (fileStat.isSymbolicLink()) {
+            const resolvedTarget = await realpath(absPath).catch(() => undefined);
+            if (!resolvedTarget)
+                throw new KbError(404, 'not_found');
+            const kbRealpath = await realpath(kb.path);
+            if (resolvedTarget !== kbRealpath && !resolvedTarget.startsWith(kbRealpath + sep)) {
+                throw new KbError(404, 'not_found');
+            }
+            const targetRelPath = relative(kbRealpath, resolvedTarget).split(sep).join(posix.sep);
+            if (!files.has(targetRelPath)) {
+                throw new KbError(404, 'not_found');
+            }
+            absPath = resolvedTarget;
+            fileStat = await lstat(absPath);
+        }
+        if (!fileStat.isFile()) {
+            throw new KbError(404, 'not_found');
+        }
+        return { kb, relPath, absPath };
+    }
+    async visibleKbFiles(kb) {
+        const now = Date.now();
+        if (this.visibleFilesCache && now - this.visibleFilesCache.loadedAt < CACHE_TTL_MS) {
+            return this.visibleFilesCache.files;
+        }
+        const files = new Set();
+        const filter = await this.rootGitignoreFilter(kb.path);
+        await this.collectVisibleFiles(kb.path, '', filter, files);
+        this.visibleFilesCache = { files, loadedAt: now };
+        return files;
+    }
+    async rootGitignoreFilter(rootPath) {
+        // Product v1 uses the KB root `.gitignore` as the boundary. Nested
+        // `.gitignore` files are intentionally not loaded yet; add them here if a
+        // KB starts relying on subdir-specific ignore rules.
+        const content = await readFile(join(rootPath, '.gitignore'), 'utf8').catch(() => undefined);
+        return content === undefined ? undefined : ignore().add(content);
+    }
+    async collectVisibleFiles(rootPath, dirRelPath, filter, files) {
+        const dirPath = dirRelPath ? join(rootPath, dirRelPath) : rootPath;
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            const relPath = dirRelPath ? `${dirRelPath}/${entry.name}` : entry.name;
+            if (relPath === '.git' || relPath.startsWith('.git/'))
+                continue;
+            if (entry.isDirectory()) {
+                if (filter?.ignores(`${relPath}/`))
+                    continue;
+                await this.collectVisibleFiles(rootPath, relPath, filter, files);
+                continue;
+            }
+            if ((entry.isFile() || entry.isSymbolicLink()) && !filter?.ignores(relPath)) {
+                files.add(relPath);
+            }
+        }
+    }
+}
+export const defaultKbRegistryService = new KbRegistryService();
+function nextKbId(existingIds, preferred) {
+    const existing = new Set(existingIds);
+    if (!existing.has(preferred))
+        return preferred;
+    for (let index = 2;; index += 1) {
+        const candidate = `${preferred}-${index}`;
+        if (!existing.has(candidate))
+            return candidate;
+    }
+}
+function isPathInside(path, parent) {
+    const relPath = relative(parent, path);
+    return relPath === '' || Boolean(relPath && !relPath.startsWith('..') && !isAbsolute(relPath));
+}

package/dist/server/messages/message.projection.d.ts

@@ -0,0 +1,8 @@
+import type { Activity } from '../../shared/activity.js';
+import type { AgentMessageRecord } from '../../shared/messages.js';
+import type { InboxItem } from '../../shared/inbox.js';
+export declare function messageFromInboxItem(item: InboxItem): AgentMessageRecord | undefined;
+export declare function messageFromActivity(activity: Activity): AgentMessageRecord | undefined;
+export declare function messageIdForInboxItem(item: InboxItem): string;
+export declare function messageIdForActivity(activity: Activity): string;
+//# sourceMappingURL=message.projection.d.ts.map

package/dist/server/messages/message.projection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message.projection.d.ts","sourceRoot":"","sources":["../../../server/messages/message.projection.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAEV,SAAS,EAGV,MAAM,uBAAuB,CAAC;AAE/B,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,SAAS,GAAG,kBAAkB,GAAG,SAAS,CAiBpF;AAED,wBAAgB,mBAAmB,CAAC,QAAQ,EAAE,QAAQ,GAAG,kBAAkB,GAAG,SAAS,CAiDtF;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAE7D;AAED,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,QAAQ,GAAG,MAAM,CAE/D"}

package/dist/server/messages/message.projection.js

@@ -0,0 +1,198 @@
+export function messageFromInboxItem(item) {
+    if (item.kind === 'slack')
+        return slackInboxMessage(item);
+    if (item.kind === 'reminder') {
+        return {
+            actor: 'Reminder',
+            direction: 'in',
+            kind: 'reminder',
+            messageId: messageIdForInboxItem(item),
+            reminderId: item.reminderId,
+            source: { id: item.id, kind: 'inbox' },
+            text: `Reminder fired: ${item.reminderId}`,
+            timestamp: item.receivedAt,
+        };
+    }
+    if (item.kind === 'onboarding')
+        return onboardingMessage(item);
+    if (item.kind === 'choice_response')
+        return choiceResponseMessage(item);
+    return undefined;
+}
+export function messageFromActivity(activity) {
+    if (activity.type !== 'external.effect.completed' && activity.type !== 'tool.call.completed')
+        return undefined;
+    const payload = activity.payload ?? {};
+    const tool = stringField(payload, 'tool');
+    const effect = stringField(payload, 'effect');
+    if (tool === 'anima.message.send' ||
+        tool === 'anima.message.update' ||
+        effect === 'slack.message.send' ||
+        effect === 'slack.message.update') {
+        return baseOutboxMessage(activity, payload, {
+            isEdit: tool === 'anima.message.update' || effect === 'slack.message.update',
+            kind: 'message',
+            messageTs: stringField(payload, 'ts') ?? stringField(payload, 'targetTs'),
+            text: stringField(payload, 'text') ?? '',
+        });
+    }
+    if (tool === 'anima.file.send' || effect === 'slack.file.send') {
+        const files = uploadFiles(payload['uploads']);
+        const caption = stringField(payload, 'caption') ?? '';
+        const text = [caption, files.length ? `Files: ${files.map((file) => file.filename).join(', ')}` : 'Files uploaded']
+            .filter(Boolean)
+            .join('\n');
+        return baseOutboxMessage(activity, payload, {
+            files,
+            kind: 'file',
+            text,
+        });
+    }
+    if (tool === 'anima.message.react' || effect === 'slack.reaction') {
+        const action = stringField(payload, 'action') === 'removed' ? 'removed' : 'added';
+        const name = stringField(payload, 'name') ?? '';
+        return baseOutboxMessage(activity, payload, {
+            kind: 'reaction',
+            messageTs: stringField(payload, 'targetTs') ?? stringField(payload, 'ts'),
+            reaction: {
+                action,
+                name,
+                ...(payload['noop'] === true ? { noop: true } : {}),
+            },
+            text: `Reaction ${action}: :${name || 'unknown'}:`,
+        });
+    }
+    return undefined;
+}
+export function messageIdForInboxItem(item) {
+    return `msg_inbox:${item.id}`;
+}
+export function messageIdForActivity(activity) {
+    return `msg_activity:${activity.activityId}`;
+}
+function slackInboxMessage(item) {
+    return {
+        actor: slackActorLabel(item),
+        actorDisplayName: item.actor?.displayName,
+        actorHandle: item.actor?.handle,
+        actorUserId: item.actor?.userId,
+        channelId: item.channelId,
+        ...(item.channelName ? { channelName: item.channelName } : {}),
+        direction: 'in',
+        ...(item.files?.length ? { files: item.files.map((file) => ({
+                filename: file.name,
+                fileId: file.id,
+                mimetype: file.mimetype,
+                sizeBytes: file.sizeBytes,
+            })) } : {}),
+        kind: 'message',
+        messageId: messageIdForInboxItem(item),
+        messageTs: item.messageTs,
+        ...(item.permalink ? { permalink: item.permalink } : {}),
+        source: { id: item.id, kind: 'inbox' },
+        text: item.text,
+        ...(item.threadTs ? { threadTs: item.threadTs } : {}),
+        timestamp: item.receivedAt,
+    };
+}
+function onboardingMessage(item) {
+    return {
+        actor: onboardingActorLabel(item),
+        actorDisplayName: item.operator.displayName,
+        actorHandle: item.operator.handle,
+        actorUserId: item.operator.slackUserId,
+        channelId: item.channelId,
+        direction: 'in',
+        kind: 'onboarding',
+        messageId: messageIdForInboxItem(item),
+        source: { id: item.id, kind: 'inbox' },
+        text: item.text,
+        timestamp: item.receivedAt,
+    };
+}
+function choiceResponseMessage(item) {
+    return {
+        actor: choiceActorLabel(item),
+        actorDisplayName: item.answeredBy.displayName,
+        actorHandle: item.answeredBy.handle,
+        actorUserId: item.answeredBy.slackUserId,
+        channelId: item.channelId,
+        ...(item.channelName ? { channelName: item.channelName } : {}),
+        direction: 'in',
+        kind: 'choice_response',
+        messageId: messageIdForInboxItem(item),
+        messageTs: item.messageTs,
+        optionLabel: item.optionLabel,
+        question: item.question,
+        source: { id: item.id, kind: 'inbox' },
+        text: `Selected: ${item.optionLabel}\nQuestion: ${item.question}`,
+        threadTs: item.threadTs,
+        timestamp: item.receivedAt,
+    };
+}
+function baseOutboxMessage(activity, payload, entry) {
+    return {
+        channelId: stringField(payload, 'channel'),
+        channelDisplayName: stringField(payload, 'channelDisplayName'),
+        channelKind: stringField(payload, 'channelKind'),
+        channelName: stringField(payload, 'channelName'),
+        direction: 'out',
+        dmHandle: stringField(payload, 'dmHandle'),
+        dmUserId: stringField(payload, 'dmUserId'),
+        messageId: messageIdForActivity(activity),
+        messageTs: entry.messageTs,
+        permalink: stringField(payload, 'permalink'),
+        source: { id: activity.activityId, kind: 'activity' },
+        threadTs: stringField(payload, 'threadTs'),
+        timestamp: activity.createdAt,
+        ...entry,
+    };
+}
+function slackActorLabel(item) {
+    const actor = item.actor;
+    const handle = actor?.handle?.replace(/^@/, '');
+    if (handle) {
+        const name = actor?.displayName ?? actor?.realName;
+        return name && name !== handle ? `${name} (@${handle})` : `@${handle}`;
+    }
+    return actor?.displayName ?? actor?.realName ?? actor?.userId ?? 'Unknown user';
+}
+function onboardingActorLabel(item) {
+    const handle = item.operator.handle?.replace(/^@/, '');
+    if (handle)
+        return `${item.operator.displayName} (@${handle})`;
+    return item.operator.displayName || item.operator.slackUserId;
+}
+function choiceActorLabel(item) {
+    const handle = item.answeredBy.handle?.replace(/^@/, '');
+    if (handle) {
+        const name = item.answeredBy.displayName;
+        return name && name !== handle ? `${name} (@${handle})` : `@${handle}`;
+    }
+    return item.answeredBy.displayName ?? item.answeredBy.slackUserId;
+}
+function uploadFiles(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    return raw.flatMap((entry) => {
+        if (!entry || typeof entry !== 'object')
+            return [];
+        const record = entry;
+        const filename = stringField(record, 'filename');
+        if (!filename)
+            return [];
+        return [{
+                filename,
+                ...(stringField(record, 'fileId') ? { fileId: stringField(record, 'fileId') } : {}),
+                ...(stringField(record, 'mimetype') ? { mimetype: stringField(record, 'mimetype') } : {}),
+                ...(stringField(record, 'permalink') ? { permalink: stringField(record, 'permalink') } : {}),
+                ...(typeof record['sizeBytes'] === 'number' ? { sizeBytes: record['sizeBytes'] } : {}),
+                ...(stringField(record, 'thumb360') ? { thumb360: stringField(record, 'thumb360') } : {}),
+                ...(stringField(record, 'thumb720') ? { thumb720: stringField(record, 'thumb720') } : {}),
+            }];
+    });
+}
+function stringField(payload, key) {
+    const value = payload[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}

package/dist/server/messages/message.service.d.ts

@@ -0,0 +1,25 @@
+import type { Activity } from '../../shared/activity.js';
+import type { AgentMessageDirection, AgentMessageHistoryPage, AgentMessageRecord } from '../../shared/messages.js';
+import type { InboxItem } from '../../shared/inbox.js';
+import { ActivityStore } from '../storage/schema/activity.store.js';
+import { WakeQueueStore } from '../storage/schema/wake-queue.store.js';
+import { MessageStore } from '../storage/schema/message.store.js';
+export interface MessageListInput {
+    before?: string;
+    direction?: AgentMessageDirection;
+    limit?: number;
+    since?: string;
+}
+export declare class MessageService {
+    private readonly store;
+    private readonly wakeQueueStore;
+    private readonly activityStore;
+    constructor(agentId: string, store?: MessageStore, wakeQueueStore?: WakeQueueStore, activityStore?: ActivityStore);
+    recordInboxItem(item: InboxItem): Promise<AgentMessageRecord | undefined>;
+    recordOutboxActivity(activity: Activity): Promise<AgentMessageRecord | undefined>;
+    list(input?: MessageListInput): Promise<AgentMessageHistoryPage>;
+    legacyBackfilled(): Promise<boolean>;
+    private backfillLegacyMessages;
+}
+export declare function messageServiceForAgent(agentId: string): MessageService;
+//# sourceMappingURL=message.service.d.ts.map