opengate 0.2.8 → 0.2.11

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,6 +156,16 @@ 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.`;
 }
 
@@ -241,6 +270,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
@@ -266,7 +299,10 @@ async function fetchInbox(url, apiKey) {
     throw new Error(`OpenGate inbox returned HTTP ${resp.status}`);
   }
   const body = await resp.json();
-  return body.todo_tasks ?? [];
+  return {
+    todoTasks: body.todo_tasks ?? [],
+    inProgressTasks: body.in_progress_tasks ?? []
+  };
 }
 var OpenGatePoller = class {
   constructor(pluginCfg, openclawCfg, logger, stateDir) {
@@ -297,6 +333,35 @@ var OpenGatePoller = class {
   }
   async poll() {
     if (!this.running) return;
+    let inbox;
+    try {
+      inbox = await fetchInbox(this.pluginCfg.url, this.pluginCfg.apiKey);
+    } catch (e) {
+      this.logger.warn(
+        `[opengate] Failed to fetch inbox: ${e instanceof Error ? e.message : String(e)}`
+      );
+      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(
+          `[opengate] Orphaned in_progress task "${task.title}" (${task.id}) \u2014 releasing back to todo`
+        );
+        await this.releaseTask(task.id);
+      }
+    }
     const maxConcurrent = this.pluginCfg.maxConcurrent ?? 3;
     const active = this.state.activeCount();
     if (active >= maxConcurrent) {
@@ -305,18 +370,9 @@ var OpenGatePoller = class {
       );
       return;
     }
-    let tasks;
-    try {
-      tasks = await fetchInbox(this.pluginCfg.url, this.pluginCfg.apiKey);
-    } catch (e) {
-      this.logger.warn(
-        `[opengate] Failed to fetch inbox: ${e instanceof Error ? e.message : String(e)}`
-      );
-      return;
-    }
-    if (tasks.length === 0) return;
-    this.logger.info(`[opengate] Found ${tasks.length} todo task(s)`);
-    for (const task of tasks) {
+    if (inbox.todoTasks.length === 0) return;
+    this.logger.info(`[opengate] Found ${inbox.todoTasks.length} todo task(s)`);
+    for (const task of inbox.todoTasks) {
       if (!this.running) break;
       const currentActive = this.state.activeCount();
       if (currentActive >= maxConcurrent) {
@@ -339,6 +395,25 @@ var OpenGatePoller = class {
     if (project) this.projectCache.set(projectId, project);
     return project;
   }
+  async releaseTask(taskId) {
+    try {
+      const resp = await fetch(
+        `${this.pluginCfg.url}/api/tasks/${taskId}/release`,
+        {
+          method: "POST",
+          headers: { Authorization: `Bearer ${this.pluginCfg.apiKey}` },
+          signal: AbortSignal.timeout(1e4)
+        }
+      );
+      if (!resp.ok) {
+        this.logger.warn(`[opengate] Failed to release task ${taskId}: HTTP ${resp.status}`);
+      }
+    } catch (e) {
+      this.logger.warn(
+        `[opengate] Failed to release task ${taskId}: ${e instanceof Error ? e.message : String(e)}`
+      );
+    }
+  }
   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.8",
+  "version": "0.2.11",
   "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