@meetquinn/animactl 0.1.1-canary.21.1.cd63d38

package/dist/server/asks/interactive-ask.service.js

@@ -0,0 +1,181 @@
+import { activityServiceForAgent } from '../activities/activity.service.js';
+import { errorMessage, nowIso } from '../ids.js';
+import { WakeQueueService } from '../inbox/wake-queue.service.js';
+import { SlackWorkspaceDirectoryService } from '../slack/workspace-directory.service.js';
+import { InteractiveAskStore, } from '../storage/schema/interactive-ask.store.js';
+export const INTERACTIVE_ASK_ACTION_ID = 'anima.ask.answer';
+const INTERACTIVE_ASK_ANSWERED_RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
+export class InteractiveAskService {
+    store;
+    queue;
+    activity;
+    constructor(agentId, store = new InteractiveAskStore(agentId), queue = new WakeQueueService(agentId), activity = activityServiceForAgent(agentId)) {
+        this.store = store;
+        this.queue = queue;
+        this.activity = activity;
+    }
+    async saveAsk(record) {
+        const ask = await this.store.create(record);
+        await this.pruneOldAnswered();
+        return ask;
+    }
+    async getAsk(askId) {
+        return this.store.find(askId);
+    }
+    async answerAsk(input) {
+        const now = nowIso();
+        let result = { outcome: 'not_found' };
+        const existingAsk = await this.store.find(input.askId);
+        const answeredBy = existingAsk
+            && existingAsk.options.some((option) => option.optionId === input.optionId)
+            && this.canUserAnswer(existingAsk, input.userId)
+            && existingAsk.status === 'pending'
+            ? await this.answeringUser(input, existingAsk)
+            : undefined;
+        if (existingAsk) {
+            const touchedAsk = { ...existingAsk, lastInteractionAt: now };
+            const option = existingAsk.options.find((candidate) => candidate.optionId === input.optionId);
+            if (!option) {
+                result = { ask: await this.store.update(touchedAsk), outcome: 'invalid_option' };
+            }
+            else if (!this.canUserAnswer(existingAsk, input.userId)) {
+                result = { ask: await this.store.update(touchedAsk), outcome: 'forbidden' };
+            }
+            else if (existingAsk.status === 'answered') {
+                result = { ask: await this.store.update(touchedAsk), outcome: 'already_answered' };
+            }
+            else {
+                const answeredAsk = {
+                    ...touchedAsk,
+                    answeredAt: now,
+                    answeredBy: answeredBy ?? { slackUserId: input.userId },
+                    chosenOptionId: option.optionId,
+                    status: 'answered',
+                };
+                result = { ask: await this.store.update(answeredAsk), outcome: 'answered' };
+            }
+        }
+        if (result.outcome !== 'answered' || !result.ask) {
+            await this.recordAnswerActivity(input.askId, input.optionId, input.userId, result.outcome);
+            await this.pruneOldAnswered();
+            return result;
+        }
+        const selected = result.ask.options.find((option) => option.optionId === result.ask?.chosenOptionId);
+        if (!selected || !result.ask.answeredBy) {
+            await this.recordAnswerActivity(input.askId, input.optionId, input.userId, 'invalid_option');
+            await this.pruneOldAnswered();
+            return { ask: result.ask, outcome: 'invalid_option' };
+        }
+        const queued = !(await this.queue.enqueue(choiceResponseInboxItem(result.ask, selected, result.ask.answeredBy))).duplicate;
+        await this.recordAnswerActivity(input.askId, input.optionId, input.userId, 'answered', {
+            queued,
+            optionLabel: selected.label,
+        });
+        await this.pruneOldAnswered();
+        return { ...result, queued };
+    }
+    async replaceAnsweredMessage(input) {
+        const option = input.ask.options.find((candidate) => candidate.optionId === input.ask.chosenOptionId);
+        const userId = input.ask.answeredBy?.slackUserId;
+        if (!option || !userId)
+            return;
+        await input.client.chat.update({
+            blocks: [
+                {
+                    type: 'section',
+                    text: {
+                        type: 'mrkdwn',
+                        text: `${input.ask.question}\n\n✓ *${option.label}* — chosen by <@${userId}>`,
+                    },
+                },
+            ],
+            channel: input.ask.channelId,
+            text: `${input.ask.question}\n\n✓ ${option.label} — chosen by <@${userId}>`,
+            ts: input.ask.messageTs,
+        });
+    }
+    async notifyForbiddenClick(input) {
+        const allowed = input.ask.allowedUserIds?.[0];
+        if (!allowed)
+            return;
+        await input.client.chat.postEphemeral({
+            channel: input.ask.channelId,
+            text: `Only <@${allowed}> can answer this ask.`,
+            user: input.userId,
+        });
+    }
+    canUserAnswer(ask, userId) {
+        return !ask.allowedUserIds?.length || ask.allowedUserIds.includes(userId);
+    }
+    async answeringUser(input, ask) {
+        const user = await new SlackWorkspaceDirectoryService({
+            client: input.client,
+            teamId: ask.teamId,
+        }).getUser(input.userId).catch(() => undefined);
+        return slackAnswerUser(user, input.userId);
+    }
+    async recordAnswerActivity(askId, optionId, userId, outcome, extra) {
+        await this.activity.record({
+            type: 'anima.ask.answer',
+            payload: {
+                askId,
+                optionId,
+                outcome,
+                userId,
+                ...(extra ?? {}),
+            },
+        }).catch(() => undefined);
+    }
+    async pruneOldAnswered() {
+        try {
+            const cutoffIso = new Date(Date.now() - INTERACTIVE_ASK_ANSWERED_RETENTION_MS).toISOString();
+            await this.store.pruneAnsweredBefore(cutoffIso);
+        }
+        catch (error) {
+            console.warn(`Interactive ask retention failed: ${errorMessage(error)}`);
+        }
+    }
+}
+export function interactiveAskServiceForAgent(agentId) {
+    return new InteractiveAskService(agentId);
+}
+export function choiceResponseInboxItem(ask, option, answeredBy) {
+    const now = ask.answeredAt ?? nowIso();
+    const threadTs = ask.threadTs ?? ask.messageTs;
+    return {
+        answeredBy,
+        askId: ask.askId,
+        channelId: ask.channelId,
+        ...(ask.channelName ? { channelName: ask.channelName } : {}),
+        handling: { createdAt: now, queuedAt: now, status: 'queued', updatedAt: now },
+        id: `choice:${ask.agentId}:${ask.askId}`,
+        kind: 'choice_response',
+        messageTs: ask.messageTs,
+        optionId: option.optionId,
+        optionLabel: option.label,
+        question: ask.question,
+        receivedAt: now,
+        teamId: ask.teamId,
+        threadTs,
+    };
+}
+export function slackAnswerUser(user, fallback) {
+    const displayName = user?.profile?.display_name?.trim()
+        || user?.profile?.real_name?.trim()
+        || user?.real_name?.trim()
+        || user?.name?.trim()
+        || undefined;
+    const handle = user?.name?.trim() || undefined;
+    return {
+        ...(displayName ? { displayName } : {}),
+        ...(handle ? { handle } : {}),
+        slackUserId: user?.id ?? fallback,
+    };
+}
+export function ownerAllowedUser(owner) {
+    return {
+        displayName: owner.displayName,
+        ...(owner.handle ? { handle: owner.handle } : {}),
+        slackUserId: owner.slackUserId,
+    };
+}

package/dist/server/bundled-templates.d.ts

@@ -0,0 +1,2 @@
+export declare function readBundledTemplate(filename: string): Promise<string>;
+//# sourceMappingURL=bundled-templates.d.ts.map

package/dist/server/bundled-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundled-templates.d.ts","sourceRoot":"","sources":["../../server/bundled-templates.ts"],"names":[],"mappings":"AASA,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAc3E"}

package/dist/server/bundled-templates.js

@@ -0,0 +1,24 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isMissingFile } from './storage/json-file.js';
+// templates/ ships at the repo root, outside dist. Relative to this module that's
+// two levels up when compiled (dist/server/bundled-templates.js) and one in dev
+// (server/bundled-templates.ts); try both so the same call works either way.
+export async function readBundledTemplate(filename) {
+    const moduleDir = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(moduleDir, '..', '..', 'templates', filename),
+        join(moduleDir, '..', 'templates', filename),
+    ];
+    for (const path of candidates) {
+        try {
+            return await readFile(path, 'utf8');
+        }
+        catch (error) {
+            if (!isMissingFile(error))
+                throw error;
+        }
+    }
+    throw new Error(`Bundled template not found: ${filename}`);
+}

package/dist/server/cli/anima.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export declare function createCliProgram(): Command;
+//# sourceMappingURL=anima.d.ts.map

package/dist/server/cli/anima.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anima.d.ts","sourceRoot":"","sources":["../../../server/cli/anima.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAepC,wBAAgB,gBAAgB,IAAI,OAAO,CAiB1C"}

package/dist/server/cli/anima.js

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { errorMessage } from '../ids.js';
+import { registerAskCommands } from '../tools/ask.js';
+import { registerReminderCommands } from '../reminders/cli.js';
+import { registerFileCommands } from '../tools/files-cli.js';
+import { registerMessageHistoryCommands } from '../tools/message-history-cli.js';
+import { registerMessageCommands } from '../tools/messages-cli.js';
+import { registerReactionCommands } from '../tools/reactions-cli.js';
+import { registerSubscriptionCommands } from '../tools/subscriptions-cli.js';
+async function main() {
+    await createCliProgram().parseAsync(process.argv);
+}
+export function createCliProgram() {
+    const program = new Command();
+    program
+        .name('anima')
+        .description('Agent-facing Anima tools')
+        .showHelpAfterError()
+        .configureHelp({ sortSubcommands: true });
+    registerMessageCommands(program);
+    registerMessageHistoryCommands(program);
+    registerReactionCommands(program);
+    registerSubscriptionCommands(program);
+    registerReminderCommands(program);
+    registerFileCommands(program);
+    registerAskCommands(program);
+    return program;
+}
+main().catch((error) => {
+    console.error(errorMessage(error));
+    process.exitCode = 1;
+});

package/dist/server/cli/animactl-npm.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export declare function createAnimactlNpmProgram(): Command;
+//# sourceMappingURL=animactl-npm.d.ts.map

package/dist/server/cli/animactl-npm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animactl-npm.d.ts","sourceRoot":"","sources":["../../../server/cli/animactl-npm.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AASpC,wBAAgB,wBAAwB,IAAI,OAAO,CAKlD"}

package/dist/server/cli/animactl-npm.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { errorMessage } from '../ids.js';
+import { registerTopLevelRuntimeCommands } from './runtime-cli.js';
+async function main() {
+    await createAnimactlNpmProgram().parseAsync(process.argv);
+}
+export function createAnimactlNpmProgram() {
+    const program = new Command();
+    program.name('animactl');
+    registerTopLevelRuntimeCommands(program);
+    return program;
+}
+main().catch((error) => {
+    console.error(errorMessage(error));
+    process.exitCode = 1;
+});

package/dist/server/cli/animactl.d.ts

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+export declare function createAdminCliProgram(): Command;
+//# sourceMappingURL=animactl.d.ts.map

package/dist/server/cli/animactl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"animactl.d.ts","sourceRoot":"","sources":["../../../server/cli/animactl.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAWpC,wBAAgB,qBAAqB,IAAI,OAAO,CAc/C"}

package/dist/server/cli/animactl.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { errorMessage } from '../ids.js';
+import { registerRuntimeCommand } from './runtime-cli.js';
+import { registerServiceCommands } from './service.js';
+import { registerServicesCommand } from './services-cli.js';
+async function main() {
+    await createAdminCliProgram().parseAsync(process.argv);
+}
+export function createAdminCliProgram() {
+    const program = new Command();
+    program
+        .name('animactl')
+        .description('Operate Anima server and web services')
+        .option('--agent <id>')
+        .showHelpAfterError()
+        .configureHelp({ sortSubcommands: true });
+    registerServiceCommands(program);
+    registerServicesCommand(program);
+    registerRuntimeCommand(program);
+    return program;
+}
+main().catch((error) => {
+    console.error(errorMessage(error));
+    process.exitCode = 1;
+});

package/dist/server/cli/runtime-cli.d.ts

@@ -0,0 +1,33 @@
+import type { Command } from 'commander';
+import { type RuntimeInstallOptions, type RuntimeStatus } from '../runtime/managed-runtime.js';
+import { type RuntimeUpgradeStatusResponse } from '../../shared/runtime-upgrade.js';
+interface RuntimeCliOptions {
+    channel?: string;
+    dashboardHost?: string;
+    dashboardPort?: number;
+    drainTimeoutMs?: number;
+    force?: boolean;
+    idleTimeoutMs?: number;
+    logPath?: string;
+    npm?: string;
+    only?: 'agent' | 'web';
+    packageName?: string;
+    previousStartedAt?: string;
+    previousVersion?: string;
+    releaseTrack?: string;
+    runtimeDir?: string;
+    skipInstall?: boolean;
+    targetVersion?: string;
+    version?: string;
+    verifyTimeoutMs?: number;
+}
+export declare function registerRuntimeCommand(program: Command): void;
+export declare function registerTopLevelRuntimeCommands(program: Command): void;
+export declare function runtimeInstallOptions(options: RuntimeCliOptions, defaults?: {
+    defaultChannel?: string;
+    defaultVersion?: string;
+}): RuntimeInstallOptions;
+export declare function printRuntimeStatus(status: RuntimeStatus): void;
+export declare function printUpgradeStatus(status: RuntimeUpgradeStatusResponse): void;
+export {};
+//# sourceMappingURL=runtime-cli.d.ts.map

package/dist/server/cli/runtime-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-cli.d.ts","sourceRoot":"","sources":["../../../server/cli/runtime-cli.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAKzC,OAAO,EAOL,KAAK,qBAAqB,EAC1B,KAAK,aAAa,EACnB,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EAAuB,KAAK,4BAA4B,EAAE,MAAM,iCAAiC,CAAC;AAEzG,UAAU,iBAAiB;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACvB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAK7D;AAED,wBAAgB,+BAA+B,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAMtE;AA6HD,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,iBAAiB,EAC1B,QAAQ,GAAE;IAAE,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAA;CAAO,GAClE,qBAAqB,CAQvB;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI,CAc9D;AAED,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,4BAA4B,GAAG,IAAI,CAgB7E"}

package/dist/server/cli/runtime-cli.js

@@ -0,0 +1,309 @@
+import { spawn } from 'node:child_process';
+import { withAnimaHome } from '../anima-home.js';
+import { defaultServerSettingsService } from '../settings/settings.service.js';
+import { DEFAULT_RUNTIME_PACKAGE, currentRuntimePackageInfo, ensureManagedRuntime, installManagedRuntime, readManagedRuntimeStatus, resolveManagedAnimaHome, } from '../runtime/managed-runtime.js';
+import { RuntimeUpgradeService, runRuntimeUpgradeWorker, } from '../runtime/runtime-upgrade.js';
+import { RuntimeReleaseTrack } from '../../shared/runtime-upgrade.js';
+export function registerRuntimeCommand(program) {
+    const runtime = program
+        .command('runtime')
+        .description('Manage the local npm-installed Anima runtime');
+    registerRuntimeCommands(runtime, { topLevel: false });
+}
+export function registerTopLevelRuntimeCommands(program) {
+    program
+        .description('Control the local npm-installed Anima runtime')
+        .showHelpAfterError()
+        .configureHelp({ sortSubcommands: true });
+    registerRuntimeCommands(program, { topLevel: true });
+}
+function registerRuntimeCommands(program, options) {
+    program
+        .command('install')
+        .description('Install Anima into the managed runtime directory')
+        .option('--channel <tag>', 'npm dist-tag to install, for example latest or canary')
+        .option('--version <version>', 'exact package version to install')
+        .option('--runtime-dir <path>', 'runtime directory (default: ~/.anima/runtime/current)')
+        .option('--package-name <name>', 'npm package name to install', DEFAULT_RUNTIME_PACKAGE)
+        .option('--npm <command>', 'npm command to use', 'npm')
+        .action(async (options) => {
+        const result = await installManagedRuntime(runtimeInstallOptions(options, { defaultChannel: 'latest' }));
+        printInstallResult(result.metadata.version, result.metadata.specifier, result.paths.runtimeDir, result.installed);
+    });
+    const statusCommand = program
+        .command('status')
+        .description(options.topLevel ? 'Show managed runtime and local service status' : 'Show the managed runtime installation status')
+        .option('--runtime-dir <path>', 'runtime directory (default: ~/.anima/runtime/current)')
+        .option('--package-name <name>', 'npm package name to inspect', DEFAULT_RUNTIME_PACKAGE);
+    statusCommand.action(async (commandOptions) => {
+        if (options.topLevel) {
+            await runManagedServiceCommand('status', commandOptions);
+            return;
+        }
+        const status = await readManagedRuntimeStatus({
+            packageName: commandOptions.packageName,
+            runtimeDir: commandOptions.runtimeDir,
+        });
+        printRuntimeStatus(status);
+        if (!status.installed)
+            process.exitCode = 1;
+    });
+    if (options.topLevel) {
+        program
+            .command('runtime-status')
+            .description('Show only the managed runtime installation status')
+            .option('--runtime-dir <path>', 'runtime directory (default: ~/.anima/runtime/current)')
+            .option('--package-name <name>', 'npm package name to inspect', DEFAULT_RUNTIME_PACKAGE)
+            .action(async (commandOptions) => {
+            const status = await readManagedRuntimeStatus({
+                packageName: commandOptions.packageName,
+                runtimeDir: commandOptions.runtimeDir,
+            });
+            printRuntimeStatus(status);
+            if (!status.installed)
+                process.exitCode = 1;
+        });
+    }
+    program
+        .command('upgrade-status')
+        .description('Check whether the managed runtime has an available update')
+        .action(async () => {
+        await withRuntimeHome(options.topLevel, async () => {
+            printUpgradeStatus(await new RuntimeUpgradeService().status());
+        });
+    });
+    program
+        .command('release-track')
+        .description('Show or set the hidden operator release track: stable or canary')
+        .argument('[track]', 'stable or canary')
+        .action(async (track) => {
+        await withRuntimeHome(options.topLevel, async () => {
+            if (track === undefined) {
+                console.log(`releaseTrack: ${await defaultServerSettingsService.getReleaseTrack()}`);
+                return;
+            }
+            const parsed = RuntimeReleaseTrack.safeParse(track);
+            if (!parsed.success)
+                throw new Error('release track must be "stable" or "canary"');
+            console.log(`releaseTrack: ${await defaultServerSettingsService.setReleaseTrack(parsed.data)}`);
+        });
+    });
+    program
+        .command('upgrade-worker')
+        .description('Internal detached runtime upgrade worker')
+        .requiredOption('--target-version <version>', 'exact runtime version to install')
+        .requiredOption('--release-track <track>', 'stable or canary')
+        .option('--dashboard-host <host>', 'dashboard host for post-upgrade verification')
+        .option('--dashboard-port <port>', 'dashboard port for post-upgrade verification', parsePositiveInteger)
+        .option('--idle-timeout-ms <ms>', 'how long to wait for idle agents before failing', parseNonNegativeInteger)
+        .option('--log-path <path>', 'upgrade log path')
+        .option('--npm <command>', 'npm command to use')
+        .option('--package-name <name>', 'npm package name to install', DEFAULT_RUNTIME_PACKAGE)
+        .option('--previous-started-at <iso>', 'server startedAt before the upgrade')
+        .option('--previous-version <version>', 'version to rollback to on failure')
+        .option('--verify-timeout-ms <ms>', 'how long to wait for the upgraded server to verify', parseNonNegativeInteger)
+        .action(async (commandOptions) => {
+        await withRuntimeHome(options.topLevel, async () => {
+            await runRuntimeUpgradeWorker(workerOptions(commandOptions));
+        });
+    });
+    serviceCommand(program, 'start', { installable: true })
+        .description('Install the managed runtime if needed, then start local Anima services')
+        .action(async (options) => {
+        await runManagedServiceCommand('start', options);
+    });
+    serviceCommand(program, 'restart', { installable: true })
+        .description('Install the managed runtime if needed, then restart local Anima services')
+        .option('--drain-timeout-ms <ms>', 'How long to wait for active agents to reach a restart drain point', parseNonNegativeInteger)
+        .option('--force', 'Restart even if agent inboxes are running or queued')
+        .option('--idle-timeout-ms <ms>', 'How long to wait for idle agents before failing', parseNonNegativeInteger)
+        .action(async (options) => {
+        await runManagedServiceCommand('restart', options);
+    });
+    serviceCommand(program, 'stop')
+        .description('Stop local Anima services from the managed runtime')
+        .action(async (options) => {
+        await runManagedServiceCommand('stop', options);
+    });
+    if (!options.topLevel) {
+        serviceCommand(program, 'service-status')
+            .description('Show managed runtime and local service status')
+            .action(async (commandOptions) => {
+            await runManagedServiceCommand('status', commandOptions);
+        });
+    }
+}
+export function runtimeInstallOptions(options, defaults = {}) {
+    return {
+        channel: options.version ? undefined : options.channel ?? defaults.defaultChannel,
+        npmCommand: options.npm,
+        packageName: options.packageName,
+        runtimeDir: options.runtimeDir,
+        version: options.version ?? defaults.defaultVersion,
+    };
+}
+export function printRuntimeStatus(status) {
+    if (!status.installed) {
+        console.log('runtime: not installed');
+        console.log(`dir: ${status.paths.runtimeDir}`);
+        console.log('Run `npx @meetquinn/animactl start` to install and start the local runtime.');
+        return;
+    }
+    console.log(`runtime: ${status.packageName}@${status.version ?? 'unknown'}`);
+    console.log(`dir: ${status.paths.runtimeDir}`);
+    console.log(`animactl: ${status.paths.animactlScript}`);
+    if (status.metadata) {
+        console.log(`requested: ${status.metadata.requested}`);
+        console.log(`installedAt: ${status.metadata.installedAt}`);
+    }
+}
+export function printUpgradeStatus(status) {
+    console.log(`runtime: ${status.currentVersion}`);
+    console.log(`releaseTrack: ${status.releaseTrack}`);
+    console.log(`latestOnTrack: ${status.latestOnTrack ?? 'unknown'}`);
+    console.log(`update: ${status.updateAvailable ? 'available' : 'none'}`);
+    console.log(`checkedAt: ${status.checkedAt}`);
+    if (status.checkError)
+        console.log(`checkError: ${status.checkError.type}: ${status.checkError.message}`);
+    console.log(`gate: ${status.gate.state}${status.gate.blockers.length ? ` (${status.gate.blockers.length} blockers)` : ''}`);
+    if (status.operation.status !== 'idle') {
+        const parts = [
+            status.operation.status,
+            status.operation.targetVersion ? `target=${status.operation.targetVersion}` : undefined,
+            status.operation.error ? `error=${JSON.stringify(status.operation.error)}` : undefined,
+        ].filter(Boolean);
+        console.log(`operation: ${parts.join(' ')}`);
+    }
+}
+function printInstallResult(version, specifier, runtimeDir, installed) {
+    const action = installed ? 'installed' : 'using';
+    console.log(`runtime: ${action} ${specifier} -> ${version}`);
+    console.log(`dir: ${runtimeDir}`);
+}
+function serviceCommand(runtime, name, options = {}) {
+    const command = runtime
+        .command(name)
+        .option('--only <service>', 'Limit the service command to agent or web')
+        .option('--runtime-dir <path>', 'runtime directory (default: ~/.anima/runtime/current)')
+        .option('--package-name <name>', 'npm package name to inspect/use', DEFAULT_RUNTIME_PACKAGE);
+    if (options.installable) {
+        command
+            .option('--npm <command>', 'npm command to use', 'npm')
+            .option('--channel <tag>', 'npm dist-tag to install before start/restart, for example latest or canary')
+            .option('--version <version>', 'exact package version to install before start/restart')
+            .option('--skip-install', 'Use the currently installed runtime without running npm install first');
+    }
+    return command;
+}
+async function runManagedServiceCommand(command, options) {
+    assertServiceOptions(options);
+    const packageName = options.packageName ?? DEFAULT_RUNTIME_PACKAGE;
+    const shouldInstall = (command === 'start' || command === 'restart') && !options.skipInstall;
+    const status = shouldInstall
+        ? undefined
+        : await readManagedRuntimeStatus({ packageName, runtimeDir: options.runtimeDir });
+    const paths = shouldInstall
+        ? (await installRuntimeForService(options)).paths
+        : status?.paths;
+    if (!paths)
+        throw new Error('Unable to resolve managed runtime paths.');
+    if (!shouldInstall) {
+        if (command === 'status' && status)
+            printRuntimeStatus(status);
+        if (!status?.installed) {
+            process.exitCode = 1;
+            return;
+        }
+    }
+    const exitCode = await runAnimactlServices(paths.animactlScript, paths.packageDir, command, options);
+    if (exitCode !== 0)
+        process.exitCode = exitCode;
+}
+async function installRuntimeForService(options) {
+    const current = await currentRuntimePackageInfo();
+    const result = await ensureManagedRuntime(runtimeInstallOptions({
+        ...options,
+        packageName: options.packageName ?? current.name,
+    }, {
+        defaultVersion: options.channel ? undefined : current.version,
+    }));
+    const action = result.installed ? 'installed' : 'using';
+    console.log(`runtime: ${action} ${result.metadata.packageName}@${result.metadata.version}`);
+    console.log(`dir: ${result.paths.runtimeDir}`);
+    return { paths: result.paths };
+}
+function assertServiceOptions(options) {
+    if (options.only && options.only !== 'agent' && options.only !== 'web') {
+        throw new Error('--only must be "agent" or "web"');
+    }
+    if (options.channel && options.version)
+        throw new Error('Choose either --version or --channel, not both.');
+}
+async function runAnimactlServices(animactlScript, packageDir, command, options) {
+    const args = [animactlScript, 'services', command];
+    if (options.only)
+        args.push('--only', options.only);
+    if (command === 'restart') {
+        if (options.force) {
+            args.push('--force');
+            if (options.idleTimeoutMs !== undefined)
+                args.push('--idle-timeout-ms', String(options.idleTimeoutMs));
+        }
+        else {
+            args.push('--drain-active', '--resume-running');
+            const drainTimeoutMs = options.drainTimeoutMs ?? options.idleTimeoutMs;
+            if (drainTimeoutMs !== undefined)
+                args.push('--drain-timeout-ms', String(drainTimeoutMs));
+        }
+    }
+    return new Promise((resolveDone, reject) => {
+        const child = spawn(process.execPath, args, {
+            cwd: packageDir,
+            env: {
+                ...process.env,
+                ANIMA_HOME: resolveManagedAnimaHome(),
+            },
+            stdio: 'inherit',
+        });
+        child.once('error', reject);
+        child.once('exit', (code, signal) => {
+            if (signal)
+                reject(new Error(`animactl services ${command} exited from signal ${signal}`));
+            else
+                resolveDone(code ?? 1);
+        });
+    });
+}
+function parseNonNegativeInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0)
+        throw new Error('value must be a non-negative integer');
+    return parsed;
+}
+function parsePositiveInteger(value) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed <= 0)
+        throw new Error('value must be a positive integer');
+    return parsed;
+}
+function workerOptions(options) {
+    if (!options.targetVersion)
+        throw new Error('--target-version is required');
+    const releaseTrack = RuntimeReleaseTrack.parse(options.releaseTrack);
+    return {
+        ...(options.dashboardHost ? { dashboardHost: options.dashboardHost } : {}),
+        ...(options.dashboardPort !== undefined ? { dashboardPort: options.dashboardPort } : {}),
+        ...(options.idleTimeoutMs !== undefined ? { idleTimeoutMs: options.idleTimeoutMs } : {}),
+        ...(options.logPath ? { logPath: options.logPath } : {}),
+        ...(options.npm ? { npmCommand: options.npm } : {}),
+        ...(options.packageName ? { packageName: options.packageName } : {}),
+        ...(options.previousStartedAt ? { previousStartedAt: options.previousStartedAt } : {}),
+        ...(options.previousVersion ? { previousVersion: options.previousVersion } : {}),
+        releaseTrack,
+        targetVersion: options.targetVersion,
+        ...(options.verifyTimeoutMs !== undefined ? { verifyTimeoutMs: options.verifyTimeoutMs } : {}),
+    };
+}
+function withRuntimeHome(topLevel, body) {
+    return topLevel ? withAnimaHome(resolveManagedAnimaHome(), body) : body();
+}