@deepseek-ai/dsh-schedule 0.1.1-rc.2 → 0.1.2-alpha.2

package/lib/types/index.js

@@ -0,0 +1,57 @@
+/**
+ * Agent-scoped durable one-shot and fixed-rate reminders over the session event log.
+ * @module @deepseek-ai/dsh-schedule
+ */
+import { scheduleProjectionDefinition } from "./projection.js";
+import { ScheduleRuntime } from "./runtime.js";
+import { registerScheduleTools } from "./tools.js";
+export { SCHEDULE_CHANGE_VERSION, MIN_EVERY_INTERVAL_SECONDS, ScheduleId, ScheduleInputError, ScheduleLogError, allocateScheduleId, createAfterScheduleRecord, createAtScheduleRecord, createEveryScheduleRecord, decodeScheduleChange, foldScheduleEvents, renderReminderFraming, renderEveryReminderBatchFraming, resolveEveryOccurrence, scheduleView, } from "./domain.js";
+export { registerScheduleTools } from "./tools.js";
+/** Cordis function-plugin name. */
+export const name = 'schedule';
+/** Services required before future root agents can receive Schedule. */
+export const inject = ['agents', 'sessions', 'tools', 'sessionPersistence'];
+/** Install Schedule only for root agents published after this plugin loads. */
+export function apply(ctx) {
+    ctx.inject(['sessionProjections'], (projectionCtx) => {
+        projectionCtx.sessionProjections.register(scheduleProjectionDefinition);
+    });
+    const runtimes = new Map();
+    let stopping = false;
+    ctx.effect(() => {
+        const stopCreated = ctx.on('agent/created', ({ agent }) => {
+            if (stopping || runtimes.has(agent) || !ctx.agents.roots().includes(agent))
+                return;
+            const runtime = new ScheduleRuntime(ctx, agent);
+            const cleanup = agent.ctx.effect(() => {
+                const disposeTools = registerScheduleTools(ctx, agent.ctx, agent, () => { runtime.requestDrive(); });
+                const stopStatus = agent.ctx.on('agent/status', ({ status }) => {
+                    if (status === 'idle' && agent.session.events.some(event => event.type === 'schedule/change')) {
+                        runtime.requestDrive();
+                    }
+                });
+                runtime.start();
+                return async () => {
+                    stopStatus();
+                    disposeTools();
+                    try {
+                        await runtime.dispose();
+                    }
+                    finally {
+                        if (runtimes.get(agent) === cleanup)
+                            runtimes.delete(agent);
+                    }
+                };
+            }, 'schedule.runtime()');
+            runtimes.set(agent, cleanup);
+        });
+        return async () => {
+            stopping = true;
+            stopCreated();
+            const cleanups = [...runtimes.values()];
+            runtimes.clear();
+            await Promise.allSettled(cleanups.map(cleanup => Promise.resolve(cleanup())));
+        };
+    }, 'schedule.lifecycle()');
+}
+//# sourceMappingURL=index.js.map

package/lib/types/invariant.js

@@ -0,0 +1,48 @@
+/**
+ * Package-owned strict Schedule stream invariant.
+ * @module @deepseek-ai/dsh-schedule/invariant
+ */
+import { foldScheduleEvents, ScheduleLogError } from "./domain.js";
+const PACKAGE_NAME = '@deepseek-ai/dsh-schedule';
+/** Cordis invariant-companion plugin name. */
+export const name = 'tool-schedule-invariant';
+/** Service required before reserving this package's invariant ownership. */
+export const inject = ['invariants'];
+/** Validate a complete exact-session stream under its fork suffix policy. */
+function validate(events, seedLength, fail) {
+    try {
+        foldScheduleEvents(events, seedLength);
+    }
+    catch (error) {
+        /* v8 ignore next -- foldScheduleEvents normalizes every rejected stream to ScheduleLogError. */
+        if (!(error instanceof ScheduleLogError))
+            throw error;
+        fail(error.message);
+    }
+}
+/* jscpd:ignore-start -- package companions share replay and dispatch plumbing */
+/** Install replay and pre-append validation for the owned event stream. */
+const install = Object.assign((ctx, fail) => {
+    for (const session of ctx.sessions.list()) {
+        validate(session.events, session.header.seedLength ?? 0, fail);
+    }
+    ctx.on('session/created', (session) => {
+        validate(session.events, session.header.seedLength ?? 0, fail);
+    }, { global: true });
+    ctx.on('internal/dispatch', (_mode, eventName, args) => {
+        if (eventName !== 'session/event')
+            return;
+        const [session, event] = args;
+        if (event.type !== 'schedule/change')
+            return;
+        validate([...session.events, event], session.header.seedLength ?? 0, fail);
+    }, { global: true });
+}, { inject: ['sessions'] });
+/* jscpd:ignore-end */
+/**
+ * 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));
+//# sourceMappingURL=invariant.js.map

package/lib/types/persistence.js

@@ -0,0 +1,30 @@
+/** Schedule-owned use of the shared session durability barrier. */
+/** Failure to prove that the current live prefix reached a persistence listener. */
+export class SchedulePersistenceError extends Error {
+    /**
+     * Construct a contained persistence failure.
+     * @param cause - Rejection returned by the shared barrier, when present.
+     */
+    constructor(cause) {
+        super('Schedule persistence did not complete.', cause === undefined ? undefined : { cause });
+        this.name = 'SchedulePersistenceError';
+    }
+}
+/**
+ * Require one successful shared persistence checkpoint.
+ * @param ctx - Context carrying the live session store.
+ * @param session - Exact live session to checkpoint.
+ * @returns After at least one listener explicitly acknowledges completed durability work.
+ */
+export async function flushSchedulePersistence(ctx, session) {
+    try {
+        if (!await ctx.sessions.flush(session))
+            throw new SchedulePersistenceError();
+    }
+    catch (error) {
+        if (error instanceof SchedulePersistenceError)
+            throw error;
+        throw new SchedulePersistenceError(error);
+    }
+}
+//# sourceMappingURL=persistence.js.map

package/lib/types/projection.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Strict Session projection of the Schedule domain's active reminder set.
+ * @module @deepseek-ai/dsh-schedule/projection
+ */
+import { z } from 'zod';
+import type { FoldedSchedules } from './domain.ts';
+import type { ScheduleRecord } from './types.ts';
+/** Persisted projection state: the immutable fork boundary plus the complete Schedule fold. */
+export interface ScheduleProjectionState extends FoldedSchedules {
+    readonly seedLength: number;
+}
+/** Projection definition sharing the Schedule domain's strict transition authority. */
+export declare const scheduleProjectionDefinition: {
+    key: "schedule";
+    stateSchema: z.ZodType<ScheduleProjectionState, unknown, z.core.$ZodTypeInternals<ScheduleProjectionState, unknown>>;
+    init: (header: import("@deepseek-ai/dsh-session").SessionHeader) => {
+        seedLength: number;
+        active: never[];
+        seenIds: never[];
+    };
+    apply: (state: NoInfer<ScheduleProjectionState>, event: import("@deepseek-ai/dsh-session").SessionEvent) => ScheduleProjectionState;
+    wire: {
+        viewSchema: z.ZodType<readonly ScheduleRecord[], unknown, z.core.$ZodTypeInternals<readonly ScheduleRecord[], unknown>>;
+        view: (state: NoInfer<ScheduleProjectionState>) => readonly ScheduleRecord[];
+    };
+    stateVersion: number;
+};
+declare module '@deepseek-ai/dsh-session-projection/types' {
+    interface SessionProjectionStateMap {
+        schedule: ScheduleProjectionState;
+    }
+}
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,67 @@
+/**
+ * Strict Session projection of the Schedule domain's active reminder set.
+ * @module @deepseek-ai/dsh-schedule/projection
+ */
+import { z } from 'zod';
+import { applyScheduleChanges, decodeScheduleChange } from "./domain.js";
+const scheduleId = z.unknown().transform((value, context) => {
+    try {
+        const change = decodeScheduleChange({ version: 1, operation: 'delete', id: value });
+        return change.id;
+    }
+    catch {
+        context.addIssue({ code: 'custom', message: 'invalid Schedule id' });
+        return z.NEVER;
+    }
+});
+const scheduleRecord = z.unknown().transform((value, context) => {
+    try {
+        const change = decodeScheduleChange({ version: 1, operation: 'create', schedule: value });
+        return change.schedule;
+    }
+    catch {
+        context.addIssue({ code: 'custom', message: 'invalid Schedule record' });
+        return z.NEVER;
+    }
+});
+const scheduleRecords = z.array(scheduleRecord);
+const scheduleProjectionStateSchema = z.object({
+    seedLength: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    active: scheduleRecords,
+    seenIds: z.array(scheduleId),
+}).strict().superRefine((state, context) => {
+    const seen = new Set(state.seenIds);
+    if (seen.size !== state.seenIds.length) {
+        context.addIssue({ code: 'custom', message: 'seen Schedule ids must be unique' });
+    }
+    const active = new Set();
+    for (const record of state.active) {
+        if (!seen.has(record.id)) {
+            context.addIssue({ code: 'custom', message: 'every active Schedule id must have been seen' });
+        }
+        if (active.has(record.id)) {
+            context.addIssue({ code: 'custom', message: 'active Schedule ids must be unique' });
+        }
+        active.add(record.id);
+    }
+});
+/** Projection definition sharing the Schedule domain's strict transition authority. */
+export const scheduleProjectionDefinition = {
+    key: 'schedule',
+    stateSchema: scheduleProjectionStateSchema,
+    init: header => ({ seedLength: header.seedLength ?? 0, active: [], seenIds: [] }),
+    apply: (state, event) => {
+        if (event.seq < state.seedLength || event.type !== 'schedule/change')
+            return state;
+        return {
+            seedLength: state.seedLength,
+            ...applyScheduleChanges(state, [decodeScheduleChange(event.data)]),
+        };
+    },
+    wire: {
+        viewSchema: scheduleRecords,
+        view: state => state.active,
+    },
+    stateVersion: 1,
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/runtime.js

@@ -0,0 +1,296 @@
+/**
+ * Disposable live timer projection for one exact root agent.
+ * @module @deepseek-ai/dsh-schedule
+ */
+import { createUserMessage } from '@deepseek-ai/dsh-llm';
+import { foldScheduleEvents, renderEveryReminderBatchFraming, renderReminderFraming, resolveEveryOccurrence, ScheduleLogError, } from "./domain.js";
+import { flushSchedulePersistence } from "./persistence.js";
+import { runScheduleTransaction } from "./transaction.js";
+/** Largest delay that Node timers represent without clamping. */
+export const MAX_TIMER_DELAY_MS = 2_147_483_647;
+/** Select one due one-shot, one complete fixed-rate batch, or the next wake. */
+function dueDecision(folded, now) {
+    const indexed = folded.active.map((record, index) => ({ record, index }));
+    const byTargetThenCreate = (left, right) => Date.parse(left.record.scheduledAt) - Date.parse(right.record.scheduledAt)
+        || left.index - right.index;
+    const oneShot = indexed
+        .filter((entry) => entry.record.kind !== 'every' && Date.parse(entry.record.scheduledAt) <= now)
+        .sort(byTargetThenCreate)[0]?.record;
+    if (oneShot !== undefined)
+        return { kind: 'one-shot', record: oneShot };
+    const every = indexed
+        .filter((entry) => entry.record.kind === 'every' && Date.parse(entry.record.scheduledAt) <= now)
+        .sort(byTargetThenCreate);
+    if (every.length > 0) {
+        return {
+            kind: 'every',
+            acceptedAt: new Date(now).toISOString(),
+            reminders: every.map(({ record }) => ({
+                record,
+                occurrenceAt: resolveEveryOccurrence(record, now).occurrenceAt,
+            })),
+        };
+    }
+    const target = folded.active.reduce((selected, record) => {
+        const candidate = Date.parse(record.scheduledAt);
+        return candidate > now && (selected === undefined || candidate < selected) ? candidate : selected;
+    }, undefined);
+    return { kind: 'wait', ...(target === undefined ? {} : { target }) };
+}
+/** Render an unknown value for process-local diagnostics only. */
+function renderThrown(value) {
+    return value instanceof Error ? value.message : String(value);
+}
+/** One process-local, disposable projection of an exact agent's durable schedules. */
+export class ScheduleRuntime {
+    ctx;
+    agent;
+    stop = Promise.withResolvers();
+    timer;
+    idleWait;
+    run;
+    requested = false;
+    stopping = false;
+    faulted = false;
+    disposal;
+    /**
+     * Construct an inactive runtime; {@link start} begins the first preflight.
+     * @param ctx - Global service context.
+     * @param agent - Exact live root agent.
+     */
+    constructor(ctx, agent) {
+        this.ctx = ctx;
+        this.agent = agent;
+    }
+    /** Begin the initial durability preflight and timer derivation. */
+    start() {
+        this.requestDrive();
+    }
+    /** Recompute the live projection after a committed mutation or idle transition. */
+    requestDrive() {
+        if (this.stopping || this.faulted)
+            return;
+        this.clearTimer();
+        this.requested = true;
+        if (this.run !== undefined)
+            return;
+        let run;
+        try {
+            run = this.ctx.agents.withoutInitiator(() => this.runRequested());
+        }
+        catch (error) {
+            if (this.isLive()) {
+                this.ctx.logger.warn(`schedule: could not start runtime for agent "${this.agent.id}": ${renderThrown(error)}`);
+            }
+            return;
+        }
+        this.run = run;
+        void run.then(() => { this.retire(run); }, (error) => {
+            if (this.isLive()) {
+                this.ctx.logger.warn(`schedule: runtime failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+            }
+            this.faulted = true;
+            this.retire(run);
+        });
+    }
+    /** Stop future work, cancel timers, and await every outstanding runtime promise. */
+    dispose() {
+        return (this.disposal ??= (async () => {
+            this.stopping = true;
+            this.requested = false;
+            this.clearTimer();
+            this.stop.resolve();
+            const pending = [this.run, this.idleWait].filter((value) => value !== undefined);
+            await Promise.allSettled(pending);
+        })());
+    }
+    /** Drain coalesced triggers serially. */
+    async runRequested() {
+        while (this.requested && !this.stopping && !this.faulted) {
+            this.requested = false;
+            await runScheduleTransaction(this.agent, () => this.driveOnce());
+        }
+    }
+    /** Retire one exact run and honor a trigger that landed during its final microtask. */
+    retire(run) {
+        /* v8 ignore next -- only the exact stored run installs this callback. */
+        if (this.run !== run)
+            return;
+        this.run = undefined;
+        /* v8 ignore next -- covers a trigger in the promise-settlement microtask gap. */
+        if (this.requested && !this.stopping && !this.faulted)
+            this.requestDrive();
+    }
+    /** Whether this exact root lifecycle remains authoritative. */
+    isLive() {
+        return this.ctx.agents.get(this.agent.id) === this.agent
+            && this.ctx.agents.roots().includes(this.agent);
+    }
+    /** Whether this runtime may start or continue Schedule work. */
+    isRunnable() {
+        return !this.stopping && this.isLive();
+    }
+    /** Cancel the currently armed timer, if any. */
+    clearTimer() {
+        if (this.timer === undefined)
+            return;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    }
+    /** Arm one bounded timer segment; every wake rechecks the wall clock. */
+    arm(target, now) {
+        const delay = Math.min(target - now, MAX_TIMER_DELAY_MS);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.requestDrive();
+        }, delay);
+    }
+    /** Await one public idle boundary without holding admission or creating a retry timer. */
+    waitForIdle() {
+        if (this.idleWait !== undefined)
+            return;
+        const wait = Promise.race([this.agent.whenIdle(), this.stop.promise]);
+        this.idleWait = wait;
+        void wait.then(() => {
+            this.idleWait = undefined;
+            this.requestDrive();
+        }, (error) => {
+            this.idleWait = undefined;
+            if (this.isLive()) {
+                this.ctx.logger.warn(`schedule: idle wait failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+            }
+        });
+    }
+    /** Fold the current exact runtime suffix and contain a corrupt durable stream. */
+    readFolded() {
+        try {
+            return foldScheduleEvents(this.agent.session.events, this.agent.session.header.seedLength ?? 0);
+        }
+        catch (error) {
+            this.faulted = true;
+            const detail = error instanceof ScheduleLogError ? error.message : renderThrown(error);
+            this.ctx.logger.warn(`schedule: corrupt schedule log for agent "${this.agent.id}": ${detail}`);
+            return undefined;
+        }
+    }
+    /** Contain an invalid wall-clock decision without permanently faulting this runtime. */
+    decide(folded, now) {
+        try {
+            return dueDecision(folded, now);
+        }
+        catch (error) {
+            this.ctx.logger.warn(`schedule: fixed-rate decision failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+            return undefined;
+        }
+    }
+    /** Preflight, fold, arm, or dispatch the next one-shot or fixed-rate batch. */
+    async driveOnce() {
+        this.clearTimer();
+        if (!this.isRunnable())
+            return;
+        try {
+            await flushSchedulePersistence(this.ctx, this.agent.session);
+        }
+        catch (error) {
+            if (this.isLive()) {
+                this.ctx.logger.warn(`schedule: preflight failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+            }
+            return;
+        }
+        if (!this.isRunnable())
+            return;
+        const folded = this.readFolded();
+        if (folded === undefined)
+            return;
+        const wakeNow = Date.now();
+        const wakeDecision = this.decide(folded, wakeNow);
+        if (wakeDecision === undefined)
+            return;
+        if (wakeDecision.kind === 'wait') {
+            if (wakeDecision.target !== undefined)
+                this.arm(wakeDecision.target, wakeNow);
+            return;
+        }
+        let maintenance;
+        try {
+            maintenance = this.agent.runMaintenance(() => {
+                if (!this.isRunnable())
+                    return Promise.resolve(false);
+                const claimed = this.readFolded();
+                if (claimed === undefined)
+                    return Promise.resolve(false);
+                const decisionNow = Date.now();
+                const decision = this.decide(claimed, decisionNow);
+                if (decision === undefined)
+                    return Promise.resolve(false);
+                if (decision.kind === 'wait') {
+                    if (decision.target !== undefined)
+                        this.arm(decision.target, decisionNow);
+                    return Promise.resolve(false);
+                }
+                try {
+                    const text = decision.kind === 'one-shot'
+                        ? renderReminderFraming(decision.record)
+                        : renderEveryReminderBatchFraming(decision.reminders);
+                    const message = createUserMessage({
+                        content: [{ type: 'text', text }],
+                        source: { kind: 'plugin', plugin: 'schedule' },
+                    });
+                    this.agent.followup(message);
+                }
+                catch (error) {
+                    if (this.isLive()) {
+                        this.ctx.logger.warn(`schedule: framing or followup failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+                    }
+                    return Promise.resolve(false);
+                }
+                try {
+                    if (decision.kind === 'one-shot') {
+                        this.agent.session.append('schedule/change', {
+                            version: 1,
+                            operation: 'dispatch',
+                            id: decision.record.id,
+                        });
+                    }
+                    else {
+                        for (const reminder of decision.reminders) {
+                            this.agent.session.append('schedule/change', {
+                                version: 1,
+                                operation: 'dispatch',
+                                id: reminder.record.id,
+                                acceptedAt: decision.acceptedAt,
+                            });
+                        }
+                    }
+                }
+                catch (error) {
+                    this.faulted = true;
+                    this.clearTimer();
+                    this.ctx.logger.warn(`schedule: dispatch append failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+                    return Promise.resolve(false);
+                }
+                return Promise.resolve(true);
+            });
+        }
+        catch (_busy) {
+            // `runMaintenance` rejects synchronously only while another agent activity owns the idle phase.
+            if (this.isLive())
+                this.waitForIdle();
+            return;
+        }
+        if (!await maintenance)
+            return;
+        try {
+            await flushSchedulePersistence(this.ctx, this.agent.session);
+        }
+        catch (error) {
+            if (this.isLive()) {
+                this.ctx.logger.warn(`schedule: dispatch barrier failed for agent "${this.agent.id}": ${renderThrown(error)}`);
+            }
+            return;
+        }
+        if (this.isRunnable())
+            this.requestDrive();
+    }
+}
+//# sourceMappingURL=runtime.js.map