@kynver-app/mcp-agent-os 0.3.6 → 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).
@@ -81,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) }],
@@ -119,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')."),
@@ -586,5 +608,9 @@ export function createAgentOsServer() {
     });
     // 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.6",
+  "version": "0.3.7",
   "description": "Kynver Agentic OS MCP server — slug-keyed agent identity, goals, projects, sessions, and long-term memory",
   "type": "module",
   "bin": {