stitchkit 0.54.0 → 0.56.0

package/dist/{index-7vb44hy8.js → index-escqg10p.js}

@@ -1,23 +1,36 @@
 import {
-  isWithinDir,
-  jsonSchemaFields,
-  toJsonSchema
-} from "./index-yxpe3phd.js";
+  isWithinDir
+} from "./index-sbdmyz75.js";
+import {
+  assertToolExtensionCompatible,
+  assertUniqueToolName,
+  buildToolPresentationSchema,
+  mergeSchemas,
+  objectShapeKeys,
+  projectRuntimeTool,
+  projectToolSurface,
+  rebuildObject
+} from "./index-6y759j86.js";
+import {
+  jsonSchemaFields
+} from "./index-cby4ar3v.js";
 import {
-  AppError,
-  STITCH_ERROR_STATUS,
   formatZodError,
   getRequestContext,
-  isStitchErrorCode,
-  isUnsafeKey,
   normalizeError,
   runWithRequestContext,
-  safeJsonParse,
   validateDeclaredOutput
-} from "./index-173tvqcp.js";
+} from "./index-j3dem06f.js";
+import {
+  AppError,
+  STITCH_ERROR_STATUS,
+  isStitchErrorCode,
+  isUnsafeKey,
+  safeJsonParse
+} from "./index-5r13htq1.js";
 import {
   isRecord
-} from "./index-bmnhqtya.js";
+} from "./index-7eq9va6e.js";
 
 // src/tools/coerce.ts
 import { z } from "zod";
@@ -100,454 +113,8 @@ function coerceJsonArgs(args, schema) {
   return isRecord(coerced) ? coerced : args;
 }
 
-// src/tools/flatten-join.ts
-var ANNOTATION_KEYS = new Set(["$schema", "default", "description", "examples", "title"]);
-var TYPE_KEYWORDS = {
-  array: [
-    "contains",
-    "items",
-    "maxContains",
-    "maxItems",
-    "minContains",
-    "minItems",
-    "prefixItems",
-    "uniqueItems"
-  ],
-  integer: ["exclusiveMaximum", "exclusiveMinimum", "maximum", "minimum", "multipleOf"],
-  number: ["exclusiveMaximum", "exclusiveMinimum", "maximum", "minimum", "multipleOf"],
-  object: [
-    "additionalProperties",
-    "dependentRequired",
-    "dependentSchemas",
-    "maxProperties",
-    "minProperties",
-    "patternProperties",
-    "properties",
-    "propertyNames",
-    "required"
-  ],
-  string: [
-    "contentEncoding",
-    "contentMediaType",
-    "format",
-    "maxLength",
-    "minLength",
-    "pattern"
-  ]
-};
-function nullableProjection(schema) {
-  if (!Array.isArray(schema.anyOf) || schema.anyOf.length !== 2)
-    return schema;
-  const branches = schema.anyOf.filter(isRecord);
-  if (branches.length !== 2)
-    return schema;
-  const nullBranch = branches.find((branch) => branch.type === "null");
-  const value = branches.find((branch) => typeof branch.type === "string" && branch.type !== "null");
-  if (!nullBranch || !value || Object.keys(nullBranch).some((key) => key !== "type")) {
-    return schema;
-  }
-  const type = value.type;
-  if (typeof type !== "string")
-    return schema;
-  const projected = { type: [type, "null"] };
-  for (const key of [...ANNOTATION_KEYS, ...TYPE_KEYWORDS[type] ?? []]) {
-    if (value[key] !== undefined)
-      projected[key] = value[key];
-    else if (schema[key] !== undefined)
-      projected[key] = schema[key];
-  }
-  if (value.const !== undefined)
-    projected.enum = [value.const, null];
-  else if (Array.isArray(value.enum))
-    projected.enum = [...value.enum, null];
-  return projected;
-}
-function withoutAnnotations(schema) {
-  const result = {};
-  for (const [key, value] of Object.entries(schema)) {
-    if (!ANNOTATION_KEYS.has(key))
-      result[key] = value;
-  }
-  return result;
-}
-function stableJson(value) {
-  if (Array.isArray(value))
-    return `[${value.map(stableJson).join(",")}]`;
-  if (!isRecord(value))
-    return JSON.stringify(value) ?? "undefined";
-  return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${stableJson(value[key])}`).join(",")}}`;
-}
-function stringValues(schema) {
-  if (typeof schema.const === "string")
-    return [schema.const];
-  if (!Array.isArray(schema.enum))
-    return null;
-  const values = schema.enum.filter((value) => typeof value === "string");
-  return values.length === schema.enum.length ? values : null;
-}
-var JSON_SCHEMA_TYPE_ORDER = [
-  "string",
-  "number",
-  "integer",
-  "boolean",
-  "object",
-  "array",
-  "null"
-];
-function jsonSchemaType(value) {
-  switch (value) {
-    case "array":
-    case "boolean":
-    case "integer":
-    case "null":
-    case "number":
-    case "object":
-    case "string":
-      return value;
-    default:
-      return null;
-  }
-}
-function valueType(value) {
-  if (value === null)
-    return "null";
-  if (Array.isArray(value))
-    return "array";
-  if (isRecord(value))
-    return "object";
-  if (typeof value === "string")
-    return "string";
-  if (typeof value === "number")
-    return "number";
-  if (typeof value === "boolean")
-    return "boolean";
-  return null;
-}
-function normalizeTypes(types) {
-  const normalized = new Set(types);
-  if (normalized.has("number"))
-    normalized.delete("integer");
-  return JSON_SCHEMA_TYPE_ORDER.filter((type) => normalized.has(type));
-}
-function combinedBranchTypes(schema) {
-  for (const keyword of ["oneOf", "anyOf"]) {
-    const value = schema[keyword];
-    if (!Array.isArray(value) || value.length === 0)
-      continue;
-    const collected = [];
-    for (const branch of value) {
-      if (!isRecord(branch))
-        return null;
-      const types = typeNames(branch);
-      if (!types)
-        return null;
-      collected.push(...types);
-    }
-    return normalizeTypes(collected);
-  }
-  return null;
-}
-function typeNames(schema) {
-  const direct = jsonSchemaType(schema.type);
-  if (direct)
-    return [direct];
-  if (Array.isArray(schema.type)) {
-    const values = [];
-    for (const value of schema.type) {
-      const type = jsonSchemaType(value);
-      if (!type)
-        return null;
-      values.push(type);
-    }
-    return values.length > 0 ? normalizeTypes(values) : null;
-  }
-  if (schema.const !== undefined) {
-    const type = valueType(schema.const);
-    return type ? [type] : null;
-  }
-  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
-    const values = [];
-    for (const value of schema.enum) {
-      const type = valueType(value);
-      if (!type)
-        return null;
-      values.push(type);
-    }
-    return normalizeTypes(values);
-  }
-  return combinedBranchTypes(schema);
-}
-function typeSchema(type, nullable) {
-  const schema = { type: nullable ? [type, "null"] : type };
-  if (type === "array")
-    schema.items = {};
-  if (type === "object")
-    schema.additionalProperties = {};
-  return schema;
-}
-function commonBaseType(schemas) {
-  const names = schemas.map(typeNames);
-  if (names.some((value) => value === null))
-    return {};
-  let nullable = false;
-  const bases = new Set;
-  for (const branch of names) {
-    if (!branch)
-      return {};
-    for (const name of branch) {
-      if (name === "null")
-        nullable = true;
-      else
-        bases.add(name);
-    }
-  }
-  if (bases.size === 0)
-    return nullable ? { type: "null" } : {};
-  if (bases.size === 1) {
-    const [only] = bases;
-    return only ? typeSchema(only, nullable) : {};
-  }
-  if ([...bases].every((name) => name === "integer" || name === "number")) {
-    return typeSchema("number", nullable);
-  }
-  const types = normalizeTypes(nullable ? [...bases, "null"] : bases);
-  return types.length > 0 ? { type: types } : {};
-}
-function mergePropertySchemas(properties) {
-  const schemas = properties.map((property) => nullableProjection(property.schema));
-  const structural = schemas.map(withoutAnnotations);
-  const [first] = structural;
-  let merged;
-  if (first && structural.every((schema) => stableJson(schema) === stableJson(first))) {
-    merged = structuredClone(first);
-  } else {
-    const values = schemas.map(stringValues);
-    const allStrings = values.every((value) => value !== null);
-    merged = allStrings ? { type: "string", enum: [...new Set(values.flatMap((value) => value ?? []))] } : commonBaseType(schemas);
-  }
-  const descriptions = [
-    ...new Set(schemas.map((schema) => schema.description).filter((value) => typeof value === "string"))
-  ];
-  if (descriptions.length === 1)
-    merged.description = descriptions[0];
-  return merged;
-}
-
-// src/tools/flatten.ts
-function rebuild(value) {
-  if (Array.isArray(value))
-    return value.map(rebuild);
-  if (!isRecord(value))
-    return value;
-  const node = {};
-  for (const [key, child] of Object.entries(value))
-    node[key] = rebuild(child);
-  return flattenNode(node);
-}
-function stringValues2(schema) {
-  if (typeof schema.const === "string")
-    return [schema.const];
-  if (!Array.isArray(schema.enum))
-    return null;
-  const values = schema.enum.filter((value) => typeof value === "string");
-  return values.length === schema.enum.length ? values : null;
-}
-function objectVariants(node) {
-  if (!Array.isArray(node.oneOf) || node.oneOf.length < 2)
-    return null;
-  const variants = node.oneOf.filter(isRecord);
-  if (variants.length !== node.oneOf.length)
-    return null;
-  if (variants.some((variant) => variant.type !== "object" || !isRecord(variant.properties))) {
-    return null;
-  }
-  return variants;
-}
-function findDiscriminator(variants) {
-  const [first] = variants;
-  if (!first || !isRecord(first.properties))
-    return null;
-  for (const key of Object.keys(first.properties).sort()) {
-    const values = [];
-    const seen = new Set;
-    let valid = true;
-    for (const variant of variants) {
-      if (!requiredKeys(variant).has(key)) {
-        valid = false;
-        break;
-      }
-      const properties = variant.properties;
-      const field = isRecord(properties) ? properties[key] : undefined;
-      const branchValues = isRecord(field) ? stringValues2(field) : null;
-      if (!branchValues || branchValues.length === 0) {
-        valid = false;
-        break;
-      }
-      for (const value of branchValues) {
-        if (seen.has(value)) {
-          valid = false;
-          break;
-        }
-        seen.add(value);
-      }
-      if (!valid)
-        break;
-      values.push(branchValues);
-    }
-    if (valid)
-      return { key, values };
-  }
-  return null;
-}
-function requiredKeys(variant) {
-  if (!Array.isArray(variant.required))
-    return new Set;
-  return new Set(variant.required.filter((key) => typeof key === "string"));
-}
-function appendHint(schema, hint) {
-  const description = typeof schema.description === "string" ? schema.description : undefined;
-  return { ...schema, description: description ? `${description} ${hint}` : hint };
-}
-function flattenNode(node) {
-  const variants = objectVariants(node);
-  if (!variants)
-    return node;
-  const discriminator = findDiscriminator(variants);
-  if (!discriminator)
-    return node;
-  const perKey = new Map;
-  for (let index = 0;index < variants.length; index++) {
-    const variant = variants[index];
-    if (!variant)
-      continue;
-    const labels = discriminator.values[index] ?? [];
-    const required2 = requiredKeys(variant);
-    if (!isRecord(variant.properties))
-      continue;
-    for (const [key, rawSchema] of Object.entries(variant.properties)) {
-      if (key === discriminator.key || !isRecord(rawSchema))
-        continue;
-      const entries = perKey.get(key) ?? [];
-      entries.push({ schema: rawSchema, labels, required: required2.has(key) });
-      perKey.set(key, entries);
-    }
-  }
-  const discriminatorProperties = [];
-  for (let index = 0;index < variants.length; index++) {
-    const variant = variants[index];
-    if (!variant || !isRecord(variant.properties))
-      continue;
-    const schema = variant.properties[discriminator.key];
-    if (!isRecord(schema))
-      continue;
-    discriminatorProperties.push({
-      schema,
-      labels: discriminator.values[index] ?? [],
-      required: true
-    });
-  }
-  const properties = {
-    [discriminator.key]: mergePropertySchemas(discriminatorProperties)
-  };
-  const required = [discriminator.key];
-  for (const [key, entries] of perKey) {
-    let merged = mergePropertySchemas(entries);
-    const requiredEverywhere = entries.length === variants.length && entries.every((entry) => entry.required);
-    if (requiredEverywhere) {
-      required.push(key);
-    } else {
-      const requiredLabels = entries.filter((entry) => entry.required).flatMap((entry) => entry.labels);
-      const presentLabels = entries.flatMap((entry) => entry.labels);
-      const labels = requiredLabels.length > 0 ? requiredLabels : presentLabels;
-      const verb = requiredLabels.length > 0 ? "Required" : "Available";
-      merged = appendHint(merged, `${verb} if ${discriminator.key} = ${[...new Set(labels)].join(" | ")}`);
-    }
-    properties[key] = merged;
-  }
-  const result = {};
-  for (const [key, value] of Object.entries(node)) {
-    if (key !== "oneOf" && key !== "anyOf" && key !== "properties" && key !== "required") {
-      result[key] = value;
-    }
-  }
-  result.type = "object";
-  result.properties = properties;
-  result.required = required;
-  result.additionalProperties = variants.every((variant) => variant.additionalProperties === false) ? false : {};
-  return result;
-}
-function flattenToolJsonSchema(schema) {
-  const result = rebuild(schema);
-  return isRecord(result) ? result : {};
-}
-function freezeToolJsonSchema(schema) {
-  for (const value of Object.values(schema))
-    freezeJsonValue(value);
-  return Object.freeze(schema);
-}
-function freezeJsonValue(value) {
-  if (Array.isArray(value)) {
-    for (const item of value)
-      freezeJsonValue(item);
-    Object.freeze(value);
-  } else if (isRecord(value)) {
-    freezeToolJsonSchema(value);
-  }
-}
-
 // src/tools/mount.ts
-import { z as z4 } from "zod";
-
-// src/tools/schema.ts
 import { z as z2 } from "zod";
-function objectShapeKeys(schema) {
-  return schema instanceof z2.ZodObject ? Object.keys(schema.shape) : [];
-}
-function keyPolicyOf(schema) {
-  return schema.def.catchall;
-}
-function rebuildObject(source, shape) {
-  return withKeyPolicy(z2.object(shape), keyPolicyOf(source));
-}
-function withKeyPolicy(object, policy) {
-  if (policy === undefined)
-    return object;
-  return object.catchall(representable(policy));
-}
-function representable(policy) {
-  if (policy instanceof z2.ZodNever || policy instanceof z2.ZodUnknown)
-    return policy;
-  if (!(policy instanceof z2.ZodType))
-    return z2.unknown();
-  try {
-    toJsonSchema(policy, "input");
-    return policy;
-  } catch {
-    return z2.unknown();
-  }
-}
-function mergeSchemas(paramsSchema, inputSchema) {
-  if (paramsSchema && !(paramsSchema instanceof z2.ZodObject)) {
-    throw new Error("Tool params schema must be a z.object()");
-  }
-  const paramsObject = paramsSchema instanceof z2.ZodObject ? paramsSchema : undefined;
-  if (!inputSchema) {
-    return paramsObject ?? z2.object({});
-  }
-  if (inputSchema instanceof z2.ZodObject) {
-    if (paramsObject) {
-      const conflicts = Object.keys(paramsObject.shape).filter((key) => (key in inputSchema.shape));
-      if (conflicts.length > 0) {
-        throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
-      }
-    }
-    return rebuildObject(inputSchema, {
-      ...paramsObject?.shape ?? {},
-      ...inputSchema.shape
-    });
-  }
-  return paramsObject ? z2.intersection(paramsObject, inputSchema) : inputSchema;
-}
 
 // src/tools/execute.ts
 var normalizedToolErrors = new WeakMap;
@@ -769,239 +336,44 @@ async function runToolMethod(method, toolName, rawArgs, context, hooks, lifecycl
   }
 }
 
-// src/tools/names.ts
-var SINGULAR_EXCEPTIONS = new Set([
-  "analytics",
-  "status",
-  "stats",
-  "settings",
-  "media",
-  "progress",
-  "news"
-]);
-var TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;
-function normalizeService(value) {
-  return value.replace(/[^a-zA-Z0-9_]/g, "_");
-}
-function normalizeMethod(value) {
-  return value.replace(/[^a-zA-Z0-9_-]/g, "_");
-}
-function singularize(name) {
-  if (SINGULAR_EXCEPTIONS.has(name))
-    return name;
-  if (name.endsWith("ies"))
-    return `${name.slice(0, -3)}y`;
-  if (name.endsWith("s") && !name.endsWith("ss"))
-    return name.slice(0, -1);
-  return name;
-}
-function singularizeTail(name) {
-  const cut = name.lastIndexOf("_");
-  if (cut === -1)
-    return singularize(name);
-  return `${name.slice(0, cut + 1)}${singularize(name.slice(cut + 1))}`;
-}
-function hasUsableChars(value) {
-  return /[a-zA-Z0-9]/.test(value);
-}
-function assertToolName(name, serviceName, key) {
-  const where = `service "${serviceName}", method "${key}"`;
-  if (!TOOL_NAME_RE.test(name)) {
-    const why = name.length > 64 ? `is ${name.length} characters (max 64) — set an explicit \`toolName\`` : "must match [a-zA-Z0-9_-]";
-    throw new Error(`Tool name "${name}" (${where}) ${why}`);
-  }
-}
-function toToolName(serviceName, methodName) {
-  const normalized = normalizeService(serviceName);
-  const singular = singularizeTail(normalized);
-  const method = normalizeMethod(methodName);
-  if (method === "list")
-    return `list_${normalized}`;
-  if (method === "get")
-    return `get_${singular}`;
-  if (method === "create")
-    return `create_${singular}`;
-  if (method === "update")
-    return `update_${singular}`;
-  if (method === "delete")
-    return `delete_${singular}`;
-  const snake = method.replace(/([A-Z])/g, "_$1").toLowerCase();
-  return `${snake}_${singular}`.replace(/^_/, "");
-}
-function assertUniqueToolName(name, taken, surface) {
-  if (taken) {
-    throw new Error(`Duplicate ${surface} "${name}" across mounted operations`);
-  }
-}
-
-// src/tools/presentation.ts
-import { z as z3 } from "zod";
-function withoutDialect(schema) {
-  const result = {};
-  for (const [key, value] of Object.entries(schema)) {
-    if (key !== "$schema")
-      result[key] = value;
-  }
-  return result;
-}
-function hasLocalReference(value) {
-  if (Array.isArray(value))
-    return value.some(hasLocalReference);
-  if (!isRecord(value))
-    return false;
-  if (typeof value.$ref === "string" && value.$ref.startsWith("#"))
-    return true;
-  return Object.values(value).some(hasLocalReference);
-}
-function rewriteLocalReferences(value, namespace) {
-  if (Array.isArray(value)) {
-    return value.map((child) => rewriteLocalReferences(child, namespace));
-  }
-  if (!isRecord(value))
-    return value;
-  const rewritten = {};
-  for (const [key, child] of Object.entries(value)) {
-    rewritten[key] = key === "$ref" && typeof child === "string" && child.startsWith("#") ? `#/definitions/${namespace}${child.slice(1)}` : rewriteLocalReferences(child, namespace);
-  }
-  return rewritten;
-}
-function namespaceLocalReferences(schema, namespace) {
-  if (!schema || !hasLocalReference(schema))
-    return schema;
-  const rewritten = rewriteLocalReferences(schema, namespace);
-  if (!isRecord(rewritten))
-    return schema;
-  return { ...rewritten, definitions: { [namespace]: rewritten } };
-}
-function objectProperties(schema) {
-  return schema.type === "object" && isRecord(schema.properties) ? schema.properties : null;
-}
-function requiredKeys2(schema) {
-  return Array.isArray(schema.required) ? schema.required.filter((key) => typeof key === "string") : [];
-}
-function mergeObjectSchemas(left, right, rightOwnsUnknownKeys) {
-  const leftProperties = objectProperties(left);
-  const rightProperties = objectProperties(right);
-  if (!leftProperties || !rightProperties)
-    return { allOf: [left, right] };
-  const conflicts = Object.keys(leftProperties).filter((key) => (key in rightProperties));
-  if (conflicts.length > 0) {
-    throw new Error(`Schema merge conflict: ${conflicts.join(", ")} appear in both params and input`);
-  }
-  const merged = {
-    type: "object",
-    properties: { ...leftProperties, ...rightProperties },
-    required: [...new Set([...requiredKeys2(left), ...requiredKeys2(right)])]
-  };
-  const leftDefinitions = isRecord(left.definitions) ? left.definitions : {};
-  const rightDefinitions = isRecord(right.definitions) ? right.definitions : {};
-  const definitions = { ...leftDefinitions, ...rightDefinitions };
-  if (Object.keys(definitions).length > 0)
-    merged.definitions = definitions;
-  const unknownKeys = rightOwnsUnknownKeys ? right.additionalProperties : left.additionalProperties;
-  if (unknownKeys !== undefined)
-    merged.additionalProperties = unknownKeys;
-  return merged;
-}
-function schemaFromZod(schema, unrepresentable, flatten) {
-  if (!schema)
-    return;
-  const json = toJsonSchema(schema, "input", unrepresentable, "draft-07");
-  return flatten ? flattenToolJsonSchema(json) : json;
-}
-function buildToolPresentationSchema(config) {
-  const unrepresentable = config.unrepresentable ?? "any";
-  const flatten = config.flattenUnionInput ?? false;
-  const params = namespaceLocalReferences(schemaFromZod(config.paramsSchema, unrepresentable, flatten), "params");
-  const input = namespaceLocalReferences(schemaFromZod(config.inputSchema, unrepresentable, flatten), "input");
-  let presentation;
-  if (params && input) {
-    presentation = mergeObjectSchemas(withoutDialect(params), withoutDialect(input), true);
-  } else if (input) {
-    presentation = input;
-  } else if (params) {
-    presentation = params;
-  } else {
-    presentation = {
-      $schema: "http://json-schema.org/draft-07/schema#",
-      type: "object",
-      properties: {}
-    };
-  }
-  if (config.extendSchema) {
-    const extra = namespaceLocalReferences(schemaFromZod(z3.object(config.extendSchema), unrepresentable, flatten), "extend");
-    if (extra) {
-      presentation = mergeObjectSchemas(withoutDialect(extra), withoutDialect(presentation), true);
-    }
-  }
-  if (presentation.$schema === undefined) {
-    presentation = {
-      $schema: "http://json-schema.org/draft-07/schema#",
-      ...presentation
-    };
-  }
-  return freezeToolJsonSchema(presentation);
-}
-function isObjectPresentationSchema(schema) {
-  return schema.type === "object" && isRecord(schema.properties);
-}
-function presentationMetadata(schema) {
-  return withoutDialect(schema);
-}
-
 // src/tools/mount.ts
 function applyExtend(base, extra) {
-  if (base instanceof z4.ZodObject) {
-    const conflicts = Object.keys(extra).filter((key) => (key in base.shape));
-    if (conflicts.length > 0) {
-      throw new Error(`Tool extend conflict: ${conflicts.join(", ")} already declared by the contract`);
-    }
+  if (base instanceof z2.ZodObject) {
+    assertToolExtensionCompatible(base, extra);
     return rebuildObject(base, { ...extra, ...base.shape });
   }
-  return z4.intersection(z4.object(extra), base);
+  return z2.intersection(z2.object(extra), base);
+}
+function contractToolMountable(projected, extend) {
+  const method = projected.source;
+  const baseArgumentSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
+  const argumentSchema = projected.shouldExtend && extend ? applyExtend(baseArgumentSchema, extend.schema) : baseArgumentSchema;
+  return {
+    method,
+    name: projected.name,
+    argumentSchema,
+    presentationSchema: projected.presentationSchema,
+    shouldExtend: projected.shouldExtend
+  };
 }
 function collectTools(service, transport, config = {}) {
   const { extend, flattenUnionInput = false, assertNames = true } = config;
   const tools = [];
-  for (const [methodName, method] of Object.entries(service.methods)) {
-    if (transport === "CLI") {
-      if (!method.expose?.includes("CLI"))
-        continue;
-    } else if (method.expose && !method.expose.includes(transport)) {
-      continue;
-    }
-    if (method.multipart)
-      continue;
-    if (method.rawBody)
-      continue;
-    if (method.responseMeta)
-      continue;
-    if (method.rawResponse)
+  for (const projected of projectToolSurface({ services: [service] }, transport === "HTTP" ? "AGENT" : transport, {
+    extend,
+    flattenUnionInput,
+    assertNames,
+    assertUniqueNames: false
+  })) {
+    if (projected.kind !== "contract")
       continue;
-    const name = method.toolName ?? toToolName(service.name, methodName);
-    if (assertNames && transport !== "CLI") {
-      if (!method.toolName && !hasUsableChars(service.name)) {
-        throw new Error(`Service prefix "${service.name}" (method "${methodName}") has no characters usable in a tool name — set an explicit \`toolName\` or rename the prefix`);
-      }
-      assertToolName(name, service.name, methodName);
-    }
-    const shouldExtend = !!extend && (!extend.filter || extend.filter(service, method));
-    const baseArgumentSchema = mergeSchemas(method.paramsSchema, method.inputSchema);
-    const argumentSchema = shouldExtend && extend ? applyExtend(baseArgumentSchema, extend.schema) : baseArgumentSchema;
-    const presentationSchema = buildToolPresentationSchema({
-      paramsSchema: method.paramsSchema,
-      inputSchema: method.inputSchema,
-      extendSchema: shouldExtend ? extend?.schema : undefined,
-      flattenUnionInput,
-      unrepresentable: "any"
-    });
-    tools.push({ method, name, argumentSchema, presentationSchema, shouldExtend });
+    tools.push(contractToolMountable(projected, extend));
   }
   return tools;
 }
 function createToolRunner(config) {
   const extension = config.extend ? {
-    schema: z4.object(config.extend.schema),
+    schema: z2.object(config.extend.schema),
     resolve: config.extend.resolve
   } : undefined;
   return async function runOneToolCall(tool, rawArgs, context) {
@@ -1075,14 +447,6 @@ function createRuntimeToolFactory(config) {
   }
   return { define };
 }
-function runtimeToolSupports(definition, transport) {
-  if (definition.transports?.length === 0) {
-    throw new Error(`Runtime tool "${definition.name}" must expose at least one transport`);
-  }
-  if (!definition.transports)
-    return transport !== "CLI";
-  return definition.transports.includes(transport);
-}
 function runtimeToolIdentity(definition) {
   return {
     method: definition.identity.method,
@@ -1098,9 +462,7 @@ function runtimeToolIdentity(definition) {
   };
 }
 function runtimeToolMountable(definition, assertName = true) {
-  if (assertName) {
-    assertToolName(definition.name, definition.identity.serviceName, definition.identity.action);
-  }
+  const projected = projectRuntimeTool(definition, assertName);
   const method = {
     ...runtimeToolIdentity(definition),
     inputSchema: definition.input,
@@ -1109,18 +471,15 @@ function runtimeToolMountable(definition, assertName = true) {
   };
   return {
     method,
-    name: definition.name,
+    name: projected.name,
     argumentSchema: definition.input,
-    presentationSchema: buildToolPresentationSchema({
-      inputSchema: definition.input,
-      unrepresentable: "any"
-    }),
+    presentationSchema: projected.presentationSchema,
     shouldExtend: false
   };
 }
 
 // src/tools/cli-args.ts
-import { z as z5 } from "zod";
+import { z as z3 } from "zod";
 var NUMERIC_VALUE = /^-(\d+\.?\d*|\.\d+)$/;
 var BOOL_OPTIONS = new Set(["json", "wait", "quiet", "dry-run", "help"]);
 var VALUE_OPTIONS = new Set(["wait-timeout", "output-dir"]);
@@ -1130,27 +489,27 @@ class CliArgumentError extends Error {
   name = "CliArgumentError";
 }
 function unwrap(field) {
-  if (field instanceof z5.ZodOptional || field instanceof z5.ZodNullable || field instanceof z5.ZodDefault) {
+  if (field instanceof z3.ZodOptional || field instanceof z3.ZodNullable || field instanceof z3.ZodDefault) {
     return unwrap(field.unwrap());
   }
   return field;
 }
 function classify(field) {
-  if (field instanceof z5.ZodBoolean)
+  if (field instanceof z3.ZodBoolean)
     return "boolean";
-  if (field instanceof z5.ZodNumber)
+  if (field instanceof z3.ZodNumber)
     return "number";
-  if (field instanceof z5.ZodBigInt)
+  if (field instanceof z3.ZodBigInt)
     return "bigint";
-  if (field instanceof z5.ZodDate)
+  if (field instanceof z3.ZodDate)
     return "date";
-  if (field instanceof z5.ZodEnum)
+  if (field instanceof z3.ZodEnum)
     return "enum";
-  if (field instanceof z5.ZodArray)
+  if (field instanceof z3.ZodArray)
     return "array";
-  if (field instanceof z5.ZodObject)
+  if (field instanceof z3.ZodObject)
     return "object";
-  if (field instanceof z5.ZodString || field instanceof z5.ZodLiteral)
+  if (field instanceof z3.ZodString || field instanceof z3.ZodLiteral)
     return "string";
   return "other";
 }
@@ -1170,11 +529,11 @@ function mergeField(fields, name, info) {
 }
 function collectSchemaFields(schema, fields) {
   const base = unwrap(schema);
-  if (base instanceof z5.ZodObject) {
+  if (base instanceof z3.ZodObject) {
     for (const [name, raw] of Object.entries(base.shape)) {
       const fieldBase = unwrap(raw);
       const kind = classify(fieldBase);
-      if (kind === "array" && fieldBase instanceof z5.ZodArray) {
+      if (kind === "array" && fieldBase instanceof z3.ZodArray) {
         mergeField(fields, name, { kind, elementKind: classify(unwrap(fieldBase.element)) });
       } else {
         mergeField(fields, name, { kind });
@@ -1182,12 +541,12 @@ function collectSchemaFields(schema, fields) {
     }
     return;
   }
-  if (base instanceof z5.ZodUnion) {
+  if (base instanceof z3.ZodUnion) {
     for (const option of base.def.options)
       collectSchemaFields(option, fields);
     return;
   }
-  if (base instanceof z5.ZodIntersection) {
+  if (base instanceof z3.ZodIntersection) {
     collectSchemaFields(base.def.left, fields);
     collectSchemaFields(base.def.right, fields);
     return;
@@ -1494,19 +853,21 @@ var DEFAULT_EXIT_CODES = {
   CONFLICT: 5,
   RATE_LIMITED: 6,
   TIMEOUT: 7,
+  WAIT_FAILED: 1,
   INTERNAL_SERVER_ERROR: 1
 };
 function emitResult(result, writers, opts) {
   if (result.ok) {
     if (result.data === undefined)
       return 0;
-    const text = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
-    writers.stdout(`${text}
+    const text2 = opts.json ? JSON.stringify(result.data) : JSON.stringify(result.data, null, 2);
+    writers.stdout(`${text2}
 `);
     return 0;
   }
   const error = formatToolError(result, opts.toolName, opts.errorHint);
-  writers.stderr(`${JSON.stringify(error, null, 2)}
+  const text = opts.json ? JSON.stringify(error) : JSON.stringify(error, null, 2);
+  writers.stderr(`${text}
 `);
   const codes = opts.exitCodes ?? DEFAULT_EXIT_CODES;
   return codes[result.code] ?? 1;
@@ -1515,6 +876,13 @@ function emitResult(result, writers, opts) {
 // src/tools/wait-core.ts
 var DEFAULT_BACKOFF = [2, 3, 5, 5, 8, 10];
 var DEFAULT_TIMEOUT = 600;
+
+class WaitTimeoutError extends Error {
+  constructor() {
+    super("wait deadline elapsed before the first snapshot");
+    this.name = "WaitTimeoutError";
+  }
+}
 var defaultSleep = (ms, signal) => {
   signal?.throwIfAborted();
   return new Promise((resolve, reject) => {
@@ -1544,52 +912,104 @@ async function pollUntil(params) {
   const lastBackoff = backoff[backoff.length - 1] ?? 5;
   const timeoutSec = params.timeoutSec ?? DEFAULT_TIMEOUT;
   const sleep = params.sleepFn ?? defaultSleep;
-  const startedAt = Date.now();
+  const now = params.nowFn ?? (() => performance.now());
+  const startedAt = now();
+  const deadline = startedAt + timeoutSec * 1000;
+  let last;
   for (let attempt = 0;; attempt++) {
     params.signal?.throwIfAborted();
-    const state = await params.poll();
+    const remainingBeforePoll = Math.max(0, deadline - now());
+    if (remainingBeforePoll === 0 && last) {
+      return { state: last.state, timedOut: true };
+    }
+    const deadlineController = new AbortController;
+    const onCallerAbort = () => deadlineController.abort(params.signal?.reason);
+    params.signal?.addEventListener("abort", onCallerAbort, { once: true });
+    const deadlineTimer = setTimeout(() => deadlineController.abort(new WaitTimeoutError), remainingBeforePoll);
+    deadlineTimer.unref?.();
+    let state;
+    try {
+      state = await params.poll(deadlineController.signal);
+    } catch (error) {
+      if (params.signal?.aborted)
+        throw params.signal.reason ?? error;
+      if (deadlineController.signal.aborted && now() >= deadline) {
+        if (last)
+          return { state: last.state, timedOut: true };
+        throw new WaitTimeoutError;
+      }
+      throw error;
+    } finally {
+      clearTimeout(deadlineTimer);
+      params.signal?.removeEventListener("abort", onCallerAbort);
+    }
     params.signal?.throwIfAborted();
+    last = { state };
     if (params.done(state))
       return { state, timedOut: false };
-    const elapsedSec = (Date.now() - startedAt) / 1000;
+    const elapsedMs = now() - startedAt;
+    const elapsedSec = elapsedMs / 1000;
     params.onTick?.(attempt + 1, elapsedSec);
     if (elapsedSec >= timeoutSec)
       return { state, timedOut: true };
     const waitSec = backoff[Math.min(attempt, backoff.length - 1)] ?? lastBackoff;
-    await sleep(waitSec * 1000, params.signal);
+    await sleep(Math.min(waitSec * 1000, Math.max(0, deadline - now())), params.signal);
   }
 }
 function runWaitOperation(params) {
   return pollUntil({
-    poll: () => params.poll(params.input, params.signal),
+    poll: (signal) => params.poll(params.input, signal),
     done: params.done,
     backoff: params.backoff,
     timeoutSec: params.timeoutSec,
     sleepFn: params.sleepFn,
     onTick: params.onTick,
-    signal: params.signal
+    signal: params.signal,
+    nowFn: params.nowFn
   });
 }
 
 // src/tools/cli-wait.ts
 var DEFAULT_TIMEOUT2 = 600;
+function waitFailure(tool, result) {
+  return {
+    ok: false,
+    code: "WAIT_FAILED",
+    details: {
+      message: `"${tool}" reached a terminal failed state`,
+      result
+    }
+  };
+}
 async function pollUntilDone(params) {
   const { initial, wait, call } = params;
   if (!initial.ok)
     return initial;
+  if (wait.failed?.(initial.data))
+    return waitFailure(wait.tool, initial.data);
   if (wait.done(initial.data))
     return initial;
   const pollArgs = wait.poll(initial.data);
   if (!pollArgs)
     return initial;
   const timeoutSec = params.timeoutSec ?? wait.timeout ?? DEFAULT_TIMEOUT2;
+  let failedState;
   const { state, timedOut } = await pollUntil({
     poll: () => call(wait.tool, pollArgs),
-    done: (result) => !result.ok || wait.done(result.data),
+    done: (result) => {
+      if (!result.ok)
+        return true;
+      if (wait.failed?.(result.data)) {
+        failedState = result;
+        return true;
+      }
+      return wait.done(result.data);
+    },
     backoff: wait.backoff,
     timeoutSec,
     sleepFn: params.sleepFn,
-    onTick: params.onTick
+    onTick: params.onTick,
+    signal: params.signal
   });
   if (timedOut) {
     return {
@@ -1598,6 +1018,8 @@ async function pollUntilDone(params) {
       details: { message: `Timed out after ${timeoutSec}s waiting for "${wait.tool}"` }
     };
   }
+  if (state === failedState && state.ok)
+    return waitFailure(wait.tool, state.data);
   return state;
 }
 
@@ -1913,13 +1335,6 @@ async function writeDownload(root, target, data) {
 }
 
 // src/tools/surface.ts
-function duplicateLabel(transport) {
-  if (transport === "MCP")
-    return "MCP tool name";
-  if (transport === "AGENT")
-    return "agent tool name";
-  return "CLI command";
-}
 function collectToolSurface({
   surface,
   transport,
@@ -1927,41 +1342,41 @@ function collectToolSurface({
   ...collectConfig
 }) {
   const entries = [];
-  const names = new Set;
   const append = (entry) => {
-    if (assertUniqueNames) {
-      assertUniqueToolName(entry.mountable.name, names.has(entry.mountable.name), duplicateLabel(transport));
-    }
-    names.add(entry.mountable.name);
     entries.push(entry);
   };
-  for (const service of surface.services ?? []) {
-    for (const mountable of collectTools(service, transport, collectConfig)) {
+  for (const projected of projectToolSurface(surface, transport, {
+    extend: collectConfig.extend,
+    flattenUnionInput: collectConfig.flattenUnionInput,
+    assertNames: collectConfig.assertNames,
+    assertUniqueNames
+  })) {
+    if (projected.kind === "contract") {
+      const mountable = contractToolMountable(projected, collectConfig.extend);
       append({
         kind: "contract",
-        service: service.name,
+        service: projected.serviceName,
         action: mountable.method.key,
-        mountable
+        mountable,
+        projection: projected
+      });
+    } else {
+      append({
+        kind: "runtime",
+        service: projected.serviceName,
+        action: projected.action,
+        mountable: runtimeToolMountable(projected.source, false),
+        definition: projected.source,
+        projection: projected
       });
     }
   }
-  for (const definition of surface.runtimeTools ?? []) {
-    if (!runtimeToolSupports(definition, transport))
-      continue;
-    append({
-      kind: "runtime",
-      service: definition.identity.serviceName,
-      action: definition.identity.action,
-      mountable: runtimeToolMountable(definition, collectConfig.assertNames),
-      definition
-    });
-  }
   return entries;
 }
 
 // src/tools/cli.ts
 var GLOBAL_OPTIONS = [
-  ["--json", "Emit raw JSON on stdout (for piping / scripts)"],
+  ["--json", "Emit compact success/error JSON records (for scripts)"],
   ["--wait", "Block-poll an async result to a terminal state"],
   ["--wait-timeout <s>", "Override the --wait timeout in seconds"],
   ["--output-dir <dir>", "Download result media into a directory"],
@@ -2058,15 +1473,41 @@ function renderTopHelp(name, version, commands) {
 `;
 }
 function renderCommandHelp(name, command, descriptor) {
-  const lines = [descriptor.description, "", `Usage: ${name} ${command} [args] [--flags]`, ""];
   const fields = jsonSchemaFields(descriptor.presentationSchema);
+  const fieldsByName = new Map(fields.map((field) => [field.name, field]));
+  const positionals = [];
+  for (const [fieldName, info] of describeSchemaFields(descriptor.argumentSchema)) {
+    if (info.kind === "boolean")
+      continue;
+    const field = fieldsByName.get(fieldName);
+    if (field)
+      positionals.push(field);
+  }
+  const positionalSyntax = new Map(positionals.map((field) => [
+    field.name,
+    field.required ? `<${field.name}>` : `[${field.name}]`
+  ]));
+  const usage = [
+    `Usage: ${name} ${command}`,
+    ...positionals.map((field) => positionalSyntax.get(field.name) ?? field.name),
+    "[--flags]"
+  ].join(" ");
+  const lines = [descriptor.description, "", usage, ""];
   if (fields.length > 0) {
     lines.push("Arguments:");
-    const width = Math.max(...fields.map((f) => f.name.length));
+    const labels = new Map(fields.map((field) => {
+      const positional = positionalSyntax.get(field.name);
+      return [
+        field.name,
+        positional ? `${positional} | --${field.name}` : `--${field.name}`
+      ];
+    }));
+    const width = Math.max(...fields.map((field) => labels.get(field.name)?.length ?? 0));
     for (const f of fields) {
       const req = f.required ? " (required)" : "";
       const desc = f.description ? ` — ${f.description}` : "";
-      lines.push(`  --${padRight(f.name, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
+      const label = labels.get(f.name) ?? `--${f.name}`;
+      lines.push(`  ${padRight(label, width)}  <${typeLabel(f.schema)}>${req}${desc}`);
     }
     lines.push("");
   }
@@ -2302,7 +1743,7 @@ async function createCli(config) {
   }
   const runTool = createToolRunner({
     source: "cli",
-    context: config.context?.(managed.auth),
+    context: { ...config.context?.(managed.auth), signal: config.signal },
     hooks: config.hooks,
     lifecycle: config.lifecycle,
     errorHint: config.errorHint,
@@ -2332,7 +1773,8 @@ async function createCli(config) {
       },
       timeoutSec: options.waitTimeout,
       onTick: options.quiet ? undefined : (attempt) => stderr(`waiting… (poll ${attempt})
-`)
+`),
+      signal: config.signal
     });
   }
   let downloadsOk = true;
@@ -2348,4 +1790,4 @@ async function createCli(config) {
   return exit(downloadsOk ? exitCode : 1);
 }
 
-export { coerceJsonArgs, toolResultFromError, toolErrorFromResult, executeToolMethod, assertToolName, assertUniqueToolName, flattenToolJsonSchema, buildToolPresentationSchema, isObjectPresentationSchema, presentationMetadata, collectTools, createToolRunner, formatToolError, defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, fetchGuarded, fetchPinnedDocument, readCapped, writeDownload, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, runWaitOperation, pollUntilDone, createCli };
+export { coerceJsonArgs, toolResultFromError, toolErrorFromResult, executeToolMethod, collectTools, createToolRunner, formatToolError, defineRuntimeTool, createRuntimeToolFactory, collectToolSurface, WaitTimeoutError, runWaitOperation, fetchGuarded, fetchPinnedDocument, readCapped, parseCliArgs, defineCliCommand, DEFAULT_EXIT_CODES, emitResult, pollUntilDone, createCli };