@hotmeshio/long-tail 0.1.0

package/build/start/index.js

@@ -0,0 +1,87 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.start = start;
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const logger_1 = require("../services/logger");
+const telemetry_1 = require("../services/telemetry");
+const events_1 = require("../services/events");
+const maintenance_1 = require("../services/maintenance");
+const cron_1 = require("../services/cron");
+const mcp_1 = require("../services/mcp");
+const escalation_strategy_1 = require("../services/escalation-strategy");
+const config_1 = require("./config");
+const adapters_1 = require("./adapters");
+const workers_1 = require("./workers");
+const server_1 = require("./server");
+const socketio_1 = require("../services/events/socketio");
+/**
+ * Start Long Tail with a declarative configuration.
+ *
+ * Handles database connection, migrations, adapter registration,
+ * worker startup, and the embedded API server. Returns a client
+ * for starting workflows and a shutdown function.
+ *
+ * ```typescript
+ * import { start } from '@hotmeshio/long-tail';
+ * import * as myWorkflow from './workflows/my-workflow';
+ *
+ * const lt = await start({
+ *   database: { host: 'localhost', port: 5432, user: 'postgres', password: 'password', database: 'mydb' },
+ *   workers: [
+ *     { taskQueue: 'my-queue', workflow: myWorkflow.myWorkflow },
+ *   ],
+ * });
+ * ```
+ */
+async function start(startConfig) {
+    // 1. Apply database config
+    (0, config_1.applyDatabaseConfig)(startConfig.database);
+    // 2. Apply server/auth config
+    await (0, config_1.applyServerAuthConfig)(startConfig);
+    // 3. Register adapters
+    (0, adapters_1.registerAdapters)(startConfig);
+    logger_1.loggerRegistry.info('[long-tail] starting...');
+    // 4-5. Collect workers, run migrations, start workers, seed data
+    const { workers, builtinMcpServerFactories } = await (0, workers_1.collectWorkers)(startConfig);
+    await (0, workers_1.startWorkers)(startConfig, workers, builtinMcpServerFactories);
+    // 6. Start embedded server (if enabled)
+    const serverEnabled = startConfig.server?.enabled !== false;
+    let httpServer = null;
+    if (serverEnabled) {
+        httpServer = (0, server_1.startServer)();
+        // Attach socket.io adapter to the HTTP server (if registered)
+        const socketAdapter = events_1.eventRegistry.getAdapter(socketio_1.SocketIOEventAdapter);
+        if (socketAdapter && httpServer) {
+            socketAdapter.attachServer(httpServer);
+            await socketAdapter.connect();
+        }
+    }
+    // 7. Return instance
+    const connection = (0, workers_1.buildConnection)();
+    const client = new hotmesh_1.Durable.Client({ connection });
+    const shutdown = async () => {
+        logger_1.loggerRegistry.info('[long-tail] shutting down...');
+        if (httpServer) {
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        }
+        if (mcp_1.mcpRegistry.hasAdapter) {
+            await mcp_1.mcpRegistry.disconnect();
+        }
+        if (cron_1.cronRegistry.hasActiveCrons) {
+            await cron_1.cronRegistry.disconnect();
+        }
+        if (maintenance_1.maintenanceRegistry.hasConfig) {
+            await maintenance_1.maintenanceRegistry.disconnect();
+        }
+        if (events_1.eventRegistry.hasAdapters) {
+            await events_1.eventRegistry.disconnect();
+        }
+        if (telemetry_1.telemetryRegistry.hasAdapter) {
+            await telemetry_1.telemetryRegistry.disconnect();
+        }
+        escalation_strategy_1.escalationStrategyRegistry.clear();
+        await hotmesh_1.Durable.shutdown();
+        logger_1.loggerRegistry.info('[long-tail] shutdown complete');
+    };
+    return { client, shutdown };
+}

package/build/start/server.d.ts

@@ -0,0 +1,6 @@
+import express from 'express';
+/**
+ * Create and start the embedded Express server with health check,
+ * API routes, and optional dashboard static assets.
+ */
+export declare function startServer(): ReturnType<typeof express.application.listen>;

package/build/start/server.js

@@ -0,0 +1,46 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startServer = startServer;
+const fs_1 = require("fs");
+const path_1 = __importDefault(require("path"));
+const express_1 = __importDefault(require("express"));
+const config_1 = require("../modules/config");
+const logger_1 = require("../services/logger");
+const routes_1 = __importDefault(require("../routes"));
+/**
+ * Create and start the embedded Express server with health check,
+ * API routes, and optional dashboard static assets.
+ */
+function startServer() {
+    const app = (0, express_1.default)();
+    if (process.env.NODE_ENV !== 'production') {
+        app.disable('etag');
+    }
+    app.use(express_1.default.json());
+    app.get('/health', (_req, res) => {
+        res.json({ status: 'ok', timestamp: new Date().toISOString() });
+    });
+    app.use('/api', routes_1.default);
+    // Serve dashboard static assets
+    // Resolves correctly in both dev (ts-node from root) and prod (node build/)
+    const devDist = path_1.default.join(__dirname, '..', 'dashboard', 'dist');
+    const prodDist = path_1.default.join(__dirname, '..', '..', 'dashboard', 'dist');
+    const dashboardDist = (0, fs_1.existsSync)(devDist) ? devDist : prodDist;
+    if ((0, fs_1.existsSync)(dashboardDist)) {
+        app.use(express_1.default.static(dashboardDist));
+        // SPA fallback — all non-API routes serve index.html
+        app.get('/{*splat}', (_req, res) => {
+            res.sendFile(path_1.default.join(dashboardDist, 'index.html'));
+        });
+        logger_1.loggerRegistry.info(`[long-tail] Dashboard: http://localhost:${config_1.config.PORT}/`);
+    }
+    const httpServer = app.listen(config_1.config.PORT, () => {
+        logger_1.loggerRegistry.info(`[long-tail] server running on port ${config_1.config.PORT}`);
+        logger_1.loggerRegistry.info(`[long-tail] API: http://localhost:${config_1.config.PORT}/api`);
+        logger_1.loggerRegistry.info(`[long-tail] Health: http://localhost:${config_1.config.PORT}/health`);
+    });
+    return httpServer;
+}

package/build/start/workers.d.ts

@@ -0,0 +1,32 @@
+import { Client as Postgres } from 'pg';
+import type { LTStartConfig } from '../types/startup';
+type WorkerEntry = {
+    taskQueue: string;
+    workflow: (...args: any[]) => any;
+};
+/**
+ * Build the connection descriptor used by HotMesh / Durable.
+ */
+export declare function buildConnection(): {
+    class: typeof Postgres;
+    options: {
+        host: string;
+        port: number;
+        user: string;
+        password: string;
+        database: string;
+    };
+};
+/**
+ * Collect all workers: system, optional examples, and user-provided.
+ */
+export declare function collectWorkers(startConfig: LTStartConfig): Promise<{
+    workers: WorkerEntry[];
+    builtinMcpServerFactories: Record<string, any>;
+}>;
+/**
+ * Run database migrations, start all workers, connect adapters,
+ * register MCP server factories, and seed data.
+ */
+export declare function startWorkers(startConfig: LTStartConfig, workers: WorkerEntry[], builtinMcpServerFactories: Record<string, any>): Promise<void>;
+export {};

package/build/start/workers.js

@@ -0,0 +1,144 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildConnection = buildConnection;
+exports.collectWorkers = collectWorkers;
+exports.startWorkers = startWorkers;
+const pg_1 = require("pg");
+const hotmesh_1 = require("@hotmeshio/hotmesh");
+const config_1 = require("../modules/config");
+const interceptor_1 = require("../services/interceptor");
+const registry_1 = require("../services/workers/registry");
+const logger_1 = require("../services/logger");
+const telemetry_1 = require("../services/telemetry");
+const events_1 = require("../services/events");
+const maintenance_1 = require("../services/maintenance");
+const cron_1 = require("../services/cron");
+const mcp_1 = require("../services/mcp");
+const yamlWorkflowWorkers = __importStar(require("../services/yaml-workflow/workers"));
+const migrate_1 = require("../services/db/migrate");
+/**
+ * Build the connection descriptor used by HotMesh / Durable.
+ */
+function buildConnection() {
+    return { class: pg_1.Client, options: config_1.postgres_options };
+}
+/**
+ * Collect all workers: system, optional examples, and user-provided.
+ */
+async function collectWorkers(startConfig) {
+    const { getSystemWorkers, builtinMcpServerFactories } = await Promise.resolve().then(() => __importStar(require('../system')));
+    const workers = [
+        ...getSystemWorkers(),
+        ...(startConfig.workers ?? []),
+    ];
+    logger_1.loggerRegistry.info('[long-tail] system workflows loaded');
+    if (startConfig.examples) {
+        const { exampleWorkers } = await Promise.resolve().then(() => __importStar(require('../examples')));
+        workers.push(...exampleWorkers);
+        logger_1.loggerRegistry.info('[long-tail] example workflows loaded');
+    }
+    return { workers, builtinMcpServerFactories };
+}
+/**
+ * Run database migrations, start all workers, connect adapters,
+ * register MCP server factories, and seed data.
+ */
+async function startWorkers(startConfig, workers, builtinMcpServerFactories) {
+    // Run migrations
+    logger_1.loggerRegistry.info('[long-tail] running migrations...');
+    await (0, migrate_1.migrate)();
+    const connection = buildConnection();
+    if (workers.length) {
+        // Connect telemetry before HotMesh starts
+        if (telemetry_1.telemetryRegistry.hasAdapter) {
+            await telemetry_1.telemetryRegistry.connect();
+        }
+        // Register LT interceptors
+        await (0, interceptor_1.registerLT)(connection, {
+            defaultRole: startConfig.interceptor?.defaultRole ?? 'reviewer',
+        });
+        // Start each worker
+        for (const w of workers) {
+            const worker = await hotmesh_1.Durable.Worker.create({
+                connection,
+                taskQueue: w.taskQueue,
+                workflow: w.workflow,
+            });
+            await worker.run();
+            (0, registry_1.registerWorker)(w.workflow.name, w.taskQueue);
+        }
+        logger_1.loggerRegistry.info(`[long-tail] workers started on queues: ${workers.map((w) => w.taskQueue).join(', ')}`);
+        // Connect event adapters
+        if (events_1.eventRegistry.hasAdapters) {
+            await events_1.eventRegistry.connect();
+            logger_1.loggerRegistry.info('[long-tail] event adapters connected');
+        }
+        // Start maintenance cron
+        if (maintenance_1.maintenanceRegistry.hasConfig) {
+            await maintenance_1.maintenanceRegistry.connect();
+            logger_1.loggerRegistry.info('[long-tail] maintenance cron started');
+        }
+        // Start workflow cron schedules
+        await cron_1.cronRegistry.connect();
+        // Connect MCP adapter
+        if (mcp_1.mcpRegistry.hasAdapter) {
+            await mcp_1.mcpRegistry.connect();
+            logger_1.loggerRegistry.info('[long-tail] MCP adapter connected');
+        }
+        // Register built-in MCP server factories from system/
+        const { registerBuiltinServer } = await Promise.resolve().then(() => __importStar(require('../services/mcp/client')));
+        for (const [name, factory] of Object.entries(builtinMcpServerFactories)) {
+            registerBuiltinServer(name, factory);
+        }
+        logger_1.loggerRegistry.info(`[long-tail] ${Object.keys(builtinMcpServerFactories).length} MCP server factories registered`);
+        // Register workers for active YAML (deterministic) workflows
+        await yamlWorkflowWorkers.registerAllActiveWorkers();
+    }
+    // Seed system MCP servers (always)
+    const { seedSystemMcpServers } = await Promise.resolve().then(() => __importStar(require('../system/seed')));
+    await seedSystemMcpServers();
+    // Ensure system bot account exists for cron/system-initiated workflows
+    const { ensureSystemBot } = await Promise.resolve().then(() => __importStar(require('../services/iam/bots')));
+    await ensureSystemBot().catch((err) => logger_1.loggerRegistry.warn(`[long-tail] system bot seed error: ${err.message}`));
+    // Seed example data when enabled
+    if (startConfig.examples) {
+        const { seedExamples } = await Promise.resolve().then(() => __importStar(require('../examples')));
+        const seedClient = new hotmesh_1.Durable.Client({ connection });
+        setTimeout(() => {
+            seedExamples(seedClient).catch((err) => logger_1.loggerRegistry.warn(`[long-tail] seed error: ${err.message}`));
+        }, 2000);
+    }
+}

package/build/system/activities/claude-code.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Execute a task using Claude Code CLI.
+ *
+ * Spawns `claude -p "<prompt>"` as a subprocess with a scoped environment.
+ * The API key is resolved from the auth context (delegation) or system env.
+ * Output is returned as structured JSON when possible.
+ *
+ * Authentication by proxy:
+ *   When called from a workflow with `_auth.userId`, the delegation token
+ *   identifies which user initiated the request. The activity uses this to:
+ *   - Log the requesting user for audit
+ *   - Scope the working directory (future: per-user sandboxing)
+ *   - Resolve the correct API key
+ */
+export declare function executeTask(args: {
+    prompt: string;
+    working_directory?: string;
+    allowed_tools?: string[];
+    max_turns?: number;
+    model?: string;
+    system_prompt?: string;
+    timeout_ms?: number;
+    api_key?: string;
+    credential_label?: string;
+    _auth?: {
+        userId?: string;
+        token?: string;
+    };
+}): Promise<{
+    result: string;
+    session_id?: string;
+    cost_usd?: number;
+    duration_ms: number;
+    is_error: boolean;
+    user_id?: string;
+}>;
+/**
+ * Check whether Claude Code CLI is installed and an API key is available.
+ *
+ * Returns availability status and version. Useful for workflows that need
+ * to decide whether to route to Claude Code or fall back to another tool.
+ */
+export declare function checkAvailability(args?: {
+    _auth?: {
+        userId?: string;
+        token?: string;
+    };
+}): Promise<{
+    available: boolean;
+    version?: string;
+    has_api_key: boolean;
+    has_oauth_session: boolean;
+    auth_method?: string;
+    user_id?: string;
+    error?: string;
+}>;

package/build/system/activities/claude-code.js

@@ -0,0 +1,258 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executeTask = executeTask;
+exports.checkAvailability = checkAvailability;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const logger_1 = require("../../services/logger");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+/** Maximum execution time for a Claude Code task (5 minutes) */
+const MAX_TIMEOUT_MS = 300_000;
+/** Default execution time (2 minutes) */
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Resolve the Anthropic credential for a given request.
+ *
+ * Returns a credential object or `null`. When `null`, the subprocess will
+ * fall back to Claude Code's own credential resolution (e.g., an OAuth
+ * session stored in the OS keychain from a prior `claude auth login`).
+ *
+ * Priority:
+ *   1. Explicit `api_key` in args (for testing / direct calls)
+ *   2. User's stored credential (from "Connect Anthropic" flow)
+ *   3. System-level CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY env var
+ *   4. null — let the CLI resolve credentials itself (local dev)
+ */
+async function resolveCredential(args) {
+    if (args.api_key) {
+        return {
+            value: args.api_key,
+            type: args.api_key.startsWith('sk-ant-oat') ? 'oauth_token' : 'api_key',
+        };
+    }
+    // Fetch the user's stored Anthropic credential (optionally by label)
+    if (args._auth?.userId) {
+        try {
+            const { getFreshAccessToken } = await Promise.resolve().then(() => __importStar(require('../../services/oauth')));
+            const token = await getFreshAccessToken(args._auth.userId, 'anthropic', args.credential_label);
+            if (token?.accessToken) {
+                const isOAuth = token.accessToken.startsWith('sk-ant-oat');
+                logger_1.loggerRegistry.info(`[lt-activity:claude-code] using stored Anthropic ${isOAuth ? 'OAuth token' : 'API key'}` +
+                    ` (label: ${token.label}) for user`);
+                return { value: token.accessToken, type: isOAuth ? 'oauth_token' : 'api_key' };
+            }
+        }
+        catch {
+            // No stored Anthropic connection for this user — fall through
+        }
+    }
+    // System-level env vars
+    if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
+        return { value: process.env.CLAUDE_CODE_OAUTH_TOKEN, type: 'oauth_token' };
+    }
+    if (process.env.ANTHROPIC_API_KEY) {
+        return { value: process.env.ANTHROPIC_API_KEY, type: 'api_key' };
+    }
+    return null;
+}
+/**
+ * Build the `claude` CLI command arguments for a prompt execution.
+ */
+function buildClaudeArgs(args) {
+    const cliArgs = ['-p', args.prompt, '--output-format', 'json'];
+    if (args.max_turns) {
+        cliArgs.push('--max-turns', String(args.max_turns));
+    }
+    if (args.model) {
+        cliArgs.push('--model', args.model);
+    }
+    if (args.system_prompt) {
+        cliArgs.push('--append-system-prompt', args.system_prompt);
+    }
+    if (args.allowed_tools?.length) {
+        for (const tool of args.allowed_tools) {
+            cliArgs.push('--allowedTools', tool);
+        }
+    }
+    return cliArgs;
+}
+// ── Activities ───────────────────────────────────────────────────────────────
+/**
+ * Execute a task using Claude Code CLI.
+ *
+ * Spawns `claude -p "<prompt>"` as a subprocess with a scoped environment.
+ * The API key is resolved from the auth context (delegation) or system env.
+ * Output is returned as structured JSON when possible.
+ *
+ * Authentication by proxy:
+ *   When called from a workflow with `_auth.userId`, the delegation token
+ *   identifies which user initiated the request. The activity uses this to:
+ *   - Log the requesting user for audit
+ *   - Scope the working directory (future: per-user sandboxing)
+ *   - Resolve the correct API key
+ */
+async function executeTask(args) {
+    const start = Date.now();
+    const userId = args._auth?.userId;
+    logger_1.loggerRegistry.info(`[lt-activity:claude-code] execute_task` +
+        (userId ? ` (user: ${userId})` : '') +
+        `: "${args.prompt.slice(0, 80)}${args.prompt.length > 80 ? '...' : ''}"`);
+    const credential = await resolveCredential(args);
+    const cliArgs = buildClaudeArgs(args);
+    const timeout = Math.min(args.timeout_ms ?? DEFAULT_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    // Build subprocess environment.
+    //
+    // Three modes:
+    //   1. OAuth token (sk-ant-oat...) — set CLAUDE_CODE_OAUTH_TOKEN
+    //      Uses the user's Claude subscription at flat rate.
+    //   2. API key (sk-ant-api...) — set ANTHROPIC_API_KEY
+    //      Billed per-token against their API account.
+    //   3. No credential — inherit parent env so the CLI can find its
+    //      own OAuth session in the OS keychain (local dev).
+    //
+    // In all cases CI=true disables interactive prompts.
+    let env;
+    if (credential) {
+        env = {
+            PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin',
+            HOME: process.env.HOME || '/root',
+            CI: 'true',
+        };
+        if (credential.type === 'oauth_token') {
+            env.CLAUDE_CODE_OAUTH_TOKEN = credential.value;
+        }
+        else {
+            env.ANTHROPIC_API_KEY = credential.value;
+        }
+    }
+    else {
+        env = { ...process.env, CI: 'true' };
+    }
+    try {
+        const { stdout, stderr } = await execFileAsync('claude', cliArgs, {
+            cwd: args.working_directory || process.cwd(),
+            env,
+            timeout,
+            maxBuffer: 10 * 1024 * 1024, // 10MB
+        });
+        const duration_ms = Date.now() - start;
+        // Try to parse structured JSON output
+        let result;
+        let session_id;
+        let cost_usd;
+        try {
+            const parsed = JSON.parse(stdout);
+            result = parsed.result ?? parsed.text ?? stdout;
+            session_id = parsed.session_id;
+            cost_usd = parsed.cost_usd;
+        }
+        catch {
+            result = stdout;
+        }
+        if (stderr) {
+            logger_1.loggerRegistry.warn(`[lt-activity:claude-code] stderr: ${stderr.slice(0, 200)}`);
+        }
+        logger_1.loggerRegistry.info(`[lt-activity:claude-code] completed in ${duration_ms}ms` +
+            (cost_usd ? ` ($${cost_usd.toFixed(4)})` : ''));
+        return { result, session_id, cost_usd, duration_ms, is_error: false, user_id: userId };
+    }
+    catch (err) {
+        const duration_ms = Date.now() - start;
+        // execFile throws on non-zero exit or timeout
+        const isTimeout = err.killed || err.code === 'ETIMEDOUT';
+        const message = isTimeout
+            ? `Claude Code timed out after ${timeout}ms`
+            : err.stderr || err.message;
+        logger_1.loggerRegistry.error(`[lt-activity:claude-code] failed: ${message}`);
+        return {
+            result: message,
+            duration_ms,
+            is_error: true,
+            user_id: userId,
+        };
+    }
+}
+/**
+ * Check whether Claude Code CLI is installed and an API key is available.
+ *
+ * Returns availability status and version. Useful for workflows that need
+ * to decide whether to route to Claude Code or fall back to another tool.
+ */
+async function checkAvailability(args = {}) {
+    const userId = args._auth?.userId;
+    const credential = await resolveCredential(args);
+    const has_api_key = !!credential;
+    // Check CLI availability and auth status
+    try {
+        const { stdout: versionOut } = await execFileAsync('claude', ['--version'], {
+            timeout: 5_000,
+            env: { PATH: process.env.PATH || '/usr/local/bin:/usr/bin:/bin' },
+        });
+        const version = versionOut.trim();
+        // Check if CLI has a valid auth session (OAuth or API key)
+        let auth_method;
+        let has_oauth_session = false;
+        try {
+            const { stdout: statusOut } = await execFileAsync('claude', ['auth', 'status'], {
+                timeout: 5_000,
+                env: { ...process.env },
+            });
+            const status = JSON.parse(statusOut);
+            has_oauth_session = status.loggedIn === true;
+            auth_method = status.authMethod;
+        }
+        catch {
+            // auth status failed — no OAuth session
+        }
+        return {
+            available: true,
+            version,
+            has_api_key,
+            has_oauth_session,
+            auth_method,
+            user_id: userId,
+        };
+    }
+    catch (err) {
+        return {
+            available: false,
+            has_api_key,
+            has_oauth_session: false,
+            user_id: userId,
+            error: `Claude Code CLI not found: ${err.message}`,
+        };
+    }
+}

package/build/system/activities/file-storage.d.ts

@@ -0,0 +1,31 @@
+export declare function writeFile(args: {
+    path: string;
+    content: string;
+    encoding?: 'utf-8' | 'base64';
+}): Promise<{
+    ref: string;
+    size: number;
+}>;
+export declare function readFile(args: {
+    path: string;
+    encoding?: 'utf-8' | 'base64';
+}): Promise<{
+    content: string;
+    size: number;
+    mime_type: string;
+}>;
+export declare function listFiles(args: {
+    directory?: string;
+    pattern?: string;
+}): Promise<{
+    files: Array<{
+        path: string;
+        size: number;
+        modified_at: string;
+    }>;
+}>;
+export declare function deleteFile(args: {
+    path: string;
+}): Promise<{
+    deleted: boolean;
+}>;