@qihongmu/dsh-plugins-scheduled-task 0.1.0

package/lib/types/index.js

@@ -0,0 +1,506 @@
+/**
+ * External global scheduled-task capability: durable registry, scheduler,
+ * delivery, and Remote surface. Reuses only shipped dsh API — no repo edits.
+ * @module @qihongmu/dsh-plugins-scheduled-task
+ */
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+import { createHash, randomUUID } from 'node:crypto';
+import { Service } from '@deepseek-ai/cordis';
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { SessionId } from '@deepseek-ai/dsh-session';
+import { WorkspaceId } from '@deepseek-ai/dsh-workspace';
+import { setApprovalPolicy } from '@deepseek-ai/dsh-user-approval';
+import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
+import { advanceRule, buildRule, renderTaskFraming, ScheduledTaskError, ScheduledTaskId, scheduledTaskView, validatePrompt, validateTitle, } from "./domain.js";
+import { scheduledTaskDomainSpec } from "./spec.js";
+export { ScheduledTaskError, ScheduledTaskId, advanceRule, buildRule, renderTaskFraming, scheduledTaskView, validatePrompt, validateTitle, } from "./domain.js";
+export { scheduledTaskDomainSpec, scheduledTaskRecord } from "./spec.js";
+/** Largest delay Node timers represent without clamping. */
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Render an unknown value for process-local diagnostics only. */
+function renderThrown(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+/**
+ * Retry delay after `count` consecutive admission failures: 30s doubling,
+ * capped at 5 minutes. Exported pure for tests.
+ */
+export function admissionBackoffMs(count) {
+    return Math.min(30_000 * 2 ** (count - 1), 300_000);
+}
+/**
+ * Delay until the earliest active task's scheduled instant: an overdue target
+ * fires immediately (0), a far target is clamped to the maximum timer delay,
+ * and a schedule with no finite active target arms nothing (`undefined`).
+ * Exported pure for tests; `rearm` is its only consumer.
+ */
+export function nextDelayMs(records, now) {
+    let earliest;
+    for (const [, record] of records) {
+        if (record.status !== 'active')
+            continue;
+        const target = Date.parse(record.rule.scheduledAt);
+        if (Number.isFinite(target) && (earliest === undefined || target < earliest))
+            earliest = target;
+    }
+    if (earliest === undefined)
+        return undefined;
+    return Math.min(Math.max(earliest - now, 0), MAX_TIMER_DELAY_MS);
+}
+/**
+ * Whether a resume failure means the run session simply is not persisted yet
+ * (first run of this task+project pair) — the only case where falling back to
+ * `create` is safe. Any other failure is rethrown so it surfaces as a visible
+ * task error instead of silently re-creating a session under the same id.
+ *
+ * The upstream agents service has no stable machine-readable "missing session"
+ * contract, so this matches the human-readable phrasings it emits today.
+ * Caveat: an upstream copy change silently breaks resume-vs-create
+ * discrimination (a truly missing session would then be rethrown as a visible
+ * task error, never silently re-created). If upstream ever exposes a stable
+ * error type/code, prefer that over this regex.
+ */
+function isMissingSessionError(error) {
+    return /\bnot found\b|\bdoes not exist\b|\bno such session\b|\bunknown session\b/
+        .test(renderThrown(error).toLowerCase());
+}
+/**
+ * Deterministic run-session identity for one task+project pair. Deriving the id
+ * from the cwd makes a project edit migrate the task to a FRESH conversation in
+ * the new workspace (workspace listings index sessions by their header's
+ * canonical cwd), while toggling back to an earlier project re-attaches that
+ * project's existing history.
+ */
+function runSessionIdOf(taskId, cwd) {
+    const digest = createHash('sha256').update(cwd).digest('hex').slice(0, 8);
+    return SessionId(`task-${taskId}-${digest}`);
+}
+/** Whether a table entry is a task currently due for admission. */
+function isDue(record, now) {
+    return record.status === 'active' && Date.parse(record.rule.scheduledAt) <= now;
+}
+/** Merge optional carry fields (prompt/project/model/confirmation) onto a record. */
+function applyCarry(target, carry) {
+    if (carry.prompt !== undefined)
+        target.prompt = validatePrompt(carry.prompt);
+    if (carry.confirmBeforeChange !== undefined)
+        target.confirmBeforeChange = carry.confirmBeforeChange;
+    if (carry.workspaceId !== undefined)
+        target.workspaceId = carry.workspaceId;
+    if (carry.cwd !== undefined)
+        target.cwd = carry.cwd;
+    if (carry.model !== undefined)
+        target.model = carry.model;
+    return target;
+}
+/**
+ * Global scheduled-task capability. The `tasks` storage-domain table is the
+ * only durable task authority; the in-memory table is its live projection, and
+ * the single timer is a disposable projection of the earliest due target. Each
+ * task's run Session is created lazily on first fire and kept live while the
+ * process runs.
+ */
+let ScheduledTaskService = (() => {
+    let _classSuper = TypertRemoteService;
+    let _instanceExtraInitializers = [];
+    let _list_decorators;
+    let _create_decorators;
+    let _update_decorators;
+    let _setStatus_decorators;
+    let _delete_decorators;
+    let _markRead_decorators;
+    return class ScheduledTaskService extends _classSuper {
+        static {
+            const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(_classSuper[Symbol.metadata] ?? null) : void 0;
+            _list_decorators = [Remote];
+            _create_decorators = [Remote];
+            _update_decorators = [Remote];
+            _setStatus_decorators = [Remote];
+            _delete_decorators = [Remote];
+            _markRead_decorators = [Remote];
+            __esDecorate(this, null, _list_decorators, { kind: "method", name: "list", static: false, private: false, access: { has: obj => "list" in obj, get: obj => obj.list }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _create_decorators, { kind: "method", name: "create", static: false, private: false, access: { has: obj => "create" in obj, get: obj => obj.create }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _update_decorators, { kind: "method", name: "update", static: false, private: false, access: { has: obj => "update" in obj, get: obj => obj.update }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _setStatus_decorators, { kind: "method", name: "setStatus", static: false, private: false, access: { has: obj => "setStatus" in obj, get: obj => obj.setStatus }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _delete_decorators, { kind: "method", name: "delete", static: false, private: false, access: { has: obj => "delete" in obj, get: obj => obj.delete }, metadata: _metadata }, null, _instanceExtraInitializers);
+            __esDecorate(this, null, _markRead_decorators, { kind: "method", name: "markRead", static: false, private: false, access: { has: obj => "markRead" in obj, get: obj => obj.markRead }, metadata: _metadata }, null, _instanceExtraInitializers);
+            if (_metadata) Object.defineProperty(this, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+        }
+        /** Services required before tasks can be listed, mutated, or fired. */
+        static inject = ['storageDomain', 'agents', 'sessions', 'sessionTitle', 'workspaceRegistry'];
+        table = __runInitializers(this, _instanceExtraInitializers);
+        timer;
+        handles = new Map();
+        /** Last task title pinned onto each run session (avoids re-rename spam). */
+        appliedTitles = new Map();
+        /** Run sessions already attached to their bound workspace (avoids re-attach churn). */
+        attachedSessions = new Set();
+        /** Consecutive admission failures per task, backing off the next retry. */
+        failures = new Map();
+        stopping = false;
+        constructor(ctx) {
+            super(ctx, 'scheduledTasks');
+        }
+        /** Open the domain, arm the first timer, and register teardown. */
+        async [Service.init]() {
+            const domain = await this.ctx.storageDomain.open(scheduledTaskDomainSpec);
+            this.ctx.effect(() => () => domain.close(), 'scheduled-task.domainClose');
+            this.table = domain.table('tasks');
+            this.ctx.effect(() => () => { void this.teardown(); }, 'scheduled-task.teardown');
+            this.rearm();
+        }
+        /**
+         * List every task, earliest target first, with wall-clock-derived view fields.
+         * @returns The complete client-facing task list.
+         */
+        list() {
+            const now = Date.now();
+            return [...this.requireTable().entries()]
+                .map(([, record]) => scheduledTaskView(record, now))
+                .sort((left, right) => Date.parse(left.rule.scheduledAt) - Date.parse(right.rule.scheduledAt)
+                || String(left.id).localeCompare(String(right.id)));
+        }
+        /**
+         * Create one task from a non-empty title and exactly one schedule selector.
+         * @param input - Task instruction and schedule selector.
+         * @returns The created task view or a stable error.
+         */
+        async create(input) {
+            try {
+                const title = validateTitle(input.title);
+                const prompt = validatePrompt(input.prompt);
+                const rule = buildRule(input, Date.now());
+                if (rule === undefined) {
+                    return { ok: false, code: 'invalid_selector', message: 'scheduled tasks accept exactly one of after_seconds, at, or every_seconds.' };
+                }
+                const id = ScheduledTaskId(randomUUID());
+                const record = applyCarry({
+                    id,
+                    title,
+                    prompt,
+                    rule,
+                    status: 'active',
+                    sessionId: SessionId(`task-${id}`),
+                    createdAt: new Date().toISOString(),
+                    confirmBeforeChange: false,
+                }, input);
+                await this.requireTable().put(id, record);
+                this.rearm();
+                return { ok: true, task: scheduledTaskView(record, Date.now()) };
+            }
+            catch (error) {
+                return this.asMutationError(error);
+            }
+        }
+        /**
+         * Edit a task's title and/or schedule; absent fields keep their stored value.
+         * @param id - Task to edit.
+         * @param input - Replacement title and/or schedule selector.
+         * @returns The updated task view or a stable error.
+         */
+        async update(id, input) {
+            try {
+                const record = this.requireTable().get(id);
+                if (record === undefined)
+                    return this.notFound(id);
+                const title = input.title === undefined ? record.title : validateTitle(input.title);
+                const rule = buildRule(input, Date.now()) ?? record.rule;
+                const next = applyCarry({ ...record, title, rule }, input);
+                await this.requireTable().put(id, next);
+                this.rearm();
+                return { ok: true, task: scheduledTaskView(next, Date.now()) };
+            }
+            catch (error) {
+                return this.asMutationError(error);
+            }
+        }
+        /**
+         * Pause or resume an active/paused task; completed tasks reject.
+         * @param id - Task to change.
+         * @param status - Target lifecycle status (`active` or `paused`).
+         * @returns The updated task view or a stable error.
+         */
+        async setStatus(id, status) {
+            try {
+                const record = this.requireTable().get(id);
+                if (record === undefined)
+                    return this.notFound(id);
+                if (record.status === 'completed') {
+                    return { ok: false, code: 'invalid_rule', message: 'a completed task cannot change status.' };
+                }
+                const next = { ...record, status };
+                await this.requireTable().put(id, next);
+                this.rearm();
+                return { ok: true, task: scheduledTaskView(next, Date.now()) };
+            }
+            catch (error) {
+                return this.asMutationError(error);
+            }
+        }
+        /**
+         * Delete one task and dispose its live run Agent, if any.
+         * @param id - Task to delete.
+         * @returns Whether a task was deleted, or a stable error.
+         */
+        async delete(id) {
+            try {
+                const deleted = await this.requireTable().delete(id);
+                if (deleted) {
+                    const handle = this.handles.get(id);
+                    if (handle !== undefined) {
+                        this.handles.delete(id);
+                        await handle.dispose();
+                    }
+                    this.failures.delete(id);
+                    this.rearm();
+                }
+                return { ok: true, deleted };
+            }
+            catch {
+                return { ok: false, code: 'internal_error', message: 'The scheduled task delete failed.' };
+            }
+        }
+        /**
+         * Mark one task read; unknown ids are an idempotent no-op.
+         * @param id - Task to mark read.
+         * @returns `null` after the durable read mark, when one was written.
+         */
+        async markRead(id) {
+            const record = this.requireTable().get(id);
+            if (record !== undefined && record.lastRunAt !== undefined) {
+                await this.requireTable().put(id, { ...record, lastReadAt: new Date().toISOString() });
+            }
+            return null;
+        }
+        notFound(id) {
+            return { ok: false, code: 'task_not_found', message: `no scheduled task '${id}'.` };
+        }
+        asMutationError(error) {
+            if (error instanceof ScheduledTaskError)
+                return { ok: false, code: error.code, message: error.message };
+            return { ok: false, code: 'internal_error', message: 'The scheduled task operation failed.' };
+        }
+        requireTable() {
+            if (this.table === undefined)
+                throw new Error('scheduled task service is not started yet');
+            return this.table;
+        }
+        /** Cancel and re-derive the single timer from the earliest due active task. */
+        rearm() {
+            if (this.timer !== undefined) {
+                clearTimeout(this.timer);
+                this.timer = undefined;
+            }
+            if (this.stopping)
+                return;
+            const table = this.table;
+            if (table === undefined)
+                return;
+            const delay = nextDelayMs(table.entries(), Date.now());
+            if (delay === undefined)
+                return;
+            this.timer = setTimeout(() => {
+                this.timer = undefined;
+                void this.fireDue(Date.now());
+            }, delay);
+        }
+        /** Fire every currently due active task, then re-arm. */
+        async fireDue(now) {
+            if (this.stopping)
+                return;
+            const due = [...this.requireTable().entries()].filter(([id, record]) => {
+                if (!isDue(record, now))
+                    return false;
+                // Tasks in failure backoff wait for their retry window even while the
+                // stored schedule instant is still in the past.
+                return (this.failures.get(id)?.retryAfter ?? 0) <= now;
+            });
+            // Fire independently: one hanging admission must not delay the others.
+            await Promise.allSettled(due.map(([id, record]) => this.fireOne(id, record, now)));
+            this.rearm();
+        }
+        /** Queue one task run, advance its durable record, and flush its Session. */
+        async fireOne(id, record, now) {
+            try {
+                const { agent, sessionId } = await this.ensureAgent(record);
+                // Pin the conversation title to the task title (re-pins only on change,
+                // and retroactively fixes sessions created before this pinning existed).
+                this.pinSessionTitle(sessionId, record, agent);
+                // List the conversation under the bound workspace project (membership is
+                // an explicit per-workspace session list, not derived from cwd).
+                await this.attachRunSession(record, sessionId);
+                // Apply the stored confirm-before-change policy before the run's first step.
+                setApprovalPolicy(agent.session, record.confirmBeforeChange ? 'ask' : 'never');
+                agent.followup(createUserMessage({
+                    content: [{ type: 'text', text: renderTaskFraming(record) }],
+                    source: { kind: 'plugin', plugin: 'scheduled-task' },
+                }));
+                const runAt = new Date(now).toISOString();
+                const advanced = advanceRule(record.rule, now);
+                const next = {
+                    ...record,
+                    sessionId,
+                    rule: advanced ?? record.rule,
+                    status: advanced === undefined ? 'completed' : record.status,
+                    lastRunAt: runAt,
+                    lastError: undefined,
+                };
+                this.failures.delete(id);
+                await this.requireTable().put(id, next);
+                await this.ctx.sessions.flush(agent.session);
+            }
+            catch (error) {
+                const message = renderThrown(error);
+                this.ctx.logger.warn(`scheduled-task: could not fire task "${id}": ${message}`);
+                // Record the failure on the task and back off the retry (30s doubling to
+                // 5min) so a persistently failing admission does not hot-loop while its
+                // schedule instant stays in the past. In-memory only; a restart retries
+                // immediately.
+                const previous = this.failures.get(id)?.count ?? 0;
+                const count = previous + 1;
+                const retryAfter = now + admissionBackoffMs(count);
+                this.failures.set(id, { count, retryAfter });
+                try {
+                    await this.requireTable().put(id, {
+                        ...record,
+                        lastError: { at: new Date(now).toISOString(), message },
+                    });
+                }
+                catch (persistError) {
+                    this.ctx.logger.warn(`scheduled-task: could not persist failure of task "${id}": ${renderThrown(persistError)}`);
+                }
+            }
+        }
+        /**
+         * Attach the run session to the task's bound workspace so the conversation
+         * lists under that project instead of "ungrouped" (workspace membership is
+         * an explicit durable session list; the entity validates the session header's
+         * canonical cwd against the workspace path and attach is idempotent).
+         */
+        async attachRunSession(record, sessionId) {
+            if (record.workspaceId === undefined)
+                return;
+            const key = `${record.workspaceId}:${sessionId}`;
+            if (this.attachedSessions.has(key))
+                return;
+            const workspace = this.ctx.workspaceRegistry.get(WorkspaceId(record.workspaceId));
+            if (workspace === undefined) {
+                this.ctx.logger.warn(`scheduled-task: workspace "${record.workspaceId}" not found for task "${record.id}"`);
+                return;
+            }
+            try {
+                await workspace.attachSession(sessionId);
+                this.attachedSessions.add(key);
+            }
+            catch (error) {
+                this.ctx.logger.warn(`scheduled-task: could not attach session "${sessionId}" to workspace: ${renderThrown(error)}`);
+            }
+        }
+        /**
+         * Pin the session's conversation title to the task title via the
+         * session-title service (a `user`-source rename pins against automatic
+         * regeneration). Keyed per SESSION so a migrated run session is titled too;
+         * re-pins only when the stored title changed since the last applied pin.
+         */
+        pinSessionTitle(sessionId, record, agent) {
+            if (this.appliedTitles.get(sessionId) === record.title)
+                return;
+            const titles = this.ctx.sessionTitle;
+            try {
+                titles.rename(agent.session, record.title);
+                this.appliedTitles.set(sessionId, record.title);
+            }
+            catch (error) {
+                this.ctx.logger.warn(`scheduled-task: could not title session "${sessionId}": ${renderThrown(error)}`);
+            }
+        }
+        /**
+         * Resolve the live run Agent for a task's CURRENT project. The durable
+         * session identity is derived from the task id + cwd (`runSessionIdOf`), so
+         * an edited project transparently starts a fresh conversation inside the new
+         * workspace while returning to an earlier project resumes that project's
+         * existing history. Returns the possibly-new sessionId for persistence.
+         */
+        async ensureAgent(record) {
+            const desiredCwd = record.cwd ?? process.cwd();
+            const targetId = runSessionIdOf(record.id, desiredCwd);
+            const agentOptions = record.model === undefined
+                ? undefined
+                : { provider: record.model.provider, model: record.model.model };
+            // A retained run handle is reused only when it still matches the target.
+            const retained = this.handles.get(record.id);
+            if (retained !== undefined) {
+                if (retained.agent.session.id === targetId && retained.agent.session.header.cwd === desiredCwd) {
+                    return { agent: retained.agent, sessionId: targetId };
+                }
+                this.handles.delete(record.id);
+                await retained.dispose();
+            }
+            let handle;
+            try {
+                handle = await this.ctx.agents.resume({
+                    resumeSessionId: targetId,
+                    ...agentOptions === undefined ? {} : { agentOptions },
+                });
+            }
+            catch (resumeError) {
+                if (!isMissingSessionError(resumeError))
+                    throw resumeError;
+                // Not persisted yet (first run for this task+project pair): create it in-project.
+                handle = await this.ctx.agents.create({
+                    sessionId: targetId,
+                    meta: { cwd: desiredCwd },
+                    ...agentOptions === undefined ? {} : { agentOptions },
+                });
+            }
+            this.handles.set(record.id, handle);
+            return { agent: handle.agent, sessionId: targetId };
+        }
+        /** Cancel the timer and dispose every retained run Agent. */
+        async teardown() {
+            this.stopping = true;
+            if (this.timer !== undefined) {
+                clearTimeout(this.timer);
+                this.timer = undefined;
+            }
+            const handles = [...this.handles.values()];
+            this.handles.clear();
+            await Promise.allSettled(handles.map(handle => handle.dispose()));
+        }
+    };
+})();
+export { ScheduledTaskService };
+export default ScheduledTaskService;

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for the external scheduled-task plugin.
+ * @module @qihongmu/dsh-plugins-scheduled-task/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis invariant-companion plugin name. */
+export declare const name = "scheduled-task-invariant";
+/** Service required before reserving this package's invariant ownership. */
+export declare const inject: string[];
+/**
+ * Register the package-owned invariant companion.
+ * @param ctx - Cordis context carrying the invariant registry.
+ * @returns Exact registration disposer after child setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/invariant.js

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for the external scheduled-task plugin.
+ * @module @qihongmu/dsh-plugins-scheduled-task/invariant
+ */
+const PACKAGE_NAME = '@qihongmu/dsh-plugins-scheduled-task';
+/** Cordis invariant-companion plugin name. */
+export const name = 'scheduled-task-invariant';
+/** Service required before reserving this package's invariant ownership. */
+export const inject = ['invariants'];
+/**
+ * Owned relationship: a task enters `completed` only after its run recorded
+ * `lastRunAt`. The service sets both in one durable put, so a completed record
+ * without a run timestamp proves a write path bypassed the scheduler.
+ */
+const install = Object.assign((ctx, fail) => {
+    ctx.on('domain/changed', (change) => {
+        if (change.domain !== 'scheduled_task' || change.table !== 'tasks' || change.operation !== 'put')
+            return;
+        const record = change.value;
+        if (record.status === 'completed' && record.lastRunAt === undefined) {
+            fail(`scheduled task '${String(record.id)}' entered completed without lastRunAt`);
+        }
+    });
+}, { inject: [] });
+/**
+ * Register the package-owned invariant companion.
+ * @param ctx - Cordis context carrying the invariant registry.
+ * @returns Exact registration disposer after child setup succeeds.
+ */
+export const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));