@kynver-app/mcp-agent-os 0.3.4 → 0.3.6

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).
@@ -50,6 +63,12 @@ state to important memories instead of burying those pointers in freeform text.
 Set `reviewStatus: "needs_review"` for important or uncertain memories that a
 human should be able to find and correct in the dashboard.
 
+Active-state and correction tools expose the "what is true right now" layer:
+`agent_os_record_state` / `agent_os_get_state` manage one current
+`active_state` row per live PR, branch, or deployment, while
+`agent_os_correct_memory` writes an auditable correction that supersedes stale
+or wrong remembered claims instead of silently editing history.
+
 Skill tools expose the AgentOS skill registry and skill-tagged memory contract.
 Use `agent_os_get_skill` to fetch instructions on demand, `agent_os_create_skill`
 /`agent_os_update_skill` to manage user-authored skills, `agent_os_import_skills`
@@ -62,6 +81,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
@@ -81,7 +82,7 @@ export function createAgentOsServer() {
     })
         .passthrough();
     const memoryTypeSchema = z
-        .enum(["decision", "lesson", "fact", "preference", "project_update", "runbook", "source_map", "correction", "note"])
+        .enum(["decision", "lesson", "fact", "preference", "project_update", "runbook", "source_map", "correction", "active_state", "note"])
         .describe("What kind of durable memory this is. Use note only when a more specific type does not fit.");
     const confidenceSchema = z
         .enum(["low", "medium", "high"])
@@ -89,6 +90,9 @@ export function createAgentOsServer() {
     const reviewStatusSchema = z
         .enum(["none", "needs_review", "reviewed", "stale", "rejected"])
         .describe("Set needs_review for important, uncertain, stale-looking, or user-correctable memories.");
+    const activeStateEntityTypeSchema = z
+        .enum(["pr_watch", "branch", "deployment"])
+        .describe("Tracked entity kind. pr_watch: a live PR. branch: local-vs-remote branch state. deployment: a live release.");
     const skillCategorySchema = z.enum(["engineering", "productivity", "agent_ops", "domain", "personal", "misc"]);
     const skillStatusSchema = z.enum(["draft", "active", "deprecated", "archived"]);
     const skillDraftSchema = z.object({
@@ -243,14 +247,31 @@ export function createAgentOsServer() {
     register("agent_os_search_memory", "Semantic + keyword hybrid search over the agent's long-term MARM memory (ownerType=agent). Use to recall specific decisions, project details, or lessons without loading full context. Replaces grep/reading MEMORY.md. Results include rrfScore — a Reciprocal Rank Fusion score where ~0.033 is a near-perfect match. Higher is better; do not treat low numbers as poor results.", {
         query: z.string().describe("Natural language query to search memory."),
         k: z.number().optional().describe("Number of results (default 10, max 50)."),
+        ticker: z.string().optional().describe("Trading desk: filter hits to this ticker symbol."),
+        debatePersona: z.enum(["bull", "bear"]).optional().describe("Trading desk: filter to bull or bear advocate memories."),
         slug: slugField,
     }, async (args) => {
         const params = new URLSearchParams({ q: args.query });
         if (args.k)
             params.set("k", String(args.k));
+        if (args.ticker)
+            params.set("ticker", args.ticker);
+        if (args.debatePersona)
+            params.set("debatePersona", args.debatePersona);
         const s = await resolveToolSlug(args.slug);
         return jsonResult(await get(`/agent-os/${s}/memory?${params}`));
     });
+    register("agent_os_get_desk_debate_context", "Fetch trading-desk debate context for a ticker: latest canonical DeskAnalysisReport debate fields plus bull/bear MARM snippets scoped by ticker and debatePersona.", {
+        ticker: z.string().describe("Equity ticker symbol, e.g. NVDA."),
+        reportId: z.string().optional().describe("Optional DeskAnalysisReport id; defaults to latest canonical report for the ticker."),
+        slug: slugField,
+    }, async (args) => {
+        const params = new URLSearchParams({ ticker: args.ticker });
+        if (args.reportId)
+            params.set("reportId", args.reportId);
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/desk-debate-context?${params}`));
+    });
     register("agent_os_list_skills", "List AgentOS skills available to this workspace, including Kynver built-ins, user-authored skills, and per-AgentOS binding state. Pass view=\"manifest\" for the runtime read path: only enabled, runtime-eligible skills (enabled binding plus, for user skills, status=active) with metadata only — no instructions. Skill instructions are fetched on demand with agent_os_get_skill; do not inject every skill into every model context.", {
         view: z
             .enum(["full", "manifest"])
@@ -503,5 +524,67 @@ export function createAgentOsServer() {
         const s = await resolveToolSlug(slug);
         return jsonResult(await post(`/agent-os/${s}/memory`, body));
     });
+    register("agent_os_correct_memory", "Write an auditable correction memory that supersedes a stale or wrong memory by slug. Use when fixing an incorrect remembered claim rather than silently editing history.", {
+        targetSlug: z.string().describe("Slug/key of the memory being corrected."),
+        content: z.string().describe("Correct replacement content to remember."),
+        reason: z.string().describe("Why the target is wrong; recorded on the superseded target."),
+        key: z.string().optional().describe("Slug for the new correction memory. Defaults to <targetSlug>-correction."),
+        alsoInvalidates: z.array(z.string()).optional().describe("Additional memory slugs/ids to supersede alongside targetSlug."),
+        assertedBySessionId: z.string().optional(),
+        sourceId: z.string().optional(),
+        sourceRefs: z.array(sourceRefSchema).optional(),
+        memoryType: memoryTypeSchema.optional(),
+        confidence: confidenceSchema.optional(),
+        reviewStatus: reviewStatusSchema.optional(),
+        projectId: z.string().optional(),
+        goalId: z.string().optional(),
+        contactId: z.string().optional(),
+        skillId: z.string().optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post("/agent-os/" + s + "/memory/correct", body));
+    });
+    register("agent_os_record_state", "Record current active state for a live mutable entity such as a PR, branch, or deployment. Server derives the canonical entityKey from fields and upserts one active_state row per entity.", {
+        entityType: activeStateEntityTypeSchema,
+        fields: z.record(z.string(), z.unknown()).describe("Entity-specific current truth. pr_watch requires repo, pr, author, headOwner, headBranch, state. branch requires repo, branch, aheadBy, behindBy, lastCommit. deployment requires target, env, state, url, and version or sha."),
+        observedAt: z.string().optional().describe("ISO timestamp the state was observed. Defaults to now."),
+        content: z.string().optional().describe("Optional human summary; one is generated otherwise."),
+        sourceRefs: z.array(sourceRefSchema).optional(),
+        projectId: z.string().optional(),
+        confidence: confidenceSchema.optional(),
+        reviewStatus: reviewStatusSchema.optional(),
+        sourceId: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, ...body } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post("/agent-os/" + s + "/memory/state", body));
+    });
+    register("agent_os_get_state", "Get current active state records. Pass entityKey for one record, or entityType/projectId/limit to list active PR, branch, or deployment state.", {
+        entityKey: z.string().optional().describe("Canonical key of a single record, e.g. pr:openclaw/openclaw#83529. Omit to list records."),
+        entityType: activeStateEntityTypeSchema.optional(),
+        projectId: z.string().optional(),
+        limit: z.number().optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, entityKey, entityType, projectId, limit } = args;
+        const s = await resolveToolSlug(slug);
+        const qs = new URLSearchParams();
+        if (entityKey)
+            qs.set("entityKey", entityKey);
+        if (entityType)
+            qs.set("entityType", entityType);
+        if (projectId)
+            qs.set("projectId", projectId);
+        if (limit !== undefined)
+            qs.set("limit", String(limit));
+        const suffix = qs.toString() ? "?" + qs.toString() : "";
+        return jsonResult(await get("/agent-os/" + s + "/memory/state" + suffix));
+    });
+    // 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.6",
   "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
   "type": "module",
   "bin": {