@openacme/tasks 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Utkarsh Kanwat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { TASK_STATUSES, TaskStatusSchema, TaskFrontmatterSchema, RECURRENCE_SESSION_MODES, RecurrenceSchema, MIN_INTERVAL_MS, MAX_RECURRENCE_COUNT, type Recurrence, type RecurrenceSession, type Task, type TaskCreate, type TaskFrontmatter, type TaskListFilter, type TaskStatus, type TaskUpdate, } from "./types.js";
+export { computeNextFire, validateRecurrence, describeRecurrence, } from "./recurrence.js";
+export { TaskStore, TaskStoreError, type OnChangeFn, type TaskStoreOptions, } from "./store.js";
+export { COMMENT_KINDS, EVENT_KINDS, INBOX_KINDS, INBOX_SOURCES, } from "./ports.js";
+export type { Comment, CommentInput, CommentKind, CommentListOptions, CommentStorePort, EventInput, EventKind, EventStorePort, InboxKind, InboxSource, TaskEvent, } from "./ports.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,EACpB,KAAK,UAAU,EACf,KAAK,iBAAiB,EACtB,KAAK,IAAI,EACT,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,SAAS,EACT,cAAc,EACd,KAAK,UAAU,EACf,KAAK,gBAAgB,GACtB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC;AAEpB,YAAY,EACV,OAAO,EACP,YAAY,EACZ,WAAW,EACX,kBAAkB,EAClB,gBAAgB,EAChB,UAAU,EACV,SAAS,EACT,cAAc,EACd,SAAS,EACT,WAAW,EACX,SAAS,GACV,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { TASK_STATUSES, TaskStatusSchema, TaskFrontmatterSchema, RECURRENCE_SESSION_MODES, RecurrenceSchema, MIN_INTERVAL_MS, MAX_RECURRENCE_COUNT, } from "./types.js";
+export { computeNextFire, validateRecurrence, describeRecurrence, } from "./recurrence.js";
+export { TaskStore, TaskStoreError, } from "./store.js";
+export { COMMENT_KINDS, EVENT_KINDS, INBOX_KINDS, INBOX_SOURCES, } from "./ports.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,wBAAwB,EACxB,gBAAgB,EAChB,eAAe,EACf,oBAAoB,GASrB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,eAAe,EACf,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,iBAAiB,CAAC;AAEzB,OAAO,EACL,SAAS,EACT,cAAc,GAGf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,aAAa,EACb,WAAW,EACX,WAAW,EACX,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/ports.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Structural ports for external stores TaskStore depends on.
+ * Defined here (not imported from @openacme/db) so the tasks package
+ * stays free of a runtime dep on the DB. AgentManager wires the
+ * concrete DB-backed stores in; tests can pass mocks or omit them.
+ *
+ * **All "kind" unions for the task subsystem live here** — `CommentKind`
+ * for comments, `EventKind` for events. Magic strings elsewhere should
+ * narrow to one of these. Add new kinds at this central spot and the
+ * tools / routes / web mirrors will surface type errors at every site
+ * that needs updating.
+ */
+/**
+ * Canonical comment kinds. `null` (or undefined) = generic, untagged.
+ * Add new kinds HERE — every other place that types kinds (DB schema's
+ * drizzle enum hint, DB store types, web mirror) imports from here so
+ * the type checker surfaces every reader site that needs an update.
+ */
+export declare const COMMENT_KINDS: readonly ["result", "system"];
+export type CommentKind = (typeof COMMENT_KINDS)[number];
+export interface Comment {
+    id: string;
+    taskId: string;
+    author: string;
+    kind: CommentKind | null;
+    body: string;
+    createdAt: number;
+}
+export interface CommentInput {
+    taskId: string;
+    author: string;
+    body: string;
+    kind?: CommentKind | null;
+}
+export interface CommentListOptions {
+    limit?: number;
+    sinceTs?: number;
+    /** Inclusive kind filter. Pass `null` in the array to also include
+     *  untagged (default-kind) comments alongside the named kinds. */
+    kinds?: (CommentKind | null)[];
+}
+export interface CommentStorePort {
+    add(input: CommentInput): Comment;
+    list(taskId: string, opts?: CommentListOptions): Comment[];
+    latestResult(taskId: string): Comment | null;
+    countByTask(taskIds: string[]): Map<string, number>;
+    deleteByTask(taskId: string): void;
+}
+/**
+ * Canonical event kinds (single source of truth — see COMMENT_KINDS
+ * note above). Adding a new kind: extend the list here, then a single
+ * recompile narrows every reader (DB schema, store, prompt rendering,
+ * web activity log).
+ */
+export declare const EVENT_KINDS: readonly ["task_assigned", "status_changed", "dep_unblocked", "comment_added", "task_deleted", "scheduler_action", "task_completed_run", "ping_user"];
+export type EventKind = (typeof EVENT_KINDS)[number];
+/**
+ * Inbox row kinds. `user_message` payload is a UIMessage; `system_notice`
+ * payload is a small structured note rendered as text. Add new kinds
+ * here; the renderer in agent-core branches on this enum.
+ */
+export declare const INBOX_KINDS: readonly ["user_message", "system_notice"];
+export type InboxKind = (typeof INBOX_KINDS)[number];
+export declare const INBOX_SOURCES: readonly ["user", "system"];
+export type InboxSource = (typeof INBOX_SOURCES)[number];
+export interface EventInput {
+    /** Task this event is anchored to. Nullable for session-level events
+     *  (e.g. `ping_user` where the agent is not currently on a task).
+     *  At least one of (taskId, sessionId) must be set. */
+    taskId?: string | null;
+    /** Session this event is anchored to. Auto-derived from the task's
+     *  current session_id if absent and taskId is present. Required for
+     *  session-level events with no task anchor. */
+    sessionId?: string | null;
+    /** Semantic owner of the event (usually the assignee). Used for the
+     *  prompt's "actor X" rendering when no explicit actor is recorded. */
+    agentId: string;
+    /**
+     * Echo-suppression key, NOT a causation field. The scheduler suppresses
+     * wake when `event.actor === sessionTarget.agentId` — i.e. "this agent's
+     * own session should not wake from this event."
+     *
+     * When emitting a new event, pick the value by asking: would waking
+     * the actor's own session here cause a runaway loop (agent acts → wakes
+     * → acts again)? If yes, set `actor` to the actor's agent id. If no,
+     * use `null` — every involved session, including the actor's own,
+     * should wake.
+     *
+     * Causation and echo-target USUALLY coincide (status_changed,
+     * comment_added — the agent did the thing in their session, no need
+     * to wake themselves again). They DIVERGE for cross-session fan-out
+     * events like `dep_unblocked`: the closer caused it, but the wake
+     * target is a different session, so `actor: null` is correct
+     * (otherwise same-agent cross-session deps never wake).
+     */
+    actor?: string | null;
+    kind: EventKind;
+    payload?: unknown;
+}
+export interface TaskEvent {
+    id: string;
+    taskId: string | null;
+    sessionId: string | null;
+    agentId: string;
+    /** The actor that caused this event, if recorded. Null/undefined for
+     *  anonymous / system events that should never be echo-suppressed. */
+    actor?: string | null;
+    kind: string;
+    payload: string | null;
+    createdAt: number;
+}
+export interface EventStorePort {
+    append(input: EventInput): unknown;
+    recentForTasks(taskIds: string[], sinceTs: number, limit?: number): TaskEvent[];
+}
+//# sourceMappingURL=ports.d.ts.map

package/dist/ports.d.ts.map

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

package/dist/ports.js

@@ -0,0 +1,43 @@
+/**
+ * Structural ports for external stores TaskStore depends on.
+ * Defined here (not imported from @openacme/db) so the tasks package
+ * stays free of a runtime dep on the DB. AgentManager wires the
+ * concrete DB-backed stores in; tests can pass mocks or omit them.
+ *
+ * **All "kind" unions for the task subsystem live here** — `CommentKind`
+ * for comments, `EventKind` for events. Magic strings elsewhere should
+ * narrow to one of these. Add new kinds at this central spot and the
+ * tools / routes / web mirrors will surface type errors at every site
+ * that needs updating.
+ */
+/**
+ * Canonical comment kinds. `null` (or undefined) = generic, untagged.
+ * Add new kinds HERE — every other place that types kinds (DB schema's
+ * drizzle enum hint, DB store types, web mirror) imports from here so
+ * the type checker surfaces every reader site that needs an update.
+ */
+export const COMMENT_KINDS = ["result", "system"];
+/**
+ * Canonical event kinds (single source of truth — see COMMENT_KINDS
+ * note above). Adding a new kind: extend the list here, then a single
+ * recompile narrows every reader (DB schema, store, prompt rendering,
+ * web activity log).
+ */
+export const EVENT_KINDS = [
+    "task_assigned",
+    "status_changed",
+    "dep_unblocked",
+    "comment_added",
+    "task_deleted",
+    "scheduler_action",
+    "task_completed_run",
+    "ping_user",
+];
+/**
+ * Inbox row kinds. `user_message` payload is a UIMessage; `system_notice`
+ * payload is a small structured note rendered as text. Add new kinds
+ * here; the renderer in agent-core branches on this enum.
+ */
+export const INBOX_KINDS = ["user_message", "system_notice"];
+export const INBOX_SOURCES = ["user", "system"];
+//# sourceMappingURL=ports.js.map

package/dist/ports.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ports.js","sourceRoot":"","sources":["../src/ports.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAU,CAAC;AAmC3D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,eAAe;IACf,gBAAgB;IAChB,eAAe;IACf,eAAe;IACf,cAAc;IACd,kBAAkB;IAClB,oBAAoB;IACpB,WAAW;CACH,CAAC;AAGX;;;;GAIG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,cAAc,EAAE,eAAe,CAAU,CAAC;AAGtE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAU,CAAC"}

package/dist/prompt-render.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Markdown rendering for tasks — the "Tasks" and "Recent activity"
+ * blocks in the agent's system prompt, plus event-payload summaries.
+ *
+ * Pure functions: take task data + lookups, return strings. No I/O.
+ * TaskStore wraps these as methods for callers; tests can call them
+ * directly.
+ */
+import type { Comment } from "./ports.js";
+import type { Task } from "./types.js";
+export interface PromptRenderDeps {
+    list: () => Task[];
+    commentCounts: (taskIds: string[]) => Map<string, number>;
+    latestNonSystemComment: (taskId: string) => Comment | null;
+}
+export declare function renderForPrompt(deps: PromptRenderDeps, agentId: string, currentSessionId: string, sessionExistsFn: (sid: string) => boolean, now?: Date): string;
+export declare function renderRecentActivity(events: import("./ports.js").TaskEvent[], titlesById: Map<string, string>, now?: Date): string;
+export declare function summarizeEventPayload(e: import("./ports.js").TaskEvent): string;
+//# sourceMappingURL=prompt-render.d.ts.map

package/dist/prompt-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-render.d.ts","sourceRoot":"","sources":["../src/prompt-render.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,OAAO,KAAK,EAAE,IAAI,EAAmB,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,IAAI,EAAE,CAAC;IACnB,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC1D,sBAAsB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;CAC5D;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,gBAAgB,EACtB,OAAO,EAAE,MAAM,EACf,gBAAgB,EAAE,MAAM,EACxB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,EACzC,GAAG,GAAE,IAAiB,GACrB,MAAM,CAyHR;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,OAAO,YAAY,EAAE,SAAS,EAAE,EACxC,UAAU,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,GAAG,GAAE,IAAiB,GACrB,MAAM,CAgBR;AAED,wBAAgB,qBAAqB,CACnC,CAAC,EAAE,OAAO,YAAY,EAAE,SAAS,GAChC,MAAM,CAiDR"}

package/dist/prompt-render.js

@@ -0,0 +1,204 @@
+/**
+ * Markdown rendering for tasks — the "Tasks" and "Recent activity"
+ * blocks in the agent's system prompt, plus event-payload summaries.
+ *
+ * Pure functions: take task data + lookups, return strings. No I/O.
+ * TaskStore wraps these as methods for callers; tests can call them
+ * directly.
+ */
+import { describeRecurrence } from "./recurrence.js";
+export function renderForPrompt(deps, agentId, currentSessionId, sessionExistsFn, now = new Date()) {
+    const all = deps.list();
+    const byId = new Map(all.map((t) => [t.id, t]));
+    const mine = all.filter((t) => t.assignee === agentId);
+    const createdByMe = all.filter((t) => t.created_by === agentId &&
+        t.assignee !== agentId &&
+        t.status !== "done" &&
+        t.status !== "canceled");
+    const inThisSession = mine.filter((t) => t.session_id === currentSessionId);
+    const active = inThisSession.filter((t) => t.status === "in_progress");
+    const queuedHere = inThisSession
+        .filter((t) => t.status === "open" &&
+        depsSatisfied(t.depends_on, byId) &&
+        !isFutureStart(t.start_at, now))
+        .sort((a, b) => a.created_at.localeCompare(b.created_at));
+    const scheduledLater = inThisSession
+        .filter((t) => t.status === "open" && isFutureStart(t.start_at, now))
+        .sort((a, b) => (a.start_at ?? "").localeCompare(b.start_at ?? ""));
+    const blocked = inThisSession.filter((t) => t.status === "blocked");
+    const otherSessions = mine.filter((t) => {
+        if (t.session_id === currentSessionId)
+            return false;
+        if (t.status === "done" || t.status === "canceled")
+            return false;
+        if (!t.session_id)
+            return false;
+        return sessionExistsFn(t.session_id);
+    });
+    // Bulk-lookup comment counts so a queue of hundreds doesn't fan out.
+    const visibleIds = new Set();
+    for (const t of [
+        ...active,
+        ...queuedHere,
+        ...scheduledLater,
+        ...blocked,
+        ...otherSessions,
+        ...createdByMe,
+    ]) {
+        visibleIds.add(t.id);
+    }
+    const counts = deps.commentCounts(Array.from(visibleIds));
+    const tag = (t) => {
+        const n = counts.get(t.id) ?? 0;
+        return n > 0 ? ` (${n} comment${n === 1 ? "" : "s"})` : "";
+    };
+    const sections = [];
+    if (active.length > 0) {
+        sections.push(renderSection("Active in this session (currently working)", active, (t) => {
+            const due = t.due_at ? ` (due ${t.due_at})` : "";
+            return `- [${t.id}]${due} ${t.title}${recurrenceTag(t)}${tag(t)}`;
+        }));
+    }
+    if (queuedHere.length > 0) {
+        sections.push(renderSection("Queued in this session (next up, in order)", queuedHere, (t) => `- [${t.id}] ${t.title}${recurrenceTag(t)}${tag(t)}`));
+    }
+    if (scheduledLater.length > 0) {
+        sections.push(renderSection("Scheduled later (in this session, starts at T)", scheduledLater, (t) => `- [${t.id}] starts ${t.start_at} — ${t.title}${recurrenceTag(t)}${tag(t)}`));
+    }
+    if (blocked.length > 0) {
+        sections.push(renderSection("Blocked on dependencies", blocked, (t) => {
+            const unmet = t.depends_on.filter((d) => {
+                const dep = byId.get(d);
+                return !dep || dep.status !== "done";
+            });
+            return `- [${t.id}] ${t.title}${recurrenceTag(t)}${tag(t)} — waiting on [${unmet.join(", ")}]`;
+        }));
+    }
+    if (otherSessions.length > 0) {
+        sections.push(renderSection("In another session (read-only awareness — don't re-handle)", otherSessions, (t) => `- [${t.id}] ${t.title}${recurrenceTag(t)}${tag(t)} — bound to session ${t.session_id}`));
+    }
+    if (createdByMe.length > 0) {
+        // Recent-activity hint for delegated tasks — the only signal that
+        // pulls assigners back when an assignee touches their work.
+        sections.push(renderSection("Created by me, assigned to others", createdByMe, (t) => {
+            const recent = deps.latestNonSystemComment(t.id);
+            const hint = recent
+                ? ` — last comment by ${recent.author} ${formatRelativeFrom(recent.createdAt, now)}${recent.kind ? ` (${recent.kind})` : ""}`
+                : "";
+            return `- [${t.id}] ${t.title}${recurrenceTag(t)}${tag(t)} — assignee ${t.assignee}, status ${t.status}${hint}`;
+        }));
+    }
+    if (sections.length === 0)
+        return "";
+    return `${sections.join("\n\n")}\n\nNOTE: snapshot from session start. Call task_list for fresh state.`;
+}
+export function renderRecentActivity(events, titlesById, now = new Date()) {
+    if (events.length === 0)
+        return "";
+    const lines = events.map((e) => {
+        const when = formatRelativeFrom(e.createdAt, now);
+        const summary = summarizeEventPayload(e);
+        const tail = summary ? ` — ${summary}` : "";
+        if (!e.taskId) {
+            // Session-level event with no task anchor. Format without the
+            // bracketed task id; the kind + payload summary already carries
+            // the context the agent needs.
+            return `- ${when} · ${e.kind}${tail}`;
+        }
+        const title = titlesById.get(e.taskId) ?? "(unknown task)";
+        return `- ${when} · ${e.kind} on [${e.taskId}] ${title}${tail}`;
+    });
+    return lines.join("\n");
+}
+export function summarizeEventPayload(e) {
+    if (!e.payload)
+        return `actor ${e.agentId}`;
+    let p = {};
+    try {
+        p = JSON.parse(e.payload);
+    }
+    catch {
+        return `actor ${e.agentId}`;
+    }
+    switch (e.kind) {
+        case "comment_added": {
+            // `e.agentId` is the recipient (task assignee). The author is in
+            // `payload.author` (or `e.actor` for non-system authors). Fall
+            // back to `e.actor` for older events that pre-date the payload
+            // change; treat null actor as "system".
+            const author = (p.author && String(p.author)) || e.actor || "system";
+            const lead = p.kind
+                ? `${String(p.kind)} comment by ${author}`
+                : `comment by ${author}`;
+            const excerpt = p.excerpt ? String(p.excerpt) : "";
+            return excerpt ? `${lead}: "${excerpt}"` : lead;
+        }
+        case "status_changed":
+            return `${String(p.from ?? "?")} → ${String(p.to ?? "?")}`;
+        case "dep_unblocked":
+            return `dep ${String(p.blocked_by_task_id ?? "?")} done — now runnable`;
+        case "task_assigned":
+            return `assigned to ${String(p.assignee ?? "?")} by ${String(p.created_by ?? "?")}`;
+        case "task_deleted":
+            return p.forced ? `deleted (cascaded)` : `deleted`;
+        case "scheduler_action": {
+            const action = String(p.action ?? "?");
+            const message = String(p.message ?? "");
+            return message ? `[${action}] ${message}` : `[${action}]`;
+        }
+        case "task_completed_run": {
+            const runs = p.runs != null ? String(p.runs) : "?";
+            const next = p.next_fire ? ` — next fire ${String(p.next_fire)}` : "";
+            return `run ${runs} done${next}`;
+        }
+        case "ping_user": {
+            const excerpt = p.message ? String(p.message).slice(0, 80) : "";
+            return excerpt
+                ? `${e.agentId} pinged user: "${excerpt}"`
+                : `${e.agentId} pinged user`;
+        }
+        default:
+            return `actor ${e.agentId}`;
+    }
+}
+// ── Internals ───────────────────────────────────────────────────────
+function renderSection(title, items, fmt) {
+    return `${title}:\n${items.map(fmt).join("\n")}`;
+}
+function recurrenceTag(t) {
+    if (!t.recurrence)
+        return "";
+    return ` (${describeRecurrence(t.recurrence)}, ran ${t.runs}×)`;
+}
+function formatRelativeFrom(unixSeconds, now) {
+    const diffSec = Math.max(0, Math.floor(now.getTime() / 1000 - unixSeconds));
+    if (diffSec < 60)
+        return `${diffSec}s ago`;
+    const m = Math.floor(diffSec / 60);
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ago`;
+}
+function isFutureStart(startAt, now) {
+    if (!startAt)
+        return false;
+    const t = Date.parse(startAt);
+    if (!Number.isFinite(t))
+        return false;
+    return t > now.getTime();
+}
+function depsSatisfied(deps, byId) {
+    for (const d of deps) {
+        const dep = byId.get(d);
+        if (!dep)
+            return false;
+        if (dep.status !== "done")
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=prompt-render.js.map

package/dist/prompt-render.js.map

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

package/dist/recurrence.d.ts

@@ -0,0 +1,21 @@
+import { type Recurrence } from "./types.js";
+export type ValidateResult = {
+    ok: true;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * Compute the next fire time for a recurrence, or null if the schedule
+ * is exhausted (count cap, until cap, or cron expression that yields no
+ * future runs). Pure — does not start a Croner timer.
+ */
+export declare function computeNextFire(rec: Recurrence, from: Date, runs: number): Date | null;
+/**
+ * Validate a recurrence at the write boundary. Cheaper than waiting for
+ * Croner to throw when the daemon eventually arms a malformed expr.
+ */
+export declare function validateRecurrence(rec: Recurrence, now: Date): ValidateResult;
+/** One-line cadence label for prompt rendering. */
+export declare function describeRecurrence(rec: Recurrence): string;
+//# sourceMappingURL=recurrence.d.ts.map

package/dist/recurrence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recurrence.d.ts","sourceRoot":"","sources":["../src/recurrence.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,UAAU,EAChB,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,cAAc,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3E;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,GACX,IAAI,GAAG,IAAI,CA4Bb;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,UAAU,EACf,GAAG,EAAE,IAAI,GACR,cAAc,CAoDhB;AAED,mDAAmD;AACnD,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,UAAU,GAAG,MAAM,CAK1D"}

package/dist/recurrence.js

@@ -0,0 +1,117 @@
+import { Cron } from "croner";
+import { MIN_INTERVAL_MS, MAX_RECURRENCE_COUNT, } from "./types.js";
+/**
+ * Compute the next fire time for a recurrence, or null if the schedule
+ * is exhausted (count cap, until cap, or cron expression that yields no
+ * future runs). Pure — does not start a Croner timer.
+ */
+export function computeNextFire(rec, from, runs) {
+    if (rec.until) {
+        const u = Date.parse(rec.until);
+        if (Number.isFinite(u) && u <= from.getTime())
+            return null;
+    }
+    if (rec.count != null && runs >= rec.count)
+        return null;
+    let candidate;
+    if (rec.kind === "cron") {
+        try {
+            const cron = new Cron(rec.expr, {
+                timezone: rec.tz ?? undefined,
+                paused: true,
+            });
+            candidate = cron.nextRun(from);
+        }
+        catch {
+            return null;
+        }
+    }
+    else {
+        candidate = new Date(from.getTime() + rec.every_ms);
+    }
+    if (!candidate)
+        return null;
+    if (rec.until) {
+        const u = Date.parse(rec.until);
+        if (Number.isFinite(u) && candidate.getTime() > u)
+            return null;
+    }
+    return candidate;
+}
+/**
+ * Validate a recurrence at the write boundary. Cheaper than waiting for
+ * Croner to throw when the daemon eventually arms a malformed expr.
+ */
+export function validateRecurrence(rec, now) {
+    if (rec.until) {
+        const u = Date.parse(rec.until);
+        if (!Number.isFinite(u)) {
+            return { ok: false, message: `recurrence.until is not a valid ISO date` };
+        }
+        if (u <= now.getTime()) {
+            return { ok: false, message: `recurrence.until is in the past` };
+        }
+    }
+    if (rec.count != null) {
+        if (!Number.isInteger(rec.count) || rec.count <= 0) {
+            return { ok: false, message: `recurrence.count must be a positive integer` };
+        }
+        if (rec.count > MAX_RECURRENCE_COUNT) {
+            return {
+                ok: false,
+                message: `recurrence.count exceeds max (${MAX_RECURRENCE_COUNT})`,
+            };
+        }
+    }
+    if (rec.kind === "cron") {
+        try {
+            const cron = new Cron(rec.expr, {
+                timezone: rec.tz ?? undefined,
+                paused: true,
+            });
+            const next = cron.nextRun(now);
+            if (!next) {
+                return {
+                    ok: false,
+                    message: `recurrence.expr ${JSON.stringify(rec.expr)} has no future runs`,
+                };
+            }
+        }
+        catch (e) {
+            return {
+                ok: false,
+                message: `recurrence.expr invalid: ${e instanceof Error ? e.message : String(e)}`,
+            };
+        }
+        return { ok: true };
+    }
+    // interval
+    if (!Number.isInteger(rec.every_ms) || rec.every_ms < MIN_INTERVAL_MS) {
+        return {
+            ok: false,
+            message: `recurrence.every_ms must be an integer >= ${MIN_INTERVAL_MS}`,
+        };
+    }
+    return { ok: true };
+}
+/** One-line cadence label for prompt rendering. */
+export function describeRecurrence(rec) {
+    if (rec.kind === "cron") {
+        return rec.tz ? `cron ${rec.expr} (${rec.tz})` : `cron ${rec.expr}`;
+    }
+    return `every ${formatMs(rec.every_ms)}`;
+}
+function formatMs(ms) {
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    const h = Math.round(m / 60);
+    if (h < 24)
+        return `${h}h`;
+    const d = Math.round(h / 24);
+    return `${d}d`;
+}
+//# sourceMappingURL=recurrence.js.map

package/dist/recurrence.js.map

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