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

package/README.md

@@ -51,6 +51,19 @@ AgentTask board (Phase 2 — batch 1 CRUD + batch 1.5 steering/lease):
 - `agent_os_task_claim`
 - `agent_os_task_renew_lease`
 
+AgentPlan first-class plans (Phase 5A — versioned operational artifacts
+separate from goals/projects/tasks):
+
+- `agent_os_plan_create`
+- `agent_os_plan_list`
+- `agent_os_plan_get`
+- `agent_os_plan_update`
+- `agent_os_plan_add_version`
+- `agent_os_plan_mark_current`
+- `agent_os_plan_add_link`
+- `agent_os_plan_list_links`
+- `agent_os_plan_list_versions`
+
 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).
@@ -63,6 +76,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`
@@ -75,6 +94,18 @@ 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.
 
+AgentPlan tools manage first-class plans — versioned operational artifacts
+distinct from goals/projects/tasks. Each `AgentPlan` owns a chain of immutable
+`AgentPlanVersion` snapshots (one stamped current at a time) plus typed
+`AgentPlanLink` rows pointing at goals/projects/tasks/memories/sessions/plans
+or remote refs (repo/branch/commit/PR/URL/markdown). The plan body itself is
+immutable — to record a new snapshot call `agent_os_plan_add_version`, which
+appends a new version and (by default) advances `currentVersionId` atomically.
+Use `planSlug` for the plan's own stable slug; the workspace `slug` argument
+is reserved for the AgentOS workspace. Workspace-owned link targets are
+re-validated server-side against the same AgentOS workspace; remote refs
+carry metadata only.
+
 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

package/dist/server.js

@@ -9,7 +9,9 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import { get, post, patch } from "./lib/kynver-client.js";
+import { registerPlanTools } from "./tools/plans.js";
 import { registerTaskTools } from "./tools/tasks.js";
+import { registerActionRequiredTools } from "./tools/action-required.js";
 function jsonResult(data) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -82,7 +84,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"])
@@ -90,6 +92,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({
@@ -116,6 +121,26 @@ export function createAgentOsServer() {
         const s = await resolveToolSlug(args.slug);
         return jsonResult(await get(`/agent-os/${s}/stats`));
     });
+    register("agent_os_context_envelope", "Build a compact context envelope for one anchor (plan | task | goal | project | session). Returns the resolved anchor, its goal + plan (with current version body) + most-relevant task + recent session + top related memories with deduplicated source refs. Use this instead of reading giant docs when picking up an in-flight piece of work — one round trip, scoped to your workspace.", {
+        anchorType: z.enum(["plan", "task", "goal", "project", "session"]).describe("Kind of anchor to load context around."),
+        anchorId: z.string().describe("Id of the anchor row within this workspace."),
+        memoryQuery: z.string().optional().describe("Override the memory search query. Defaults to a query derived from the anchor's title/summary."),
+        memoryLimit: z.number().optional().describe("Max memory hits (default 5, max 20). Set 0 to skip memory recall."),
+        sessionLimit: z.number().optional().describe("Max recent sessions (default 1, max 5). Set 0 to skip."),
+        slug: slugField,
+    }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        const params = new URLSearchParams();
+        params.set("anchorType", args.anchorType);
+        params.set("anchorId", args.anchorId);
+        if (args.memoryQuery)
+            params.set("memoryQuery", args.memoryQuery);
+        if (args.memoryLimit !== undefined)
+            params.set("memoryLimit", String(args.memoryLimit));
+        if (args.sessionLimit !== undefined)
+            params.set("sessionLimit", String(args.sessionLimit));
+        return jsonResult(await get(`/agent-os/${s}/context-envelope?${params}`));
+    });
     register("agent_os_open_session", "Call this at the START of every session. Records channel, model, and opens a session record for continuity. Ghost calls this immediately after agent_os_get_context on startup.", {
         channel: z.string().describe("Runtime channel: 'webchat' | 'telegram' | 'discord' | …"),
         model: z.string().optional().describe("Model used for the session (default 'claude-sonnet-4-6')."),
@@ -244,14 +269,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"])
@@ -504,7 +546,71 @@ 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 });
+    // First-class AgentOS plans (Phase 5A): versioned operational artifacts.
+    registerPlanTools({ register, resolveToolSlug, jsonResult, compact });
+    // Action Required inbox: agent_os_ask_human + agent_os_await_action (slice 1).
+    registerActionRequiredTools({ register, jsonResult, compact });
     return server;
 }

package/dist/tools/action-required.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Action Required inbox MCP tools.
+ *
+ * Slice 1 exposes two tools:
+ *   - agent_os_ask_human   : create one inbox item (one decision per call)
+ *   - agent_os_await_action: poll an item until it resolves (or timeout)
+ *
+ * Each tool proxies to `/api/action-required/*`. The Kynver API enforces
+ * per-user ownership and the one-question lint server-side.
+ */
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: unknown;
+};
+export interface ActionRequiredToolDeps {
+    register: (name: string, description: string, inputSchema: Record<string, unknown>, cb: (args: any) => any) => void;
+    jsonResult: (data: unknown) => ToolResult;
+    compact: (source: Record<string, unknown>) => Record<string, unknown>;
+}
+export declare function registerActionRequiredTools({ register, jsonResult, compact, }: ActionRequiredToolDeps): void;
+export {};

package/dist/tools/action-required.js

@@ -0,0 +1,140 @@
+/**
+ * Action Required inbox MCP tools.
+ *
+ * Slice 1 exposes two tools:
+ *   - agent_os_ask_human   : create one inbox item (one decision per call)
+ *   - agent_os_await_action: poll an item until it resolves (or timeout)
+ *
+ * Each tool proxies to `/api/action-required/*`. The Kynver API enforces
+ * per-user ownership and the one-question lint server-side.
+ */
+import { z } from "zod";
+import { get, post } from "../lib/kynver-client.js";
+const category = z.enum([
+    "decision",
+    "approval",
+    "question",
+    "blocker",
+    "clarification",
+]);
+const priority = z.enum(["low", "normal", "high", "critical"]);
+const blockerKind = z
+    .enum([
+    "none",
+    "deploy",
+    "env",
+    "db",
+    "npm",
+    "live_trade",
+    "content_publish",
+    "code_review",
+    "merge",
+    "other",
+])
+    .optional();
+const askerKind = z.enum(["agent", "reviewer", "task", "system"]).default("agent");
+const recommendation = z
+    .object({
+    value: z.string().describe("The recommended answer the user can accept with one tap."),
+    confidence: z.enum(["low", "medium", "high"]).optional(),
+    rationale: z.string().optional(),
+    source: z.enum(["agent", "policy", "history"]).optional(),
+})
+    .strict();
+const evidence = z
+    .array(z
+    .object({
+    kind: z.enum(["url", "memory", "task_event", "file", "text", "pr", "commit"]),
+    label: z.string().optional(),
+    ref: z.string(),
+})
+    .strict())
+    .optional();
+const options = z
+    .array(z
+    .object({
+    value: z.string(),
+    label: z.string().optional(),
+    isRecommended: z.boolean().optional(),
+})
+    .strict())
+    .optional();
+export function registerActionRequiredTools({ register, jsonResult, compact, }) {
+    register("agent_os_ask_human", [
+        "Surface one decision to the human via the Action Required inbox.",
+        "Each call MUST contain exactly one question the human can answer in one breath.",
+        "Compound asks ('Do X? Or Y?') are rejected server-side with multiple_questions_detected — split them into two calls.",
+        "Recommendation is required for category=decision|approval; supply the best-guess answer the user can one-tap accept.",
+        "Returns the created `item` (with id you can pass to agent_os_await_action) and a `created` flag (false = idempotent re-create).",
+    ].join(" "), {
+        title: z.string().describe("Short headline rendered as the card title."),
+        question: z
+            .string()
+            .describe("The single question (one '?'). The user sees this verbatim."),
+        body: z
+            .string()
+            .optional()
+            .describe("Expanded context / background. Collapsed in the UI; expand-on-tap."),
+        category: category.default("decision"),
+        priority: priority.default("normal"),
+        askerKind: askerKind.optional(),
+        askerRef: z.string().optional().describe("Free-form ref (e.g. agent slug, reviewer id)."),
+        blockerKind: blockerKind,
+        recommendation: recommendation.optional(),
+        evidence,
+        options,
+        taskId: z.string().optional().describe("Linked AgentTask id — unblocks on answer."),
+        planId: z.string().optional(),
+        planVersionId: z.string().optional(),
+        goalId: z.string().optional(),
+        projectId: z.string().optional(),
+        sessionId: z.string().optional(),
+        sourceEventId: z.number().int().optional(),
+        unblockTaskIds: z.array(z.string()).optional(),
+        expiresAt: z
+            .string()
+            .optional()
+            .describe("ISO-8601 timestamp for hard deadline. Defaults to 24h for approvals; null otherwise."),
+        agentOsId: z.string().optional(),
+        createdByAgentRef: z.string().optional(),
+        clientRequestId: z
+            .string()
+            .optional()
+            .describe("Dedupe key — repeating the same id within a user returns the existing item with created=false."),
+    }, async (args) => {
+        return jsonResult(await post("/action-required", compact(args)));
+    });
+    register("agent_os_await_action", [
+        "Poll one Action Required item until it resolves.",
+        "Returns immediately if the item is already terminal (answered / resolved_noop / expired / superseded / cancelled).",
+        "If still open/snoozed, waits up to `timeoutSeconds` (default 60, max 300) with `pollIntervalSeconds` between checks.",
+        "On answer, the answer text + acceptedRecommendation flag are returned so you can resume work without re-fetching.",
+    ].join(" "), {
+        itemId: z.string().describe("The Action Required item id returned by agent_os_ask_human."),
+        timeoutSeconds: z.number().int().min(0).max(300).optional(),
+        pollIntervalSeconds: z.number().int().min(2).max(60).optional(),
+    }, async (args) => {
+        const itemId = String(args.itemId);
+        const timeout = Math.min(300, Math.max(0, args.timeoutSeconds ?? 60));
+        const interval = Math.max(2, Math.min(60, args.pollIntervalSeconds ?? 5));
+        const start = Date.now();
+        let last = null;
+        while (true) {
+            const data = (await get(`/action-required/${encodeURIComponent(itemId)}/await`));
+            last = data;
+            if (data.status !== "open" && data.status !== "snoozed") {
+                return jsonResult({ ...data, waited: Math.round((Date.now() - start) / 1000) });
+            }
+            if (Date.now() - start >= timeout * 1000) {
+                return jsonResult({
+                    ...data,
+                    stillOpen: true,
+                    waited: Math.round((Date.now() - start) / 1000),
+                });
+            }
+            await new Promise((r) => setTimeout(r, interval * 1000));
+        }
+        // eslint-disable-next-line no-unreachable
+        return jsonResult(last);
+    });
+}

package/dist/tools/plans.d.ts

@@ -0,0 +1,29 @@
+/**
+ * AgentOS plan MCP tools — Phase 5A of
+ * docs/superpowers/plans/2026-05-17-agent-os-memory-reliability.md. Each tool
+ * proxies to `/api/agent-os/{slug}/plans*` on Kynver. Workspace isolation is
+ * enforced server-side via slug-resolved AgentOS context plus service-layer
+ * scope checks — callers do NOT pass userId or agentOsId from here.
+ *
+ * Kept in its own module so server.ts stays small. server.ts calls
+ * `registerPlanTools` with the helpers it already has in scope.
+ */
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: unknown;
+};
+export interface PlanToolDeps {
+    /** 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 registerPlanTools({ register, resolveToolSlug, jsonResult, compact, }: PlanToolDeps): void;
+export {};

package/dist/tools/plans.js

@@ -0,0 +1,201 @@
+/**
+ * AgentOS plan MCP tools — Phase 5A of
+ * docs/superpowers/plans/2026-05-17-agent-os-memory-reliability.md. Each tool
+ * proxies to `/api/agent-os/{slug}/plans*` on Kynver. Workspace isolation is
+ * enforced server-side via slug-resolved AgentOS context plus service-layer
+ * scope checks — callers do NOT pass userId or agentOsId from here.
+ *
+ * Kept in its own module so server.ts stays small. server.ts calls
+ * `registerPlanTools` with the helpers it already has in scope.
+ */
+import { z } from "zod";
+import { get, post, patch } from "../lib/kynver-client.js";
+const planStatus = z.enum([
+    "draft",
+    "active",
+    "blocked",
+    "complete",
+    "archived",
+    "superseded",
+]);
+const planPriority = z.enum(["low", "normal", "high", "critical"]);
+const planLinkTarget = z.enum([
+    "goal",
+    "project",
+    "task",
+    "memory",
+    "session",
+    "repo",
+    "branch",
+    "commit",
+    "pr",
+    "url",
+    "markdown",
+    "plan",
+]);
+const initialVersionSchema = z
+    .object({
+    title: z.string().optional(),
+    body: z.string().describe("Full plan body (markdown)."),
+    summary: z.string().optional(),
+    changeSummary: z.string().optional(),
+    author: z.string().optional(),
+    sourceRefs: z.unknown().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+})
+    .passthrough();
+export function registerPlanTools({ register, resolveToolSlug, jsonResult, compact, }) {
+    const slugField = z
+        .string()
+        .optional()
+        .describe("AgentOS workspace slug. Omit to use env or the server-discovered primary.");
+    register("agent_os_plan_create", "Create a first-class AgentOS plan with an initial version. Plans are versioned operational artifacts (separate from goals/projects/tasks). `initialVersion.body` is required and becomes the plan's current version. Use `planSlug` for the plan's own stable slug — the workspace `slug` argument is reserved for the AgentOS workspace.", {
+        title: z.string().describe("Human-readable plan title (required)."),
+        summary: z.string().optional(),
+        planSlug: z
+            .string()
+            .optional()
+            .describe("Stable slug for the plan within the AgentOS workspace."),
+        status: planStatus.optional(),
+        priority: planPriority.optional(),
+        owner: z.string().optional(),
+        projectId: z.string().optional(),
+        goalId: z.string().optional(),
+        canonicalKey: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        sourceRefs: z.unknown().optional(),
+        initialVersion: initialVersionSchema.describe("First version snapshot (required). Becomes the plan's current version."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, planSlug, ...rest } = args;
+        const s = await resolveToolSlug(slug);
+        const body = compact({
+            ...rest,
+            ...(planSlug !== undefined ? { slug: planSlug } : {}),
+        });
+        return jsonResult(await post(`/agent-os/${s}/plans`, body));
+    });
+    register("agent_os_plan_list", "List AgentOS plans, optionally filtered by status, projectId, goalId, or canonicalKey.", {
+        status: planStatus.optional(),
+        projectId: z.string().optional(),
+        goalId: z.string().optional(),
+        canonicalKey: 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.projectId)
+            params.set("projectId", args.projectId);
+        if (args.goalId)
+            params.set("goalId", args.goalId);
+        if (args.canonicalKey)
+            params.set("canonicalKey", args.canonicalKey);
+        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}/plans${qs ? `?${qs}` : ""}`));
+    });
+    register("agent_os_plan_get", "Fetch one AgentOS plan with its full version history, current version pointer, and typed links.", { planId: z.string(), slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/plans/${args.planId}`));
+    });
+    register("agent_os_plan_update", "Patch an AgentOS plan's metadata (title, summary, status, priority, owner, project/goal links, canonicalKey). The plan body itself is immutable — use agent_os_plan_add_version to record a new snapshot. Use `planSlug` for the plan's own stable slug.", {
+        planId: z.string(),
+        title: z.string().optional(),
+        summary: z.string().optional(),
+        planSlug: z
+            .string()
+            .optional()
+            .describe("Stable slug for the plan within the AgentOS workspace."),
+        status: planStatus.optional(),
+        priority: planPriority.optional(),
+        owner: z.string().optional(),
+        projectId: z.string().optional(),
+        goalId: z.string().optional(),
+        canonicalKey: z.string().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        sourceRefs: z.unknown().optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, planId, planSlug, ...rest } = args;
+        const s = await resolveToolSlug(slug);
+        const body = compact({
+            ...rest,
+            ...(planSlug !== undefined ? { slug: planSlug } : {}),
+        });
+        return jsonResult(await patch(`/agent-os/${s}/plans/${planId}`, body));
+    });
+    register("agent_os_plan_add_version", "Append an immutable version snapshot to a plan. The new version's versionNumber is one greater than the latest, and (when markCurrent is true, the default) the plan's currentVersionId pointer advances atomically. Use this — not agent_os_plan_update — to record a new plan body.", {
+        planId: z.string(),
+        title: z.string().optional(),
+        body: z.string().describe("Full new version body (markdown)."),
+        summary: z.string().optional(),
+        changeSummary: z.string().optional(),
+        author: z.string().optional(),
+        sourceRefs: z.unknown().optional(),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        markCurrent: z
+            .boolean()
+            .optional()
+            .describe("When true (default), the new version becomes the plan's current version."),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, planId, ...rest } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/plans/${planId}/versions`, compact(rest)));
+    });
+    register("agent_os_plan_mark_current", "Promote an existing version of a plan to be the current version. The version must already belong to the plan.", {
+        planId: z.string(),
+        versionId: z
+            .string()
+            .describe("Existing version id to promote to current."),
+        slug: slugField,
+    }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await post(`/agent-os/${s}/plans/${args.planId}/versions`, {
+            action: "mark_current",
+            versionId: args.versionId,
+        }));
+    });
+    register("agent_os_plan_add_link", "Add a typed link from a plan (and optionally a specific version) to a related goal, project, task, memory, session, repo, branch, commit, PR, URL, markdown file, or other plan. Workspace-owned targets (goal/project/task/memory/session/plan) are validated against the same AgentOS workspace server-side; remote refs (url/repo/branch/commit/pr/markdown) carry metadata only.", {
+        planId: z.string(),
+        planVersionId: z
+            .string()
+            .optional()
+            .describe("Optional version id when the link applies to a specific snapshot."),
+        targetType: planLinkTarget,
+        targetId: z
+            .string()
+            .optional()
+            .describe("AgentOS-owned target id. Required for workspace-owned link types."),
+        targetUrl: z
+            .string()
+            .optional()
+            .describe("URL for remote refs. Either targetId or targetUrl is required."),
+        label: z.string().optional(),
+        relation: z
+            .string()
+            .optional()
+            .describe("Optional free-form relation label (e.g. 'derived_from', 'supersedes')."),
+        metadata: z.record(z.string(), z.unknown()).optional(),
+        slug: slugField,
+    }, async (args) => {
+        const { slug, planId, ...rest } = args;
+        const s = await resolveToolSlug(slug);
+        return jsonResult(await post(`/agent-os/${s}/plans/${planId}/links`, compact(rest)));
+    });
+    register("agent_os_plan_list_links", "List the typed links attached to a plan.", { planId: z.string(), slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/plans/${args.planId}/links`));
+    });
+    register("agent_os_plan_list_versions", "List the version history of a plan in ascending order by versionNumber. agent_os_plan_get already returns versions; use this when you only need the version list.", { planId: z.string(), slug: slugField }, async (args) => {
+        const s = await resolveToolSlug(args.slug);
+        return jsonResult(await get(`/agent-os/${s}/plans/${args.planId}/versions`));
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kynver-app/mcp-agent-os",
-  "version": "0.3.5",
+  "version": "0.3.7",
   "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
   "type": "module",
   "bin": {