letagents 0.12.8 → 0.12.10

package/dist/mcp/server/tools/tasks/board-intent-tools.js

@@ -0,0 +1,321 @@
+import { z } from "zod";
+import { deleteActiveBoardManager, getCanonicalTask, getBoardIntents, getBoardSettings, patchBoardSettings, postBoardIntent, postBoardIntentDecision, postBoardManager, } from "./api.js";
+import { resolveCanonicalRoomId, resolveCanonicalTaskToolIdentity, taskActorPayload, } from "./context.js";
+import { jsonToolResponse, taskToolError } from "./response.js";
+import { workerTaskIdentitySchema } from "./schemas.js";
+import { boardIntentPayloadForLeaseAction, boardIntentPayloadForTaskCreate, boardIntentPayloadForTaskMutation, } from "../../../../api/board-intent-payloads.js";
+const boardManagerModeSchema = z.enum(["off", "manager_optional", "intent_required"]);
+const boardManagerRuntimeSourceSchema = z.enum(["desktop_managed", "open_model", "external", "unknown"]);
+const boardIntentActionTypeSchema = z.enum([
+    "task_create",
+    "task_claim",
+    "task_close",
+    "task_override",
+    "task_update",
+]);
+const boardIntentPayloadSchema = z.record(z.string(), z.unknown());
+const boardIntentCloseStatusSchema = z.enum(["merged", "done", "cancelled"]);
+async function registerTypedBoardIntent(input) {
+    const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(input.roomId, input.agentSessionId ?? undefined);
+    const result = await postBoardIntent(input.roomId, {
+        action_type: input.actionType,
+        payload: input.payload,
+        task_id: input.taskId ?? undefined,
+        ...taskActorPayload(identity, agentSession),
+    });
+    return jsonToolResponse({
+        success: true,
+        ...responseObject(result),
+    }, 2);
+}
+function responseObject(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function activeWorkLeaseIdFromTask(value) {
+    const task = responseObject(value);
+    const leases = Array.isArray(task.active_leases)
+        ? task.active_leases
+        : Array.isArray(task.activeLeases)
+            ? task.activeLeases
+            : [];
+    const workLease = leases.find((lease) => {
+        if (!lease || typeof lease !== "object")
+            return false;
+        const candidate = lease;
+        return candidate.kind === "work"
+            && candidate.status === "active"
+            && typeof candidate.id === "string"
+            && candidate.id.trim().length > 0;
+    });
+    return typeof workLease?.id === "string" ? workLease.id : null;
+}
+export function registerBoardIntentTools(server) {
+    server.tool("get_board_settings", "Read Board Manager mode, the active Board Manager assignment, and pending intent count for the current room.", {
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ room_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            return jsonToolResponse({ success: true, ...responseObject(await getBoardSettings(targetRoomId)) }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("set_board_manager_mode", "Set room Board Manager mode. Requires room admin authority. Use manager_optional unless the human explicitly requires all high-impact agent board actions to register intent.", {
+        manager_mode: boardManagerModeSchema.describe("off disables intent checks; manager_optional requires approval only while a manager is assigned; intent_required always requires approval."),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ manager_mode, room_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const result = await patchBoardSettings(targetRoomId, { manager_mode });
+            return jsonToolResponse({ success: true, ...responseObject(result) }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("assign_board_manager", "Promote an active worker session to Board Manager for this room. Runtime source is inferred for Open Model workers unless explicitly provided. Requires room admin authority.", {
+        agent_session_id: z.string().describe("Active room agent session to promote."),
+        runtime_source: boardManagerRuntimeSourceSchema.optional().describe("Runtime source for audit display."),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ agent_session_id, runtime_source, room_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const result = await postBoardManager(targetRoomId, { agent_session_id, runtime_source });
+            return jsonToolResponse({
+                success: true,
+                ...responseObject(result),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("release_board_manager", "Release the active Board Manager assignment for this room. Requires room admin authority.", {
+        reason: z.string().optional().describe("Why the manager role is being released."),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ reason, room_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const result = await deleteActiveBoardManager(targetRoomId, { reason });
+            return jsonToolResponse({ success: true, ...responseObject(result) }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("register_board_intent", "Advanced: register intent with an exact payload for a high-impact board action. Prefer the typed register_task_*_intent tools so the later action hash matches.", {
+        action_type: boardIntentActionTypeSchema.describe("High-impact board action being proposed."),
+        payload: boardIntentPayloadSchema.describe("Exact payload for the intended action. The later mutation must match this payload."),
+        task_id: z.string().optional().describe("Task id for task-specific intents."),
+        ...workerTaskIdentitySchema,
+    }, async ({ action_type, payload, task_id, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postBoardIntent(targetRoomId, {
+                action_type,
+                payload,
+                task_id,
+                ...taskActorPayload(identity, agentSession),
+            });
+            return jsonToolResponse({
+                success: true,
+                ...responseObject(result),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("register_task_create_intent", "Register intent to add a task. Use this instead of add_task when Board Manager approval is required; approval creates the task directly.", {
+        title: z.string().describe("Task title exactly as it will be passed to add_task."),
+        description: z.string().optional().describe("Task description exactly as it will be passed to add_task."),
+        source_message_id: z.string().optional().describe("Source message id exactly as it will be passed to add_task."),
+        ...workerTaskIdentitySchema,
+    }, async ({ title, description, source_message_id, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            return await registerTypedBoardIntent({
+                roomId: targetRoomId,
+                actionType: "task_create",
+                payload: boardIntentPayloadForTaskCreate({
+                    title,
+                    description: description ?? null,
+                    sourceMessageId: source_message_id ?? null,
+                }),
+                agentSessionId: agent_session_id,
+            });
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("register_task_claim_intent", "Register intent to claim an accepted task as the current worker. Use the returned approval with claim_task.", {
+        task_id: z.string().describe("Task id to claim, e.g. task_12."),
+        ...workerTaskIdentitySchema,
+    }, async ({ task_id, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postBoardIntent(targetRoomId, {
+                action_type: "task_claim",
+                task_id,
+                payload: boardIntentPayloadForTaskMutation({
+                    taskId: task_id,
+                    status: "assigned",
+                    assignee: identity.actor_label,
+                    assigneeAgentKey: identity.canonical_key,
+                }),
+                ...taskActorPayload(identity, agentSession),
+            });
+            return jsonToolResponse({ success: true, ...responseObject(result) }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("register_task_close_intent", "Register intent to close a task as merged, done, or cancelled. Use the returned approval with update_task.", {
+        task_id: z.string().describe("Task id to close, e.g. task_12."),
+        status: boardIntentCloseStatusSchema.describe("Closeout status to pass to update_task."),
+        pr_url: z.string().optional().describe("PR URL exactly as it will be passed to update_task, if any."),
+        ...workerTaskIdentitySchema,
+    }, async ({ task_id, status, pr_url, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            return await registerTypedBoardIntent({
+                roomId: targetRoomId,
+                actionType: "task_close",
+                taskId: task_id,
+                payload: boardIntentPayloadForTaskMutation({
+                    taskId: task_id,
+                    status,
+                    prUrl: pr_url ?? null,
+                }),
+                agentSessionId: agent_session_id,
+            });
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("register_task_lease_action_intent", "Register intent to release or hand off a task work lease. Use the returned approval with release_task_lease or handoff_task_lease.", {
+        task_id: z.string().describe("Task id whose work lease will be changed."),
+        action: z.enum(["release", "handoff"]).describe("Lease action that will be performed."),
+        lease_id: z.string().optional().describe("Expected active lease id exactly as it will be passed to the lease action."),
+        target_agent_key: z.string().optional().describe("Target canonical agent key. Required for handoff."),
+        target_agent_session_id: z.string().optional().describe("Target registered agent session id exactly as it will be passed to handoff_task_lease."),
+        ...workerTaskIdentitySchema,
+    }, async ({ task_id, action, lease_id, target_agent_key, target_agent_session_id, room_id, conversation_id: _conversation_id, agent_session_id, }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        if (action === "handoff" && !target_agent_key) {
+            return taskToolError("target_agent_key is required for handoff intent.");
+        }
+        try {
+            const expectedLeaseId = lease_id ?? activeWorkLeaseIdFromTask(await getCanonicalTask(targetRoomId, task_id));
+            if (!expectedLeaseId) {
+                return taskToolError("No active work lease exists for this task; pass lease_id if you are approving a specific lease action.");
+            }
+            return await registerTypedBoardIntent({
+                roomId: targetRoomId,
+                actionType: "task_override",
+                taskId: task_id,
+                payload: boardIntentPayloadForLeaseAction({
+                    taskId: task_id,
+                    action,
+                    leaseId: expectedLeaseId,
+                    targetActorKey: target_agent_key ?? null,
+                    targetAgentSessionId: target_agent_session_id ?? null,
+                }),
+                agentSessionId: agent_session_id,
+            });
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("list_board_intents", "List Board Manager intents for this room, optionally filtered by status.", {
+        status: z.enum(["pending", "approved", "denied", "expired", "used"]).optional(),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ status, room_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", status);
+        try {
+            const result = await getBoardIntents(targetRoomId, params.toString());
+            return jsonToolResponse({ success: true, ...responseObject(result) }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("approve_board_intent", "Approve a pending board intent. For task_create intents this creates the task immediately and returns result.kind=\"task_created\"; do not call add_task afterward. Other intent types return a scoped approval token for the follow-up board action.", {
+        intent_id: z.string().describe("Board intent id to approve."),
+        reason: z.string().optional().describe("Short approval reason."),
+        ...workerTaskIdentitySchema,
+    }, async ({ intent_id, reason, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postBoardIntentDecision(targetRoomId, intent_id, "approve", {
+                reason,
+                ...taskActorPayload(identity, agentSession),
+            });
+            return jsonToolResponse({
+                success: true,
+                ...responseObject(result),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("deny_board_intent", "Deny a pending board intent with a short reason.", {
+        intent_id: z.string().describe("Board intent id to deny."),
+        reason: z.string().optional().describe("Short denial reason."),
+        ...workerTaskIdentitySchema,
+    }, async ({ intent_id, reason, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postBoardIntentDecision(targetRoomId, intent_id, "deny", {
+                reason,
+                ...taskActorPayload(identity, agentSession),
+            });
+            return jsonToolResponse({
+                success: true,
+                ...responseObject(result),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+}

package/dist/mcp/server/tools/tasks/board-tools.js

@@ -0,0 +1,73 @@
+import { z } from "zod";
+import { ensureAgentIdentity, getRememberedRoomPresence, heartbeatRoomPresence, syncRoomPresence, toPublicAgentIdentity, } from "../../runtime.js";
+import { createTask, listTasks } from "./api.js";
+import { resolveTaskToolIdentity, resolveTaskToolTarget, taskActorPayload, } from "./context.js";
+import { jsonToolResponse, taskToolError } from "./response.js";
+import { boardIntentApprovalSchema, TASK_STATUSES, workerTaskIdentitySchema } from "./schemas.js";
+export function registerTaskBoardTools(server) {
+    server.tool("add_task", "Add a new task to the room board. Tasks normally start as 'proposed' and must be " +
+        "accepted before an agent can claim them. Agent-created tasks require coordinator " +
+        "acceptance before they become claimable. Use this when a human or agent identifies " +
+        "work that needs to be done.", {
+        title: z.string().describe("Short task title, e.g. 'Wire up Jest test runner'"),
+        description: z.string().optional().describe("Longer description of what needs to be done"),
+        created_by: z
+            .string()
+            .optional()
+            .describe("Deprecated override. Agent identity is resolved automatically on room entry."),
+        source_message_id: z.string().optional().describe("Optional message ID where task was agreed, e.g. 'msg_42'"),
+        ...workerTaskIdentitySchema,
+        ...boardIntentApprovalSchema,
+    }, async ({ title, description, created_by: _createdBy, source_message_id, room_id, conversation_id: _conversation_id, agent_session_id, board_intent_id, board_approval_token }) => {
+        const target = resolveTaskToolTarget(room_id);
+        if (!target)
+            return taskToolError("Not in a room. Join one first.");
+        const { identity, agentSession } = await resolveTaskToolIdentity(target, agent_session_id);
+        const task = await createTask(target, {
+            title,
+            description,
+            created_by: identity.actor_label,
+            ...taskActorPayload(identity, agentSession),
+            source_message_id,
+            board_intent_id,
+            board_approval_token,
+        });
+        await syncRoomPresence(target.effectiveRoomId, identity, getRememberedRoomPresence(target.effectiveRoomId, identity), agentSession);
+        return jsonToolResponse({ success: true, task, agent_identity: toPublicAgentIdentity(identity) }, 2);
+    });
+    server.tool("get_board", "Get the current task board for the room. By default shows only actionable tasks " +
+        "(including merged closeout work, but not done/cancelled). Agents should check this on startup and when idle to " +
+        "see if there is unassigned work to claim.", {
+        status: z.enum(TASK_STATUSES).optional().describe("Filter by specific status"),
+        open_only: z.boolean().optional().describe("If true (default), only show actionable tasks, including merged closeout work but not done/cancelled"),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ status, open_only, room_id }) => {
+        const target = resolveTaskToolTarget(room_id);
+        if (!target)
+            return taskToolError("Not in a room. Join one first.");
+        const params = new URLSearchParams();
+        if (status)
+            params.set("status", status);
+        if (open_only !== false)
+            params.set("open", "true");
+        const allTasks = [];
+        let afterCursor;
+        for (;;) {
+            const pageParams = new URLSearchParams(params);
+            if (afterCursor)
+                pageParams.set("after", afterCursor);
+            const qs = pageParams.toString();
+            const result = await listTasks(target, qs);
+            const tasks = result.tasks ?? [];
+            allTasks.push(...tasks);
+            if (!result.has_more || tasks.length === 0)
+                break;
+            const lastTask = tasks[tasks.length - 1];
+            if (!lastTask?.id)
+                break;
+            afterCursor = lastTask.id;
+        }
+        await heartbeatRoomPresence(target.effectiveRoomId, await ensureAgentIdentity());
+        return jsonToolResponse({ success: true, tasks: allTasks }, 2);
+    });
+}

package/dist/mcp/server/tools/tasks/context.js

@@ -0,0 +1,35 @@
+import { AGENT_INSTANCE_UUID, agentSessionCredentials, currentRoom, getFallbackProjectId, getTargetRoomId, resolveWorkerToolIdentity, } from "../../runtime.js";
+export function resolveTaskToolTarget(roomId) {
+    const targetRoomId = getTargetRoomId(roomId);
+    const targetProjectId = getFallbackProjectId();
+    if (!targetRoomId && !targetProjectId)
+        return null;
+    return {
+        roomId: targetRoomId ?? null,
+        projectId: targetProjectId ?? null,
+        effectiveRoomId: targetRoomId ?? currentRoom?.room_id ?? null,
+    };
+}
+export function resolveCanonicalRoomId(roomId) {
+    return getTargetRoomId(roomId) ?? null;
+}
+export function resolveTaskToolIdentity(target, agentSessionId) {
+    return resolveWorkerToolIdentity({
+        roomId: target.effectiveRoomId,
+        agentSessionId,
+    });
+}
+export function resolveCanonicalTaskToolIdentity(roomId, agentSessionId) {
+    return resolveWorkerToolIdentity({
+        roomId,
+        agentSessionId,
+    });
+}
+export function taskActorPayload(identity, agentSession) {
+    return {
+        actor_label: identity.actor_label,
+        actor_key: identity.canonical_key,
+        actor_instance_id: agentSession.agent_instance_id || AGENT_INSTANCE_UUID,
+        ...agentSessionCredentials(agentSession),
+    };
+}

package/dist/mcp/server/tools/tasks/event-tools.js

@@ -0,0 +1,40 @@
+import { z } from "zod";
+import { buildRoomEventsQueryString } from "../../../room-events-query.js";
+import { encodeRoomIdPath } from "../../../room-id.js";
+import { roomScopedApiCall } from "../../runtime.js";
+import { resolveTaskToolTarget } from "./context.js";
+import { jsonToolResponse, taskToolError } from "./response.js";
+export function registerTaskEventTools(server) {
+    server.tool("get_room_events", "Get GitHub events for the room (PRs, issues, reviews, check runs, etc.). " +
+        "Returns a paginated list of normalized GitHub events persisted from webhooks. " +
+        "Use this to check what happened in the repo without parsing chat messages.", {
+        event_type: z.string().optional().describe("Filter by event type: pull_request, issue, issue_comment, pull_request_review, check_run, installation, installation_repositories, repository, push, create, delete"),
+        object_id: z.string().optional().describe("Filter by GitHub object ID (e.g. PR number, issue number)"),
+        actor: z.string().optional().describe("Filter by GitHub login of the actor"),
+        since: z.string().optional().describe("ISO timestamp — only events after this time"),
+        until: z.string().optional().describe("ISO timestamp — only events before this time"),
+        after: z.string().optional().describe("Cursor event ID for pagination (from a previous response)"),
+        limit: z.number().int().min(1).max(100).optional().describe("Max events to return (default 50, max 100)"),
+        room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
+    }, async ({ event_type, object_id, actor, since, until, after, limit, room_id }) => {
+        const target = resolveTaskToolTarget(room_id);
+        if (!target)
+            return taskToolError("Not in a room. Join one first.");
+        const qs = buildRoomEventsQueryString({
+            event_type,
+            object_id,
+            actor,
+            since,
+            until,
+            after,
+            limit,
+        });
+        const result = await roomScopedApiCall({
+            room_id: target.roomId,
+            project_id: target.projectId,
+            room_path: (roomId) => `/rooms/${encodeRoomIdPath(roomId)}/events${qs ? `?${qs}` : ""}`,
+            project_path: (projectId) => `/rooms/${encodeURIComponent(projectId)}/events${qs ? `?${qs}` : ""}`,
+        });
+        return jsonToolResponse({ success: true, events: result.events ?? [], has_more: result.has_more ?? false }, 2);
+    });
+}

package/dist/mcp/server/tools/tasks/index.js

@@ -0,0 +1,14 @@
+import { registerBoardIntentTools } from "./board-intent-tools.js";
+import { registerTaskArtifactTools } from "./artifact-tools.js";
+import { registerTaskBoardTools } from "./board-tools.js";
+import { registerTaskEventTools } from "./event-tools.js";
+import { registerTaskLeaseTools } from "./lease-tools.js";
+import { registerTaskMutationTools } from "./mutation-tools.js";
+export function registerTaskTools(server) {
+    registerTaskBoardTools(server);
+    registerBoardIntentTools(server);
+    registerTaskEventTools(server);
+    registerTaskArtifactTools(server);
+    registerTaskMutationTools(server);
+    registerTaskLeaseTools(server);
+}

package/dist/mcp/server/tools/tasks/lease-tools.js

@@ -0,0 +1,145 @@
+import { z } from "zod";
+import { syncRoomPresence, toPublicAgentIdentity } from "../../runtime.js";
+import { postCanonicalTaskAction } from "./api.js";
+import { resolveCanonicalRoomId, resolveCanonicalTaskToolIdentity, taskActorPayload, } from "./context.js";
+import { jsonToolResponse, taskToolError } from "./response.js";
+import { boardIntentApprovalSchema, taskLeaseIdentitySchema, taskReviewIdentitySchema } from "./schemas.js";
+export function registerTaskLeaseTools(server) {
+    server.tool("claim_task_review", "Claim board review authority for a task in review. This creates a review lease " +
+        "for the registered worker session and is rejected if the worker holds the active work lease.", {
+        task_id: z.string().describe("The task to review, e.g. 'task_1'"),
+        reason: z.string().optional().describe("Why this worker is taking review authority"),
+        ...taskReviewIdentitySchema,
+    }, async ({ task_id, reason, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postCanonicalTaskAction(targetRoomId, task_id, "review-lease-action", {
+                action: "claim",
+                reason,
+                ...taskActorPayload(identity, agentSession),
+            });
+            await syncRoomPresence(targetRoomId, identity, {
+                status: "reviewing",
+                status_text: `reviewing ${task_id}`,
+            }, agentSession);
+            return jsonToolResponse({
+                success: true,
+                ...result,
+                agent_identity: toPublicAgentIdentity(identity),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("release_task_review", "Release this worker's active review lease on a task. Room admins can pass a specific lease_id to clear another review lease.", {
+        task_id: z.string().describe("The task whose review lease should be released"),
+        lease_id: z.string().optional().describe("Optional review lease id. Required for admin release of another reviewer."),
+        reason: z.string().optional().describe("Why review authority is being released"),
+        ...taskReviewIdentitySchema,
+    }, async ({ task_id, lease_id, reason, room_id, conversation_id: _conversation_id, agent_session_id }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postCanonicalTaskAction(targetRoomId, task_id, "review-lease-action", {
+                action: "release",
+                lease_id: lease_id ?? undefined,
+                reason,
+                ...taskActorPayload(identity, agentSession),
+            });
+            await syncRoomPresence(targetRoomId, identity, {
+                status: "idle",
+                status_text: `released review on ${task_id}`,
+            }, agentSession);
+            return jsonToolResponse({
+                success: true,
+                ...result,
+                agent_identity: toPublicAgentIdentity(identity),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("release_task_lease", "Release or forcibly clear the active work lease on a task so it can be claimed again. " +
+        "Use this when the current worker is blocked, gone, or needs to give the lane back to the room.", {
+        task_id: z.string().describe("The task whose active work lease should be cleared"),
+        lease_id: z.string().optional().describe("Optional expected active lease id for stale-checking"),
+        reason: z.string().optional().describe("Why the lease is being released"),
+        ...taskLeaseIdentitySchema,
+        ...boardIntentApprovalSchema,
+    }, async ({ task_id, lease_id, reason, room_id, conversation_id: _conversation_id, agent_session_id, board_intent_id, board_approval_token }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postCanonicalTaskAction(targetRoomId, task_id, "lease-action", {
+                action: "release",
+                lease_id: lease_id ?? undefined,
+                reason,
+                board_intent_id,
+                board_approval_token,
+                ...taskActorPayload(identity, agentSession),
+            });
+            await syncRoomPresence(targetRoomId, identity, {
+                status: "working",
+                status_text: `released lease on ${task_id}`,
+            }, agentSession);
+            return jsonToolResponse({
+                success: true,
+                ...result,
+                agent_identity: toPublicAgentIdentity(identity),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+    server.tool("handoff_task_lease", "Transfer the active work lease on a task to another agent. " +
+        "This reassigns the task and mints a fresh work lease for the target worker session.", {
+        task_id: z.string().describe("The task whose active work lease should be transferred"),
+        target_agent_key: z.string().describe("Canonical agent key to receive the new work lease"),
+        target_actor_instance_id: z.string().optional().describe("Optional target agent instance id when selecting among active sessions for the same agent key"),
+        target_agent_session_id: z.string().optional().describe("Optional target registered agent session id. Required when the target agent key has multiple active worker sessions."),
+        lease_id: z.string().optional().describe("Optional expected active lease id for stale-checking"),
+        reason: z.string().optional().describe("Why the lane is being handed off"),
+        ...taskLeaseIdentitySchema,
+        ...boardIntentApprovalSchema,
+    }, async ({ task_id, target_agent_key, target_actor_instance_id, target_agent_session_id, lease_id, reason, room_id, conversation_id: _conversation_id, agent_session_id, board_intent_id, board_approval_token, }) => {
+        const targetRoomId = resolveCanonicalRoomId(room_id);
+        if (!targetRoomId)
+            return taskToolError("Not in a canonical room.");
+        try {
+            const { identity, agentSession } = await resolveCanonicalTaskToolIdentity(targetRoomId, agent_session_id);
+            const result = await postCanonicalTaskAction(targetRoomId, task_id, "lease-action", {
+                action: "handoff",
+                lease_id: lease_id ?? undefined,
+                reason,
+                target_actor_key: target_agent_key,
+                target_actor_instance_id: target_actor_instance_id ?? undefined,
+                target_agent_session_id: target_agent_session_id ?? undefined,
+                board_intent_id,
+                board_approval_token,
+                ...taskActorPayload(identity, agentSession),
+            });
+            await syncRoomPresence(targetRoomId, identity, {
+                status: "working",
+                status_text: `handed off ${task_id} to ${target_agent_key}`,
+            }, agentSession);
+            return jsonToolResponse({
+                success: true,
+                ...result,
+                agent_identity: toPublicAgentIdentity(identity),
+            }, 2);
+        }
+        catch (error) {
+            return taskToolError(String(error));
+        }
+    });
+}