@blotout/qinto-cli 0.1.8 → 0.1.10

package/dist/worker-artifact/app-runtime/index.js

@@ -7,6 +7,10 @@ var __export = (target, all) => {
 // ../../../libs/app-manifest/src/cron.ts
 var MAX_CRON_LENGTH = 128;
 
+// ../../../libs/app-manifest/src/tool-names.ts
+var MAX_APP_TOOL_NAME_LENGTH = 32;
+var APP_TOOL_NAME_PATTERN = /^[a-zA-Z][a-zA-Z0-9_]*$/;
+
 // ../../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/v4/classic/external.js
 var external_exports = {};
 __export(external_exports, {
@@ -2348,13 +2352,13 @@ var $ZodType = /* @__PURE__ */ $constructor("$ZodType", (inst, def) => {
         canary.aborted = true;
         return canary;
       }
-      const checkResult = runChecks(payload, checks, ctx);
-      if (checkResult instanceof Promise) {
+      const checkResult2 = runChecks(payload, checks, ctx);
+      if (checkResult2 instanceof Promise) {
         if (ctx.async === false)
           throw new $ZodAsyncError();
-        return checkResult.then((checkResult2) => inst._zod.parse(checkResult2, ctx));
+        return checkResult2.then((checkResult3) => inst._zod.parse(checkResult3, ctx));
       }
-      return inst._zod.parse(checkResult, ctx);
+      return inst._zod.parse(checkResult2, ctx);
     };
     inst._zod.run = (payload, ctx) => {
       if (ctx.skipChecks) {
@@ -3036,10 +3040,10 @@ var $ZodObject = /* @__PURE__ */ $constructor("$ZodObject", (inst, def) => {
     const shape = def.shape;
     const propValues = {};
     for (const key in shape) {
-      const field = shape[key]._zod;
-      if (field.values) {
+      const field2 = shape[key]._zod;
+      if (field2.values) {
         propValues[key] ?? (propValues[key] = /* @__PURE__ */ new Set());
-        for (const v of field.values)
+        for (const v of field2.values)
           propValues[key].add(v);
       }
     }
@@ -14628,6 +14632,11 @@ var envelopeResponseSchema = external_exports.object({
 var CONTROL_ENVELOPE_VERSION = 1;
 var MAX_CONTROL_BYTES = 256 * 1024;
 var MAX_MIGRATION_CHECKPOINT_BYTES = 16 * 1024;
+var MAX_TOOL_ARGUMENTS_BYTES = 32 * 1024;
+var MAX_TOOL_RESULT_BYTES = 64 * 1024;
+var MAX_TOOL_DATA_DEPTH = 8;
+var MAX_TOOL_DATA_NODES = 5e3;
+var MAX_TOOL_ERROR_MESSAGE_LENGTH = 512;
 var installSchema2 = external_exports.object({
   id: external_exports.string().min(1).max(64),
   ord: external_exports.number().int().min(1),
@@ -14701,15 +14710,32 @@ var scheduleSchema = external_exports.object({
     }).strict()
   ).min(1).max(MAX_INSTALLS_PER_APP)
 }).strict();
+var toolSchema = external_exports.object({
+  // The manifest's tools[].name, never the `<slug>_` composed MCP name: the slug is already in
+  // `app.slug`, and carrying it twice would give the app worker two sources for one fact.
+  name: external_exports.string().min(1).max(MAX_APP_TOOL_NAME_LENGTH).regex(APP_TOOL_NAME_PATTERN),
+  // Who asked, and what they may do on this site. Derived from the bearer by the portal, never
+  // from the model's arguments.
+  viewer: external_exports.object({ userId: external_exports.string().min(1).max(64), access: external_exports.enum(["read", "write"]) }).strict(),
+  // Already validated against the tool's declared inputSchema, with the reserved routing names
+  // stripped. Every declared input schema has an object root, so this is an object too — and a
+  // call that names no arguments normalizes to `{}` rather than reaching the handler as undefined.
+  arguments: external_exports.record(external_exports.string(), external_exports.unknown()).default({}),
+  // Stable across a collapsed retry, so an app can deduplicate its external effects on it.
+  callId: external_exports.string().min(1).max(64)
+}).strict().refine((tool) => {
+  return new TextEncoder().encode(JSON.stringify(tool.arguments)).length <= MAX_TOOL_ARGUMENTS_BYTES;
+}, "Tool arguments exceed the size cap");
 var controlEnvelopeSchema = external_exports.object({
   v: external_exports.literal(CONTROL_ENVELOPE_VERSION),
-  kind: external_exports.enum(["noop", "lifecycle", "migration", "schedule"]),
+  kind: external_exports.enum(["noop", "lifecycle", "migration", "schedule", "tool"]),
   site: external_exports.object({ origin: external_exports.string().min(1).max(255) }).strict(),
   app: external_exports.object({ slug: external_exports.string().min(1).max(30), version: external_exports.string().min(1).max(32) }).strict(),
   install: external_exports.object({ id: external_exports.string().min(1).max(64), ord: external_exports.number().int().min(1), label: external_exports.string().max(100) }).strict().optional(),
   lifecycle: lifecycleEventSchema.optional(),
   migration: migrationSchema.optional(),
-  schedule: scheduleSchema.optional()
+  schedule: scheduleSchema.optional(),
+  tool: toolSchema.optional()
 }).strict().superRefine((envelope, ctx) => {
   if (envelope.kind === "lifecycle" !== (envelope.lifecycle !== void 0)) {
     ctx.addIssue({ code: "custom", path: ["lifecycle"], message: "Lifecycle payload must match the control kind" });
@@ -14720,13 +14746,50 @@ var controlEnvelopeSchema = external_exports.object({
   if (envelope.kind === "schedule" !== (envelope.schedule !== void 0)) {
     ctx.addIssue({ code: "custom", path: ["schedule"], message: "Schedule payload must match the control kind" });
   }
+  if (envelope.kind === "tool" !== (envelope.tool !== void 0)) {
+    ctx.addIssue({ code: "custom", path: ["tool"], message: "Tool payload must match the control kind" });
+  }
   if (envelope.kind === "lifecycle" && envelope.install === void 0) {
     ctx.addIssue({ code: "custom", path: ["install"], message: "Lifecycle control needs an install" });
   }
+  if (envelope.kind === "tool" && envelope.install === void 0) {
+    ctx.addIssue({ code: "custom", path: ["install"], message: "Tool control needs an install" });
+  }
 });
+var toolDataWithinLimits = (value) => {
+  const stack = [{ value, depth: 0 }];
+  let seen = 0;
+  while (stack.length > 0) {
+    const next = stack.pop();
+    seen += 1;
+    if (next.depth > MAX_TOOL_DATA_DEPTH || seen > MAX_TOOL_DATA_NODES) {
+      return false;
+    }
+    if (next.value !== null && typeof next.value === "object") {
+      for (const child of Object.values(next.value)) {
+        stack.push({ value: child, depth: next.depth + 1 });
+      }
+    }
+  }
+  return true;
+};
+var toolResultSchema = external_exports.object({
+  content: external_exports.string().max(MAX_TOOL_RESULT_BYTES),
+  // MCP defines `structuredContent` as an object, so a bare scalar or array is refused here rather
+  // than surfacing as a protocol error at the client.
+  data: external_exports.record(external_exports.string(), external_exports.unknown()).optional(),
+  // True when the handler chose to fail with `ctx.fail`: `content` is then the app's own message
+  // for the model. A thrown handler is `ok: false` with no `tool` at all.
+  failed: external_exports.boolean()
+}).strict().refine((result) => {
+  return toolDataWithinLimits(result.data);
+}, "Tool result nests too deeply or carries too many values").refine((result) => {
+  return new TextEncoder().encode(JSON.stringify({ content: result.content, data: result.data ?? null })).length <= MAX_TOOL_RESULT_BYTES;
+}, "Tool result exceeds the size cap");
 var controlResponseSchema = external_exports.object({
   v: external_exports.literal(CONTROL_ENVELOPE_VERSION),
   ok: external_exports.boolean(),
+  tool: toolResultSchema.optional(),
   migration: external_exports.union([
     external_exports.object({ done: external_exports.literal(true) }).strict(),
     external_exports.object({ done: external_exports.literal(false), checkpoint: external_exports.unknown() }).strict().refine((result) => {
@@ -14741,12 +14804,21 @@ var ENDPOINT_CONTEXT_HEADER = "x-qinto-endpoint-context";
 var ENDPOINT_OUTCOMES_HEADER = "x-qinto-endpoint-outcomes";
 var MAX_ENDPOINT_BODY_BYTES = 1024 * 1024;
 var MAX_ENDPOINT_OUTCOMES_BYTES = 64 * 1024;
+var MAX_ENDPOINT_PATH_LENGTH = 16 * 1024;
 var installSchema3 = external_exports.object({ id: external_exports.string().min(1).max(64), ord: external_exports.number().int().min(1), label: external_exports.string().max(100) }).strict();
 var endpointContextSchema = external_exports.object({
-  path: external_exports.string().min(1).max(255),
+  // The declared template, which keys the bundle's handler map; `path` is what the caller asked
+  // for. Only `route` may key the rate limiter — a concrete path gives every parameter value its
+  // own bucket, which is no limit at all.
+  route: external_exports.string().min(1).max(255),
+  path: external_exports.string().min(1).max(MAX_ENDPOINT_PATH_LENGTH),
+  // A name is cut from `route`, so the route's own cap bounds it; anything tighter would reject a
+  // parameter the manifest grammar accepts and the worker already matched.
+  params: external_exports.record(external_exports.string().min(1).max(255), external_exports.string().max(MAX_ENDPOINT_PATH_LENGTH)).default({}),
   method: external_exports.enum(["GET", "POST", "PUT", "PATCH", "DELETE"]),
   mode: external_exports.enum(["webhook", "api"]),
   version: external_exports.string().min(1).max(32),
+  site: external_exports.object({ origin: external_exports.string().min(1).max(255) }).strict(),
   installs: external_exports.array(installSchema3).min(1).max(15)
 }).strict().refine((context) => {
   return context.mode === "webhook" || context.installs.length === 1;
@@ -14761,6 +14833,96 @@ var endpointOutcomesSchema = external_exports.object({
   ).max(15)
 }).strict();
 
+// ../../../libs/app-envelope/src/oauth.ts
+var APP_OAUTH_BINDING_PREFIX = "OAUTH_";
+var appOauthBindingName = (providerId, ordinal) => {
+  return `${APP_OAUTH_BINDING_PREFIX}${providerId.toUpperCase().replaceAll("-", "_")}_${ordinal}`;
+};
+var parseAppOauthBinding = (raw) => {
+  if (raw === void 0 || raw === "") {
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const value = parsed;
+  if (value["st"] !== "connected" && value["st"] !== "reconnect_required") {
+    return null;
+  }
+  const expiresAt = value["e"];
+  const token = value["t"];
+  return {
+    ...typeof token === "string" && token !== "" ? { t: token } : {},
+    e: typeof expiresAt === "number" ? expiresAt : null,
+    st: value["st"]
+  };
+};
+
+// ../../../libs/app-envelope/src/observability.ts
+var APP_OBSERVABILITY_HEADER = "x-qinto-app-observability";
+var APP_OBSERVABILITY_VERSION = 1;
+var MAX_APP_OBSERVABILITY_EVENTS = 20;
+var MAX_APP_SAVED_ERRORS = 5;
+var MAX_APP_EVENT_NAME_BYTES = 128;
+var MAX_APP_ACTION_NAME_BYTES = 256;
+var MAX_APP_ERROR_DESCRIPTION_BYTES = 2048;
+var MAX_APP_ERROR_PAYLOAD_BYTES = 4096;
+var MAX_APP_DATA_POINT_BLOB_BYTES = 16 * 1024;
+var MAX_APP_OBSERVABILITY_BYTES = 32 * 1024;
+var APP_OBSERVABILITY_JSON_BUDGET = MAX_APP_OBSERVABILITY_BYTES / 4 * 3;
+var APP_EVENT_STATUSES = ["success", "error"];
+var APP_ERROR_CATEGORIES = ["authorization", "configuration", "validation", "rate_limit", "upstream", "internal"];
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+var observabilityEventSchema = external_exports.object({ ord: external_exports.number().int().min(1), name: external_exports.string().min(1).max(MAX_APP_EVENT_NAME_BYTES), status: external_exports.enum(APP_EVENT_STATUSES) }).strict();
+var savedErrorSchema = external_exports.object({
+  ord: external_exports.number().int().min(1),
+  category: external_exports.enum(APP_ERROR_CATEGORIES),
+  action: external_exports.string().min(1).max(MAX_APP_ACTION_NAME_BYTES),
+  description: external_exports.string().min(1).max(MAX_APP_ERROR_DESCRIPTION_BYTES),
+  payload: external_exports.string().max(MAX_APP_ERROR_PAYLOAD_BYTES).optional(),
+  error: external_exports.string().max(MAX_APP_ERROR_PAYLOAD_BYTES).optional()
+}).strict();
+var appObservabilityRecordSchema = external_exports.object({
+  v: external_exports.literal(APP_OBSERVABILITY_VERSION),
+  truncated: external_exports.boolean().optional(),
+  events: external_exports.array(observabilityEventSchema).max(MAX_APP_OBSERVABILITY_EVENTS),
+  errors: external_exports.array(savedErrorSchema).max(MAX_APP_SAVED_ERRORS)
+}).strict();
+var utf8Length = (value) => {
+  return encoder.encode(value).length;
+};
+var truncateUtf8 = (value, maxBytes) => {
+  if (utf8Length(value) <= maxBytes) {
+    return value;
+  }
+  let kept = "";
+  let used = 0;
+  for (const character of value) {
+    const size = utf8Length(character);
+    if (used + size > maxBytes) {
+      break;
+    }
+    kept += character;
+    used += size;
+  }
+  return kept;
+};
+var serializeAppObservability = (record2) => {
+  const bytes = encoder.encode(JSON.stringify(record2));
+  let binary = "";
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte);
+  }
+  return btoa(binary);
+};
+
 // ../../../libs/app-envelope/src/ui.ts
 var UI_CONTEXT_HEADER = "x-qinto-ui-context";
 var MAX_UI_BODY_BYTES = 1024 * 1024;
@@ -14806,10 +14968,10 @@ var formatSpansRecord = (record2) => {
 };
 
 // ../../../libs/tail-trace/src/app-spans.ts
-var encoder = new TextEncoder();
-var decoder = new TextDecoder();
+var encoder2 = new TextEncoder();
+var decoder2 = new TextDecoder();
 var serializeAppSpans = (record2) => {
-  const bytes = encoder.encode(JSON.stringify(record2));
+  const bytes = encoder2.encode(JSON.stringify(record2));
   let binary = "";
   for (const byte of bytes) {
     binary += String.fromCharCode(byte);
@@ -14818,12 +14980,12 @@ var serializeAppSpans = (record2) => {
 };
 
 // ../../../libs/tail-trace/src/budget.ts
-var encoder2 = new TextEncoder();
+var encoder3 = new TextEncoder();
 var byteLength = (value) => {
-  return encoder2.encode(JSON.stringify(value)).length;
+  return encoder3.encode(JSON.stringify(value)).length;
 };
 var fitsBudget = (text, max) => {
-  return text.length * 3 <= max || encoder2.encode(text).length <= max;
+  return text.length * 3 <= max || encoder3.encode(text).length <= max;
 };
 var MIN_KEEP = 64;
 var halveLongestString = (holders) => {
@@ -15407,6 +15569,162 @@ var buildAppsClient = (env, envelope) => {
   };
 };
 
+// src/oauth.ts
+var EXPIRY_FLOOR_MS = 1e3;
+var read = (env, id, ord, now) => {
+  const raw = env[appOauthBindingName(id, ord)];
+  const parsed = parseAppOauthBinding(typeof raw === "string" ? raw : void 0);
+  if (parsed === null) {
+    return null;
+  }
+  const expired = parsed.e !== null && parsed.e - now < EXPIRY_FLOOR_MS;
+  return {
+    id,
+    status: parsed.st === "connected" && !expired ? "connected" : "reconnect_required",
+    expiresAt: parsed.e
+  };
+};
+var buildOauth = (env, ord, now = Date.now) => {
+  return {
+    token: (id) => {
+      const raw = env[appOauthBindingName(id, ord)];
+      const parsed = parseAppOauthBinding(typeof raw === "string" ? raw : void 0);
+      if (parsed === null) {
+        throw new Error(`not_connected: this install has no ${id} connection`);
+      }
+      const state = read(env, id, ord, now());
+      if (parsed.t === void 0 || state?.status !== "connected") {
+        throw new Error(`reconnect_required: the ${id} connection has ended and a site manager must reconnect it`);
+      }
+      return parsed.t;
+    },
+    connection: (id) => {
+      return read(env, id, ord, now());
+    }
+  };
+};
+var oauthTokenValues = (env) => {
+  const values = /* @__PURE__ */ new Set();
+  for (const [name, raw] of Object.entries(env)) {
+    if (!name.startsWith("OAUTH_") || typeof raw !== "string") {
+      continue;
+    }
+    const token = parseAppOauthBinding(raw)?.t;
+    if (token !== void 0 && token !== "") {
+      values.add(token);
+    }
+  }
+  return [...values];
+};
+var buildUiOauth = (env, installs, now = Date.now) => {
+  const ordinalOf = (installId) => {
+    return installs.find((install) => install.id === installId)?.ord ?? null;
+  };
+  return {
+    token: (id, options) => {
+      const ord = ordinalOf(options.installId);
+      if (ord === null) {
+        throw new Error(`not_connected: ${options.installId} is not an install of this app`);
+      }
+      return buildOauth(env, ord, now).token(id);
+    },
+    connection: (id, options) => {
+      const ord = ordinalOf(options.installId);
+      return ord === null ? null : buildOauth(env, ord, now).connection(id);
+    }
+  };
+};
+
+// src/observability-collector.ts
+import { AsyncLocalStorage as AsyncLocalStorage2 } from "node:async_hooks";
+var ENVELOPE_OVERHEAD = 64;
+var collectors = new AsyncLocalStorage2();
+var serialized = (value) => {
+  if (value instanceof Error) {
+    const stack = value.stack;
+    return JSON.stringify({ name: value.name, message: value.message, ...stack === void 0 ? {} : { stack } });
+  }
+  let text;
+  try {
+    text = JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+  return typeof text === "string" ? text : String(value);
+};
+var field = (value, redact, maxBytes) => {
+  return truncateUtf8(redact(value), maxBytes);
+};
+var optionalField = (value, redact) => {
+  if (value === void 0) {
+    return void 0;
+  }
+  return field(serialized(value), redact, MAX_APP_ERROR_PAYLOAD_BYTES);
+};
+var createObservabilityCollector = (redact) => {
+  const events = [];
+  const errors = [];
+  let used = ENVELOPE_OVERHEAD;
+  let truncated = false;
+  const size = (entry) => {
+    return utf8Length(JSON.stringify(entry)) + 1;
+  };
+  return {
+    addEvent: (ord, name, status) => {
+      if (name === "" || !APP_EVENT_STATUSES.includes(status)) {
+        truncated = true;
+        return;
+      }
+      if (events.length >= MAX_APP_OBSERVABILITY_EVENTS) {
+        truncated = true;
+        return;
+      }
+      const entry = { ord, name: field(name, redact, MAX_APP_EVENT_NAME_BYTES), status };
+      used += size(entry);
+      events.push(entry);
+    },
+    addError: (ord, input) => {
+      if (!APP_ERROR_CATEGORIES.includes(input.category) || input.action === "" || input.description === "") {
+        truncated = true;
+        return;
+      }
+      if (errors.length >= MAX_APP_SAVED_ERRORS) {
+        truncated = true;
+        return;
+      }
+      const payload = optionalField(input.payload, redact);
+      const error51 = optionalField(input.error, redact);
+      const entry = {
+        ord,
+        category: input.category,
+        action: field(input.action, redact, MAX_APP_ACTION_NAME_BYTES),
+        description: field(input.description, redact, MAX_APP_ERROR_DESCRIPTION_BYTES),
+        ...payload === void 0 ? {} : { payload },
+        ...error51 === void 0 ? {} : { error: error51 }
+      };
+      const entrySize = size(entry);
+      if (used + entrySize > APP_OBSERVABILITY_JSON_BUDGET) {
+        truncated = true;
+        return;
+      }
+      used += entrySize;
+      errors.push(entry);
+    },
+    record: () => {
+      if (events.length === 0 && errors.length === 0) {
+        return null;
+      }
+      return { v: APP_OBSERVABILITY_VERSION, ...truncated ? { truncated } : {}, events, errors };
+    }
+  };
+};
+var runWithObservability = (collector, run) => {
+  return collectors.run(collector, run);
+};
+var currentObservability = () => {
+  return collectors.getStore();
+};
+
 // src/observability.ts
 var exceptionAttrs = (error51) => {
   const attrs = {
@@ -15429,7 +15747,7 @@ var consoleText = (error51) => {
   }
   return redactUrlParams(error51 instanceof Error ? error51.stack ?? error51.message : String(error51));
 };
-var buildObservability = () => {
+var buildObservability = (ord) => {
   return {
     log: (message, attrs) => {
       addSpanEvent(message, attrs === void 0 ? {} : { attrs });
@@ -15439,6 +15757,21 @@ var buildObservability = () => {
       addSpanEvent(message, { level: "error", attrs: { ...attrs, ...error51 === void 0 ? {} : exceptionAttrs(error51) } });
       console.error(redactUrlParams(message), consoleText(error51), redactAttrs(attrs ?? {}));
     },
+    event: (name, status) => {
+      addSpanEvent(name, { attrs: { "app.event.status": status } });
+      if (ord !== null) {
+        currentObservability()?.addEvent(ord, name, status);
+      }
+    },
+    saveError: (input) => {
+      addSpanEvent(input.description, {
+        level: "error",
+        attrs: { "app.error.category": input.category, "app.error.action": input.action }
+      });
+      if (ord !== null) {
+        currentObservability()?.addError(ord, input);
+      }
+    },
     span: ((...args) => {
       const [name] = args;
       const { attrs, run } = spanParts(args);
@@ -15515,6 +15848,9 @@ var secretValues = (env) => {
       values.add(value);
     }
   }
+  for (const value of oauthTokenValues(env)) {
+    values.add(value);
+  }
   return [...values];
 };
 var projectInstallValues = (maps, kinds, ord) => {
@@ -15591,13 +15927,13 @@ var readOnce = (env, subject) => {
   };
 };
 var fetchedContext = (env, subject, collector) => {
-  const read = readOnce(env, () => {
+  const read2 = readOnce(env, () => {
     return subject("context.load");
   });
   return {
     private: {
       load: async () => {
-        return (await read()).private;
+        return (await read2()).private;
       },
       set: (patch) => {
         subject("context.set");
@@ -15606,7 +15942,7 @@ var fetchedContext = (env, subject, collector) => {
     },
     shared: {
       load: async () => {
-        return (await read()).shared;
+        return (await read2()).shared;
       },
       set: (patch) => {
         subject("context.set");
@@ -15616,13 +15952,13 @@ var fetchedContext = (env, subject, collector) => {
   };
 };
 var asyncContext = (env, subject) => {
-  const read = readOnce(env, () => {
+  const read2 = readOnce(env, () => {
     return subject("context.load");
   });
   return {
     private: {
       load: async () => {
-        return (await read()).private;
+        return (await read2()).private;
       },
       set: async (patch) => {
         assertValidPatch(patch);
@@ -15634,7 +15970,7 @@ var asyncContext = (env, subject) => {
     },
     shared: {
       load: async () => {
-        return (await read()).shared;
+        return (await read2()).shared;
       },
       set: async (patch) => {
         assertValidPatch(patch);
@@ -15694,12 +16030,13 @@ var buildWorkflowContext = (env, stamp) => {
     env,
     install,
     startWorkflow: buildStartWorkflow(stamp),
+    oauth: buildOauth(env, stamp.ord),
     variables,
     secrets,
     appVariables,
     appSecrets,
     userId: stamp.anonId,
-    observability: buildObservability(),
+    observability: buildObservability(stamp.ord),
     context: asyncContext(env, (what) => {
       return requireSubject(stamp.anonId, what);
     }),
@@ -15776,6 +16113,7 @@ var buildContext = ({
     secrets,
     appVariables: appScope.appVariables,
     appSecrets: appScope.appSecrets,
+    oauth: buildOauth(env, install.ord),
     user: envelope.user ?? null,
     consent: envelope.consent,
     geo: envelope.geo,
@@ -15830,7 +16168,7 @@ var buildContext = ({
         }
       }
     },
-    observability: buildObservability(),
+    observability: buildObservability(install.ord),
     apps: buildAppsClient(env, envelope)
   };
 };
@@ -15902,7 +16240,8 @@ var buildCatalogQuery = ({ env, ticket, installId }) => {
 // src/schedule.ts
 var dispatchSchedule = async (envelope, bundle, env) => {
   const schedule = envelope.schedule;
-  const handler = bundle.schedules?.[schedule.id];
+  const schedules = bundle.schedules;
+  const handler = schedules !== void 0 && Object.hasOwn(schedules, schedule.id) ? schedules[schedule.id] : void 0;
   if (typeof handler !== "function") {
     return json2(200, {
       v: CONTROL_ENVELOPE_VERSION,
@@ -15927,11 +16266,12 @@ var dispatchSchedule = async (envelope, bundle, env) => {
         installLabel: install.label,
         anonId: null
       }),
+      oauth: buildOauth(env, install.ord),
       variables,
       secrets,
       appVariables: appScope.appVariables,
       appSecrets: appScope.appSecrets,
-      observability: buildObservability(),
+      observability: buildObservability(install.ord),
       apps: buildAppsClient(env, { depth: 0 }),
       query: buildCatalogQuery({ env, ticket: install.catalogQueryTicket, installId: install.id }),
       push: async (userId, message) => {
@@ -15963,6 +16303,141 @@ var dispatchSchedule = async (envelope, bundle, env) => {
   return json2(200, { v: CONTROL_ENVELOPE_VERSION, ok: true });
 };
 
+// src/tool.ts
+var failure = (message) => {
+  return json2(200, { v: CONTROL_ENVELOPE_VERSION, ok: false, error: { message } });
+};
+var isFailure = (value) => {
+  return value !== null && typeof value === "object" && value.kind === "tool_error" && typeof value.message === "string";
+};
+var isResult = (value) => {
+  return value !== null && typeof value === "object" && typeof value.content === "string";
+};
+var isStructuredData = (data) => {
+  return data === void 0 || data !== null && typeof data === "object" && !Array.isArray(data);
+};
+var isPlainContainer = (value) => {
+  const prototype = Object.getPrototypeOf(value);
+  return Array.isArray(value) || prototype === Object.prototype || prototype === null;
+};
+var jsonScalarVerdict = (value) => {
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return "ok";
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? "ok" : "invalid";
+  }
+  if (value === void 0 || typeof value !== "object" || !isPlainContainer(value)) {
+    return "invalid";
+  }
+  return "container";
+};
+var isJsonValue = (root) => {
+  const stack = [root];
+  const seen = /* @__PURE__ */ new Set();
+  while (stack.length > 0) {
+    const value = stack.pop();
+    const verdict = jsonScalarVerdict(value);
+    if (verdict === "invalid") {
+      return false;
+    }
+    if (verdict === "ok" || seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    if (Array.isArray(value) && Object.keys(value).length !== value.length) {
+      return false;
+    }
+    stack.push(...Object.values(value));
+  }
+  return true;
+};
+var truncate = (message) => {
+  return message.length <= MAX_TOOL_ERROR_MESSAGE_LENGTH ? message : message.slice(0, MAX_TOOL_ERROR_MESSAGE_LENGTH);
+};
+var checkResult = (result) => {
+  if (!isStructuredData(result.data)) {
+    return "not_structured";
+  }
+  if (result.data !== void 0 && !isJsonValue(result.data)) {
+    return "not_serializable";
+  }
+  let encoded;
+  try {
+    encoded = new TextEncoder().encode(JSON.stringify({ content: result.content, data: result.data ?? null }));
+  } catch {
+    return "not_serializable";
+  }
+  if (encoded.length > MAX_TOOL_RESULT_BYTES || !toolDataWithinLimits(result.data)) {
+    return "too_large";
+  }
+  return "ok";
+};
+var buildContext2 = (envelope, env) => {
+  const install = envelope.install;
+  const { variableKinds, appVariableKinds } = contextKindsOf(env);
+  const maps = parseVariableMaps(env);
+  const appScope = projectAppValues(env, appVariableKinds);
+  const { variables, secrets } = projectInstallValues(maps, variableKinds, install.ord);
+  return {
+    env,
+    site: envelope.site,
+    install: { id: install.id, label: install.label },
+    viewer: envelope.tool.viewer,
+    callId: envelope.tool.callId,
+    startWorkflow: buildStartWorkflow({ ord: install.ord, installId: install.id, installLabel: install.label, anonId: null }),
+    oauth: buildOauth(env, install.ord),
+    variables,
+    secrets,
+    appVariables: appScope.appVariables,
+    appSecrets: appScope.appSecrets,
+    observability: buildObservability(install.ord),
+    apps: buildAppsClient(env, { depth: 0 }),
+    fail: (message) => {
+      return { kind: "tool_error", message: truncate(message) };
+    }
+  };
+};
+var dispatchTool = async (envelope, bundle, env) => {
+  const name = envelope.tool.name;
+  const tools = bundle.tools;
+  const handler = tools !== void 0 && Object.hasOwn(tools, name) ? tools[name] : void 0;
+  if (typeof handler !== "function") {
+    return failure(`missing handler: tools.${name}`);
+  }
+  setSpanAttributes({ "app.tool": name, "app.tool_call_id": envelope.tool.callId });
+  let value;
+  try {
+    value = await installSpan(envelope.install, () => {
+      return handler(envelope.tool.arguments, buildContext2(envelope, env));
+    });
+  } catch (error51) {
+    console.warn(`tool ${name} failed for install ${envelope.install.id}: ${failureMessage(error51)}`);
+    return failure(`tool ${name} failed`);
+  }
+  if (isFailure(value)) {
+    return json2(200, { v: CONTROL_ENVELOPE_VERSION, ok: true, tool: { content: truncate(value.message), failed: true } });
+  }
+  if (!isResult(value)) {
+    return failure(`tool ${name} returned no result`);
+  }
+  const verdict = checkResult(value);
+  if (verdict === "not_structured") {
+    return failure(`tool ${name} returned data that is not a JSON object`);
+  }
+  if (verdict === "not_serializable") {
+    return failure(`tool ${name} returned data that cannot be serialized`);
+  }
+  if (verdict === "too_large") {
+    return failure(`tool ${name} returned a result over the size cap`);
+  }
+  return json2(200, {
+    v: CONTROL_ENVELOPE_VERSION,
+    ok: true,
+    tool: { content: value.content, ...value.data === void 0 ? {} : { data: value.data }, failed: false }
+  });
+};
+
 // src/control.ts
 var controlError = (status, message) => {
   return json2(status, { v: CONTROL_ENVELOPE_VERSION, ok: false, error: { message } });
@@ -15993,7 +16468,7 @@ var lifecycleContext = (env, envelope) => {
       installLabel: install.label,
       anonId: null
     }),
-    observability: buildObservability()
+    observability: buildObservability(install.ord)
   };
 };
 var migrationContext = (env, envelope) => {
@@ -16003,7 +16478,9 @@ var migrationContext = (env, envelope) => {
     site: envelope.site,
     appVariables: appScope.appVariables,
     appSecrets: appScope.appSecrets,
-    observability: buildObservability()
+    // A migration runs once for the site, not once per install, so it has no install to attribute
+    // an event or a saved error to.
+    observability: buildObservability(null)
   };
 };
 var runStatementMigration = async (env, migration) => {
@@ -16100,6 +16577,9 @@ var dispatchControl = async ({ request, env, versions }) => {
     case "schedule": {
       return dispatchSchedule(envelope, bundle, env);
     }
+    case "tool": {
+      return dispatchTool(envelope, bundle, env);
+    }
   }
 };
 
@@ -16132,19 +16612,22 @@ var handlerRequest = (request, context, body) => {
     body: body.byteLength === 0 ? void 0 : body
   });
 };
-var buildContext2 = ({ env, maps, kinds, appScope, install }) => {
+var buildContext3 = ({ env, maps, kinds, appScope, install, site, params }) => {
   const { variables, secrets } = projectInstallValues(maps, kinds, install.ord);
   return {
     env,
+    site,
+    params,
     install: { id: install.id, label: install.label },
     // An endpoint has no visitor, so a workflow it starts cannot push. `push` below is the
     // exception: it names its subject rather than inheriting one.
     startWorkflow: buildStartWorkflow({ ord: install.ord, installId: install.id, installLabel: install.label, anonId: null }),
+    oauth: buildOauth(env, install.ord),
     variables,
     secrets,
     appVariables: appScope.appVariables,
     appSecrets: appScope.appSecrets,
-    observability: buildObservability(),
+    observability: buildObservability(install.ord),
     apps: buildAppsClient(env, { depth: 0 }),
     push: async (userId, message) => {
       await brokerPush(env, {
@@ -16207,7 +16690,8 @@ var dispatchEndpoint = async ({ request, env, versions }) => {
     return Response.json({ error: "unknown version" }, { status: 404 });
   }
   const bundle = versions[context.version];
-  const candidate = bundle?.endpoints?.[context.path];
+  const endpoints = bundle?.endpoints;
+  const candidate = endpoints !== void 0 && Object.hasOwn(endpoints, context.route) ? endpoints[context.route] : void 0;
   if (typeof candidate !== "function") {
     return Response.json({ error: "not_found" }, { status: 404 });
   }
@@ -16218,7 +16702,10 @@ var dispatchEndpoint = async ({ request, env, versions }) => {
   const appScope = projectAppValues(env, appVariableKinds);
   const invoke = async (install) => {
     return installSpan(install, () => {
-      return handler(handlerRequest(request, context, body), buildContext2({ env, maps, kinds: variableKinds, appScope, install }));
+      return handler(
+        handlerRequest(request, context, body),
+        buildContext3({ env, maps, kinds: variableKinds, appScope, install, site: context.site, params: context.params })
+      );
     });
   };
   const installs = [...context.installs].sort((left, right) => {
@@ -16241,29 +16728,38 @@ var appSlug = (context) => {
     return "app";
   }
 };
-var withSpans = (response, record2) => {
+var withSpans = (response, record2, collector) => {
   const headers = new Headers(response.headers);
   headers.set(APP_SPANS_HEADER, serializeAppSpans(record2));
+  headers.delete(APP_OBSERVABILITY_HEADER);
+  const observability = collector.record();
+  if (observability !== null) {
+    headers.set(APP_OBSERVABILITY_HEADER, serializeAppObservability(observability));
+  }
   return new Response(response.body, { status: response.status, statusText: response.statusText, headers });
 };
 var runAppInvocation = async (input, handle) => {
   let record2 = { spans: [] };
+  const redact = spanRedactor(input.secrets);
+  const collector = createObservabilityCollector(redact);
   try {
     const response = await runInvocation(
       {
         name: appSlug(input.context),
         trace: parseTraceContext(input.request.headers.get(TRACE_HEADER)),
         budget: APP_SPANS_JSON_BUDGET,
-        redact: spanRedactor(input.secrets),
+        redact,
         emit: (emitted) => {
           record2 = emitted;
         }
       },
-      handle
+      () => {
+        return runWithObservability(collector, handle);
+      }
     );
-    return withSpans(response, record2);
+    return withSpans(response, record2, collector);
   } catch {
-    return withSpans(input.failure(), record2);
+    return withSpans(input.failure(), record2, collector);
   }
 };
 
@@ -16289,21 +16785,21 @@ var capturedBody = async (open) => {
       return void 0;
     }
     const reader = body.getReader();
-    const decoder2 = new TextDecoder();
+    const decoder3 = new TextDecoder();
     const expired = new Promise((resolve) => {
       timer = setTimeout(() => resolve(null), READ_BUDGET_MS);
     });
     let text = "";
     for (; ; ) {
-      const read = await Promise.race([reader.read(), expired]);
-      if (read === null) {
+      const read2 = await Promise.race([reader.read(), expired]);
+      if (read2 === null) {
         abandon(reader);
         return INCOMPLETE;
       }
-      if (read.done) {
+      if (read2.done) {
         break;
       }
-      text += decoder2.decode(read.value, { stream: true });
+      text += decoder3.decode(read2.value, { stream: true });
       if (text.length > MAX_BODY_CHARS) {
         abandon(reader);
         return TOO_LARGE;
@@ -16415,6 +16911,9 @@ var dispatchUi = async ({ request, env, versions }) => {
     env,
     install: { id: context.install.id, label: context.install.label },
     installs: projectAllInstallValues(maps, variableKinds, context.installs),
+    // The install is named rather than inherited: one panel serves every install, and reading the
+    // subject install's token while showing another account's UI would be silently wrong.
+    oauth: buildUiOauth(env, context.installs),
     settings: buildSettings({ env, ticket: context.writeTicket }),
     // The panel's viewer is a portal user, not a visitor, so a workflow it starts carries no subject.
     startWorkflow: buildUiStartWorkflow(
@@ -16426,7 +16925,7 @@ var dispatchUi = async ({ request, env, versions }) => {
     appVariables,
     appSecrets,
     viewer: context.viewer,
-    observability: buildObservability(),
+    observability: buildObservability(context.install.ord),
     apps: buildAppsClient(env, { depth: 0 })
   };
   let response;
@@ -16491,7 +16990,7 @@ var runInstalls = async (envelope, env, invoke) => {
   const { variableKinds: kinds, appVariableKinds } = contextKindsOf(env);
   const appScope = projectAppValues(env, appVariableKinds);
   const groups = [];
-  let failure;
+  let failure2;
   for (const install of envelope.installs) {
     const emits = [];
     const pushes = [];
@@ -16505,7 +17004,7 @@ var runInstalls = async (envelope, env, invoke) => {
     } catch (error51) {
       const message = failureMessage(error51);
       console.warn(`app hook failed for install ${install.id}: ${message}`);
-      failure ??= message;
+      failure2 ??= message;
       continue;
     }
     const contextWrites = context.writes();
@@ -16517,8 +17016,8 @@ var runInstalls = async (envelope, env, invoke) => {
   if (groups.length > 0) {
     body.effects = groups;
   }
-  if (failure !== void 0) {
-    body.error = { message: failure };
+  if (failure2 !== void 0) {
+    body.error = { message: failure2 };
   }
   return json2(200, body);
 };