@kynver-app/mcp-agent-os 0.3.63 → 0.3.68

package/dist/context/context-budget-receipt.d.ts

@@ -1,4 +1,4 @@
-import { estimateTokensFromChars, RUNTIME_CONTEXT_BUDGET_RECEIPT_V2_SCHEMA_VERSION, type ContextBudgetReceiptSurface, type RuntimeContextBudgetReceiptV2 } from "@kynver-app/runtime";
+import { estimateTokensFromChars, RUNTIME_CONTEXT_BUDGET_RECEIPT_V2_SCHEMA_VERSION, type ContextBudgetReceiptSurface, type RuntimeContextBudgetReceiptV2 } from "@kynver-app/runtime/server/context-budget-receipt";
 /** MCP tool-context measurement adapter (PR2) — metadata only; does not mutate payloads. */
 export declare function measureMcpToolContextReceipt(payload: unknown, input?: {
     agentOsId?: string | null;

package/dist/context/context-budget-receipt.js

@@ -1,4 +1,4 @@
-import { buildContextBudgetReceiptV2, estimateTokensFromChars, sectionReceiptFromMarkdown, RUNTIME_CONTEXT_BUDGET_RECEIPT_V2_SCHEMA_VERSION, } from "@kynver-app/runtime";
+import { buildContextBudgetReceiptV2, estimateTokensFromChars, sectionReceiptFromMarkdown, RUNTIME_CONTEXT_BUDGET_RECEIPT_V2_SCHEMA_VERSION, } from "@kynver-app/runtime/server/context-budget-receipt";
 const MCP_TOOL_RESULT_BUDGET_BYTES = 12_288;
 function utf8ByteLength(value) {
     return new TextEncoder().encode(JSON.stringify(value)).length;

package/dist/lib/kynver-client.js

@@ -49,8 +49,13 @@ function getHeaders() {
     const userId = ctx?.userId;
     const serviceSecret = process.env.KYNVER_SERVICE_SECRET;
     if (userId) {
+        const runnerToken = process.env.KYNVER_RUNNER_TOKEN?.trim();
+        if (runnerToken) {
+            headers["X-Kynver-Runner-Token"] = runnerToken;
+            return headers;
+        }
         if (!serviceSecret) {
-            throw new Error("X-Kynver-User-Id was set in context but KYNVER_SERVICE_SECRET is missing; refusing to send an unscoped request.");
+            throw new Error("User context requires authentication: set KYNVER_RUNNER_TOKEN (preferred) or KYNVER_SERVICE_SECRET in the MCP server environment.");
         }
         headers["X-Kynver-User-Id"] = userId;
         headers["X-Kynver-Service-Secret"] = serviceSecret;

package/dist/lib/mcp-sse-server.d.ts

@@ -1,4 +1,4 @@
-import { type IncomingMessage } from "node:http";
+import { createServer, type IncomingMessage } from "node:http";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 export declare const MAX_SSE_BODY_BYTES: number;
 export type SessionAuth = {
@@ -40,5 +40,5 @@ type RateLimiter = {
 export declare function createFixedWindowRateLimiter(limit: number, windowMs: number): RateLimiter;
 export declare function parseJsonBody(req: IncomingMessage, maxBytes?: number): Promise<unknown>;
 export declare function validateMcporterServerName(name: string): string;
-export declare function startKynverMcpSseServer(options: StartKynverMcpSseServerOptions): void;
+export declare function startKynverMcpSseServer(options: StartKynverMcpSseServerOptions): ReturnType<typeof createServer>;
 export {};

package/dist/lib/mcp-sse-server.js

@@ -1,10 +1,18 @@
 // @generated — synced from packages/kynver-mcp-sse-lib/src/index.ts via scripts/sync-mcp-sse-server.mjs
 // Do not edit by hand; change the canonical file and re-run the sync script.
 import { createServer } from "node:http";
-import { timingSafeEqual } from "node:crypto";
+import { randomUUID, timingSafeEqual } from "node:crypto";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 export const MAX_SSE_BODY_BYTES = 1 * 1024 * 1024;
 const FORBIDDEN_QUERY_KEYS = ["apiKey", "secret", "userId"];
+const TRUTHY_ENV = new Set(["1", "true", "yes", "on"]);
+function isServiceSecretImpersonationRejectedInProduction() {
+    const override = process.env.KYNVER_ALLOW_SERVICE_SECRET_IMPERSONATION?.trim().toLowerCase();
+    if (override !== undefined && TRUTHY_ENV.has(override))
+        return false;
+    return process.env.NODE_ENV === "production" || process.env.VERCEL_ENV === "production";
+}
 export function headerValue(req, name) {
     const v = req.headers[name];
     return typeof v === "string" ? v : Array.isArray(v) ? (v[0] ?? null) : null;
@@ -121,6 +129,8 @@ function resolveInternalAuth(req, serviceSecret) {
     const internalSecret = headerValue(req, "x-kynver-service-secret");
     if (!internalUserId || !serviceSecret || !internalSecret)
         return null;
+    if (isServiceSecretImpersonationRejectedInProduction())
+        return null;
     if (!timingSafeEqualString(internalSecret, serviceSecret))
         return null;
     return { userId: internalUserId, auth: { kind: "internal", userId: internalUserId } };
@@ -162,13 +172,15 @@ export function startKynverMcpSseServer(options) {
     const serviceSecret = process.env.KYNVER_SERVICE_SECRET ?? "";
     const host = resolveListenHost();
     const sessions = {};
+    const streamableSessions = {};
     // Resource / abuse limits (env-overridable; in-process per server).
     const maxSessions = intFromEnv("MCP_SSE_MAX_SESSIONS", 200);
     const maxSessionsPerUser = intFromEnv("MCP_SSE_MAX_SESSIONS_PER_USER", 20);
     const idleTimeoutMs = intFromEnv("MCP_SSE_IDLE_TIMEOUT_MS", 5 * 60 * 1000);
     const rateLimitPerMin = intFromEnv("MCP_SSE_RATE_LIMIT_PER_MIN", 120);
     const rateLimiter = createFixedWindowRateLimiter(rateLimitPerMin, 60 * 1000);
-    // Close idle SSE sessions so a flood of half-open connections can't pin memory.
+    // Close idle sessions (both transports) so a flood of half-open connections
+    // can't pin memory.
     const idleSweep = setInterval(() => {
         const now = Date.now();
         for (const [sid, entry] of Object.entries(sessions)) {
@@ -177,8 +189,17 @@ export function startKynverMcpSseServer(options) {
                 void entry.transport.close().catch(() => { });
             }
         }
+        for (const [sid, entry] of Object.entries(streamableSessions)) {
+            if (now - entry.lastActivity > idleTimeoutMs) {
+                delete streamableSessions[sid];
+                void entry.transport.close().catch(() => { });
+            }
+        }
     }, 60 * 1000);
     idleSweep.unref?.();
+    const activeSessionCount = () => Object.keys(sessions).length + Object.keys(streamableSessions).length;
+    const activeSessionCountForUser = (userId) => Object.values(sessions).filter((s) => s.userId === userId).length +
+        Object.values(streamableSessions).filter((s) => s.userId === userId).length;
     const httpServer = createServer(async (req, res) => {
         const url = parseUrl(req, port);
         const path = url.pathname;
@@ -215,14 +236,14 @@ export function startKynverMcpSseServer(options) {
                 });
                 return;
             }
-            // Connection caps — bound total + per-user concurrent SSE sessions so an
-            // authenticated caller can't exhaust memory/sockets by opening many.
-            const allEntries = Object.values(sessions);
-            if (allEntries.length >= maxSessions) {
+            // Connection caps — bound total + per-user concurrent sessions (across
+            // both transports) so an authenticated caller can't exhaust
+            // memory/sockets by opening many.
+            if (activeSessionCount() >= maxSessions) {
                 json(res, 503, { error: "Server at capacity. Try again shortly." });
                 return;
             }
-            if (allEntries.filter((s) => s.userId === userId).length >= maxSessionsPerUser) {
+            if (activeSessionCountForUser(userId) >= maxSessionsPerUser) {
                 json(res, 429, { error: "Too many concurrent connections for this account." });
                 return;
             }
@@ -266,6 +287,146 @@ export function startKynverMcpSseServer(options) {
             }
             return;
         }
+        // Streamable HTTP transport (MCP spec 2025-03-26+) — the transport modern
+        // connector clients (Grok, ChatGPT, Gemini, Claude) expect for remote
+        // servers. One path, three verbs: POST carries JSON-RPC (initialize opens a
+        // session; the response's mcp-session-id header identifies it), GET opens
+        // the standalone server→client SSE stream, DELETE terminates the session.
+        // Auth model mirrors the legacy /sse pair: credentials are verified on the
+        // initialize POST, bound to the session, and every subsequent request must
+        // re-present the same credentials.
+        if (path === "/mcp") {
+            if (req.method !== "POST" && req.method !== "GET" && req.method !== "DELETE") {
+                res.writeHead(405, { "Content-Type": "application/json", Allow: "GET, POST, DELETE" });
+                res.end(JSON.stringify({ error: "Method not allowed" }));
+                return;
+            }
+            if (hasForbiddenQueryAuth(url)) {
+                json(res, 400, {
+                    error: "Internal auth via query params is not allowed. Use X-Kynver-User-Id and X-Kynver-Service-Secret headers.",
+                });
+                return;
+            }
+            const sessionId = headerValue(req, "mcp-session-id");
+            if (sessionId) {
+                const entry = streamableSessions[sessionId];
+                if (!entry) {
+                    // 404 (not 400) per spec so a well-behaved client re-initializes.
+                    json(res, 404, { error: "Unknown or expired MCP session. Re-initialize." });
+                    return;
+                }
+                if (!verifyPostAuth(req, url, entry.auth, serviceSecret)) {
+                    json(res, 401, {
+                        error: "Unauthorized. Re-send the same credentials used to initialize the MCP session.",
+                    });
+                    return;
+                }
+                if (!rateLimiter.check(`msg:${entry.userId}`)) {
+                    json(res, 429, { error: "Too many requests. Slow down and retry." });
+                    return;
+                }
+                entry.lastActivity = Date.now();
+                try {
+                    const body = req.method === "POST" ? await parseJsonBody(req) : undefined;
+                    await options.requestContext.run({ userId: entry.userId }, async () => {
+                        await entry.transport.handleRequest(req, res, body);
+                    });
+                }
+                catch (error) {
+                    if (!res.headersSent) {
+                        json(res, 400, {
+                            error: error instanceof Error ? error.message : "Invalid request body",
+                        });
+                    }
+                }
+                return;
+            }
+            // No session header — only an initialize POST may open a session. (The
+            // transport itself rejects a sessionless non-initialize POST with 400.)
+            if (req.method !== "POST") {
+                json(res, 400, {
+                    error: "Missing mcp-session-id header. Open a session with an initialize POST first.",
+                });
+                return;
+            }
+            // Pre-auth rate limit by client IP (we don't know the user yet).
+            if (!rateLimiter.check(`mcp:${clientIp(req)}`)) {
+                json(res, 429, { error: "Too many requests. Slow down and retry." });
+                return;
+            }
+            let userId = null;
+            let auth = null;
+            const internal = serviceSecret ? resolveInternalAuth(req, serviceSecret) : null;
+            if (internal) {
+                userId = internal.userId;
+                auth = internal.auth;
+            }
+            else {
+                const apiKey = bearerToken(req);
+                if (apiKey) {
+                    userId = await resolveUserFromApiKey(baseUrl, apiKey);
+                    if (userId)
+                        auth = { kind: "apiKey", apiKey };
+                }
+            }
+            if (!userId || !auth) {
+                json(res, 401, {
+                    error: "Unauthorized. Pass API key via Authorization: Bearer <key> or internal X-Kynver-User-Id + X-Kynver-Service-Secret headers.",
+                });
+                return;
+            }
+            if (activeSessionCount() >= maxSessions) {
+                json(res, 503, { error: "Server at capacity. Try again shortly." });
+                return;
+            }
+            if (activeSessionCountForUser(userId) >= maxSessionsPerUser) {
+                json(res, 429, { error: "Too many concurrent connections for this account." });
+                return;
+            }
+            let body;
+            try {
+                body = await parseJsonBody(req);
+            }
+            catch (error) {
+                json(res, 400, {
+                    error: error instanceof Error ? error.message : "Invalid request body",
+                });
+                return;
+            }
+            const boundUserId = userId;
+            const boundAuth = auth;
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (sid) => {
+                    streamableSessions[sid] = {
+                        transport,
+                        userId: boundUserId,
+                        auth: boundAuth,
+                        lastActivity: Date.now(),
+                    };
+                    console.log(`[MCP HTTP] New session (${options.label}, user: ${boundUserId.slice(0, 8)}...)`);
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId)
+                    delete streamableSessions[transport.sessionId];
+            };
+            const server = await options.createMcpServer();
+            await server.connect(transport);
+            try {
+                await options.requestContext.run({ userId: boundUserId }, async () => {
+                    await transport.handleRequest(req, res, body);
+                });
+            }
+            catch (error) {
+                if (!res.headersSent) {
+                    json(res, 400, {
+                        error: error instanceof Error ? error.message : "Invalid request",
+                    });
+                }
+            }
+            return;
+        }
         if (req.method === "GET" && path === "/health") {
             res.writeHead(200, { "Content-Type": "text/plain" });
             res.end("ok");
@@ -276,4 +437,5 @@ export function startKynverMcpSseServer(options) {
     httpServer.listen(port, host, () => {
         console.log(`[MCP SSE] ${options.label} listening on ${host}:${port}`);
     });
+    return httpServer;
 }

package/dist/tools/context-preview.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { buildChatMemoryShadowPreview, buildLegacyChatMemorySection, } from "@kynver-app/runtime";
+import { buildChatMemoryShadowPreview, buildLegacyChatMemorySection, } from "@kynver-app/runtime/server/context-budget-receipt";
 function envTruthy(value) {
     if (!value)
         return false;

package/dist/tools/graph.js

@@ -125,10 +125,18 @@ export function registerGraphTools({ register, resolveToolSlug, jsonResult }) {
         grantToken: z
             .string()
             .describe("Signed expansion grant (kve:g:…) bound to this graph handle and envelope."),
-        purpose: z.string().describe("Why expansion is requested (audit-bound)."),
+        purpose: z
+            .string()
+            .describe("Informational only — the server enforces the graph-expansion purpose bound into the grant and ignores this value."),
         envelopeId: z.string().describe("Active context envelope id binding this expansion."),
         asOf: z.string().optional().describe("Optional UTC ISO as-of instant for temporal filtering."),
-        maxDepth: z.number().int().min(1).max(2).optional(),
+        maxDepth: z
+            .number()
+            .int()
+            .min(1)
+            .max(1)
+            .optional()
+            .describe("Traversal depth; the server caps expansion depth at 1."),
         maxNodes: z.number().int().min(1).max(36).optional(),
     }, async (args) => {
         const slug = await resolveToolSlug(args.slug);

package/dist/tools/workbench.js

@@ -19,6 +19,20 @@ const commandKind = z.enum([
     "yield",
     "take",
 ]);
+/** Keep in sync with COMMAND_CENTER_VIEW_MODES in command-center-url-state.ts */
+const workbenchView = z.enum([
+    "overview",
+    "flow",
+    "marketing",
+    "projects",
+    "tasks",
+    "goals",
+    "dq",
+    "web",
+    "review",
+    "system",
+    "health",
+]);
 export function registerWorkbenchTools({ register, resolveToolSlug, jsonResult, }) {
     register("agent_os_workbench_query", [
         "Read the operator's current workbench focus (view mode, drilldown stack, focused entity)",
@@ -37,14 +51,26 @@ export function registerWorkbenchTools({ register, resolveToolSlug, jsonResult,
     ].join(" "), {
         slug: z.string().optional(),
         kind: commandKind,
-        view: z.enum(["projects", "tasks", "goals", "dq", "web"]).optional(),
+        view: workbenchView.optional(),
         target: z.string().optional().describe("EntityRef e.g. task:<id>, plan:<id>"),
         push: z.boolean().optional().describe("For drill: push onto stack (default true)"),
-        panel: z.string().optional(),
+        panel: z
+            .string()
+            .optional()
+            .describe("For open_panel: plan-detail | task-detail | goal-detail | project-detail | dq | lane-experts | graph-rail | system-console | system-group:<groupId> | system:<panelId>"),
         tab: z.string().optional(),
         personaSlug: z.string().optional(),
         planId: z.string().optional(),
         prUrl: z.string().optional(),
+        refs: z
+            .array(z.string())
+            .optional()
+            .describe("For highlight: EntityRefs to point at (max 20) — renders a visible callout"),
+        ttlMs: z
+            .number()
+            .optional()
+            .describe("For highlight: callout duration ms (2000–120000, default 12000)"),
+        note: z.string().optional().describe("For annotate: note text (≤500 chars) shown with target"),
         chip: z.string().optional(),
         review: z.string().optional(),
         q: z.string().optional(),
@@ -81,6 +107,12 @@ export function registerWorkbenchTools({ register, resolveToolSlug, jsonResult,
             case "open_pr_history":
                 body.open_pr_history = { planId: args.planId, prUrl: args.prUrl };
                 break;
+            case "highlight":
+                body.highlight = { refs: args.refs, ttlMs: args.ttlMs };
+                break;
+            case "annotate":
+                body.annotate = { target: args.target, note: args.note };
+                break;
             case "filter":
                 body.filter = { chip: args.chip, review: args.review, q: args.q };
                 break;

package/package.json

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