@some-useful-agents/core 0.2.0 → 0.3.1

package/dist/index.d.ts

@@ -8,4 +8,6 @@ export * from './chain-resolver.js';
 export * from './chain-executor.js';
 export * from './env-builder.js';
 export * from './secrets-store.js';
+export * from './scheduler.js';
+export * from './llm-invoker.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/dist/index.js

@@ -8,4 +8,6 @@ export * from './chain-resolver.js';
 export * from './chain-executor.js';
 export * from './env-builder.js';
 export * from './secrets-store.js';
+export * from './scheduler.js';
+export * from './llm-invoker.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC"}

package/dist/llm-invoker.d.ts

@@ -0,0 +1,29 @@
+export type LlmProvider = 'claude' | 'codex';
+export interface LlmInvokeOptions {
+    prompt: string;
+    provider: LlmProvider;
+    timeoutMs?: number;
+}
+export interface LlmInvokeResult {
+    output: string;
+    error?: string;
+    exitCode: number;
+}
+export interface LlmAvailability {
+    claude: {
+        installed: boolean;
+        version?: string;
+    };
+    codex: {
+        installed: boolean;
+        version?: string;
+    };
+}
+/** Detect which LLM CLIs are installed on the host. Fast, synchronous. */
+export declare function detectLlms(): LlmAvailability;
+/**
+ * Invoke an LLM CLI with a prompt, return its stdout.
+ * Uses --print (claude) / exec -s read-only (codex).
+ */
+export declare function invokeLlm(options: LlmInvokeOptions): Promise<LlmInvokeResult>;
+//# sourceMappingURL=llm-invoker.d.ts.map

package/dist/llm-invoker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-invoker.d.ts","sourceRoot":"","sources":["../src/llm-invoker.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,OAAO,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,WAAW,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,KAAK,EAAE;QAAE,SAAS,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED,0EAA0E;AAC1E,wBAAgB,UAAU,IAAI,eAAe,CAqB5C;AAED;;;GAGG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsD7E"}

package/dist/llm-invoker.js

@@ -0,0 +1,77 @@
+import { spawn, execSync } from 'node:child_process';
+/** Detect which LLM CLIs are installed on the host. Fast, synchronous. */
+export function detectLlms() {
+    const result = {
+        claude: { installed: false },
+        codex: { installed: false },
+    };
+    try {
+        const v = execSync('claude --version', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        result.claude = { installed: true, version: v };
+    }
+    catch {
+        // not installed or not on PATH
+    }
+    try {
+        const v = execSync('codex --version', { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+        result.codex = { installed: true, version: v };
+    }
+    catch {
+        // not installed
+    }
+    return result;
+}
+/**
+ * Invoke an LLM CLI with a prompt, return its stdout.
+ * Uses --print (claude) / exec -s read-only (codex).
+ */
+export function invokeLlm(options) {
+    const { prompt, provider, timeoutMs = 60_000 } = options;
+    return new Promise((resolve) => {
+        const args = provider === 'claude'
+            ? ['--print', prompt]
+            : ['exec', '-s', 'read-only', prompt];
+        const child = spawn(provider, args, {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let stdout = '';
+        let stderr = '';
+        let killed = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill('SIGTERM');
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => { stdout += chunk.toString(); });
+        child.stderr.on('data', (chunk) => { stderr += chunk.toString(); });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            if (killed) {
+                resolve({
+                    output: stdout,
+                    exitCode: 124,
+                    error: `${provider} timed out after ${timeoutMs / 1000}s`,
+                });
+                return;
+            }
+            resolve({
+                output: stdout,
+                exitCode: code ?? 1,
+                error: code !== 0 ? (stderr || `${provider} exited with code ${code}`) : undefined,
+            });
+        });
+        child.on('error', (err) => {
+            clearTimeout(timer);
+            if (err.message.includes('ENOENT')) {
+                resolve({
+                    output: '',
+                    exitCode: 127,
+                    error: `${provider} CLI not found on PATH. Install it and retry.`,
+                });
+            }
+            else {
+                resolve({ output: '', exitCode: 127, error: err.message });
+            }
+        });
+    });
+}
+//# sourceMappingURL=llm-invoker.js.map

package/dist/llm-invoker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-invoker.js","sourceRoot":"","sources":["../src/llm-invoker.ts"],"names":[],"mappings":"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"}

package/dist/llm-invoker.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=llm-invoker.test.d.ts.map

package/dist/llm-invoker.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-invoker.test.d.ts","sourceRoot":"","sources":["../src/llm-invoker.test.ts"],"names":[],"mappings":""}

package/dist/llm-invoker.test.js

@@ -0,0 +1,45 @@
+import { describe, it, expect } from 'vitest';
+import { detectLlms, invokeLlm } from './llm-invoker.js';
+describe('detectLlms', () => {
+    it('returns a structure with both provider slots', () => {
+        const avail = detectLlms();
+        expect(avail).toHaveProperty('claude');
+        expect(avail).toHaveProperty('codex');
+        expect(avail.claude).toHaveProperty('installed');
+        expect(avail.codex).toHaveProperty('installed');
+    });
+});
+describe('invokeLlm', () => {
+    it('returns exit code 127 with ENOENT message when CLI missing', async () => {
+        // Call with a provider name that is definitely not on PATH by spawning
+        // a bogus binary through the real code path. We can't mock spawn here
+        // without a heavy setup, so we trust the ENOENT branch by invoking a
+        // non-existent CLI via a shim: the spawn in llm-invoker uses the literal
+        // provider name, so we test by renaming the PATH lookup via env.
+        const result = await invokeLlm({
+            provider: 'claude',
+            prompt: 'test',
+            timeoutMs: 1000,
+        });
+        // Either: claude exists and returned some exit code, OR it didn't and we got 127.
+        // The test is that we got a well-formed result object either way.
+        expect(result).toHaveProperty('output');
+        expect(result).toHaveProperty('exitCode');
+        expect(typeof result.exitCode).toBe('number');
+    });
+    it('respects the timeout option', async () => {
+        // If claude is installed and hangs we should get exit 124. If it's not
+        // installed we'll get 127 quickly. Either way, the call returns within
+        // a reasonable bound.
+        const start = Date.now();
+        await invokeLlm({
+            provider: 'codex',
+            prompt: 'hang forever please',
+            timeoutMs: 500,
+        });
+        const elapsed = Date.now() - start;
+        // Either we timed out fast (500ms+some) or the CLI is missing and errored quickly
+        expect(elapsed).toBeLessThan(3000);
+    });
+});
+//# sourceMappingURL=llm-invoker.test.js.map

package/dist/llm-invoker.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"llm-invoker.test.js","sourceRoot":"","sources":["../src/llm-invoker.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAEzD,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,8CAA8C,EAAE,GAAG,EAAE;QACtD,MAAM,KAAK,GAAG,UAAU,EAAE,CAAC;QAC3B,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACvC,MAAM,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC;QACtC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,cAAc,CAAC,WAAW,CAAC,CAAC;IAClD,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC;AAEH,QAAQ,CAAC,WAAW,EAAE,GAAG,EAAE;IACzB,EAAE,CAAC,4DAA4D,EAAE,KAAK,IAAI,EAAE;QAC1E,uEAAuE;QACvE,sEAAsE;QACtE,qEAAqE;QACrE,yEAAyE;QACzE,iEAAiE;QACjE,MAAM,MAAM,GAAG,MAAM,SAAS,CAAC;YAC7B,QAAQ,EAAE,QAAQ;YAClB,MAAM,EAAE,MAAM;YACd,SAAS,EAAE,IAAI;SAChB,CAAC,CAAC;QACH,kFAAkF;QAClF,kEAAkE;QAClE,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;QACxC,MAAM,CAAC,MAAM,CAAC,CAAC,cAAc,CAAC,UAAU,CAAC,CAAC;QAC1C,MAAM,CAAC,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IAEH,EAAE,CAAC,6BAA6B,EAAE,KAAK,IAAI,EAAE;QAC3C,uEAAuE;QACvE,uEAAuE;QACvE,sBAAsB;QACtB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACzB,MAAM,SAAS,CAAC;YACd,QAAQ,EAAE,OAAO;YACjB,MAAM,EAAE,qBAAqB;YAC7B,SAAS,EAAE,GAAG;SACf,CAAC,CAAC;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC;QACnC,kFAAkF;QAClF,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;IACrC,CAAC,CAAC,CAAC;AACL,CAAC,CAAC,CAAC"}

package/dist/scheduler.d.ts

@@ -0,0 +1,28 @@
+import type { AgentDefinition, Provider } from './types.js';
+export interface ScheduledAgentEntry {
+    agent: AgentDefinition;
+    schedule: string;
+}
+export interface LocalSchedulerOptions {
+    provider: Provider;
+    agents: Map<string, AgentDefinition>;
+    onFire?: (agent: AgentDefinition, runId: string) => void;
+    onError?: (agent: AgentDefinition, error: Error) => void;
+}
+export declare class LocalScheduler {
+    private tasks;
+    private readonly provider;
+    private readonly agents;
+    private readonly onFire?;
+    private readonly onError?;
+    constructor(options: LocalSchedulerOptions);
+    /** Return entries with a `schedule` field, validated. Throws on invalid cron strings. */
+    getScheduledAgents(): ScheduledAgentEntry[];
+    /** Register cron tasks for every agent with a schedule. */
+    start(): ScheduledAgentEntry[];
+    /** Stop all tasks and release resources. */
+    stop(): void;
+    /** True if a cron expression parses cleanly. */
+    static isValid(expression: string): boolean;
+}
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5D,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,eAAe,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,QAAQ,CAAC;IACnB,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACrC,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IACzD,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,KAAK,KAAK,IAAI,CAAC;CAC1D;AAED,qBAAa,cAAc;IACzB,OAAO,CAAC,KAAK,CAAmE;IAChF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;IACpC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAkD;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAiD;gBAE9D,OAAO,EAAE,qBAAqB;IAO1C,yFAAyF;IACzF,kBAAkB,IAAI,mBAAmB,EAAE;IAc3C,2DAA2D;IAC3D,KAAK,IAAI,mBAAmB,EAAE;IAgB9B,4CAA4C;IAC5C,IAAI,IAAI,IAAI;IAOZ,gDAAgD;IAChD,MAAM,CAAC,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO;CAG5C"}

package/dist/scheduler.js

@@ -0,0 +1,56 @@
+import cron from 'node-cron';
+export class LocalScheduler {
+    tasks = [];
+    provider;
+    agents;
+    onFire;
+    onError;
+    constructor(options) {
+        this.provider = options.provider;
+        this.agents = options.agents;
+        this.onFire = options.onFire;
+        this.onError = options.onError;
+    }
+    /** Return entries with a `schedule` field, validated. Throws on invalid cron strings. */
+    getScheduledAgents() {
+        const entries = [];
+        for (const agent of this.agents.values()) {
+            if (!agent.schedule)
+                continue;
+            if (!cron.validate(agent.schedule)) {
+                throw new Error(`Agent "${agent.name}" has invalid cron schedule: "${agent.schedule}"`);
+            }
+            entries.push({ agent, schedule: agent.schedule });
+        }
+        return entries;
+    }
+    /** Register cron tasks for every agent with a schedule. */
+    start() {
+        const entries = this.getScheduledAgents();
+        for (const { agent, schedule } of entries) {
+            const task = cron.schedule(schedule, async () => {
+                try {
+                    const run = await this.provider.submitRun({ agent, triggeredBy: 'schedule' });
+                    this.onFire?.(agent, run.id);
+                }
+                catch (err) {
+                    this.onError?.(agent, err instanceof Error ? err : new Error(String(err)));
+                }
+            });
+            this.tasks.push({ agent, task });
+        }
+        return entries;
+    }
+    /** Stop all tasks and release resources. */
+    stop() {
+        for (const { task } of this.tasks) {
+            task.stop();
+        }
+        this.tasks = [];
+    }
+    /** True if a cron expression parses cleanly. */
+    static isValid(expression) {
+        return cron.validate(expression);
+    }
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../src/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAe7B,MAAM,OAAO,cAAc;IACjB,KAAK,GAAgE,EAAE,CAAC;IAC/D,QAAQ,CAAW;IACnB,MAAM,CAA+B;IACrC,MAAM,CAAmD;IACzD,OAAO,CAAkD;IAE1E,YAAY,OAA8B;QACxC,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC;QACjC,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;QAC7B,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IACjC,CAAC;IAED,yFAAyF;IACzF,kBAAkB;QAChB,MAAM,OAAO,GAA0B,EAAE,CAAC;QAC1C,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,KAAK,CAAC,QAAQ;gBAAE,SAAS;YAC9B,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;gBACnC,MAAM,IAAI,KAAK,CACb,UAAU,KAAK,CAAC,IAAI,iCAAiC,KAAK,CAAC,QAAQ,GAAG,CACvE,CAAC;YACJ,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC;QACpD,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,2DAA2D;IAC3D,KAAK;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;QAC1C,KAAK,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,OAAO,EAAE,CAAC;YAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE;gBAC9C,IAAI,CAAC;oBACH,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,CAAC,CAAC;oBAC9E,IAAI,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBAC/B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBAC7E,CAAC;YACH,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,4CAA4C;IAC5C,IAAI;QACF,KAAK,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YAClC,IAAI,CAAC,IAAI,EAAE,CAAC;QACd,CAAC;QACD,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;IAClB,CAAC;IAED,gDAAgD;IAChD,MAAM,CAAC,OAAO,CAAC,UAAkB;QAC/B,OAAO,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;CACF"}

package/dist/scheduler.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=scheduler.test.d.ts.map

package/dist/scheduler.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.test.d.ts","sourceRoot":"","sources":["../src/scheduler.test.ts"],"names":[],"mappings":""}

package/dist/scheduler.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect, vi } from 'vitest';
+import { LocalScheduler } from './scheduler.js';
+function makeAgent(name, schedule) {
+    return { name, type: 'shell', command: `echo ${name}`, schedule };
+}
+function makeFakeProvider() {
+    return {
+        name: 'fake',
+        initialize: async () => { },
+        shutdown: async () => { },
+        submitRun: async (req) => ({
+            id: `run-${req.agent.name}-${Date.now()}`,
+            agentName: req.agent.name,
+            status: 'running',
+            startedAt: new Date().toISOString(),
+            triggeredBy: req.triggeredBy,
+        }),
+        getRun: async () => null,
+        listRuns: async () => [],
+        cancelRun: async () => { },
+        getRunLogs: async () => '',
+    };
+}
+describe('LocalScheduler', () => {
+    it('returns only agents with schedule fields', () => {
+        const agents = new Map([
+            ['a', makeAgent('a', '* * * * *')],
+            ['b', makeAgent('b')], // no schedule
+            ['c', makeAgent('c', '0 9 * * *')],
+        ]);
+        const scheduler = new LocalScheduler({ provider: makeFakeProvider(), agents });
+        const entries = scheduler.getScheduledAgents();
+        expect(entries.map(e => e.agent.name).sort()).toEqual(['a', 'c']);
+    });
+    it('throws on invalid cron expressions', () => {
+        const agents = new Map([
+            ['bad', makeAgent('bad', 'not-a-cron')],
+        ]);
+        const scheduler = new LocalScheduler({ provider: makeFakeProvider(), agents });
+        expect(() => scheduler.getScheduledAgents()).toThrow('invalid cron schedule');
+    });
+    it('isValid accepts standard cron expressions', () => {
+        expect(LocalScheduler.isValid('* * * * *')).toBe(true);
+        expect(LocalScheduler.isValid('0 9 * * *')).toBe(true);
+        expect(LocalScheduler.isValid('*/5 * * * *')).toBe(true);
+        expect(LocalScheduler.isValid('not valid')).toBe(false);
+        expect(LocalScheduler.isValid('')).toBe(false);
+    });
+    it('start() registers tasks for every scheduled agent', () => {
+        const agents = new Map([
+            ['a', makeAgent('a', '* * * * *')],
+            ['b', makeAgent('b', '0 9 * * *')],
+        ]);
+        const scheduler = new LocalScheduler({ provider: makeFakeProvider(), agents });
+        const entries = scheduler.start();
+        expect(entries.length).toBe(2);
+        scheduler.stop();
+    });
+    it('stop() is safe to call multiple times', () => {
+        const agents = new Map([
+            ['a', makeAgent('a', '* * * * *')],
+        ]);
+        const scheduler = new LocalScheduler({ provider: makeFakeProvider(), agents });
+        scheduler.start();
+        scheduler.stop();
+        scheduler.stop(); // should not throw
+    });
+    it('start() returns empty when no agents have schedules', () => {
+        const agents = new Map([
+            ['a', makeAgent('a')],
+            ['b', makeAgent('b')],
+        ]);
+        const scheduler = new LocalScheduler({ provider: makeFakeProvider(), agents });
+        const entries = scheduler.start();
+        expect(entries.length).toBe(0);
+        scheduler.stop();
+    });
+    it('onFire callback wires to submitRun with triggeredBy=schedule', async () => {
+        // Use a cron expression that fires every second
+        const agents = new Map([
+            ['tick', makeAgent('tick', '* * * * * *')], // 6-field = seconds granularity
+        ]);
+        const provider = makeFakeProvider();
+        const submitSpy = vi.spyOn(provider, 'submitRun');
+        const fireEvents = [];
+        const scheduler = new LocalScheduler({
+            provider,
+            agents,
+            onFire: (agent, runId) => fireEvents.push({ name: agent.name, runId }),
+        });
+        scheduler.start();
+        await new Promise(r => setTimeout(r, 1500)); // wait for at least one tick
+        scheduler.stop();
+        expect(submitSpy).toHaveBeenCalled();
+        expect(submitSpy.mock.calls[0][0].triggeredBy).toBe('schedule');
+        expect(fireEvents.length).toBeGreaterThan(0);
+        expect(fireEvents[0].name).toBe('tick');
+    }, 5000);
+});
+//# sourceMappingURL=scheduler.test.js.map

package/dist/scheduler.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.test.js","sourceRoot":"","sources":["../src/scheduler.test.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@some-useful-agents/core",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Core types, schemas, and utilities for some-useful-agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
   "dependencies": {
     "yaml": "^2.7.0",
     "zod": "^3.24.0",
-    "uuid": "^11.1.0"
+    "uuid": "^11.1.0",
+    "node-cron": "^4.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",