@kynver-app/mcp-agent-os 0.3.9 → 0.3.13

package/dist/server.js

@@ -13,6 +13,7 @@ import { registerPlanTools } from "./tools/plans.js";
 import { registerPlanProgressTools } from "./tools/plan-progress.js";
 import { registerTaskTools } from "./tools/tasks.js";
 import { registerActionRequiredTools } from "./tools/action-required.js";
+import { registerGraphTools } from "./tools/graph.js";
 function jsonResult(data) {
     return {
         content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
@@ -614,5 +615,7 @@ export function createAgentOsServer() {
     registerPlanProgressTools({ register, resolveToolSlug, jsonResult, compact });
     // Action Required inbox: agent_os_ask_human + agent_os_await_action (slice 1).
     registerActionRequiredTools({ register, jsonResult, compact });
+    // Operational graph insights — Agent SEE (agent_os_graph_query).
+    registerGraphTools({ register, resolveToolSlug, jsonResult });
     return server;
 }

package/dist/tools/graph.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Operational-graph MCP tools — "Agent SEE" (graph M6).
+ *
+ * agent_os_graph_query proxies to GET `/api/agent-os/{slug}/graph/query`, which
+ * returns server-computed insights (bottlenecks, per-owner load, orphans) over
+ * the operational graph. Read-only; the Kynver route enforces session +
+ * workspace scope. Kept in its own module so server.ts stays slim.
+ */
+type ToolResult = {
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent?: unknown;
+};
+export interface GraphToolDeps {
+    register: (name: string, description: string, inputSchema: Record<string, unknown>, cb: (args: any) => any) => void;
+    resolveToolSlug: (explicitSlug?: string) => Promise<string>;
+    jsonResult: (data: unknown) => ToolResult;
+}
+export declare function registerGraphTools({ register, resolveToolSlug, jsonResult }: GraphToolDeps): void;
+export {};

package/dist/tools/graph.js

@@ -0,0 +1,91 @@
+/**
+ * Operational-graph MCP tools — "Agent SEE" (graph M6).
+ *
+ * agent_os_graph_query proxies to GET `/api/agent-os/{slug}/graph/query`, which
+ * returns server-computed insights (bottlenecks, per-owner load, orphans) over
+ * the operational graph. Read-only; the Kynver route enforces session +
+ * workspace scope. Kept in its own module so server.ts stays slim.
+ */
+import { z } from "zod";
+import { get, post } from "../lib/kynver-client.js";
+export function registerGraphTools({ register, resolveToolSlug, jsonResult }) {
+    register("agent_os_graph_query", [
+        "Read the operational graph's computed insights for the AgentOS:",
+        "top bottlenecks (highest downstream impact among still-active or blocked work),",
+        "per-owner load (who is carrying work and who is blocked), and orphaned tasks.",
+        "Use this to answer questions like 'what is my biggest bottleneck',",
+        "'what is blocking project X', 'what is <persona> working on', or 'what is unassigned'.",
+        "Read-only — modifies nothing. Returns { available, generatedAt, stats, insights }.",
+    ].join(" "), {
+        slug: z
+            .string()
+            .optional()
+            .describe("AgentOS slug. Defaults to the configured env/primary AgentOS."),
+        bottlenecks: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("Max bottleneck rows to return (default 10)."),
+        owners: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe("Max per-owner load rows to return (default 12)."),
+        orphans: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .describe("Max orphan rows to return (default 25)."),
+    }, async (args) => {
+        const slug = await resolveToolSlug(args.slug);
+        const qs = new URLSearchParams();
+        if (args.bottlenecks !== undefined)
+            qs.set("bottlenecks", String(args.bottlenecks));
+        if (args.owners !== undefined)
+            qs.set("owners", String(args.owners));
+        if (args.orphans !== undefined)
+            qs.set("orphans", String(args.orphans));
+        const suffix = qs.toString() ? "?" + qs.toString() : "";
+        return jsonResult(await get(`/agent-os/${slug}/graph/query${suffix}`));
+    });
+    register("agent_os_graph_view", [
+        "Steer the human's open 3D web view (shared focus) — fly the camera to a node, filter, or reset,",
+        "so you and the user are provably looking at the same thing.",
+        "kind=focus needs nodeId (operational graph id, e.g. 'task:abc'); kind=filter sets which type/status",
+        "buckets are hidden; kind=reset clears focus + filters; kind=highlight focuses without isolating.",
+        "Takes effect only while the user has the 3D Web tab open (delivered over SSE).",
+        "Requires Redis in multi-instance/serverless prod to fan out; single-instance dev works without it.",
+    ].join(" "), {
+        slug: z.string().optional().describe("AgentOS slug. Defaults to env/primary."),
+        kind: z
+            .enum(["focus", "filter", "reset", "highlight"])
+            .describe("focus | highlight (camera) · filter (hide buckets) · reset (clear)."),
+        nodeId: z
+            .string()
+            .optional()
+            .describe("Target operational-graph node id for focus/highlight (e.g. 'task:abc123')."),
+        hiddenKinds: z
+            .array(z.string())
+            .optional()
+            .describe("For kind=filter: node kinds to hide (e.g. ['repo_file']). [] clears."),
+        hiddenStatuses: z
+            .array(z.string())
+            .optional()
+            .describe("For kind=filter: statuses to hide (e.g. ['done']). [] clears."),
+    }, async (args) => {
+        const slug = await resolveToolSlug(args.slug);
+        return jsonResult(await post(`/agent-os/${slug}/graph/view`, {
+            kind: args.kind,
+            nodeId: args.nodeId,
+            hiddenKinds: args.hiddenKinds,
+            hiddenStatuses: args.hiddenStatuses,
+            source: "agent",
+        }));
+    });
+}

package/dist/tools/plans.js

@@ -18,7 +18,11 @@ const planStatus = z.enum([
     "archived",
     "superseded",
 ]);
-const planPriority = z.enum(["low", "normal", "high", "critical"]);
+const planPriority = z
+    .enum(["low", "normal", "high", "critical"])
+    .describe("Priority — default 'normal'. Most plans are 'normal'; routine is 'low'. Use 'high' only for genuinely " +
+    "urgent+important plans and 'critical' ONLY for true emergencies blocking the mission now (very few). " +
+    "Over-tagging destroys the signal — if everything is critical, nothing is.");
 const planLinkTarget = z.enum([
     "goal",
     "project",

package/dist/tools/tasks.js

@@ -7,17 +7,32 @@
  */
 import { z } from "zod";
 import { get, post, patch } from "../lib/kynver-client.js";
-const taskStatus = z.enum([
+const taskStatus = z
+    .enum([
     "queued",
+    "ready",
     "running",
+    "waiting",
+    "scheduled",
     "blocked",
     "needs_input",
     "awaiting_review",
     "done",
     "failed",
     "cancelled",
-]);
-const taskPriority = z.enum(["low", "normal", "high", "critical"]);
+])
+    .describe("Work-state lifecycle. `ready` = admitted, can start now (the real 'queued' — which survives as a legacy alias). " +
+    "`running` = an executor holds a live lease. `waiting` = gated on upstream tasks (set dependsOnTaskIds; auto-promotes " +
+    "to ready when they're all done). `scheduled` = deferred to a time (set scheduledFor; auto-promotes to ready when it " +
+    "passes). `blocked`/`needs_input` = a human must resolve. `awaiting_review` = review gate open. Don't hand-set " +
+    "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' for genuine urgency. If everything is " +
+    "critical, nothing is — keep most tasks at normal/low.");
 const taskExecutor = z.enum(["inline", "harness", "acp", "manual"]);
 const taskEventType = z.enum([
     "created",
@@ -36,12 +51,23 @@ const personaSlug = z
     .nullable()
     .optional()
     .describe("Lane-expert worker slug to attribute the task to, or null to clear/filter unassigned tasks.");
+const scheduledFor = z
+    .string()
+    .nullable()
+    .optional()
+    .describe("ISO-8601 timestamp to defer the task to. A future time creates the task as `scheduled`; the operator loop " +
+    "auto-promotes it to `ready` once the time passes. null clears the schedule.");
+const dependsOnTaskIds = z
+    .array(z.string())
+    .optional()
+    .describe("Upstream task ids this task waits on. Creates the task as `waiting`; the operator loop auto-promotes it to " +
+    "`ready` once every listed task is `done` (a failed/cancelled upstream keeps it waiting).");
 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).", {
+    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)."),
         description: z.string().optional(),
         priority: taskPriority.optional(),
@@ -51,6 +77,8 @@ export function registerTaskTools({ register, resolveToolSlug, jsonResult, compa
         goalId: z.string().optional(),
         projectId: z.string().optional(),
         personaSlug,
+        scheduledFor,
+        dependsOnTaskIds,
         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,
@@ -86,7 +114,7 @@ export function registerTaskTools({ register, resolveToolSlug, jsonResult, compa
         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.", {
+    register("agent_os_task_update", "Patch an AgentTask: status, priority, executor, links, schedule (scheduledFor), dependencies (dependsOnTaskIds), 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(),
@@ -98,6 +126,8 @@ export function registerTaskTools({ register, resolveToolSlug, jsonResult, compa
         goalId: z.string().optional(),
         projectId: z.string().optional(),
         personaSlug,
+        scheduledFor,
+        dependsOnTaskIds,
         lastSummary: z.string().optional().describe("Latest progress summary."),
         blocker: z.string().optional(),
         branch: z.string().optional(),

package/package.json

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