discoclaw 0.1.0

package/dist/cron/job-lock.js

@@ -0,0 +1,164 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import crypto from 'node:crypto';
+/**
+ * Collision-resistant lock name from a cron ID.
+ * Sanitizes non-alphanumeric chars and appends a short hash suffix
+ * to prevent collisions when different IDs sanitize to the same string
+ * (e.g. "a/b" vs "a_b").
+ */
+export function safeCronId(id) {
+    const sanitized = id.replace(/[^a-zA-Z0-9._-]/g, '_');
+    const hash = crypto.createHash('sha256').update(id).digest('hex').slice(0, 8);
+    return `${sanitized}.${hash}`;
+}
+/**
+ * Read the Linux process start time from /proc/{pid}/stat (field 22, jiffies since boot).
+ * Returns null on non-Linux systems or on any read failure.
+ */
+export async function getProcessStartTime(pid) {
+    try {
+        const stat = await fs.readFile(`/proc/${pid}/stat`, 'utf-8');
+        // Fields are space-separated but field 2 (comm) may contain spaces and is wrapped in parens.
+        // Find the closing paren, then split the rest.
+        const closeParenIdx = stat.lastIndexOf(')');
+        if (closeParenIdx === -1)
+            return null;
+        const fields = stat.slice(closeParenIdx + 2).split(' ');
+        // After the closing paren: field 3=state(idx 0), ..., field 22=starttime(idx 19)
+        const startTime = Number(fields[19]);
+        return Number.isFinite(startTime) ? startTime : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Grace period: lock dirs younger than this with missing meta.json are treated as initializing. */
+const GRACE_PERIOD_MS = 2000;
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (err) {
+        const code = err.code;
+        if (code === 'EPERM')
+            return true; // process exists, no permission to signal
+        return false; // ESRCH = dead
+    }
+}
+function generateToken() {
+    return crypto.randomBytes(16).toString('hex');
+}
+async function readMeta(lockPath) {
+    try {
+        const raw = await fs.readFile(path.join(lockPath, 'meta.json'), 'utf-8');
+        const parsed = JSON.parse(raw);
+        if (typeof parsed?.pid !== 'number' || typeof parsed?.token !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+async function writeMeta(lockPath, meta) {
+    const metaPath = path.join(lockPath, 'meta.json');
+    const tmpPath = `${metaPath}.tmp.${process.pid}`;
+    await fs.writeFile(tmpPath, JSON.stringify(meta) + '\n', 'utf-8');
+    await fs.rename(tmpPath, metaPath);
+}
+/**
+ * Acquire a file-based lock for a cron job.
+ * Returns a token on success. Throws if the lock is held or initializing.
+ */
+export async function acquireCronLock(lockDir, cronId) {
+    const lockName = safeCronId(cronId);
+    const lockPath = path.join(lockDir, lockName + '.lock');
+    const token = generateToken();
+    const startTime = await getProcessStartTime(process.pid);
+    const meta = {
+        pid: process.pid,
+        token,
+        acquiredAt: new Date().toISOString(),
+        ...(startTime != null ? { startTime } : {}),
+    };
+    // Attempt 1: try atomic mkdir.
+    try {
+        await fs.mkdir(lockPath);
+        await writeMeta(lockPath, meta);
+        return token;
+    }
+    catch (err) {
+        if (err.code !== 'EEXIST')
+            throw err;
+    }
+    // Lock directory exists — check if it's stale.
+    const existingMeta = await readMeta(lockPath);
+    if (!existingMeta) {
+        // meta.json missing or corrupt — check grace period.
+        let dirAge = Infinity;
+        try {
+            const stat = await fs.stat(lockPath);
+            dirAge = Date.now() - stat.mtimeMs;
+        }
+        catch {
+            // Can't stat — treat as old.
+        }
+        if (dirAge < GRACE_PERIOD_MS) {
+            throw new Error(`Lock initializing for "${cronId}" (dir age: ${Math.round(dirAge)}ms)`);
+        }
+        // Old enough with no valid meta — treat as corrupt/orphaned.
+        await fs.rm(lockPath, { recursive: true, force: true });
+    }
+    else {
+        // Valid meta — check PID liveness + startTime.
+        const alive = isPidAlive(existingMeta.pid);
+        if (alive) {
+            // PID is alive — check startTime to detect PID reuse.
+            const existingStartTime = await getProcessStartTime(existingMeta.pid);
+            const metaHasStartTime = existingMeta.startTime != null;
+            const procHasStartTime = existingStartTime != null;
+            if (metaHasStartTime && procHasStartTime && existingMeta.startTime !== existingStartTime) {
+                // PID was reused — stale lock.
+                await fs.rm(lockPath, { recursive: true, force: true });
+            }
+            else {
+                // PID alive and startTime matches (or unavailable on one/both sides) — lock is held.
+                throw new Error(`Lock held by PID ${existingMeta.pid} for "${cronId}"`);
+            }
+        }
+        else {
+            // PID is dead — stale lock.
+            await fs.rm(lockPath, { recursive: true, force: true });
+        }
+    }
+    // Attempt 2: retry mkdir after removing stale lock.
+    try {
+        await fs.mkdir(lockPath);
+        await writeMeta(lockPath, meta);
+        return token;
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            throw new Error(`Lock contention for "${cronId}" (lost race on retry)`);
+        }
+        throw err;
+    }
+}
+/**
+ * Release a file-based lock for a cron job.
+ * Only removes the lock if the token matches (prevents one process from
+ * releasing another's lock). Silent on mismatch or missing lock.
+ */
+export async function releaseCronLock(lockDir, cronId, token) {
+    const lockName = safeCronId(cronId);
+    const lockPath = path.join(lockDir, lockName + '.lock');
+    const meta = await readMeta(lockPath);
+    if (!meta)
+        return; // Lock dir missing or meta unreadable — nothing to do.
+    if (meta.token === token) {
+        await fs.rm(lockPath, { recursive: true, force: true });
+    }
+    // Token mismatch — another process owns it; leave it alone.
+}

package/dist/cron/job-lock.test.js

@@ -0,0 +1,178 @@
+import { describe, expect, it, beforeEach, afterEach } from 'vitest';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { safeCronId, acquireCronLock, releaseCronLock, getProcessStartTime } from './job-lock.js';
+let tmpDir;
+beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'job-lock-test-'));
+});
+afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true });
+});
+// ---------------------------------------------------------------------------
+// safeCronId
+// ---------------------------------------------------------------------------
+describe('safeCronId', () => {
+    it('produces distinct names for IDs that sanitize identically', () => {
+        // "a/b" and "a_b" both sanitize to "a_b" but hashes differ.
+        const a = safeCronId('a/b');
+        const b = safeCronId('a_b');
+        expect(a).not.toBe(b);
+    });
+    it('preserves safe characters', () => {
+        const result = safeCronId('cron-abc_123.test');
+        expect(result).toMatch(/^cron-abc_123\.test\.[0-9a-f]{8}$/);
+    });
+    it('replaces unsafe characters', () => {
+        const result = safeCronId('my cron/job!@#');
+        expect(result).not.toContain(' ');
+        expect(result).not.toContain('/');
+        expect(result).not.toContain('!');
+    });
+});
+// ---------------------------------------------------------------------------
+// getProcessStartTime
+// ---------------------------------------------------------------------------
+describe('getProcessStartTime', () => {
+    it('returns a number for the current process (Linux) or null (non-Linux)', async () => {
+        const result = await getProcessStartTime(process.pid);
+        if (process.platform === 'linux') {
+            expect(typeof result).toBe('number');
+            expect(result).toBeGreaterThan(0);
+        }
+        else {
+            expect(result).toBeNull();
+        }
+    });
+    it('returns null for a non-existent PID', async () => {
+        const result = await getProcessStartTime(999999999);
+        expect(result).toBeNull();
+    });
+});
+// ---------------------------------------------------------------------------
+// acquireCronLock
+// ---------------------------------------------------------------------------
+describe('acquireCronLock', () => {
+    it('acquires a fresh lock (directory + meta.json created)', async () => {
+        const token = await acquireCronLock(tmpDir, 'cron-test');
+        expect(typeof token).toBe('string');
+        expect(token.length).toBe(32); // 16 bytes hex
+        const lockPath = path.join(tmpDir, safeCronId('cron-test') + '.lock');
+        const stat = await fs.stat(lockPath);
+        expect(stat.isDirectory()).toBe(true);
+        const raw = await fs.readFile(path.join(lockPath, 'meta.json'), 'utf-8');
+        const meta = JSON.parse(raw);
+        expect(meta.pid).toBe(process.pid);
+        expect(meta.token).toBe(token);
+        expect(meta.acquiredAt).toBeDefined();
+    });
+    it('throws when PID alive and startTime matches (lock held)', async () => {
+        const token1 = await acquireCronLock(tmpDir, 'cron-held');
+        expect(token1).toBeDefined();
+        // Second acquire by same process — PID alive, startTime will match.
+        await expect(acquireCronLock(tmpDir, 'cron-held')).rejects.toThrow(/Lock held by PID/);
+    });
+    it('takes over when PID is dead (ESRCH)', async () => {
+        // Create a lock with a fake dead PID.
+        const lockPath = path.join(tmpDir, safeCronId('cron-dead') + '.lock');
+        await fs.mkdir(lockPath);
+        const fakeMeta = { pid: 999999999, token: 'old-token', acquiredAt: new Date().toISOString() };
+        await fs.writeFile(path.join(lockPath, 'meta.json'), JSON.stringify(fakeMeta));
+        const token = await acquireCronLock(tmpDir, 'cron-dead');
+        expect(typeof token).toBe('string');
+        // Verify the new lock has our PID.
+        const raw = await fs.readFile(path.join(lockPath, 'meta.json'), 'utf-8');
+        const meta = JSON.parse(raw);
+        expect(meta.pid).toBe(process.pid);
+        expect(meta.token).toBe(token);
+    });
+    it('takes over when PID alive but startTime mismatches (PID reuse)', async () => {
+        const lockPath = path.join(tmpDir, safeCronId('cron-reuse') + '.lock');
+        await fs.mkdir(lockPath);
+        // Use current PID (alive) but a bogus startTime that won't match.
+        const fakeMeta = {
+            pid: process.pid,
+            token: 'old-token',
+            acquiredAt: new Date().toISOString(),
+            startTime: 12345, // won't match real startTime
+        };
+        await fs.writeFile(path.join(lockPath, 'meta.json'), JSON.stringify(fakeMeta));
+        if (process.platform === 'linux') {
+            // On Linux, startTime will differ → stale takeover.
+            const token = await acquireCronLock(tmpDir, 'cron-reuse');
+            expect(typeof token).toBe('string');
+        }
+        else {
+            // On non-Linux, getProcessStartTime returns null for both sides,
+            // and meta has a startTime while proc doesn't → they don't both have startTime,
+            // so it falls through to "lock held" (PID alive, can't confirm mismatch).
+            await expect(acquireCronLock(tmpDir, 'cron-reuse')).rejects.toThrow(/Lock held by PID/);
+        }
+    });
+    it('blocks when lock dir exists, meta.json missing, dir < 2s old (grace period)', async () => {
+        const lockPath = path.join(tmpDir, safeCronId('cron-grace') + '.lock');
+        await fs.mkdir(lockPath);
+        // No meta.json, dir just created → grace period.
+        await expect(acquireCronLock(tmpDir, 'cron-grace')).rejects.toThrow(/Lock initializing/);
+    });
+    it('takes over when lock dir exists, meta.json missing, dir >= 2s old', async () => {
+        const lockPath = path.join(tmpDir, safeCronId('cron-old') + '.lock');
+        await fs.mkdir(lockPath);
+        // Backdate the directory mtime by 3 seconds.
+        const past = new Date(Date.now() - 3000);
+        await fs.utimes(lockPath, past, past);
+        const token = await acquireCronLock(tmpDir, 'cron-old');
+        expect(typeof token).toBe('string');
+    });
+    it('takes over when meta.json is corrupt (invalid JSON) and dir old', async () => {
+        const lockPath = path.join(tmpDir, safeCronId('cron-corrupt') + '.lock');
+        await fs.mkdir(lockPath);
+        await fs.writeFile(path.join(lockPath, 'meta.json'), 'not json!!!');
+        // Backdate directory.
+        const past = new Date(Date.now() - 3000);
+        await fs.utimes(lockPath, past, past);
+        const token = await acquireCronLock(tmpDir, 'cron-corrupt');
+        expect(typeof token).toBe('string');
+    });
+    it('simulates EEXIST contention then stale-takeover retry path', async () => {
+        // Pre-create a lock with a dead PID to ensure the EEXIST → stale → retry path.
+        const lockPath = path.join(tmpDir, safeCronId('cron-contention') + '.lock');
+        await fs.mkdir(lockPath);
+        const fakeMeta = { pid: 999999999, token: 'stale-token', acquiredAt: new Date().toISOString() };
+        await fs.writeFile(path.join(lockPath, 'meta.json'), JSON.stringify(fakeMeta));
+        // Should detect EEXIST, read meta, find dead PID, rm, retry, succeed.
+        const token = await acquireCronLock(tmpDir, 'cron-contention');
+        expect(typeof token).toBe('string');
+    });
+});
+// ---------------------------------------------------------------------------
+// releaseCronLock
+// ---------------------------------------------------------------------------
+describe('releaseCronLock', () => {
+    it('removes lock when token matches', async () => {
+        const token = await acquireCronLock(tmpDir, 'cron-release');
+        const lockPath = path.join(tmpDir, safeCronId('cron-release') + '.lock');
+        // Lock exists.
+        await expect(fs.stat(lockPath)).resolves.toBeDefined();
+        await releaseCronLock(tmpDir, 'cron-release', token);
+        // Lock removed.
+        await expect(fs.stat(lockPath)).rejects.toThrow();
+    });
+    it('leaves lock intact when token does not match', async () => {
+        const token = await acquireCronLock(tmpDir, 'cron-mismatch');
+        const lockPath = path.join(tmpDir, safeCronId('cron-mismatch') + '.lock');
+        await releaseCronLock(tmpDir, 'cron-mismatch', 'wrong-token');
+        // Lock still exists.
+        const stat = await fs.stat(lockPath);
+        expect(stat.isDirectory()).toBe(true);
+        // And the original token is still in meta.json.
+        const raw = await fs.readFile(path.join(lockPath, 'meta.json'), 'utf-8');
+        const meta = JSON.parse(raw);
+        expect(meta.token).toBe(token);
+    });
+    it('is idempotent (no error if dir already missing)', async () => {
+        // No lock exists — should not throw.
+        await expect(releaseCronLock(tmpDir, 'cron-nonexistent', 'any-token')).resolves.toBeUndefined();
+    });
+});

package/dist/cron/parser.js

@@ -0,0 +1,68 @@
+import { resolveModel } from '../runtime/model-tiers.js';
+import { getDefaultTimezone } from './default-timezone.js';
+function buildSystemPrompt() {
+    const defaultTz = getDefaultTimezone();
+    return `You are a cron definition parser. Extract a cron schedule from a natural-language task description.
+
+Return ONLY valid JSON with these fields:
+- schedule: 5-field cron expression (minute hour day-of-month month day-of-week)
+- timezone: IANA timezone string (default "${defaultTz}" if not specified)
+- channel: target Discord channel name (without #) or ID. If the user says "post to #general", channel is "general".
+- prompt: the instruction text the bot should follow at each execution (rephrase as a direct instruction)
+
+Rules:
+- Use standard 5-field cron (no seconds). Examples: "0 7 * * 1-5" = weekdays at 7am, "*/5 * * * *" = every 5 minutes, "0 9 * * 1" = Mondays at 9am.
+- Day-of-week: 0=Sunday, 1=Monday, ..., 6=Saturday. Range "1-5" = weekdays.
+- If the user says "every minute", use "* * * * *".
+- If no timezone is mentioned, default to "${defaultTz}".
+- If no target channel is mentioned, set channel to "general".
+- The prompt field should capture what the bot should do/say, not the scheduling part.
+
+Return ONLY the JSON object, no markdown fences, no explanation.`;
+}
+export async function parseCronDefinition(text, runtime, opts) {
+    const prompt = `${buildSystemPrompt()}\n\nUser definition:\n${text}`;
+    let finalText = '';
+    let deltaText = '';
+    for await (const evt of runtime.invoke({
+        prompt,
+        model: resolveModel(opts?.model ?? 'fast', runtime.id),
+        cwd: opts?.cwd ?? process.cwd(),
+        timeoutMs: opts?.timeoutMs ?? 30_000,
+        tools: [],
+    })) {
+        if (evt.type === 'text_final') {
+            finalText = evt.text;
+        }
+        else if (evt.type === 'text_delta') {
+            deltaText += evt.text;
+        }
+        else if (evt.type === 'error') {
+            return null;
+        }
+    }
+    const output = finalText || deltaText;
+    // Strip markdown fences if present.
+    const cleaned = output.replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/, '').trim();
+    if (!cleaned)
+        return null;
+    try {
+        const parsed = JSON.parse(cleaned);
+        if (typeof parsed.schedule !== 'string' ||
+            typeof parsed.timezone !== 'string' ||
+            typeof parsed.channel !== 'string' ||
+            typeof parsed.prompt !== 'string') {
+            return null;
+        }
+        return {
+            triggerType: 'schedule',
+            schedule: parsed.schedule.trim(),
+            timezone: parsed.timezone.trim() || getDefaultTimezone(),
+            channel: parsed.channel.replace(/^#/, '').trim(),
+            prompt: parsed.prompt.trim(),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/cron/parser.test.js

@@ -0,0 +1,115 @@
+import { describe, expect, it, vi } from 'vitest';
+import { parseCronDefinition } from './parser.js';
+function makeMockRuntime(response) {
+    return {
+        id: 'claude_code',
+        capabilities: new Set(['streaming_text']),
+        async *invoke() {
+            yield { type: 'text_final', text: response };
+            yield { type: 'done' };
+        },
+    };
+}
+function makeMockRuntimeError() {
+    return {
+        id: 'claude_code',
+        capabilities: new Set(['streaming_text']),
+        async *invoke() {
+            yield { type: 'error', message: 'timeout' };
+            yield { type: 'done' };
+        },
+    };
+}
+describe('parseCronDefinition', () => {
+    it('parses a valid JSON response', async () => {
+        const runtime = makeMockRuntime(JSON.stringify({
+            schedule: '0 7 * * 1-5',
+            timezone: 'America/Los_Angeles',
+            channel: 'general',
+            prompt: 'Check the weather for Portland OR and post a brief summary.',
+        }));
+        const result = await parseCronDefinition('Every weekday at 7am Pacific, check the weather', runtime);
+        expect(result).toEqual({
+            triggerType: 'schedule',
+            schedule: '0 7 * * 1-5',
+            timezone: 'America/Los_Angeles',
+            channel: 'general',
+            prompt: 'Check the weather for Portland OR and post a brief summary.',
+        });
+    });
+    it('handles markdown-fenced JSON', async () => {
+        const json = JSON.stringify({
+            schedule: '* * * * *',
+            timezone: 'UTC',
+            channel: 'general',
+            prompt: 'Say hello.',
+        });
+        const runtime = makeMockRuntime('```json\n' + json + '\n```');
+        const result = await parseCronDefinition('Every minute, say hello to #general', runtime);
+        expect(result).toEqual({
+            triggerType: 'schedule',
+            schedule: '* * * * *',
+            timezone: 'UTC',
+            channel: 'general',
+            prompt: 'Say hello.',
+        });
+    });
+    it('strips # from channel name', async () => {
+        const runtime = makeMockRuntime(JSON.stringify({
+            schedule: '0 9 * * 1',
+            timezone: 'UTC',
+            channel: '#announcements',
+            prompt: 'Post weekly update.',
+        }));
+        const result = await parseCronDefinition('Every Monday at 9am, post to #announcements', runtime);
+        expect(result?.channel).toBe('announcements');
+    });
+    it('returns null on runtime error', async () => {
+        const runtime = makeMockRuntimeError();
+        const result = await parseCronDefinition('test', runtime);
+        expect(result).toBeNull();
+    });
+    it('returns null on empty output', async () => {
+        const runtime = makeMockRuntime('');
+        const result = await parseCronDefinition('test', runtime);
+        expect(result).toBeNull();
+    });
+    it('returns null on invalid JSON', async () => {
+        const runtime = makeMockRuntime('not json at all');
+        const result = await parseCronDefinition('test', runtime);
+        expect(result).toBeNull();
+    });
+    it('returns null when required fields are missing', async () => {
+        const runtime = makeMockRuntime(JSON.stringify({
+            schedule: '0 7 * * *',
+            timezone: 'UTC',
+        }));
+        const result = await parseCronDefinition('test', runtime);
+        expect(result).toBeNull();
+    });
+    it('defaults timezone to UTC when empty and DEFAULT_TIMEZONE=UTC', async () => {
+        vi.stubEnv('DEFAULT_TIMEZONE', 'UTC');
+        const runtime = makeMockRuntime(JSON.stringify({
+            schedule: '0 7 * * *',
+            timezone: '',
+            channel: 'general',
+            prompt: 'Do something.',
+        }));
+        const result = await parseCronDefinition('test', runtime);
+        expect(result?.timezone).toBe('UTC');
+        vi.unstubAllEnvs();
+    });
+    it('defaults timezone to system timezone when empty and no env override', async () => {
+        vi.stubEnv('DEFAULT_TIMEZONE', '');
+        const systemTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+        const runtime = makeMockRuntime(JSON.stringify({
+            schedule: '0 7 * * *',
+            timezone: '',
+            channel: 'general',
+            prompt: 'Do something.',
+        }));
+        const result = await parseCronDefinition('test', runtime);
+        expect(result?.timezone).toBe(systemTz);
+        vi.unstubAllEnvs();
+    });
+});

package/dist/cron/run-control.js

@@ -0,0 +1,24 @@
+export class CronRunControl {
+    cancelers = new Map();
+    register(jobId, cancel) {
+        this.cancelers.set(jobId, cancel);
+    }
+    clear(jobId, cancel) {
+        const current = this.cancelers.get(jobId);
+        if (!current)
+            return;
+        if (!cancel || current === cancel) {
+            this.cancelers.delete(jobId);
+        }
+    }
+    requestCancel(jobId) {
+        const cancel = this.cancelers.get(jobId);
+        if (!cancel)
+            return false;
+        cancel();
+        return true;
+    }
+    has(jobId) {
+        return this.cancelers.has(jobId);
+    }
+}

package/dist/cron/run-control.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it, vi } from 'vitest';
+import { CronRunControl } from './run-control.js';
+describe('CronRunControl', () => {
+    it('registers and cancels a running job', () => {
+        const control = new CronRunControl();
+        const cancel = vi.fn();
+        control.register('job-1', cancel);
+        expect(control.has('job-1')).toBe(true);
+        expect(control.requestCancel('job-1')).toBe(true);
+        expect(cancel).toHaveBeenCalledOnce();
+    });
+    it('clear with mismatched cancel function is ignored', () => {
+        const control = new CronRunControl();
+        const cancel = vi.fn();
+        control.register('job-1', cancel);
+        control.clear('job-1', () => { });
+        expect(control.has('job-1')).toBe(true);
+    });
+    it('clear removes registered cancel function', () => {
+        const control = new CronRunControl();
+        const cancel = vi.fn();
+        control.register('job-1', cancel);
+        control.clear('job-1', cancel);
+        expect(control.has('job-1')).toBe(false);
+        expect(control.requestCancel('job-1')).toBe(false);
+    });
+});