@kynver-app/mcp-agent-os 0.3.3 → 0.3.5

package/README.md

@@ -38,6 +38,19 @@ The full family:
 - `agent_os_update_contact`
 - `agent_os_consolidate_memory`
 
+AgentTask board (Phase 2 — batch 1 CRUD + batch 1.5 steering/lease):
+
+- `agent_os_task_create`
+- `agent_os_task_get`
+- `agent_os_task_list`
+- `agent_os_task_update`
+- `agent_os_task_log_event`
+- `agent_os_task_close`
+- `agent_os_task_steer`
+- `agent_os_task_abort`
+- `agent_os_task_claim`
+- `agent_os_task_renew_lease`
+
 Schemas are mirrored in `lib/mcp/tool-manifests/kynver-mcp-agent-os.json` in
 the Kynver repo (used as the static fallback when stdio spawn isn't available
 — e.g. on Vercel).
@@ -62,6 +75,17 @@ slug as `skillId`; user-authored skill memories use `AgentSkill.id`.
 summaries can then be synthesized from actual topics, actions, decisions, and
 follow-ups instead of generic lifecycle text.
 
+AgentTask tools expose the durable task board. `agent_os_task_create` is
+idempotent within an AgentOS — pass `idempotencyKey` (or `requestId`) from the
+foreground turn so a retry or restart returns the existing task instead of
+spawning a duplicate. `agent_os_task_log_event` accepts a stable `eventKey` so a
+board-down executor can replay its local event spool without creating
+duplicates; `artifact` events take an `artifactVisibility` tier (`internal` |
+`telegram_safe` | `public_pr_safe`, default `internal`). `agent_os_task_claim`
+and `agent_os_task_renew_lease` implement the lease model — an executor must
+hold a live lease to own a task, and a claim is an atomic conditional update
+that increments `attempt`.
+
 ## Env
 
 | Var | Purpose |
@@ -70,6 +94,7 @@ follow-ups instead of generic lifecycle text.
 | `KYNVER_API_KEY` | Bearer token for external authentication |
 | `KYNVER_AGENT_OS_SLUG` | Default agent slug when the tool's `slug` arg is omitted (defaults to `"ghost"`) |
 | `KYNVER_SERVICE_SECRET` | Required when running under SSE and forwarding internal `userId` headers |
+| `MCP_SSE_HOST` | SSE bind address (defaults to `127.0.0.1`) |
 | `PORT` | SSE port (defaults to `3101`) |
 
 ## OpenClaw / Claude Code config

package/SECURITY.md

@@ -0,0 +1,31 @@
+# Security — Kynver MCP packages
+
+## Recommended deployment
+
+- **Prefer stdio** (`npx @kynver-app/mcp-*`) from Cursor, Claude Code, or OpenClaw. The MCP host process owns the trust boundary.
+- **Avoid exposing SSE** (`start:sse`) to the public internet unless you terminate TLS and restrict access at a reverse proxy.
+
+## Secrets
+
+- Store `KYNVER_API_KEY` and `KYNVER_SERVICE_SECRET` in environment variables or your MCP host's secret store — never in git, query strings, or shared logs.
+- `KYNVER_SERVICE_SECRET` plus a valid user API key can impersonate any user on your Kynver deployment. Treat it as tier-0.
+
+## SSE mode (`start:sse`)
+
+When you run the optional HTTP/SSE server:
+
+| Control | Default | Purpose |
+|---------|---------|---------|
+| `MCP_SSE_HOST` | `127.0.0.1` | Bind address — keep localhost unless behind a proxy |
+| `PORT` | package-specific | Listen port |
+
+Authentication rules:
+
+- **Headers only** for internal auth on `GET /sse` — `X-Kynver-User-Id` + `X-Kynver-Service-Secret`. Never pass `secret` or `userId` in query strings.
+- **External API keys** may use `Authorization: Bearer <apiKey>` (preferred) or `?apiKey=` on `GET /sse` when your MCP client cannot set headers (EventSource). Query keys may appear in access logs.
+- **`POST /messages` requires the same API key or internal headers** used to open the SSE session — not `sessionId` alone.
+- Request bodies are capped at **1 MB**.
+
+## Reporting
+
+Report vulnerabilities to Kynver through your usual security channel for the Kynver deployment you operate.

package/dist/server.js

@@ -9,6 +9,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, patch } from "./lib/kynver-client.js";
+import { registerTaskTools } from "./tools/tasks.js";
 function jsonResult(data) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -25,7 +26,7 @@ function compact(source) {
 }
 const MCP_LEGACY_SLUG_FALLBACK = "ghost";
 export function createAgentOsServer() {
-    const server = new McpServer({ name: "kynver-mcp-agent-os", version: "0.3.2" }, { capabilities: { tools: {} } });
+    const server = new McpServer({ name: "kynver-mcp-agent-os", version: "0.3.5" }, { capabilities: { tools: {} } });
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     function register(name, description, inputSchema, cb) {
         // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -503,5 +504,7 @@ export function createAgentOsServer() {
         const s = await resolveToolSlug(slug);
         return jsonResult(await post(`/agent-os/${s}/memory`, body));
     });
+    // AgentTask board — batch 1 (CRUD) + batch 1.5 (steering / lease) tools.
+    registerTaskTools({ register, resolveToolSlug, jsonResult, compact });
     return server;
 }

package/dist/sse.d.ts

@@ -1,18 +1 @@
-/**
- * SSE entry point for the Agentic OS MCP server.
- *
- * Supports two authentication modes:
- *   1. Internal (Kynver dashboard): X-Kynver-User-Id + X-Kynver-Service-Secret
- *      request headers. The legacy userId/secret query params are still
- *      accepted as a deprecated transitional fallback so an older web-tier
- *      build keeps working during a rolling deploy — remove once all callers
- *      send headers. Secrets must never travel in the query string in steady
- *      state (they leak via access logs, proxies, and referrers).
- *   2. External (Claude Code, Cursor, any MCP client): Kynver API key via
- *      query param (?apiKey=…) or Authorization header
- *
- * External keys are validated by calling GET /api/users/me on the Kynver API.
- * Once authenticated, tool calls execute on behalf of the resolved user via
- * the requestContext AsyncLocalStorage.
- */
 export {};

package/dist/sse.js

@@ -1,140 +1,9 @@
-/**
- * SSE entry point for the Agentic OS MCP server.
- *
- * Supports two authentication modes:
- *   1. Internal (Kynver dashboard): X-Kynver-User-Id + X-Kynver-Service-Secret
- *      request headers. The legacy userId/secret query params are still
- *      accepted as a deprecated transitional fallback so an older web-tier
- *      build keeps working during a rolling deploy — remove once all callers
- *      send headers. Secrets must never travel in the query string in steady
- *      state (they leak via access logs, proxies, and referrers).
- *   2. External (Claude Code, Cursor, any MCP client): Kynver API key via
- *      query param (?apiKey=…) or Authorization header
- *
- * External keys are validated by calling GET /api/users/me on the Kynver API.
- * Once authenticated, tool calls execute on behalf of the resolved user via
- * the requestContext AsyncLocalStorage.
- */
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { createServer } from "node:http";
+import { startKynverMcpSseServer } from "@kynver-app/mcp-sse-lib";
 import { createAgentOsServer } from "./server.js";
 import { requestContext } from "./lib/kynver-client.js";
-const PORT = parseInt(process.env.PORT ?? "3101", 10);
-const BASE_URL = process.env.KYNVER_API_URL ?? "https://kynver.com";
-const SERVICE_SECRET = process.env.KYNVER_SERVICE_SECRET ?? "";
-// ---------------------------------------------------------------------------
-// Session tracking — maps sessionId → { transport, userId }
-// ---------------------------------------------------------------------------
-const sessions = {};
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/** Validate an external API key by calling the Kynver API. */
-async function resolveUser(apiKey) {
-    try {
-        const res = await fetch(`${BASE_URL}/api/users/me`, {
-            headers: { Authorization: `Bearer ${apiKey}` },
-        });
-        if (!res.ok)
-            return null;
-        const data = (await res.json());
-        return data.id ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-/** Read and JSON-parse the request body (needed for raw http.Server). */
-function parseBody(req) {
-    return new Promise((resolve, reject) => {
-        const chunks = [];
-        req.on("data", (chunk) => chunks.push(chunk));
-        req.on("end", () => {
-            try {
-                resolve(JSON.parse(Buffer.concat(chunks).toString()));
-            }
-            catch (e) {
-                reject(e);
-            }
-        });
-        req.on("error", reject);
-    });
-}
-function parseUrl(req) {
-    return new URL(req.url ?? "/", `http://localhost:${PORT}`);
-}
-// ---------------------------------------------------------------------------
-// HTTP server
-// ---------------------------------------------------------------------------
-const httpServer = createServer(async (req, res) => {
-    const url = parseUrl(req);
-    const path = url.pathname;
-    // ── SSE connection ──────────────────────────────────────────────────
-    if (req.method === "GET" && path === "/sse") {
-        // Internal auth: Kynver web tier passes userId + service secret as headers.
-        // Query params are a deprecated transitional fallback (see file header).
-        const headerValue = (name) => {
-            const v = req.headers[name];
-            return typeof v === "string" ? v : Array.isArray(v) ? (v[0] ?? null) : null;
-        };
-        const internalUserId = headerValue("x-kynver-user-id") ?? url.searchParams.get("userId");
-        const internalSecret = headerValue("x-kynver-service-secret") ?? url.searchParams.get("secret");
-        // External auth: API key via query param or Authorization header
-        const apiKey = url.searchParams.get("apiKey") ??
-            req.headers.authorization?.replace("Bearer ", "") ??
-            "";
-        let userId = null;
-        if (internalUserId && SERVICE_SECRET && internalSecret === SERVICE_SECRET) {
-            userId = internalUserId;
-        }
-        else if (apiKey) {
-            userId = await resolveUser(apiKey);
-        }
-        if (!userId) {
-            res.writeHead(401, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                error: "Unauthorized. Provide a valid Kynver API key.",
-            }));
-            return;
-        }
-        console.log(`[MCP SSE] New connection (userId: ${userId})`);
-        const transport = new SSEServerTransport("/messages", res);
-        sessions[transport.sessionId] = { transport, userId };
-        res.on("close", () => {
-            console.log(`[MCP SSE] Connection closed: ${transport.sessionId}`);
-            delete sessions[transport.sessionId];
-        });
-        const server = createAgentOsServer();
-        await server.connect(transport);
-        return;
-    }
-    // ── Message handler (client → server JSON-RPC messages) ─────────────
-    if (req.method === "POST" && path === "/messages") {
-        const sessionId = url.searchParams.get("sessionId");
-        const entry = sessionId ? sessions[sessionId] : undefined;
-        if (!entry) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({
-                error: "No active SSE session for this sessionId",
-            }));
-            return;
-        }
-        const body = await parseBody(req);
-        // Wrap in request context so kynver-client sends the right user headers
-        await requestContext.run({ userId: entry.userId }, async () => {
-            await entry.transport.handlePostMessage(req, res, body);
-        });
-        return;
-    }
-    // ── Health check ────────────────────────────────────────────────────
-    if (req.method === "GET" && path === "/health") {
-        res.writeHead(200, { "Content-Type": "text/plain" });
-        res.end("ok");
-        return;
-    }
-    res.writeHead(404, { "Content-Type": "application/json" });
-    res.end(JSON.stringify({ error: "Not found" }));
-});
-httpServer.listen(PORT, () => {
-    console.log(`[MCP SSE] Agentic OS server listening on port ${PORT}`);
+startKynverMcpSseServer({
+    label: "Agentic OS server",
+    defaultPort: 3101,
+    createMcpServer: createAgentOsServer,
+    requestContext,
 });

package/dist/tools/tasks.d.ts

@@ -0,0 +1,26 @@
+/**
+ * AgentTask board MCP tools — batch 1 (Ghost-facing CRUD) and batch 1.5
+ * (steering / lease). Each tool proxies to `/api/agent-os/{slug}/tasks/*`.
+ *
+ * Kept in its own module so server.ts does not grow monolithic. server.ts
+ * calls `registerTaskTools` with the helpers it already has in scope.
+ */
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: unknown;
+};
+export interface TaskToolDeps {
+    /** server.ts's thin wrapper over `server.registerTool`. */
+    register: (name: string, description: string, inputSchema: Record<string, unknown>, cb: (args: any) => any) => void;
+    /** Resolve the effective AgentOS slug (explicit arg → env → discovered primary). */
+    resolveToolSlug: (explicitSlug?: string) => Promise<string>;
+    /** Wrap a value as an MCP text + structuredContent result. */
+    jsonResult: (data: unknown) => ToolResult;
+    /** Drop `undefined` entries from an object. */
+    compact: (source: Record<string, unknown>) => Record<string, unknown>;
+}
+export declare function registerTaskTools({ register, resolveToolSlug, jsonResult, compact, }: TaskToolDeps): void;
+export {};

package/dist/tools/tasks.js

@@ -0,0 +1,167 @@
+/**
+ * AgentTask board MCP tools — batch 1 (Ghost-facing CRUD) and batch 1.5
+ * (steering / lease). Each tool proxies to `/api/agent-os/{slug}/tasks/*`.
+ *
+ * Kept in its own module so server.ts does not grow monolithic. server.ts
+ * calls `registerTaskTools` with the helpers it already has in scope.
+ */
+import { z } from "zod";
+import { get, post, patch } from "../lib/kynver-client.js";
+const taskStatus = z.enum([
+    "queued",
+    "running",
+    "blocked",
+    "needs_input",
+    "awaiting_review",
+    "done",
+    "failed",
+    "cancelled",
+]);
+const taskPriority = z.enum(["low", "normal", "high", "critical"]);
+const taskExecutor = z.enum(["inline", "harness", "acp", "manual"]);
+const taskEventType = z.enum([
+    "created",
+    "started",
+    "worker_update",
+    "blocked",
+    "steer",
+    "artifact",
+    "review",
+    "done",
+    "failed",
+]);
+const artifactVisibility = z.enum(["internal", "telegram_safe", "public_pr_safe"]);
+export function registerTaskTools({ register, resolveToolSlug, jsonResult, compact, }) {
+    const slugField = z
+        .string()
+        .optional()
+        .describe("AgentOS slug. Omit to use env or the server-discovered primary.");
+    register("agent_os_task_create", "Create an AgentTask on the board. Idempotent within the AgentOS: pass idempotencyKey (or requestId) from the foreground turn so a Telegram retry or Ghost restart returns the existing task instead of spawning a duplicate. Response includes `created` (false = an existing task was returned).", {
+        title: z.string().describe("Short task title (required)."),
+        description: z.string().optional(),
+        priority: taskPriority.optional(),
+        executor: taskExecutor.optional().describe("How the task runs: inline | harness | acp | manual."),
+        executorRef: z.string().optional().describe("Opaque ref to the executor process / unit."),
+        parentTaskId: z.string().optional().describe("Parent task id when this is one of 2+ coordinated workers."),
+        goalId: z.string().optional(),
+        projectId: z.string().optional(),
+        idempotencyKey: z.string().optional().describe("Dedupe key from the foreground turn. Strongly recommended."),
+        requestId: z.string().optional().describe("Raw foreground request id; used as the dedupe key if idempotencyKey is absent."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks`, compact(body)));
+    });
+    register("agent_os_task_get", "Fetch one AgentTask by id, including lease, artifact, and steer-cursor fields.", { taskId: z.string(), slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/tasks/${args.taskId}`));
+    });
+    register("agent_os_task_list", "List AgentTasks on the board, optionally filtered by status, executor, or parent task.", {
+        status: taskStatus.optional(),
+        executor: taskExecutor.optional(),
+        parentTaskId: z.string().optional(),
+        limit: z.number().optional().describe("Max rows (default 50, max 200)."),
+        slug: slugField,
+    }, async (args) => {
+        const params = new URLSearchParams();
+        if (args.status)
+            params.set("status", args.status);
+        if (args.executor)
+            params.set("executor", args.executor);
+        if (args.parentTaskId)
+            params.set("parentTaskId", args.parentTaskId);
+        if (args.limit)
+            params.set("limit", String(args.limit));
+        const qs = params.toString();
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/tasks${qs ? `?${qs}` : ""}`));
+    });
+    register("agent_os_task_update", "Patch an AgentTask: status, priority, executor, links, progress summary, blocker, or first-class artifact refs (branch/worktreePath/prUrl/headCommit). Does not touch lease fields — use claim/renew for those.", {
+        taskId: z.string(),
+        title: z.string().optional(),
+        description: z.string().optional(),
+        status: taskStatus.optional(),
+        priority: taskPriority.optional(),
+        executor: taskExecutor.optional(),
+        executorRef: z.string().optional(),
+        parentTaskId: z.string().optional(),
+        goalId: z.string().optional(),
+        projectId: z.string().optional(),
+        lastSummary: z.string().optional().describe("Latest progress summary."),
+        blocker: z.string().optional(),
+        branch: z.string().optional(),
+        worktreePath: z.string().optional(),
+        prUrl: z.string().optional(),
+        headCommit: z.string().optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await patch(`/agent-os/${s}/tasks/${taskId}`, compact(body)));
+    });
+    register("agent_os_task_log_event", "Append one event to a task's append-only journal: worker_update, blocked, artifact, review, etc. For artifact events set artifactVisibility (internal | telegram_safe | public_pr_safe) and put branch/prUrl/headCommit/worktreePath in payload — they are promoted to the task. Pass a stable eventKey so a board-down spool can replay without duplicates.", {
+        taskId: z.string(),
+        type: taskEventType.describe("Event type."),
+        payload: z.record(z.string(), z.unknown()).optional().describe("Structured event detail."),
+        artifactVisibility: artifactVisibility
+            .optional()
+            .describe("Required mental model for artifact events; defaults to internal (most conservative)."),
+        eventKey: z.string().optional().describe("Stable idempotency key for spool replay."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks/${taskId}/events`, compact(body)));
+    });
+    register("agent_os_task_close", "Close a task into a terminal status (done | failed | cancelled, default done). Stamps closedAt, releases the lease, records the summary, and appends a terminal journal event.", {
+        taskId: z.string(),
+        status: z.enum(["done", "failed", "cancelled"]).optional(),
+        summary: z.string().optional().describe("Closing summary."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks/${taskId}/close`, compact(body)));
+    });
+    register("agent_os_task_steer", "Append a steer event to a task. Steers are an ordered log — two concurrent steers never overwrite each other; the task's lastSteerEventId tracks the newest. The executor reads steers between its cursor and lastSteerEventId.", {
+        taskId: z.string(),
+        message: z.string().describe("The steering instruction."),
+        detail: z.record(z.string(), z.unknown()).optional(),
+        eventKey: z.string().optional().describe("Stable idempotency key for spool replay."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks/${taskId}/steer`, compact(body)));
+    });
+    register("agent_os_task_abort", "Hard-abort a task: marks it cancelled and stamps a closing event. Local executor / worktree teardown is the executor's job — this only updates durable board state.", {
+        taskId: z.string(),
+        reason: z.string().optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks/${taskId}/abort`, compact(body)));
+    });
+    register("agent_os_task_claim", "Atomically claim a task lease. Succeeds only when the task is non-terminal and its lease is free (never set or expired). The same conditional update increments `attempt` and flips the task to running. A failed claim returns ok=false with a reason (lease_held | terminal | not_found).", {
+        taskId: z.string(),
+        leaseOwner: z.string().describe("Unique id of the claiming executor."),
+        leaseDurationMs: z.number().optional().describe("Lease duration in ms (default 300000)."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks/${taskId}/claim`, compact(body)));
+    });
+    register("agent_os_task_renew_lease", "Renew a lease the caller already owns — call periodically while the executor is alive. Succeeds only when leaseOwner matches and the lease has not expired. A failed renew returns ok=false with reason owner_mismatch or lease_expired; the caller must re-claim.", {
+        taskId: z.string(),
+        leaseOwner: z.string().describe("Must match the current lease owner."),
+        leaseDurationMs: z.number().optional().describe("New lease duration in ms (default 300000)."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, taskId, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/tasks/${taskId}/renew-lease`, compact(body)));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kynver-app/mcp-agent-os",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
   "type": "module",
   "bin": {
@@ -8,10 +8,11 @@
   },
   "files": [
     "dist",
-    "README.md"
+    "README.md",
+    "SECURITY.md"
   ],
   "scripts": {
-    "build": "node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc",
+    "build": "npm run build -w @kynver-app/mcp-sse-lib && node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc",
     "dev": "node --max-old-space-size=8192 ../../node_modules/typescript/bin/tsc --watch",
     "start": "node dist/index.js",
     "start:sse": "node dist/sse.js"
@@ -20,6 +21,7 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@kynver-app/mcp-sse-lib": "*",
     "@modelcontextprotocol/sdk": "^1.27.0",
     "zod": "^3.23.0"
   },