@kynver-app/mcp-agent-os 0.3.4 → 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 |

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/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.4",
+  "version": "0.3.5",
   "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
   "type": "module",
   "bin": {