@ours.network/fleet 1.2.0-nightly.9 → 2.0.1

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

@@ -0,0 +1,35 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { publicProgressEntry } from './task-review.js';
+import type { TaskContributionAuthor, TaskProgressEntry } from './types.js';
+/** The task this agent belongs to, from supervisor launch records; never from tool arguments. */
+export interface TaskToolBinding {
+    taskId: string;
+    role: string;
+    identityCid?: string;
+    /** Launched as a task-owned temporary member (layout participant). */
+    taskOwned: boolean;
+}
+export declare const TASK_TOOL_NAMES: readonly ["fleet_task_progress_list", "fleet_task_progress_append", "fleet_task_review_show", "fleet_task_review_set", "fleet_task_review_detach"];
+export declare const PROGRESS_PAGE_MAX = 50;
+/** One chronological page of the log; `next_after` continues after the last returned entry. */
+export declare function progressPage(entries: TaskProgressEntry[], input: {
+    after?: string;
+    limit?: number;
+}): {
+    progress: ReturnType<typeof publicProgressEntry>[];
+    total: number;
+    next_after?: string;
+};
+/**
+ * Confirm the binding against the task record: a listed member must match by
+ * name and identity; an unlisted caller must be a task-owned launch.
+ */
+export declare function verifiedTaskAuthor(binding: TaskToolBinding): TaskContributionAuthor;
+/**
+ * Task Progress and To review tools on the agent's own managed MCP endpoint.
+ * The task and author come from the caller's supervisor, so an agent can only
+ * read and write the task it was launched for. Review files are attached with
+ * `ours-fleet task review-package <id> --attach <path>`, which reads the file
+ * under the agent's own permissions.
+ */
+export declare function registerTaskTools(server: McpServer, binding: () => TaskToolBinding | undefined, admit: () => Promise<() => void>): void;

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

@@ -0,0 +1,134 @@
+import { z } from 'zod';
+import { appendTaskProgress, detachTaskReviewArtifact, getTaskReview, listTaskProgress, publicProgressEntry, publicReview, setTaskReviewMarkdown, TaskReviewError, PROGRESS_TEXT_MAX, REVIEW_MARKDOWN_MAX, } from './task-review.js';
+import { getTask, TaskStateError } from './task-state.js';
+export const TASK_TOOL_NAMES = Object.freeze([
+    'fleet_task_progress_list', 'fleet_task_progress_append',
+    'fleet_task_review_show', 'fleet_task_review_set', 'fleet_task_review_detach',
+]);
+/** Compact JSON: a result is carried twice (text and structured) inside one bounded bridge frame. */
+function result(value) {
+    return {
+        content: [{ type: 'text', text: JSON.stringify(value) }],
+        structuredContent: value,
+        isError: false,
+    };
+}
+export const PROGRESS_PAGE_MAX = 50;
+/** Serialized entry bytes per page, well inside the bridge's frame limit even at maximal escaping. */
+const PROGRESS_PAGE_BYTES = 200_000;
+/** One chronological page of the log; `next_after` continues after the last returned entry. */
+export function progressPage(entries, input) {
+    const limit = input.limit ?? PROGRESS_PAGE_MAX;
+    if (!Number.isInteger(limit) || limit < 1 || limit > PROGRESS_PAGE_MAX)
+        throw new TaskReviewError('invalid_request', `limit must be 1..${PROGRESS_PAGE_MAX}`);
+    let start = 0;
+    if (input.after !== undefined) {
+        start = entries.findIndex(entry => entry.id === input.after) + 1;
+        if (!start)
+            throw new TaskReviewError('invalid_request', 'after must be the id of an entry in this log');
+    }
+    const page = [];
+    let bytes = 0;
+    for (const entry of entries.slice(start, start + limit)) {
+        const visible = publicProgressEntry(entry), size = Buffer.byteLength(JSON.stringify(visible));
+        if (page.length && bytes + size > PROGRESS_PAGE_BYTES)
+            break;
+        page.push(visible);
+        bytes += size;
+    }
+    const end = start + page.length;
+    return { progress: page, total: entries.length, ...(end < entries.length ? { next_after: entries[end - 1].id } : {}) };
+}
+function failure(code, message) {
+    return { content: [{ type: 'text', text: JSON.stringify({ error: code, message }) }], isError: true };
+}
+/**
+ * Confirm the binding against the task record: a listed member must match by
+ * name and identity; an unlisted caller must be a task-owned launch.
+ */
+export function verifiedTaskAuthor(binding) {
+    const task = getTask(binding.taskId);
+    const member = task.member_roles.find(item => item.name === binding.role);
+    if (member ? (binding.identityCid && member.identity_cid !== binding.identityCid) : !binding.taskOwned)
+        throw new TaskReviewError('conflict', `agent ${binding.role} is not a member of task ${binding.taskId}`);
+    return { kind: 'agent', role: binding.role, ...(binding.identityCid ? { identity_cid: binding.identityCid } : {}), surface: 'mcp' };
+}
+/**
+ * Task Progress and To review tools on the agent's own managed MCP endpoint.
+ * The task and author come from the caller's supervisor, so an agent can only
+ * read and write the task it was launched for. Review files are attached with
+ * `ours-fleet task review-package <id> --attach <path>`, which reads the file
+ * under the agent's own permissions.
+ */
+export function registerTaskTools(server, binding, admit) {
+    const run = async (operation) => {
+        let release;
+        try {
+            release = await admit();
+        }
+        catch {
+            return failure('runtime_not_ready', 'the managed runtime is not admitting tool calls right now; nothing was read or changed');
+        }
+        try {
+            const bound = binding();
+            if (!bound)
+                return failure('task_unavailable', 'this agent was not launched for a Fleet task');
+            try {
+                return result(operation(bound, verifiedTaskAuthor(bound)));
+            }
+            catch (error) {
+                if (error instanceof TaskReviewError)
+                    return failure(error.code, error.message);
+                if (error instanceof TaskStateError)
+                    return failure('task_unavailable', error.message);
+                return failure('task_store_failed', 'the task could not be read or updated; nothing was changed');
+            }
+        }
+        finally {
+            release();
+        }
+    };
+    server.registerTool('fleet_task_progress_list', {
+        description: 'Read the Progress milestone log of the task you were launched for, oldest first, one page at a time. '
+            + 'When next_after is present, call again with after set to it for the following entries.',
+        inputSchema: {
+            after: z.string().optional().describe('Entry id from the previous page\'s next_after; omit for the first page.'),
+            limit: z.number().int().optional().describe(`Maximum entries per page (1..${PROGRESS_PAGE_MAX}, default ${PROGRESS_PAGE_MAX}). Pages are also bounded in size.`),
+        },
+    }, async (args) => run(bound => ({ task_id: bound.taskId, ...progressPage(listTaskProgress(bound.taskId), args) })));
+    server.registerTool('fleet_task_progress_append', {
+        description: 'Append ONE significant, verified milestone to your task\'s Progress log (e.g. root cause found, PR opened with link, '
+            + 'measured result with its scope, final deliverable ready). Not for routine status, handoffs or review chatter. '
+            + 'Entries are permanent and shown to the Owner as written. Repeating a call with the same request_key and text returns the original entry.',
+        inputSchema: {
+            text: z.string().describe(`Free-form milestone text, kept exactly as written (max ${PROGRESS_TEXT_MAX} characters).`),
+            request_key: z.string().optional().describe('Stable key for this milestone so a retried call cannot add it twice (e.g. "pr-opened-123").'),
+        },
+    }, async (args) => run((bound, author) => {
+        const appended = appendTaskProgress(bound.taskId, { text: args.text, requestKey: args.request_key, author });
+        return { task_id: bound.taskId, entry: publicProgressEntry(appended.entry), replayed: appended.replayed };
+    }));
+    server.registerTool('fleet_task_review_show', {
+        description: 'Read your task\'s To review package: its Markdown and the retained files attached to it.',
+        inputSchema: {},
+    }, async () => run(bound => {
+        const review = getTaskReview(bound.taskId);
+        return { task_id: bound.taskId, review: review ? publicReview(review) : null };
+    }));
+    server.registerTool('fleet_task_review_set', {
+        description: 'Replace the Markdown of your task\'s To review package: the self-contained material the Owner reviews without reading the room or task description '
+            + '(outcome, clickable PR/spec links, validation and CI, independent verdict, limits, decisions needed). '
+            + 'Pass the Markdown you last read as expected_markdown ("" when empty); a concurrent change is refused instead of overwritten.',
+        inputSchema: {
+            markdown: z.string().describe(`Review Markdown (max ${REVIEW_MARKDOWN_MAX} characters). Links use the same safe rules as task descriptions.`),
+            expected_markdown: z.string().describe('The current Markdown as you last read it, or "" if there is none.'),
+        },
+    }, async (args) => run((bound, author) => ({
+        task_id: bound.taskId,
+        review: publicReview(setTaskReviewMarkdown(bound.taskId, { markdown: args.markdown, expectedMarkdown: args.expected_markdown, author })),
+    })));
+    server.registerTool('fleet_task_review_detach', {
+        description: 'Remove one file from your task\'s To review package by artifact_id (from fleet_task_review_show).',
+        inputSchema: { artifact_id: z.string() },
+    }, async (args) => run((bound, author) => ({ task_id: bound.taskId, detached: detachTaskReviewArtifact(bound.taskId, args.artifact_id, { author }) })));
+}

package/dist/rooms-tasks/types.d.ts

@@ -62,6 +62,8 @@ export type TaskDeletionMemberPhase = 'pending' | 'stop_requested' | 'liveness_a
 export interface TaskDeletionMemberCursor {
     name: string;
     identity_cid: string;
+    action_id?: string;
+    task_supervised?: boolean;
     phase: TaskDeletionMemberPhase;
     launch_id?: string;
     archive_path?: string;
@@ -88,13 +90,79 @@ export interface TaskDeletionIntent {
     /** Snapshot of managed members at acceptance; the missing-room retirement evidence. */
     members: TaskDeletionMemberCursor[];
     archived_absences?: ArchivedMemberAbsence[];
+    absent_members?: string[];
+    /** Archive proofs were verified before owned workspace cleanup may consume them. */
+    workspace_cleanup_started_at?: string;
     error?: string;
     error_at?: string;
     recovery_hint?: string;
     first_failure?: string;
     first_recovery_hint?: string;
 }
+export interface TaskLayoutLink {
+    name: string;
+    /** Deterministic `task-<task_id>` Room Layout run ID. */
+    run_id: string;
+    /** sha256 of the canonical source layout definition the run must snapshot. */
+    definition_hash: string;
+}
+export interface TaskNotificationEvent {
+    eventId: string;
+    title: string;
+    body: string;
+    target: {
+        kind: 'task' | 'task-deleted';
+        taskId: string;
+    };
+    taskId: string;
+}
+/** Who wrote a progress entry or review change, as established by the Fleet surface. */
+export type TaskContributionAuthor = {
+    kind: 'agent';
+    role: string;
+    identity_cid?: string;
+    surface: 'mcp' | 'cli';
+} | {
+    kind: 'local_control';
+    surface: 'cli' | 'web';
+};
+/** One append-only milestone; text is stored exactly as authored. */
+export interface TaskProgressEntry {
+    id: string;
+    at: string;
+    author: TaskContributionAuthor;
+    text: string;
+    /** Caller retry key, scoped to the author. */
+    request_key?: string;
+}
+/** Metadata of a retained review file; bytes live in Fleet's private task review store. */
+export interface TaskReviewArtifact {
+    id: string;
+    name: string;
+    mime: string;
+    size: number;
+    sha256: string;
+    added_at: string;
+    added_by: TaskContributionAuthor;
+    request_key?: string;
+}
+/** Self-contained material the Owner reviews: Markdown plus retained files. */
+export interface TaskReview {
+    /** Increases with every change to the Markdown or the files; absent on packages written before it. */
+    revision?: number;
+    markdown: string;
+    updated_at: string;
+    updated_by: TaskContributionAuthor;
+    artifacts: TaskReviewArtifact[];
+}
 export interface TaskRecord {
+    /** Optional milestone log; absent on tasks that never recorded one. */
+    progress?: TaskProgressEntry[];
+    /** Optional To review package; absent until an agent prepares it. */
+    review?: TaskReview;
+    /** Pending lifecycle events, committed atomically with their task change. */
+    notification_events?: TaskNotificationEvent[];
+    workspace?: import('./workspace.js').OwnedWorkspace;
     task_id: string;
     /** Stable organizational list identifier. Missing legacy values mean `default`. */
     list_id: string;
@@ -115,6 +183,12 @@ export interface TaskRecord {
         plan_hash: string;
     };
     no_room?: boolean;
+    /** Multi-room task: rooms and participants come from a Room Layout run. */
+    layout?: TaskLayoutLink;
+    /** Set when the room plan (layout or one-room template) was changed after creation, before start. */
+    room_plan_changed_at?: string;
+    /** Fingerprint of the room plan requested at creation; idempotent retries compare against it after later plan edits. */
+    creation_plan?: string;
     room_id?: string;
     room_identity_cid?: string;
     member_roles: TaskMemberRole[];
@@ -153,6 +227,7 @@ export interface RoomRoleBriefingDefinition {
     last_error?: string;
 }
 export interface RoomMemberLaunchState {
+    task_supervised?: boolean;
     state: 'pending' | 'intent' | 'launched' | 'stopped' | 'failed';
     attempt: number;
     action_id?: string;
@@ -209,6 +284,7 @@ export type RoomHistoryEvidence = {
 };
 export type MemberRetirementPhase = 'stop_requested' | 'liveness_absent' | 'archive_secured' | 'identity_absent';
 export interface MemberRetirement {
+    absence_verified?: boolean;
     phase: MemberRetirementPhase;
     launch_id: string;
     updated_at: string;
@@ -235,12 +311,14 @@ export interface RoomMemberSeat {
     retirement?: MemberRetirement;
 }
 export interface RoomOrchestrationRecord {
+    workspace?: import('./workspace.js').OwnedWorkspace;
     room_id: string;
     room_identity_cid?: string;
     room_name: string;
     goal?: string;
     task_id?: string;
     template_snapshot?: TemplateSnapshot;
+    additional_member_templates?: TemplateSnapshot[];
     /** Resolved once at launch; legacy absence means non-anonymous. */
     room_policy?: RoomLaunchPolicy;
     saga: SagaCursor;

package/dist/rooms-tasks/workspace-artifacts.d.ts

@@ -0,0 +1,6 @@
+import { type OwnedWorkspace } from './workspace.js';
+/** Runtime control state stays in Fleet's live roster and recovery store. Its
+ * durable launch descriptor, not a name prefix or caller-supplied path, proves
+ * artifact ownership. Audit receipts/journals intentionally outlive deletion.
+ */
+export declare function collectWorkspaceArchives(workspace: OwnedWorkspace): void;

package/dist/rooms-tasks/workspace-artifacts.js

@@ -0,0 +1,93 @@
+import { lstatSync, mkdirSync, readdirSync, readFileSync, renameSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parse } from 'yaml';
+import { stateRoot } from '../paths.js';
+import { assertSafeAncestors, auditWorkspaceGit, validateWorkspace, ensureWorkspace, WorkspaceError } from './workspace.js';
+/** Runtime control state stays in Fleet's live roster and recovery store. Its
+ * durable launch descriptor, not a name prefix or caller-supplied path, proves
+ * artifact ownership. Audit receipts/journals intentionally outlive deletion.
+ */
+export function collectWorkspaceArchives(workspace) {
+    validateWorkspace(workspace);
+    const root = join(stateRoot(), 'recovery', 'temporary');
+    assertSafeAncestors(root);
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return;
+        throw e;
+    }
+    const owned = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || entry.isSymbolicLink())
+            continue;
+        const path = join(root, entry.name);
+        const roleFile = join(path, 'role.yaml');
+        let role;
+        try {
+            const s = lstatSync(roleFile);
+            if (!s.isFile() || s.isSymbolicLink())
+                continue;
+            role = parse(readFileSync(roleFile, 'utf8'));
+        }
+        catch {
+            continue;
+        } // no ownership proof: never adopt a foreign archive
+        const recorded = role?.roomMemberStartup?.workspace;
+        if (recorded?.owner !== workspace.owner || recorded.id !== workspace.id)
+            continue;
+        if (JSON.stringify(recorded) !== JSON.stringify(workspace))
+            throw new WorkspaceError('workspace archive ownership mismatch');
+        assertSafeAncestors(path);
+        const termination = join(path, 'termination.jsonl');
+        if (!lstatSync(termination).isFile() || lstatSync(termination).isSymbolicLink())
+            throw new WorkspaceError('unsafe workspace archive termination evidence');
+        const supervisorPath = join(path, '.temp-supervisor.json');
+        let supervisor;
+        try {
+            if (!lstatSync(supervisorPath).isFile() || lstatSync(supervisorPath).isSymbolicLink())
+                throw new WorkspaceError('unsafe workspace archive supervisor evidence');
+            supervisor = JSON.parse(readFileSync(supervisorPath, 'utf8'));
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        if (supervisor && (supervisor.role !== role.name || !supervisor.launchId))
+            throw new WorkspaceError('workspace archive launch ownership mismatch');
+        const terminated = readFileSync(termination, 'utf8').trim().split('\n').some(line => {
+            const value = JSON.parse(line);
+            return value.version === 1 && value.role === role.name
+                && value.launchId === supervisor?.launchId
+                && ['retired', 'reclaimed', 'failed'].includes(value.outcome);
+        });
+        if (!terminated || entry.name.endsWith('.retiring'))
+            throw new WorkspaceError('workspace archive retirement is incomplete');
+        auditWorkspaceGit(path, { forDeletion: true });
+        owned.push(path);
+    }
+    // Preflight the entire set before mutation; task/room record remains until all succeed.
+    if (!owned.length)
+        return;
+    ensureWorkspace(workspace);
+    const destination = join(workspace.path, '.fleet-retired-agents');
+    assertSafeAncestors(destination);
+    mkdirSync(destination, { recursive: true, mode: 0o700 });
+    for (const path of owned) {
+        const target = join(destination, basename(path));
+        try {
+            lstatSync(target);
+            throw new WorkspaceError('archive collection destination exists');
+        }
+        catch (e) {
+            if (e.code !== 'ENOENT')
+                throw e;
+        }
+        // Atomic transfer before workspace deletion: a crash never loses ownership
+        // evidence halfway through recursively removing a global recovery archive.
+        renameSync(path, target);
+    }
+}

package/dist/rooms-tasks/workspace.d.ts

@@ -0,0 +1,35 @@
+/** Persisted before allocation. Never infer ownership from an Agent's cwd. */
+export interface OwnedWorkspace {
+    version: 1;
+    owner: 'task' | 'room';
+    id: string;
+    path: string;
+    token: string;
+}
+export declare class WorkspaceError extends Error {
+}
+export declare function assertSafeAncestors(path: string): void;
+export declare function planWorkspace(owner: OwnedWorkspace['owner'], id: string): OwnedWorkspace;
+export declare function validateWorkspace(w: OwnedWorkspace, owner?: "task" | "room", id?: string): void;
+/** Read-only recovery proof; never allocate a replacement for a missing workspace. */
+export declare function assertWorkspacePresent(w: OwnedWorkspace, owner: OwnedWorkspace['owner'], id: string): void;
+/** Caller must first prove the exact workspace marker or retired archive
+ * provenance, and hold its lifecycle lock with all managed writers retired.
+ * Directories need owner rwx for recursive removal; ordinary files do not.
+ */
+export declare function prepareOwnedDeletionTree(path: string): void;
+/** Atomic directory publication; retry uses the durable token, never adopts another folder. */
+export declare function ensureWorkspace(w: OwnedWorkspace): string;
+/** Audit both directions of Git worktree registration, without executing repository config/hooks.
+ * All registrations and common dirs must be inside this workspace. Removing the complete
+ * workspace then removes their registries atomically with the owned repositories; never prune.
+ */
+export declare function auditWorkspaceGit(path: string, options?: {
+    forDeletion?: boolean;
+}): void;
+/** Called only after all managed writers retire, under the owner's lifecycle lock.
+ * The tombstone is derived from the durable unguessable token. A crash during rm
+ * resumes that exact tombstone even if rm already removed its marker.
+ */
+export declare function assertWorkspaceDeletable(w: OwnedWorkspace, owner: OwnedWorkspace['owner'], id: string): void;
+export declare function deleteWorkspace(w: OwnedWorkspace, owner: OwnedWorkspace['owner'], id: string): void;