synartesis 0.8.7 → 0.9.0

package/dist/proxy.js

@@ -1,13 +1,18 @@
 #!/usr/bin/env node
 import {
   PROXY_FLAGS,
+  SILENT,
   canonical,
   cliCommandFrom,
-  connectStdioUpstream,
+  clientEnvFor,
+  connectUpstream,
   createPolicyResolver,
   createRouter,
+  declaredNames,
+  desktopNotifier,
   findJournal,
   findManifest,
+  fingerprint2 as fingerprint,
   isDisconnected,
   loadManifest,
   mark,
@@ -20,12 +25,15 @@ import {
   runRead,
   toPayload,
   toolShapes,
+  trustsMarks,
   ungoverned,
   untested,
+  upstreamEnv,
   verifyAgainstServers,
   warnUntested,
-  withIdempotencyKey
-} from "./chunk-JE7MOCZO.js";
+  withIdempotencyKey,
+  withoutMissingTools
+} from "./chunk-AEEKBR5D.js";
 import {
   SnapshotError,
   UpstreamError,
@@ -147,6 +155,10 @@ async function serveHttp(options) {
           await writeResponse(res, await existing.transport.handleRequest(toRequest(req, raw, origin)));
           return;
         }
+        if (typeof sessionId === "string") {
+          refuse(res, 404, "that session has ended; start a new one with an initialize request");
+          return;
+        }
         const body = req.method === "POST" && raw.length > 0 ? JSON.parse(raw.toString("utf8")) : void 0;
         if (req.method !== "POST" || !isInitialize(body)) {
           refuse(res, 400, "no such session; start one with an initialize request");
@@ -209,14 +221,28 @@ async function serveHttp(options) {
 // src/gate/gate.ts
 var DEFAULT_GATE_TIMEOUT_MS = 3e5;
 var DEFAULT_HINT = (actionId) => `synartesis approve ${actionId.slice(0, 8)}`;
-function createRetryGate(journal, approveHint = DEFAULT_HINT) {
+function createRetryGate(journal, approveHint = DEFAULT_HINT, notify = SILENT) {
   return {
     decide(request) {
+      const first = journal.getAction(request.actionId)?.status !== "gated";
       journal.markGated(request.actionId, request.why);
+      if (first) {
+        notify({
+          server: request.server,
+          tool: request.tool,
+          actionId: request.actionId,
+          approve: approveHint(request.actionId)
+        });
+      }
       return Promise.resolve({
         approved: false,
         awaiting: true,
-        reason: "it is waiting for a person to approve it. Ask them to run: " + approveHint(request.actionId) + "  --- then make this exact call again."
+        // Nothing here tells the agent how to approve it. This used to hand
+        // over the exact `synartesis approve` command to relay, and an agent
+        // with a shell -- Claude Code, Codex -- could simply run it, recorded
+        // as the person. The command goes to the person instead: in the
+        // notification, in `watch`, in the console and in `gates`.
+        reason: "It is waiting for a person to decide, and they have been told. Let the user know it is waiting, then make this exact call again once they say it is approved."
       });
     }
   };
@@ -285,9 +311,29 @@ function shouldGateOnWrite(args) {
 
 // src/proxy/proxy.ts
 var APPROVAL_WINDOW_MS = 60 * 60 * 1e3;
+function saidNo(name, denial) {
+  return new McpError(
+    ErrorCode.InvalidRequest,
+    `synartesis blocked ${name}: ${denial.by} denied this exact call ${ago(denial.at)} (${denial.reason}). Ask the user what they want instead; do not retry it or reach the same result another way.`
+  );
+}
+function ago(at) {
+  const minutes = Math.max(0, Math.round((Date.now() - Date.parse(at)) / 6e4));
+  if (minutes === 0) {
+    return "just now";
+  }
+  return `${String(minutes)} minute${minutes === 1 ? "" : "s"} ago`;
+}
 var PassthroughResult = z.looseObject({});
 var ToolList = z.looseObject({
-  tools: z.array(z.looseObject({ name: z.string() })),
+  tools: z.array(
+    z.looseObject({
+      name: z.string(),
+      // Only the one mark this reads. Anything else a server says passes
+      // through untouched, and a malformed value reads as no mark at all.
+      annotations: z.looseObject({ readOnlyHint: z.unknown().optional() }).optional().catch(void 0)
+    })
+  ),
   nextCursor: z.string().optional()
 });
 var PromptList = z.looseObject({
@@ -360,10 +406,11 @@ var SYNARTESIS_INSTRUCTIONS = [
   "Some actions cannot be undone. Those are held until a person approves them, and the call",
   'will fail with a message beginning "Synartesis is holding this call for approval".',
   "When that happens:",
-  "  1. Tell the user plainly that you are asking Synartesis for approval, and what for.",
-  "  2. Give them the exact `synartesis approve ...` command from the error.",
-  "  3. Once they say they have approved it, make the same call again. It will go through.",
-  "Do not try to work around a held call by using a different tool to achieve the same thing."
+  "  1. Tell the user plainly that the call is waiting for their approval, and what it is for.",
+  "     They have been notified, and can see and answer it in `synartesis watch`.",
+  "  2. Once they say they have approved it, make the same call again. It will go through.",
+  "Do not approve it yourself, and do not try to work around a held call by using a",
+  "different tool to achieve the same thing."
 ].join("\n");
 function instructionsFor(router) {
   const sections = router.upstreams.map((upstream2) => ({
@@ -422,8 +469,18 @@ function createProxyServer(options) {
   const { upstreams, manifest, journal } = options;
   const router = createRouter(upstreams, manifest);
   const policies = createPolicyResolver(manifest);
+  const markedReadOnly = /* @__PURE__ */ new Set();
   const log = options.logger;
-  const gate = options.gate ?? createRetryGate(journal, options.approveHint);
+  const trusting = (found, server2, tool) => {
+    if (found.matched || !trustsMarks(manifest, server2) || !markedReadOnly.has(qualify(server2, tool))) {
+      return found;
+    }
+    return {
+      policy: { match: qualify(server2, tool), class: "readonly", gate: "never", refusal: "uncertain" },
+      matched: false
+    };
+  };
+  const gate = options.gate ?? createRetryGate(journal, options.approveHint, options.notify);
   const capabilities = mergeCapabilities(
     upstreams.map((upstream) => upstream.client.getServerCapabilities() ?? {})
   );
@@ -576,6 +633,12 @@ function createProxyServer(options) {
             return { items: page.tools, nextCursor: page.nextCursor };
           });
           for (const tool of items) {
+            const qualified = qualify(upstream.name, tool.name);
+            if (tool.annotations?.readOnlyHint === true) {
+              markedReadOnly.add(qualified);
+            } else {
+              markedReadOnly.delete(qualified);
+            }
             tools.push({
               ...compatible(tool, (dialect) => {
                 log?.warn(
@@ -602,11 +665,17 @@ function createProxyServer(options) {
           `no configured server provides tool ${request.params.name}`
         );
       }
-      const { policy } = policies.resolve(qualify(route.upstream.name, route.tool));
+      const { policy, matched } = trusting(
+        policies.resolve(qualify(route.upstream.name, route.tool)),
+        route.upstream.name,
+        route.tool
+      );
       const args = request.params.arguments ?? {};
       enter();
       try {
-        const wantsGate = policy.gate === "always" || policy.gate === "on_write" && shouldGateOnWrite(args);
+        const policyGates = policy.gate === "always" || policy.gate === "on_write" && shouldGateOnWrite(args);
+        const allowance = policyGates ? journal.findAllowance(route.upstream.name, route.tool, (/* @__PURE__ */ new Date()).toISOString()) : void 0;
+        const wantsGate = policyGates && allowance === void 0;
         const unresolved = policy.class === "readonly" ? void 0 : journal.findPending({
           runId: activeRun,
           server: route.upstream.name,
@@ -627,6 +696,19 @@ function createProxyServer(options) {
           tool: route.tool,
           args
         }) : void 0;
+        const refused = mustAsk && granted === void 0 && waiting === void 0 ? journal.findDenial({
+          server: route.upstream.name,
+          tool: route.tool,
+          args,
+          notBefore: new Date(Date.now() - APPROVAL_WINDOW_MS).toISOString()
+        }) : void 0;
+        if (refused !== void 0) {
+          log?.info(
+            { action: refused.action.id, by: refused.by },
+            "refused again: a person denied this exact call"
+          );
+          throw saidNo(request.params.name, refused);
+        }
         const reusable = waiting ?? (inherited === void 0 ? granted : void 0);
         const pending = reusable === void 0 ? journal.recordPending({
           runId: activeRun,
@@ -639,6 +721,9 @@ function createProxyServer(options) {
           seq: reusable.seq,
           idempotencyKey: reusable.idempotencyKey
         };
+        if (allowance !== void 0 && !mustAsk) {
+          journal.markAllowed(pending.actionId, `${allowance.by} (allowed without asking)`);
+        }
         let spent = true;
         if (inherited !== void 0) {
           spent = journal.adoptApproval(pending.actionId, inherited);
@@ -709,7 +794,12 @@ function createProxyServer(options) {
         if (mustAsk && (granted === void 0 || !spent)) {
           const because = [
             unresolved === void 0 ? void 0 : `an earlier attempt at this exact call, action ${String(unresolved.seq)}, went out and its outcome could never be established, so sending it again may apply the change a second time`,
-            wantsGate ? "this action cannot be undone" : void 0
+            // Two different problems used to share this one sentence. A tool
+            // no rule mentions is held because nobody has said what it does,
+            // not because it is known to be permanent -- and the answer to
+            // that is a rule, which the person is told how to write, not a
+            // yes to every call it makes.
+            wantsGate ? matched ? "this action cannot be undone" : `there is no rule for ${route.upstream.name}.${route.tool} in the policy, so nothing says whether it can be undone` : void 0
           ].filter((one) => one !== void 0);
           await decide(because.join(", and "));
         }
@@ -764,13 +854,33 @@ function createProxyServer(options) {
         }
         const priorState = probe === void 0 || foundNothing ? { present: false } : { present: true, value: snapshot };
         if (noWayBack !== void 0 && !askedAlready) {
-          const standing = journal.findApproval({
+          const allowedNow = journal.findAllowance(
+            route.upstream.name,
+            route.tool,
+            (/* @__PURE__ */ new Date()).toISOString()
+          );
+          const standing = allowedNow === void 0 ? journal.findApproval({
             server: route.upstream.name,
             tool: route.tool,
             args,
             notBefore: new Date(Date.now() - APPROVAL_WINDOW_MS).toISOString()
-          });
-          if (standing === void 0) {
+          }) : void 0;
+          const refusedHere = allowedNow === void 0 && standing === void 0 ? journal.findDenial({
+            server: route.upstream.name,
+            tool: route.tool,
+            args,
+            notBefore: new Date(Date.now() - APPROVAL_WINDOW_MS).toISOString()
+          }) : void 0;
+          if (allowedNow !== void 0) {
+            journal.markAllowed(pending.actionId, `${allowedNow.by} (allowed without asking)`);
+          } else if (refusedHere !== void 0) {
+            journal.settleAsDenied(
+              pending.actionId,
+              refusedHere.by,
+              `not sent: ${refusedHere.by} had denied this exact call`
+            );
+            throw saidNo(request.params.name, refusedHere);
+          } else if (standing === void 0) {
             await decide(noWayBack.asked);
           } else if (journal.adoptApproval(pending.actionId, standing)) {
             log?.info(
@@ -794,11 +904,11 @@ function createProxyServer(options) {
             signal: extra.signal
           });
           let inferred;
-          const refused = refusal(result);
-          if (refused !== void 0) {
+          const refused2 = refusal(result);
+          if (refused2 !== void 0) {
             const settled = policy.refusal === "clean" ? "none" : await whatHappened(router, probe, priorState, extra.signal);
             if (settled !== "applied") {
-              const why = `the upstream refused the call: ${refused}`;
+              const why = `the upstream refused the call: ${refused2}`;
               if (settled === "none") {
                 journal.markFailed(pending.actionId, why);
               } else {
@@ -808,14 +918,14 @@ function createProxyServer(options) {
                 );
               }
               log?.debug(
-                { seq: pending.seq, tool: route.tool, reason: refused, settled },
+                { seq: pending.seq, tool: route.tool, reason: refused2, settled },
                 "refused by the upstream"
               );
               return result;
             }
-            inferred = `the upstream answered with an error and the change was established by reading the resource back, so nothing confirmed it: ${refused}`;
+            inferred = `the upstream answered with an error and the change was established by reading the resource back, so nothing confirmed it: ${refused2}`;
             log?.warn(
-              { seq: pending.seq, tool: route.tool, reason: refused },
+              { seq: pending.seq, tool: route.tool, reason: refused2 },
               "the upstream reported an error after changing the resource"
             );
           }
@@ -866,8 +976,9 @@ function createProxyServer(options) {
           });
           return result;
         } catch (error) {
-          const disconnected = isDisconnected(error);
-          if (neverDispatched(error)) {
+          const kind = route.upstream.classify?.(error);
+          const disconnected = isDisconnected(error) || kind === "lost";
+          if (neverDispatched(error) || kind !== void 0) {
             journal.markFailed(pending.actionId, describe(error));
           } else {
             const settled = await whatHappened(router, probe, priorState, extra.signal);
@@ -1188,29 +1299,39 @@ async function main() {
       `--server ${String(argv.server)} is not declared in ${argv.manifest}; it has: ${declared.map(([name]) => name).join(", ")}`
     );
   }
+  const source = argv.server === void 0 ? { kind: "manifest" } : { kind: "inherit" };
   const upstreams = [];
+  const key = journal.fingerprintKey();
+  const startedWith = /* @__PURE__ */ new Map();
   for (const [name, spec] of wanted) {
-    upstreams.push(
-      await connectStdioUpstream({
-        name,
-        command: spec.command,
-        args: spec.args,
-        ...spec.env === void 0 ? {} : { env: spec.env }
-      })
-    );
+    upstreams.push(await connectUpstream(name, spec, { env: source }));
+    let client;
+    try {
+      client = source.kind === "inherit" ? clientEnvFor(argv.manifest, name)?.env : void 0;
+    } catch {
+      client = void 0;
+    }
+    startedWith.set(name, {
+      cwd: process.cwd(),
+      fingerprints: fingerprint(key, upstreamEnv(name, spec, source), declaredNames(spec, client))
+    });
+  }
+  const { manifest: served, disabled } = await withoutMissingTools(upstreams, manifest);
+  for (const line of disabled) {
+    log.warn(line);
   }
   await verifyAgainstServers(
     upstreams,
-    argv.server === void 0 ? manifest : {
-      ...manifest,
-      tools: manifest.tools.filter((rule) => rule.match.startsWith(`${String(argv.server)}.`))
+    argv.server === void 0 ? served : {
+      ...served,
+      tools: served.tools.filter((rule) => rule.match.startsWith(`${String(argv.server)}.`))
     }
   );
   const uncovered = ungoverned(
-    manifest,
+    served,
     new Map(await Promise.all(upstreams.map(async (upstream) => [
       upstream.name,
-      (await toolShapes(upstream)).map((tool) => tool.name)
+      (await toolShapes(upstream)).filter((tool) => !(tool.readOnly === true && trustsMarks(served, upstream.name))).map((tool) => tool.name)
     ])))
   );
   for (const entry of uncovered) {
@@ -1224,21 +1345,33 @@ async function main() {
       manifest: argv.manifest,
       journal: argv.journal,
       servers: upstreams.map((upstream) => upstream.name),
-      policies: manifest.tools.length,
+      policies: served.tools.length,
+      held: disabled.length,
       ungoverned: uncovered.reduce((sum, entry) => sum + entry.tools.length, 0)
     },
     "proxy ready"
   );
-  const build = () => createProxyServer({
-    upstreams,
-    manifest,
-    journal,
-    logger: log,
-    // Absolute, because whoever approves may be in any directory at all.
-    approveHint: (actionId) => `${cliCommandFrom(import.meta.url)} approve ${actionId.slice(0, 8)} --journal ${resolve(argv.journal)}`
-  });
+  const build = () => {
+    const proxy2 = createProxyServer({
+      upstreams,
+      manifest: served,
+      journal,
+      logger: log,
+      // Absolute, because whoever approves may be in any directory at all.
+      approveHint: (actionId) => `${cliCommandFrom(import.meta.url)} approve ${actionId.slice(0, 8)} --journal ${resolve(argv.journal)}`,
+      notify: desktopNotifier()
+    });
+    proxy2.ready.then((runId) => {
+      for (const [server, started] of startedWith) {
+        journal.recordRunServer(runId, server, started.cwd, started.fingerprints);
+      }
+    }).catch((error) => {
+      log.warn({ error: describe(error) }, "could not record what this session's servers were started with");
+    });
+    return proxy2;
+  };
   if (argv.http !== void 0) {
-    const served = await serveHttp({
+    const served2 = await serveHttp({
       ...argv.http,
       create: build,
       log: {
@@ -1252,7 +1385,7 @@ async function main() {
     });
     const stop = () => {
       void (async () => {
-        await served.close();
+        await served2.close();
         for (const upstream of upstreams) {
           await upstream.close();
         }

package/manifests/aws-docs.yaml

@@ -0,0 +1,26 @@
+# Policy for awslabs.aws-documentation-mcp-server.
+#
+# Written against the build current in September 2026 from the server's own tools/list.
+#
+# Reads AWS's public documentation. Nothing here touches an AWS account.
+#
+# A tool a later version adds is held until a rule says what it does.
+version: 1
+
+servers:
+  aws-docs:
+    command: uvx
+    args: ["awslabs.aws-documentation-mcp-server@latest"]
+    provenance: live
+
+tools:
+  - match: "aws-docs.read_documentation"
+    class: readonly
+  - match: "aws-docs.read_sections"
+    class: readonly
+  - match: "aws-docs.search_table"
+    class: readonly
+  - match: "aws-docs.search_documentation"
+    class: readonly
+  - match: "aws-docs.recommend"
+    class: readonly

package/manifests/brave.yaml

@@ -0,0 +1,33 @@
+# Policy for @brave/brave-search-mcp-server.
+#
+# Written against 2.1.4 from the server's own tools/list.
+#
+# Every tool searches. The server does not mark them read-only, which is why
+# each search was held before this file existed.
+#
+# A tool a later version adds is held until a rule says what it does.
+version: 1
+
+servers:
+  brave:
+    command: npx
+    args: ["-y", "@brave/brave-search-mcp-server"]
+    provenance: live
+
+tools:
+  - match: "brave.brave_web_search"
+    class: readonly
+  - match: "brave.brave_local_search"
+    class: readonly
+  - match: "brave.brave_video_search"
+    class: readonly
+  - match: "brave.brave_image_search"
+    class: readonly
+  - match: "brave.brave_news_search"
+    class: readonly
+  - match: "brave.brave_summarizer"
+    class: readonly
+  - match: "brave.brave_llm_context"
+    class: readonly
+  - match: "brave.brave_place_search"
+    class: readonly

package/manifests/chrome-devtools.yaml

@@ -0,0 +1,115 @@
+# Policy for chrome-devtools-mcp.
+#
+# Written against 1.10.1 from the server's own tools/list, read-only hints and
+# all.
+#
+# What playwright.yaml says holds here too. Nothing a browser does can be
+# undone, and holding every click made the server unusable, so interactions
+# are recorded rather than held: each is classed as a call that cannot be
+# undone, and written to the journal with its arguments.
+#
+# Two tools are still held. Running a script the agent wrote has the reach of
+# the page and everything it is signed in to, and an upload sends a file from
+# your disk to whoever runs the page. A tool this file does not mention is held
+# until a rule says otherwise.
+#
+# Only the tools the server marks read-only are classed as reads. The ones it
+# does not include screenshots, snapshots, traces and audits, and several of
+# those can write a file to disk when given a path. They are recorded, not
+# held.
+version: 1
+
+servers:
+  chrome-devtools:
+    command: npx
+    args: ["-y", "chrome-devtools-mcp@latest"]
+    provenance: live
+
+tools:
+  # --- reads: the tools the server itself marks read-only ------------------
+  - match: "chrome-devtools.list_pages"
+    class: readonly
+  - match: "chrome-devtools.select_page"
+    class: readonly
+  - match: "chrome-devtools.list_console_messages"
+    class: readonly
+  - match: "chrome-devtools.get_console_message"
+    class: readonly
+  - match: "chrome-devtools.list_network_requests"
+    class: readonly
+  - match: "chrome-devtools.get_css_styles"
+    class: readonly
+  - match: "chrome-devtools.performance_analyze_insight"
+    class: readonly
+  - match: "chrome-devtools.wait_for"
+    class: readonly
+
+  # --- held: each reaches past the page -------------------------------------
+  - match: "chrome-devtools.evaluate_script"
+    class: irreversible
+    gate: always
+  - match: "chrome-devtools.upload_file"
+    class: irreversible
+    gate: always
+
+  # --- recorded, not held ----------------------------------------------------
+  - match: "chrome-devtools.navigate_page"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.new_page"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.close_page"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.click"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.fill"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.fill_form"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.type_text"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.press_key"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.hover"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.drag"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.handle_dialog"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.emulate"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.resize_page"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.take_screenshot"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.take_snapshot"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.take_heapsnapshot"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.get_network_request"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.performance_start_trace"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.performance_stop_trace"
+    class: irreversible
+    gate: never
+  - match: "chrome-devtools.lighthouse_audit"
+    class: irreversible
+    gate: never

package/manifests/exa.yaml

@@ -0,0 +1,20 @@
+# Policy for exa-mcp-server.
+#
+# Written against 3.4.1 from the server's own tools/list.
+#
+# Both tools are marked read-only by the server itself.
+#
+# A tool a later version adds is held until a rule says what it does.
+version: 1
+
+servers:
+  exa:
+    command: npx
+    args: ["-y", "exa-mcp-server"]
+    provenance: live
+
+tools:
+  - match: "exa.web_search_exa"
+    class: readonly
+  - match: "exa.web_fetch_exa"
+    class: readonly

package/manifests/fetch.yaml

@@ -0,0 +1,20 @@
+# Policy for mcp-server-fetch.
+#
+# Written against 1.30.0 from the server's own tools/list.
+#
+# It fetches a URL and hands back what is there. A GET can still reach
+# something that changes state on being read -- that is the page's doing, and
+# no policy here can see it.
+#
+# A tool a later version adds is held until a rule says what it does.
+version: 1
+
+servers:
+  fetch:
+    command: uvx
+    args: ["mcp-server-fetch"]
+    provenance: live
+
+tools:
+  - match: "fetch.fetch"
+    class: readonly