fix(kiro): bound the tool catalog so large MCP sessions still generate

truncateDescription() shortened each description but nothing capped the
catalog as a whole, so a session with many MCP tools shipped an unbounded
spec list and Kiro returned CONTENT_FILTERED before generating anything.

The catalog is now capped at 48 tools and 96 KiB of converted JSON.
Issue #719's own successful probe used 49 outbound tools at roughly
108 KiB, so the caps sit just under a size known to work, leaving a slot
for Kiro's private completion tool and headroom for the enclosing
request. These are not published limits and the constants say so.

What gets dropped matters more than the number. Declaration order is
preserved and only the oversized suffix is omitted, so the same session
yields the same catalog every time. The omission is reported to the
model with a count and the first omitted names, because a tool that
silently disappears is indistinguishable to the model from a tool that
never existed -- it will confidently tell the user the capability is
unavailable. Better to say what was cut.

Ablated by raising both caps out of reach: the count and byte tests both
fail. Neither passes on per-description truncation alone, which was the
trap worth avoiding here.

Author: lidge-jun

src/adapters/kiro-tools.ts

@@ -1,10 +1,15 @@
-import type { OcxParsedRequest } from "../types";
+import type { OcxParsedRequest, OcxTool } from "../types";
 import { namespacedToolName } from "../types";
 import { normalizeKiroModelId } from "../providers/kiro-models";
 import { createKiroToolNameRegistry, type KiroToolNameRegistry } from "./kiro-wire";
 
 const MAX_KIRO_TOOL_DESCRIPTION_UNVERIFIED = 1024;
 const MAX_KIRO_TOOL_DESCRIPTION_GPT_56_SOL = 9_216;
+// Issue #719's successful Kiro probe used 49 outbound tools at about 108 KiB. Leave one of those
+// slots for Kiro's private completion tool and headroom for the enclosing request/message fields.
+export const MAX_KIRO_TOOL_COUNT = 48;
+export const MAX_KIRO_TOOL_CATALOG_BYTES = 96_000;
+const textEncoder = new TextEncoder();
 
 // JSON Schema validation/annotation keywords that Kiro's runtimeservice tool-spec validator
 // rejects ("ValidationException: Invalid tool use format."). Codex's built-in tools omit these,
@@ -147,6 +152,17 @@ function truncateDescription(description: string, limit: number): string {
   return `${description.slice(0, limit - 1)}…`;
 }
 
+function serializedToolCatalogBytes(tools: readonly unknown[]): number {
+  return textEncoder.encode(JSON.stringify(tools)).byteLength;
+}
+
+function omittedToolCatalogNotice(kept: number, omitted: readonly OcxTool[], registry: KiroToolNameRegistry): string {
+  const names = omitted.slice(0, 12).map(tool => registry.alias(namespacedToolName(tool.namespace, tool.name)));
+  const remainder = omitted.length - names.length;
+  const summary = `${names.join(", ")}${remainder > 0 ? `, and ${remainder} more` : ""}`;
+  return `[opencodex] Kiro's outbound catalog budget allows ${kept} of ${kept + omitted.length} client tools this turn. Omitted and unavailable this turn: ${summary}.`;
+}
+
 export function convertKiroToolContext(
   parsed: OcxParsedRequest,
   registry: KiroToolNameRegistry = createKiroToolNameRegistry(),
@@ -156,24 +172,39 @@ export function convertKiroToolContext(
   // Validate every listed name even when tool_choice:none emulates a tool-free turn.
   for (const tool of tools) registry.alias(namespacedToolName(tool.namespace, tool.name));
   const effectiveTools = parsed.options.toolChoice === "none" ? [] : tools;
+  const convertedTools: unknown[] = [];
+  let omittedAt = effectiveTools.length;
+  for (const [index, tool] of effectiveTools.entries()) {
+    const description = tool.description || `Tool: ${tool.name}`;
+    // Send the full namespaced wire name (e.g. mcp__chrome-devtools__navigate_page) so Kiro echoes
+    // it back; the bridge's toolNsMap is keyed by this name and restores the MCP namespace Codex
+    // routes by. Kiro's runtimeservice rejects names with spaces or >64 chars, so normalize to a
+    // safe form and remember the mapping; the response parser restores the original wire name.
+    const wireName = namespacedToolName(tool.namespace, tool.name);
+    const toolName = registry.alias(wireName);
+    const converted = {
+      toolSpecification: {
+        name: toolName,
+        description: truncateDescription(description, descriptionLimit),
+        inputSchema: { json: ensureRootObjectType(sanitizeKiroSchema(tool.parameters ?? {})) },
+      },
+    };
+    // Preserve declaration order and only omit a suffix. Ranking tools would make a catalog change
+    // silently alter which capability disappears; this deterministic policy is paired with a
+    // model-visible omission notice so unavailable tools are explicit rather than assumed absent.
+    if (
+      convertedTools.length >= MAX_KIRO_TOOL_COUNT
+      || serializedToolCatalogBytes([...convertedTools, converted]) > MAX_KIRO_TOOL_CATALOG_BYTES
+    ) {
+      omittedAt = index;
+      break;
+    }
+    convertedTools.push(converted);
+  }
+  const omittedTools = effectiveTools.slice(omittedAt);
   return {
-    tools: effectiveTools.map(t => {
-      const description = t.description || `Tool: ${t.name}`;
-      // Send the full namespaced wire name (e.g. mcp__chrome-devtools__navigate_page) so Kiro echoes
-      // it back; the bridge's toolNsMap is keyed by this name and restores the MCP namespace Codex
-      // routes by. Kiro's runtimeservice rejects names with spaces or >64 chars, so normalize to a
-      // safe form and remember the mapping; the response parser restores the original wire name.
-      const wireName = namespacedToolName(t.namespace, t.name);
-      const toolName = registry.alias(wireName);
-      return {
-        toolSpecification: {
-          name: toolName,
-          description: truncateDescription(description, descriptionLimit),
-          inputSchema: { json: ensureRootObjectType(sanitizeKiroSchema(t.parameters ?? {})) },
-        },
-      };
-    }),
-    systemAdditions: [],
+    tools: convertedTools,
+    systemAdditions: omittedTools.length > 0 ? [omittedToolCatalogNotice(convertedTools.length, omittedTools, registry)] : [],
     nameMap: registry.nameMap,
     registry,
   };

src/adapters/kiro.ts

@@ -429,6 +429,10 @@ export function buildKiroPayload(
   // Neutralize Codex's GPT-5 identity line so a routed Kiro model never misreports as GPT-5/OpenAI
   // and the proxy identity never leaks upstream.
   if (parsed.context.systemPrompt?.length) systemParts.push(neutralizeIdentity(parsed.context.systemPrompt.join("\n\n")));
+  for (const addition of toolContext.systemAdditions) {
+    const boundedAddition = boundedInjectedInstruction(addition, injectedChars);
+    if (boundedAddition) systemParts.push(boundedAddition);
+  }
   const toolCatalogNudge = buildNonOpenAIToolCatalogNudgeFromNames(kiroToolWireNames(kiroTools));
   const boundedNudge = toolCatalogNudge ? boundedInjectedInstruction(toolCatalogNudge, injectedChars) : undefined;
   if (boundedNudge) systemParts.push(boundedNudge);

tests/kiro-adapter.test.ts

@@ -5,6 +5,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { createKiroAdapter } from "../src/adapters/kiro";
 import { KIRO_TOOL_RESULT_CARRIER_MESSAGE } from "../src/adapters/kiro-constants";
+import { MAX_KIRO_TOOL_CATALOG_BYTES, MAX_KIRO_TOOL_COUNT } from "../src/adapters/kiro-tools";
 import { applyProviderConfigHints, buildCatalogEntries } from "../src/codex/catalog";
 import { getValidAccessTokenSnapshot } from "../src/oauth";
 import { saveCredential } from "../src/oauth/store";
@@ -674,6 +675,53 @@ describe("kiro adapter — buildRequest", () => {
     expect(verifiedSpec.description.endsWith("…")).toBe(true);
   });
 
+  test("large catalogs retain the declared prefix within Kiro's count budget", async () => {
+    // Each top-level description is below the existing per-description cap: this proves the
+    // aggregate count budget, rather than that older truncation behavior, limits the catalog.
+    const tools = Array.from({ length: MAX_KIRO_TOOL_COUNT + 20 }, (_, index) => ({
+      name: `count_tool_${String(index).padStart(3, "0")}`,
+      description: `Brief description ${index}`,
+      parameters: { type: "object" },
+    }));
+    const current = JSON.parse((await createKiroAdapter(provider).buildRequest(
+      parsedWith([{ role: "user", content: "hi" }], tools),
+    )).body).conversationState.currentMessage.userInputMessage;
+    const ordinary = current.userInputMessageContext.tools.slice(0, -1);
+
+    expect(ordinary).toHaveLength(MAX_KIRO_TOOL_COUNT);
+    expect(ordinary.map((tool: { toolSpecification: { name: string } }) => tool.toolSpecification.name)).toEqual(
+      tools.slice(0, MAX_KIRO_TOOL_COUNT).map(tool => tool.name),
+    );
+    expect(current.content).toContain(`Kiro's outbound catalog budget allows ${MAX_KIRO_TOOL_COUNT} of ${tools.length} client tools`);
+    expect(current.content).toContain("count_tool_048");
+    expect(current.content).toContain("Omitted and unavailable this turn");
+  });
+
+  test("large catalogs retain the declared prefix within Kiro's serialized byte budget", async () => {
+    // Top-level descriptions stay small, so existing description truncation cannot make this pass.
+    // The repeated schema descriptions instead make the aggregate converted catalog exceed 96 KiB.
+    const tools = Array.from({ length: 40 }, (_, index) => ({
+      name: `byte_tool_${String(index).padStart(3, "0")}`,
+      description: `Brief description ${index}`,
+      parameters: {
+        type: "object",
+        properties: { payload: { type: "string", description: "x".repeat(8_000) } },
+      },
+    }));
+    const current = JSON.parse((await createKiroAdapter(provider).buildRequest(
+      parsedWith([{ role: "user", content: "hi" }], tools),
+    )).body).conversationState.currentMessage.userInputMessage;
+    const ordinary = current.userInputMessageContext.tools.slice(0, -1);
+    const serializedBytes = new TextEncoder().encode(JSON.stringify(ordinary)).byteLength;
+
+    expect(ordinary.length).toBeLessThan(tools.length);
+    expect(serializedBytes).toBeLessThanOrEqual(MAX_KIRO_TOOL_CATALOG_BYTES);
+    expect(ordinary.map((tool: { toolSpecification: { name: string } }) => tool.toolSpecification.name)).toEqual(
+      tools.slice(0, ordinary.length).map(tool => tool.name),
+    );
+    expect(current.content).toContain(`Kiro's outbound catalog budget allows ${ordinary.length} of ${tools.length} client tools`);
+  });
+
   test("historical tool calls stay structured when the current catalog is omitted", async () => {
     const messages = [
       { role: "user", content: "run it" },