minionsai 0.1.0

package/dist/server/server/live-chat.js

@@ -0,0 +1,217 @@
+import { v4 as uuid } from 'uuid';
+const runs = new Map();
+const subscribers = new Map();
+const expiryTimers = new Map();
+const KEEPALIVE_INTERVAL_MS = 30_000;
+let keepaliveTimer = null;
+function cloneRun(run) {
+    return {
+        ...run,
+        messages: run.messages.map((message) => ({
+            ...message,
+            tools: message.tools ? message.tools.map((tool) => ({ ...tool })) : undefined,
+        })),
+        context: run.context ? { ...run.context } : null,
+    };
+}
+function runState(run) {
+    return {
+        taskId: run.taskId,
+        runId: run.runId,
+        status: run.status,
+        startedAt: run.startedAt,
+        updatedAt: run.updatedAt,
+    };
+}
+function assistantMessage(run) {
+    for (let i = run.messages.length - 1; i >= 0; i--) {
+        if (run.messages[i].role === 'assistant')
+            return run.messages[i];
+    }
+    const message = {
+        id: uuid(),
+        task_id: run.taskId,
+        role: 'assistant',
+        content: '',
+        created_at: Date.now(),
+    };
+    run.messages.push(message);
+    return message;
+}
+function mergeToolProgress(tools, event) {
+    const tool = {
+        tool: event.tool ?? 'tool',
+        status: event.status ?? 'running',
+        duration: event.duration,
+        label: event.label,
+    };
+    if (tool.status === 'running') {
+        tools.push(tool);
+        return;
+    }
+    for (let i = tools.length - 1; i >= 0; i--) {
+        if (tools[i].tool === tool.tool && tools[i].status === 'running') {
+            tools[i] = { ...tools[i], ...tool, label: tool.label ?? tools[i].label };
+            return;
+        }
+    }
+    tools.push(tool);
+}
+function writeEvent(res, event) {
+    try {
+        return res.write(`data: ${JSON.stringify(event)}\n\n`);
+    }
+    catch {
+        return false;
+    }
+}
+function startKeepalive() {
+    if (keepaliveTimer)
+        return;
+    keepaliveTimer = setInterval(() => {
+        for (const [taskId, taskSubscribers] of subscribers) {
+            for (const subscriber of taskSubscribers) {
+                try {
+                    subscriber.write(':keepalive\n\n');
+                }
+                catch {
+                    taskSubscribers.delete(subscriber);
+                }
+            }
+            if (taskSubscribers.size === 0)
+                subscribers.delete(taskId);
+        }
+        if (subscribers.size === 0 && keepaliveTimer) {
+            clearInterval(keepaliveTimer);
+            keepaliveTimer = null;
+        }
+    }, KEEPALIVE_INTERVAL_MS);
+}
+export function startRun(taskId, sessionId, userContent) {
+    const expiryTimer = expiryTimers.get(taskId);
+    if (expiryTimer) {
+        clearTimeout(expiryTimer);
+        expiryTimers.delete(taskId);
+    }
+    const now = Date.now();
+    const run = {
+        taskId,
+        runId: uuid(),
+        sessionId,
+        status: 'streaming',
+        startedAt: now,
+        updatedAt: now,
+        messages: [
+            {
+                id: uuid(),
+                task_id: taskId,
+                role: 'user',
+                content: userContent,
+                created_at: now,
+            },
+            {
+                id: uuid(),
+                task_id: taskId,
+                role: 'assistant',
+                content: '',
+                created_at: now,
+                tools: [],
+            },
+        ],
+    };
+    runs.set(taskId, run);
+    return cloneRun(run);
+}
+export function applyEvent(taskId, event) {
+    const run = runs.get(taskId);
+    if (!run)
+        return;
+    const assistant = assistantMessage(run);
+    if (event.type === 'text_delta' && event.content) {
+        assistant.content += event.content;
+    }
+    else if (event.type === 'thinking_delta' && event.content) {
+        assistant.thinking = `${assistant.thinking ?? ''}${event.content}`;
+    }
+    else if (event.type === 'tool_progress') {
+        if (!assistant.tools)
+            assistant.tools = [];
+        mergeToolProgress(assistant.tools, event);
+    }
+    else if (event.type === 'done') {
+        if (run.status !== 'error')
+            run.status = 'done';
+        if (event.sessionId)
+            run.sessionId = event.sessionId;
+        if (event.context !== undefined) {
+            run.context = event.context;
+        }
+    }
+    else if (event.type === 'error') {
+        const error = event.error || 'Unknown error';
+        run.status = 'error';
+        run.error = error;
+        if (!assistant.content.includes(`[Error: ${error}]`)) {
+            assistant.content = assistant.content
+                ? `${assistant.content}\n[Error: ${error}]`
+                : `[Error: ${error}]`;
+        }
+    }
+    run.updatedAt = Date.now();
+}
+export function getRun(taskId) {
+    const run = runs.get(taskId);
+    return run ? cloneRun(run) : undefined;
+}
+export function getRunContext(taskId) {
+    return runs.get(taskId)?.context;
+}
+export function getRunStatus(taskId) {
+    const run = runs.get(taskId);
+    return run ? runState(run) : undefined;
+}
+export function getRunStatuses() {
+    return Array.from(runs.values()).map(runState);
+}
+export function subscribe(taskId, res) {
+    let taskSubscribers = subscribers.get(taskId);
+    if (!taskSubscribers) {
+        taskSubscribers = new Set();
+        subscribers.set(taskId, taskSubscribers);
+    }
+    taskSubscribers.add(res);
+    res.on('close', () => {
+        taskSubscribers.delete(res);
+        if (taskSubscribers.size === 0)
+            subscribers.delete(taskId);
+    });
+    startKeepalive();
+}
+export function sendSnapshot(res, run) {
+    writeEvent(res, { type: 'snapshot', run });
+}
+export function broadcast(taskId, event) {
+    const taskSubscribers = subscribers.get(taskId);
+    if (!taskSubscribers)
+        return;
+    for (const subscriber of taskSubscribers) {
+        if (!writeEvent(subscriber, event))
+            taskSubscribers.delete(subscriber);
+    }
+    if (taskSubscribers.size === 0)
+        subscribers.delete(taskId);
+}
+export function finishRun(taskId, ttlMs, runId) {
+    if (!runs.has(taskId))
+        return;
+    const expiryTimer = expiryTimers.get(taskId);
+    if (expiryTimer)
+        clearTimeout(expiryTimer);
+    const timer = setTimeout(() => {
+        if (runs.get(taskId)?.runId === runId)
+            runs.delete(taskId);
+        expiryTimers.delete(taskId);
+    }, ttlMs);
+    timer.unref();
+    expiryTimers.set(taskId, timer);
+}

package/dist/server/server/paths.d.ts

@@ -0,0 +1,7 @@
+export declare function expandHomePrefix(value: string): string;
+export declare function resolveMinionsHome(): string;
+export declare function resolveMinionsDataDir(): string;
+export declare function resolveMinionsLogsDir(): string;
+export declare function resolveMinionsWorkspaceDir(): string;
+export declare function resolveMinionsDbPath(): string;
+export declare function ensureMinionsStateDirs(): void;

package/dist/server/server/paths.js

@@ -0,0 +1,39 @@
+import { mkdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+export function expandHomePrefix(value) {
+    if (value === '~')
+        return homedir();
+    if (value.startsWith('~/'))
+        return join(homedir(), value.slice(2));
+    return value;
+}
+function resolveHomeAwarePath(value) {
+    return resolve(expandHomePrefix(value));
+}
+export function resolveMinionsHome() {
+    const configured = process.env.MINIONS_HOME?.trim();
+    return resolveHomeAwarePath(configured || '~/.minions');
+}
+export function resolveMinionsDataDir() {
+    return join(resolveMinionsHome(), 'data');
+}
+export function resolveMinionsLogsDir() {
+    return join(resolveMinionsHome(), 'logs');
+}
+export function resolveMinionsWorkspaceDir() {
+    return join(resolveMinionsHome(), 'workspace');
+}
+export function resolveMinionsDbPath() {
+    const configured = process.env.DB_PATH?.trim();
+    if (configured)
+        return resolveHomeAwarePath(configured);
+    return join(resolveMinionsDataDir(), 'minions.db');
+}
+export function ensureMinionsStateDirs() {
+    const dbPath = resolveMinionsDbPath();
+    mkdirSync(resolveMinionsDataDir(), { recursive: true });
+    mkdirSync(resolveMinionsLogsDir(), { recursive: true });
+    mkdirSync(resolveMinionsWorkspaceDir(), { recursive: true });
+    mkdirSync(dirname(dbPath), { recursive: true });
+}

package/dist/server/server/prompts/task-agent.d.ts

@@ -0,0 +1 @@
+export declare const TASK_AGENT_SYSTEM_PROMPT = "<task_agent>\n  <role>\n    You are an autonomous task agent. A user has given you a task to accomplish.\n  </role>\n\n  <responsibilities>\n    <responsibility name=\"understand\">\n      Read the task carefully. Identify anything unclear, ambiguous, or underspecified.\n    </responsibility>\n    <responsibility name=\"clarify\">\n      Before doing work, make sure you fully understand what the user wants. Ask focused clarifying questions about scope, constraints, expected outcomes, edge cases, or anything else you are uncertain about. Do not assume when the uncertainty matters. The user is available to answer. Keep asking until you are confident you understand the task correctly.\n    </responsibility>\n    <responsibility name=\"execute\">\n      Once you and the user are aligned, choose the best execution strategy. Do the work yourself in this session if it is straightforward. Create a child session if you need a dedicated sub-agent for complex sub-work. Set up a cron job when the work is recurring, periodic, routine, or better handled as durable batches over time. You have full autonomy to use the tools and approach that best accomplish the task.\n    </responsibility>\n  </responsibilities>\n\n  <guidelines>\n    <guideline>Understand first, act second. Do not start executing until you are confident you know what the user wants.</guideline>\n    <guideline>When clarifying, ask focused questions rather than a long wall of questions. A natural back-and-forth conversation is ideal.</guideline>\n    <guideline>When the user asks for a cron job, schedule, routine, recurring task, monitor, daily/weekly task, or similar repeated work, default to a Hermes cron job using the available cronjob tooling. Do not use Linux cron, systemd timers, or host OS schedulers unless the user explicitly asks for them.</guideline>\n    <guideline>For lead generation, prospecting, and large list processing, prefer a small sample or validation run first. If the user wants more than a small one-off result, prefer a cron job with a self-contained prompt, sensible batch size, output/checkpoint location, and schedule.</guideline>\n    <guideline>Keep the user informed of meaningful progress in your responses.</guideline>\n    <guideline>You have project-specific skills under the \"minions\" category in your skills index. Before executing a task, check if any minions skill is relevant and load it \u2014 these encode proven workflows tailored to this system.</guideline>\n  </guidelines>\n</task_agent>";

package/dist/server/server/prompts/task-agent.js

@@ -0,0 +1,26 @@
+export const TASK_AGENT_SYSTEM_PROMPT = `<task_agent>
+  <role>
+    You are an autonomous task agent. A user has given you a task to accomplish.
+  </role>
+
+  <responsibilities>
+    <responsibility name="understand">
+      Read the task carefully. Identify anything unclear, ambiguous, or underspecified.
+    </responsibility>
+    <responsibility name="clarify">
+      Before doing work, make sure you fully understand what the user wants. Ask focused clarifying questions about scope, constraints, expected outcomes, edge cases, or anything else you are uncertain about. Do not assume when the uncertainty matters. The user is available to answer. Keep asking until you are confident you understand the task correctly.
+    </responsibility>
+    <responsibility name="execute">
+      Once you and the user are aligned, choose the best execution strategy. Do the work yourself in this session if it is straightforward. Create a child session if you need a dedicated sub-agent for complex sub-work. Set up a cron job when the work is recurring, periodic, routine, or better handled as durable batches over time. You have full autonomy to use the tools and approach that best accomplish the task.
+    </responsibility>
+  </responsibilities>
+
+  <guidelines>
+    <guideline>Understand first, act second. Do not start executing until you are confident you know what the user wants.</guideline>
+    <guideline>When clarifying, ask focused questions rather than a long wall of questions. A natural back-and-forth conversation is ideal.</guideline>
+    <guideline>When the user asks for a cron job, schedule, routine, recurring task, monitor, daily/weekly task, or similar repeated work, default to a Hermes cron job using the available cronjob tooling. Do not use Linux cron, systemd timers, or host OS schedulers unless the user explicitly asks for them.</guideline>
+    <guideline>For lead generation, prospecting, and large list processing, prefer a small sample or validation run first. If the user wants more than a small one-off result, prefer a cron job with a self-contained prompt, sensible batch size, output/checkpoint location, and schedule.</guideline>
+    <guideline>Keep the user informed of meaningful progress in your responses.</guideline>
+    <guideline>You have project-specific skills under the "minions" category in your skills index. Before executing a task, check if any minions skill is relevant and load it — these encode proven workflows tailored to this system.</guideline>
+  </guidelines>
+</task_agent>`;

package/dist/server/server/routes/agent.d.ts

@@ -0,0 +1,4 @@
+import { Router } from 'express';
+import type { HermesWorkerAdapter } from '../adapters/hermes-worker.js';
+export declare function createAgentRouter(adapter: HermesWorkerAdapter): Router;
+export declare function createTaskAgentSettingsRouter(adapter: HermesWorkerAdapter): Router;

package/dist/server/server/routes/agent.js

@@ -0,0 +1,94 @@
+import { Router } from 'express';
+import { getTask } from '../db/queries.js';
+import { isRecord, toErrorMessage } from '../errors.js';
+import { taskRunSettings } from '../agent-settings.js';
+import { REASONING_EFFORTS } from '../../shared/types.js';
+const FALLBACK_DEFAULTS = {
+    provider: null,
+    model: null,
+    baseUrl: null,
+    apiMode: null,
+    reasoningEffort: 'medium',
+    showReasoning: true,
+};
+async function defaultsForSettings(adapter) {
+    try {
+        return await adapter.getDefaults();
+    }
+    catch {
+        return FALLBACK_DEFAULTS;
+    }
+}
+function buildTaskSettings(task, defaults) {
+    const overrides = taskRunSettings(task);
+    return {
+        task: {
+            model: overrides.model ?? null,
+            reasoningEffort: overrides.reasoningEffort ?? null,
+        },
+        defaults,
+        effective: {
+            model: overrides.model ?? defaults.model,
+            provider: defaults.provider,
+            reasoningEffort: overrides.reasoningEffort ?? defaults.reasoningEffort,
+        },
+    };
+}
+export function createAgentRouter(adapter) {
+    const router = Router();
+    router.get('/defaults', async (_req, res) => {
+        try {
+            res.json(await adapter.getDefaults());
+        }
+        catch (error) {
+            res.status(503).json({ error: toErrorMessage(error, 'Hermes worker unavailable') });
+        }
+    });
+    router.patch('/defaults', async (req, res) => {
+        if (!isRecord(req.body)) {
+            return res.status(400).json({ error: 'Request body is required' });
+        }
+        const updates = {};
+        if ('model' in req.body) {
+            const model = req.body.model;
+            if (model !== null && typeof model !== 'string') {
+                return res.status(400).json({ error: 'model must be a string or null' });
+            }
+            updates.model = typeof model === 'string' ? model.trim() || null : null;
+        }
+        if ('reasoningEffort' in req.body) {
+            const effort = req.body.reasoningEffort;
+            if (effort !== null && (typeof effort !== 'string' || !REASONING_EFFORTS.includes(effort))) {
+                return res.status(400).json({ error: `reasoningEffort must be one of: ${REASONING_EFFORTS.join(', ')}` });
+            }
+            updates.reasoningEffort = effort;
+        }
+        try {
+            const defaults = await adapter.setDefaults(updates);
+            res.json(defaults);
+        }
+        catch (error) {
+            res.status(503).json({ error: toErrorMessage(error, 'Failed to update defaults') });
+        }
+    });
+    router.get('/models', async (_req, res) => {
+        try {
+            res.json(await adapter.getModels());
+        }
+        catch (error) {
+            res.status(503).json({ error: toErrorMessage(error, 'Hermes worker unavailable') });
+        }
+    });
+    return router;
+}
+export function createTaskAgentSettingsRouter(adapter) {
+    const router = Router();
+    router.get('/:id/agent-settings', async (req, res) => {
+        const task = getTask(req.params.id);
+        if (!task)
+            return res.status(404).json({ error: 'Task not found' });
+        const defaults = await defaultsForSettings(adapter);
+        res.json(buildTaskSettings(task, defaults));
+    });
+    return router;
+}

package/dist/server/server/routes/chat.d.ts

@@ -0,0 +1 @@
+export declare const chatRouter: import("express-serve-static-core").Router;

package/dist/server/server/routes/chat.js

@@ -0,0 +1,177 @@
+import { Router } from 'express';
+import { contextFromTask, getTask, updateTask, touchTask, recordAgentResponse } from '../db/queries.js';
+import { adapter } from '../app.js';
+import { broadcast, initSSE } from '../events.js';
+import { applyEvent, broadcast as broadcastLive, finishRun, getRun, getRunContext, getRunStatus, sendSnapshot, startRun, subscribe, } from '../live-chat.js';
+import { taskRunSettings, parseRunSettingsBody } from '../agent-settings.js';
+import { TASK_AGENT_SYSTEM_PROMPT } from '../prompts/task-agent.js';
+import { toErrorMessage } from '../errors.js';
+export const chatRouter = Router();
+function hasNoSession(task) {
+    if (task.last_agent_response_at !== null)
+        return false;
+    return getRunStatus(task.id)?.status !== 'streaming';
+}
+chatRouter.get('/:id/messages', async (req, res) => {
+    const task = getTask(req.params.id);
+    if (!task)
+        return res.status(404).json({ error: 'Task not found' });
+    const liveContext = getRunContext(task.id);
+    const context = liveContext !== undefined ? liveContext : contextFromTask(task);
+    if (hasNoSession(task))
+        return res.json({ messages: [], context });
+    try {
+        const messages = await adapter.getMessages(task.id, task.id);
+        res.json({ messages, context });
+    }
+    catch (error) {
+        res.status(503).json({ error: toErrorMessage(error, 'Hermes session history unavailable') });
+    }
+});
+chatRouter.get('/:id/session', async (req, res) => {
+    const task = getTask(req.params.id);
+    if (!task)
+        return res.status(404).json({ error: 'Task not found' });
+    if (hasNoSession(task))
+        return res.json({ session: null });
+    try {
+        const session = await adapter.getSessionMetadata(task.id);
+        res.json({ session });
+    }
+    catch (error) {
+        res.status(503).json({ error: toErrorMessage(error, 'Hermes session metadata unavailable') });
+    }
+});
+const DONE_SNAPSHOT_TTL_MS = 30_000;
+const ERROR_SNAPSHOT_TTL_MS = 5 * 60_000;
+async function judgeTaskCompletion(task, responseText, responseAt) {
+    if (!responseText.trim() || task.status !== 'in_progress')
+        return;
+    try {
+        const result = await adapter.judgeCompletion(task.title, task.description, responseText);
+        if (result.done) {
+            const current = getTask(task.id);
+            if (!current ||
+                current.status !== 'in_progress' ||
+                current.last_agent_response_at !== responseAt) {
+                return;
+            }
+            const updated = updateTask(task.id, { status: 'in_review' });
+            if (updated)
+                broadcast({ type: 'task_updated', task: updated });
+        }
+    }
+    catch {
+        // Judge failure is non-critical — leave task as-is
+    }
+}
+async function consumeChatRun(runTask, sessionId, content, runId) {
+    let sawDone = false;
+    let doneContext;
+    let responseText = '';
+    try {
+        const stream = adapter.chatStream(sessionId, content, {
+            systemMessage: TASK_AGENT_SYSTEM_PROMPT,
+            settings: taskRunSettings(runTask),
+            task: { id: runTask.id, title: runTask.title },
+        });
+        for await (const event of stream) {
+            if (event.type === 'text_delta' && responseText.length < 4200)
+                responseText += event.content ?? '';
+            if (event.type === 'done') {
+                sawDone = true;
+                doneContext = event.context;
+            }
+            applyEvent(runTask.id, event);
+            broadcastLive(runTask.id, event);
+        }
+    }
+    catch (error) {
+        const event = { type: 'error', error: toErrorMessage(error, 'Hermes chat stream failed') };
+        applyEvent(runTask.id, event);
+        broadcastLive(runTask.id, event);
+    }
+    finally {
+        const currentRun = getRunStatus(runTask.id);
+        if (!sawDone && currentRun?.status === 'streaming') {
+            const event = { type: 'done', sessionId };
+            sawDone = true;
+            applyEvent(runTask.id, event);
+            broadcastLive(runTask.id, event);
+        }
+        const finishedRun = getRunStatus(runTask.id);
+        if (finishedRun)
+            broadcast({ type: 'task_run_updated', run: finishedRun });
+        if (sawDone && finishedRun?.status === 'done') {
+            const responseAt = Date.now();
+            const updated = recordAgentResponse(runTask.id, responseAt, doneContext ?? null);
+            if (updated)
+                broadcast({ type: 'task_updated', task: updated });
+            void judgeTaskCompletion(runTask, responseText, responseAt);
+        }
+        else {
+            touchTask(runTask.id);
+        }
+        const ttl = finishedRun?.status === 'error' ? ERROR_SNAPSHOT_TTL_MS : DONE_SNAPSHOT_TTL_MS;
+        finishRun(runTask.id, ttl, runId);
+    }
+}
+chatRouter.post('/:id/messages', async (req, res) => {
+    const task = getTask(req.params.id);
+    if (!task)
+        return res.status(404).json({ error: 'Task not found' });
+    const { content } = req.body;
+    if (!content || typeof content !== 'string') {
+        return res.status(400).json({ error: 'content is required' });
+    }
+    let runSettings;
+    try {
+        runSettings = parseRunSettingsBody(req.body);
+    }
+    catch (error) {
+        return res.status(400).json({ error: toErrorMessage(error, 'Invalid run settings') });
+    }
+    const activeRun = getRunStatus(task.id);
+    if (activeRun?.status === 'streaming') {
+        return res.status(409).json({ error: 'This task already has a message in progress' });
+    }
+    let runTask = task;
+    const taskUpdates = {};
+    if (runSettings.hasFields) {
+        const { taskFields } = runSettings;
+        if (taskFields.agent_model !== undefined && taskFields.agent_model !== task.agent_model) {
+            taskUpdates.agent_model = taskFields.agent_model;
+        }
+        if (taskFields.reasoning_effort !== undefined && taskFields.reasoning_effort !== task.reasoning_effort) {
+            taskUpdates.reasoning_effort = taskFields.reasoning_effort;
+        }
+    }
+    if (task.status === 'in_review') {
+        taskUpdates.status = 'in_progress';
+    }
+    if (Object.keys(taskUpdates).length > 0) {
+        const updated = updateTask(task.id, taskUpdates);
+        if (!updated)
+            return res.status(404).json({ error: 'Task not found' });
+        runTask = updated;
+        broadcast({ type: 'task_updated', task: updated });
+    }
+    const sessionId = runTask.id;
+    const run = startRun(runTask.id, sessionId, content);
+    const startedRun = getRunStatus(runTask.id);
+    if (startedRun)
+        broadcast({ type: 'task_run_updated', run: startedRun });
+    broadcastLive(runTask.id, { type: 'snapshot', run });
+    void consumeChatRun(runTask, sessionId, content, run.runId);
+    res.status(202).json({ runId: run.runId, run });
+});
+chatRouter.get('/:id/live', (req, res) => {
+    const task = getTask(req.params.id);
+    if (!task)
+        return res.status(404).json({ error: 'Task not found' });
+    initSSE(res);
+    subscribe(task.id, res);
+    const run = getRun(task.id);
+    if (run)
+        sendSnapshot(res, run);
+});

package/dist/server/server/routes/cron.d.ts

@@ -0,0 +1,4 @@
+import { Router } from 'express';
+import type { HermesWorkerAdapter } from '../adapters/hermes-worker.js';
+export declare function createCronRouter(adapter: HermesWorkerAdapter): Router;
+export declare function createTaskCronRouter(adapter: HermesWorkerAdapter): Router;