@zackbart/connecta 0.9.1 → 0.10.1

package/src/access-tokens.ts

@@ -0,0 +1,289 @@
+import type { AuthResult, InboundAuth, KVStorage } from "./types.js";
+
+const TOKEN_PREFIX = "cta_";
+const TOKEN_BYTES = 32;
+const TOKEN_VALUE_RE = /^cta_[A-Za-z0-9_-]{43}$/;
+const RECORD_PREFIX = "access-token:v1:record:";
+const LOOKUP_PREFIX = "access-token:v1:lookup:";
+const MAX_NAME_CHARACTERS = 80;
+const DEFAULT_MAX_ACTIVE = 100;
+const MAX_CONFIGURED_ACTIVE = 1_000;
+const encoder = new TextEncoder();
+
+interface StoredAccessToken {
+  version: 1;
+  id: string;
+  name: string;
+  tokenHash: string;
+  tokenPrefix: string;
+  createdAt: string;
+  createdBy: string;
+  revokedAt?: string;
+  revokedBy?: string;
+}
+
+interface TokenLookup {
+  version: 1;
+  id: string;
+}
+
+export interface AccessTokenMetadata {
+  id: string;
+  name: string;
+  tokenPrefix: string;
+  createdAt: string;
+  revokedAt?: string;
+}
+
+export interface CreatedAccessToken {
+  token: string;
+  accessToken: AccessTokenMetadata;
+}
+
+function recordKey(id: string): string {
+  return `${RECORD_PREFIX}${id}`;
+}
+
+function lookupKey(hash: string): string {
+  return `${LOOKUP_PREFIX}${hash}`;
+}
+
+function bytesToBase64Url(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary)
+    .replaceAll("+", "-")
+    .replaceAll("/", "_")
+    .replace(/=+$/u, "");
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  return [...bytes]
+    .map((byte) => byte.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+async function hashToken(token: string): Promise<string> {
+  return bytesToHex(
+    new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(token))),
+  );
+}
+
+function normalizeName(value: unknown): string {
+  if (typeof value !== "string") {
+    throw new Error("Token name must be a string");
+  }
+  const compact = value.replace(/\s+/gu, " ").trim();
+  if (!compact) throw new Error("Token name cannot be empty");
+  if (Array.from(compact).length > MAX_NAME_CHARACTERS) {
+    throw new Error(
+      `Token name cannot exceed ${MAX_NAME_CHARACTERS} characters`,
+    );
+  }
+  return compact;
+}
+
+function parseRecord(raw: string): StoredAccessToken {
+  try {
+    const value = JSON.parse(raw) as Partial<StoredAccessToken>;
+    if (
+      value.version !== 1 ||
+      typeof value.id !== "string" ||
+      !/^[0-9a-f-]{36}$/u.test(value.id) ||
+      typeof value.name !== "string" ||
+      typeof value.tokenHash !== "string" ||
+      !/^[0-9a-f]{64}$/u.test(value.tokenHash) ||
+      typeof value.tokenPrefix !== "string" ||
+      typeof value.createdAt !== "string" ||
+      typeof value.createdBy !== "string" ||
+      (value.revokedAt !== undefined &&
+        typeof value.revokedAt !== "string") ||
+      (value.revokedBy !== undefined &&
+        typeof value.revokedBy !== "string")
+    ) {
+      throw new Error("invalid token record");
+    }
+    return value as StoredAccessToken;
+  } catch {
+    throw new Error("Stored access token metadata is invalid or corrupted");
+  }
+}
+
+function parseLookup(raw: string): TokenLookup | null {
+  try {
+    const value = JSON.parse(raw) as Partial<TokenLookup>;
+    return value.version === 1 && typeof value.id === "string"
+      ? { version: 1, id: value.id }
+      : null;
+  } catch {
+    return null;
+  }
+}
+
+function metadata(record: StoredAccessToken): AccessTokenMetadata {
+  return {
+    id: record.id,
+    name: record.name,
+    tokenPrefix: record.tokenPrefix,
+    createdAt: record.createdAt,
+    ...(record.revokedAt ? { revokedAt: record.revokedAt } : {}),
+  };
+}
+
+function unauthorized(): AuthResult {
+  return {
+    ok: false,
+    response: new Response(JSON.stringify({ error: "unauthorized" }), {
+      status: 401,
+      headers: {
+        "Content-Type": "application/json",
+        "WWW-Authenticate": "Bearer",
+      },
+    }),
+  };
+}
+
+/**
+ * Deployment-scoped personal access tokens. Secret material is never
+ * recoverable: authentication indexes a SHA-256 digest of a random 256-bit
+ * token, while separately enumerable metadata powers operator management.
+ */
+export class AccessTokenManager {
+  readonly auth: InboundAuth;
+  private readonly maxActive: number;
+
+  constructor(
+    private readonly storage: KVStorage,
+    options: { maxActive?: number } = {},
+  ) {
+    if (!storage.list) {
+      throw new Error(
+        "accessTokens requires a storage adapter that implements list(prefix)",
+      );
+    }
+    const maxActive = options.maxActive ?? DEFAULT_MAX_ACTIVE;
+    if (
+      !Number.isInteger(maxActive) ||
+      maxActive < 1 ||
+      maxActive > MAX_CONFIGURED_ACTIVE
+    ) {
+      throw new Error(
+        `accessTokens.maxActive must be a whole number from 1 to ${MAX_CONFIGURED_ACTIVE}`,
+      );
+    }
+    this.maxActive = maxActive;
+    this.auth = {
+      kind: "access_token",
+      activityActorNamespace: "connecta:access-tokens:v1",
+      activityActorLabel: async (id) => {
+        try {
+          return (await this.read(id))?.name;
+        } catch {
+          return undefined;
+        }
+      },
+      authorize: (request) => this.authorize(request),
+    };
+  }
+
+  private async read(id: string): Promise<StoredAccessToken | null> {
+    const raw = await this.storage.get(recordKey(id));
+    return raw ? parseRecord(raw) : null;
+  }
+
+  async list(): Promise<AccessTokenMetadata[]> {
+    const keys = await this.storage.list!(RECORD_PREFIX);
+    const records = await Promise.all(
+      keys.map(async (key) => {
+        const raw = await this.storage.get(key);
+        return raw ? parseRecord(raw) : null;
+      }),
+    );
+    return records
+      .filter((record): record is StoredAccessToken => Boolean(record))
+      .sort((a, b) => b.createdAt.localeCompare(a.createdAt))
+      .map(metadata);
+  }
+
+  async create(name: unknown, createdBy: string): Promise<CreatedAccessToken> {
+    const normalizedName = normalizeName(name);
+    const active = (await this.list()).filter((token) => !token.revokedAt);
+    if (active.length >= this.maxActive) {
+      throw new Error(
+        `This deployment already has the maximum of ${this.maxActive} active access tokens`,
+      );
+    }
+    const secretBytes = crypto.getRandomValues(new Uint8Array(TOKEN_BYTES));
+    const token = TOKEN_PREFIX + bytesToBase64Url(secretBytes);
+    const hash = await hashToken(token);
+    if (await this.storage.get(lookupKey(hash))) {
+      throw new Error("Access token collision; create another token");
+    }
+    const record: StoredAccessToken = {
+      version: 1,
+      id: crypto.randomUUID(),
+      name: normalizedName,
+      tokenHash: hash,
+      tokenPrefix: token.slice(0, 12),
+      createdAt: new Date().toISOString(),
+      createdBy,
+    };
+    await this.storage.set(recordKey(record.id), JSON.stringify(record));
+    try {
+      await this.storage.set(
+        lookupKey(hash),
+        JSON.stringify({ version: 1, id: record.id } satisfies TokenLookup),
+      );
+    } catch (error) {
+      await this.storage.delete(recordKey(record.id)).catch(() => {});
+      throw error;
+    }
+    return { token, accessToken: metadata(record) };
+  }
+
+  async rename(
+    id: string,
+    name: unknown,
+  ): Promise<AccessTokenMetadata | null> {
+    const record = await this.read(id);
+    if (!record) return null;
+    record.name = normalizeName(name);
+    await this.storage.set(recordKey(id), JSON.stringify(record));
+    return metadata(record);
+  }
+
+  async revoke(
+    id: string,
+    revokedBy: string,
+  ): Promise<AccessTokenMetadata | null> {
+    const record = await this.read(id);
+    if (!record) return null;
+    if (!record.revokedAt) {
+      // Admission disappears first. A metadata-write failure may leave the UI
+      // calling the record active, but can never leave a token labelled
+      // revoked while its lookup still admits requests.
+      await this.storage.delete(lookupKey(record.tokenHash));
+      record.revokedAt = new Date().toISOString();
+      record.revokedBy = revokedBy;
+      await this.storage.set(recordKey(id), JSON.stringify(record));
+    }
+    return metadata(record);
+  }
+
+  private async authorize(request: Request): Promise<AuthResult> {
+    const header = request.headers.get("authorization") ?? "";
+    const match = /^Bearer\s+(.+)$/iu.exec(header);
+    const token = match?.[1];
+    if (!token || !TOKEN_VALUE_RE.test(token)) return unauthorized();
+    const hash = await hashToken(token);
+    const lookupRaw = await this.storage.get(lookupKey(hash));
+    if (!lookupRaw) return unauthorized();
+    const lookup = parseLookup(lookupRaw);
+    if (!lookup) return unauthorized();
+    const record = await this.read(lookup.id);
+    if (!record || record.revokedAt || record.tokenHash !== hash) {
+      return unauthorized();
+    }
+    return { ok: true, subjectId: record.id };
+  }
+}

package/src/catalog-service.ts

@@ -10,7 +10,7 @@ import {
   mapSettledWithConcurrency,
   resolveDiscoveryConcurrency,
 } from "./concurrency.js";
-import { classifyCallError, messageLooksRetryable } from "./errors.js";
+import { classifyCallError, framingError } from "./errors.js";
 import type { CallErrorDetails } from "./errors.js";
 import type {
   ConnectorOperationOptions,
@@ -199,10 +199,6 @@ export type CatalogResolution =
       cause?: unknown;
     };
 
-function framingError(code: string, message: string): CallErrorDetails {
-  return { code, message, retryable: messageLooksRetryable(message) };
-}
-
 function renderSchema(schema: JsonSchema, format: "compact" | "json"): unknown {
   return format === "json" ? schema : compactSchema(schema);
 }

package/src/errors.ts

@@ -102,6 +102,34 @@ export interface CallErrorDetails {
   retry?: string;
 }
 
+/**
+ * Codes whose retryability is a fact about connecta's own framing, never a
+ * guess from text. The message embeds the address the caller asked for, so a
+ * connector named `svc-503` or `temporary-export` would otherwise flip a policy
+ * refusal into `retryable: true` through the heuristic below — and a caller that
+ * trusts the flag would cheerfully retry a refusal forever.
+ */
+const NEVER_RETRYABLE_FRAMING = new Set([
+  "unknown_address",
+  "unknown_tool",
+  "ambiguous_tool_alias",
+  "destructive_tool_requires_approval",
+]);
+
+/**
+ * Details for a failure connecta itself framed — an address it could not
+ * resolve, a tool it refuses to run — rather than one a connector threw.
+ */
+export function framingError(code: string, message: string): CallErrorDetails {
+  return {
+    code,
+    message,
+    retryable: NEVER_RETRYABLE_FRAMING.has(code)
+      ? false
+      : messageLooksRetryable(message),
+  };
+}
+
 const RETRYABLE_MESSAGE_RE =
   /timeout|timed out|econnreset|econnrefused|temporar|rate.?limit|429|502|503|504|refcountedcanceler|different request/i;
 const TIMEOUT_MESSAGE_RE = /timed out|timeout/i;

package/src/execute.ts

@@ -4,6 +4,7 @@ import type { ActivityRequestContext } from "./activity.js";
 import {
   boundedDiscoveryText,
   CatalogService,
+  DiscoveryPolicyError,
   flatSearchResult,
 } from "./catalog-service.js";
 import { errorResult, jsonResult, type ToolResult } from "./meta-tools.js";
@@ -16,12 +17,14 @@ import {
   ExecutorAdmissionError,
   isAdmittingExecutor,
 } from "./executor-admission.js";
+import { classifyCallError } from "./errors.js";
 import {
   InvocationFailure,
   InvocationService,
 } from "./invocation.js";
 import type { RegistryView } from "./registry.js";
 import type {
+  ConnectaSurface,
   Executor,
   ExecutorProvider,
   Logger,
@@ -205,6 +208,29 @@ export async function buildSandboxProviders(
       }
     },
   });
+  /**
+   * A discovery bound is as typed a failure as a tool call is, and a program
+   * that lets one escape deserves the same envelope: register it on the same
+   * request-local channel so an unhandled `invalid_args`/`result_too_large`
+   * reaches the model with its code instead of as prose. The guest still sees
+   * only the message — that is the bridge's limit, not a policy.
+   */
+  const typedDiscovery = async <T>(operation: () => Promise<T>): Promise<T> => {
+    try {
+      return await operation();
+    } catch (err) {
+      if (err instanceof DiscoveryPolicyError) {
+        limits.onInvocationFailure?.(
+          new InvocationFailure({
+            code: err.code,
+            message: err.message,
+            retryable: false,
+          }),
+        );
+      }
+      throw err;
+    }
+  };
   const callAddress = async (address: unknown, args: unknown) => {
     const outcome = await invocation.invoke(
       String(address),
@@ -262,53 +288,65 @@ export async function buildSandboxProviders(
                   data: await callAddress(item.address, item.args),
                 };
               } catch (err) {
+                // Same failure shape batch_call reports: the message a program
+                // can log, plus the typed details it must classify by. A
+                // thrown host error crosses the sandbox bridge as a bare
+                // message string in every executor, so this is the one place a
+                // program can tell a policy refusal from a transient failure.
+                const details =
+                  err instanceof InvocationFailure
+                    ? err.details
+                    : classifyCallError(err, "batch_call_failed");
                 return {
                   address: String(item.address),
                   ok: false,
-                  error: msg(err),
+                  error: details.message,
+                  errorDetails: details,
                 };
               }
             }),
           );
         },
-        search: async (raw: unknown) => {
-          const args = (raw ?? {}) as {
-            query?: string;
-            connector?: string;
-            limit?: number;
-            offset?: number;
-            fullDescriptions?: boolean;
-            includeSchemas?: "compact" | "json";
-            includeSchemaKeys?: boolean;
-          };
-          const result = flatSearchResult(
-            await catalog.search({
-              ...args,
-              // Key metadata rides along with schemas by default, since that is
-              // the whole point of it in code mode. It stays opt-out because it
-              // counts against the same hard discovery-byte ceiling.
-              includeSchemaKeys: args.includeSchemaKeys !== false,
-            }),
-          );
-          boundedDiscoveryText(
-            result,
-            "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.",
-          );
-          return result;
-        },
-        describe: async (raw: unknown) => {
-          const args = (raw ?? {}) as {
-            addresses?: unknown;
-            format?: "compact" | "json";
-            fullDescriptions?: boolean;
-          };
-          const result = { tools: await catalog.describe(args) };
-          boundedDiscoveryText(
-            result,
-            'Split the address list or use format: "compact".',
-          );
-          return result;
-        },
+        search: async (raw: unknown) =>
+          typedDiscovery(async () => {
+            const args = (raw ?? {}) as {
+              query?: string;
+              connector?: string;
+              limit?: number;
+              offset?: number;
+              fullDescriptions?: boolean;
+              includeSchemas?: "compact" | "json";
+              includeSchemaKeys?: boolean;
+            };
+            const result = flatSearchResult(
+              await catalog.search({
+                ...args,
+                // Key metadata rides along with schemas by default, since that
+                // is the whole point of it in code mode. It stays opt-out
+                // because it counts against the same discovery-byte ceiling.
+                includeSchemaKeys: args.includeSchemaKeys !== false,
+              }),
+            );
+            boundedDiscoveryText(
+              result,
+              "Request a smaller limit, omit fullDescriptions, use compact schemas, or pass includeSchemaKeys: false.",
+            );
+            return result;
+          }),
+        describe: async (raw: unknown) =>
+          typedDiscovery(async () => {
+            const args = (raw ?? {}) as {
+              addresses?: unknown;
+              format?: "compact" | "json";
+              fullDescriptions?: boolean;
+            };
+            const result = { tools: await catalog.describe(args) };
+            boundedDiscoveryText(
+              result,
+              'Split the address list or use format: "compact".',
+            );
+            return result;
+          }),
       },
     },
   ];
@@ -413,13 +451,26 @@ export function createExecuteTool(
       // an unhandled tool failure keeps the same structured contract as
       // call_tool and batch_call. Failures caught by model code never reach
       // outcome.error and therefore remain under that code's control.
+      //
+      // An error the program let through unchanged matches exactly, and an
+      // exact match always wins: a program that wrapped one failure's message
+      // around another's must not have the wrong type attached. Containment is
+      // the fallback, so a wrapped message still reports its underlying type
+      // rather than losing it to prose.
       let invocationFailure: InvocationFailure | undefined;
-      for (let i = invocationFailures.length - 1; i >= 0; i--) {
-        const candidate = invocationFailures[i];
-        if (candidate && outcome.error.includes(candidate.message)) {
-          invocationFailure = candidate;
-          break;
+      for (const match of [
+        (candidate: InvocationFailure) => outcome.error === candidate.message,
+        (candidate: InvocationFailure) =>
+          outcome.error?.includes(candidate.message) === true,
+      ]) {
+        for (let i = invocationFailures.length - 1; i >= 0; i--) {
+          const candidate = invocationFailures[i];
+          if (candidate && match(candidate)) {
+            invocationFailure = candidate;
+            break;
+          }
         }
+        if (invocationFailure) break;
       }
       if (invocationFailure) {
         const result = jsonResult({
@@ -451,15 +502,37 @@ export function createExecuteTool(
   };
 }
 
-const EXECUTE_DESC = `Use for dependent multi-step calls, loops, joins, branching, or reducing large results in a sandbox. Never use execute_code for search-only discovery or one downstream call: use search_tools, then call_tool when needed. For 2–10 independent calls use batch_call. Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
+/**
+ * How the tool opens, and where a program's argument schemas come from. Both
+ * differ by surface: on the classic surface `execute_code` is the tool of last
+ * resort and its neighbours (`batch_call`, `describe_tools`) own the simpler
+ * jobs, while on the code-first surface those tools are gone and the program is
+ * where all of that work happens. Everything after these two phrases is
+ * identical, so the shared body below has one source of truth.
+ */
+const EXECUTE_ROUTING = {
+  classic:
+    "Use for dependent multi-step calls, loops, joins, branching, or reducing large results in a sandbox. Never use execute_code for search-only discovery or one downstream call: use search_tools, then call_tool when needed. For 2–10 independent calls use batch_call.",
+  "code-first":
+    "The primary surface. Use for discovery beyond one lookup, two or more calls, dependent steps, loops, joins, branching, or reducing large results before they reach the model — connecta.search and connecta.describe browse and expand catalogs in the run, and connecta.batch replaces a separate batch tool. The exception is a single call at an address already in hand: search_tools then one call_tool is cheaper than a program.",
+} as const;
+
+const EXECUTE_SCHEMA_SOURCE = {
+  classic: "describe_tools",
+  "code-first": "connecta.describe",
+} as const;
+
+const executeDescription = (
+  surface: ConnectaSurface,
+) => `${EXECUTE_ROUTING[surface]} Only tools explicitly annotated readOnlyHint: true are available. Each run is limited to ${EXECUTE_MAX_HOST_CALLS} host calls; connecta.batch accepts at most ${EXECUTE_MAX_BATCH_CALLS}; each host call has a ${EXECUTE_HOST_CALL_TIMEOUT_MS / 1_000}-second deadline.
 
 Write an async arrow function. It runs with NO network, filesystem, timers, or imports — the only capabilities are:
-- One global per connector: every address <connectorId>.<toolName> from search_tools is callable as <connectorId>.<toolName>(args) with a single args object matching the schema from describe_tools. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (e.g. my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words get "_" appended.
+- One global per connector: every address <connectorId>.<toolName> from search_tools is callable as <connectorId>.<toolName>(args) with a single args object matching the schema from ${EXECUTE_SCHEMA_SOURCE[surface]}. Names are sanitized to JS identifiers: characters outside [A-Za-z0-9_$] become "_" (e.g. my-service.get.thing → my_service.get_thing), leading digits get "_" prefixed, reserved words get "_" appended.
 - connecta.call(address, args) and connecta.batch(calls) — call raw addresses.
 - connecta.search(args) and connecta.describe(args) — load and inspect request-local catalogs on demand. Matches carrying schemas also list inputKeys, requiredInputKeys, and outputKeys — the same names the schema shows, ready to check against before building args. They are absent when a schema is not a plain object shape, so read the schema itself rather than assuming a missing list means no fields.
 - console.log(...) — captured and returned alongside the result.
 
-Tool calls return plain values (MCP text content is JSON-parsed when possible) and throw on downstream errors — use try/catch to handle them. Return a JSON-serializable value; large results are truncated, so reduce data in code instead of returning raw payloads.
+Tool calls return plain values (MCP text content is JSON-parsed when possible) and throw on downstream errors — use try/catch to handle them. A thrown error carries only a message; connecta.batch reports each call as { address, ok: true, data } or { address, ok: false, error, errorDetails: { code, retryable } }, so use it when the program must tell a policy refusal from a transient failure. Never retry a failure whose retryable is false, and never retry a rate_limited one immediately — the sandbox has no timers. Return a JSON-serializable value; large results are truncated, so reduce data in code instead of returning raw payloads.
 
 Plain JavaScript only — no TypeScript syntax. For unknown-address dependent work, use one execute_code call: search inside it, read the compact schemas, and continue to the dependent calls; do not return search results for a second execute_code call. Compact schemas are TypeScript-like strings, not JSON Schema objects: write the property names they display, never a positional guess or an invented alias.
 Dependent example (only when the second call requires a value returned by the first): async () => { const { tools } = await connecta.search({ query: "pipeline run job logs", includeSchemas: "compact" }); const pick = (suffix) => { const match = tools.find((tool) => tool.address.endsWith(suffix)); if (!match) throw new Error("no tool matching " + suffix); return match.address; }; const run = await connecta.call(pick(".get_run"), { runId: 42 }); const logs = await connecta.call(pick(".get_job_logs"), { jobId: run.failedJobId }); return [run, logs]; }`;
@@ -475,6 +548,8 @@ export function registerExecuteTool(
     activity?: ActivityRequestContext;
     requestSignal?: AbortSignal;
     discoveryConcurrency?: number;
+    /** The advertised surface, which decides this tool's routing copy. */
+    surface?: ConnectaSurface;
   },
 ): void {
   const handler = createExecuteTool(
@@ -490,7 +565,7 @@ export function registerExecuteTool(
   server.registerTool(
     "execute_code",
     {
-      description: EXECUTE_DESC,
+      description: executeDescription(ctx.surface ?? "classic"),
       inputSchema: z.object({
         code: z
           .string()

package/src/executor-result.ts

@@ -13,15 +13,59 @@ function serializeExecuteValue(value: unknown): string {
   return serialized === undefined ? String(value) : serialized;
 }
 
+const TRUNCATION_HINT =
+  "filter/map/slice data inside execute_code and return only what you need";
+
+/**
+ * Shape the over-cap notice so the **serialized envelope** fits the same cap
+ * the raw value missed. Escaping matters: a preview sliced to the cap is JSON
+ * text whose quotes and newlines re-escape to well over it, so a fixed slice
+ * would leave the envelope over-cap and a second pass through this guard would
+ * truncate the truncation — reporting the envelope's length as `totalChars` and
+ * burying the real size. Shrinking proportionally until it fits keeps the guard
+ * idempotent by construction: `totalChars` is always the true serialized size
+ * of what the program returned, and truncation happens exactly once no matter
+ * how many hops the value takes.
+ */
+function truncationEnvelope(text: string): {
+  truncated: true;
+  preview: string;
+  totalChars: number;
+  hint: string;
+} {
+  const base = {
+    truncated: true as const,
+    preview: "",
+    totalChars: text.length,
+    hint: TRUNCATION_HINT,
+  };
+  let budget = Math.max(
+    0,
+    MAX_EXECUTE_RESULT_CHARS - JSON.stringify(base).length,
+  );
+  for (let attempt = 0; attempt < 8 && budget > 0; attempt += 1) {
+    const candidate = { ...base, preview: text.slice(0, budget) };
+    const size = JSON.stringify(candidate).length;
+    if (size <= MAX_EXECUTE_RESULT_CHARS) return candidate;
+    // Every character costs at least one serialized character, so scaling by
+    // the overshoot ratio (minus a step) strictly shrinks the budget.
+    budget = Math.max(
+      0,
+      Math.floor(budget * (MAX_EXECUTE_RESULT_CHARS / size)) - 8,
+    );
+  }
+  // The loop shrinks monotonically, so this is unreachable in practice — but an
+  // unchecked slice is exactly how a "bounded" envelope stops being bounded.
+  const clamped = { ...base, preview: text.slice(0, Math.max(0, budget)) };
+  return JSON.stringify(clamped).length <= MAX_EXECUTE_RESULT_CHARS
+    ? clamped
+    : { ...base, preview: "" };
+}
+
 export function guardExecuteResultValue(value: unknown): unknown {
   const text = serializeExecuteValue(value);
   if (text.length <= MAX_EXECUTE_RESULT_CHARS) return value;
-  return {
-    truncated: true,
-    preview: text.slice(0, MAX_EXECUTE_RESULT_CHARS),
-    totalChars: text.length,
-    hint: "filter/map/slice data inside execute_code and return only what you need",
-  };
+  return truncationEnvelope(text);
 }
 
 export function truncateExecuteText(text: string, max: number): string {