@zackbart/connecta 0.28.1 → 0.30.0

package/dist/executors/quickjs.js

@@ -15,11 +15,13 @@ import { fork } from "node:child_process";
 import { existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { Deferred, Duration, Effect, Exit, Schedule, Scope } from "effect";
-import { AdmissionController, ExecutorAdmissionError, ExecutorExecutionError, } from "../executor-admission.js";
+import { AdmissionController, ExecutorAdmissionError, ExecutorExecutionError } from "../executor-admission.js";
 import { msg } from "../errors.js";
+import { InvocationFailure } from "../invocation.js";
+import { brandExecutor } from "../executor-contract.js";
 import { MAX_EXECUTE_LOG_CHARS } from "../executor-result.js";
 import { detach, fromSignal, runEdge } from "../runtime/run.js";
-import { hostCallLabel, MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
+import { hostCallLabel, MAX_QUICKJS_IPC_BYTES, MAX_QUICKJS_RESULT_BYTES, QUICKJS_RESULT_CHUNK_CHARS, MAX_QUICKJS_HOST_RPC_BYTES, serializedBytes, stringifyBounded, } from "./quickjs-protocol.js";
 export { normalizeCode } from "./quickjs-runtime.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_CPU_TIME_MS = 250;
@@ -36,10 +38,7 @@ const MAX_CHILD_STDERR_BYTES = 8 * 1024;
 const MAX_ERROR_CHARS = 4_000;
 // Respawn backoff after consecutive crashes: 100 ms, doubling, capped at 5 s.
 // A value, not a running effect: stepping it happens inside a request's fiber.
-const CRASH_BACKOFF = Schedule.min([
-    Schedule.exponential(Duration.millis(100)),
-    Schedule.spaced(Duration.seconds(5)),
-]);
+const CRASH_BACKOFF = Schedule.min([Schedule.exponential(Duration.millis(100)), Schedule.spaced(Duration.seconds(5))]);
 const crashBackoff = Effect.map(Schedule.toStep(CRASH_BACKOFF), (step) => (crashedAt) => step(crashedAt, undefined).pipe(Effect.map(([, delay]) => crashedAt + Duration.toMillis(delay)), 
 // Neither schedule ever halts; a halt here would be a broken invariant.
 Effect.orDie));
@@ -56,36 +55,27 @@ function retainStderrTail(current, chunk) {
 function childExitError(message, stderrTail) {
     if (stderrTail.length === 0)
         return new Error(message);
-    return new Error(`${message}\nRecent child stderr (last ${stderrTail.length} bytes):\n` +
-        stderrTail.toString("utf8"));
+    return new Error(`${message}\nRecent child stderr (last ${stderrTail.length} bytes):\n` + stderrTail.toString("utf8"));
 }
 function positiveWhole(value, fallback, name) {
     const resolved = value ?? fallback;
-    if (!Number.isFinite(resolved) ||
-        !Number.isInteger(resolved) ||
-        resolved < 1) {
+    if (!Number.isFinite(resolved) || !Number.isInteger(resolved) || resolved < 1) {
         throw new TypeError(`${name} must be a positive whole number.`);
     }
     return resolved;
 }
 function nonNegativeWhole(value, fallback, name) {
     const resolved = value ?? fallback;
-    if (!Number.isFinite(resolved) ||
-        !Number.isInteger(resolved) ||
-        resolved < 0) {
+    if (!Number.isFinite(resolved) || !Number.isInteger(resolved) || resolved < 0) {
         throw new TypeError(`${name} must be a non-negative whole number.`);
     }
     return resolved;
 }
 function errorPayload(error) {
-    // X11: a partial authenticated frame exposes its secret instead of decoding.
-    // Refuse it whole if a host ever bypasses execute.ts's framing bound.
-    const message = error.length > MAX_ERROR_CHARS && error.includes("\u001econnecta-error:")
-        ? `Host failure exceeded the ${MAX_ERROR_CHARS}-character bridge limit.`
-        : error.slice(0, MAX_ERROR_CHARS);
     return JSON.stringify({
         ok: false,
-        error: message,
+        error: msg(error).slice(0, MAX_ERROR_CHARS),
+        ...(error instanceof InvocationFailure ? { call: error.details } : {}),
     });
 }
 function cancelled(message) {
@@ -104,10 +94,7 @@ function unlessCancelled(effect, signal, message) {
         return effect;
     if (signal.aborted)
         return Effect.fail(cancelled(message));
-    return Effect.raceAllFirst([
-        effect,
-        fromSignal(signal).pipe(Effect.mapError(() => cancelled(message))),
-    ]);
+    return Effect.raceAllFirst([effect, fromSignal(signal).pipe(Effect.mapError(() => cancelled(message)))]);
 }
 /**
  * The child's release: SIGTERM, then wait for the exit, bounded — a child
@@ -257,6 +244,8 @@ class QuickJsChildPool {
                 id,
                 logs: [],
                 logChars: 0,
+                resultChunks: [],
+                resultBytes: 0,
                 providers: providerMap,
                 outcome: Deferred.makeUnsafe(),
             };
@@ -282,9 +271,19 @@ class QuickJsChildPool {
                 this.rejectActive(slot, error);
                 this.recycle(slot);
             }).pipe(Effect.andThen(Effect.never));
+            const started = Date.now();
             const contenders = [
                 Deferred.await(active.outcome),
-                Effect.sleep(Duration.millis(this.runtimeOptions.timeoutMs + CHILD_EXIT_GRACE_MS)).pipe(Effect.andThen(endWith(new Error(`QuickJS child exceeded the ${this.runtimeOptions.timeoutMs}ms wall budget and was terminated.`)))),
+                Effect.sleep(Duration.millis(this.runtimeOptions.timeoutMs + CHILD_EXIT_GRACE_MS)).pipe(Effect.andThen(Effect.suspend(() => {
+                    const elapsedMs = Date.now() - started;
+                    const deadlineMs = this.runtimeOptions.timeoutMs;
+                    return endWith(new InvocationFailure({
+                        code: "timeout",
+                        message: `Operation "execute_code" timed out during sandbox termination after ${elapsedMs}ms (effective deadline ${deadlineMs}ms).`,
+                        retryable: false,
+                        details: { operation: "execute_code", stage: "sandbox termination", elapsedMs, deadlineMs },
+                    }));
+                }))),
             ];
             if (signal) {
                 contenders.push(fromSignal(signal).pipe(Effect.catch(() => endWith(cancelled("Execution was cancelled.")))));
@@ -448,7 +447,9 @@ class QuickJsChildPool {
                 active.logs.push(retained);
                 active.logChars += separator + retained.length;
             }
-            catch { /* Malformed log messages carry no output. */ }
+            catch {
+                /* Malformed log messages carry no output. */
+            }
             return;
         }
         if (message.type === "host-call") {
@@ -457,15 +458,29 @@ class QuickJsChildPool {
             await this.handleHostCall(slot, child.process, active, message);
             return;
         }
-        if (message.type !== "result" || message.jobId !== active.id)
+        if ((message.type !== "result" && message.type !== "result-chunk") || message.jobId !== active.id)
             return;
-        if (serializedBytes(message.payloadJson) > MAX_QUICKJS_IPC_BYTES) {
+        if (message.payloadJson.length > QUICKJS_RESULT_CHUNK_CHARS ||
+            (message.type === "result-chunk" && message.payloadJson.length !== QUICKJS_RESULT_CHUNK_CHARS) ||
+            message.payloadJson.length === 0) {
+            this.rejectActive(slot, new Error("QuickJS execution result exceeded the IPC limit."));
+            this.recycle(slot);
+            return;
+        }
+        const bytes = serializedBytes(message.payloadJson);
+        if (active.resultBytes + bytes > MAX_QUICKJS_RESULT_BYTES) {
             this.rejectActive(slot, new Error("QuickJS execution result exceeded the IPC limit."));
             this.recycle(slot);
             return;
         }
         try {
-            const payload = JSON.parse(message.payloadJson);
+            stringifyBounded(message, "QuickJS result IPC envelope");
+            active.resultBytes += bytes;
+            active.resultChunks.push(message.payloadJson);
+            if (message.type === "result-chunk")
+                return;
+            const payload = JSON.parse(active.resultChunks.join(""));
+            active.resultChunks.length = 0;
             // A result ends any crash streak: the next crash backs off from 100 ms.
             slot.crashes.length = 0;
             slot.backoff = undefined;
@@ -487,8 +502,7 @@ class QuickJsChildPool {
     async handleHostCall(slot, child, active, message) {
         let payloadJson;
         try {
-            if (serializedBytes(message.payloadJson) >
-                MAX_QUICKJS_HOST_RPC_BYTES) {
+            if (serializedBytes(message.payloadJson) > MAX_QUICKJS_HOST_RPC_BYTES) {
                 // Refused before parsing, so there is no address to name here: parsing
                 // an over-limit payload to improve its error message would spend the
                 // work the limit exists to refuse.
@@ -496,9 +510,7 @@ class QuickJsChildPool {
             }
             const payload = JSON.parse(message.payloadJson);
             const provider = active.providers.get(payload.namespace);
-            const fn = provider && Object.hasOwn(provider.fns, payload.functionName)
-                ? provider.fns[payload.functionName]
-                : undefined;
+            const fn = provider && Object.hasOwn(provider.fns, payload.functionName) ? provider.fns[payload.functionName] : undefined;
             if (!fn) {
                 throw new Error(`Unknown function ${payload.namespace}.${payload.functionName}`);
             }
@@ -517,7 +529,7 @@ class QuickJsChildPool {
             }
         }
         catch (err) {
-            payloadJson = errorPayload(msg(err));
+            payloadJson = errorPayload(err);
         }
         if (!child.connected || slot.active !== active)
             return;
@@ -554,9 +566,7 @@ class QuickJsChildPool {
             return;
         // Never concatenate the stream with the final reply: those entries are
         // the same logs. A normal reply retains its existing full log contract.
-        const resolved = outcome.logs === undefined && active.logs.length > 0
-            ? { ...outcome, logs: active.logs }
-            : outcome;
+        const resolved = outcome.logs === undefined && active.logs.length > 0 ? { ...outcome, logs: active.logs } : outcome;
         this.clearActive(slot);
         Deferred.doneUnsafe(active.outcome, Exit.succeed(resolved));
     }
@@ -621,5 +631,5 @@ class QuickJsChildPool {
  * double-acquire deadlock at concurrency 1.
  */
 export function quickJsExecutor(options = {}) {
-    return new QuickJsChildPool(options);
+    return brandExecutor(new QuickJsChildPool(options), "leased");
 }

package/dist/favicon.js

@@ -32,8 +32,7 @@ function buildIco() {
             const dx = x - 15.5;
             const dy = y - 15.5;
             const radius = Math.sqrt(dx * dx + dy * dy);
-            const opaque = radius >= 8 && radius <= 13 &&
-                (x <= 18 || Math.abs(dy) >= 7);
+            const opaque = radius >= 8 && radius <= 13 && (x <= 18 || Math.abs(dy) >= 7);
             const row = size - 1 - y;
             const pixel = pixels + (row * size + x) * 4;
             ico[pixel + 3] = opaque ? 255 : 0;

package/dist/fix-prompt.js

@@ -18,9 +18,7 @@ const CONNECTOR_ID_RE = /^[a-z0-9_-]+$/;
  * than escaped, since a value that is not a connector id is not config.
  */
 export function renderFixPrompt(spec, connectorId) {
-    const id = connectorId !== undefined && CONNECTOR_ID_RE.test(connectorId)
-        ? connectorId
-        : undefined;
+    const id = connectorId !== undefined && CONNECTOR_ID_RE.test(connectorId) ? connectorId : undefined;
     return [
         "Diagnose and fix a problem in this connecta deployment (the @zackbart/connecta package). " +
             "It is configured as code: connectors, credential slots, OAuth clients, pools, and inbound auth " +

package/dist/guest-runtime.js

@@ -0,0 +1,238 @@
+/** Capture the single-use runner before evaluating the guest expression. */
+export function wrapGuestProgram(code) {
+    return `async () => globalThis.__connecta_run()(async (connecta) => await (\n${code}\n)())`;
+}
+/** Separate user source from the trusted wrapper before publishing Worker modules. */
+export function isolateGuestProgram(code) {
+    const prefix = "async () => globalThis.__connecta_run()(";
+    const callback = "async (connecta) => await (\n";
+    const suffix = "\n)())";
+    if (!code.startsWith(prefix + callback) || !code.endsWith(suffix))
+        return undefined;
+    return {
+        program: code.slice(prefix.length, -1),
+        // Only this fixed wrapper enters the private runner module. Matching text
+        // inside an arbitrary body/string is guest data, never a trusted wrapper.
+        wrapper: `${prefix}__connecta_user_program)`,
+    };
+}
+/**
+ * Emissions are acknowledged before success, even when the guest omits await.
+ * Capture intrinsics before user code can replace them.
+ */
+export function guestPrelude() {
+    return `${guestInitializer()}(connecta);`;
+}
+/** Protect completion promises before any Worker or QuickJS guest runs. */
+export function guestPromiseInitializer() {
+    return `(() => {
+  const NativePromise = Promise;
+  const nativeResolve = Function.prototype.call.bind(NativePromise.resolve);
+  const nativeRace = Function.prototype.call.bind(NativePromise.race);
+  const isArray = Array.isArray;
+  const iteratorKey = Symbol.iterator;
+  const arrayValues = Function.prototype.call.bind(Array.prototype.values);
+  const arrayNext = Function.prototype.call.bind(Object.getPrototypeOf([][Symbol.iterator]()).next);
+  function safeRace(values) {
+    // Upstream constructs its completion array after the program starts.
+    // Use captured array iteration, with private own methods, so neither a
+    // replaced iterator factory nor iterator.next can observe its promises.
+    if (isArray(values)) {
+      const iterator = arrayValues(values);
+      values = { __proto__: null, [iteratorKey]: () => ({ __proto__: null,
+        next: () => arrayNext(iterator) }) };
+    }
+    return nativeRace(HostPromise, values);
+  }
+  // The upstream Worker starts its Promise.race after invoking the program.
+  // Its deadline must not use a resolve function replaced during that invocation.
+  class HostPromise extends NativePromise {}
+  Object.defineProperties(HostPromise, {
+    resolve: { value: value => nativeResolve(HostPromise, value) },
+    [Symbol.species]: { value: HostPromise }
+  });
+  Object.freeze(HostPromise.prototype);
+  Object.freeze(HostPromise);
+  Object.defineProperties(NativePromise, {
+    race: { value: safeRace, writable: false, configurable: false },
+    [Symbol.species]: { value: NativePromise, configurable: false }
+  });
+  // Async return values are adopted through their prototype's then method.
+  // Guest callbacks must not change host completion.
+  Object.freeze(NativePromise.prototype);
+})()`;
+}
+/** Capture a private initializer before a Worker evaluates its guest module. */
+export function guestInitializer() {
+    return `(() => {
+  ${guestPromiseInitializer()};
+  const NativePromise = Promise;
+  const freeze = Object.freeze;
+  const defineProperties = Object.defineProperties;
+  // Protect the bridge codec and its object prototypes from guest hooks.
+  freeze(JSON);
+  freeze(Object.prototype);
+  defineProperties(globalThis, {
+    JSON: { value: JSON, writable: false, configurable: false },
+    Promise: { value: NativePromise, writable: false, configurable: false }
+  });
+  const promiseThen = Function.prototype.call.bind(NativePromise.prototype.then);
+  const promiseCatch = Function.prototype.call.bind(NativePromise.prototype.catch);
+  const promiseFinally = Function.prototype.call.bind(NativePromise.prototype.finally);
+  const push = Function.prototype.call.bind(Array.prototype.push);
+  const apply = Function.prototype.call.bind(Function.prototype.apply);
+  const NativeError = Error;
+  const NativeWeakMap = WeakMap;
+  const isArray = Array.isArray;
+  const weakGet = Function.prototype.call.bind(WeakMap.prototype.get);
+  const weakSet = Function.prototype.call.bind(WeakMap.prototype.set);
+  return freeze((provider) => {
+  const pending = [];
+  const emit = provider.emit;
+  const hostCall = provider.call;
+  const hostResult = provider.result;
+  const nativeRefs = new NativeWeakMap();
+  async function inline(value) {
+    if (!value || typeof value.transfer !== "string" || !value.handle) return value;
+    // A completed downstream call stays successful if transfer storage fails.
+    // Preserve its handle so the caller can page later, without repeating a write.
+    try {
+      let text = "", page;
+      do {
+        page = await hostResult(value.transfer);
+        text += page.text;
+      } while (page.hasMore);
+      return { data: value.handle.valueFormat === "json" ? JSON.parse(text) : text,
+        format: value.handle.valueFormat };
+    } catch { return value.handle; }
+  }
+  async function call() {
+    const reply = await apply(hostCall, undefined, arguments);
+    if (!reply || !reply.native) return inline(reply);
+    const native = await inline(reply.native.value);
+    if (native.format === "paged" && !reply.value) return native;
+    const value = reply.value ? await inline(reply.value) : {
+      data: reply.native.dataKey ? native.data[reply.native.dataKey] : native.data, format: "json"
+    };
+    if (value.format === "paged") return value;
+    if (native.format === "paged") {
+      value.contentResult = native;
+      return value;
+    }
+    if (native.format === "json" && native.data && isArray(native.data.content)) {
+      const content = native.data.content;
+      // Only host-issued refs cross back. Binary data never needs a second
+      // guest-to-host transfer, and guest edits cannot mint native pointers.
+      for (let i = 0; i < content.length; i++) {
+        weakSet(nativeRefs, content[i], { ref: reply.native.ref, index: i });
+      }
+      value.content = content;
+      weakSet(nativeRefs, value, { ref: reply.native.ref });
+    }
+    return value;
+  }
+  function trackEmission(task) {
+    const entry = { handled: false, settled: promiseThen(task,
+      () => ({ ok: true }), error => ({ ok: false, error })) };
+    push(pending, entry);
+    // Every derived promise owns propagated rejection; only an unhandled
+    // leaf fails the run, so a later catch also handles its ancestors.
+    return freeze({
+      then(resolve, reject) {
+        entry.handled = true;
+        return trackEmission(promiseThen(task, resolve, reject));
+      },
+      catch(reject) {
+        entry.handled = true;
+        return trackEmission(promiseCatch(task, reject));
+      },
+      finally(callback) {
+        entry.handled = true;
+        return trackEmission(promiseFinally(task, callback));
+      }
+    });
+  }
+  const namespace = freeze({
+    __proto__: null,
+    search: provider.search,
+    describe: provider.describe,
+    call,
+    read: provider.read,
+    result: provider.result,
+    skill: provider.skill,
+    emit(block) {
+      const ref = block && typeof block === "object" ? weakGet(nativeRefs, block) : undefined;
+      return trackEmission(emit(ref || block));
+    }
+  });
+  globalThis.connecta = namespace;
+  defineProperties(globalThis, {
+    Error: { value: NativeError, writable: false, configurable: false },
+    __connecta_run: { configurable: true, value: () => {
+      delete globalThis.__connecta_run;
+      let used = false;
+      return async (program) => {
+        if (used) throw new NativeError("Guest runner initialization is single-use.");
+        used = true;
+        const result = await program(namespace);
+        for (let i = 0; i < pending.length; i++) {
+          const report = await pending[i].settled;
+          if (!report.ok && !pending[i].handled) throw report.error;
+        }
+        return result;
+      };
+    }}
+  });
+  });
+})()`;
+}
+const ERROR_NAMES = new Set([
+    "Error",
+    "TypeError",
+    "SyntaxError",
+    "ReferenceError",
+    "RangeError",
+    "EvalError",
+    "URIError",
+    "AggregateError",
+]);
+/** Fixed repair guidance, used only in agent-facing results. */
+export function programError(raw, code) {
+    const message = typeof raw.message === "string" ? raw.message : "Program failed.";
+    const name = typeof raw.name === "string" && ERROR_NAMES.has(raw.name) ? raw.name : "Error";
+    const stack = typeof raw.stack === "string" ? raw.stack : "";
+    // Compare QuickJS/V8 locations to the wrapper baseline after the source.
+    const location = /:(\d+)(?::\d+)?\)?(?:\n|$)/.exec(stack);
+    const baseline = typeof raw.baseline === "string" ? /:(\d+)(?::\d+)?\)?(?:\n|$)/.exec(raw.baseline) : null;
+    // Workers publish only the user callback in this module, with one prefix line.
+    // Its trusted wrapper and baseline live in a separate, private module scope.
+    const workerLocation = /connecta-guest\.js:(\d+):\d+/.exec(stack);
+    const line = typeof raw.line === "number" && Number.isFinite(raw.line)
+        ? Math.max(1, raw.line)
+        : workerLocation
+            ? Math.max(1, Number(workerLocation[1]) - 1)
+            : location && baseline
+                ? Math.max(1, Number(location[1]) - Number(baseline[1]) + code.split("\n").length + 1)
+                : null;
+    let hint = "Use plain JavaScript in one async () => { ... } expression and the connecta global.";
+    if (/\brequire\b|\b[Ii]mports?\b|\bfs\b|filesystem|node:/.test(message) ||
+        (name === "SyntaxError" && /\bimport\b/.test(code))) {
+        hint =
+            "Imports, require, and filesystem access are outside the guest API. Use connecta.call to access configured services.";
+    }
+    else if (["TypeError", "ReferenceError"].includes(name) &&
+        /(?:const|let|var|function|\()\s*connecta\b/.test(code)) {
+        hint = "Do not shadow connecta. Use the host-provided connecta global.";
+    }
+    else if (/callTool|mixpanel|\bskills\b|connecta\.(?:guide|skills)/.test(message) ||
+        (["TypeError", "ReferenceError"].includes(name) && /connecta\.(?:guide|skills)\b/.test(code))) {
+        hint =
+            "Use connecta.call(address, args), connecta.search, connecta.describe, connecta.result, and connecta.skill(name). Services are addressed by connector.tool, never guest globals.";
+    }
+    return {
+        code: "program_error",
+        message: `Program ${name}: ${message}`,
+        retryable: false,
+        details: { name, line, hint },
+    };
+}

package/dist/guest-types.d.ts

@@ -0,0 +1,218 @@
+import type { ToolDef } from "./types.js";
+import type { CallErrorDetails } from "./errors.js";
+/** TypeScript notation for the JavaScript guest global; programs receive no arguments. */
+export interface GuestApi {
+    search(args?: CatalogSearchArgs): Promise<CatalogSearchResult>;
+    describe(args?: CatalogDescribeArgs): Promise<{
+        tools: CatalogDescription[];
+    }>;
+    call(address: string, args?: unknown, options?: {
+        timeoutMs?: number;
+    }): Promise<GuestResult>;
+    call(request: {
+        address: string;
+        args?: unknown;
+        timeoutMs?: number;
+    }): Promise<GuestResult>;
+    read(uri: string): Promise<GuestResourceResult>;
+    result(id: string | GuestResultHandle, options?: {
+        page?: number;
+        offset?: number;
+        maxBytes?: number;
+    }): Promise<GuestResultPage>;
+    skill(name: string): Promise<{
+        name: string;
+        text: string;
+        format: "text";
+    }>;
+    emit(block: GuestNativeBlock | GuestResult): PromiseLike<void>;
+}
+export interface GuestResourceResult {
+    contents: Array<{
+        uri: string;
+        mimeType?: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    })>;
+}
+export interface GuestResultHandle {
+    format: "paged";
+    valueFormat: "json" | "text";
+    resultId?: string;
+    totalBytes: number;
+    truncated: true;
+    hint: string;
+}
+/** Inline MCP rich results expose original blocks; emit(result) forwards all of them. */
+export type GuestResult = ({
+    data: unknown;
+    format: "json";
+} | {
+    data: string;
+    format: "text";
+} | GuestResultHandle) & {
+    content?: GuestNativeBlock[];
+    /** Paging handle when native content exceeds the inline cap or transfer fails. */
+    contentResult?: GuestResultHandle;
+};
+/** Native call blocks can be forwarded unchanged, including annotations and metadata. */
+export type GuestNativeBlock = (GuestBlock | {
+    type: "resource";
+    resource: {
+        uri: string;
+        mimeType?: string;
+    } & ({
+        text: string;
+    } | {
+        blob: string;
+    });
+} | {
+    type: "resource_link";
+    uri: string;
+    name: string;
+    title?: string;
+    description?: string;
+    mimeType?: string;
+    size?: number;
+}) & {
+    annotations?: {
+        audience?: Array<"user" | "assistant">;
+        priority?: number;
+        lastModified?: string;
+    };
+    _meta?: Record<string, unknown>;
+};
+export interface GuestResultPage {
+    resultId: string;
+    offset: number;
+    bytes: number;
+    totalBytes: number;
+    hasMore: boolean;
+    nextOffset?: number;
+    format: "text";
+    text: string;
+}
+export type GuestBlock = {
+    type: "text";
+    text: string;
+} | {
+    type: "image" | "audio";
+    data: string;
+    mimeType: string;
+};
+type SchemaFormat = "json" | "compact" | "typescript";
+export interface CatalogSearchArgs {
+    query?: string;
+    connector?: string;
+    safety?: "readOnly" | "approvalRequired" | "all";
+    limit?: number;
+    offset?: number;
+    fullDescriptions?: boolean;
+    includeSchemas?: SchemaFormat;
+    includeSchemaKeys?: boolean;
+}
+export interface CatalogDescribeArgs {
+    address?: unknown;
+    addresses?: unknown;
+    format?: SchemaFormat;
+    fullDescriptions?: boolean;
+}
+type GuideRequiredReason = "connector_required" | "approval_required" | "schema_truncated";
+interface CatalogFailureDetail extends Partial<import("./errors.js").AuthorizationHandoff> {
+    nextAction?: CallErrorDetails["nextAction"];
+    retry?: string;
+    code: string;
+    message: string;
+    retryable: boolean;
+    retryAfterMs?: number;
+}
+interface CatalogDescriptionFailureDetail extends CatalogFailureDetail {
+    configuredConnectors?: string[];
+    nextAction?: NonNullable<CallErrorDetails["nextAction"]>;
+    suggestions?: string[];
+}
+interface CatalogSearchFailure extends CatalogFailureDetail {
+    connector: string;
+    nextAction?: Extract<NonNullable<CallErrorDetails["nextAction"]>, {
+        tool: "authorize_connector";
+    }>;
+    retry?: string;
+}
+export interface CatalogSearchPage {
+    catalogErrors: CatalogSearchFailure[];
+    absence?: {
+        service: string;
+        message: string;
+        configuredConnectors: string[];
+    };
+    total: number;
+    offset: number;
+    limit: number;
+    hasMore: boolean;
+    nextOffset?: number;
+    matchMode?: "partial";
+    queryAnalysis?: {
+        representedTerms: string[];
+        otherResultTerms: string[];
+        unmatchedTerms: string[];
+        truncated?: true;
+        connectorScope?: string;
+        unknownConnector?: true;
+        configuredConnectors?: string[];
+        unavailableConnectorCount?: number;
+        catalogError?: CatalogFailureDetail;
+        guide?: string;
+        guideSummary?: string;
+        guideRequired?: true;
+        guideRequiredReasons?: GuideRequiredReason[];
+        guidance?: string;
+    };
+}
+export type CatalogSearchResult = CatalogSearchPage & {
+    tools: Array<CatalogSearchTool & {
+        connectorTitle?: string;
+        guide?: string;
+        guideSummary?: string;
+    }>;
+};
+export interface CatalogDescription {
+    address: string;
+    schemaFormat?: "json" | "text";
+    name?: string;
+    description?: string;
+    guide?: string;
+    guideSummary?: string;
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    signature?: string;
+    outputSchemaSource?: "observed";
+    inputSchemaTruncated?: true;
+    outputSchemaTruncated?: true;
+    annotations?: ToolDef["annotations"];
+    error?: string;
+    errorDetails?: CatalogDescriptionFailureDetail;
+}
+type CatalogSearchTool = {
+    name: string;
+    address: string;
+    description?: string;
+    inputSchema?: unknown;
+    outputSchema?: unknown;
+    signature?: string;
+    schemaFormat?: "json" | "text";
+    outputSchemaSource?: "observed";
+    inputSchemaTruncated?: true;
+    outputSchemaTruncated?: true;
+    inputKeys?: string[];
+    requiredInputKeys?: string[];
+    outputKeys?: string[];
+    annotations?: ToolDef["annotations"];
+    classification?: ToolDef["classification"];
+    guideRequired?: true;
+    guideRequiredReasons?: GuideRequiredReason[];
+};
+export {};

package/dist/guest-types.js

@@ -0,0 +1 @@
+export {};