@mininglamp-oss/cc-channel-octo 1.0.1

package/dist/cron-scheduler.d.ts

@@ -0,0 +1,46 @@
+/**
+ * #115: Cron scheduler — a resident per-bot loop that fires due tasks.
+ *
+ * Every tick it loads the bot's cron.json, and for each enabled task whose
+ * `nextRun` is past, synthesizes a BotMessage (the task's prompt as a Text
+ * message, bound to the task's session coords, marked `_cronFire`) and hands it
+ * to `onFire` — which the gateway wires to the same `onInbound` real messages
+ * use, so a fired task runs through the entire normal pipeline.
+ *
+ * Best-effort throughout: a failing task is logged and skipped, never crashing
+ * the loop. Missed tasks (process was down across their window) fire ONCE on
+ * catch-up, then advance to the next future occurrence — no thundering herd.
+ */
+import type { BotMessage } from './octo/types.js';
+import { CronStore, type CronTask } from './cron-store.js';
+/** How often the scheduler scans cron.json (ms). 30s → ≤30s firing latency. */
+export declare const CRON_TICK_MS = 30000;
+export interface CronSchedulerOptions {
+    cronStore: CronStore;
+    /**
+     * Invoked with a synthetic BotMessage when a task is due (= onInbound). Fire
+     * is non-blocking; the scheduler does not await it and nextRun advances
+     * regardless (a failed fire is logged at the handler's own catch site —
+     * attributed to the task via the `cron:<id>:<ts>` message_id — not retried, to
+     * avoid an error loop hammering the channel).
+     */
+    onFire: (msg: BotMessage) => void;
+    /** Log prefix, e.g. "[bot-id] " in multi-bot mode. */
+    label?: string;
+}
+/** Build the synthetic inbound message for a fired task. */
+export declare function synthesizeCronMessage(task: CronTask): BotMessage;
+export declare class CronScheduler {
+    private readonly opts;
+    private timer;
+    constructor(opts: CronSchedulerOptions);
+    /** Arm the periodic scan. Idempotent. */
+    start(): void;
+    /** Stop scanning. */
+    stop(): void;
+    /**
+     * One scan: fire due tasks, advance/drop them, persist. Exposed for tests.
+     * Never throws.
+     */
+    tick(): void;
+}

package/dist/cron-scheduler.js

@@ -0,0 +1,114 @@
+/**
+ * #115: Cron scheduler — a resident per-bot loop that fires due tasks.
+ *
+ * Every tick it loads the bot's cron.json, and for each enabled task whose
+ * `nextRun` is past, synthesizes a BotMessage (the task's prompt as a Text
+ * message, bound to the task's session coords, marked `_cronFire`) and hands it
+ * to `onFire` — which the gateway wires to the same `onInbound` real messages
+ * use, so a fired task runs through the entire normal pipeline.
+ *
+ * Best-effort throughout: a failing task is logged and skipped, never crashing
+ * the loop. Missed tasks (process was down across their window) fire ONCE on
+ * catch-up, then advance to the next future occurrence — no thundering herd.
+ */
+import { MessageType } from './octo/types.js';
+import { computeNextRun } from './cron-evaluator.js';
+import { CRON_FIRE_NONCE, CRON_FIRE_NONCE_KEY } from './cron-fire-marker.js';
+/** How often the scheduler scans cron.json (ms). 30s → ≤30s firing latency. */
+export const CRON_TICK_MS = 30_000;
+/** Build the synthetic inbound message for a fired task. */
+export function synthesizeCronMessage(task) {
+    return {
+        message_id: `cron:${task.id}:${Date.now()}`,
+        message_seq: 0,
+        from_uid: task.fromUid,
+        from_name: task.fromName,
+        channel_id: task.channelId,
+        channel_type: task.channelType,
+        timestamp: Math.floor(Date.now() / 1000),
+        payload: {
+            type: MessageType.Text,
+            content: task.prompt,
+            // Synthetic marker + per-process nonce: lets the router bypass the group
+            // @mention gate for genuine in-process cron fires only (see
+            // session-router isCronFire / cron-fire-marker). A forged inbound payload
+            // can set `_cronFire` but cannot know the secret nonce. Allowed by the
+            // MessagePayload index signature; never set on real inbound messages.
+            _cronFire: true,
+            [CRON_FIRE_NONCE_KEY]: CRON_FIRE_NONCE,
+        },
+    };
+}
+export class CronScheduler {
+    opts;
+    timer = null;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    /** Arm the periodic scan. Idempotent. */
+    start() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.tick(), CRON_TICK_MS);
+        this.timer.unref(); // never keep the process alive on the cron loop alone
+    }
+    /** Stop scanning. */
+    stop() {
+        if (this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * One scan: fire due tasks, advance/drop them, persist. Exposed for tests.
+     * Never throws.
+     */
+    tick() {
+        const now = Date.now();
+        // Single atomic read-modify-write: fire due tasks and persist the survivor
+        // set in one synchronous pass, so a concurrent tool create/delete (which
+        // also goes through cronStore.update) can't lose updates against us.
+        try {
+            this.opts.cronStore.update((tasks) => {
+                const survivors = [];
+                let changed = false;
+                for (const task of tasks) {
+                    if (!task.enabled || task.nextRun === null || task.nextRun > now) {
+                        survivors.push(task);
+                        continue;
+                    }
+                    changed = true;
+                    // Due. Fire (best-effort; onFire is fire-and-forget).
+                    const lateMin = Math.round((now - task.nextRun) / 60_000);
+                    if (lateMin >= 1) {
+                        console.warn(`[cc-channel-octo] ${this.opts.label ?? ''}cron: task ${task.id} (${task.schedule}) ` +
+                            `fired ${lateMin} min late (catch-up)`);
+                    }
+                    try {
+                        // Fire-and-forget: onFire (= onInbound) drives the full pipeline,
+                        // which swallows its own errors and posts a user-facing reply. A
+                        // FAILED fire is attributed to this task at handleMessage's catch
+                        // site (via the `cron:<id>:<ts>` message_id) — not here, because the
+                        // returned value is void and never rejects.
+                        this.opts.onFire(synthesizeCronMessage(task));
+                    }
+                    catch (err) {
+                        console.error(`[cc-channel-octo] ${this.opts.label ?? ''}cron: onFire threw for ${task.id}: ${String(err)}`);
+                    }
+                    task.lastRun = now;
+                    if (task.recurring) {
+                        task.nextRun = computeNextRun(task.schedule, true, now);
+                        survivors.push(task); // keep; next future occurrence (or null → inert)
+                    }
+                    // one-shot: drop (not pushed to survivors)
+                }
+                // Return the SAME reference when nothing fired so update() skips the write.
+                return changed ? survivors : tasks;
+            });
+        }
+        catch (err) {
+            console.error(`[cc-channel-octo] ${this.opts.label ?? ''}cron: tick failed: ${String(err)}`);
+        }
+    }
+}
+//# sourceMappingURL=cron-scheduler.js.map

package/dist/cron-scheduler.js.map

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

package/dist/cron-store.d.ts

@@ -0,0 +1,62 @@
+/**
+ * #115: Per-bot cron task persistence — `<baseDir>/<botId>/cron.json`.
+ *
+ * Holds the scheduled tasks a bot's agent has registered via the cron tool. Read
+ * by both the cron tool (agent turn, under the session lock) and the scheduler
+ * tick (every ~30s). Node is single-threaded and all I/O here is synchronous, so
+ * a tool write and a scheduler read can never interleave mid-operation; the
+ * atomic temp+rename below additionally guarantees a reader never sees a partial
+ * file even across a crash.
+ */
+import type { ChannelType } from './octo/types.js';
+/** One scheduled task. Persisted as a plain JSON object. */
+export interface CronTask {
+    /** Stable handle (uuid) — used by cron_delete; not user-chosen. */
+    id: string;
+    /** 5-field cron expression OR a one-shot ISO datetime. */
+    schedule: string;
+    /** true = re-schedule after each fire; false = delete after firing once. */
+    recurring: boolean;
+    /** Prompt injected as the synthetic message's text (≤ MAX_PROMPT_BYTES). */
+    prompt: string;
+    /** Bound session coords — where the fired task runs and replies. */
+    channelId: string;
+    channelType: ChannelType;
+    fromUid: string;
+    fromName?: string;
+    /** uid that registered the task (owner-gate source of truth). */
+    createdBy: string;
+    /** Scheduler skips disabled tasks (kept for a future cron_disable). */
+    enabled: boolean;
+    /** Unix ms of creation. */
+    createdAt: number;
+    /** Unix ms of the last fire, or null if never fired. */
+    lastRun: number | null;
+    /** Unix ms of the next fire (the scheduler's due check), or null if none. */
+    nextRun: number | null;
+}
+/** Max prompt size (bytes) accepted into a task. */
+export declare const MAX_PROMPT_BYTES = 2048;
+/** Max number of tasks per bot. */
+export declare const MAX_TASKS_PER_BOT = 50;
+/** Load/save a single bot's cron.json. */
+export declare class CronStore {
+    private readonly cronJsonPath;
+    constructor(cronJsonPath: string);
+    /** Parse cron.json. Throws on malformed JSON (loud, not silent). */
+    load(): CronTask[];
+    /** Like load(), but returns [] when the file does not exist. */
+    loadOrEmpty(): CronTask[];
+    /** Atomically write the task array (temp file + rename). */
+    save(tasks: CronTask[]): void;
+    /**
+     * Atomic read-modify-write: load the current tasks, apply `mutator`, persist
+     * the result, and return it. The whole sequence runs **synchronously** (no
+     * await), so under Node's single-threaded model no other turn or scheduler
+     * tick can interleave between the load and the save — eliminating the
+     * lost-update race that separate load()+save() calls would risk if a caller
+     * ever introduced an await between them. All cron mutations (create, delete,
+     * scheduler advance) go through this one method.
+     */
+    update(mutator: (tasks: CronTask[]) => CronTask[]): CronTask[];
+}

package/dist/cron-store.js

@@ -0,0 +1,63 @@
+/**
+ * #115: Per-bot cron task persistence — `<baseDir>/<botId>/cron.json`.
+ *
+ * Holds the scheduled tasks a bot's agent has registered via the cron tool. Read
+ * by both the cron tool (agent turn, under the session lock) and the scheduler
+ * tick (every ~30s). Node is single-threaded and all I/O here is synchronous, so
+ * a tool write and a scheduler read can never interleave mid-operation; the
+ * atomic temp+rename below additionally guarantees a reader never sees a partial
+ * file even across a crash.
+ */
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+/** Max prompt size (bytes) accepted into a task. */
+export const MAX_PROMPT_BYTES = 2048;
+/** Max number of tasks per bot. */
+export const MAX_TASKS_PER_BOT = 50;
+/** Load/save a single bot's cron.json. */
+export class CronStore {
+    cronJsonPath;
+    constructor(cronJsonPath) {
+        this.cronJsonPath = cronJsonPath;
+    }
+    /** Parse cron.json. Throws on malformed JSON (loud, not silent). */
+    load() {
+        const raw = readFileSync(this.cronJsonPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (!Array.isArray(parsed)) {
+            throw new Error(`cron.json is not an array: ${this.cronJsonPath}`);
+        }
+        return parsed;
+    }
+    /** Like load(), but returns [] when the file does not exist. */
+    loadOrEmpty() {
+        if (!existsSync(this.cronJsonPath))
+            return [];
+        return this.load();
+    }
+    /** Atomically write the task array (temp file + rename). */
+    save(tasks) {
+        const tmp = `${this.cronJsonPath}.tmp`;
+        writeFileSync(tmp, JSON.stringify(tasks, null, 2), { mode: 0o600 });
+        renameSync(tmp, this.cronJsonPath);
+    }
+    /**
+     * Atomic read-modify-write: load the current tasks, apply `mutator`, persist
+     * the result, and return it. The whole sequence runs **synchronously** (no
+     * await), so under Node's single-threaded model no other turn or scheduler
+     * tick can interleave between the load and the save — eliminating the
+     * lost-update race that separate load()+save() calls would risk if a caller
+     * ever introduced an await between them. All cron mutations (create, delete,
+     * scheduler advance) go through this one method.
+     */
+    update(mutator) {
+        const current = this.loadOrEmpty();
+        const next = mutator(current);
+        // Skip the write when the mutator returns the same array reference
+        // unchanged (e.g. an idle scheduler tick with nothing due) — avoids
+        // rewriting cron.json on every 30s tick.
+        if (next !== current)
+            this.save(next);
+        return next;
+    }
+}
+//# sourceMappingURL=cron-store.js.map

package/dist/cron-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-store.js","sourceRoot":"","sources":["../src/cron-store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AA8B9E,oDAAoD;AACpD,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,CAAC;AACrC,mCAAmC;AACnC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC;AAEpC,0CAA0C;AAC1C,MAAM,OAAO,SAAS;IACS;IAA7B,YAA6B,YAAoB;QAApB,iBAAY,GAAZ,YAAY,CAAQ;IAAG,CAAC;IAErD,oEAAoE;IACpE,IAAI;QACF,MAAM,GAAG,GAAG,YAAY,CAAC,IAAI,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;QACpD,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC/B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;YAC3B,MAAM,IAAI,KAAK,CAAC,8BAA8B,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;QACrE,CAAC;QACD,OAAO,MAAoB,CAAC;IAC9B,CAAC;IAED,gEAAgE;IAChE,WAAW;QACT,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,YAAY,CAAC;YAAE,OAAO,EAAE,CAAC;QAC9C,OAAO,IAAI,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,4DAA4D;IAC5D,IAAI,CAAC,KAAiB;QACpB,MAAM,GAAG,GAAG,GAAG,IAAI,CAAC,YAAY,MAAM,CAAC;QACvC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;QACpE,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC,YAAY,CAAC,CAAC;IACrC,CAAC;IAED;;;;;;;;OAQG;IACH,MAAM,CAAC,OAA0C;QAC/C,MAAM,OAAO,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC9B,mEAAmE;QACnE,oEAAoE;QACpE,yCAAyC;QACzC,IAAI,IAAI,KAAK,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtC,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/cron-tool.d.ts

@@ -0,0 +1,44 @@
+/**
+ * #115: Cron tool — an in-process MCP server letting the agent register, list,
+ * and delete per-bot scheduled tasks. Tools surface to the model as
+ * `mcp__cron__cron_create` / `_list` / `_delete`.
+ *
+ * The server is built PER TURN (`createCronToolServer`) with the current
+ * message's raw channel coords + the bot owner uid, so:
+ *  - a created task BINDS to the session that created it (fires + replies there);
+ *  - creation/deletion is GATED to the bot owner (registerBot.owner_uid). The
+ *    agent is driven by untrusted IM users, so this server-side check — not LLM
+ *    judgment — is what stops a prompt-injected agent from registering a
+ *    malicious recurring task. (See SECURITY_PROMPT_PREFIX for the advisory
+ *    defense-in-depth layer.)
+ */
+import { z } from 'zod';
+import type { ChannelType } from './octo/types.js';
+import { CronStore } from './cron-store.js';
+/** MCP server name; tools surface as `mcp__cron__<tool>`. */
+export declare const CRON_TOOL_SERVER_NAME = "cron";
+/** Raw coords of the session creating a task — what a fired task binds to. */
+export interface CronSessionCoords {
+    channelId: string;
+    channelType: ChannelType;
+    fromUid: string;
+    fromName?: string;
+}
+/**
+ * Build the cron tool DEFINITIONS for one agent turn. Exported separately from
+ * the server so tests can invoke each handler directly (the MCP server keeps its
+ * tools in private internals). `coords` binds created tasks to this session;
+ * `ownerUid` gates create/delete to the bot owner.
+ */
+export declare function buildCronTools(cronStore: CronStore, coords: CronSessionCoords, ownerUid: string): (import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    schedule: z.ZodString;
+    prompt: z.ZodString;
+    recurring: z.ZodOptional<z.ZodBoolean>;
+}> | import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{}> | import("@anthropic-ai/claude-agent-sdk").SdkMcpToolDefinition<{
+    id: z.ZodString;
+}>)[];
+/**
+ * Build the cron MCP server for one agent turn. `coords` binds created tasks to
+ * this session; `ownerUid` gates create/delete to the bot owner.
+ */
+export declare function createCronToolServer(cronStore: CronStore, coords: CronSessionCoords, ownerUid: string): import("@anthropic-ai/claude-agent-sdk").McpSdkServerConfigWithInstance;

package/dist/cron-tool.js

@@ -0,0 +1,151 @@
+/**
+ * #115: Cron tool — an in-process MCP server letting the agent register, list,
+ * and delete per-bot scheduled tasks. Tools surface to the model as
+ * `mcp__cron__cron_create` / `_list` / `_delete`.
+ *
+ * The server is built PER TURN (`createCronToolServer`) with the current
+ * message's raw channel coords + the bot owner uid, so:
+ *  - a created task BINDS to the session that created it (fires + replies there);
+ *  - creation/deletion is GATED to the bot owner (registerBot.owner_uid). The
+ *    agent is driven by untrusted IM users, so this server-side check — not LLM
+ *    judgment — is what stops a prompt-injected agent from registering a
+ *    malicious recurring task. (See SECURITY_PROMPT_PREFIX for the advisory
+ *    defense-in-depth layer.)
+ */
+import { z } from 'zod';
+import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { MAX_PROMPT_BYTES, MAX_TASKS_PER_BOT } from './cron-store.js';
+import { computeNextRun, isOneShotSchedule, parseCronExpression } from './cron-evaluator.js';
+/** MCP server name; tools surface as `mcp__cron__<tool>`. */
+export const CRON_TOOL_SERVER_NAME = 'cron';
+function jsonResult(value) {
+    return { content: [{ type: 'text', text: JSON.stringify(value, null, 2) }] };
+}
+function errResult(msg) {
+    return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+}
+/** A task rendered for the model (nextRun as ISO, no internal-only churn). */
+function summarize(t) {
+    return {
+        id: t.id,
+        schedule: t.schedule,
+        recurring: t.recurring,
+        prompt: t.prompt,
+        nextRun: t.nextRun ? new Date(t.nextRun).toISOString() : null,
+        enabled: t.enabled,
+    };
+}
+/**
+ * Build the cron tool DEFINITIONS for one agent turn. Exported separately from
+ * the server so tests can invoke each handler directly (the MCP server keeps its
+ * tools in private internals). `coords` binds created tasks to this session;
+ * `ownerUid` gates create/delete to the bot owner.
+ */
+export function buildCronTools(cronStore, coords, ownerUid) {
+    const isOwner = coords.fromUid === ownerUid && ownerUid !== '';
+    return [
+        tool('cron_create', 'Schedule a task: at the given time the bot re-runs `prompt` in THIS chat, ' +
+            'as if you received it as a message, and posts the result here. ' +
+            '`schedule` is a 5-field cron expression ("0 9 * * 1-5" = weekdays 9am) ' +
+            'or a one-shot ISO datetime ("2026-06-09T09:00:00Z"). Set recurring=false ' +
+            'for a one-time reminder. Only the bot owner may create tasks.', {
+            schedule: z.string().min(1).describe('5-field cron expression or one-shot ISO datetime.'),
+            prompt: z.string().min(1).describe('The instruction to run when the task fires.'),
+            recurring: z.boolean().optional().describe('Re-run on every match (default: cron→true, one-shot→false).'),
+        }, async (args) => {
+            try {
+                if (!isOwner) {
+                    return errResult('Only the bot owner can create scheduled tasks.');
+                }
+                const oneShot = isOneShotSchedule(args.schedule);
+                // Validate the schedule.
+                if (!oneShot && !parseCronExpression(args.schedule)) {
+                    return errResult(`Invalid cron expression: ${args.schedule}`);
+                }
+                if (Buffer.byteLength(args.prompt, 'utf8') > MAX_PROMPT_BYTES) {
+                    return errResult(`prompt too long (max ${MAX_PROMPT_BYTES} bytes).`);
+                }
+                const recurring = args.recurring ?? !oneShot;
+                const now = Date.now();
+                const nextRun = computeNextRun(args.schedule, recurring, now);
+                if (nextRun === null) {
+                    return errResult(oneShot
+                        ? 'one-shot time is in the past or invalid.'
+                        : `schedule never matches (impossible cron): ${args.schedule}`);
+                }
+                const task = {
+                    id: crypto.randomUUID(),
+                    schedule: args.schedule,
+                    recurring,
+                    prompt: args.prompt,
+                    channelId: coords.channelId,
+                    channelType: coords.channelType,
+                    fromUid: coords.fromUid,
+                    fromName: coords.fromName,
+                    createdBy: coords.fromUid,
+                    enabled: true,
+                    createdAt: now,
+                    lastRun: null,
+                    nextRun,
+                };
+                // Atomic read-modify-write; re-check the cap inside the mutator so a
+                // concurrent create can't push us over the limit.
+                let capped = false;
+                cronStore.update((tasks) => {
+                    if (tasks.length >= MAX_TASKS_PER_BOT) {
+                        capped = true;
+                        return tasks;
+                    }
+                    return [...tasks, task];
+                });
+                if (capped) {
+                    return errResult(`task limit reached (max ${MAX_TASKS_PER_BOT}). Delete one first.`);
+                }
+                return jsonResult({ created: summarize(task) });
+            }
+            catch (err) {
+                return errResult(err instanceof Error ? err.message : String(err));
+            }
+        }),
+        tool('cron_list', 'List the scheduled tasks bound to this bot.', {}, async () => {
+            try {
+                return jsonResult({ tasks: cronStore.loadOrEmpty().map(summarize) });
+            }
+            catch (err) {
+                return errResult(err instanceof Error ? err.message : String(err));
+            }
+        }),
+        tool('cron_delete', 'Delete a scheduled task by its id. Only the bot owner may delete tasks.', { id: z.string().min(1).describe('The task id (from cron_list).') }, async (args) => {
+            try {
+                if (!isOwner) {
+                    return errResult('Only the bot owner can delete scheduled tasks.');
+                }
+                let found = false;
+                cronStore.update((tasks) => {
+                    const next = tasks.filter((t) => t.id !== args.id);
+                    found = next.length !== tasks.length;
+                    return found ? next : tasks;
+                });
+                if (!found) {
+                    return errResult(`no task with id ${args.id}`);
+                }
+                return jsonResult({ deleted: args.id });
+            }
+            catch (err) {
+                return errResult(err instanceof Error ? err.message : String(err));
+            }
+        }),
+    ];
+}
+/**
+ * Build the cron MCP server for one agent turn. `coords` binds created tasks to
+ * this session; `ownerUid` gates create/delete to the bot owner.
+ */
+export function createCronToolServer(cronStore, coords, ownerUid) {
+    return createSdkMcpServer({
+        name: CRON_TOOL_SERVER_NAME,
+        version: '1.0.0',
+        tools: buildCronTools(cronStore, coords, ownerUid),
+    });
+}
+//# sourceMappingURL=cron-tool.js.map

package/dist/cron-tool.js.map

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

package/dist/cwd-resolver.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Q3: Per-session cwd isolation under a shared `cwdBase`.
+ *
+ * Each session maps to a deterministic 16-hex sha256 prefix directory inside
+ * `cwdBase`, so one user's working tree cannot be read or mutated from another
+ * user's session while operators still allocate a single disk root for the bot.
+ *
+ * The partition key is the *exact* `sessionKey` the SessionRouter already
+ * produced for history (`SessionRouter.sessionKey()`), prefixed by the channel
+ * kind. Reusing the router key verbatim — rather than re-deriving spaceId or
+ * channel_id from the raw message — guarantees the cwd partition can never
+ * drift from the history partition:
+ *
+ *   - DM:    sessionKey = `${spaceId}:${uid}` (or bare `uid`)   → `dm:<key>`
+ *   - Group: sessionKey = `${channel_id}`                       → `group:<key>`
+ *
+ * Group sessionKey is the channel id alone, so ALL members of a group share one
+ * sandbox (a group is a collective workspace). DM is per-user, so each peer gets
+ * a private sandbox. The `kind` prefix keeps a DM key and a group key that
+ * happen to be byte-identical from colliding. (Group sharing reverses the
+ * per-(channel×user) split from PR #64 — intentional; space isolation is
+ * provided by one-bot-per-space, each with its own cwdBase.)
+ */
+/**
+ * Per-session routing context for cwd isolation. `kind` is the channel class
+ * and `sessionKey` is the router-produced key the session's history is stored
+ * under — see `SessionRouter.sessionKey()`. Passing the router key directly
+ * (instead of re-deriving uid/spaceId/channel_id here) is what keeps the cwd
+ * and history partitions byte-for-byte consistent.
+ */
+export type SessionCtx = {
+    kind: 'dm' | 'group';
+    sessionKey: string;
+};
+/** 7 days — long enough for a vacation, short enough to bound disk growth. */
+export declare const DEFAULT_CWD_TTL_MS: number;
+/**
+ * Compute the SDK auto-memory directory for a session under `memoryBase`.
+ *
+ * Deliberately a PURE function — unlike resolveSessionCwd it does NOT mkdir,
+ * touch mtime, or write a registry marker. The SDK creates the directory on
+ * first use, and we want auto-memory to be PERMANENT (no TTL): `memoryBase`
+ * lives outside `cwdBase`, so the cwd TTL sweep (cleanupExpiredCwds) never sees
+ * it. Uses the same kind-prefixed sha256 hashing as the cwd sandbox so the
+ * memory partition tracks the session partition exactly (group=shared per
+ * channel, DM=private per peer).
+ */
+export declare function resolveMemoryDir(memoryBase: string, ctx: SessionCtx): string;
+/**
+ * Resolve and ensure the per-session cwd exists. Idempotent — safe to call
+ * on every turn. Returns the absolute path under `cwdBase`.
+ *
+ * Note: the TTL tracks last *bot turn* (this function bumps the dir mtime on
+ * every call), not arbitrary filesystem activity inside the sandbox. A session
+ * with no inbound message for `ttlMs` is reclaimed even if a background process
+ * is still touching files inside it.
+ */
+export declare function resolveSessionCwd(cwdBase: string, ctx: SessionCtx): string;
+/**
+ * Sweep `cwdBase` for hashed session dirs whose mtime is older than `ttlMs`
+ * and remove them. Best-effort: failures are logged, never thrown — the bot
+ * must continue running even if disk cleanup hits a permission error.
+ *
+ * Silent no-op when `cwdBase` does not exist (e.g. first-run before any
+ * session has been resolved).
+ *
+ * A dir is eligible for deletion only when ALL hold: the name matches the
+ * 16-hex pattern, it is a real directory (not a symlink), and it has a matching
+ * entry in the `.cc-octo-sessions` registry (P0-3). The registry entry is
+ * removed alongside the dir.
+ */
+export declare function cleanupExpiredCwds(cwdBase: string, ttlMs?: number): void;