@kynver-app/mcp-agent-os 0.3.32 → 0.3.34

package/README.md

@@ -50,6 +50,7 @@ AgentTask board (Phase 2 — batch 1 CRUD + batch 1.5 steering/lease):
 - `agent_os_task_abort`
 - `agent_os_task_claim`
 - `agent_os_task_renew_lease`
+- `agent_os_task_operator_priority`
 
 AgentPlan first-class plans (Phase 5A — versioned operational artifacts
 separate from goals/projects/tasks):

package/dist/__tests__/agent-context.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/__tests__/agent-context.test.js

@@ -0,0 +1,36 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { resolveAgentContext } from "../server.js";
+const OLD_CONTEXT = process.env.KYNVER_AGENT_CONTEXT;
+const OLD_OS_CONTEXT = process.env.KYNVER_AGENT_OS_CONTEXT;
+afterEach(() => {
+    if (OLD_CONTEXT === undefined)
+        delete process.env.KYNVER_AGENT_CONTEXT;
+    else
+        process.env.KYNVER_AGENT_CONTEXT = OLD_CONTEXT;
+    if (OLD_OS_CONTEXT === undefined)
+        delete process.env.KYNVER_AGENT_OS_CONTEXT;
+    else
+        process.env.KYNVER_AGENT_OS_CONTEXT = OLD_OS_CONTEXT;
+});
+describe("resolveAgentContext", () => {
+    it("prefers explicit agentContext over environment defaults", () => {
+        process.env.KYNVER_AGENT_CONTEXT = "forge";
+        process.env.KYNVER_AGENT_OS_CONTEXT = "ghost";
+        expect(resolveAgentContext(" hermes-forge ")).toBe("hermes-forge");
+    });
+    it("defaults to KYNVER_AGENT_CONTEXT when omitted", () => {
+        process.env.KYNVER_AGENT_CONTEXT = " forge ";
+        process.env.KYNVER_AGENT_OS_CONTEXT = "ghost";
+        expect(resolveAgentContext()).toBe("forge");
+    });
+    it("falls back to KYNVER_AGENT_OS_CONTEXT for compatibility", () => {
+        delete process.env.KYNVER_AGENT_CONTEXT;
+        process.env.KYNVER_AGENT_OS_CONTEXT = " hermes-forge ";
+        expect(resolveAgentContext()).toBe("hermes-forge");
+    });
+    it("omits agentContext when neither explicit nor environment context is set", () => {
+        delete process.env.KYNVER_AGENT_CONTEXT;
+        delete process.env.KYNVER_AGENT_OS_CONTEXT;
+        expect(resolveAgentContext("   ")).toBeUndefined();
+    });
+});

package/dist/lib/mcp-json-result.d.ts

@@ -0,0 +1,12 @@
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: unknown;
+};
+/** Default MCP text result — pretty JSON for small payloads. */
+export declare function jsonResult(data: unknown): ToolResult;
+/** Truncation-safe MCP result — priority keys serialize first. */
+export declare function jsonResultOrdered(data: Record<string, unknown>, priorityKeys: readonly string[]): ToolResult;
+export {};

package/dist/lib/mcp-json-result.js

@@ -0,0 +1,30 @@
+function orderedStringifyForMcp(value, priorityKeys) {
+    const ordered = {};
+    const seen = new Set();
+    for (const key of priorityKeys) {
+        if (key in value) {
+            ordered[key] = value[key];
+            seen.add(key);
+        }
+    }
+    for (const [key, val] of Object.entries(value)) {
+        if (!seen.has(key))
+            ordered[key] = val;
+    }
+    return JSON.stringify(ordered, null, 2);
+}
+/** Default MCP text result — pretty JSON for small payloads. */
+export function jsonResult(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        structuredContent: data,
+    };
+}
+/** Truncation-safe MCP result — priority keys serialize first. */
+export function jsonResultOrdered(data, priorityKeys) {
+    const text = orderedStringifyForMcp(data, priorityKeys);
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: data,
+    };
+}

package/dist/server.d.ts

@@ -7,4 +7,5 @@
  * `GET /api/agent-os` `{ primarySlug }` → list first item → legacy `"ghost"`.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function resolveAgentContext(explicitAgentContext?: string): string | undefined;
 export declare function createAgentOsServer(): McpServer;

package/dist/server.js

@@ -36,6 +36,13 @@ function compact(source) {
     return out;
 }
 const MCP_LEGACY_SLUG_FALLBACK = "ghost";
+export function resolveAgentContext(explicitAgentContext) {
+    const explicit = explicitAgentContext?.trim();
+    if (explicit)
+        return explicit;
+    const fromEnv = process.env.KYNVER_AGENT_CONTEXT?.trim() || process.env.KYNVER_AGENT_OS_CONTEXT?.trim() || "";
+    return fromEnv || undefined;
+}
 export function createAgentOsServer() {
     const server = new McpServer({ name: "kynver-mcp-agent-os", version: PACKAGE_VERSION }, { capabilities: { tools: {} } });
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -79,6 +86,14 @@ export function createAgentOsServer() {
         .enum(["operator", "customer"])
         .optional()
         .describe("Response shape for memory reads. Owners/env admins may pass operator for full diagnostics or customer to preview grantee-safe JSON. Grantees always receive customer-safe fields regardless of this flag.");
+    const contextProjectionField = z
+        .enum(["brief", "full"])
+        .optional()
+        .describe("Response shape. Default brief returns compact identity/current-work context with follow-up hints. full returns the legacy broad stats payload and can be large/truncation-prone.");
+    const agentContextField = z
+        .string()
+        .optional()
+        .describe("Active agent/runtime/persona context within the shared AgentOS workspace, e.g. ghost, forge, or hermes-forge. Do not use slug for this; slug selects the workspace.");
     const sourceRefSchema = z
         .object({
         type: z
@@ -130,9 +145,15 @@ export function createAgentOsServer() {
         sourceRefs: z.array(sourceRefSchema).optional(),
     })
         .passthrough();
-    register("agent_os_get_context", "Get the agent's full Agentic-OS state in one call: identity, open goals, active projects with current focus/next-actions/blockers, recent sessions, contacts, and long-term memory stats. Use at session start instead of reading SOUL.md / USER.md / MEMORY.md.", { slug: slugField }, async (args) => {
+    register("agent_os_get_context", "Get compact startup context: identity/Soul-equivalent, key preferences, current-work pointers, memory stats, and follow-up instructions. Default brief stays small; projection=full returns the legacy broad stats payload. Pass agentContext for persona-specific context inside a shared workspace.", { slug: slugField, projection: contextProjectionField, agentContext: agentContextField }, async (args) => {
         const s = await resolveToolSlug(args.slug);
-        return jsonResult(await get(`/agent-os/${s}/stats`));
+        const params = new URLSearchParams();
+        params.set("projection", args.projection === "full" ? "full" : "brief");
+        const agentContext = resolveAgentContext(args.agentContext);
+        if (agentContext) {
+            params.set("agentContext", agentContext);
+        }
+        return jsonResult(await get(`/agent-os/${s}/stats?${params}`));
     });
     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."),

package/dist/tools/command-center.d.ts

@@ -6,7 +6,7 @@
  *
  * agent_os_command_center_dashboard_contract_get proxies to
  * `.../command-center/dashboard-contract` — slim verification payload (counts,
- * packageVersionHealth, runtime capacity, activePlanRollups) without graph/hierarchy.
+ * packageVersionHealth, runtime capacity, activePlanRollups, blockerSlo) without graph/hierarchy.
  */
 type ToolResult = {
     content: {

package/dist/tools/command-center.js

@@ -6,10 +6,38 @@
  *
  * agent_os_command_center_dashboard_contract_get proxies to
  * `.../command-center/dashboard-contract` — slim verification payload (counts,
- * packageVersionHealth, runtime capacity, activePlanRollups) without graph/hierarchy.
+ * packageVersionHealth, runtime capacity, activePlanRollups, blockerSlo) without graph/hierarchy.
  */
 import { z } from "zod";
 import { get } from "../lib/kynver-client.js";
+import { jsonResultOrdered } from "../lib/mcp-json-result.js";
+const COMMAND_CENTER_MCP_PRIORITY_KEYS = [
+    "agentReadable",
+    "resultContract",
+    "agentOsId",
+    "rollupVersion",
+    "generatedAt",
+    "headsUp",
+    "runningTasks",
+    "nextActions",
+    "followUps",
+    "countSnapshot",
+    "readiness",
+    "attention",
+    "runtime",
+    "packageVersionHealth",
+    "dailyLandedPrs",
+    "usefulProgress",
+    "usefulProgressLedger",
+    "reviewLanes",
+    "activePlanRollups",
+    "tasksPreview",
+    "unparentedTasksPreview",
+    "harnessRunsPreview",
+    "freshness",
+    "sourceFreshness",
+    "dashboard",
+];
 async function resolveAgentOsId(slug) {
     const row = await get(`/agent-os/${encodeURIComponent(slug)}`);
     const id = typeof row.id === "string" ? row.id.trim() : "";
@@ -25,9 +53,10 @@ export function registerCommandCenterTools({ register, resolveToolSlug, jsonResu
         "prReadyNotifications (journal pr_ready events), dailyLandedPrs (journal merge counts:",
         "today/yesterday, rolling 24h/48h, pace + agentReadable summary), runtime capacity, and",
         "packageVersionHealth (managed npm alignment for @kynver-app/runtime).",
-        "Includes `countSnapshot` (canonical header-chip / saved-view / review-lane counts — same",
-        "contract the dashboard badges use). For a compact runtime verification payload without",
-        "operationalGraph/hierarchy, use agent_os_command_center_dashboard_contract_get.",
+        "Default projection=compact returns a tiny navigable brief (<12k UTF-8): heads-up counts,",
+        "capped running tasks, top next actions/blockers, and follow-up tool hints. Deep detail",
+        "requires agent_os_task_get, agent_os_plan_get, agent_os_tasks_list, or graph tools.",
+        "Pass projection=full only for admin/debug (expensive, truncation-prone browser rollup).",
         "Same aggregate as the browser Command Center. Omit slug to use env/primary workspace;",
         "pass agentOsId when already known from a prior identity fetch.",
     ].join(" "), {
@@ -51,6 +80,10 @@ export function registerCommandCenterTools({ register, resolveToolSlug, jsonResu
             .number()
             .optional()
             .describe("Max harness runs in the rollup (server cap 200)."),
+        projection: z
+            .enum(["compact", "full"])
+            .optional()
+            .describe("Response shape. Default compact — tiny brief flight-board (<12k). Use full only for admin/debug."),
     }, async (args) => {
         const slug = await resolveToolSlug(args.slug);
         const agentOsId = typeof args.agentOsId === "string" && args.agentOsId.trim()
@@ -65,14 +98,19 @@ export function registerCommandCenterTools({ register, resolveToolSlug, jsonResu
         if (typeof args.harnessLimit === "number" && Number.isFinite(args.harnessLimit)) {
             qs.set("harnessLimit", String(args.harnessLimit));
         }
+        const projection = args.projection === "full" ? "full" : "compact";
+        qs.set("projection", projection);
         const suffix = qs.toString() ? `?${qs.toString()}` : "";
-        return jsonResult(await get(`/agent-os/by-id/${encodeURIComponent(agentOsId)}/command-center${suffix}`));
+        const payload = await get(`/agent-os/by-id/${encodeURIComponent(agentOsId)}/command-center${suffix}`);
+        if (projection === "compact") {
+            return jsonResultOrdered(payload, COMMAND_CENTER_MCP_PRIORITY_KEYS);
+        }
+        return jsonResult(payload);
     });
     register("agent_os_command_center_dashboard_contract_get", [
-        "Fetch the slim Command Center dashboard contract for runtime verification:",
-        "countSnapshot, readiness, packageVersionHealth, runtime capacity, activePlanRollups,",
-        "and review-lane totals — same sources as the browser dashboard badges, without",
-        "operationalGraph or hierarchy payloads (avoids MCP truncation on large boards).",
+        "Fetch the Command Center dashboard MCP brief (default projection=mcp): same tiny flight-board",
+        "as agent_os_command_center_get compact — heads-up counts, running tasks, next actions, follow-ups.",
+        "Pass projection=slim only when you need the full dashboard verification DTO (large on big boards).",
     ].join(" "), {
         slug: z
             .string()
@@ -90,6 +128,10 @@ export function registerCommandCenterTools({ register, resolveToolSlug, jsonResu
             .number()
             .optional()
             .describe("Max tasks to load when building counts (server cap 10000)."),
+        projection: z
+            .enum(["mcp", "slim"])
+            .optional()
+            .describe("mcp (default) — tiny brief. slim — full dashboard verification DTO (countSnapshot, activePlanRollups, …)."),
     }, async (args) => {
         const slug = await resolveToolSlug(args.slug);
         const agentOsId = typeof args.agentOsId === "string" && args.agentOsId.trim()
@@ -101,7 +143,13 @@ export function registerCommandCenterTools({ register, resolveToolSlug, jsonResu
         if (typeof args.limit === "number" && Number.isFinite(args.limit)) {
             qs.set("limit", String(args.limit));
         }
+        const projection = args.projection === "slim" ? "slim" : "mcp";
+        qs.set("projection", projection === "slim" ? "slim" : "mcp");
         const suffix = qs.toString() ? `?${qs.toString()}` : "";
-        return jsonResult(await get(`/agent-os/by-id/${encodeURIComponent(agentOsId)}/command-center/dashboard-contract${suffix}`));
+        const payload = await get(`/agent-os/by-id/${encodeURIComponent(agentOsId)}/command-center/dashboard-contract${suffix}`);
+        if (projection === "mcp") {
+            return jsonResultOrdered(payload, COMMAND_CENTER_MCP_PRIORITY_KEYS);
+        }
+        return jsonResult(payload);
     });
 }

package/dist/tools/tasks.js

@@ -27,17 +27,15 @@ const taskStatus = z
     "ready→running; the dispatcher/executor lease owns that.");
 const taskPriority = z
     .enum(["low", "normal", "high", "critical"])
-    .describe("Priority — default 'normal'. Create coding/implementation tasks as 'normal' (routine/cleanup 'low'); " +
-    "do NOT inherit the parent plan's priority — a task on a critical plan is still 'normal'. A task only " +
-    "becomes 'critical' once it is actively BLOCKING progress (and the system already marks blocked tasks " +
-    "critical automatically). Reserve manual 'high'/'critical' only when Will explicitly asked or there is a " +
-    "live production/security incident — pass priorityEscalationReason quoting him or the incident. The server " +
-    "downgrades unsolicited high/critical to normal. If everything is critical, nothing is — keep most tasks at normal/low.");
+    .describe("Priority is a worker-capacity queue signal, not importance. Default 'normal' (cleanup 'low'). " +
+    "Do NOT inherit plan/goal priority. Use 'high' only when harness workers are saturated and ready work waits for slots. " +
+    "Use 'critical' only for live production/security incidents — pass priorityEscalationReason or cite in title/description. " +
+    "When slots are free, omit priority and dispatch at normal. The API downgrades importance-style high/critical.");
 const priorityEscalationReason = z
     .string()
     .optional()
-    .describe("Required when setting priority to high/critical: quote Will's words or name the live incident. " +
-    "Without this (and without explicit escalation in title/description), the API coerces to normal.");
+    .describe("Required for critical: quote the requesting user or name the live production/security incident. " +
+    "High does not use this field — high requires worker-capacity contention at create time.");
 const taskExecutor = z.enum(["inline", "harness", "acp", "manual"]);
 const taskEventType = z.enum([
     "created",
@@ -72,8 +70,10 @@ export function registerTaskTools({ register, resolveToolSlug, jsonResult, compa
         .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. New tasks start `ready` (dispatchable now) unless you defer them: pass scheduledFor for a timed start (→ `scheduled`) or dependsOnTaskIds to gate on upstream work (→ `waiting`); both auto-promote to `ready` when their gate clears. 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)."),
+    register("agent_os_task_create", "Create an AgentTask on the board. New tasks start `ready` (dispatchable now) unless you defer them: pass scheduledFor for a timed start (→ `scheduled`) or dependsOnTaskIds to gate on upstream work (→ `waiting`); both auto-promote to `ready` when their gate clears. 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). Do NOT create closeout-only bookkeeping tasks whose purpose is merely to close/reconcile/clean up another task — complete/update/block/cancel the existing task (or spawn a child only for genuine unresolved implementation work).", {
+        title: z
+            .string()
+            .describe("Short task title (required). Never a closeout-only sweep — mutate/close the existing task instead."),
         description: z.string().optional(),
         priority: taskPriority.optional(),
         priorityEscalationReason,
@@ -126,6 +126,7 @@ export function registerTaskTools({ register, resolveToolSlug, jsonResult, compa
         description: z.string().optional(),
         status: taskStatus.optional(),
         priority: taskPriority.optional(),
+        priorityEscalationReason,
         executor: taskExecutor.optional(),
         executorRef: z.string().optional(),
         parentTaskId: z.string().optional(),

package/package.json

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