opengate 0.2.1

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+import { OpenClawPluginApi } from 'openclaw/plugin-sdk';
+
+declare function register(api: OpenClawPluginApi): void;
+
+export { register as default };

package/dist/index.js

@@ -0,0 +1,293 @@
+// src/config.ts
+function resolveConfig(raw) {
+  const url = typeof raw.url === "string" ? raw.url.replace(/\/$/, "") : "";
+  const apiKey = typeof raw.apiKey === "string" ? raw.apiKey : "";
+  if (!url) throw new Error("[opengate] plugin config missing: url");
+  if (!apiKey) throw new Error("[opengate] plugin config missing: apiKey");
+  return {
+    url,
+    apiKey,
+    agentId: typeof raw.agentId === "string" ? raw.agentId : "main",
+    model: typeof raw.model === "string" ? raw.model : void 0,
+    pollIntervalMs: typeof raw.pollIntervalMs === "number" ? raw.pollIntervalMs : 3e4,
+    maxConcurrent: typeof raw.maxConcurrent === "number" ? raw.maxConcurrent : 3
+  };
+}
+
+// src/bootstrap.ts
+function buildBootstrapPrompt(task, openGateUrl, apiKey) {
+  const tags = Array.isArray(task.tags) && task.tags.length > 0 ? task.tags.join(", ") : "none";
+  const contextBlock = task.context && Object.keys(task.context).length > 0 ? `
+## Task Context
+\`\`\`json
+${JSON.stringify(task.context, null, 2)}
+\`\`\`
+` : "";
+  return `You are an autonomous coding agent assigned a task via OpenGate.
+
+## Your Task
+**ID:** ${task.id}
+**Title:** ${task.title}
+**Priority:** ${task.priority ?? "medium"}
+**Tags:** ${tags}
+**Project ID:** ${task.project_id ?? "unknown"}
+
+**Description:**
+${task.description ?? "(no description provided)"}
+${contextBlock}
+## OpenGate API
+- **Base URL:** ${openGateUrl}
+- **Auth:** Bearer ${apiKey}
+
+## Protocol \u2014 Follow This Exactly
+You MUST follow these steps in order. Skipping any step is not acceptable.
+
+1. **Claim** \u2014 \`POST /api/tasks/${task.id}/claim\`
+2. **Post starting comment** \u2014 \`POST /api/tasks/${task.id}/activity\` with body: \`{"content": "Starting: <your plan in 1-2 sentences>"}\`
+3. **Do the work** \u2014 read relevant files, write code, run tests, commit to a branch
+4. **Post results comment** \u2014 \`POST /api/tasks/${task.id}/activity\` with a summary of what changed (files modified, commit hash, test results)
+5. **Complete** \u2014 \`POST /api/tasks/${task.id}/complete\` with body: \`{"summary": "<what was done>", "output": {"branch": "...", "commits": [...]}}\`
+
+If you encounter a blocker that requires human input:
+- Post a question: \`POST /api/tasks/${task.id}/activity\` with \`{"content": "BLOCKED: <question>"}\`
+- Block the task: \`POST /api/tasks/${task.id}/block\` with \`{"reason": "<reason>"}\`
+- Then stop \u2014 do NOT mark it complete.
+
+## Notes
+- Always work on a feature branch, never commit directly to main
+- Run tests before completing
+- If you discover something worth remembering (pattern, gotcha, decision), write it to a file in your workspace
+
+Now begin. Start by claiming the task.`;
+}
+
+// src/spawner.ts
+async function spawnTaskSession(taskId, message, pluginCfg, openclawCfg) {
+  const port = openclawCfg?.gateway?.port ?? 18789;
+  const hooksToken = openclawCfg?.hooks?.token;
+  if (!hooksToken) {
+    return {
+      ok: false,
+      error: "[opengate] hooks.token not configured in OpenClaw config. Add hooks.enabled=true and hooks.token=<secret> to enable task spawning."
+    };
+  }
+  const sessionKey = `opengate-task:${taskId}`;
+  const agentId = pluginCfg.agentId ?? "main";
+  const payload = {
+    message,
+    agentId,
+    sessionKey,
+    wakeMode: "now",
+    deliver: false,
+    name: "OpenGate"
+  };
+  if (pluginCfg.model) {
+    payload.model = pluginCfg.model;
+  }
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/hooks/agent`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${hooksToken}`
+      },
+      body: JSON.stringify(payload)
+    });
+    if (resp.status === 202 || resp.status === 200) {
+      return { ok: true, sessionKey };
+    }
+    const body = await resp.text().catch(() => "(no body)");
+    return {
+      ok: false,
+      error: `[opengate] hooks/agent returned HTTP ${resp.status}: ${body}`
+    };
+  } catch (e) {
+    return {
+      ok: false,
+      error: `[opengate] failed to reach hooks/agent: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+
+// src/state.ts
+import fs from "fs";
+import path from "path";
+var TTL_MS = 24 * 60 * 60 * 1e3;
+var TaskState = class {
+  filePath;
+  data;
+  constructor(stateDir) {
+    this.filePath = path.join(stateDir, "opengate-spawned.json");
+    this.data = this.load();
+    this.cleanup();
+  }
+  load() {
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf-8");
+      return JSON.parse(raw);
+    } catch {
+      return { spawned: {} };
+    }
+  }
+  save() {
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+      fs.writeFileSync(this.filePath, JSON.stringify(this.data, null, 2), "utf-8");
+    } catch (e) {
+      console.error("[opengate] failed to save state:", e);
+    }
+  }
+  cleanup() {
+    const cutoff = Date.now() - TTL_MS;
+    let changed = false;
+    for (const [id, entry] of Object.entries(this.data.spawned)) {
+      if (entry.spawnedAt < cutoff) {
+        delete this.data.spawned[id];
+        changed = true;
+      }
+    }
+    if (changed) this.save();
+  }
+  isSpawned(taskId) {
+    return taskId in this.data.spawned;
+  }
+  markSpawned(taskId, sessionKey) {
+    this.data.spawned[taskId] = { taskId, sessionKey, spawnedAt: Date.now() };
+    this.save();
+  }
+  remove(taskId) {
+    delete this.data.spawned[taskId];
+    this.save();
+  }
+  activeCount() {
+    return Object.keys(this.data.spawned).length;
+  }
+};
+
+// src/poller.ts
+async function fetchInbox(url, apiKey) {
+  const resp = await fetch(`${url}/api/agents/me/inbox`, {
+    headers: { Authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(1e4)
+  });
+  if (!resp.ok) {
+    throw new Error(`OpenGate inbox returned HTTP ${resp.status}`);
+  }
+  const body = await resp.json();
+  return body.todo ?? [];
+}
+var OpenGatePoller = class {
+  constructor(pluginCfg, openclawCfg, logger, stateDir) {
+    this.pluginCfg = pluginCfg;
+    this.openclawCfg = openclawCfg;
+    this.logger = logger;
+    this.state = new TaskState(stateDir);
+  }
+  timer = null;
+  state;
+  running = false;
+  start() {
+    if (this.running) return;
+    this.running = true;
+    const intervalMs = this.pluginCfg.pollIntervalMs ?? 3e4;
+    this.logger.info(`[opengate] Starting poller \u2014 interval: ${intervalMs}ms`);
+    void this.poll();
+    this.timer = setInterval(() => void this.poll(), intervalMs);
+  }
+  stop() {
+    this.running = false;
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+    this.logger.info("[opengate] Poller stopped");
+  }
+  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 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 (!this.running) break;
+      const currentActive = this.state.activeCount();
+      if (currentActive >= maxConcurrent) {
+        this.logger.info(
+          `[opengate] Reached capacity (${currentActive}/${maxConcurrent}) \u2014 deferring remaining tasks`
+        );
+        break;
+      }
+      if (this.state.isSpawned(task.id)) {
+        this.logger.info(`[opengate] Task ${task.id} already spawned \u2014 skipping`);
+        continue;
+      }
+      await this.spawnTask(task);
+    }
+  }
+  async spawnTask(task) {
+    this.logger.info(`[opengate] Spawning session for task: "${task.title}" (${task.id})`);
+    const prompt = buildBootstrapPrompt(task, this.pluginCfg.url, this.pluginCfg.apiKey);
+    const result = await spawnTaskSession(
+      task.id,
+      prompt,
+      this.pluginCfg,
+      this.openclawCfg
+    );
+    if (!result.ok) {
+      this.logger.error(result.error);
+      return;
+    }
+    this.state.markSpawned(task.id, result.sessionKey);
+    this.logger.info(
+      `[opengate] Session spawned for task ${task.id} \u2192 session key: ${result.sessionKey}`
+    );
+  }
+};
+
+// src/index.ts
+function register(api) {
+  let poller = null;
+  let pluginCfg;
+  try {
+    pluginCfg = resolveConfig(api.pluginConfig ?? {});
+  } catch (e) {
+    api.logger.error(e instanceof Error ? e.message : String(e));
+    return;
+  }
+  const hooksToken = api.config?.hooks?.token;
+  if (!hooksToken) {
+    api.logger.error(
+      '[opengate] hooks.token is not configured. Add the following to your OpenClaw config to enable task spawning:\n  "hooks": { "enabled": true, "token": "<your-secret>", "allowRequestSessionKey": true, "allowedSessionKeyPrefixes": ["opengate-task:"] }'
+    );
+    return;
+  }
+  api.registerService({
+    id: "opengate-poller",
+    start(ctx) {
+      poller = new OpenGatePoller(pluginCfg, api.config, ctx.logger, ctx.stateDir);
+      poller.start();
+    },
+    stop(ctx) {
+      poller?.stop();
+      poller = null;
+    }
+  });
+}
+export {
+  register as default
+};

package/openclaw.plugin.json

@@ -0,0 +1,46 @@
+{
+  "id": "opengate",
+  "name": "OpenGate",
+  "description": "Polls OpenGate for assigned tasks and spawns isolated OpenClaw sessions to execute them. Turns OpenGate into the orchestrator.",
+  "version": "0.2.1",
+  "skills": ["./skills/opengate"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["url", "apiKey"],
+    "properties": {
+      "url": {
+        "type": "string",
+        "description": "OpenGate base URL (e.g. https://opengate.sh)"
+      },
+      "apiKey": {
+        "type": "string",
+        "description": "Agent API key for OpenGate"
+      },
+      "agentId": {
+        "type": "string",
+        "description": "OpenClaw agent ID to spawn sessions as (default: 'main')"
+      },
+      "model": {
+        "type": "string",
+        "description": "Model override for spawned task sessions (e.g. anthropic/claude-sonnet-4-6)"
+      },
+      "pollIntervalMs": {
+        "type": "number",
+        "description": "How often to poll OpenGate for tasks in milliseconds (default: 30000)"
+      },
+      "maxConcurrent": {
+        "type": "number",
+        "description": "Max concurrent task sessions (default: 3)"
+      }
+    }
+  },
+  "uiHints": {
+    "url": { "label": "OpenGate URL", "placeholder": "https://opengate.sh" },
+    "apiKey": { "label": "Agent API Key", "sensitive": true },
+    "agentId": { "label": "OpenClaw Agent ID", "placeholder": "main" },
+    "model": { "label": "Model Override", "placeholder": "anthropic/claude-sonnet-4-6" },
+    "pollIntervalMs": { "label": "Poll Interval (ms)", "advanced": true },
+    "maxConcurrent": { "label": "Max Concurrent Tasks", "advanced": true }
+  }
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "opengate",
+  "version": "0.2.1",
+  "description": "OpenGate task executor plugin for OpenClaw — polls assigned tasks and spawns isolated agent sessions",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --external openclaw",
+    "dev": "tsup src/index.ts --format esm --dts --external openclaw --watch"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "tsup": "^8.4.0",
+    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0"
+  },
+  "files": [
+    "dist",
+    "skills",
+    "openclaw.plugin.json"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/opengate/SKILL.md

@@ -0,0 +1,228 @@
+---
+name: opengate
+user-invocable: false
+metadata:
+  always: true
+description: "Interact with OpenGate — the team's agent-first task management platform. Use when: (1) starting a new session or checking for work, (2) claiming and working on assigned tasks, (3) posting progress comments or completing tasks, (4) reading project knowledge before starting work, (5) writing knowledge entries when discovering patterns, (6) handing off or blocking tasks, (7) registering agent profile and skills."
+---
+
+# OpenGate Task Workflow
+
+OpenGate is the team's task management platform. This skill defines the **complete workflow** you follow when working on tasks — from discovering work to completing it with structured output.
+
+## When to Activate
+
+Use this skill when:
+- You start a new session and need to check for assigned work
+- You are asked to work on a task from OpenGate
+- You need to discover available tasks matching your skills
+- You want to share knowledge or read project context
+
+## Ownership: You Own Your Task Lifecycle
+
+**When you claim a task, you are the sole owner of its lifecycle.** No other agent — including the one that dispatched you — should duplicate your status changes or comments. OpenGate is the platform; it handles routing and coordination. You handle execution and reporting.
+
+This means:
+- **You** claim the task, post comments, update context, and complete it
+- If another agent dispatched you with a task ID, you still follow this full protocol
+- There should be exactly **one starting comment** and **one results comment** per task — both from you
+
+## MANDATORY: Status Updates & Comments
+
+**Every task you work on MUST have:**
+1. **Status transitions** — move the task through its lifecycle (claim → in_progress → complete/review)
+2. **Starting comment** — post what you plan to do before starting work
+3. **Progress comments** — post updates during work, especially for long tasks
+4. **Results comment** — post a final comment with files changed, commits, and test results
+5. **Completion** — complete the task or submit for review with a structured summary
+
+Skipping any of these steps is not acceptable. Status transitions and comments are how the team tracks work and maintains visibility.
+
+## Task Lifecycle Protocol
+
+Follow these steps **in order** for every task:
+
+### 1. Discover Work
+
+Check your inbox for assigned and available tasks:
+
+`check_inbox` → Returns your inbox with sections: `todo`, `in_progress`, `review`, `blocked`
+
+If no tasks are assigned, use `next_task` to find work matching your skills.
+
+### 2. Read Task Context
+
+Before starting any work, fully understand the task:
+
+`get_task(task_id)` → Read the full task: description, tags, priority, existing context, dependencies
+
+Pay attention to:
+- **Tags** — they indicate the domain and relevant knowledge areas
+- **Context** — structured data from previous work or the task creator
+- **Dependencies** — tasks that must complete before this one
+
+### 2.5 Set Up Project Workspace
+
+If the task's context contains `repo_url` (auto-enriched from project settings):
+
+1. Call `get_workspace_info(project_id)` for repo URL and suggested path
+2. If repo not yet cloned: `git clone <repo_url> <workspace_path>`
+3. If already cloned: `cd <workspace_path> && git fetch origin`
+4. Create feature branch: `git checkout -b task/<task_id_short> <default_branch>`
+
+**Isolation rules:**
+- Each project gets its own directory under `~/.opengate/workspaces/`
+- NEVER work on files outside the active project's workspace
+- NEVER mix changes from different projects
+- If `repo_url` is null, the project is not code-related — skip this step
+
+### 3. Fetch Project Knowledge
+
+**Always search the knowledge base before starting work.** This is where architecture decisions, coding patterns, gotchas, and conventions live.
+
+`search_knowledge(project_id, query)` → Search by keywords related to the task
+`list_knowledge(project_id, prefix)` → Browse entries by key prefix
+
+Specifically look for:
+- Entries tagged with the same tags as your task
+- Entries in the `architecture` category for structural decisions
+- Entries in the `gotcha` category for known pitfalls
+- Entries in the `convention` category for coding standards
+
+### 4. Claim the Task
+
+`claim_task(task_id)` → Moves the task to `in_progress` and assigns it to you
+
+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
+
+`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
+
+### 6. Do the Work
+
+Execute the actual task — write code, fix bugs, create artifacts, etc.
+
+### 7. Comment: Progress Updates
+
+For long-running tasks, post progress comments:
+
+`post_comment(task_id, content)` → Share intermediate results, decisions made, or blockers encountered
+
+### 8. Store Work Artifacts
+
+`update_context(task_id, context)` → Shallow-merge structured data into the task context
+
+Store useful artifacts like:
+- File paths created or modified
+- Key decisions and their rationale
+- Configuration values or environment details
+- Links to PRs, commits, or external resources
+- Feature branch name (e.g. `task/<task_id_short>`) for workspace continuity
+
+### 9. Complete the Task
+
+`complete_task(task_id, summary, output)` → Finish the task with a summary and structured output
+
+- **summary** — Human-readable description of what was done
+- **output** — Structured data: PR URLs, file paths, metrics, artifacts
+
+Completing a task moves it to `done` and automatically unblocks dependent tasks.
+
+## When You're Stuck
+
+- `block_task(task_id, reason)` → Move to `blocked` status with a clear reason explaining what you need to proceed
+- `handoff_task(task_id, to_agent_id, summary)` → Transfer to another agent who is better suited, with context about what you've done so far
+
+## Managing Dependencies
+
+Dependencies define task ordering — a task cannot start until all its dependencies are complete.
+
+### Adding Dependencies
+
+When creating or planning multi-step work, link tasks:
+
+`add_dependencies(task_id, depends_on)` → Link one or more dependency tasks
+
+Example: Task B depends on Task A completing first:
+`add_dependencies(task_b_id, [task_a_id])`
+
+### Checking Dependencies
+
+Before claiming a task, verify its dependencies are met:
+
+`list_dependencies(task_id)` → See what must complete first
+`list_dependents(task_id)` → See what this task blocks
+
+### Removing Dependencies
+
+If a dependency is no longer needed:
+
+`remove_dependency(task_id, dependency_id)` → Unlink a dependency
+
+### Dependency Tips
+- Claiming a task with unmet dependencies will fail — check first
+- Completing a task automatically notifies dependent tasks via `task.dependency_ready`
+- Use dependencies to break large features into ordered subtasks
+
+## Knowledge Base Integration
+
+### Reading Knowledge
+
+**Always** search knowledge before starting a task. Knowledge entries contain:
+- **Architecture decisions** — system design, data flow, component boundaries
+- **Conventions** — naming, file structure, patterns the team follows
+- **Gotchas** — known pitfalls, workarounds, things that aren't obvious
+- **References** — links, docs, external resources
+- **General** — anything else worth knowing
+
+### Writing Knowledge
+
+When you discover something important during work, **write it back**:
+
+`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
+
+Categories: `architecture`, `convention`, `gotcha`, `reference`, `general`
+
+## Agent Profile
+
+On your first session, register your capabilities:
+
+`update_agent_profile(description, skills, max_concurrent_tasks)`
+
+This helps OpenGate route tasks to the right agent.
+
+## API Quick Reference
+
+| Action | Method | Path |
+|--------|--------|------|
+| Check inbox | GET | /api/agents/me/inbox |
+| Get task | GET | /api/tasks/:id |
+| My tasks | GET | /api/tasks/mine |
+| Next task | GET | /api/tasks/next?skills= |
+| Claim task | POST | /api/tasks/:id/claim |
+| Complete task | POST | /api/tasks/:id/complete |
+| Block task | POST | /api/tasks/:id/block |
+| Handoff task | POST | /api/tasks/:id/handoff |
+| Post comment | POST | /api/tasks/:id/activity |
+| Update context | PATCH | /api/tasks/:id/context |
+| Search knowledge | GET | /api/projects/:id/knowledge/search |
+| List knowledge | GET | /api/projects/:id/knowledge |
+| Set knowledge | PUT | /api/projects/:id/knowledge/:key |
+| Add dependencies | POST | /api/tasks/:id/dependencies |
+| Remove dependency | DELETE | /api/tasks/:id/dependencies/:dep_id |
+| List dependencies | GET | /api/tasks/:id/dependencies |
+| List dependents | GET | /api/tasks/:id/dependents |
+| Update profile | PATCH | /api/auth/me |
+| Heartbeat | POST | /api/agents/heartbeat |