mu-harness 0.16.3

package/esm/harness/npm/src/plugin/types.d.ts

@@ -0,0 +1,11 @@
+import type { Tool } from 'mu-core';
+import type { Agent } from '../agents/index.js';
+import type { AgentSessionHooks } from '../hooks/index.js';
+import type { Skill } from '../skills/index.js';
+export interface Plugin {
+    name: string;
+    tools?: Tool[];
+    hooks?: AgentSessionHooks;
+    agents?: Agent[];
+    skills?: Skill[];
+}

package/esm/harness/npm/src/plugin/types.js

@@ -0,0 +1 @@
+export {};

package/esm/harness/npm/src/scheduler/command.d.ts

@@ -0,0 +1,3 @@
+import type { TaskStore } from './engine/index.js';
+import type { Command } from '../commands/index.js';
+export declare const createTasksCommand: (tasks: TaskStore) => Command;

package/esm/harness/npm/src/scheduler/command.js

@@ -0,0 +1,19 @@
+export const createTasksCommand = (tasks) => ({
+    name: 'tasks',
+    description: 'List scheduled tasks',
+    run: async () => {
+        const list = await tasks.list();
+        if (list.length === 0)
+            return { ok: true, output: 'No tasks scheduled.' };
+        const describe = (t) => {
+            const when = t.schedule.kind === 'cron'
+                ? t.schedule.expr
+                : t.schedule.kind === 'interval'
+                    ? `every ${t.schedule.ms}ms`
+                    : 'once';
+            const state = t.enabled ? when : `${when} (disabled)`;
+            return `- ${t.id} — ${t.skill} [${state}]`;
+        };
+        return { ok: true, output: list.map(describe).join('\n') };
+    },
+});

package/esm/harness/npm/src/scheduler/engine/index.d.ts

@@ -0,0 +1,3 @@
+export type { Schedule, Task, TaskInput, TaskResult, TaskRunner, TaskStore } from './types.js';
+export { createTaskStore } from './store.js';
+export { createScheduler, type Scheduler } from './scheduler.js';

package/esm/harness/npm/src/scheduler/engine/index.js

@@ -0,0 +1,2 @@
+export { createTaskStore } from './store.js';
+export { createScheduler } from './scheduler.js';

package/esm/harness/npm/src/scheduler/engine/scheduler.d.ts

@@ -0,0 +1,12 @@
+import type { Task, TaskRunner, TaskStore } from './types.js';
+export interface Scheduler {
+    start(): Promise<void>;
+    stop(): void;
+    reload(): Promise<void>;
+    runNow(id: string): Promise<void>;
+}
+export declare const createScheduler: (deps: {
+    store: TaskStore;
+    run: TaskRunner;
+    onError?: (error: unknown, task: Task) => void;
+}) => Scheduler;

package/esm/harness/npm/src/scheduler/engine/scheduler.js

@@ -0,0 +1,65 @@
+import { Cron } from 'croner';
+export const createScheduler = (deps) => {
+    const { store, run } = deps;
+    const crons = new Map();
+    const timers = new Map();
+    let started = false;
+    const fire = async (id) => {
+        const task = await store.get(id);
+        if (!task || !task.enabled)
+            return;
+        try {
+            const result = await run(task);
+            await store.update(id, { lastRun: Date.now(), lastResult: result });
+        }
+        catch (error) {
+            deps.onError?.(error, task);
+            const message = error instanceof Error ? error.message : String(error);
+            await store.update(id, { lastRun: Date.now(), lastResult: { ok: false, error: message } });
+        }
+        if (task.schedule.kind === 'once')
+            await store.update(id, { enabled: false });
+    };
+    const clear = () => {
+        for (const cron of crons.values())
+            cron.stop();
+        for (const timer of timers.values())
+            clearTimeout(timer);
+        crons.clear();
+        timers.clear();
+    };
+    const schedule = (task) => {
+        if (!task.enabled)
+            return;
+        const s = task.schedule;
+        if (s.kind === 'cron') {
+            crons.set(task.id, new Cron(s.expr, () => void fire(task.id)));
+        }
+        else if (s.kind === 'interval') {
+            timers.set(task.id, setInterval(() => void fire(task.id), s.ms));
+        }
+        else {
+            const delay = s.at ? Math.max(0, s.at - Date.now()) : 0;
+            timers.set(task.id, setTimeout(() => void fire(task.id), delay));
+        }
+    };
+    const reload = async () => {
+        clear();
+        if (!started)
+            return;
+        for (const task of await store.list())
+            schedule(task);
+    };
+    return {
+        start: async () => {
+            started = true;
+            await reload();
+        },
+        stop: () => {
+            started = false;
+            clear();
+        },
+        reload,
+        runNow: (id) => fire(id),
+    };
+};

package/esm/harness/npm/src/scheduler/engine/store.d.ts

@@ -0,0 +1,4 @@
+import type { TaskStore } from './types.js';
+export declare const createTaskStore: (options: {
+    dir: string;
+}) => TaskStore;

package/esm/harness/npm/src/scheduler/engine/store.js

@@ -0,0 +1,55 @@
+import { mkdir, readdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const createTaskStore = (options) => {
+    const { dir } = options;
+    const file = (id) => join(dir, `${id}.json`);
+    const read = async (id) => {
+        try {
+            return JSON.parse(await readFile(file(id), 'utf-8'));
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const write = async (task) => {
+        await mkdir(dir, { recursive: true });
+        await writeFile(file(task.id), JSON.stringify(task, null, 2), 'utf-8');
+    };
+    return {
+        list: async () => {
+            let entries;
+            try {
+                entries = await readdir(dir);
+            }
+            catch {
+                return [];
+            }
+            const tasks = [];
+            for (const name of entries.sort()) {
+                if (!name.endsWith('.json'))
+                    continue;
+                const task = await read(name.slice(0, -'.json'.length));
+                if (task)
+                    tasks.push(task);
+            }
+            return tasks;
+        },
+        get: read,
+        create: async (input) => {
+            const task = { ...input, id: crypto.randomUUID(), enabled: input.enabled ?? true, createdAt: Date.now() };
+            await write(task);
+            return task;
+        },
+        update: async (id, patch) => {
+            const task = await read(id);
+            if (!task)
+                return undefined;
+            const next = { ...task, ...patch, id: task.id };
+            await write(next);
+            return next;
+        },
+        remove: async (id) => {
+            await rm(file(id), { force: true });
+        },
+    };
+};

package/esm/harness/npm/src/scheduler/engine/types.d.ts

@@ -0,0 +1,37 @@
+export type Schedule = {
+    kind: 'cron';
+    expr: string;
+} | {
+    kind: 'interval';
+    ms: number;
+} | {
+    kind: 'once';
+    at?: number;
+};
+export interface TaskResult {
+    ok: boolean;
+    output?: string;
+    error?: string;
+}
+export interface Task {
+    id: string;
+    skill: string;
+    prompt: string;
+    agent?: string;
+    schedule: Schedule;
+    enabled: boolean;
+    createdAt: number;
+    lastRun?: number;
+    lastResult?: TaskResult;
+}
+export type TaskInput = Omit<Task, 'id' | 'enabled' | 'createdAt' | 'lastRun' | 'lastResult'> & {
+    enabled?: boolean;
+};
+export type TaskRunner = (task: Task) => Promise<TaskResult>;
+export interface TaskStore {
+    list(): Promise<Task[]>;
+    get(id: string): Promise<Task | undefined>;
+    create(input: TaskInput): Promise<Task>;
+    update(id: string, patch: Partial<Task>): Promise<Task | undefined>;
+    remove(id: string): Promise<void>;
+}

package/esm/harness/npm/src/scheduler/engine/types.js

@@ -0,0 +1 @@
+export {};

package/esm/harness/npm/src/scheduler/index.d.ts

@@ -0,0 +1,4 @@
+export type { Schedule, Task, TaskInput, TaskResult, TaskRunner, TaskStore } from './engine/index.js';
+export { createScheduler, createTaskStore, type Scheduler } from './engine/index.js';
+export { createScheduleTaskTool } from './tool.js';
+export { createTasksCommand } from './command.js';

package/esm/harness/npm/src/scheduler/index.js

@@ -0,0 +1,3 @@
+export { createScheduler, createTaskStore } from './engine/index.js';
+export { createScheduleTaskTool } from './tool.js';
+export { createTasksCommand } from './command.js';

package/esm/harness/npm/src/scheduler/tool.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from 'mu-core';
+import type { TaskStore } from './engine/index.js';
+import type { SkillRegistry } from '../skills/index.js';
+export declare const createScheduleTaskTool: (deps: {
+    store: TaskStore;
+    skills: SkillRegistry;
+    onChange?: () => void | Promise<void>;
+}) => Tool;

package/esm/harness/npm/src/scheduler/tool.js

@@ -0,0 +1,49 @@
+const toSchedule = (raw) => {
+    const { cron, everyMs, at } = (raw ?? {});
+    if (typeof cron === 'string' && cron.trim())
+        return { kind: 'cron', expr: cron.trim() };
+    if (typeof everyMs === 'number' && everyMs > 0)
+        return { kind: 'interval', ms: everyMs };
+    if (typeof at === 'number')
+        return { kind: 'once', at };
+    return undefined;
+};
+export const createScheduleTaskTool = (deps) => ({
+    name: 'schedule_task',
+    description: 'Persist a recurring (cron / heartbeat) or one-shot task that runs a sub-agent under a skill on a given prompt.',
+    prompt: 'Use `schedule_task` to register work that should run later or on a schedule: a `cron` expression, an `everyMs` heartbeat, or a one-shot `at` timestamp. It invokes a skill on a prompt, like `run_skill`.',
+    parameters: {
+        type: 'object',
+        properties: {
+            skill: { type: 'string', description: 'Skill name to run.' },
+            prompt: { type: 'string', description: 'The task prompt handed to the agent on each run.' },
+            agent: { type: 'string', description: 'Agent persona to run the skill as (defines its tools).' },
+            schedule: {
+                type: 'object',
+                description: 'Exactly one of: cron, everyMs, at.',
+                properties: {
+                    cron: { type: 'string', description: 'Cron expression, e.g. "0 9 * * *".' },
+                    everyMs: { type: 'number', description: 'Heartbeat interval in milliseconds.' },
+                    at: { type: 'number', description: 'One-shot epoch-ms timestamp (omit to run as soon as scheduled).' },
+                },
+                additionalProperties: false,
+            },
+        },
+        required: ['skill', 'prompt', 'agent', 'schedule'],
+        additionalProperties: false,
+    },
+    run: async (input) => {
+        const { skill, prompt, agent, schedule } = (input ?? {});
+        if (!skill || !prompt || !agent) {
+            return [{ type: 'text', text: 'Error: schedule_task requires `skill`, `prompt`, and `agent`.' }];
+        }
+        if (!deps.skills.get(skill))
+            return [{ type: 'text', text: `Error: unknown skill "${skill}".` }];
+        const parsed = toSchedule(schedule);
+        if (!parsed)
+            return [{ type: 'text', text: 'Error: schedule needs one of `cron`, `everyMs`, or `at`.' }];
+        const task = await deps.store.create({ skill, prompt, agent, schedule: parsed });
+        await deps.onChange?.();
+        return [{ type: 'text', text: `Scheduled task ${task.id} (${parsed.kind}) running skill "${skill}".` }];
+    },
+});

package/esm/harness/npm/src/session/agent-session.d.ts

@@ -0,0 +1,15 @@
+import { type Message, type Provider, type Tool } from 'mu-core';
+import { type AgentSessionHooks } from '../hooks/index.js';
+import { type Plugin } from '../plugin/index.js';
+import type { AgentSession } from './types.js';
+export interface AgentSessionConfig {
+    provider: Provider;
+    model: string;
+    tools?: Tool[];
+    hooks?: AgentSessionHooks;
+    plugins?: Plugin[];
+    system?: string;
+    id?: string;
+    messages?: Message[];
+}
+export declare const createAgentSession: (config: AgentSessionConfig) => AgentSession;

package/esm/harness/npm/src/session/agent-session.js

@@ -0,0 +1,82 @@
+import { run } from 'mu-core';
+import { createEmitter } from '../common/index.js';
+import { withHooks } from '../hooks/index.js';
+import { resolve } from '../plugin/index.js';
+const toMessage = (input) => ({
+    role: 'user',
+    content: typeof input === 'string' ? [{ type: 'text', text: input }] : input,
+});
+const systemMessage = (text) => ({ role: 'system', content: [{ type: 'text', text }] });
+const textOf = (message) => message.content.map((part) => (part.type === 'text' ? part.text : '')).join('');
+export const createAgentSession = (config) => {
+    const { provider } = config;
+    const { tools, hooks } = resolve(config);
+    const decorated = tools.map((tool) => withHooks(tool, hooks));
+    const id = config.id ?? crypto.randomUUID();
+    const messages = config.messages
+        ? [...config.messages]
+        : config.system
+            ? [{ role: 'system', content: [{ type: 'text', text: config.system }] }]
+            : [];
+    const emitter = createEmitter();
+    let started = false;
+    let running = false;
+    let controller;
+    const send = async (input) => {
+        if (running)
+            throw new Error('AgentSession: busy (a turn is already running)');
+        running = true;
+        const ac = new AbortController();
+        controller = ac;
+        try {
+            if (!started) {
+                started = true;
+                await hooks.sessionStart?.();
+            }
+            const message = toMessage(input);
+            messages.push(message);
+            emitter.emit({ type: 'turn_start', input: message });
+            const hasSystem = messages[0]?.role === 'system';
+            const system = hasSystem ? textOf(messages[0]) : '';
+            const prepared = await hooks.prepareRequest?.({ system, tools: decorated });
+            const callTools = prepared?.tools ?? decorated;
+            const baseSystem = prepared?.system ?? system;
+            const toolBlock = callTools.map((tool) => tool.prompt?.trim()).filter(Boolean).join('\n');
+            const effectiveSystem = [baseSystem, toolBlock].filter(Boolean).join('\n\n');
+            const body = hasSystem ? messages.slice(1) : messages;
+            const callMessages = effectiveSystem ? [systemMessage(effectiveSystem), ...body] : body;
+            const events = run({
+                provider,
+                model: config.model,
+                tools: callTools,
+                messages: callMessages,
+                signal: ac.signal,
+            });
+            for await (const event of events) {
+                if (event.type === 'message')
+                    messages.push(event.message);
+                emitter.emit(event);
+            }
+            emitter.emit({ type: 'turn_end' });
+        }
+        catch (error) {
+            if (ac.signal.aborted)
+                emitter.emit({ type: 'turn_end' });
+            else
+                emitter.emit({ type: 'error', error });
+        }
+        finally {
+            running = false;
+            controller = undefined;
+        }
+    };
+    return {
+        id,
+        get messages() {
+            return messages;
+        },
+        send,
+        abort: () => controller?.abort(),
+        subscribe: emitter.subscribe,
+    };
+};

package/esm/harness/npm/src/session/catalog.d.ts

@@ -0,0 +1,24 @@
+export interface SessionRecord {
+    id: string;
+    title?: string;
+    cwd?: string;
+    parentId?: string;
+    createdAt: number;
+}
+export interface SessionCatalog {
+    record(id: string, info: {
+        cwd?: string;
+        parentId?: string;
+    }): void;
+    setTitle(id: string, title: string): void;
+    get(id: string): SessionRecord | undefined;
+    list(filter?: {
+        cwd?: string;
+        parentId?: string;
+    }): SessionRecord[];
+    delete(id: string): void;
+    close(): void;
+}
+export declare const createSessionCatalog: ({ file }: {
+    file: string;
+}) => SessionCatalog;

package/esm/harness/npm/src/session/catalog.js

@@ -0,0 +1,55 @@
+import { mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+const toRecord = (row) => ({
+    id: row.id,
+    title: row.title ?? undefined,
+    cwd: row.cwd ?? undefined,
+    parentId: row.parent_id ?? undefined,
+    createdAt: row.created_at,
+});
+export const createSessionCatalog = ({ file }) => {
+    mkdirSync(dirname(file), { recursive: true });
+    const db = new DatabaseSync(file);
+    db.exec('CREATE TABLE IF NOT EXISTS sessions (id TEXT PRIMARY KEY, title TEXT, cwd TEXT, parent_id TEXT, created_at INTEGER NOT NULL)');
+    try {
+        db.exec('ALTER TABLE sessions ADD COLUMN parent_id TEXT');
+    }
+    catch {
+        void 0;
+    }
+    return {
+        record: (id, info) => {
+            db.prepare('INSERT OR IGNORE INTO sessions (id, cwd, parent_id, created_at) VALUES (?, ?, ?, ?)').run(id, info.cwd ?? null, info.parentId ?? null, Date.now());
+        },
+        setTitle: (id, title) => {
+            db.prepare('UPDATE sessions SET title = ? WHERE id = ?').run(title, id);
+        },
+        get: (id) => {
+            const row = db.prepare('SELECT * FROM sessions WHERE id = ?').get(id);
+            return row ? toRecord(row) : undefined;
+        },
+        list: (filter) => {
+            let sql = 'SELECT * FROM sessions';
+            const params = [];
+            if (filter?.parentId !== undefined) {
+                sql += ' WHERE parent_id = ?';
+                params.push(filter.parentId);
+            }
+            else {
+                sql += ' WHERE parent_id IS NULL';
+                if (filter?.cwd !== undefined) {
+                    sql += ' AND cwd = ?';
+                    params.push(filter.cwd);
+                }
+            }
+            sql += ' ORDER BY created_at DESC';
+            const rows = db.prepare(sql).all(...params);
+            return rows.map(toRecord);
+        },
+        delete: (id) => {
+            db.prepare('DELETE FROM sessions WHERE id = ?').run(id);
+        },
+        close: () => db.close(),
+    };
+};

package/esm/harness/npm/src/session/index.d.ts

@@ -0,0 +1,7 @@
+export type { AgentSession, AgentSessionEvent } from './types.js';
+export { type AgentSessionConfig, createAgentSession } from './agent-session.js';
+export { createSessionStore, type SessionStore, type StoredSession } from './store.js';
+export { createSessionCatalog, type SessionCatalog, type SessionRecord } from './catalog.js';
+export { persistTo } from './persist.js';
+export { createSessionManager, type ReviveInput, type SessionManager, type SessionManagerOptions } from './manager.js';
+export { cleanTitle, runTitler, type RunTitlerOptions, titleFallback } from './title.js';

package/esm/harness/npm/src/session/index.js

@@ -0,0 +1,6 @@
+export { createAgentSession } from './agent-session.js';
+export { createSessionStore } from './store.js';
+export { createSessionCatalog } from './catalog.js';
+export { persistTo } from './persist.js';
+export { createSessionManager } from './manager.js';
+export { cleanTitle, runTitler, titleFallback } from './title.js';

package/esm/harness/npm/src/session/manager.d.ts

@@ -0,0 +1,39 @@
+import type { Message } from 'mu-core';
+import type { SessionCatalog, SessionRecord } from './catalog.js';
+import type { SessionStore, StoredSession } from './store.js';
+import type { AgentSession } from './types.js';
+export interface ReviveInput {
+    id: string;
+    model?: string;
+    messages?: Message[];
+}
+export interface SessionManagerOptions {
+    store: SessionStore;
+    catalog: SessionCatalog;
+    revive(input: ReviveInput): AgentSession;
+    newId(): string;
+    cwd?: string;
+    title?(input: {
+        id: string;
+        text: string;
+    }): void;
+}
+export interface SessionManager {
+    create(options?: {
+        id?: string;
+        model?: string;
+        cwd?: string;
+    }): AgentSession;
+    open(id: string): Promise<AgentSession>;
+    fork(id: string, upToIndex: number): Promise<AgentSession>;
+    list(filter?: {
+        cwd?: string;
+        parentId?: string;
+    }): Promise<SessionRecord[]>;
+    get(id: string): Promise<SessionRecord | undefined>;
+    /** Read a session's stored messages by id without instantiating a live session. */
+    read(id: string): Promise<StoredSession | undefined>;
+    rename(id: string, title: string): void;
+    delete(id: string): Promise<void>;
+}
+export declare const createSessionManager: ({ store, catalog, revive, newId, cwd, title }: SessionManagerOptions) => SessionManager;

package/esm/harness/npm/src/session/manager.js

@@ -0,0 +1,62 @@
+import { persistTo } from './persist.js';
+const inputText = (input) => typeof input === 'string' ? input : input.map((part) => (part.type === 'text' ? part.text : '')).join('');
+const onFirstMessage = (session, fire) => {
+    let pending = !session.messages.some((message) => message.role === 'user');
+    return {
+        get id() {
+            return session.id;
+        },
+        get messages() {
+            return session.messages;
+        },
+        send: async (input) => {
+            if (pending) {
+                pending = false;
+                fire({ id: session.id, text: inputText(input) });
+            }
+            await session.send(input);
+        },
+        abort: session.abort,
+        subscribe: session.subscribe,
+    };
+};
+export const createSessionManager = ({ store, catalog, revive, newId, cwd, title }) => ({
+    create: (options) => {
+        const id = options?.id ?? newId();
+        catalog.record(id, { cwd: options?.cwd ?? cwd });
+        const session = persistTo(store, revive({ id, model: options?.model }));
+        return title ? onFirstMessage(session, title) : session;
+    },
+    open: async (id) => {
+        const stored = await store.load(id);
+        return persistTo(store, revive({ id: stored.id, messages: stored.messages }), stored.messages.length);
+    },
+    fork: async (id, upToIndex) => {
+        const stored = await store.load(id);
+        const messages = stored.messages.slice(0, upToIndex + 1);
+        const forkId = newId();
+        catalog.record(forkId, { cwd: catalog.get(id)?.cwd ?? cwd });
+        const session = revive({ id: forkId, messages });
+        await store.append(forkId, messages);
+        return persistTo(store, session, messages.length);
+    },
+    list: async (filter) => catalog.list(filter),
+    get: async (id) => catalog.get(id),
+    read: async (id) => {
+        try {
+            return await store.load(id);
+        }
+        catch {
+            return undefined;
+        }
+    },
+    rename: (id, title) => catalog.setTitle(id, title),
+    delete: async (id) => {
+        for (const child of catalog.list({ parentId: id })) {
+            await store.delete(child.id);
+            catalog.delete(child.id);
+        }
+        await store.delete(id);
+        catalog.delete(id);
+    },
+});

package/esm/harness/npm/src/session/persist.d.ts

@@ -0,0 +1,3 @@
+import type { SessionStore } from './store.js';
+import type { AgentSession } from './types.js';
+export declare const persistTo: (store: SessionStore, session: AgentSession, persisted?: number) => AgentSession;

package/esm/harness/npm/src/session/persist.js

@@ -0,0 +1,21 @@
+export const persistTo = (store, session, persisted = 0) => {
+    let count = persisted;
+    return {
+        get id() {
+            return session.id;
+        },
+        get messages() {
+            return session.messages;
+        },
+        send: async (input) => {
+            await session.send(input);
+            const all = session.messages;
+            if (all.length > count) {
+                await store.append(session.id, all.slice(count));
+                count = all.length;
+            }
+        },
+        abort: session.abort,
+        subscribe: session.subscribe,
+    };
+};

package/esm/harness/npm/src/session/store.d.ts

@@ -0,0 +1,13 @@
+import type { Message } from 'mu-core';
+export interface StoredSession {
+    id: string;
+    messages: Message[];
+}
+export interface SessionStore {
+    load(id: string): Promise<StoredSession>;
+    append(id: string, messages: Message[]): Promise<void>;
+    delete(id: string): Promise<void>;
+}
+export declare const createSessionStore: ({ dir }: {
+    dir: string;
+}) => SessionStore;