@openacme/tasks 0.4.0

package/dist/store.d.ts

@@ -0,0 +1,156 @@
+/**
+ * File-backed task store. One markdown file per task at
+ * `<tasksDir>/<id>.md` — YAML frontmatter for structured fields, body
+ * for the agent-readable description and accumulated notes.
+ *
+ * Concurrency: per-task in-process async mutex serializes
+ * read-modify-write of a single id. Each operation only acquires one
+ * mutex at a time — fan-out paths (`unblockDependents`, `delete --force`)
+ * iterate sequentially without holding multiple locks, so there's no
+ * deadlock surface.
+ *
+ * The store enforces:
+ *   - cycle-free `depends_on` graph (DFS on write).
+ *   - status auto-transition between `open` and `blocked` based on deps.
+ *   - at most one `in_progress` per `session_id`.
+ *   - inputs validated against the frontmatter schema at the write
+ *     boundary so a bad input can't land malformed YAML on disk.
+ *
+ * Status state machine (legal transitions only — anything else is a bug):
+ *
+ *   open ─────► in_progress    (assignee claims via update; requires deps satisfied)
+ *   open ─────► blocked        (auto, when deps regress)
+ *   open ─────► done/canceled  (terminal)
+ *
+ *   in_progress ──► blocked      (via TaskStore.park, by scheduler on
+ *                                 timeout/error or watchdog)
+ *   in_progress ──► done/canceled (terminal; assignee or human)
+ *
+ *   blocked ──► open             (auto, when deps satisfy via unblockDependents)
+ *   blocked ──► done/canceled    (terminal; bypasses in_progress)
+ *
+ *   done ────► open              (ONLY for recurring tasks — self-reset
+ *                                 to next fire. Non-recurring done is
+ *                                 terminal.)
+ *   canceled ──► (nothing)       (kill switch; never resets, even for recurring)
+ *
+ * Adding a new status: extend `TASK_STATUSES`, then audit `computeAutoStatus`,
+ * the closing branches in `update()`, the recurring self-reset, scheduler's
+ * `park` / `watchdogPark`, `hasAnyActive`, and prompt rendering.
+ */
+import { type Task, type TaskCreate, type TaskListFilter, type TaskUpdate } from "./types.js";
+import type { Comment, CommentInput, CommentListOptions, CommentStorePort, EventStorePort, TaskEvent } from "./ports.js";
+export declare class TaskStoreError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type OnChangeFn = () => void;
+export interface TaskStoreOptions {
+    /** Optional: discussion thread store. If absent, comment methods no-op. */
+    commentStore?: CommentStorePort;
+    /** Optional: event log store. If absent, no events emitted. */
+    eventStore?: EventStorePort;
+    /** Optional: session existence check. When provided, create/update
+     *  reject task bindings to a session id the check returns false for —
+     *  prevents agents from hallucinating session uuids that would become
+     *  scheduler zombies. */
+    validateSession?: (id: string) => boolean;
+}
+export declare class TaskStore {
+    readonly tasksDir: string;
+    private readonly inFlight;
+    private onChange;
+    private readonly commentStore;
+    private readonly eventStore;
+    private readonly validateSession;
+    constructor(tasksDir: string, options?: TaskStoreOptions);
+    setOnChange(fn: OnChangeFn | null): void;
+    filePath(id: string): string;
+    get(id: string): Task | null;
+    list(filter?: TaskListFilter): Task[];
+    byAssignee(agentId: string): Task[];
+    byCreator(agentId: string): Task[];
+    byParent(parentId: string): Task[];
+    dependentsOf(id: string): Task[];
+    /** Tasks bound to `sessionId` in queue order (deps + start_at + created_at). */
+    queueFor(sessionId: string, now?: Date): Task[];
+    /** Top of `queueFor` excluding already in_progress / done / canceled. */
+    nextEligibleFor(sessionId: string, now?: Date): Task | null;
+    create(input: TaskCreate): Promise<Task>;
+    update(id: string, patch: TaskUpdate, opts?: {
+        actor?: string | null;
+    }): Promise<Task>;
+    delete(id: string, opts?: {
+        force?: boolean;
+        actor?: string | null;
+    }): Promise<void>;
+    /**
+     * Restart sweep: any task `in_progress` whose `updated_at` is older
+     * than the staleness threshold is reset to `open`. Returns the ids
+     * that were reset.
+     */
+    /**
+     * Park a task: flip to `blocked` with a future `start_at` and append
+     * a `system:scheduler` comment explaining why. The scheduler uses this
+     * for both failure attribution (`parkInProgress`) and watchdog stalls
+     * (`watchdogPark`). Single helper means the "blocked + back-off +
+     * system note" pattern lives in one place.
+     */
+    park(input: {
+        id: string;
+        retryAt: Date;
+        reason: string;
+    }): Promise<void>;
+    sweepStale(now?: Date): Promise<string[]>;
+    /**
+     * System-prompt block for an agent. `sessionExistsFn` lets the caller
+     * treat tasks bound to a deleted session as if they were unbound.
+     */
+    renderForPrompt(agentId: string, currentSessionId: string, sessionExistsFn: (sid: string) => boolean, now?: Date): string;
+    private latestNonSystemComment;
+    private assertDepsExist;
+    private assertNoCycle;
+    private writeFile;
+    private withMutex;
+    private fireOnChange;
+    private emitEvent;
+    /**
+     * Append a comment to the task's discussion thread. Authorship gates
+     * (assignee-only for `kind: "result"`, system-only for `kind: "system"`)
+     * live in the tool layer; the store accepts whatever it's given so
+     * automation paths can write system entries directly.
+     */
+    addComment(input: CommentInput): Promise<Comment | null>;
+    listComments(taskId: string, opts?: CommentListOptions): Comment[];
+    latestResult(taskId: string): Comment | null;
+    commentCounts(taskIds: string[]): Map<string, number>;
+    /**
+     * Tasks this session is "involved with" — bound to the session, plus
+     * the agent's assigned/created tasks that have no session yet (those
+     * land here when they get a fresh session). Plus tasks the agent
+     * created and assigned to OTHERS — without this, the agent loses
+     * the event feed for delegated work the moment its assignee picks
+     * it up and the task gets bound to a different session.
+     */
+    involvedTaskIds(sessionId: string, agentId: string): string[];
+    /**
+     * Fetch recent events for the given session's involvement set, since
+     * `sinceTs` (unix seconds). Empty array if no event store wired.
+     * `excludeActor` filters out events caused by that actor — used by
+     * the mid-turn injection path so the cursor and the rendered set
+     * always match (otherwise self-events get re-shown on every step).
+     */
+    recentEventsForSession(sessionId: string, agentId: string, sinceTs: number, opts?: {
+        limit?: number;
+        excludeActor?: string;
+    }): TaskEvent[];
+    /**
+     * Format the events feed as a markdown section for the system prompt.
+     * Returns "" when there are no events to render.
+     */
+    renderRecentActivity(sessionId: string, agentId: string, sinceTs: number, now?: Date, opts?: {
+        limit?: number;
+        excludeActor?: string;
+    }): string;
+}
+//# sourceMappingURL=store.d.ts.map

package/dist/store.d.ts.map

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