overlord-cli 0.2605101225.0

package/plugins/cursor/scripts/overlord-mcp.mjs

@@ -0,0 +1,150 @@
+#!/usr/bin/env node
+
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const execFileAsync = promisify(execFile);
+const OVLD_BIN = process.env.OVLD_BIN?.trim() || 'ovld';
+const PROTOCOL_VERSION = '2025-06-18';
+let buffer = Buffer.alloc(0);
+
+function send(message) {
+  const json = JSON.stringify(message);
+  const body = Buffer.from(json, 'utf8');
+  const header = Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'utf8');
+  process.stdout.write(Buffer.concat([header, body]));
+}
+
+function parseMessages(chunk) {
+  buffer = Buffer.concat([buffer, chunk]);
+  const messages = [];
+  while (true) {
+    const headerEnd = buffer.indexOf('\r\n\r\n');
+    if (headerEnd === -1) break;
+    const headerText = buffer.subarray(0, headerEnd).toString('utf8');
+    const lengthMatch = headerText.match(/Content-Length:\s*(\d+)/i);
+    if (!lengthMatch) throw new Error('Missing Content-Length header');
+    const contentLength = Number(lengthMatch[1]);
+    const totalLength = headerEnd + 4 + contentLength;
+    if (buffer.length < totalLength) break;
+    const body = buffer.subarray(headerEnd + 4, totalLength).toString('utf8');
+    buffer = buffer.subarray(totalLength);
+    messages.push(JSON.parse(body));
+  }
+  return messages;
+}
+
+async function runProtocol(subcommand, args = {}) {
+  const flags = Object.entries(args).flatMap(([key, value]) => {
+    if (value === undefined || value === null) return [];
+    if (typeof value === 'boolean') return value ? [`--${key}`] : [];
+    if (Array.isArray(value)) return [`--${key}`, JSON.stringify(value)];
+    if (typeof value === 'object') return [`--${key}-json`, JSON.stringify(value)];
+    return [`--${key}`, String(value)];
+  });
+
+  try {
+    const { stdout } = await execFileAsync(OVLD_BIN, ['protocol', subcommand, ...flags], {
+      env: {
+        ...process.env,
+        AGENT_IDENTIFIER: process.env.AGENT_IDENTIFIER ?? 'cursor-overlord-plugin'
+      },
+      maxBuffer: 20 * 1024 * 1024
+    });
+    const data = stdout.trim() ? JSON.parse(stdout) : {};
+    return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }], structuredContent: data };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: 'text', text: message }], isError: true };
+  }
+}
+
+process.stdin.on('data', async chunk => {
+  for (const message of parseMessages(chunk)) {
+    if (!message || typeof message !== 'object' || !('id' in message)) continue;
+    if (message.method === 'initialize') {
+      send({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          protocolVersion: PROTOCOL_VERSION,
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'overlord-cursor', version: '0.1.0' }
+        }
+      });
+      continue;
+    }
+    if (message.method === 'tools/list') {
+      send({
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          tools: [
+            {
+              name: 'attach_ticket',
+              description: 'Attach to an Overlord ticket.',
+              inputSchema: { type: 'object', properties: { ticket_id: { type: 'string' } }, required: ['ticket_id'] }
+            },
+            {
+              name: 'post_update',
+              description: 'Post a progress update.',
+              inputSchema: {
+                type: 'object',
+                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                required: ['session_key', 'ticket_id', 'summary']
+              }
+            },
+            {
+              name: 'deliver_ticket',
+              description: 'Deliver completed work.',
+              inputSchema: {
+                type: 'object',
+                properties: { session_key: { type: 'string' }, ticket_id: { type: 'string' }, summary: { type: 'string' } },
+                required: ['session_key', 'ticket_id', 'summary']
+              }
+            }
+          ]
+        }
+      });
+      continue;
+    }
+    if (message.method === 'tools/call') {
+      const toolName = message.params?.name;
+      const args = message.params?.arguments ?? {};
+      if (toolName === 'attach_ticket') {
+        send({ jsonrpc: '2.0', id: message.id, result: await runProtocol('attach', { 'ticket-id': args.ticket_id }) });
+      } else if (toolName === 'post_update') {
+        send({
+          jsonrpc: '2.0',
+          id: message.id,
+          result: await runProtocol('update', {
+            'session-key': args.session_key,
+            'ticket-id': args.ticket_id,
+            summary: args.summary,
+            phase: 'execute'
+          })
+        });
+      } else if (toolName === 'deliver_ticket') {
+        send({
+          jsonrpc: '2.0',
+          id: message.id,
+          result: await runProtocol('deliver', {
+            'session-key': args.session_key,
+            'ticket-id': args.ticket_id,
+            summary: args.summary
+          })
+        });
+      } else {
+        send({ jsonrpc: '2.0', id: message.id, error: { code: -32602, message: `Unknown tool: ${toolName}` } });
+      }
+      continue;
+    }
+    if (message.method === 'ping') {
+      send({ jsonrpc: '2.0', id: message.id, result: {} });
+      continue;
+    }
+    send({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: `Method not found: ${message.method}` } });
+  }
+});
+
+process.stdin.resume();

package/plugins/cursor/skills/overlord-ticket/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: overlord-ticket
+description: Overlord local workflow protocol for Cursor, covering both Overlord-launched tickets and chat-invoked Overlord work.
+---
+
+# Overlord Ticket
+
+Use this skill whenever Cursor needs to work with Overlord, whether the session was launched by Overlord Desktop/CLI or the user asks from chat to engage with Overlord.
+
+## Mode 1: Launched From Overlord Desktop Or CLI
+
+1. Attach first with `ovld protocol attach --ticket-id <ticket_id>`.
+2. Keep the returned `session.sessionKey` for all follow-up calls.
+3. Treat the Overlord ticket prompt as authoritative for the objective, constraints, and delivery target.
+4. Post updates while working with `ovld protocol update --phase execute`.
+5. If the user sends a follow-up message after the initial ticket, publish it immediately with `--event-type user_follow_up`.
+6. If blocked, call `ovld protocol ask` and stop.
+7. Deliver last with `ovld protocol deliver`, including `changeRationales` for each meaningful behavioral file change.
+
+## Mode 2: Asked From Chat To Use Overlord
+
+1. If the user wants to create tickets (and does not ask to start execution), use `/create` or run `ovld protocol create --agent cursor --objective "..."`.
+2. Default to `create` for new tickets. Only use `/spawn` or `ovld protocol spawn --agent cursor --objective "..."` when the user explicitly asks to create and execute immediately.
+3. If the user already has a ticket ID and only wants to inspect it, use `/load` or run `ovld protocol load-context --ticket-id <ticket_id>`.
+4. If the user wants to route the current session onto an existing ticket by ID, use `/connect` or run `ovld protocol connect --ticket-id <ticket_id>`.
+5. If the user wants to search for tickets by keyword or status, use the `search_tickets` MCP tool.
+6. If you need other lifecycle commands or flags, run `ovld protocol help` and use the real subcommand list instead of guessing.
+7. Once you attach to a ticket, switch back to Mode 1 and follow the full ticket lifecycle.
+
+## Choosing `--execution-target` When Creating Tickets
+
+Pass `--execution-target agent` or `--execution-target human` (default: `human`) when creating tickets.
+
+- **`agent`** — any task an AI agent can complete in a computer environment: coding, internet research, document editing, data analysis, automated testing, etc.
+- **`human`** — any task requiring human presence or judgment: setting credentials or tokens in a third-party UI (e.g. Vercel, AWS), sending physical mail, making a product or business decision, physical-world actions.
+
+When in doubt, ask yourself: *can this be done entirely inside a terminal or browser by an AI without human intervention?* If yes → `agent`. If it requires a human to log in, decide, or act in the real world → `human`.
+
+## Rules
+
+- Always attach first and always deliver last once you are on a ticket.
+- Use `ovld protocol` commands, the plugin commands, and the MCP tool instead of ad hoc scripts.
+- Do not invent protocol subcommands. Use `ovld protocol help` when unsure.
+- If `ovld` reports `OVERLORD_URL` is unreachable, request permission escalation or network access before retrying.
+- If a protocol or MCP call fails with auth/session errors, run `ovld auth repair` yourself before asking the user to log in again or proceed without Overlord updates.
+- Include at least one progress update before delivering.
+- When creating follow-up tickets, always set `--execution-target` explicitly using the `agent`/`human` rule above.
+
+<!-- version: 0.2.4 -->

package/plugins/overlord/.codex-plugin/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "overlord",
+  "version": "0.2.1",
+  "description": "Chat-driven access to Overlord ticket protocol workflows.",
+  "author": {
+    "name": "Cooperativ",
+    "url": "https://github.com/cooperativ"
+  },
+  "homepage": "https://github.com/cooperativ/overlord",
+  "repository": "https://github.com/cooperativ/overlord",
+  "license": "UNLICENSED",
+  "keywords": ["overlord", "tickets", "agents", "workflow", "protocol", "mcp", "codex-plugin"],
+  "skills": "./skills/",
+  "mcpServers": "./.mcp.json",
+  "interface": {
+    "displayName": "Overlord",
+    "shortDescription": "Run Overlord ticket workflows from Codex chat",
+    "longDescription": "Connect Codex to Overlord's local ticket workflow through the existing `ovld protocol` CLI. The plugin bundles workflow skills plus MCP tools for ticket attachment, progress updates, shared context, artifacts, delivery, and follow-up ticket creation.",
+    "developerName": "Cooperativ",
+    "category": "Productivity",
+    "capabilities": ["Interactive", "Write"],
+    "websiteURL": "https://www.ovld.ai/docs",
+    "privacyPolicyURL": "https://www.ovld.ai/privacy",
+    "termsOfServiceURL": "https://www.ovld.ai/terms",
+    "defaultPrompt": [
+      "Create an Overlord ticket with the objective 'Implement feature X' and summarize the context before editing code",
+      "Execute Overlord ticket [ticket-id]",
+      "Find all Overlord tickets with the status 'next-up' and prioritize the most important one"
+    ],
+    "brandColor": "#1E6B5C",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "screenshots": ["./assets/screenshot.png"]
+  }
+}

package/plugins/overlord/.mcp.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "overlord": {
+      "command": "node",
+      "args": [
+        "./scripts/overlord-mcp.mjs"
+      ],
+      "note": "Local MCP bridge for the Overlord `ovld protocol` CLI. Requires `ovld` on PATH plus valid OVERLORD_URL and AGENT_TOKEN credentials when talking to a live server."
+    }
+  }
+}

package/plugins/overlord/README.md

@@ -0,0 +1,42 @@
+# Overlord Plugin
+
+This plugin exposes the installed `ovld protocol` workflow to Codex as a local plugin bundle.
+
+It now includes:
+
+- MCP tools for the Overlord ticket protocol
+- a bundled Codex skill for the local ticket lifecycle
+- branded plugin assets for the Codex install surfaces
+
+The plugin is designed for personal installs under `~/.codex/plugins/overlord` with a
+personal marketplace entry at `~/.agents/plugins/marketplace.json`.
+
+## Requirements
+
+- Install the Overlord CLI so `ovld` is available on `PATH`.
+- If a shared session already exists but looks stale, authenticate with `ovld auth repair` first. If repair does not help, use `ovld auth login` or Overlord Desktop. `OVERLORD_URL` can be used to point the CLI at a non-default host.
+- Optionally set `OVLD_BIN` if the CLI lives at a non-standard path.
+- If `ovld` reports `OVERLORD_URL` is unreachable, the bundled workflow tells Codex to request permission escalation or network access before retrying.
+
+## Tool coverage
+
+- Project resolution: `discover_project`
+- Ticket search: `search_tickets` — keyword search + status/filter (direct API call)
+- Ticket session flow: `attach_ticket`, `connect_ticket`, `load_ticket_context`, `spawn_ticket`
+- Progress and review flow: `post_update`, `record_change_rationales`, `ask_blocking_question`, `deliver_ticket`
+- Shared context: `read_shared_context`, `write_shared_context`
+- Objective attachments: `list_attachments`, `prepare_attachment_upload`, `finalize_attachment_upload`, `get_attachment_download_url`, `upload_attachment_file`
+
+The MCP server shells into the installed `ovld` binary so the plugin stays aligned with the shipped CLI behavior instead of depending on this repository checkout.
+
+## Skill coverage
+
+- `skills/overlord-ticket/SKILL.md` teaches Codex the durable local workflow:
+  attach first, update during work, ask when blocked, and deliver last.
+
+## App surface status
+
+The Codex plugin docs support an optional `.app.json` file, but the current file format
+expects a real OpenAI-issued `asdk_app_*` or `connector_*` identifier. This repo does not
+yet have an issued Overlord app ID to point at, so the plugin intentionally does not ship
+an `.app.json` mapping yet.

package/plugins/overlord/assets/screenshot.svg

@@ -0,0 +1,28 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 960 640" role="img" aria-labelledby="title">
+  <title>Overlord Codex Plugin Screenshot</title>
+  <rect width="960" height="640" rx="32" fill="#EEE8DC" />
+  <rect x="28" y="28" width="904" height="584" rx="24" fill="#102A26" />
+  <rect x="56" y="56" width="220" height="528" rx="20" fill="#173D37" />
+  <rect x="300" y="56" width="604" height="528" rx="20" fill="#F6F3EC" />
+  <rect x="80" y="88" width="96" height="14" rx="7" fill="#F4B35D" />
+  <rect x="80" y="130" width="160" height="14" rx="7" fill="#D5E4DE" opacity="0.92" />
+  <rect x="80" y="160" width="132" height="14" rx="7" fill="#D5E4DE" opacity="0.62" />
+  <rect x="80" y="226" width="172" height="42" rx="21" fill="#1E6B5C" />
+  <rect x="332" y="96" width="184" height="18" rx="9" fill="#214D43" />
+  <rect x="332" y="146" width="520" height="18" rx="9" fill="#CFD8D3" />
+  <rect x="332" y="180" width="470" height="18" rx="9" fill="#CFD8D3" />
+  <rect x="332" y="214" width="550" height="18" rx="9" fill="#CFD8D3" />
+  <rect x="332" y="276" width="524" height="116" rx="18" fill="#F0EADF" />
+  <rect x="356" y="304" width="168" height="14" rx="7" fill="#173D37" />
+  <rect x="356" y="336" width="468" height="14" rx="7" fill="#B9C7C2" />
+  <rect x="356" y="360" width="384" height="14" rx="7" fill="#B9C7C2" />
+  <rect x="332" y="430" width="180" height="44" rx="22" fill="#1E6B5C" />
+  <rect x="530" y="430" width="140" height="44" rx="22" fill="#E0D8CA" />
+  <text
+    x="332"
+    y="538"
+    fill="#214D43"
+    font-family="IBM Plex Mono, monospace"
+    font-size="24"
+  >Attach, update, ask, deliver</text>
+</svg>