letagents 0.12.1 → 0.12.3

package/dist/mcp/agent-presence.js

@@ -0,0 +1,39 @@
+const IDLE_STATUS_RE = /\b(idle|available|online|polling|monitoring|watching|ready)\b/i;
+const REVIEWING_STATUS_RE = /\b(review|reviewing|approve|approval|approving)\b/i;
+const BLOCKED_STATUS_RE = /\b(blocked|waiting|stuck)\b/i;
+export function classifyPresenceStatusText(statusText, fallback = "working") {
+    const normalized = statusText.trim();
+    if (!normalized) {
+        return fallback;
+    }
+    if (BLOCKED_STATUS_RE.test(normalized)) {
+        return "blocked";
+    }
+    if (IDLE_STATUS_RE.test(normalized)) {
+        return "idle";
+    }
+    if (REVIEWING_STATUS_RE.test(normalized)) {
+        return "reviewing";
+    }
+    return "working";
+}
+export function deriveTaskPresenceStatus(taskStatus, fallback = "working") {
+    switch (taskStatus) {
+        case "blocked":
+            return "blocked";
+        case "in_review":
+            return "reviewing";
+        case "merged":
+        case "done":
+        case "accepted":
+            return "idle";
+        case "assigned":
+        case "in_progress":
+            return "working";
+        default:
+            return fallback;
+    }
+}
+export function getRoomIdentityPresenceCacheKey(roomId, actorLabel) {
+    return JSON.stringify([roomId, actorLabel]);
+}

package/dist/mcp/room-events-query.js

@@ -0,0 +1,18 @@
+export function buildRoomEventsQueryString(input) {
+    const params = new URLSearchParams();
+    if (input.event_type)
+        params.set("event_type", input.event_type);
+    if (input.object_id)
+        params.set("object_id", input.object_id);
+    if (input.actor)
+        params.set("actor", input.actor);
+    if (input.since)
+        params.set("since", input.since);
+    if (input.until)
+        params.set("until", input.until);
+    if (input.after)
+        params.set("after", input.after);
+    if (input.limit)
+        params.set("limit", String(input.limit));
+    return params.toString();
+}

package/dist/mcp/server.js

@@ -16,10 +16,13 @@ import { encodeRoomIdPath, getCanonicalRoomWebPath, looksLikeInviteCode, normali
 import { buildAgentActorLabel, formatOwnerAttribution, inferAgentIdeLabel, toTitleCaseCodename, } from "../shared/agent-identity.js";
 import { buildRoomAgentPrompt, normalizeAgentPromptKind, } from "../shared/room-agent-prompts.js";
 import { inspectLocalCodexSession, startLocalCodexSession, stopLocalCodexSession, toPublicCodexLiveSession, } from "./codex-session.js";
+import { classifyPresenceStatusText, deriveTaskPresenceStatus, getRoomIdentityPresenceCacheKey, } from "./agent-presence.js";
+import { buildRoomEventsQueryString } from "./room-events-query.js";
 let currentRoom = null;
 let currentAgentIdentityKey = "";
 let currentAgentIdentity = null;
 let currentAuthenticatedAccount = undefined;
+const roomPresenceByIdentity = new Map();
 // ---------------------------------------------------------------------------
 // Conversation-scoped identity (Option C: per-conversation hints)
 // ---------------------------------------------------------------------------
@@ -734,6 +737,42 @@ function touchCurrentRoom(lastMessageId) {
     }
     touchRoomSession(currentRoom.room_id, lastMessageId);
 }
+function getRememberedRoomPresence(roomId, identity) {
+    if (!roomId || !identity) {
+        return { status: "idle", status_text: null };
+    }
+    return (roomPresenceByIdentity.get(getRoomIdentityPresenceCacheKey(roomId, identity.actor_label)) ?? { status: "idle", status_text: null });
+}
+async function syncRoomPresence(roomId, identity, presence) {
+    if (!roomId || !identity) {
+        return;
+    }
+    roomPresenceByIdentity.set(getRoomIdentityPresenceCacheKey(roomId, identity.actor_label), presence);
+    try {
+        await apiCall(`/rooms/${encodeRoomIdPath(roomId)}/presence`, {
+            method: "POST",
+            body: JSON.stringify({
+                actor_label: identity.actor_label,
+                agent_key: identity.canonical_key,
+                display_name: identity.display_name,
+                owner_label: identity.owner_label,
+                ide_label: identity.ide_label,
+                status: presence.status,
+                status_text: presence.status_text,
+            }),
+        });
+        touchRoomSession(roomId);
+    }
+    catch (error) {
+        if (isMissingRouteError(error)) {
+            return;
+        }
+        throw error;
+    }
+}
+async function heartbeatRoomPresence(roomId, identity) {
+    await syncRoomPresence(roomId, identity, getRememberedRoomPresence(roomId, identity));
+}
 function getTargetRoomId(roomId) {
     return roomId || currentRoom?.room_id || null;
 }
@@ -827,6 +866,10 @@ async function joinRoomIdentifier(identifier, joinedVia) {
             joined_via: joinedVia,
         }));
         const agentIdentity = await ensureAgentIdentity();
+        await syncRoomPresence(room.room_id, agentIdentity, {
+            status: "idle",
+            status_text: "online in room",
+        });
         return {
             room,
             response: {
@@ -855,6 +898,10 @@ async function joinRoomIdentifier(identifier, joinedVia) {
             joined_via: joinedVia,
         }));
         const agentIdentity = await ensureAgentIdentity();
+        await syncRoomPresence(room.room_id, agentIdentity, {
+            status: "idle",
+            status_text: "online in room",
+        });
         return {
             room,
             response: {
@@ -883,6 +930,10 @@ async function joinRoomIdentifier(identifier, joinedVia) {
         joined_via: joinedVia,
     }));
     const agentIdentity = await ensureAgentIdentity();
+    await syncRoomPresence(room.room_id, agentIdentity, {
+        status: "idle",
+        status_text: "online in room",
+    });
     return {
         room,
         response: {
@@ -908,6 +959,10 @@ async function createInviteRoom() {
         joined_via: "join_code",
     }));
     const agentIdentity = await ensureAgentIdentity();
+    await syncRoomPresence(room.room_id, agentIdentity, {
+        status: "idle",
+        status_text: "online in room",
+    });
     return {
         room,
         response: {
@@ -1362,6 +1417,10 @@ server.tool("post_status", "Broadcast a lightweight status update to the current
         },
     });
     touchCurrentRoom(typeof message.id === "string" ? message.id : undefined);
+    await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, {
+        status: classifyPresenceStatusText(status, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity).status),
+        status_text: status,
+    });
     return {
         content: [
             {
@@ -1420,6 +1479,7 @@ server.tool("add_task", "Add a new task to the room board. Tasks normally start
             }),
         },
     });
+    await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity);
     return {
         content: [
             {
@@ -1471,10 +1531,49 @@ server.tool("get_board", "Get the current task board for the room. By default sh
             break;
         afterCursor = lastTask.id;
     }
+    await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, await ensureAgentIdentity());
     return {
         content: [{ type: "text", text: JSON.stringify({ success: true, tasks: allTasks }, null, 2) }],
     };
 });
+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"),
+    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 targetRoomId = getTargetRoomId(room_id);
+    const targetProjectId = getFallbackProjectId();
+    if (!targetRoomId && !targetProjectId) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: "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: targetRoomId,
+        project_id: targetProjectId,
+        room_path: (targetRoomId) => `/rooms/${encodeRoomIdPath(targetRoomId)}/events${qs ? `?${qs}` : ""}`,
+        project_path: (targetProjectId) => `/rooms/${encodeURIComponent(targetProjectId)}/events${qs ? `?${qs}` : ""}`,
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify({ success: true, events: result.events ?? [], has_more: result.has_more ?? false }, null, 2) }],
+    };
+});
 server.tool("claim_task", "Claim an accepted task. The task must be in 'accepted' " +
     "status. This sets the assignee to you and moves the status to 'assigned'. " +
     "Do NOT claim proposed tasks — they need to be accepted first.", {
@@ -1505,6 +1604,10 @@ server.tool("claim_task", "Claim an accepted task. The task must be in 'accepted
                 body: JSON.stringify({ status: "assigned", assignee: identity.actor_label }),
             },
         });
+        await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, {
+            status: "working",
+            status_text: `claimed ${task_id}`,
+        });
         return {
             content: [
                 {
@@ -1530,9 +1633,23 @@ server.tool("update_task", "Update a task's status or assignee. Status transitio
         .optional()
         .describe("New assignee for the task. Defaults to the current agent when status=assigned."),
     pr_url: z.string().optional().describe("PR URL to link to the task"),
+    workflow_artifacts: z
+        .array(z.object({
+        provider: z.enum(["github", "gitlab", "bitbucket", "unknown"]),
+        kind: z.enum(["issue", "branch", "pull_request", "merge_request", "review", "check_run", "merge"]),
+        id: z.string().nullable().optional(),
+        number: z.number().int().nullable().optional(),
+        title: z.string().nullable().optional(),
+        url: z.string().nullable().optional(),
+        ref: z.string().nullable().optional(),
+        state: z.string().nullable().optional(),
+    }).strict())
+        .max(32)
+        .optional()
+        .describe("Persisted provider-neutral task workflow artifacts to attach to the task"),
     room_id: z.string().optional().describe("Canonical room ID. Defaults to current room."),
     conversation_id: z.string().optional().describe("Optional conversation ID for per-conversation identity scoping."),
-}, async ({ task_id, status, assignee, pr_url, room_id, conversation_id }) => {
+}, async ({ task_id, status, assignee, pr_url, workflow_artifacts, room_id, conversation_id }) => {
     const targetRoomId = getTargetRoomId(room_id);
     const targetProjectId = getFallbackProjectId();
     if (!targetRoomId && !targetProjectId) {
@@ -1541,9 +1658,7 @@ server.tool("update_task", "Update a task's status or assignee. Status transitio
         };
     }
     try {
-        const identity = status === "assigned" && !assignee
-            ? (getConversationIdentity(conversation_id) ?? await ensureAgentIdentity())
-            : null;
+        const identity = getConversationIdentity(conversation_id) ?? await ensureAgentIdentity();
         const updated = await roomScopedApiCall({
             room_id: targetRoomId,
             project_id: targetProjectId,
@@ -1553,11 +1668,18 @@ server.tool("update_task", "Update a task's status or assignee. Status transitio
                 method: "PATCH",
                 body: JSON.stringify({
                     status,
-                    assignee: assignee ?? identity?.actor_label,
+                    assignee: status === "assigned" && !assignee ? identity.actor_label : assignee,
                     pr_url,
+                    workflow_artifacts,
                 }),
             },
         });
+        await syncRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity, {
+            status: deriveTaskPresenceStatus(status ?? null, getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity).status),
+            status_text: status
+                ? `${task_id} -> ${status}`
+                : getRememberedRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity).status_text,
+        });
         return {
             content: [
                 {
@@ -1565,7 +1687,7 @@ server.tool("update_task", "Update a task's status or assignee. Status transitio
                     text: JSON.stringify({
                         success: true,
                         task: updated,
-                        agent_identity: identity ? toPublicAgentIdentity(identity) : null,
+                        agent_identity: toPublicAgentIdentity(identity),
                     }, null, 2),
                 },
             ],
@@ -1765,11 +1887,15 @@ server.tool("send_message", "Send a message to a Let Agents Chat room.", {
         .optional()
         .describe("Deprecated override. Agent identity is resolved automatically on room entry."),
     text: z.string().describe("The message text to send"),
+    reply_to: z
+        .string()
+        .optional()
+        .describe("Optional message id to quote-reply to (for example `msg_42`)."),
     conversation_id: z
         .string()
         .optional()
         .describe("Optional conversation ID for per-conversation identity scoping."),
-}, async ({ room_id, sender: _sender, text, conversation_id }) => {
+}, async ({ room_id, sender: _sender, text, reply_to, conversation_id }) => {
     const targetRoomId = getTargetRoomId(room_id);
     const targetProjectId = getFallbackProjectId();
     if (!targetRoomId && !targetProjectId) {
@@ -1783,10 +1909,11 @@ server.tool("send_message", "Send a message to a Let Agents Chat room.", {
         project_path: (targetProjectId) => `/projects/${encodeURIComponent(targetProjectId)}/messages`,
         options: {
             method: "POST",
-            body: JSON.stringify({ sender: identity.actor_label, text }),
+            body: JSON.stringify({ sender: identity.actor_label, text, reply_to }),
         },
     });
     touchCurrentRoom(typeof message.id === "string" ? message.id : undefined);
+    await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity);
     return {
         content: [
             {
@@ -1831,6 +1958,7 @@ server.tool("read_messages", "Read all messages from a Let Agents Chat room.", {
             break;
         afterCursor = lastMsg.id;
     }
+    await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, await ensureAgentIdentity());
     const output = { messages: toAgentReadableMessages(allMessages) };
     if (roomIdFromResponse) {
         output[targetRoomId ? "room_id" : "project_id"] = roomIdFromResponse;
@@ -1860,6 +1988,8 @@ server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat roo
 }, async ({ room_id, after_message_id, timeout }) => {
     const targetRoomId = getTargetRoomId(room_id);
     const targetProjectId = getFallbackProjectId();
+    const identity = await ensureAgentIdentity();
+    await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity);
     const serverTimeout = Math.min(Math.max(timeout || DEFAULT_POLL_TIMEOUT_MS, 1000), MAX_POLL_TIMEOUT_MS);
     const clientTimeout = serverTimeout + 5000; // 5s buffer over server timeout
     const params = new URLSearchParams();
@@ -1905,6 +2035,7 @@ server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat roo
     if (targetRoomId) {
         touchRoomSession(targetRoomId, getLastMessageId(output));
     }
+    await heartbeatRoomPresence(targetRoomId ?? currentRoom?.room_id ?? null, identity);
     return {
         content: [
             {

package/dist/shared/agent-presence.js

@@ -0,0 +1,26 @@
+export const AGENT_PRESENCE_STATUSES = [
+    "idle",
+    "working",
+    "reviewing",
+    "blocked",
+];
+export const AGENT_PRESENCE_FRESHNESS = [
+    "active",
+    "stale",
+];
+export const ACTIVE_AGENT_PRESENCE_WINDOW_MS = 90_000;
+export function normalizeAgentPresenceStatus(value) {
+    const normalized = String(value || "").trim().toLowerCase();
+    return AGENT_PRESENCE_STATUSES.includes(normalized)
+        ? normalized
+        : null;
+}
+export function getAgentPresenceFreshness(lastHeartbeatAt, now = Date.now()) {
+    const heartbeatTime = new Date(lastHeartbeatAt).getTime();
+    if (!Number.isFinite(heartbeatTime)) {
+        return "stale";
+    }
+    return now - heartbeatTime <= ACTIVE_AGENT_PRESENCE_WINDOW_MS
+        ? "active"
+        : "stale";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "letagents",
-  "version": "0.12.1",
+  "version": "0.12.3",
   "description": "Let Agents Chat — MCP server for AI agent communication",
   "type": "module",
   "main": "dist/mcp/server.js",