@meetquinn/animactl 0.1.1-canary.21.1.cd63d38

package/README.md

@@ -0,0 +1,13 @@
+# @meetquinn/animactl
+
+Operator CLI for installing and running Anima from npm.
+
+```bash
+npx @meetquinn/animactl start
+npx @meetquinn/animactl@canary restart
+npx @meetquinn/animactl status
+npx @meetquinn/animactl stop
+```
+
+This package installs the `@meetquinn/animactl` runtime into `~/.anima/runtime/current` and runs
+services from that pinned runtime. Durable Anima data remains in `~/.anima`.

package/bin/anima

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const scriptPath = fileURLToPath(import.meta.url);
+const sourcePath = existsSync(scriptPath) ? realpathSync(scriptPath) : scriptPath;
+const packageRoot = resolve(dirname(sourcePath), '..');
+const cliPath = resolve(packageRoot, 'dist/server/cli/anima.js');
+const result = spawnSync(process.execPath, [cliPath, ...process.argv.slice(2)], { stdio: 'inherit' });
+if (result.error) throw result.error;
+if (result.signal) process.kill(process.pid, result.signal);
+process.exit(result.status ?? 1);

package/bin/animactl

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+import { existsSync, realpathSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const scriptPath = fileURLToPath(import.meta.url);
+const sourcePath = existsSync(scriptPath) ? realpathSync(scriptPath) : scriptPath;
+const packageRoot = resolve(dirname(sourcePath), '..');
+const cliPath = resolve(packageRoot, 'dist/server/cli/animactl-npm.js');
+const result = spawnSync(process.execPath, [cliPath, ...process.argv.slice(2)], { stdio: 'inherit' });
+if (result.error) throw result.error;
+if (result.signal) process.kill(process.pid, result.signal);
+process.exit(result.status ?? 1);

package/dist/server/activities/activity.service.d.ts

@@ -0,0 +1,22 @@
+import type { Activity, AgentActivityFeedPage } from '../../shared/activity.js';
+import { WakeQueueService } from '../inbox/wake-queue.service.js';
+import { ActivityStore, type ActivityRecordInput } from '../storage/schema/activity.store.js';
+export interface ActivityListInput {
+    before?: string;
+    limit?: number;
+}
+export interface ActivityRecorder {
+    record(agentId: string, input: ActivityRecordInput): Promise<Activity>;
+}
+export declare class ActivityService {
+    private readonly store;
+    private readonly wakeQueue;
+    constructor(agentId: string, store?: ActivityStore, wakeQueue?: WakeQueueService);
+    record(input: ActivityRecordInput): Promise<Activity>;
+    readAll(): Promise<Activity[]>;
+    readSince(createdAt: string): Promise<Activity[]>;
+    listActivityFeed(input?: ActivityListInput): Promise<AgentActivityFeedPage>;
+}
+export declare function activityServiceForAgent(agentId: string): ActivityService;
+export declare const defaultActivityRecorder: ActivityRecorder;
+//# sourceMappingURL=activity.service.d.ts.map

package/dist/server/activities/activity.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity.service.d.ts","sourceRoot":"","sources":["../../../server/activities/activity.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAA0B,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AACxG,OAAO,EAAE,gBAAgB,EAAkB,MAAM,gCAAgC,CAAC;AAClF,OAAO,EAAE,aAAa,EAAE,KAAK,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAE9F,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CACxE;AAED,qBAAa,eAAe;IAGxB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,SAAS;gBAF1B,OAAO,EAAE,MAAM,EACE,KAAK,GAAE,aAA0C,EACjD,SAAS,GAAE,gBAAgD;IAG9E,MAAM,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,QAAQ,CAAC;IAIrD,OAAO,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI9B,SAAS,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;IAI3C,gBAAgB,CAAC,KAAK,GAAE,iBAAsB,GAAG,OAAO,CAAC,qBAAqB,CAAC;CActF;AAED,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,CAExE;AAED,eAAO,MAAM,uBAAuB,EAAE,gBAErC,CAAC"}

package/dist/server/activities/activity.service.js

@@ -0,0 +1,49 @@
+import { WakeQueueService } from '../inbox/wake-queue.service.js';
+import { ActivityStore } from '../storage/schema/activity.store.js';
+export class ActivityService {
+    store;
+    wakeQueue;
+    constructor(agentId, store = new ActivityStore(agentId), wakeQueue = new WakeQueueService(agentId)) {
+        this.store = store;
+        this.wakeQueue = wakeQueue;
+    }
+    record(input) {
+        return this.store.record(input);
+    }
+    readAll() {
+        return this.store.readAll();
+    }
+    readSince(createdAt) {
+        return this.store.readSince(createdAt);
+    }
+    async listActivityFeed(input = {}) {
+        const limit = normalizeActivityLimit(input.limit);
+        const [activities, items] = await Promise.all([
+            input.before ? this.store.readBefore(input.before, limit) : this.store.readLastN(limit),
+            this.wakeQueue.list(),
+        ]);
+        const events = [...activities.map(activityFeedEvent), ...items.map(inboxFeedEvent)]
+            .filter((event) => !input.before || event.timestamp < input.before)
+            .sort((a, b) => a.timestamp.localeCompare(b.timestamp))
+            .slice(-limit);
+        const nextCursor = events.length >= limit ? (events[0]?.timestamp ?? null) : null;
+        return { events, nextCursor };
+    }
+}
+export function activityServiceForAgent(agentId) {
+    return new ActivityService(agentId);
+}
+export const defaultActivityRecorder = {
+    record: (agentId, input) => activityServiceForAgent(agentId).record(input),
+};
+function normalizeActivityLimit(limit) {
+    if (!Number.isFinite(limit))
+        return 100;
+    return Math.min(Math.max(1, Math.trunc(limit)), 500);
+}
+function activityFeedEvent(activity) {
+    return { activity, kind: 'activity', timestamp: activity.createdAt };
+}
+function inboxFeedEvent(item) {
+    return { item, kind: 'inbox', timestamp: item.receivedAt };
+}

package/dist/server/agents/agent-config-ops.d.ts

@@ -0,0 +1,17 @@
+import { type AgentConfig, type AgentCreateRequest, type AgentUpdateProviderRequest } from '../../shared/agent-config.js';
+export declare class AgentConfigError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare function isAgentRunnable(agent: AgentConfig): boolean;
+export declare function agentConfigFromCreateInput(input: AgentCreateRequest): AgentConfig;
+export declare function agentConfigWithProviderUpdate(current: AgentConfig, update: AgentUpdateProviderRequest): AgentConfig;
+export declare function redactAgentConfig(agent: AgentConfig): AgentConfig;
+export declare function normalizeAgentConfig(agentId: string, agent: AgentConfig): AgentConfig;
+export declare function assertAgentConfigId(agentId: string, agent: AgentConfig, path: string): void;
+export declare function validateAgentConfig(agent: AgentConfig): Promise<void>;
+export declare function validateRunnableAgentConfig(agent: AgentConfig): Promise<void>;
+export declare function ensureCreateAgentHome(homePath: string): Promise<void>;
+export declare function ensureExistingAgentHome(homePath: string): Promise<void>;
+export declare function resolveAgentHomePath(agent: AgentConfig): string;
+//# sourceMappingURL=agent-config-ops.d.ts.map

package/dist/server/agents/agent-config-ops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-config-ops.d.ts","sourceRoot":"","sources":["../../../server/agents/agent-config-ops.ts"],"names":[],"mappings":"AAIA,OAAO,EAKL,KAAK,WAAW,EAChB,KAAK,kBAAkB,EACvB,KAAK,0BAA0B,EAChC,MAAM,8BAA8B,CAAC;AAYtC,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;gBAEhB,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAIhD;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAE3D;AAMD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,kBAAkB,GAAG,WAAW,CAqBjF;AAED,wBAAgB,6BAA6B,CAC3C,OAAO,EAAE,WAAW,EACpB,MAAM,EAAE,0BAA0B,GACjC,WAAW,CAKb;AAiED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,WAAW,CAMjE;AAaD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,GAAG,WAAW,CAMrF;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAI3F;AAED,wBAAsB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAM3E;AAED,wBAAsB,2BAA2B,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAKnF;AAoCD,wBAAsB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU3E;AAED,wBAAsB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAK7E;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAE/D"}

package/dist/server/agents/agent-config-ops.js

@@ -0,0 +1,209 @@
+import { mkdir, stat } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, resolve } from 'node:path';
+import { ANIMA_MANAGED_PROVIDER_ENV_KEYS, AgentProviderConfig, agentConfigSchema, agentIdFromName, } from '../../shared/agent-config.js';
+import { DEFAULT_REASONING_EFFORT, isSupportedReasoningEffort, isSupportedProviderKind, isSupportedProviderModel, providerCatalogEntry, } from '../../shared/provider-catalog.js';
+import { resolveAnimaHome } from '../anima-home.js';
+import { AGENT_ID } from '../storage/schema/agent.store.js';
+export class AgentConfigError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.statusCode = statusCode;
+    }
+}
+export function isAgentRunnable(agent) {
+    return Boolean(agent.provider && agent.slack.appToken && agent.slack.botToken);
+}
+// ---------------------------------------------------------------------------
+// Construction
+// ---------------------------------------------------------------------------
+export function agentConfigFromCreateInput(input) {
+    return {
+        createdAt: new Date().toISOString(),
+        enabled: true,
+        id: agentIdFromName(input.name),
+        profile: {
+            displayName: input.name,
+            role: input.role,
+        },
+        provider: AgentProviderConfig.parse(input.provider),
+        slack: {
+            appToken: '',
+            botToken: '',
+            connected: false,
+            manifestVersion: 0,
+            teamId: '',
+            workspaceIconUrl: '',
+            workspaceName: '',
+        },
+        homePath: resolveServerPath(input.homePath),
+    };
+}
+export function agentConfigWithProviderUpdate(current, update) {
+    const selection = mergeProviderSelection(current.provider, update);
+    const env = mergeProviderEnv(current.provider.env, update.env);
+    if (env)
+        selection.env = env;
+    return { ...current, provider: AgentProviderConfig.parse(selection) };
+}
+// Returns the provider's kind/model/effort (and any kind-specific fields), env stripped.
+// env is merged separately by mergeProviderEnv so the two concerns stay untangled.
+function mergeProviderSelection(current, update) {
+    // Same kind: keep the current selection, overlay only the fields the update provides.
+    if (!update.kind || update.kind === current.kind) {
+        const currentEffort = 'reasoningEffort' in current ? current.reasoningEffort : undefined;
+        const model = update.model ?? current.model;
+        const reasoningEffort = update.reasoningEffort ?? currentEffort;
+        validateProviderShape(current.kind, model, reasoningEffort);
+        const { env: _env, ...rest } = current;
+        const next = { ...rest };
+        if (update.model !== undefined)
+            next.model = update.model;
+        if (update.reasoningEffort !== undefined)
+            next.reasoningEffort = update.reasoningEffort;
+        return next;
+    }
+    // Kind change: drop the old model/effort and adopt the new kind's catalog defaults.
+    const entry = providerCatalogEntry(update.kind);
+    if (!entry)
+        throw new AgentConfigError(400, `unsupported provider kind ${update.kind}`);
+    const model = update.model ?? entry.defaultModel;
+    const reasoningEffort = update.reasoningEffort ?? defaultReasoningEffort(entry);
+    validateProviderShape(entry.kind, model, reasoningEffort);
+    const next = { kind: entry.kind, model };
+    if (current.idleTimeoutMs !== undefined)
+        next.idleTimeoutMs = current.idleTimeoutMs;
+    if (reasoningEffort !== undefined)
+        next.reasoningEffort = reasoningEffort;
+    return next;
+}
+function mergeProviderEnv(current, update) {
+    const env = { ...current };
+    for (const [key, value] of Object.entries(update ?? {})) {
+        if (value !== null && isAnimaManagedProviderEnvKey(key)) {
+            throw new AgentConfigError(400, `${key} is managed by Anima and cannot be set in provider.env`);
+        }
+        if (value === null)
+            delete env[key];
+        else
+            env[key] = value;
+    }
+    return Object.keys(env).length > 0 ? env : undefined;
+}
+function defaultReasoningEffort(entry) {
+    if (entry.reasoningEfforts.length === 0)
+        return undefined;
+    return entry.reasoningEfforts.includes(DEFAULT_REASONING_EFFORT)
+        ? DEFAULT_REASONING_EFFORT
+        : entry.reasoningEfforts[0];
+}
+function isAnimaManagedProviderEnvKey(key) {
+    return ANIMA_MANAGED_PROVIDER_ENV_KEYS.includes(key);
+}
+// ---------------------------------------------------------------------------
+// Redaction (strip secrets before a config leaves the server)
+// ---------------------------------------------------------------------------
+export function redactAgentConfig(agent) {
+    return {
+        ...agent,
+        provider: redactProviderEnv(agent.provider),
+        slack: { ...agent.slack, appToken: '', botToken: '' },
+    };
+}
+// Keep the env keys visible so the UI can show what's set, but blank their values.
+function redactProviderEnv(provider) {
+    if (!provider.env)
+        return provider;
+    const env = Object.fromEntries(Object.keys(provider.env).sort().map((key) => [key, '']));
+    return { ...provider, env };
+}
+// ---------------------------------------------------------------------------
+// Validation (the write gate; the zod schema repairs configs on read)
+// ---------------------------------------------------------------------------
+export function normalizeAgentConfig(agentId, agent) {
+    if (!AGENT_ID.test(agentId))
+        throw new AgentConfigError(400, `agent id must match ${AGENT_ID}`);
+    const next = agentConfigSchema(agentId).parse(agent);
+    if (next.id !== agentId)
+        throw new AgentConfigError(400, 'agent id is immutable');
+    validateAgentConfigShape(next);
+    return next;
+}
+export function assertAgentConfigId(agentId, agent, path) {
+    if (agent.id !== agentId) {
+        throw new AgentConfigError(400, `${path}: agent id must match directory name ${agentId}`);
+    }
+}
+export async function validateAgentConfig(agent) {
+    validateAgentConfigShape(agent);
+    const homeStat = await stat(resolveAgentHomePath(agent)).catch(() => undefined);
+    if (!homeStat?.isDirectory()) {
+        throw new AgentConfigError(400, `Agent ${agent.id}: homePath must be an existing directory`);
+    }
+}
+export async function validateRunnableAgentConfig(agent) {
+    await validateAgentConfig(agent);
+    if (!isAgentRunnable(agent)) {
+        throw new Error(`Agent ${agent.id}: provider and Slack tokens are required to run`);
+    }
+}
+function validateAgentConfigShape(agent) {
+    if (!AGENT_ID.test(agent.id))
+        throw new AgentConfigError(400, `agent id must match ${AGENT_ID}`);
+    const provider = agent.provider;
+    const reasoningEffort = 'reasoningEffort' in provider ? provider.reasoningEffort : undefined;
+    validateProviderShape(provider.kind, provider.model, reasoningEffort, `Agent ${agent.id}: `);
+    if (agent.slack.appToken && !agent.slack.appToken.startsWith('xapp-')) {
+        throw new AgentConfigError(400, `Agent ${agent.id}: slack.appToken must start with xapp-`);
+    }
+    if (agent.slack.botToken && !agent.slack.botToken.startsWith('xoxb-')) {
+        throw new AgentConfigError(400, `Agent ${agent.id}: slack.botToken must start with xoxb-`);
+    }
+}
+function validateProviderShape(kind, model, reasoningEffort, prefix = '') {
+    if (!isSupportedProviderKind(kind)) {
+        throw new AgentConfigError(400, `${prefix}unsupported provider kind ${kind}`);
+    }
+    if (model && !isSupportedProviderModel(kind, model)) {
+        throw new AgentConfigError(400, `${prefix}unsupported model for ${kind}: ${model}`);
+    }
+    if (reasoningEffort && !isSupportedReasoningEffort(kind, reasoningEffort)) {
+        throw new AgentConfigError(400, `${prefix}unsupported reasoningEffort ${reasoningEffort}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Home paths
+// ---------------------------------------------------------------------------
+export async function ensureCreateAgentHome(homePath) {
+    const absolutePath = resolveServerPath(homePath);
+    const existing = await stat(absolutePath).catch(() => undefined);
+    if (existing) {
+        if (!existing.isDirectory())
+            throw new AgentConfigError(400, 'homePath must be a directory');
+        return;
+    }
+    // Recursive so the full path (including the default agent home root) is created on first
+    // run when the parent directories don't exist yet.
+    await mkdir(absolutePath, { recursive: true });
+}
+export async function ensureExistingAgentHome(homePath) {
+    const existing = await stat(resolveServerPath(homePath)).catch(() => undefined);
+    if (!existing?.isDirectory()) {
+        throw new AgentConfigError(400, 'homePath must be an existing directory');
+    }
+}
+export function resolveAgentHomePath(agent) {
+    return resolveServerPath(agent.homePath);
+}
+function resolveServerPath(rawPath) {
+    const expanded = expandHome(rawPath);
+    return isAbsolute(expanded) ? resolve(expanded) : resolve(resolveAnimaHome(), expanded);
+}
+function expandHome(path) {
+    if (path === '~')
+        return homedir();
+    if (path.startsWith('~/'))
+        return resolve(homedir(), path.slice(2));
+    return path;
+}

package/dist/server/agents/agent-skills.d.ts

@@ -0,0 +1,4 @@
+import type { AgentConfig } from '../../shared/agent-config.js';
+import type { AgentSkills } from '../../shared/skills.js';
+export declare function scanAgentSkills(agent: AgentConfig): Promise<AgentSkills>;
+//# sourceMappingURL=agent-skills.d.ts.map

package/dist/server/agents/agent-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skills.d.ts","sourceRoot":"","sources":["../../../server/agents/agent-skills.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAChE,OAAO,KAAK,EAAE,WAAW,EAAgB,MAAM,wBAAwB,CAAC;AAMxE,wBAAsB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CAS9E"}

package/dist/server/agents/agent-skills.js

@@ -0,0 +1,71 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { resolveAgentHomePath } from './agent-config-ops.js';
+const GLOBAL_AGENTS_SKILLS = join(homedir(), '.agents', 'skills');
+const GLOBAL_CODEX_SKILLS = join(homedir(), '.codex', 'skills');
+export async function scanAgentSkills(agent) {
+    const isCodex = agent.provider.kind === 'codex-cli';
+    const globalPath = isCodex ? GLOBAL_CODEX_SKILLS : GLOBAL_AGENTS_SKILLS;
+    const localPath = join(resolveAgentHomePath(agent), '.claude', 'skills');
+    const [global, local] = await Promise.all([
+        scanSkillDir(globalPath, isCodex),
+        scanSkillDir(localPath, false),
+    ]);
+    return { global, globalPath, local, localPath };
+}
+async function scanSkillDir(dir, excludeSystem) {
+    let dirNames;
+    try {
+        const entries = await readdir(dir, { withFileTypes: true });
+        dirNames = entries
+            .filter((entry) => {
+            if (!entry.isDirectory())
+                return false;
+            if (excludeSystem && entry.name === '.system')
+                return false;
+            if (entry.name.startsWith('.'))
+                return false;
+            return true;
+        })
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+    const results = await Promise.all(dirNames.map((dirName) => readSkill(dir, dirName)));
+    return results.filter((skill) => skill !== null);
+}
+async function readSkill(base, dirName) {
+    try {
+        const content = await readFile(join(base, dirName, 'SKILL.md'), 'utf8');
+        const frontmatter = parseSkillFrontmatter(content);
+        return {
+            dirName,
+            name: frontmatter.name ?? dirName,
+            ...(frontmatter.description ? { description: frontmatter.description } : {}),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function parseSkillFrontmatter(content) {
+    const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (!match)
+        return {};
+    const result = {};
+    for (const line of match[1].split(/\r?\n/)) {
+        const keyValue = line.match(/^(\w+)\s*:\s*(.*)/);
+        if (!keyValue)
+            continue;
+        const key = keyValue[1];
+        const value = keyValue[2].trim();
+        if (key === 'description' && value)
+            result.description = value;
+        if (key === 'name' && value)
+            result.name = value;
+    }
+    return result;
+}

package/dist/server/agents/agent-slack-validation.d.ts

@@ -0,0 +1,16 @@
+import type { WebClient } from '@slack/web-api';
+import { type AgentSlackValidateRequest, type AgentSlackValidateResponse } from '../../shared/agent-config.js';
+export interface SlackDisplayInfo {
+    appId?: string;
+    avatarUrl?: string;
+    botName?: string;
+    botUserId?: string;
+    teamId?: string;
+    workspaceIconUrl?: string;
+    workspaceName?: string;
+}
+export declare function validateSlackTokenPair(input: AgentSlackValidateRequest): Promise<AgentSlackValidateResponse>;
+export declare function getSlackDisplayInfo(client: WebClient): Promise<SlackDisplayInfo>;
+export declare function appIdFromAppToken(token: string | undefined): string | undefined;
+export declare function getBotTokenScopes(token: string): Promise<string[]>;
+//# sourceMappingURL=agent-slack-validation.d.ts.map

package/dist/server/agents/agent-slack-validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-slack-validation.d.ts","sourceRoot":"","sources":["../../../server/agents/agent-slack-validation.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EACL,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAKhC,MAAM,8BAA8B,CAAC;AAMtC,MAAM,WAAW,gBAAgB;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAID,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,0BAA0B,CAAC,CAYrC;AAED,wBAAsB,mBAAmB,CAAC,MAAM,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAoBtF;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAE/E;AAED,wBAAsB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAWxE"}

package/dist/server/agents/agent-slack-validation.js

@@ -0,0 +1,155 @@
+import { isRecord } from '../json.js';
+import { createSlackWebClient } from '../slack/client.js';
+import { SlackWorkspaceDirectoryService } from '../slack/workspace-directory.service.js';
+import { parseOauthScopesHeader } from '../slack/shortcuts.js';
+const APP_TOKEN_APP_ID_PATTERN = /^xapp-\d+-(A[A-Z0-9]+)-/;
+export async function validateSlackTokenPair(input) {
+    const app = input.appToken !== undefined
+        ? await validateSlackToken('app', input.appToken)
+        : undefined;
+    const bot = input.botToken !== undefined
+        ? await validateSlackToken('bot', input.botToken)
+        : undefined;
+    return {
+        ...(app ? { app } : {}),
+        ...(bot ? { bot } : {}),
+        connection: slackConnectionValidation(app, bot),
+    };
+}
+export async function getSlackDisplayInfo(client) {
+    const auth = await client.auth.test();
+    if (!auth.user_id)
+        throw new Error('Slack auth.test did not return a bot user id');
+    // Fetch the bot user profile directly (bypasses WorkspaceDirectoryService cache)
+    // so avatar changes take effect immediately on sync without requiring a full
+    // workspace directory refresh.
+    const userInfo = await client.users.info({ user: auth.user_id });
+    const user = userInfo.user;
+    const directory = new SlackWorkspaceDirectoryService({ client, teamId: auth.team_id });
+    const botName = directory.getUserDisplayName(user, (typeof auth.user === 'string' ? auth.user.trim() : '') || auth.user_id);
+    const workspaceIconUrl = await directory.getWorkspaceIconUrl().catch(() => '');
+    return {
+        appId: auth.app_id,
+        avatarUrl: user?.profile?.image_72 ?? '',
+        botName,
+        botUserId: auth.user_id,
+        teamId: auth.team_id ?? '',
+        workspaceIconUrl,
+        workspaceName: auth.team ?? '',
+    };
+}
+export function appIdFromAppToken(token) {
+    return token?.match(APP_TOKEN_APP_ID_PATTERN)?.[1];
+}
+export async function getBotTokenScopes(token) {
+    const response = await fetch(slackApiMethodUrl('auth.test'), {
+        headers: {
+            authorization: `Bearer ${token}`,
+            'content-type': 'application/x-www-form-urlencoded',
+        },
+        method: 'POST',
+    });
+    const result = await response.json();
+    if (!result.ok)
+        throw new Error(`Slack auth.test failed: ${result.error ?? 'unknown_error'}`);
+    return parseOauthScopesHeader(response.headers.get('x-oauth-scopes'));
+}
+async function validateSlackToken(expected, rawToken) {
+    const token = rawToken.trim();
+    if (!token)
+        return invalidTokenValidation('unknown', expected, 'missing_token');
+    const detected = slackTokenKind(token);
+    if (detected === 'unknown')
+        return invalidTokenValidation(detected, expected, 'unknown_token_type');
+    if (detected !== expected)
+        return invalidTokenValidation(detected, expected, 'wrong_token_type');
+    return expected === 'app'
+        ? validateAppToken(token)
+        : validateBotToken(token);
+}
+async function validateAppToken(token) {
+    const appId = appIdFromAppToken(token);
+    try {
+        await createSlackWebClient(token).apps.connections.open({});
+        return { ...(appId ? { appId } : {}), detected: 'app', expected: 'app', valid: true };
+    }
+    catch (error) {
+        return {
+            ...(appId ? { appId } : {}),
+            detected: 'app',
+            expected: 'app',
+            reason: tokenValidationReason(error, 'app'),
+            valid: false,
+        };
+    }
+}
+async function validateBotToken(token) {
+    try {
+        const info = await getSlackDisplayInfo(createSlackWebClient(token));
+        return {
+            appId: info.appId,
+            botAvatarUrl: info.avatarUrl,
+            botName: info.botName,
+            botUserId: info.botUserId,
+            detected: 'bot',
+            expected: 'bot',
+            teamId: info.teamId,
+            valid: true,
+            workspaceIconUrl: info.workspaceIconUrl,
+            workspaceName: info.workspaceName,
+        };
+    }
+    catch (error) {
+        return { detected: 'bot', expected: 'bot', reason: tokenValidationReason(error, 'bot'), valid: false };
+    }
+}
+function invalidTokenValidation(detected, expected, reason) {
+    return { detected, expected, reason, valid: false };
+}
+function slackTokenKind(token) {
+    if (token.startsWith('xapp-'))
+        return 'app';
+    if (token.startsWith('xoxb-'))
+        return 'bot';
+    return 'unknown';
+}
+function slackApiMethodUrl(method) {
+    const base = process.env.ANIMA_SLACK_API_URL ?? 'https://slack.com/api';
+    return `${base.replace(/\/$/, '')}/${method}`;
+}
+function slackConnectionValidation(app, bot) {
+    if (!app?.valid || !bot?.valid)
+        return { reason: 'incomplete', valid: false };
+    const base = {
+        appId: bot.appId ?? app.appId,
+        botAvatarUrl: bot.botAvatarUrl,
+        botName: bot.botName,
+        botUserId: bot.botUserId,
+        teamId: bot.teamId,
+        workspaceIconUrl: bot.workspaceIconUrl,
+        workspaceName: bot.workspaceName,
+    };
+    if (app.appId && bot.appId && app.appId !== bot.appId) {
+        return { ...base, reason: 'app_mismatch', valid: false };
+    }
+    return { ...base, valid: true };
+}
+function slackErrorCode(error) {
+    const data = isRecord(error) ? error['data'] : undefined;
+    if (isRecord(data) && typeof data['error'] === 'string')
+        return data['error'];
+    if (isRecord(error) && typeof error['code'] === 'string')
+        return error['code'];
+    return undefined;
+}
+function tokenValidationReason(error, kind) {
+    const code = slackErrorCode(error);
+    if (code === 'missing_scope' && kind === 'app')
+        return 'missing_connections_write';
+    if (code === 'invalid_auth' || code === 'not_authed' || code === 'token_revoked' || code === 'account_inactive') {
+        return 'invalid_token';
+    }
+    if (kind === 'bot' && error instanceof Error && /bot user id/i.test(error.message))
+        return 'not_bot_token';
+    return 'slack_api_error';
+}

package/dist/server/agents/agent-slack.service.d.ts

@@ -0,0 +1,26 @@
+import type { WebClient } from '@slack/web-api';
+import { type AgentConnectSlackRequest, type AgentConfig, type AgentSetOwnerRequest, type AgentSlackValidateRequest, type AgentSlackValidateResponse, type SlackUserCandidate } from '../../shared/agent-config.js';
+import { type AgentSlackManifestUpdateInfo, type AgentSlackManifestUpgradeRequest } from '../../shared/slack-manifest.js';
+import { AgentService } from './agent.service.js';
+export declare class AgentSlackService {
+    private readonly agentService;
+    constructor(agentService: AgentService);
+    validateTokens(input: AgentSlackValidateRequest): Promise<AgentSlackValidateResponse>;
+    connect(input: AgentConnectSlackRequest): Promise<AgentConfig>;
+    getManifestUpdateInfo(): Promise<AgentSlackManifestUpdateInfo>;
+    upgradeManifestVersion(input: AgentSlackManifestUpgradeRequest): Promise<AgentConfig>;
+    syncDisplayInfo(): Promise<AgentConfig>;
+    getWebClient(): Promise<WebClient>;
+    getAgentWebClient(): Promise<{
+        agent: AgentConfig;
+        client: WebClient;
+    }>;
+    private webClientForAgent;
+    fetchPrivateUrl(url: string): Promise<Response>;
+    listUsers(): Promise<SlackUserCandidate[]>;
+    setOwner(input: AgentSetOwnerRequest): Promise<AgentConfig>;
+    getInstallUrl(): Promise<string>;
+    private ensureOwnerOnboardingPrompt;
+}
+export declare function agentSlackServiceForAgent(agentId: string): AgentSlackService;
+//# sourceMappingURL=agent-slack.service.d.ts.map

package/dist/server/agents/agent-slack.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-slack.service.d.ts","sourceRoot":"","sources":["../../../server/agents/agent-slack.service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEhD,OAAO,EACL,KAAK,wBAAwB,EAC7B,KAAK,WAAW,EAChB,KAAK,oBAAoB,EACzB,KAAK,yBAAyB,EAC9B,KAAK,0BAA0B,EAC/B,KAAK,kBAAkB,EACxB,MAAM,8BAA8B,CAAC;AACtC,OAAO,EAEL,KAAK,4BAA4B,EACjC,KAAK,gCAAgC,EACtC,MAAM,gCAAgC,CAAC;AAExC,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAoBlD,qBAAa,iBAAiB;IAChB,OAAO,CAAC,QAAQ,CAAC,YAAY;gBAAZ,YAAY,EAAE,YAAY;IAGjD,cAAc,CAClB,KAAK,EAAE,yBAAyB,GAC/B,OAAO,CAAC,0BAA0B,CAAC;IAIhC,OAAO,CAAC,KAAK,EAAE,wBAAwB,GAAG,OAAO,CAAC,WAAW,CAAC;IAwB9D,qBAAqB,IAAI,OAAO,CAAC,4BAA4B,CAAC;IAgB9D,sBAAsB,CAC1B,KAAK,EAAE,gCAAgC,GACtC,OAAO,CAAC,WAAW,CAAC;IAoCjB,eAAe,IAAI,OAAO,CAAC,WAAW,CAAC;IAcvC,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC;IAIlC,iBAAiB,IAAI,OAAO,CAAC;QAAE,KAAK,EAAE,WAAW,CAAC;QAAC,MAAM,EAAE,SAAS,CAAA;KAAE,CAAC;IAK7E,OAAO,CAAC,iBAAiB;IAInB,eAAe,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAK/C,SAAS,IAAI,OAAO,CAAC,kBAAkB,EAAE,CAAC;IAK1C,QAAQ,CAAC,KAAK,EAAE,oBAAoB,GAAG,OAAO,CAAC,WAAW,CAAC;IAkB3D,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC;YAMxB,2BAA2B;CAqD1C;AAED,wBAAgB,yBAAyB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAE5E"}