opengate 0.2.9 → 0.2.12

package/dist/index.js

@@ -95,9 +95,11 @@ Before writing any code, gather all available context:
    - Read any returned entries \u2014 they contain architecture decisions, patterns, gotchas, and conventions for this project
    - Follow these conventions in your implementation
 
-### Phase 3: Plan & Announce
+### Phase 3: Plan & Announce (REQUIRED)
 4. **Post starting comment** \u2014 \`POST /api/tasks/${task.id}/activity\`
-   Body: \`{"content": "Starting work. Plan: <your plan informed by the context you gathered, 2-4 sentences>"}\`
+   Body: \`{"content": "## Starting Work\\n\\n**Plan:**\\n- <step 1>\\n- <step 2>\\n\\n**Context from KB:** <what you learned>\\n\\n**Concerns:** <any blockers or risks>"}\`
+
+   This comment is REQUIRED. Do not skip it.
    - Your plan should reflect what you learned from the knowledge base, existing comments, and dependencies
 
 ${workspaceBlock}
@@ -109,15 +111,32 @@ ${workspaceBlock}
    - Run the project's test suite and fix any failures
    - Commit your changes with a descriptive message referencing the task
 
-### Phase 6: Report & Complete
+### Phase 5.5: Knowledge Review (MANDATORY)
+Before completing the task, review your work and ask yourself:
+- Did I make an architecture or design decision? \u2192 Write it (category: "decision" or "architecture")
+- Did I encounter a non-obvious gotcha or bug? \u2192 Write it (category: "gotcha")
+- Did I establish or follow a pattern others should know? \u2192 Write it (category: "pattern")
+- Did I discover project structure or conventions? \u2192 Write it (category: "reference")
+
+If ANY of the above apply, write knowledge entries BEFORE completing:
+\`PUT /api/projects/${projectId}/knowledge/<descriptive-key>\`
+Body: \`{"title": "...", "content": "...", "tags": [...], "category": "..."}\`
+
+Key naming: use kebab-case descriptors, e.g. "auth-middleware-pattern", "db-migration-gotcha"
+
+IMPORTANT: Only write PROJECT-SCOPED knowledge. Do NOT write task-specific details.
+Good: "The API uses tower middleware for auth, not axum extractors"
+Bad: "Task T-123 required adding a new endpoint"
+
+If nothing new was discovered, that's fine \u2014 skip this phase.
+
+### Phase 6: Report & Complete (REQUIRED)
 8. **Post results comment** \u2014 \`POST /api/tasks/${task.id}/activity\`
-   Body: \`{"content": "<summary of what changed: files modified, approach taken, test results, commit hash>"}\`
+   Body: \`{"content": "## Results\\n\\n**Changes:**\\n- <file1>: <what changed>\\n- <file2>: <what changed>\\n\\n**Approach:** <brief explanation>\\n\\n**Tests:** <pass/fail status>\\n\\n**Commits:** <hash(es)>"}\`
 
-9. **Write knowledge** (if you discovered something worth sharing) \u2014 \`PUT /api/projects/${projectId}/knowledge/<key>\`
-   Body: \`{"title": "...", "content": "...", "tags": [...], "category": "<architecture|pattern|gotcha|decision|reference>"}\`
-   - Write entries for: architectural decisions you made, gotchas you encountered, patterns you established
+   This comment is REQUIRED. Do not skip it.
 
-10. **Complete the task** \u2014 \`POST /api/tasks/${task.id}/complete\`
+9. **Complete the task** \u2014 \`POST /api/tasks/${task.id}/complete\`
     Body: \`{"summary": "<what was done>", "output": {"branch": "<branch-name>", "commits": ["<hash>"]}}\`
 
 ## Handling Blockers
@@ -137,8 +156,64 @@ If a dependency is not yet done:
 - Respect existing patterns found in the knowledge base
 - Keep commits atomic and descriptive
 
+## Handling @-Mentions
+If you receive a \`task.comment_mention\` notification:
+1. Read the comment content from the notification body
+2. Fetch the full task context: \`GET /api/tasks/{taskId}\`
+3. Reason about what's being asked:
+   - If it's a question \u2192 post a reply comment with your answer
+   - If it's a request for changes \u2192 update task status to in_progress, make the changes, then re-complete
+   - If it's a simple acknowledgment \u2192 post a brief confirmation comment
+4. Always reply with a comment so the human knows you've seen it
+
 Now begin. Start with Phase 1: claim the task.`;
 }
+function buildMentionPrompt(taskId, commentBody, commentAuthor, openGateUrl, apiKey, project, projectsDir) {
+  let workspacePath = null;
+  if (project?.repo_url) {
+    const repoName = repoNameFromUrl(project.repo_url);
+    if (repoName && projectsDir) {
+      workspacePath = `${projectsDir}/${repoName}`;
+    }
+  }
+  const workspaceInstruction = workspacePath ? `Your project workspace is at: ${workspacePath}
+Change into this directory before any file operations.` : "";
+  return `You are an AI agent responding to an @-mention in a task comment.
+
+## API Access
+- Base URL: ${openGateUrl}
+- API Key: ${apiKey} (pass as Authorization: Bearer header)
+
+## Task
+- Task ID: ${taskId}
+${workspaceInstruction}
+
+## The Comment That Mentioned You
+**Author:** ${commentAuthor}
+**Content:**
+${commentBody}
+
+## Instructions
+
+1. Fetch the full task context: GET ${openGateUrl}/api/tasks/${taskId} (with Authorization header)
+2. Read the task description, status, and recent activity to understand context
+3. Reason about what the comment author is asking:
+   - If it's a **question** \u2192 post a reply comment with your answer
+   - If it's a **request for changes** \u2192 assess what's needed, make the changes if possible, and post a comment describing what you did
+   - If it's a **simple acknowledgment or FYI** \u2192 post a brief confirmation comment
+4. Post your reply: POST ${openGateUrl}/api/tasks/${taskId}/activity
+   Body: {"content": "<your reply>", "activity_type": "comment"}
+5. If you made code changes, post a summary of what changed
+
+## Rules
+- ALWAYS reply with a comment so the author knows you've seen the mention
+- Do NOT change the task status unless explicitly asked to
+- Do NOT try to claim or complete the task \u2014 you are just responding to a comment
+- Keep your response focused and concise
+- If you need to make code changes, work on a feature branch
+
+Begin by fetching the task context.`;
+}
 
 // src/spawner.ts
 async function spawnTaskSession(taskId, message, pluginCfg, openclawCfg) {
@@ -241,6 +316,10 @@ var TaskState = class {
   activeCount() {
     return Object.keys(this.data.spawned).length;
   }
+  /** Returns all task IDs currently in the spawned set. */
+  spawnedIds() {
+    return Object.keys(this.data.spawned);
+  }
 };
 
 // src/poller.ts
@@ -271,6 +350,34 @@ async function fetchInbox(url, apiKey) {
     inProgressTasks: body.in_progress_tasks ?? []
   };
 }
+async function fetchNotifications(url, apiKey) {
+  const resp = await fetch(`${url}/api/agents/me/notifications?unread=true`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!resp.ok) return [];
+  return await resp.json();
+}
+async function ackNotification(url, apiKey, notifId) {
+  await fetch(`${url}/api/agents/me/notifications/${notifId}/ack`, {
+    method: "POST",
+    headers: { Authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(1e4)
+  }).catch(() => {
+  });
+}
+async function fetchTaskById(url, apiKey, taskId) {
+  try {
+    const resp = await fetch(`${url}/api/tasks/${taskId}`, {
+      headers: { Authorization: `Bearer ${apiKey}` },
+      signal: AbortSignal.timeout(1e4)
+    });
+    if (!resp.ok) return null;
+    return await resp.json();
+  } catch {
+    return null;
+  }
+}
 var OpenGatePoller = class {
   constructor(pluginCfg, openclawCfg, logger, stateDir) {
     this.pluginCfg = pluginCfg;
@@ -300,14 +407,6 @@ var OpenGatePoller = class {
   }
   async poll() {
     if (!this.running) return;
-    const maxConcurrent = this.pluginCfg.maxConcurrent ?? 3;
-    const active = this.state.activeCount();
-    if (active >= maxConcurrent) {
-      this.logger.info(
-        `[opengate] At capacity (${active}/${maxConcurrent} active) \u2014 skipping poll`
-      );
-      return;
-    }
     let inbox;
     try {
       inbox = await fetchInbox(this.pluginCfg.url, this.pluginCfg.apiKey);
@@ -317,6 +416,18 @@ var OpenGatePoller = class {
       );
       return;
     }
+    const inboxTaskIds = /* @__PURE__ */ new Set([
+      ...inbox.todoTasks.map((t) => t.id),
+      ...inbox.inProgressTasks.map((t) => t.id)
+    ]);
+    for (const spawnedId of this.state.spawnedIds()) {
+      if (!inboxTaskIds.has(spawnedId)) {
+        this.logger.info(
+          `[opengate] Task ${spawnedId} no longer in inbox (completed/cancelled) \u2014 freeing slot`
+        );
+        this.state.remove(spawnedId);
+      }
+    }
     for (const task of inbox.inProgressTasks) {
       if (!this.state.isSpawned(task.id)) {
         this.logger.warn(
@@ -325,6 +436,15 @@ var OpenGatePoller = class {
         await this.releaseTask(task.id);
       }
     }
+    await this.handleNotifications();
+    const maxConcurrent = this.pluginCfg.maxConcurrent ?? 3;
+    const active = this.state.activeCount();
+    if (active >= maxConcurrent) {
+      this.logger.info(
+        `[opengate] At capacity (${active}/${maxConcurrent} active) \u2014 skipping poll`
+      );
+      return;
+    }
     if (inbox.todoTasks.length === 0) return;
     this.logger.info(`[opengate] Found ${inbox.todoTasks.length} todo task(s)`);
     for (const task of inbox.todoTasks) {
@@ -369,6 +489,68 @@ var OpenGatePoller = class {
       );
     }
   }
+  async handleNotifications() {
+    let notifications;
+    try {
+      notifications = await fetchNotifications(this.pluginCfg.url, this.pluginCfg.apiKey);
+    } catch {
+      return;
+    }
+    const mentionNotifs = notifications.filter(
+      (n) => n.event_type === "task.comment_mention" && n.task_id
+    );
+    for (const notif of mentionNotifs) {
+      if (!this.running) break;
+      const maxConcurrent = this.pluginCfg.maxConcurrent ?? 3;
+      if (this.state.activeCount() >= maxConcurrent) {
+        this.logger.info("[opengate] At capacity \u2014 deferring mention notifications");
+        break;
+      }
+      const mentionKey = `mention:${notif.id}`;
+      if (this.state.isSpawned(mentionKey)) continue;
+      await this.spawnMentionSession(notif);
+      await ackNotification(this.pluginCfg.url, this.pluginCfg.apiKey, notif.id);
+    }
+  }
+  async spawnMentionSession(notif) {
+    const taskId = notif.task_id;
+    this.logger.info(
+      `[opengate] Handling @-mention notification ${notif.id} on task ${taskId}`
+    );
+    const bodyText = notif.body ?? "";
+    const colonIdx = bodyText.indexOf(": ");
+    const author = colonIdx > 0 ? bodyText.slice(0, colonIdx) : "Someone";
+    const commentBody = colonIdx > 0 ? bodyText.slice(colonIdx + 2) : bodyText;
+    const task = await fetchTaskById(this.pluginCfg.url, this.pluginCfg.apiKey, taskId);
+    let project = null;
+    if (task?.project_id) {
+      project = await this.resolveProject(task.project_id);
+    }
+    const prompt = buildMentionPrompt(
+      taskId,
+      commentBody,
+      author,
+      this.pluginCfg.url,
+      this.pluginCfg.apiKey,
+      project,
+      this.pluginCfg.projectsDir
+    );
+    const result = await spawnTaskSession(
+      `mention-${notif.id}`,
+      prompt,
+      this.pluginCfg,
+      this.openclawCfg
+    );
+    if (!result.ok) {
+      this.logger.error(result.error);
+      return;
+    }
+    const mentionKey = `mention:${notif.id}`;
+    this.state.markSpawned(mentionKey, result.sessionKey);
+    this.logger.info(
+      `[opengate] Mention session spawned for notification ${notif.id} \u2192 ${result.sessionKey}`
+    );
+  }
   async spawnTask(task) {
     this.logger.info(`[opengate] Spawning session for task: "${task.title}" (${task.id})`);
     let project = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opengate",
-  "version": "0.2.9",
+  "version": "0.2.12",
   "description": "OpenGate task executor plugin for OpenClaw — polls assigned tasks and spawns isolated agent sessions",
   "type": "module",
   "main": "./dist/index.js",

package/skills/opengate/SKILL.md

@@ -95,14 +95,24 @@ Specifically look for:
 
 This enforces capacity limits and dependency checks. If claiming fails, read the error — you may have too many tasks in progress or a dependency is incomplete.
 
-### 5. Comment: Starting Work
+### 5. Comment: Starting Work (REQUIRED)
 
 `post_comment(task_id, content)` → Post a comment before you start
 
-Your starting comment should include:
-- What you understand the task requires
-- Your planned approach
-- Any concerns or assumptions
+Your starting comment MUST use this structure:
+```
+## Starting Work
+
+**Plan:**
+- <step 1>
+- <step 2>
+
+**Context from KB:** <what you learned>
+
+**Concerns:** <any blockers or risks>
+```
+
+Do NOT skip this comment. It is how the team tracks work and maintains visibility.
 
 ### 6. Do the Work
 
@@ -125,7 +135,28 @@ Store useful artifacts like:
 - Links to PRs, commits, or external resources
 - Feature branch name (e.g. `task/<task_id_short>`) for workspace continuity
 
-### 9. Complete the Task
+### 9. Post Results Comment (REQUIRED)
+
+`post_comment(task_id, content)` → Post a final results comment
+
+Your results comment MUST use this structure:
+```
+## Results
+
+**Changes:**
+- <file1>: <what changed>
+- <file2>: <what changed>
+
+**Approach:** <brief explanation>
+
+**Tests:** <pass/fail status>
+
+**Commits:** <hash(es)>
+```
+
+Do NOT skip this comment. It is critical for reviewers and future reference.
+
+### 10. Complete the Task
 
 `complete_task(task_id, summary, output)` → Finish the task with a summary and structured output
 
@@ -181,19 +212,28 @@ If a dependency is no longer needed:
 - **References** — links, docs, external resources
 - **General** — anything else worth knowing
 
-### Writing Knowledge
+### Writing Knowledge (MANDATORY Review)
 
-When you discover something important during work, **write it back**:
+Before completing any task, review your work with this checklist:
+
+- [ ] Did I make an architecture or design decision? → Write it (category: `decision` or `architecture`)
+- [ ] Did I encounter a non-obvious gotcha or bug? → Write it (category: `gotcha`)
+- [ ] Did I establish or follow a pattern others should know? → Write it (category: `pattern`)
+- [ ] Did I discover project structure or conventions? → Write it (category: `reference`)
+
+If ANY apply, write knowledge entries BEFORE completing:
 
 `set_knowledge(project_id, key, title, content, tags, category)`
 
-Write knowledge when you:
-- Discover a non-obvious pattern or constraint
-- Make an architecture decision that affects future work
-- Find a gotcha that would trip up other agents
-- Establish a convention through your implementation
+Key naming: use kebab-case descriptors, e.g. `auth-middleware-pattern`, `db-migration-gotcha`
+
+**IMPORTANT: Only write PROJECT-SCOPED knowledge.** Do NOT write task-specific details.
+- Good: "The API uses tower middleware for auth, not axum extractors"
+- Bad: "Task T-123 required adding a new endpoint"
+
+If nothing new was discovered, that's fine — skip writing.
 
-Categories: `architecture`, `convention`, `gotcha`, `reference`, `general`
+Categories: `architecture`, `pattern`, `gotcha`, `decision`, `reference`
 
 ## Agent Profile