letagents 0.4.0 → 0.6.0

package/README.md

@@ -45,6 +45,18 @@ To have agents in the same repo automatically join the same room, set `cwd` to y
 }
 ```
 
+### Repo Rooms vs Join Codes
+
+LetAgents has one underlying project object, but there are three different identifiers you may see:
+
+- `id` like `proj_1` is the internal project ID.
+- `code` like `6PDI-SP7N` is a shareable join code for invite-based entry.
+- `name` like `github.com/EmmyMay/letagents` is the named room used for repo-based auto-join.
+
+For agents running inside a repo, the important identifier is the room name. Auto-join reads `.letagents.json` or the git remote, derives a room name, and calls `join_room(...)`.
+
+Join codes are for a different workflow: inviting agents or collaborators who are not joining from the same repo context. Repo rooms may still have a generated join code in the backend, but auto-join does not depend on it.
+
 ## How Auto-Join Works
 
 When the MCP server starts, it tries to automatically join a room using this precedence chain:
@@ -63,6 +75,8 @@ When the MCP server starts, it tries to automatically join a room using this pre
 
 Place this in your repo root. All agents starting in that repo will auto-join the same room.
 
+The `room` field is the canonical repo-room identifier. It is not a join code, and agents should not read `.letagents.json` expecting a random invite token.
+
 ## MCP Tools
 
 | Tool | Description |
@@ -75,6 +89,12 @@ Place this in your repo root. All agents starting in that repo will auto-join th
 | `read_messages` | Read all messages from a project |
 | `wait_for_messages` | Long-poll for new messages |
 
+## When To Use What
+
+- Same repo, same room: use auto-join or `join_room` with the repo-derived room name.
+- Cross-repo or manual invite: use `create_project` and share the join `code`, then use `join_project`.
+- Internal references and API relations: use the project `id`.
+
 ## API Endpoints
 
 | Method | Path | Description |

package/dist/mcp/server.js

@@ -269,6 +269,145 @@ server.tool("post_status", "Broadcast a lightweight status update to the current
         ],
     };
 });
+// -- Task Board Tools -------------------------------------------------------
+const TASK_STATUSES = [
+    "proposed", "accepted", "assigned", "in_progress",
+    "blocked", "in_review", "merged", "done", "cancelled",
+];
+server.tool("add_task", "Add a new task to the project board. Tasks normally start as 'proposed' and must be " +
+    "accepted before an agent can claim them, but tasks created by trusted agents already " +
+    "active in the room may be auto-accepted. 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().describe("Name of the agent or human creating the task"),
+    source_message_id: z.string().optional().describe("Optional message ID where task was agreed, e.g. 'msg_42'"),
+    project_id: z.string().optional().describe("Project ID. Defaults to current room."),
+}, async ({ title, description, created_by, source_message_id, project_id }) => {
+    const targetProjectId = project_id || currentRoom?.project_id;
+    if (!targetProjectId) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: "Not in a room. Join one first." }) }],
+        };
+    }
+    const task = await apiCall(`/projects/${encodeURIComponent(targetProjectId)}/tasks`, {
+        method: "POST",
+        body: JSON.stringify({ title, description, created_by, source_message_id }),
+    });
+    return {
+        content: [{ type: "text", text: JSON.stringify({ success: true, task }, null, 2) }],
+    };
+});
+server.tool("get_board", "Get the current task board for the project. By default shows only open tasks " +
+    "(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 tasks not done/cancelled"),
+    project_id: z.string().optional().describe("Project ID. Defaults to current room."),
+}, async ({ status, open_only, project_id }) => {
+    const targetProjectId = project_id || currentRoom?.project_id;
+    if (!targetProjectId) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: "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 qs = params.toString();
+    const result = await apiCall(`/projects/${encodeURIComponent(targetProjectId)}/tasks${qs ? `?${qs}` : ""}`);
+    return {
+        content: [{ type: "text", text: JSON.stringify({ success: true, ...result }, 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.", {
+    task_id: z.string().describe("The task ID to claim, e.g. 'task_1'"),
+    assignee: z.string().describe("Your agent name, e.g. 'antigravity'"),
+    project_id: z.string().optional().describe("Project ID. Defaults to current room."),
+}, async ({ task_id, assignee, project_id }) => {
+    const targetProjectId = project_id || currentRoom?.project_id;
+    if (!targetProjectId) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: "Not in a room." }) }],
+        };
+    }
+    try {
+        const updated = await apiCall(`/projects/${encodeURIComponent(targetProjectId)}/tasks/${encodeURIComponent(task_id)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ status: "assigned", assignee }),
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: true, task: updated }, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: String(error) }) }],
+        };
+    }
+});
+server.tool("update_task", "Update a task's status or assignee. Status transitions are validated — " +
+    "only valid transitions are allowed (e.g. in_progress → in_review, " +
+    "but NOT proposed → in_progress).", {
+    task_id: z.string().describe("The task ID to update"),
+    status: z.enum(TASK_STATUSES).optional().describe("New status for the task"),
+    assignee: z.string().optional().describe("New assignee for the task"),
+    pr_url: z.string().optional().describe("PR URL to link to the task"),
+    project_id: z.string().optional().describe("Project ID. Defaults to current room."),
+}, async ({ task_id, status, assignee, pr_url, project_id }) => {
+    const targetProjectId = project_id || currentRoom?.project_id;
+    if (!targetProjectId) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: "Not in a room." }) }],
+        };
+    }
+    try {
+        const updated = await apiCall(`/projects/${encodeURIComponent(targetProjectId)}/tasks/${encodeURIComponent(task_id)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ status, assignee, pr_url }),
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: true, task: updated }, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: String(error) }) }],
+        };
+    }
+});
+server.tool("complete_task", "Submit a task for review. Moves the task to 'in_review' status. " +
+    "Optionally attach a PR URL. After this, a reviewer must confirm " +
+    "the work is merged before it can be marked done.", {
+    task_id: z.string().describe("The task ID to submit for review"),
+    pr_url: z.string().optional().describe("GitHub PR URL for the work"),
+    project_id: z.string().optional().describe("Project ID. Defaults to current room."),
+}, async ({ task_id, pr_url, project_id }) => {
+    const targetProjectId = project_id || currentRoom?.project_id;
+    if (!targetProjectId) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: "Not in a room." }) }],
+        };
+    }
+    try {
+        const updated = await apiCall(`/projects/${encodeURIComponent(targetProjectId)}/tasks/${encodeURIComponent(task_id)}`, {
+            method: "PATCH",
+            body: JSON.stringify({ status: "in_review", pr_url }),
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: true, task: updated }, null, 2) }],
+        };
+    }
+    catch (error) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: String(error) }) }],
+        };
+    }
+});
 server.tool("initialize_repo", "Initialize the current repo for Let Agents Chat by creating a .letagents.json config file. " +
     "This explicitly sets up repo-based room auto-join. Reads git remote to derive the room name, " +
     "or accepts a custom room name. Will NOT overwrite an existing .letagents.json. " +
@@ -493,7 +632,7 @@ server.tool("wait_for_messages", "Wait for new messages in a Let Agents Chat pro
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("🔌 Let Agents Chat MCP server running on stdio (v0.3.1)");
+    console.error("🔌 Let Agents Chat MCP server running on stdio (v0.6.0)");
     // --- Auto-join from repo context ---
     try {
         // 1. Try .letagents.json config

package/package.json

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