@stigmer/runner 3.9.0 → 3.11.0

package/src/shared/__tests__/vertex-seam.test.ts

@@ -0,0 +1,295 @@
+/**
+ * Characterization test for the ChatAnthropic `createClient` -> AnthropicVertex
+ * seam — the integration T02's vertex backend adapter will be built on.
+ *
+ * This is NOT a unit test of our code (there is no production vertex code
+ * yet). It pins the exact cross-package behavior production will rely on:
+ * the REAL `ChatAnthropic` (@langchain/anthropic, bundling @anthropic-ai/sdk
+ * 0.95.x) driving the REAL `AnthropicVertex` client (@anthropic-ai/vertex-sdk,
+ * bundling its own nested @anthropic-ai/sdk >=0.115). If a future bump of
+ * either side changes request shaping, streaming event handling, tool-call
+ * assembly, or usage accounting across this seam, this suite fails in CI
+ * instead of production. See scripts/check-langchain-deps.sh for why two
+ * @anthropic-ai/sdk copies coexist and when they collapse to one.
+ *
+ * Determinism: zero credentials, zero network. Google auth is bypassed by
+ * injecting a fake `authClient` (the SDK's supported constructor option —
+ * `accessToken` alone does NOT skip the auth client, adaptRequest always
+ * awaits it), and transport is a recording `fetch` injected through the
+ * SDK's own `fetch` option. No global patching, no SDK mocks.
+ */
+
+import { describe, it, expect } from "vitest";
+import { ChatAnthropic } from "@langchain/anthropic";
+import { AnthropicVertex } from "@anthropic-ai/vertex-sdk";
+import type { AuthClient } from "google-auth-library";
+import { HumanMessage, AIMessage, AIMessageChunk } from "@langchain/core/messages";
+
+// ─── Fixtures ────────────────────────────────────────────────────────────────
+
+/** Dated pre-4.6 id in Vertex's `@date` form (see llm-backend.ts translation). */
+const VERTEX_MODEL_ID = "claude-sonnet-4-5@20250929";
+const PROJECT_ID = "test-project";
+const REGION = "asia-south1";
+
+const WEATHER_TOOL = {
+  name: "get_weather",
+  description: "Get the current weather for a city.",
+  input_schema: {
+    type: "object" as const,
+    properties: { city: { type: "string" } },
+    required: ["city"],
+  },
+};
+
+/** Non-streaming (`:rawPredict`) response: text + tool_use + usage. */
+const MESSAGE_RESPONSE = {
+  id: "msg_vertex_test_01",
+  type: "message",
+  role: "assistant",
+  model: VERTEX_MODEL_ID,
+  content: [
+    { type: "text", text: "I'll check the weather." },
+    { type: "tool_use", id: "toolu_test_01", name: "get_weather", input: { city: "Chennai" } },
+  ],
+  stop_reason: "tool_use",
+  stop_sequence: null,
+  usage: { input_tokens: 25, output_tokens: 17 },
+};
+
+/**
+ * Streaming (`:streamRawPredict`) response as Anthropic SSE: a text block,
+ * a tool_use block assembled from input_json_delta, then cumulative usage in
+ * message_delta — the exact event grammar the nested SDK parses.
+ */
+const SSE_EVENTS: ReadonlyArray<[string, object]> = [
+  ["message_start", {
+    type: "message_start",
+    message: {
+      id: "msg_vertex_test_02", type: "message", role: "assistant",
+      model: VERTEX_MODEL_ID, content: [], stop_reason: null, stop_sequence: null,
+      usage: { input_tokens: 25, output_tokens: 1 },
+    },
+  }],
+  ["content_block_start", { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } }],
+  ["content_block_delta", { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "I'll check the weather." } }],
+  ["content_block_stop", { type: "content_block_stop", index: 0 }],
+  ["content_block_start", { type: "content_block_start", index: 1, content_block: { type: "tool_use", id: "toolu_test_02", name: "get_weather", input: {} } }],
+  ["content_block_delta", { type: "content_block_delta", index: 1, delta: { type: "input_json_delta", partial_json: '{"city":"Chennai"}' } }],
+  ["content_block_stop", { type: "content_block_stop", index: 1 }],
+  ["message_delta", { type: "message_delta", delta: { stop_reason: "tool_use", stop_sequence: null }, usage: { output_tokens: 17 } }],
+  ["message_stop", { type: "message_stop" }],
+];
+
+function sseBody(): string {
+  return SSE_EVENTS
+    .map(([event, data]) => `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`)
+    .join("");
+}
+
+// ─── Harness ─────────────────────────────────────────────────────────────────
+
+interface RecordedRequest {
+  url: string;
+  method: string;
+  headers: Record<string, string>;
+  body: Record<string, unknown>;
+}
+
+interface SeamHarness {
+  model: ChatAnthropic;
+  requests: RecordedRequest[];
+  /** Options ChatAnthropic passed to the createClient factory. */
+  factoryOptions: Array<{ maxRetries?: number }>;
+  /** The AnthropicVertex instances the factory constructed. */
+  clients: AnthropicVertex[];
+}
+
+/**
+ * Build a real ChatAnthropic wired to a real AnthropicVertex through the
+ * `createClient` seam, with transport replaced by a recording fetch.
+ *
+ * The factory honors `maxRetries` from the incoming options: LangChain owns
+ * retrying (its AsyncCaller wraps every request) and passes `maxRetries: 0`
+ * so the underlying SDK must not retry underneath it. A factory that ignored
+ * this would nest the Vertex SDK's default 2 retries inside LangChain's loop,
+ * multiplying every transient failure — the T02 adapter must preserve this.
+ */
+function buildSeamHarness(): SeamHarness {
+  const requests: RecordedRequest[] = [];
+  const factoryOptions: SeamHarness["factoryOptions"] = [];
+  const clients: AnthropicVertex[] = [];
+
+  const recordingFetch: typeof fetch = async (input, init) => {
+    const headers: Record<string, string> = {};
+    new Headers(init?.headers).forEach((value, key) => {
+      headers[key] = value;
+    });
+    requests.push({
+      url: String(input),
+      method: init?.method ?? "GET",
+      headers,
+      body: JSON.parse(String(init?.body)) as Record<string, unknown>,
+    });
+    const streaming = String(input).includes(":streamRawPredict");
+    return streaming
+      ? new Response(sseBody(), {
+          status: 200,
+          headers: { "Content-Type": "text/event-stream" },
+        })
+      : new Response(JSON.stringify(MESSAGE_RESPONSE), {
+          status: 200,
+          headers: { "Content-Type": "application/json" },
+        });
+  };
+
+  // Minimal structural fake of google-auth-library's AuthClient — the Vertex
+  // SDK's adaptRequest calls exactly `getRequestHeaders()` (merged into the
+  // outbound request) and reads `projectId`. The cast is test-only: building
+  // a real AuthClient would require credentials, defeating determinism.
+  const fakeAuthClient = {
+    projectId: PROJECT_ID,
+    getRequestHeaders: async () => new Headers({ authorization: "Bearer test-token" }),
+  } as unknown as AuthClient;
+
+  const model = new ChatAnthropic({
+    model: VERTEX_MODEL_ID,
+    temperature: 0,
+    maxTokens: 1024,
+    createClient: (options) => {
+      factoryOptions.push({ maxRetries: options.maxRetries });
+      const client = new AnthropicVertex({
+        projectId: PROJECT_ID,
+        region: REGION,
+        authClient: fakeAuthClient,
+        fetch: recordingFetch,
+        maxRetries: options.maxRetries,
+      });
+      clients.push(client);
+      return client;
+    },
+  });
+
+  return { model, requests, factoryOptions, clients };
+}
+
+const expectedUrl = (specifier: "rawPredict" | "streamRawPredict") =>
+  `https://${REGION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}` +
+  `/locations/${REGION}/publishers/anthropic/models/${VERTEX_MODEL_ID}:${specifier}`;
+
+// ─── Tests ───────────────────────────────────────────────────────────────────
+
+describe("ChatAnthropic createClient -> AnthropicVertex seam", () => {
+  it("constructs without an Anthropic API key when createClient is provided", () => {
+    // chat_models.js waives the "Anthropic API key not found" check for
+    // factory-constructed clients — the waiver the vertex backend depends on.
+    expect(() => buildSeamHarness()).not.toThrow();
+  });
+
+  it("shapes a non-streaming request into Vertex wire form (:rawPredict)", async () => {
+    const h = buildSeamHarness();
+
+    const result = await h.model.invoke([new HumanMessage("Weather in Chennai?")]);
+
+    expect(h.requests).toHaveLength(1);
+    const req = h.requests[0];
+
+    // The model id rides in the URL path — with `@` intact — not in the body.
+    expect(req.url).toBe(expectedUrl("rawPredict"));
+    expect(req.method).toBe("POST");
+    expect(req.body).not.toHaveProperty("model");
+    expect(req.body.anthropic_version).toBe("vertex-2023-10-16");
+    expect(req.body.max_tokens).toBe(1024);
+
+    // The fake auth client's OAuth header reached the wire.
+    expect(req.headers.authorization).toBe("Bearer test-token");
+
+    expect(result).toBeInstanceOf(AIMessage);
+  });
+
+  it("round-trips tool definitions and tool_use blocks into tool_calls", async () => {
+    const h = buildSeamHarness();
+    const withTools = h.model.bindTools([WEATHER_TOOL]);
+
+    const result = (await withTools.invoke([
+      new HumanMessage("Weather in Chennai?"),
+    ])) as AIMessage;
+
+    // Tool definition survived request shaping through the Vertex adapter.
+    const tools = h.requests[0].body.tools as Array<{ name: string }>;
+    expect(tools).toHaveLength(1);
+    expect(tools[0].name).toBe("get_weather");
+
+    // The tool_use response block became a LangChain tool_call with its id —
+    // the identity the HITL approval flow keys on.
+    expect(result.tool_calls).toHaveLength(1);
+    expect(result.tool_calls?.[0]).toMatchObject({
+      id: "toolu_test_01",
+      name: "get_weather",
+      args: { city: "Chennai" },
+    });
+  });
+
+  it("reports usage_metadata on non-streaming responses (what billing reads)", async () => {
+    const h = buildSeamHarness();
+
+    const result = (await h.model.invoke([
+      new HumanMessage("Weather in Chennai?"),
+    ])) as AIMessage;
+
+    expect(result.usage_metadata).toMatchObject({
+      input_tokens: 25,
+      output_tokens: 17,
+      total_tokens: 42,
+    });
+  });
+
+  it("streams via :streamRawPredict, assembling tool_calls and usage from SSE", async () => {
+    const h = buildSeamHarness();
+
+    let final: AIMessageChunk | undefined;
+    for await (const chunk of await h.model.stream([
+      new HumanMessage("Weather in Chennai?"),
+    ])) {
+      final = final === undefined ? chunk : final.concat(chunk);
+    }
+
+    expect(h.requests).toHaveLength(1);
+    expect(h.requests[0].url).toBe(expectedUrl("streamRawPredict"));
+    expect(h.requests[0].body.stream).toBe(true);
+    expect(h.requests[0].body).not.toHaveProperty("model");
+
+    expect(final).toBeDefined();
+    expect(final?.text).toBe("I'll check the weather.");
+    expect(final?.tool_calls).toHaveLength(1);
+    expect(final?.tool_calls?.[0]).toMatchObject({
+      id: "toolu_test_02",
+      name: "get_weather",
+      args: { city: "Chennai" },
+    });
+
+    // input from message_start; output accumulated across message events.
+    // Pinned to the observed accumulation so a LangChain bump that changes
+    // usage math (billing input) fails here first.
+    expect(final?.usage_metadata).toMatchObject({
+      input_tokens: 25,
+      output_tokens: 18,
+    });
+  });
+
+  it("passes maxRetries: 0 to the factory and the honored value reaches the client", async () => {
+    const h = buildSeamHarness();
+
+    await h.model.invoke([new HumanMessage("hi")]);
+    for await (const chunk of await h.model.stream([new HumanMessage("hi")])) {
+      void chunk;
+    }
+
+    // LangChain owns retrying: it must hand the factory maxRetries: 0, once
+    // per cached client (batch + streaming are constructed independently).
+    expect(h.factoryOptions).toHaveLength(2);
+    expect(h.factoryOptions.every((o) => o.maxRetries === 0)).toBe(true);
+    expect(h.clients).toHaveLength(2);
+    expect(h.clients.every((c) => c.maxRetries === 0)).toBe(true);
+  });
+});

package/src/shared/approval-policy.ts

@@ -16,7 +16,6 @@
  */
 
 import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
-import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { ApprovalAction, ApprovalMode, ApprovalPolicySource } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import { toolApprovalCategory, type ToolApprovalCategory } from "./tool-kind.js";
@@ -321,9 +320,16 @@ export interface MergedToolPolicy {
  * Policy chain (each level overrides the previous):
  * 1. status.toolApprovals — system-generated defaults; presence = requires approval
  * 2. spec.pinnedToolApprovals — manual overrides; presence = requires approval
- * 3. agent tool_approval_overrides — explicit boolean per tool (enable OR disable)
+ * 3. usage tool_approval_overrides — explicit boolean per tool (enable OR disable)
  * 4. active leases — runtime bypass (highest priority), now scoped
  *
+ * Layer 3 is read from {@link ResolvedMcpServer.toolApprovalOverrides} — the
+ * overrides ride each server from the usage that resolved it (issue #349), so
+ * an override is STRUCTURALLY scoped to its own server. There is deliberately
+ * no cross-server override input: a flat list applied inside this per-server
+ * loop is how an override once leaked onto — or silently un-gated — a
+ * same-named tool on another server.
+ *
  * The map carries ONLY the tools that require approval — a tool's absence means
  * "auto-approved". Leases shape that absence:
  * - On a global pre-arm ({@link ActiveLeases.global}) the map is empty.
@@ -341,7 +347,6 @@ export interface MergedToolPolicy {
  */
 export function mergeApprovalPolicies(
   resolvedServers: ResolvedMcpServer[],
-  agentOverrides: ToolApprovalOverride[],
   leases: ActiveLeases,
 ): Map<string, MergedToolPolicy> {
   const merged = new Map<string, MergedToolPolicy>();
@@ -382,10 +387,12 @@ export function mergeApprovalPolicies(
       });
     }
 
-    // Layer 3: per-agent overrides (explicit boolean, can enable or disable).
-    // Touching a tool here makes the per-agent layer the responsible source,
-    // whether it enables, disables, or re-messages the gate.
-    for (const override of agentOverrides) {
+    // Layer 3: this usage's overrides (explicit boolean, can enable or
+    // disable) — scoped to THIS server because they arrived on it (see the
+    // function doc). Touching a tool here makes the per-agent layer the
+    // responsible source, whether it enables, disables, or re-messages the
+    // gate.
+    for (const override of server.toolApprovalOverrides) {
       if (!override.toolName) continue;
       const existing = serverPolicies.get(override.toolName);
       if (existing) {

package/src/shared/attachment-naming.ts

@@ -0,0 +1,78 @@
+/**
+ * Naming policy for execution attachments — the single owner of the rule that
+ * resolves duplicate attachment filenames (issue #364).
+ *
+ * Both harnesses materialize attachments into the platform inputs namespace
+ * keyed by filename, so two attachments carrying the same name contend for
+ * one on-disk path. Before this module existed each harness had an accidental
+ * answer: the deep-agent injector failed the whole execution on the collision
+ * and the Cursor resolver silently overwrote the earlier file. The platform
+ * answer is neither — a duplicate is mechanically renamed (`report.pdf`,
+ * `report-2.pdf`, ...) and the rename is disclosed to the agent through the
+ * input-files prompt section, so no execution is ever burned over a
+ * resolvable name and no user file silently vanishes.
+ *
+ * The `stem-2.ext` semantics deliberately mirror the React SDK composer's
+ * client-side rename (sdk/react/src/attachment/attachment-utils.ts,
+ * `uniquifyFilename` — kept in sync by hand, the packages share no
+ * dependency), so a user sees the same rename shape whether the client or the
+ * runner performed it.
+ *
+ * Scope: this module owns NAMES only. What constitutes a collision is the
+ * caller's business — the deep-agent injector keys on full mount paths
+ * (explicit `mountPath` values participate), the Cursor resolver keys on bare
+ * filenames under `inputs/`. Callers that consider a collision a user
+ * contradiction (two attachments explicitly pinning the same mount path)
+ * keep rejecting; only mechanically derived names are renamed.
+ */
+
+/** The outcome of allocating a unique name for one attachment. */
+export interface AllocatedName {
+  /** The final name — unchanged when it was free, `stem-N.ext` otherwise. */
+  readonly name: string;
+  /**
+   * The original requested name, present only when a rename happened — the
+   * disclosure payload the prompt builders render so the agent can still
+   * connect "the two report.pdfs" in the user's message to distinct files.
+   */
+  readonly renamedFrom?: string;
+}
+
+/**
+ * Returns `name` unchanged when it is not in `taken`, otherwise the first
+ * free `stem-2.ext`, `stem-3.ext`, … variant.
+ *
+ * Byte-for-byte twin of the React SDK's `uniquifyFilename`
+ * (sdk/react/src/attachment/attachment-utils.ts) so client-side and
+ * runner-side renames are indistinguishable to the user.
+ */
+export function uniquifyFilename(
+  name: string,
+  taken: ReadonlySet<string>,
+): string {
+  if (!taken.has(name)) return name;
+
+  const dotIndex = name.lastIndexOf(".");
+  // A leading dot (".env") is a hidden-file prefix, not an extension.
+  const stem = dotIndex > 0 ? name.slice(0, dotIndex) : name;
+  const ext = dotIndex > 0 ? name.slice(dotIndex) : "";
+
+  for (let n = 2; ; n++) {
+    const candidate = `${stem}-${n}${ext}`;
+    if (!taken.has(candidate)) return candidate;
+  }
+}
+
+/**
+ * Allocate a unique name against `taken`, claiming the result in the set so
+ * sequential allocations see each other. Returns the disclosure payload
+ * (`renamedFrom`) when the name had to change.
+ */
+export function allocateUniqueName(
+  name: string,
+  taken: Set<string>,
+): AllocatedName {
+  const unique = uniquifyFilename(name, taken);
+  taken.add(unique);
+  return unique === name ? { name: unique } : { name: unique, renamedFrom: name };
+}

package/src/shared/attachment-vision.ts

@@ -16,6 +16,14 @@
  * authoritative. A declared image whose bytes are not a recognizable image
  * degrades to the file-pointer story instead of shipping a mislabeled payload.
  *
+ * Model capability gate: eligibility also consults the execution model's
+ * vision capability, sourced from the model registry's `capabilities.vision`
+ * flag (model-registry.ts, `getModelVisionCapability`) and passed in at
+ * budget construction. The gate fails OPEN on unknown — only an explicit
+ * `vision: false` degrades — because most registry entries have never been
+ * capability-assessed, and blocking images on missing data would regress
+ * behavior that works today (issue #370 has the full evidence trail).
+ *
  * Degradation is always non-fatal and always disclosed: an image the model
  * cannot see is announced in the prompt (see {@link visionDisclosureLines}) so
  * the agent can tell the user instead of silently ignoring a photo the user
@@ -83,7 +91,14 @@ export type VisionDegradedReason =
   /** A real image type the current harness cannot display (e.g. WebP on Cursor). */
   | "unsupported_format"
   /** Declared as an image but the bytes are not a recognizable image (HEIC named .jpg, corrupt file). */
-  | "type_mismatch";
+  | "type_mismatch"
+  /**
+   * The model registry explicitly flags the execution's model as unable to
+   * see images (`capabilities.vision: false`). Unlike every other reason,
+   * this one is not resend-fixable — no smaller or re-encoded image can help
+   * — so the disclosure gives it its own honest wording.
+   */
+  | "model_no_vision";
 
 export type VisionOutcome =
   | { readonly kind: "accepted"; readonly image: VisionImage }
@@ -187,17 +202,32 @@ export class VisionBudget {
   private readonly maxImageBytes: number;
   private readonly maxTotalBytes: number;
   private readonly maxImages: number;
+  /**
+   * Tri-state model capability from the registry (model-registry.ts,
+   * `getModelVisionCapability`). Only an explicit `false` gates: `undefined`
+   * means the capability was never assessed (or the registry was
+   * unreachable, or the model is the Cursor "default" Auto pool), and the
+   * policy fails OPEN on unknown — degrading every image because a flag is
+   * missing would regress behavior that works today.
+   */
+  private readonly modelVision?: boolean;
   private totalBytes = 0;
   private imageCount = 0;
 
   constructor(
     profile: VisionProfile,
-    limits?: { maxImageBytes?: number; maxTotalBytes?: number; maxImages?: number },
+    options?: {
+      maxImageBytes?: number;
+      maxTotalBytes?: number;
+      maxImages?: number;
+      modelVision?: boolean;
+    },
   ) {
     this.profile = profile;
-    this.maxImageBytes = limits?.maxImageBytes ?? MAX_VISION_IMAGE_BYTES;
-    this.maxTotalBytes = limits?.maxTotalBytes ?? MAX_VISION_TOTAL_BYTES;
-    this.maxImages = limits?.maxImages ?? MAX_VISION_IMAGES;
+    this.maxImageBytes = options?.maxImageBytes ?? MAX_VISION_IMAGE_BYTES;
+    this.maxTotalBytes = options?.maxTotalBytes ?? MAX_VISION_TOTAL_BYTES;
+    this.maxImages = options?.maxImages ?? MAX_VISION_IMAGES;
+    this.modelVision = options?.modelVision;
   }
 
   /** Evaluate one attachment's bytes against every eligibility and budget rule. */
@@ -205,6 +235,17 @@ export class VisionBudget {
     const sniffed = sniffImageMime(bytes);
     const declaredIsImage = declaredType.toLowerCase().startsWith("image/");
 
+    // The blind-model gate comes before every other rule: for a model that
+    // cannot see images, format/size/budget reasons would be irrelevant and
+    // their "resend smaller" advice actively misleading. Anything
+    // image-shaped (recognizable bytes OR a declared image type) is
+    // disclosed; everything else stays on the silent file story.
+    if (this.modelVision === false) {
+      return sniffed !== undefined || declaredIsImage
+        ? { kind: "degraded", reason: "model_no_vision" }
+        : { kind: "skipped" };
+    }
+
     if (sniffed === undefined) {
       // Declared an image but isn't one we can recognize — the user plausibly
       // expects it to be seen (iPhone HEIC renamed .jpg is the common case),
@@ -250,6 +291,28 @@ export class VisionBudget {
   offerOversized(): VisionOutcome {
     return { kind: "degraded", reason: "too_large" };
   }
+
+  /**
+   * True when the model is explicitly flagged as unable to see images, so no
+   * candidate can ever be accepted. Callers on a no-read path (the Cursor
+   * local-file fast branch) check this BEFORE stat/size logic — a blind
+   * model's oversized image must report {@link offerBlind}'s honest reason,
+   * never `too_large`'s "resend smaller" advice — then record the outcome
+   * via {@link offerBlind}, mirroring the exceedsImageCap/offerOversized
+   * pattern.
+   */
+  modelCannotSee(): boolean {
+    return this.modelVision === false;
+  }
+
+  /**
+   * Record a vision candidate the caller chose not to read because
+   * {@link modelCannotSee} was true — the model's blindness alone settles
+   * the outcome.
+   */
+  offerBlind(): VisionOutcome {
+    return { kind: "degraded", reason: "model_no_vision" };
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -331,6 +394,8 @@ function reasonLabel(reason: VisionDegradedReason): string {
       return "unsupported format";
     case "type_mismatch":
       return "unreadable image format";
+    case "model_no_vision":
+      return "model cannot view images";
   }
 }
 
@@ -358,10 +423,28 @@ export function visionDisclosureLines(
       .map((e) => `\`${e.path}\` (${reasonLabel(e.reason)})`)
       .join(", ");
     lines.push(`NOT VIEWABLE INLINE: ${entries}.`);
-    lines.push(
-      "You cannot see these files; if you need one, ask the user to resend it " +
-        "as a smaller PNG or JPEG.",
-    );
+    // The advice must match the reason. Resending helps only when the image
+    // itself was the problem; for a blind model that advice would send the
+    // user on a pointless resize-and-resend errand, so that arm gets its own
+    // honest wording. (In practice a blind model degrades EVERY image, so
+    // the two lines rarely co-occur — but the wording stays reason-accurate
+    // either way.)
+    const resendFixable = notViewable.filter((e) => e.reason !== "model_no_vision");
+    const modelBlind = notViewable.filter((e) => e.reason === "model_no_vision");
+    if (resendFixable.length > 0) {
+      lines.push(
+        "You cannot see these files; if you need one, ask the user to resend it " +
+          "as a smaller PNG or JPEG.",
+      );
+    }
+    if (modelBlind.length > 0) {
+      lines.push(
+        "The current model does not support image input, so no resend will " +
+          "help. The files are saved on disk at the paths above; if the user " +
+          "needs an image understood, suggest switching to a vision-capable " +
+          "model.",
+      );
+    }
   }
   if (inlineFilenames.length > 0) {
     lines.push(

package/src/shared/caller-identity.ts

@@ -10,8 +10,10 @@
  *   2. The session creator (`stigmer_user`) from the Session resource's
  *      audit actor — console/CLI sessions have no channel sender, but the
  *      platform knows exactly who created the session.
- *   3. The anonymous sentinel — discovery (no session exists) and sessions
- *      with no readable creator. Consumers must treat anonymous as a
+ *   3. The anonymous sentinel — discovery (no session exists), sessions
+ *      with no readable creator, and sessions whose creator is the
+ *      backend's "system" audit placeholder (not a principal — see
+ *      SYSTEM_CREATOR_SENTINEL). Consumers must treat anonymous as a
  *      first-class caller: answer tools/list, refuse tool calls.
  *
  * Injection is opt-in by construction: the values enter the env map used
@@ -54,6 +56,20 @@ export const STIGMER_USER_KIND = "stigmer_user";
  */
 export const ANONYMOUS_KIND = "anonymous";
 
+/**
+ * Audit-actor id that backends stamp when NO caller identity exists —
+ * the OSS server writes it on every create (no local auth), and the
+ * cloud's AuditActorBuilder falls back to it for caller-less internal
+ * writes. It names "nobody in particular": unrelated sessions from
+ * unrelated people all carry it, so presenting it as a caller identity
+ * would make the one string a grantable value that silently covers ALL
+ * such traffic in an MCP server's binding sheet. A creator matching this
+ * sentinel (and carrying no email) is therefore unresolvable and falls
+ * to anonymous — the deny-by-default the docs guide already promises
+ * for self-hosted backends.
+ */
+export const SYSTEM_CREATOR_SENTINEL = "system";
+
 /** The resolved caller identity. */
 export interface CallerIdentity {
   kind: string;
@@ -79,6 +95,12 @@ export function anonymousCallerIdentity(): CallerIdentity {
  * humans, and the audit actor's `id` field is historically mixed
  * (identity-account id vs email — see the proto's own @internal note).
  * Binding matchers should compare emails case-insensitively.
+ *
+ * A creator with no email whose id is the "system" audit placeholder is
+ * NOT a principal (see SYSTEM_CREATOR_SENTINEL) and resolves to
+ * anonymous. Email-first is deliberate here too: a real account that
+ * merely has "system" somewhere in its id is never demoted, because its
+ * email wins before the sentinel check runs.
  */
 export function resolveCallerIdentity(
   sessionMetadata: Record<string, string> | undefined,
@@ -90,10 +112,23 @@ export function resolveCallerIdentity(
   }
 
   const email = creator?.email?.trim();
+  if (email) {
+    return { kind: STIGMER_USER_KIND, value: email };
+  }
+
   const id = creator?.id?.trim();
-  const value = email || id;
-  if (value) {
-    return { kind: STIGMER_USER_KIND, value };
+  if (id === SYSTEM_CREATOR_SENTINEL) {
+    // Operator tripwire: identity-gated MCP tools will refuse this
+    // session; the fix is real caller attribution, never a "system" grant.
+    console.info(
+      `Session creator is the "${SYSTEM_CREATOR_SENTINEL}" audit placeholder ` +
+      `(no email) — not a resolvable principal; presenting the anonymous ` +
+      `caller identity to MCP servers`,
+    );
+    return anonymousCallerIdentity();
+  }
+  if (id) {
+    return { kind: STIGMER_USER_KIND, value: id };
   }
 
   return anonymousCallerIdentity();

package/src/shared/channel-attachment.ts

@@ -128,6 +128,7 @@ export function synthesizeChannelAttachment(
     slug: CHANNEL_ATTACHMENT_SLUG,
     toolApprovals: [],
     pinnedToolApprovals: [],
+    toolApprovalOverrides: [],
     discoveredCapabilitiesEmpty: false,
   };