@ours.network/fleet 2.3.2 → 2.3.3

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
-  "version": "2.3.2",
-  "buildId": "597fdbc5f69f",
-  "commit": "31b6aae8610ef1e4d74212cb06d9b03379a8eb40",
+  "version": "2.3.3",
+  "buildId": "f813635f30d3",
+  "commit": "b0dbf450ed45e131fb34f64d71a16e8eb960b77f",
   "dirty": false,
-  "builtAt": "2026-10-31T06:49:15.117Z",
+  "builtAt": "2026-11-03T12:22:11.870Z",
   "capabilities": [
     "service.refresh-v1",
     "managed-cli.codex-reasoning-effort-v1",

package/dist/rooms-tasks/task-contributions.d.ts

@@ -0,0 +1,50 @@
+import type { TaskRecord } from './types.js';
+export declare const CONTRIBUTION_PAGE_MAX = 100;
+export declare const CONTRIBUTION_CUTOFF_MAX = 200;
+export interface ContributionItem {
+    /** `p:<task>:<entry>` or `r:<task>:<revision>`: a new review revision is a new item. */
+    id: string;
+    kind: 'progress' | 'review';
+    task_id: string;
+    mission_key?: string;
+    task_title: string;
+    task_state: TaskRecord['state'];
+    at: string;
+    excerpt: string;
+    unread: boolean;
+    entry_id?: string;
+    revision?: number;
+}
+/** What one task had when it was listed; the bulk read acknowledges nothing beyond it. */
+export interface ContributionCutoff {
+    task_id: string;
+    progress: number;
+    progress_last: string | null;
+    review: number;
+}
+/**
+ * One page, newest first. The cursor is a position, not an item: it stays valid when the item it
+ * names is read, filtered out or deleted. `cutoff` lists every task with unread items as listed;
+ * `unavailable` counts task records that could not be read.
+ */
+export declare function listTaskContributions(options?: {
+    before?: string;
+    limit?: number;
+    unread?: boolean;
+}): {
+    items: ContributionItem[];
+    next_cursor: string | null;
+    unread_total: number;
+    cutoff: ContributionCutoff[];
+    unavailable: number;
+};
+export type ContributionReadResult = {
+    task_id: string;
+} & ({
+    status: 'read';
+    read: number;
+} | {
+    status: 'changed' | 'gone' | 'deleting' | 'failed';
+});
+/** Read every task of a captured cutoff up to that cutoff, each under its own lock; one task's outcome never blocks another. */
+export declare function readTaskContributions(cutoff: ContributionCutoff[]): ContributionReadResult[];

package/dist/rooms-tasks/task-contributions.js

@@ -0,0 +1,169 @@
+/**
+ * Progress entries and To review revisions of every task as one newest-first notification list,
+ * with the canonical read state of each task record. Nothing is copied: the task records stay the
+ * only read truth, and the per-task routes and the bulk read below change the same markers.
+ *
+ * The projection is retained in this process. Each request lists the task directory and stats each
+ * record; only a record whose inode, size or time changed is read again (every write replaces the
+ * file atomically). Room history and other services are never consulted.
+ */
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { acknowledgeTaskContributionsThrough, contributionUnread, getTask, reviewRevision, tasksDir, TaskStateError } from './task-state.js';
+import { TaskReviewError } from './task-review.js';
+const TASK_FILE = /^([0-9a-z]{9}[0-9a-f]{8})\.json$/;
+const EXCERPT_MAX = 200;
+export const CONTRIBUTION_PAGE_MAX = 100;
+export const CONTRIBUTION_CUTOFF_MAX = 200;
+let cache;
+function excerpt(text) {
+    const points = [...text.replace(/\s+/g, ' ').trim()];
+    return points.length > EXCERPT_MAX ? points.slice(0, EXCERPT_MAX - 1).join('') + '…' : points.join('');
+}
+function reviewExcerpt(task) {
+    const line = task.review?.markdown.split('\n').map(text => text.replace(/^\s*(?:#{1,6}\s|>\s?|[-*+]\s|\d+\.\s)*/, '').trim()).find(Boolean);
+    if (line)
+        return excerpt(line);
+    const files = task.review?.artifacts.length ?? 0;
+    return files ? `${files} attached ${files === 1 ? 'file' : 'files'}` : 'The review request was cleared.';
+}
+const time = (at) => { const value = Date.parse(at); return Number.isFinite(value) ? value : 0; };
+function project(task, stamp) {
+    const base = {
+        task_id: task.task_id, ...(task.key ? { mission_key: task.key } : {}), task_title: task.title, task_state: task.state,
+    };
+    const reads = task.contribution_reads, seen = new Set(reads?.progress_read);
+    const items = (task.progress ?? []).map(entry => ({
+        ...base, id: `p:${task.task_id}:${entry.id}`, kind: 'progress', at: entry.at, order: time(entry.at),
+        excerpt: excerpt(entry.text), unread: !!reads && !seen.has(entry.id), entry_id: entry.id,
+    }));
+    const unread = contributionUnread(task);
+    if (task.review) {
+        const revision = reviewRevision(task.review);
+        items.push({ ...base, id: `r:${task.task_id}:${revision}`, kind: 'review', at: task.review.updated_at,
+            order: time(task.review.updated_at), excerpt: reviewExcerpt(task), unread: unread.review, revision });
+    }
+    const progress = task.progress ?? [];
+    return { stamp, items, unread: unread.progress + (unread.review ? 1 : 0),
+        ...(unread.progress || unread.review ? { cutoff: { task_id: task.task_id, progress: progress.length,
+                progress_last: progress.at(-1)?.id ?? null, review: reviewRevision(task.review) } } : {}) };
+}
+/** Bring the retained projection up to date with the task directory; returns the tasks not readable now. */
+function refresh() {
+    const dir = tasksDir();
+    if (cache?.dir !== dir)
+        cache = { dir, tasks: new Map() };
+    const current = cache;
+    let names;
+    // No task directory yet means no tasks; any other failure is an error, never an empty list.
+    try {
+        names = readdirSync(dir);
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        names = [];
+    }
+    const present = new Set();
+    let unavailable = 0;
+    for (const name of names) {
+        const id = TASK_FILE.exec(name)?.[1];
+        if (!id)
+            continue;
+        try {
+            // Writes replace the record by rename: a new inode, and a change time in nanoseconds.
+            const stat = statSync(join(dir, name), { bigint: true });
+            const stamp = `${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`;
+            present.add(id);
+            if (current.tasks.get(id)?.stamp === stamp)
+                continue;
+            const task = getTask(id);
+            current.index = undefined;
+            // A task pending deletion lists nothing and counts nothing.
+            if (task.deletion?.status === 'pending')
+                current.tasks.set(id, { stamp, items: [], unread: 0 });
+            else
+                current.tasks.set(id, project(task, stamp));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' || (error instanceof TaskStateError && /not found/.test(error.message)))
+                continue;
+            present.add(id);
+            unavailable++;
+            if (current.tasks.delete(id))
+                current.index = undefined;
+        }
+    }
+    for (const id of current.tasks.keys())
+        if (!present.has(id)) {
+            current.tasks.delete(id);
+            current.index = undefined;
+        }
+    return unavailable;
+}
+function index() {
+    return cache.index ??= [...cache.tasks.values()].flatMap(task => task.items)
+        .sort((a, b) => b.order - a.order || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
+}
+function encodeCursor(item) {
+    return Buffer.from(JSON.stringify([item.order, item.id])).toString('base64url');
+}
+function decodeCursor(cursor) {
+    try {
+        const [order, id] = JSON.parse(Buffer.from(cursor, 'base64url').toString('utf8'));
+        if (typeof order === 'number' && Number.isFinite(order) && typeof id === 'string' && id.length <= 200)
+            return { order, id };
+    }
+    catch { /* invalid below */ }
+    throw new TaskReviewError('invalid_request', 'invalid cursor');
+}
+/**
+ * One page, newest first. The cursor is a position, not an item: it stays valid when the item it
+ * names is read, filtered out or deleted. `cutoff` lists every task with unread items as listed;
+ * `unavailable` counts task records that could not be read.
+ */
+export function listTaskContributions(options = {}) {
+    const limit = options.limit ?? 50;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > CONTRIBUTION_PAGE_MAX)
+        throw new TaskReviewError('invalid_request', `limit must be 1-${CONTRIBUTION_PAGE_MAX}`);
+    const after = options.before === undefined ? undefined : decodeCursor(options.before);
+    const unavailable = refresh();
+    const page = [];
+    let more = false;
+    for (const item of index()) {
+        if (after && (item.order > after.order || (item.order === after.order && item.id >= after.id)))
+            continue;
+        if (options.unread && !item.unread)
+            continue;
+        if (page.length === limit) {
+            more = true;
+            break;
+        }
+        page.push(item);
+    }
+    const tasks = [...cache.tasks.values()];
+    return {
+        items: page.map(({ order: _order, ...item }) => item),
+        next_cursor: more ? encodeCursor(page.at(-1)) : null,
+        unread_total: tasks.reduce((sum, task) => sum + task.unread, 0),
+        cutoff: tasks.flatMap(task => task.cutoff ? [task.cutoff] : []),
+        unavailable,
+    };
+}
+/** Read every task of a captured cutoff up to that cutoff, each under its own lock; one task's outcome never blocks another. */
+export function readTaskContributions(cutoff) {
+    return cutoff.map(({ task_id, progress, progress_last, review }) => {
+        try {
+            const read = acknowledgeTaskContributionsThrough(task_id, { progress, progressLast: progress_last, review });
+            return read === 'changed' ? { task_id, status: 'changed' } : { task_id, status: 'read', read };
+        }
+        catch (error) {
+            if (error instanceof TaskStateError && /pending deletion/.test(error.message))
+                return { task_id, status: 'deleting' };
+            if (error instanceof TaskStateError && /not found/.test(error.message))
+                return { task_id, status: 'gone' };
+            // An unreadable or unwritable record fails alone; tasks already read stay read and are reported.
+            return { task_id, status: 'failed' };
+        }
+    });
+}

package/dist/rooms-tasks/task-state.d.ts

@@ -24,6 +24,18 @@ export declare function acknowledgeTaskReview(id: string, revision: number): {
     progress: number;
     review: boolean;
 };
+/**
+ * Bulk read up to a captured cutoff: the first `progress` entries (Progress is append-only, so an
+ * entry appended after the capture has a higher index) and To review up to exactly `review`, never
+ * a newer revision. Both are written in one task change. Returns how many items that were unread
+ * are read now, or `changed` (nothing written) when the task no longer matches the cutoff, including a
+ * review revision the task never had; refuses a task pending deletion.
+ */
+export declare function acknowledgeTaskContributionsThrough(id: string, cutoff: {
+    progress: number;
+    progressLast: string | null;
+    review: number;
+}): number | 'changed';
 /** Atomic snapshots contain the events, including intermediate states between polls. */
 /** `upgraded`: IDs of events queued by an earlier release without a delivery policy. They are sent push-only under the
  * same event ID (state transitions never count as unread); the queued record itself is not rewritten. A service that

package/dist/rooms-tasks/task-state.js

@@ -266,6 +266,42 @@ export function acknowledgeTaskReview(id, revision) {
         return contributionUnread(task);
     });
 }
+/**
+ * Bulk read up to a captured cutoff: the first `progress` entries (Progress is append-only, so an
+ * entry appended after the capture has a higher index) and To review up to exactly `review`, never
+ * a newer revision. Both are written in one task change. Returns how many items that were unread
+ * are read now, or `changed` (nothing written) when the task no longer matches the cutoff, including a
+ * review revision the task never had; refuses a task pending deletion.
+ */
+export function acknowledgeTaskContributionsThrough(id, cutoff) {
+    assertCanonicalTaskId(id);
+    return withTaskLock(id, () => {
+        const task = readTask(id);
+        assertNoPendingDeletion(task);
+        const { progress, progressLast, review } = cutoff;
+        // The cutoff names its last entry: a different entry at that position reads nothing.
+        const entries = task.progress ?? [];
+        if (!Number.isSafeInteger(progress) || progress < 0 || progress > entries.length
+            || (progress > 0 ? entries[progress - 1].id : null) !== progressLast
+            || !Number.isSafeInteger(review) || review < 0 || review > reviewRevision(task.review))
+            return 'changed';
+        const reads = task.contribution_reads;
+        if (!reads)
+            return 0;
+        const seen = new Set(reads.progress_read);
+        const added = entries.slice(0, progress).map(entry => entry.id).filter(entryId => !seen.has(entryId));
+        const reviewRead = review > reads.review_revision;
+        if (!added.length && !reviewRead)
+            return 0;
+        task.contribution_reads = {
+            progress_read: [...reads.progress_read, ...added],
+            review_revision: reviewRead ? review : reads.review_revision,
+        };
+        writeTask(task);
+        // An older revision moves the marker but leaves the current package unread: it is not counted.
+        return added.length + (reviewRead && review === reviewRevision(task.review) ? 1 : 0);
+    });
+}
 const retiredNotificationsDir = () => join(tasksDir(), '.notification-retired');
 function typedTaskNotification(value, id) {
     if (!value || typeof value !== 'object' || Object.keys(value).some(key => !['eventId', 'title', 'body', 'target', 'taskId', 'delivery'].includes(key)))

package/dist/web/server.js

@@ -25,6 +25,7 @@ import { FleetEventBus } from './events.js';
 import { ROLE_NAME_RE } from '../config.js';
 import { TaskListError } from '../rooms-tasks/task-lists.js';
 import { acknowledgeTaskProgress, acknowledgeTaskReview, contributionUnread, resolveTaskRef, TaskStateError } from '../rooms-tasks/task-state.js';
+import { CONTRIBUTION_CUTOFF_MAX, CONTRIBUTION_PAGE_MAX, listTaskContributions, readTaskContributions } from '../rooms-tasks/task-contributions.js';
 import { MissionKeyError } from '../rooms-tasks/mission-keys.js';
 import { appendTaskProgress, getTaskReview, taskProgressSnapshot, publicProgressEntry, publicReview, readTaskReviewArtifact, setTaskReviewMarkdown, taskContributionSummary, TaskReviewError, } from '../rooms-tasks/task-review.js';
 import { isProvider } from '../subscriptions/store.js';
@@ -686,6 +687,39 @@ export async function buildWebServer(services, boundary, options = {}) {
             reply.code(201);
         return { entry: publicProgressEntry(result.entry), replayed: result.replayed };
     });
+    /**
+     * Progress and To review of every task, newest first, for the notification list. The first page
+     * (no `before`) also carries the cutoff a bulk read may acknowledge up to: each task with unread
+     * items as it was read, one task at a time (per task, not one atomic instant across tasks).
+     */
+    app.get('/api/v1/contributions', async (request) => {
+        auth.authenticate(request);
+        const query = request.query;
+        if (query.unread !== undefined && !['true', 'false'].includes(query.unread))
+            throw new FleetError('invalid_request', 'unread must be true or false');
+        if (query.limit !== undefined && !/^\d{1,3}$/.test(query.limit))
+            throw new FleetError('invalid_request', `limit must be 1-${CONTRIBUTION_PAGE_MAX}`);
+        const page = await reviewApi(() => listTaskContributions({
+            ...(query.before !== undefined ? { before: query.before } : {}),
+            ...(query.limit !== undefined ? { limit: Number(query.limit) } : {}),
+            unread: query.unread === 'true',
+        }));
+        const { cutoff, ...rest } = page;
+        return query.before === undefined ? page : rest;
+    });
+    /** Bulk read up to a captured cutoff, at most `CONTRIBUTION_CUTOFF_MAX` tasks per request, with a result per task. */
+    app.post('/api/v1/contributions/read', async (request) => {
+        auth.authenticate(request, true);
+        const cutoff = request.body?.cutoff;
+        const valid = (item) => !!item && typeof item === 'object' && Object.keys(item).length === 4
+            && typeof item.task_id === 'string' && /^[0-9a-z]{9}[0-9a-f]{8}$/.test(item.task_id) && Number.isSafeInteger(item.progress) && item.progress >= 0
+            && (item.progress_last === null || (typeof item.progress_last === 'string' && item.progress_last.length <= 64))
+            && Number.isSafeInteger(item.review) && item.review >= 0;
+        if (!Array.isArray(cutoff) || cutoff.length > CONTRIBUTION_CUTOFF_MAX || !cutoff.every(valid)
+            || new Set(cutoff.map(item => item.task_id)).size !== cutoff.length)
+            throw new FleetError('invalid_request', `cutoff must list at most ${CONTRIBUTION_CUTOFF_MAX} distinct tasks as captured`);
+        return { results: await reviewApi(() => readTaskContributions(cutoff)) };
+    });
     /** Acknowledge Progress entries the browser actually showed; returns the task's remaining unread. */
     app.post('/api/v1/tasks/:id/progress/read', async (request) => {
         auth.authenticate(request, true);

package/docs/task-progress-review.md

@@ -155,6 +155,8 @@ workspace-device bearer. `GET /api/v1/meta` reports API minor version 1.
 | `GET /tasks/:id/review` | `{review: {revision, markdown, updated_at, updated_by, artifacts: [{id, name, mime, size, sha256, added_at, added_by}]}}` or `{review: null}`. |
 | `PUT /tasks/:id/review` | `{markdown, expectedMarkdown}`; 409 when the Markdown changed meanwhile. |
 | `GET /tasks/:id/review/artifacts/:artifactId` | The retained bytes as `application/octet-stream` attachment with `Content-Security-Policy: default-src 'none'; sandbox`, `nosniff` and `no-store`. Another task's artifact ID is 404. |
+| `GET /contributions?limit=1-100&before=&unread=true` | Every task's Progress entries and current To review revision for the notification list, newest first: `{items: [{id, kind, task_id, mission_key?, task_title, task_state, at, excerpt, unread, entry_id? \| revision?}], next_cursor, unread_total, unavailable}`. The cursor is a position, valid after its item is read or deleted. Tasks pending deletion are left out; `unavailable` counts unreadable task records. The first page also has `cutoff: [{task_id, progress, progress_last, review}]` for every task with unread items, each captured from that task's own read (per task, not one instant across tasks). |
+| `POST /contributions/read` | `{cutoff}` with at most 200 distinct tasks from a first page: reads each task's first `progress` entries and review revision `review`, never later ones, one task change each. `{results: [{task_id, status}]}` in request order, `status` `read` (with `read`: items that were unread and are read now), `changed` (the task no longer matches its cutoff; nothing written), `gone`, `deleting` or `failed`. |
 
 The HTTP API has no upload route: the browser never submits a file path.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ours.network/fleet",
-  "version": "2.3.2",
+  "version": "2.3.3",
   "description": "Harness-agnostic fleet of persistent, identity-bound AI agents. Declarative fleet.yaml, managed native/ACP sessions, supervision, and ours.network messaging.",
   "type": "module",
   "license": "FSL-1.1-Apache-2.0",