@agentvalet/mcp-server 1.8.0 → 1.12.0

package/README.md

@@ -59,6 +59,18 @@ Add to your `.mcp.json` or equivalent:
 | `report_self_diagnostic` | JWT | Lodge a self-report (error/warning/info) with the owner |
 | `agent_register` | None | Self-register a new agent with an owner |
 | `agent_status` | None | Poll registration approval status |
+| `issue_child_agent` | JWT | Mint a short-lived child identity for a subagent: its own agent id, an attenuated scope slice (child ⊆ parent), its own audit trail, individually revocable. Returns a bearer token for the subagent's `Authorization` header. |
+
+## Session attribution
+
+Every assertion this server signs carries a stable per-process `session_id`
+claim, which the proxy stamps on each audit row. It distinguishes *runs* of
+the server, not subagents: hosts that share one server process (for example
+Claude Code Task-tool subagents) share the id. HTTP callers without this
+server can supply the same discriminator via an `X-AV-Session` header
+(`[A-Za-z0-9._:-]{1,128}`). Both are caller-asserted forensics — the proxy
+never makes an authorization decision on them. For verified per-subagent
+identity, mint a child with `issue_child_agent` instead.
 
 ## Transports
 

package/dist/auth.js

@@ -9,7 +9,7 @@ import { fetchWithTimeout } from "./net.js";
 export async function signJWT(ctx) {
     if (!ctx.privateKey)
         throw new Error("Private key not loaded");
-    return new SignJWT({ agent_id: ctx.AGENT_ID, owner_id: ctx.OWNER_ID })
+    return new SignJWT({ agent_id: ctx.AGENT_ID, owner_id: ctx.OWNER_ID, session_id: ctx.SESSION_ID })
         .setProtectedHeader({ alg: "RS256" })
         .setIssuedAt()
         .setExpirationTime("60s")

package/dist/index.js

@@ -15,6 +15,7 @@ process.on("unhandledRejection", (err) => {
     process.stderr.write(`[mcp-server] FATAL unhandledRejection: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`);
     process.exit(1);
 });
+import { randomBytes } from "node:crypto";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
@@ -22,9 +23,9 @@ import { validateConfig } from "./config.js";
 import { renderInstructions } from "./instructions.js";
 import { signJWT } from "./auth.js";
 import { ALLOWED_METHODS, ALL_TOOLS } from "./tools/schemas.js";
-import { handleListPlatforms, handleUsePlatform, handleAgentRegister, handleAgentStatus, handleAuthzenEvaluate, handleListMyPendingActions, handleReportSelfDiagnostic, handleRequestPlatformAccess, } from "./tools/handlers.js";
+import { handleListPlatforms, handleUsePlatform, handleAgentRegister, handleAgentStatus, handleAuthzenEvaluate, handleListMyPendingActions, handleReportSelfDiagnostic, handleRequestPlatformAccess, handleIssueChildAgent, } from "./tools/handlers.js";
 import { errorContent } from "./net.js";
-import { getPermissionsVersion, recordPermissionsVersion, startPermissionsWatcher, } from "./permissions-watcher.js";
+import { getPermissionsVersion, noteAgentActivity, recordPermissionsVersion, startPermissionsWatcher, } from "./permissions-watcher.js";
 // ---------------------------------------------------------------------------
 // Startup env validation
 // ---------------------------------------------------------------------------
@@ -47,12 +48,18 @@ const server = new Server({ name: "agentvalet", version: "1.0.0" },
 // permissions-watcher.ts). Declaring the capability is what makes the SDK
 // allow that notification.
 { capabilities: { tools: { listChanged: true } }, instructions: renderInstructions(undefined) });
+// One id per server process. Discriminates runs in audit_log.session_id;
+// forensics only — the proxy never branches enforcement on it. Note: Claude
+// Code Task-tool subagents share the parent process, so this discriminates
+// processes/runs, not subagents.
+const SESSION_ID = "sess_" + randomBytes(8).toString("hex");
 // The config + server bundle threaded into auth + handlers (see context.ts) —
 // keeps those modules free of globals.
 const ctx = {
     AGENT_ID,
     OWNER_ID,
     PROXY_URL,
+    SESSION_ID,
     AGENT_PRIVATE_KEY_RAW,
     privateKey,
     server,
@@ -110,6 +117,10 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
 });
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
     const { name, arguments: args } = request.params;
+    // The agent is doing something, so its view of the spec is about to matter.
+    // This is what un-idles the permissions watcher (and resets its backoff); an
+    // editor window nobody is using never reaches here and never revalidates.
+    noteAgentActivity();
     if (name === "list_platforms") {
         return await handleListPlatforms(ctx);
     }
@@ -213,6 +224,12 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         return await handleRequestPlatformAccess(ctx, args);
     }
+    if (name === "issue_child_agent") {
+        if (!args || !Array.isArray(args.grants)) {
+            return errorContent("Invalid or missing argument: grants is required");
+        }
+        return await handleIssueChildAgent(ctx, args);
+    }
     return {
         content: [{ type: "text", text: `Unknown tool: ${name}` }],
         isError: true,

package/dist/permissions-watcher.js

@@ -22,14 +22,66 @@
 // (apps/proxy/src/routes/mcp.ts) is deliberately stateless — a fresh Server per
 // request — so it has no server→client channel and cannot push at all; there,
 // cheap revalidation via the 304 path is the whole story.
+//
+// WHEN we revalidate, and why it is not simply "every 60 seconds":
+//
+// A fixed timer polls a resource that almost never changes, on behalf of a
+// session that is usually doing nothing. On 2026-09-01 that shape turned 210
+// real governed calls into ~7,000 revalidations in a day — mostly from editor
+// windows left open overnight — and each one cost the proxy a full spec
+// resolution. The spec only matters when the agent is about to ACT on it, so
+// the timer now defers to two signals:
+//
+//   1. ACTIVITY. noteAgentActivity() is called from the tool dispatch on every
+//      tool call. A server that has not served one in IDLE_AFTER_MS stops
+//      revalidating entirely — an idle window costs nothing — and resumes the
+//      moment the agent does anything.
+//   2. STABILITY. Each consecutive 304 backs the interval off (doubling, to a
+//      cap). A spec that has not moved in twenty minutes is not about to be
+//      checked every minute. Any observed change, and any tool call, resets it.
+//
+// What this trades away: after an idle stretch, the FIRST tool call may still
+// reason from a spec up to one poll old. That is the pre-watcher behaviour and
+// it is safe by construction — the proxy authorises every call against the live
+// database regardless, so the worst case is one clean 403 rather than a wrongly
+// permitted action. An agent that wants certainty calls list_platforms, which
+// revalidates synchronously.
 import { signJWT } from "./auth.js";
 import { fetchWithTimeout } from "./net.js";
 const DEFAULT_POLL_MS = 60_000;
 // Floor so a typo in the env var can't turn an agent into a polling hammer
 // against the proxy.
 const MIN_POLL_MS = 10_000;
+// No tool call in this long ⇒ nobody is relying on the spec, so stop asking for
+// it. Generous on purpose: the point is to catch the window left open all
+// night, not to punish a user who paused to read something.
+const IDLE_AFTER_MS = 15 * 60 * 1000;
+// Ceiling on the stability backoff, counted in base intervals. At the 60s
+// default this settles an unchanging spec at one revalidation every ~16 min.
+const MAX_BACKOFF_TICKS = 15;
 let currentVersion = null;
 let timer = null;
+// Boot counts as activity: a server that has just started is about to be used.
+let lastActivityAt = Date.now();
+// Base intervals still to be skipped before the next revalidation.
+let ticksToSkip = 0;
+// Consecutive revalidations that found nothing changed; drives the backoff.
+let unchangedStreak = 0;
+/**
+ * Record that the agent just did something. Called from the tool dispatch on
+ * EVERY tool call — the cheapest possible signal that the spec is about to
+ * matter again. Resets both gates, so a session waking up revalidates on the
+ * next tick rather than at the end of a long backoff.
+ */
+export function noteAgentActivity() {
+    lastActivityAt = Date.now();
+    ticksToSkip = 0;
+    unchangedStreak = 0;
+}
+/** Whether the watcher would skip a tick right now. Exported for tests. */
+export function isIdle(now = Date.now()) {
+    return now - lastActivityAt > IDLE_AFTER_MS;
+}
 export function getPermissionsVersion() {
     return currentVersion;
 }
@@ -49,6 +101,9 @@ export function recordPermissionsVersion(version) {
 /** Test seam: forget everything the watcher has learned. */
 export function resetPermissionsVersion() {
     currentVersion = null;
+    lastActivityAt = Date.now();
+    ticksToSkip = 0;
+    unchangedStreak = 0;
 }
 export function pollIntervalMs(raw = process.env.AV_PERMISSIONS_POLL_MS) {
     if (raw === undefined || raw === "")
@@ -107,6 +162,36 @@ export async function checkPermissionsVersion(ctx) {
     }
     return true;
 }
+/**
+ * One timer tick: decide whether this is a moment worth spending a request on,
+ * and revalidate if so. Exported for tests. Returns true when it actually went
+ * to the network.
+ */
+export async function tick(ctx) {
+    // Nobody is using this session. The spec can drift freely — the next tool
+    // call resets the gate, and the proxy authorises against the live database
+    // whatever this server happens to believe.
+    if (isIdle())
+        return false;
+    // Backing off after a run of unchanged reads.
+    if (ticksToSkip > 0) {
+        ticksToSkip -= 1;
+        return false;
+    }
+    const changed = await checkPermissionsVersion(ctx);
+    if (changed) {
+        // Something moved. Watch closely again — an owner mid-edit often makes
+        // several changes in a row.
+        unchangedStreak = 0;
+        ticksToSkip = 0;
+    }
+    else {
+        // 1, 3, 7, 15, 15, … base intervals of silence.
+        unchangedStreak += 1;
+        ticksToSkip = Math.min(2 ** unchangedStreak - 1, MAX_BACKOFF_TICKS);
+    }
+    return true;
+}
 /**
  * Start background revalidation. No-op without credentials or when polling is
  * disabled. The timer is unref'd so it can never hold the process open.
@@ -120,7 +205,7 @@ export function startPermissionsWatcher(ctx) {
     if (interval === 0)
         return;
     timer = setInterval(() => {
-        void checkPermissionsVersion(ctx).catch(() => { });
+        void tick(ctx).catch(() => { });
     }, interval);
     // `unref` is absent in some non-Node runtimes; guard rather than assume.
     timer.unref?.();

package/dist/tools/handlers.js

@@ -347,6 +347,17 @@ export async function handleRequestPlatformAccess(ctx, args) {
         message: "Request submitted and awaiting admin approval. Retry your call later.",
     }));
 }
+export async function handleIssueChildAgent(ctx, args) {
+    const gate = await requireCredentials(ctx);
+    if (gate)
+        return gate;
+    const resp = await fetchWithAuth(ctx, `${ctx.PROXY_URL}/v1/agents/children`, {
+        method: "POST",
+        body: JSON.stringify(args ?? {}),
+    });
+    const json = await resp.json().catch(() => ({ error: `HTTP ${resp.status}` }));
+    return { content: [{ type: "text", text: JSON.stringify(json) }], isError: !resp.ok };
+}
 export async function handleReportSelfDiagnostic(ctx, args) {
     const gate = await requireCredentials(ctx);
     if (gate)

package/dist/tools/schemas.js

@@ -7,7 +7,7 @@
 export const ALLOWED_METHODS = ["GET", "POST", "PUT", "PATCH", "DELETE"];
 export const LIST_PLATFORMS_TOOL = {
     name: "list_platforms",
-    description: "list_platforms: List the platforms and permission scopes this agent has access to.\nInput: None.\nReturns: { platforms: [{ platformId, platformName, scopes, requireApproval, approvalScopes?, connections? }], version: \"<hex>\" }. A platform includes `connections` only when it has 2+ usable accounts; pass the chosen connection_id to use_platform (omit for the default).\nApproval: a call needs human approval if the platform's requireApproval is true (grant-level: every call prompts), if the chosen connection's requireApproval is true, or if the scope is listed in approvalScopes (policy-level: just those scopes prompt). approvalScopes is omitted when no scope is policy-gated.\nVersion: a deterministic hash over the effective spec — it changes whenever the platform set, the scopes, the approval requirements (grant or policy), or the connections change. Compare it against the `Current permissions version` stamped on this description: if they differ, your cached result is stale and you must call list_platforms again before trusting it.\nAuth: Bearer JWT.",
+    description: "list_platforms: List the platforms and permission scopes this agent has access to.\nInput: None.\nReturns: { platforms: [{ platformId, platformName, scopes, requireApproval, approvalScopes?, connections?, callStyle? }], version: \"<hex>\" }. A platform includes `connections` only when it has 2+ usable accounts; pass the chosen connection_id to use_platform (omit for the default).\nCall style: `callStyle` is present only as \"graphql\", and says how to ADDRESS the platform rather than what you may do there: that platform has ONE endpoint taking {query, variables} via POST, so pass \"/\" as the endpoint and put the operation in the body. Its path and HTTP method carry no meaning, read_platform cannot be used on it at all, and a GET returns an upstream error naming neither the platform nor the cause. Absent means a conventional REST API.\nApproval: a call needs human approval if the platform's requireApproval is true (grant-level: every call prompts), if the chosen connection's requireApproval is true, or if the scope is listed in approvalScopes (policy-level: just those scopes prompt). approvalScopes is omitted when no scope is policy-gated.\nVersion: a deterministic hash over the effective spec — it changes whenever the platform set, the scopes, the approval requirements (grant or policy), or the connections change. Compare it against the `Current permissions version` stamped on this description: if they differ, your cached result is stale and you must call list_platforms again before trusting it.\nAuth: Bearer JWT.",
     inputSchema: { type: "object", properties: {} },
     outputSchema: {
         type: "object",
@@ -101,7 +101,7 @@ export const USE_PLATFORM_TOOL = {
 // readOnlyHint annotation enforced rather than merely promised.
 export const READ_PLATFORM_TOOL = {
     name: "read_platform",
-    description: "read_platform: Read data from a platform the owner has connected, through the AgentValet proxy. Calls the platform's own public REST API (for example the GitHub REST API, the Slack Web API, the Stripe API); `endpoint` is a path in that API exactly as its documentation defines it. Always issues GET — use write_platform to create or update, and delete_platform to remove. Input: platform, endpoint, scope, connection_id (optional), reason (optional). Returns: the upstream API response body. Auth: Bearer JWT.",
+    description: "read_platform: Read data from a platform the owner has connected, through the AgentValet proxy. Calls the platform's own public REST API (for example the GitHub REST API, the Slack Web API, the Stripe API); `endpoint` is a path in that API exactly as its documentation defines it. A platform that list_platforms reports as callStyle 'graphql' cannot be read with this tool at all: it exposes a SINGLE endpoint that accepts only POST {query, variables}, so send the read query through write_platform (or use_platform with method POST) even though it is a read. Issuing a GET there returns an upstream error that names neither the platform nor the cause — it is not a broker fault. Always issues GET — use write_platform to create or update, and delete_platform to remove. Input: platform, endpoint, scope, connection_id (optional), reason (optional). Returns: the upstream API response body. Auth: Bearer JWT.",
     inputSchema: {
         type: "object",
         properties: {
@@ -122,7 +122,7 @@ export const READ_PLATFORM_TOOL = {
 };
 export const WRITE_PLATFORM_TOOL = {
     name: "write_platform",
-    description: "write_platform: Create or update data on a platform the owner has connected, through the AgentValet proxy. Calls the platform's own public REST API (for example the GitHub REST API, the Slack Web API, the Stripe API); `endpoint` is a path in that API exactly as its documentation defines it. Accepts POST, PUT or PATCH only — use read_platform for GET and delete_platform for DELETE. May block up to 50s for owner approval, then returns the approved result; otherwise returns a pending_approval envelope. Input: platform, endpoint, scope, method (optional, default POST), body (optional), connection_id (optional), reason (optional). Auth: Bearer JWT.",
+    description: "write_platform: Create or update data on a platform the owner has connected, through the AgentValet proxy. Calls the platform's own public REST API (for example the GitHub REST API, the Slack Web API, the Stripe API); `endpoint` is a path in that API exactly as its documentation defines it. For a platform whose callStyle is 'graphql', pass \"/\" as the endpoint and put the operation in body as {query, variables}: the path and the HTTP method carry no meaning on that platform. Accepts POST, PUT or PATCH only — use read_platform for GET and delete_platform for DELETE. May block up to 50s for owner approval, then returns the approved result; otherwise returns a pending_approval envelope. Input: platform, endpoint, scope, method (optional, default POST), body (optional), connection_id (optional), reason (optional). Auth: Bearer JWT.",
     inputSchema: {
         type: "object",
         properties: {
@@ -153,7 +153,7 @@ export const WRITE_PLATFORM_TOOL = {
 };
 export const DELETE_PLATFORM_TOOL = {
     name: "delete_platform",
-    description: "delete_platform: Delete data on a platform the owner has connected, through the AgentValet proxy. Calls the platform's own public REST API (for example the GitHub REST API, the Slack Web API, the Stripe API); `endpoint` is a path in that API exactly as its documentation defines it. Always issues DELETE. This removes data and is not reversible by AgentValet. May block up to 50s for owner approval. Input: platform, endpoint, scope, body (optional), connection_id (optional), reason (optional). Auth: Bearer JWT.",
+    description: "delete_platform: Delete data on a platform the owner has connected, through the AgentValet proxy. Calls the platform's own public REST API (for example the GitHub REST API, the Slack Web API, the Stripe API); `endpoint` is a path in that API exactly as its documentation defines it. For a platform whose callStyle is 'graphql', pass \"/\" as the endpoint and put the operation in body as {query, variables}: the path and the HTTP method carry no meaning on that platform. Always issues DELETE. This removes data and is not reversible by AgentValet. May block up to 50s for owner approval. Input: platform, endpoint, scope, body (optional), connection_id (optional), reason (optional). Auth: Bearer JWT.",
     inputSchema: {
         type: "object",
         properties: {
@@ -375,6 +375,34 @@ export const REQUEST_PLATFORM_ACCESS_TOOL = {
         required: ["status"],
     },
 };
+export const ISSUE_CHILD_AGENT_TOOL = {
+    name: "issue_child_agent",
+    description: "Issue a short-lived child agent identity for a subagent you are about to spawn. The child gets its own agent id, its own attenuated permission slice (child scopes must be a subset of yours), and its own audit trail; it can be revoked alone without touching you or its siblings. Returns a bearer token the subagent must send as its Authorization header. TTL 60-3600s (default 900). Inject ONLY the bearer_token into the subagent's context — never your own credentials.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: { type: "string", description: "Optional human-readable name for the child agent (1-200 chars)." },
+            ttl_seconds: {
+                type: "number",
+                description: "Optional lifetime in seconds for the child's bearer token. 60-3600, default 900.",
+            },
+            grants: {
+                type: "array",
+                description: "Array of platform grants to attenuate onto the child. Each scope must be a subset of your own granted scopes.",
+                items: {
+                    type: "object",
+                    properties: {
+                        platform: { type: "string", description: "Platform ID (e.g. github, slack)" },
+                        scopes: { type: "array", items: { type: "string" }, description: "Scopes to grant the child for this platform." },
+                        connection_id: { type: "string", description: "Optional. Target a specific connection when a platform has more than one connected." },
+                    },
+                    required: ["platform", "scopes"],
+                },
+            },
+        },
+        required: ["grants"],
+    },
+};
 export const ALL_TOOLS = [
     LIST_PLATFORMS_TOOL,
     USE_PLATFORM_TOOL,
@@ -387,4 +415,5 @@ export const ALL_TOOLS = [
     REPORT_SELF_DIAGNOSTIC_TOOL,
     LIST_MY_PENDING_ACTIONS_TOOL,
     REQUEST_PLATFORM_ACCESS_TOOL,
+    ISSUE_CHILD_AGENT_TOOL,
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentvalet/mcp-server",
-  "version": "1.8.0",
+  "version": "1.12.0",
   "description": "AgentValet MCP server — lets AI agents call approved platforms via the AgentValet proxy",
   "mcpName": "io.github.agentvalet/mcp-server",
   "type": "module",