@personaai/runtime 0.22.0 → 0.23.0

package/dist/index.js

@@ -46,6 +46,8 @@ function createClientForRequest(options, userId, logger) {
   return new PersonaClient({
     baseUrl: options.baseUrl,
     credential: options.credential,
+    // No end user (`null`) = a Project-scoped client: `/health` and the
+    // Project-wide admin capabilities.
     externalUserId: userId ?? void 0,
     fetch: options.fetch,
     logger: clientLogger
@@ -53,7 +55,12 @@ function createClientForRequest(options, userId, logger) {
 }
 
 // src/errors.ts
-import { PersonaApiError } from "@personaai/sdk";
+import {
+  BudgetExceededError,
+  EvalGateError,
+  ForbiddenScopeError,
+  PersonaApiError
+} from "@personaai/sdk";
 var RuntimeHttpError = class _RuntimeHttpError extends Error {
   status;
   code;
@@ -70,6 +77,36 @@ function mapErrorToRuntimeError(err, mode) {
   if (err instanceof RuntimeHttpError) {
     return { status: err.status, code: err.code, message: err.message };
   }
+  if (err instanceof ForbiddenScopeError) {
+    return {
+      status: 500,
+      code: "RUNTIME_MISCONFIGURED",
+      message: dev ? `The runtime's Persona API key lacks the "${err.requiredScope ?? "unknown"}" scope: ${err.message}` : "The server's Persona API key can't do this.",
+      ...dev ? { detail: { requiredScope: err.requiredScope, acceptedScopes: err.acceptedScopes } } : {}
+    };
+  }
+  if (err instanceof BudgetExceededError) {
+    return {
+      status: 402,
+      code: err.code,
+      message: err.message,
+      ...err.scope ? { details: { scope: err.scope } } : {},
+      ...dev ? { detail: err.response } : {}
+    };
+  }
+  if (err instanceof EvalGateError) {
+    return {
+      status: err.statusCode,
+      code: err.code,
+      message: err.message,
+      details: {
+        ...err.datasetId ? { datasetId: err.datasetId } : {},
+        ...err.minPassRate !== void 0 ? { minPassRate: err.minPassRate } : {},
+        ...err.passRate !== void 0 ? { passRate: err.passRate } : {},
+        ...err.runId ? { runId: err.runId } : {}
+      }
+    };
+  }
   if (err instanceof PersonaApiError) {
     return {
       status: err.statusCode,
@@ -101,6 +138,7 @@ function errorToResponse(err, mode) {
       error: {
         code: mapped.code,
         message: mapped.message,
+        ...mapped.details !== void 0 ? { details: mapped.details } : {},
         ...mapped.detail !== void 0 ? { detail: mapped.detail } : {}
       }
     })
@@ -131,7 +169,7 @@ function evictStaleRuns(runs, now, graceMs = DEFAULT_RUN_GRACE_MS, maxTracked =
 }
 
 // src/version.ts
-var RUNTIME_VERSION = "0.22.0";
+var RUNTIME_VERSION = "0.23.0";
 
 // src/routes/health.ts
 var alwaysOnCapabilities = {
@@ -141,15 +179,61 @@ var alwaysOnCapabilities = {
   files: true,
   memory: true,
   mcpOAuth: true,
-  workflows: true
-};
+  workflows: true,
+  voice: true,
+  feedback: true
+};
+var CAPABILITY_SCOPES = {
+  agentsWrite: ["*"],
+  mcps: ["*"],
+  providers: ["*"],
+  skills: ["*"],
+  knowledge: ["*"],
+  stores: ["*"],
+  rcpSources: ["*"],
+  auditLogs: ["*"],
+  architect: ["*"],
+  workflowsWrite: ["*"],
+  secrets: ["*"],
+  restToolSources: ["*"],
+  messages: ["agent:invoke"],
+  deploy: ["deploy:write"],
+  traces: ["traces:read", "agent:invoke"],
+  evals: ["eval:run"],
+  observe: ["traces:read"]
+};
+function scopeWarnings(scopes, capabilities) {
+  if (!scopes || scopes.includes("*")) return [];
+  const has = (s) => scopes.includes(s);
+  const warnings = [];
+  if (!has("agent:invoke")) {
+    warnings.push(
+      'The API key lacks "agent:invoke": chat, threads, files, memory and voice will fail.'
+    );
+  }
+  for (const [cap, needed] of Object.entries(CAPABILITY_SCOPES)) {
+    if (!capabilities[cap]) continue;
+    const missing = needed.filter((s) => !has(s));
+    if (missing.length) {
+      warnings.push(
+        `capabilities.${cap} is on but the API key lacks ${missing.map((s) => `"${s}"`).join(" and ")}.`
+      );
+    }
+  }
+  return warnings;
+}
 var healthRoute = async (_request, ctx) => {
+  let principal;
   try {
-    await ctx.client.whoami();
+    principal = await ctx.client.whoami();
   } catch (err) {
     const failed = errorToResponse(err, ctx.mode);
     return { ...failed, status: 503 };
   }
+  const raw = principal?.scopes;
+  const scopes = Array.isArray(raw) ? raw.filter((s) => typeof s === "string") : void 0;
+  const warnings = scopeWarnings(scopes, ctx.capabilities);
+  for (const w of warnings) ctx.logger.warn(w);
   return {
     kind: "buffered",
     status: 200,
@@ -157,7 +241,9 @@ var healthRoute = async (_request, ctx) => {
     body: JSON.stringify({
       status: "ok",
       version: RUNTIME_VERSION,
-      capabilities: { ...alwaysOnCapabilities, ...ctx.capabilities }
+      capabilities: { ...alwaysOnCapabilities, ...ctx.capabilities },
+      ...scopes ? { scopes } : {},
+      ...warnings.length ? { warnings } : {}
     })
   };
 };
@@ -248,6 +334,54 @@ function validateTurnContext(value) {
   }
   return context;
 }
+var ENVIRONMENTS = ["development", "production"];
+function clientVersionFields(body) {
+  const out = {};
+  if (body.environment !== void 0 && body.environment !== null) {
+    if (!ENVIRONMENTS.includes(body.environment)) {
+      throw new RuntimeHttpError(
+        400,
+        "INVALID_REQUEST",
+        '"environment" must be "development" or "production".'
+      );
+    }
+    out.environment = body.environment;
+  }
+  if (body.agentVersion !== void 0 && body.agentVersion !== null) {
+    const v = body.agentVersion;
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1) {
+      throw new RuntimeHttpError(
+        400,
+        "INVALID_REQUEST",
+        '"agentVersion" must be a positive integer.'
+      );
+    }
+    out.agentVersion = v;
+  }
+  return out;
+}
+async function resolveRunVersion(body, ctx, selection) {
+  const { selectVersion, defaultEnvironment, allowClientVersionSelection } = ctx.versioning;
+  if (allowClientVersionSelection) {
+    const fromClient = clientVersionFields(body);
+    if (fromClient.environment || fromClient.agentVersion) return fromClient;
+  }
+  if (selectVersion) {
+    const picked = await selectVersion(selection);
+    if (picked && (picked.environment || picked.agentVersion)) {
+      return {
+        ...picked.environment ? { environment: picked.environment } : {},
+        ...picked.agentVersion ? { agentVersion: picked.agentVersion } : {}
+      };
+    }
+  }
+  return defaultEnvironment ? { environment: defaultEnvironment } : {};
+}
+function incomingTraceparent(headers, enabled) {
+  if (!enabled) return void 0;
+  const value = headers.traceparent ?? headers.Traceparent;
+  return value && /^[0-9a-f]{2}-[0-9a-f]{32}-[0-9a-f]{16}-[0-9a-f]{2}$/i.test(value.trim()) ? value.trim() : void 0;
+}
 
 // src/routes/restToolsManifest.ts
 var restToolsManifestRoute = async (request, ctx) => {
@@ -306,6 +440,8 @@ function newAccumulator() {
     interrupted: false,
     erroredInBand: false,
     threadCreateFired: false,
+    personaRunId: void 0,
+    threadId: void 0,
     toolNames: /* @__PURE__ */ new Map(),
     nodeMeta: /* @__PURE__ */ new Map()
   };
@@ -315,6 +451,8 @@ async function processEvent(event, acc, runCtx, hooks) {
   switch (e.type) {
     case EventType.RUN_STARTED: {
       const threadId = typeof e.threadId === "string" ? e.threadId : void 0;
+      if (!acc.personaRunId && typeof e.runId === "string") acc.personaRunId = e.runId;
+      if (!acc.threadId && threadId) acc.threadId = threadId;
       if (runCtx.kind === "chat" && runCtx.agentId && !acc.threadCreateFired && !runCtx.threadId && threadId) {
         acc.threadCreateFired = true;
         await hooks?.onThreadCreate?.({ userId: runCtx.userId, agentId: runCtx.agentId, threadId });
@@ -423,9 +561,9 @@ var RunDriver = class {
   constructor(runId, runCtx, source, hooks, mode) {
     this.runId = runId;
     this.runCtx = runCtx;
-    this.firstFramePromise = new Promise((resolve, reject) => {
+    this.firstFramePromise = new Promise((resolve, reject2) => {
       this.resolveFirstFrame = resolve;
-      this.rejectFirstFrame = reject;
+      this.rejectFirstFrame = reject2;
     });
     void this.pump(source, hooks, mode);
   }
@@ -460,7 +598,9 @@ var RunDriver = class {
         text: acc.text,
         eventCount: count,
         interrupted: acc.interrupted,
-        erroredInBand: acc.erroredInBand
+        erroredInBand: acc.erroredInBand,
+        ...acc.personaRunId ? { personaRunId: acc.personaRunId } : {},
+        ...acc.threadId || this.runCtx.threadId ? { threadId: acc.threadId ?? this.runCtx.threadId } : {}
       };
       try {
         await hooks?.afterRun?.(this.runCtx, result);
@@ -510,14 +650,13 @@ var RunDriver = class {
    * original connection plus a reconnect that raced it) are supported.
    */
   subscribe(sinceSeq) {
-    const buffered = this.frames.slice(Math.max(sinceSeq + 1, 0));
-    const finishedAtSubscribeTime = this.finished;
+    const driver = this;
     const listeners = this.listeners;
     const doneListeners = this.doneListeners;
     return {
       [Symbol.asyncIterator]() {
-        const queue = [...buffered];
-        let live = !finishedAtSubscribeTime;
+        const queue = driver.frames.slice(Math.max(sinceSeq + 1, 0));
+        let live = !driver.finished;
         let wake = null;
         const onFrame = (_seq, frame) => {
           queue.push(frame);
@@ -657,12 +796,19 @@ var chatRoute = async (request, ctx) => {
     hasContext: !!body.context
   });
   const userId = request.userId;
+  const version = await resolveRunVersion(request.body, ctx, {
+    userId,
+    agentId: body.agentId,
+    kind: "chat"
+  });
+  const traceparent = incomingTraceparent(request.headers, ctx.forwardTraceparent);
   const runCtx = {
     userId,
     kind: "chat",
     agentId: body.agentId,
     threadId: body.threadId,
-    messages: body.messages
+    messages: body.messages,
+    ...version
   };
   logger.debug("beforeRun hook", { agentId: body.agentId, threadId: body.threadId });
   await ctx.hooks?.beforeRun?.(runCtx);
@@ -675,7 +821,9 @@ var chatRoute = async (request, ctx) => {
     contextOverride: body.contextOverride,
     context: body.context,
     tools: body.tools,
-    attachments: body.attachments
+    attachments: body.attachments,
+    ...version,
+    ...traceparent ? { traceparent } : {}
   });
   const runId = crypto.randomUUID();
   logger.info("chat run created", {
@@ -874,7 +1022,13 @@ var createVoiceSession = async (request, ctx) => {
   const contextOverride = typeof body.contextOverride === "string" && body.contextOverride ? body.contextOverride : void 0;
   const context = validateTurnContext(body.context);
   const tools = parseFrontendTools(body.tools);
+  const version = await resolveRunVersion(body, ctx, {
+    userId: request.userId,
+    agentId,
+    kind: "voice"
+  });
   const ticket = await ctx.client.voice.createSession(agentId, {
+    ...version,
     ...threadId ? { threadId } : {},
     ...contextOverride ? { contextOverride } : {},
     ...context ? { context } : {},
@@ -883,7 +1037,8 @@ var createVoiceSession = async (request, ctx) => {
   await ctx.hooks?.onVoiceSessionCreate?.({
     userId: request.userId,
     agentId,
-    threadId
+    threadId,
+    ...version
   });
   return json(201, ticket);
 };
@@ -1717,15 +1872,15 @@ function resolveSignedUrl(request, publicUrl) {
 }
 async function computeTwilioSignature(authToken, url, params) {
   const payload = url + Object.keys(params).sort().map((key2) => `${key2}${params[key2]}`).join("");
-  const encoder = new TextEncoder();
+  const encoder2 = new TextEncoder();
   const key = await crypto.subtle.importKey(
     "raw",
-    encoder.encode(authToken),
+    encoder2.encode(authToken),
     { name: "HMAC", hash: "SHA-1" },
     false,
     ["sign"]
   );
-  const signature = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  const signature = await crypto.subtle.sign("HMAC", key, encoder2.encode(payload));
   const bytes = new Uint8Array(signature);
   let binary = "";
   for (const byte of bytes) binary += String.fromCharCode(byte);
@@ -1890,6 +2045,598 @@ var twilioMessageChannel = async (request, ctx) => {
   }
 };
 
+// src/routes/feedback.ts
+var MAX_COMMENT = 2e3;
+var MAX_TAGS = 10;
+var MAX_TAG = 50;
+var createFeedback = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const runId = requireStringField(body, "runId");
+  if (body.score !== 1 && body.score !== -1) {
+    throw new RuntimeHttpError(400, "INVALID_REQUEST", '"score" must be 1 or -1.');
+  }
+  const score = body.score;
+  let comment;
+  if (body.comment !== void 0 && body.comment !== null) {
+    if (typeof body.comment !== "string" || body.comment.length > MAX_COMMENT) {
+      throw new RuntimeHttpError(
+        400,
+        "INVALID_REQUEST",
+        `"comment" must be a string of at most ${MAX_COMMENT} characters.`
+      );
+    }
+    comment = body.comment.trim() || void 0;
+  }
+  let tags;
+  if (body.tags !== void 0 && body.tags !== null) {
+    if (!Array.isArray(body.tags) || body.tags.length > MAX_TAGS || !body.tags.every((t) => typeof t === "string" && t.length > 0 && t.length <= MAX_TAG)) {
+      throw new RuntimeHttpError(
+        400,
+        "INVALID_REQUEST",
+        `"tags" must be up to ${MAX_TAGS} strings of at most ${MAX_TAG} characters.`
+      );
+    }
+    tags = body.tags;
+  }
+  const result = await ctx.client.feedback.create({
+    runId,
+    score,
+    ...comment ? { comment } : {},
+    ...tags?.length ? { tags } : {}
+  });
+  await ctx.hooks?.onFeedback?.({
+    userId: request.userId,
+    runId,
+    score,
+    ...comment ? { comment } : {},
+    ...tags?.length ? { tags } : {}
+  });
+  return json(200, result);
+};
+
+// src/routes/webhooks.ts
+var encoder = new TextEncoder();
+var DEFAULT_SEEN_LIMIT = 1e3;
+function rawBodyBytes(request) {
+  const raw = request.rawBody;
+  if (raw === void 0 || raw === null) return null;
+  return typeof raw === "string" ? encoder.encode(raw) : raw;
+}
+function parseSignature(header) {
+  let timestamp = null;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq <= 0) continue;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t" && /^\d+$/.test(value)) timestamp = Number(value);
+    else if (key === "v1" && /^[0-9a-f]{64}$/i.test(value)) signatures.push(value.toLowerCase());
+  }
+  return timestamp === null || signatures.length === 0 ? null : { timestamp, signatures };
+}
+function toHex(bytes) {
+  return [...new Uint8Array(bytes)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+function safeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+async function hmacHex(secret, message) {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  return toHex(await crypto.subtle.sign("HMAC", key, message));
+}
+function concat(a, b) {
+  const out = new Uint8Array(a.length + b.length);
+  out.set(a, 0);
+  out.set(b, a.length);
+  return out;
+}
+var reject = (code, message) => json(400, { error: { code, message } });
+function createSeenSet(limit = DEFAULT_SEEN_LIMIT) {
+  const ids = /* @__PURE__ */ new Set();
+  return {
+    has: (id) => ids.has(id),
+    add(id) {
+      ids.add(id);
+      if (ids.size > limit) ids.delete(ids.values().next().value);
+    }
+  };
+}
+function createWebhookRoute() {
+  const memory = createSeenSet();
+  return async (request, ctx) => {
+    const options = ctx.webhooks;
+    if (!options) return json(404, { error: { code: "NOT_FOUND", message: "Not found" } });
+    const logger = ctx.logger.child("webhooks");
+    const body = rawBodyBytes(request);
+    if (!body) {
+      logger.error("webhook request has no rawBody: the adapter must pass the raw bytes");
+      return json(500, {
+        error: {
+          code: "RUNTIME_MISCONFIGURED",
+          message: "The server did not keep the raw request body for webhook verification."
+        }
+      });
+    }
+    const header = request.headers["x-persona-signature"];
+    if (!header) return reject("MISSING_SIGNATURE", "Missing X-Persona-Signature header");
+    const parsed = parseSignature(header);
+    if (!parsed) return reject("INVALID_SIGNATURE", "Malformed X-Persona-Signature header");
+    const expected = await hmacHex(
+      options.secret,
+      concat(encoder.encode(`${parsed.timestamp}.`), body)
+    );
+    if (!parsed.signatures.some((sig) => safeEqual(sig, expected))) {
+      logger.warn("webhook signature does not match");
+      return reject("INVALID_SIGNATURE", "Webhook signature does not match");
+    }
+    const tolerance = options.toleranceSec ?? 300;
+    if (tolerance > 0 && Math.abs(Math.floor(Date.now() / 1e3) - parsed.timestamp) > tolerance) {
+      return reject("TIMESTAMP_OUT_OF_RANGE", "Webhook timestamp is outside the allowed tolerance");
+    }
+    let event;
+    try {
+      event = JSON.parse(new TextDecoder().decode(body));
+    } catch {
+      return reject("INVALID_PAYLOAD", "Webhook body is not valid JSON");
+    }
+    if (!event || typeof event !== "object" || typeof event.type !== "string") {
+      return reject("INVALID_PAYLOAD", "Webhook body is not a Persona event");
+    }
+    const deliveryId = request.headers["x-persona-delivery"];
+    if (deliveryId) {
+      const store = options.dedupe ?? memory;
+      if (await store.has(deliveryId)) {
+        logger.debug("duplicate webhook delivery ignored", { deliveryId, type: event.type });
+        return json(200, { received: true, duplicate: true });
+      }
+    }
+    const type = event.type;
+    const handlers = [options.on[type], options.on["*"]].filter(
+      (h) => typeof h === "function"
+    );
+    try {
+      for (const handler of handlers) await handler(event, { id: deliveryId, type });
+    } catch (err) {
+      logger.error("webhook handler failed", {
+        type,
+        deliveryId,
+        error: err instanceof Error ? err.message : String(err)
+      });
+      return json(500, { error: { code: "HANDLER_FAILED", message: "Webhook handler failed" } });
+    }
+    if (deliveryId) await (options.dedupe ?? memory).add(deliveryId);
+    logger.info("webhook handled", { type, deliveryId, handlers: handlers.length });
+    return json(200, { received: true });
+  };
+}
+
+// src/routes/secrets.ts
+var listSecrets = async (_request, ctx) => {
+  return json(200, await ctx.client.secrets.list());
+};
+var createSecret = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const secret = await ctx.client.secrets.create(
+    {
+      label: requireStringField(body, "label"),
+      value: requireStringField(body, "value")
+    },
+    request.headers["idempotency-key"]
+  );
+  return json(201, secret);
+};
+var getSecret = async (_request, ctx) => {
+  return json(200, await ctx.client.secrets.get(requireParam(ctx.params, "id")));
+};
+var updateSecret = async (request, ctx) => {
+  const body = request.body ?? {};
+  return json(200, await ctx.client.secrets.update(requireParam(ctx.params, "id"), body));
+};
+var deleteSecret = async (_request, ctx) => {
+  await ctx.client.secrets.delete(requireParam(ctx.params, "id"));
+  return noContent();
+};
+var getSecretUsage = async (_request, ctx) => {
+  return json(200, await ctx.client.secrets.getUsage(requireParam(ctx.params, "id")));
+};
+var bulkDeleteSecrets = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const ids = Array.isArray(body.ids) ? body.ids : [];
+  return json(200, await ctx.client.secrets.bulkDelete(ids));
+};
+
+// src/routes/restToolSources.ts
+var listRestToolSources = async (request, ctx) => {
+  const items = await ctx.client.restToolSources.list({
+    page: toInt(request.query.page),
+    limit: toInt(request.query.limit),
+    search: request.query.search
+  });
+  return json(200, items);
+};
+var createRestToolSource = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const source = await ctx.client.restToolSources.create(body, request.headers["idempotency-key"]);
+  return json(201, source);
+};
+var getRestToolSource = async (_request, ctx) => {
+  return json(200, await ctx.client.restToolSources.get(requireParam(ctx.params, "id")));
+};
+var updateRestToolSource = async (request, ctx) => {
+  const body = request.body ?? {};
+  return json(200, await ctx.client.restToolSources.update(requireParam(ctx.params, "id"), body));
+};
+var deleteRestToolSource = async (_request, ctx) => {
+  await ctx.client.restToolSources.delete(requireParam(ctx.params, "id"));
+  return noContent();
+};
+var getRestToolSourceUsage = async (_request, ctx) => {
+  return json(200, await ctx.client.restToolSources.getUsage(requireParam(ctx.params, "id")));
+};
+var testRestToolSource = async (_request, ctx) => {
+  return json(200, await ctx.client.restToolSources.testConnection(requireParam(ctx.params, "id")));
+};
+var bulkDeleteRestToolSources = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const ids = Array.isArray(body.ids) ? body.ids : [];
+  return json(200, await ctx.client.restToolSources.bulkDelete(ids));
+};
+
+// src/routes/deploy.ts
+function environmentParam(ctx) {
+  const env = requireParam(ctx.params, "environment");
+  if (env !== "development" && env !== "production") {
+    throw new RuntimeHttpError(
+      400,
+      "INVALID_REQUEST",
+      'environment must be "development" or "production".'
+    );
+  }
+  return env;
+}
+function positiveInt(raw, name) {
+  const v = Number(raw);
+  if (!Number.isInteger(v) || v < 1) {
+    throw new RuntimeHttpError(400, "INVALID_REQUEST", `${name} must be a positive integer.`);
+  }
+  return v;
+}
+function versionOrDraft(raw, name) {
+  if (!raw || raw === "draft") return "draft";
+  return positiveInt(raw, name);
+}
+async function audit(request, ctx, action, target) {
+  await ctx.hooks?.onAdminAction?.({
+    userId: request.userId,
+    capability: "deploy",
+    action,
+    target
+  });
+}
+var listAgentVersions = async (request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().agents.versions.list(requireParam(ctx.params, "id"), {
+      page: toInt(request.query.page),
+      limit: toInt(request.query.limit)
+    })
+  );
+};
+var publishAgentVersion = async (request, ctx) => {
+  const agentId = requireParam(ctx.params, "id");
+  const body = request.body ?? {};
+  const changelog = typeof body.changelog === "string" ? body.changelog : void 0;
+  const version = await ctx.projectClient().agents.versions.publish(agentId, changelog ? { changelog } : {});
+  await audit(request, ctx, "agent.version.publish", { agentId, version: version.version });
+  return json(201, version);
+};
+var agentVersionStats = async (request, ctx) => {
+  const source = request.query.source;
+  return json(
+    200,
+    await ctx.projectClient().agents.versions.stats(requireParam(ctx.params, "id"), {
+      days: toInt(request.query.days),
+      ...source ? { source } : {}
+    })
+  );
+};
+var getAgentVersion = async (_request, ctx) => {
+  const version = positiveInt(requireParam(ctx.params, "version"), "version");
+  return json(
+    200,
+    await ctx.projectClient().agents.versions.get(requireParam(ctx.params, "id"), version)
+  );
+};
+var diffAgentVersion = async (request, ctx) => {
+  const from = versionOrDraft(requireParam(ctx.params, "version"), "version");
+  const to = versionOrDraft(request.query.against, '"against"');
+  return json(
+    200,
+    await ctx.projectClient().agents.versions.diff(requireParam(ctx.params, "id"), from, to)
+  );
+};
+var getAgentDeployments = async (_request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().agents.versions.deployments(requireParam(ctx.params, "id"))
+  );
+};
+var setAgentServePolicy = async (request, ctx) => {
+  const agentId = requireParam(ctx.params, "id");
+  const body = requireBodyObject(request.body);
+  if (typeof body.serveDeployedVersion !== "boolean") {
+    throw new RuntimeHttpError(
+      400,
+      "INVALID_REQUEST",
+      '"serveDeployedVersion" is required and must be a boolean.'
+    );
+  }
+  const result = await ctx.projectClient().agents.versions.setServePolicy(agentId, body.serveDeployedVersion);
+  await audit(request, ctx, "agent.serve_policy.set", { agentId, ...result });
+  return json(200, result);
+};
+var deployAgentVersion = async (request, ctx) => {
+  const agentId = requireParam(ctx.params, "id");
+  const environment = environmentParam(ctx);
+  const body = request.body ?? {};
+  let version;
+  if (body.version !== void 0 && body.version !== null) {
+    if (typeof body.version !== "number" || !Number.isInteger(body.version) || body.version < 1) {
+      throw new RuntimeHttpError(400, "INVALID_REQUEST", '"version" must be a positive integer.');
+    }
+    version = body.version;
+  }
+  const deployment = await ctx.projectClient().agents.versions.deploy(agentId, { environment, ...version ? { version } : {} });
+  await audit(request, ctx, "agent.version.deploy", {
+    agentId,
+    environment,
+    version: deployment.version
+  });
+  return json(200, deployment);
+};
+var rollbackAgentDeployment = async (request, ctx) => {
+  const agentId = requireParam(ctx.params, "id");
+  const environment = environmentParam(ctx);
+  const deployment = await ctx.projectClient().agents.versions.rollback(agentId, environment);
+  await audit(request, ctx, "agent.version.rollback", {
+    agentId,
+    environment,
+    version: deployment.version
+  });
+  return json(200, deployment);
+};
+
+// src/routes/traces.ts
+var STRING_FILTERS = [
+  "agentId",
+  "threadId",
+  "runId",
+  "status",
+  "source",
+  "channel",
+  "environment",
+  "feedback",
+  "from",
+  "to"
+];
+var listTraces = async (request, ctx) => {
+  const params = {
+    page: toInt(request.query.page),
+    limit: toInt(request.query.limit),
+    agentVersion: toInt(request.query.agentVersion)
+  };
+  for (const key of STRING_FILTERS) {
+    const value = request.query[key];
+    if (value) params[key] = value;
+  }
+  return json(200, await ctx.projectClient().traces.list(params));
+};
+var getTrace = async (request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().traces.get(requireParam(ctx.params, "id"), {
+      spans: request.query.spans !== "false"
+    })
+  );
+};
+var getTraceFeedback = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().traces.feedback(requireParam(ctx.params, "id")));
+};
+var getReplayPlan = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().traces.replayPlan(requireParam(ctx.params, "id")));
+};
+var replayTrace = async (request, ctx) => {
+  const traceId = requireParam(ctx.params, "id");
+  const options = request.body ?? {};
+  const result = await ctx.projectClient().traces.replay(traceId, options);
+  await ctx.hooks?.onAdminAction?.({
+    userId: request.userId,
+    capability: "traces",
+    action: "trace.replay",
+    target: { traceId, replayTraceId: result.traceId }
+  });
+  return json(201, result);
+};
+var listTraceReplays = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().traces.replays(requireParam(ctx.params, "id")));
+};
+
+// src/routes/evals.ts
+async function audit2(request, ctx, action, target) {
+  await ctx.hooks?.onAdminAction?.({
+    userId: request.userId,
+    capability: "evals",
+    action,
+    target
+  });
+}
+var listDatasets = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().datasets.list());
+};
+var createDataset = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const dataset = await ctx.projectClient().datasets.create(body);
+  await audit2(request, ctx, "dataset.create", { datasetId: dataset._id });
+  return json(201, dataset);
+};
+var getDataset = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().datasets.get(requireParam(ctx.params, "id")));
+};
+var updateDataset = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  return json(200, await ctx.projectClient().datasets.update(requireParam(ctx.params, "id"), body));
+};
+var deleteDataset = async (request, ctx) => {
+  const datasetId = requireParam(ctx.params, "id");
+  const result = await ctx.projectClient().datasets.delete(datasetId);
+  await audit2(request, ctx, "dataset.delete", { datasetId });
+  return json(200, result);
+};
+var listDatasetItems = async (request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().datasets.items.list(requireParam(ctx.params, "id"), {
+      page: toInt(request.query.page),
+      limit: toInt(request.query.limit)
+    })
+  );
+};
+var addDatasetItems = async (request, ctx) => {
+  const datasetId = requireParam(ctx.params, "id");
+  const body = requireBodyObject(request.body);
+  let cases;
+  if (typeof body.text === "string") cases = body.text;
+  else if (Array.isArray(body.items)) cases = body.items;
+  else {
+    throw new RuntimeHttpError(
+      400,
+      "INVALID_REQUEST",
+      'Send "items" (an array of cases) or "text" (CSV / JSON).'
+    );
+  }
+  try {
+    return json(201, await ctx.projectClient().datasets.import(datasetId, cases));
+  } catch (err) {
+    if (err instanceof Error && err.message.startsWith("parseDatasetCases:")) {
+      throw new RuntimeHttpError(
+        400,
+        "INVALID_REQUEST",
+        err.message.replace("parseDatasetCases: ", "")
+      );
+    }
+    throw err;
+  }
+};
+var addDatasetItemFromTrace = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const traceId = requireStringField(body, "traceId");
+  const options = body.expected === null ? { expected: null } : typeof body.expected === "string" ? { expected: body.expected } : {};
+  return json(
+    201,
+    await ctx.projectClient().datasets.items.addFromTrace(requireParam(ctx.params, "id"), traceId, options)
+  );
+};
+var updateDatasetItem = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  return json(
+    200,
+    await ctx.projectClient().datasets.items.update(
+      requireParam(ctx.params, "id"),
+      requireParam(ctx.params, "itemId"),
+      body
+    )
+  );
+};
+var deleteDatasetItem = async (_request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().datasets.items.delete(requireParam(ctx.params, "id"), requireParam(ctx.params, "itemId"))
+  );
+};
+var listEvalRuns = async (request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().evals.list({
+      page: toInt(request.query.page),
+      limit: toInt(request.query.limit),
+      ...request.query.agentId ? { agentId: request.query.agentId } : {},
+      ...request.query.datasetId ? { datasetId: request.query.datasetId } : {}
+    })
+  );
+};
+var startEvalRun = async (request, ctx) => {
+  const body = requireBodyObject(request.body);
+  const run = await ctx.projectClient().evals.create(body);
+  await audit2(request, ctx, "eval_run.start", {
+    runId: run.id,
+    agentId: run.agentId,
+    datasetId: run.datasetId
+  });
+  return json(201, run);
+};
+var compareEvalRuns = async (request, ctx) => {
+  const { a, b } = request.query;
+  if (!a || !b) {
+    throw new RuntimeHttpError(
+      400,
+      "INVALID_REQUEST",
+      '"a" and "b" query parameters are required.'
+    );
+  }
+  return json(200, await ctx.projectClient().evals.compare(a, b));
+};
+var getEvalRun = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().evals.get(requireParam(ctx.params, "id")));
+};
+var deleteEvalRun = async (request, ctx) => {
+  const runId = requireParam(ctx.params, "id");
+  const result = await ctx.projectClient().evals.delete(runId);
+  await audit2(request, ctx, "eval_run.delete", { runId });
+  return json(200, result);
+};
+var listEvalResults = async (request, ctx) => {
+  return json(
+    200,
+    await ctx.projectClient().evals.results(requireParam(ctx.params, "id"), {
+      page: toInt(request.query.page),
+      limit: toInt(request.query.limit),
+      ...request.query.failed === "true" ? { failed: true } : {}
+    })
+  );
+};
+var cancelEvalRun = async (request, ctx) => {
+  const runId = requireParam(ctx.params, "id");
+  const run = await ctx.projectClient().evals.cancel(runId);
+  await audit2(request, ctx, "eval_run.cancel", { runId });
+  return json(200, run);
+};
+
+// src/routes/observe.ts
+var getBudget = async (_request, ctx) => {
+  return json(200, await ctx.projectClient().observe.budget());
+};
+var getUsage = async (request, ctx) => {
+  const source = request.query.source;
+  return json(
+    200,
+    await ctx.projectClient().observe.usage({
+      days: toInt(request.query.days),
+      ...request.query.agentId ? { agentId: request.query.agentId } : {},
+      ...source ? { source } : {}
+    })
+  );
+};
+
 // src/runtime.ts
 function resolveCapabilities(capabilities) {
   return {
@@ -1903,7 +2650,13 @@ function resolveCapabilities(capabilities) {
     auditLogs: capabilities?.auditLogs ?? false,
     architect: capabilities?.architect ?? false,
     workflowsWrite: capabilities?.workflowsWrite ?? false,
-    messages: capabilities?.messages ?? false
+    messages: capabilities?.messages ?? false,
+    secrets: capabilities?.secrets ?? false,
+    restToolSources: capabilities?.restToolSources ?? false,
+    deploy: capabilities?.deploy ?? false,
+    traces: capabilities?.traces ?? false,
+    evals: capabilities?.evals ?? false,
+    observe: capabilities?.observe ?? false
   };
 }
 function buildRoutes(capabilities) {
@@ -1925,6 +2678,9 @@ function buildRoutes(capabilities) {
     // (powered by Gemini Live). Mints a ticket only; the host's own
     // frontend opens the WebSocket directly, this runtime never proxies it.
     { method: "POST", pattern: ["voice", "sessions"], handler: createVoiceSession },
+    // Feedback — always on: an end user rates one of their own runs
+    // (Persona refuses ratings on anyone else's).
+    { method: "POST", pattern: ["feedback"], handler: createFeedback },
     // Agents — read-only discovery always on; write ops behind agentsWrite.
     { method: "GET", pattern: ["agents"], handler: listAgents },
     // Files — always on, end-user-scoped uploads.
@@ -2129,8 +2885,128 @@ function buildRoutes(capabilities) {
       { method: "GET", pattern: ["workflows", "runs", ":runId"], handler: getWorkflowRun }
     );
   }
+  if (capabilities.secrets) {
+    routes.push(
+      { method: "GET", pattern: ["secrets"], handler: listSecrets },
+      { method: "POST", pattern: ["secrets"], handler: createSecret },
+      { method: "POST", pattern: ["secrets", "bulk-delete"], handler: bulkDeleteSecrets },
+      { method: "GET", pattern: ["secrets", ":id"], handler: getSecret },
+      { method: "PATCH", pattern: ["secrets", ":id"], handler: updateSecret },
+      { method: "DELETE", pattern: ["secrets", ":id"], handler: deleteSecret },
+      { method: "GET", pattern: ["secrets", ":id", "usage"], handler: getSecretUsage }
+    );
+  }
+  if (capabilities.restToolSources) {
+    routes.push(
+      { method: "GET", pattern: ["rest-tool-sources"], handler: listRestToolSources },
+      { method: "POST", pattern: ["rest-tool-sources"], handler: createRestToolSource },
+      {
+        method: "POST",
+        pattern: ["rest-tool-sources", "bulk-delete"],
+        handler: bulkDeleteRestToolSources
+      },
+      { method: "GET", pattern: ["rest-tool-sources", ":id"], handler: getRestToolSource },
+      { method: "PATCH", pattern: ["rest-tool-sources", ":id"], handler: updateRestToolSource },
+      { method: "DELETE", pattern: ["rest-tool-sources", ":id"], handler: deleteRestToolSource },
+      {
+        method: "GET",
+        pattern: ["rest-tool-sources", ":id", "usage"],
+        handler: getRestToolSourceUsage
+      },
+      { method: "POST", pattern: ["rest-tool-sources", ":id", "test"], handler: testRestToolSource }
+    );
+  }
+  if (capabilities.deploy) {
+    routes.push(
+      { method: "GET", pattern: ["agents", ":id", "versions"], handler: listAgentVersions },
+      { method: "POST", pattern: ["agents", ":id", "versions"], handler: publishAgentVersion },
+      // Before `versions/:version`, which would otherwise capture "stats".
+      {
+        method: "GET",
+        pattern: ["agents", ":id", "versions", "stats"],
+        handler: agentVersionStats
+      },
+      {
+        method: "GET",
+        pattern: ["agents", ":id", "versions", ":version"],
+        handler: getAgentVersion
+      },
+      {
+        method: "GET",
+        pattern: ["agents", ":id", "versions", ":version", "diff"],
+        handler: diffAgentVersion
+      },
+      { method: "GET", pattern: ["agents", ":id", "deployments"], handler: getAgentDeployments },
+      {
+        method: "PUT",
+        pattern: ["agents", ":id", "deployments", "policy"],
+        handler: setAgentServePolicy
+      },
+      {
+        method: "POST",
+        pattern: ["agents", ":id", "deployments", ":environment"],
+        handler: deployAgentVersion
+      },
+      {
+        method: "POST",
+        pattern: ["agents", ":id", "deployments", ":environment", "rollback"],
+        handler: rollbackAgentDeployment
+      }
+    );
+  }
+  if (capabilities.traces) {
+    routes.push(
+      { method: "GET", pattern: ["traces"], handler: listTraces },
+      { method: "GET", pattern: ["traces", ":id"], handler: getTrace },
+      { method: "GET", pattern: ["traces", ":id", "feedback"], handler: getTraceFeedback },
+      { method: "GET", pattern: ["traces", ":id", "replay"], handler: getReplayPlan },
+      { method: "POST", pattern: ["traces", ":id", "replay"], handler: replayTrace },
+      { method: "GET", pattern: ["traces", ":id", "replays"], handler: listTraceReplays }
+    );
+  }
+  if (capabilities.evals) {
+    routes.push(
+      { method: "GET", pattern: ["datasets"], handler: listDatasets },
+      { method: "POST", pattern: ["datasets"], handler: createDataset },
+      { method: "GET", pattern: ["datasets", ":id"], handler: getDataset },
+      { method: "PATCH", pattern: ["datasets", ":id"], handler: updateDataset },
+      { method: "DELETE", pattern: ["datasets", ":id"], handler: deleteDataset },
+      { method: "GET", pattern: ["datasets", ":id", "items"], handler: listDatasetItems },
+      { method: "POST", pattern: ["datasets", ":id", "items"], handler: addDatasetItems },
+      {
+        method: "POST",
+        pattern: ["datasets", ":id", "items", "from-trace"],
+        handler: addDatasetItemFromTrace
+      },
+      {
+        method: "PATCH",
+        pattern: ["datasets", ":id", "items", ":itemId"],
+        handler: updateDatasetItem
+      },
+      {
+        method: "DELETE",
+        pattern: ["datasets", ":id", "items", ":itemId"],
+        handler: deleteDatasetItem
+      },
+      { method: "GET", pattern: ["eval-runs"], handler: listEvalRuns },
+      { method: "POST", pattern: ["eval-runs"], handler: startEvalRun },
+      // Before `eval-runs/:id`, which would otherwise capture "compare".
+      { method: "GET", pattern: ["eval-runs", "compare"], handler: compareEvalRuns },
+      { method: "GET", pattern: ["eval-runs", ":id"], handler: getEvalRun },
+      { method: "DELETE", pattern: ["eval-runs", ":id"], handler: deleteEvalRun },
+      { method: "GET", pattern: ["eval-runs", ":id", "results"], handler: listEvalResults },
+      { method: "POST", pattern: ["eval-runs", ":id", "cancel"], handler: cancelEvalRun }
+    );
+  }
+  if (capabilities.observe) {
+    routes.push(
+      { method: "GET", pattern: ["observe", "budget"], handler: getBudget },
+      { method: "GET", pattern: ["observe", "usage"], handler: getUsage }
+    );
+  }
   return routes;
 }
+var ADMIN_CAPABILITIES = ["deploy", "traces", "evals", "observe"];
 function resolveMode(options) {
   if (options.mode) return options.mode;
   return process.env.NODE_ENV === "development" ? "development" : "production";
@@ -2177,6 +3053,15 @@ function createRuntime(options) {
       }
     );
   }
+  if (options.webhooks) {
+    if (!options.webhooks.secret) throw new Error('createRuntime: "webhooks.secret" is required');
+    routes.push({
+      method: "POST",
+      pattern: ["webhooks", "persona"],
+      handler: createWebhookRoute(),
+      requiresAuth: false
+    });
+  }
   const mode = resolveMode(options);
   const heartbeatIntervalMs = options.heartbeatIntervalMs ?? 15e3;
   const runGraceMs = options.runGraceMs ?? DEFAULT_RUN_GRACE_MS;
@@ -2195,6 +3080,18 @@ function createRuntime(options) {
     mountPath: options.mountPath ?? "",
     enabledCapabilities: enabledCaps.length ? enabledCaps : ["(core only)"]
   });
+  const adminCaps = enabledCaps.filter((c) => ADMIN_CAPABILITIES.includes(c));
+  if (adminCaps.length) {
+    logger.warn(
+      "Project-wide admin capabilities are on: they act for the whole Project, not the resolved user. Serve them only behind a resolveUser that admits your own team.",
+      {
+        capabilities: adminCaps,
+        scopes: Object.fromEntries(
+          adminCaps.map((c) => [c, CAPABILITY_SCOPES[c]])
+        )
+      }
+    );
+  }
   logger.trace("runtime config", {
     baseUrl: options.baseUrl,
     hasHooks: !!options.hooks,
@@ -2327,6 +3224,7 @@ function createRuntime(options) {
       }
       const resolvedRequest = { ...request, userId };
       const client = createClientForRequest(options, userId, logger);
+      let projectClient;
       const routeLogger = logger.child("route");
       logger.debug("handler start", {
         method: request.method,
@@ -2345,7 +3243,15 @@ function createRuntime(options) {
         logger: routeLogger,
         restToolsManifest: options.restToolsManifest,
         rcpManifest: options.rcpManifest,
-        channels: options.channels
+        channels: options.channels,
+        projectClient: () => userId === null ? client : projectClient ??= createClientForRequest(options, null, logger),
+        webhooks: options.webhooks,
+        versioning: {
+          selectVersion: options.selectVersion,
+          defaultEnvironment: options.defaultEnvironment,
+          allowClientVersionSelection: options.allowClientVersionSelection
+        },
+        forwardTraceparent: options.forwardTraceparent ?? true
       });
       const durationMs = Date.now() - startMs;
       logger.info("handle succeeded", {
@@ -2405,6 +3311,7 @@ function createRuntime(options) {
   };
 }
 export {
+  CAPABILITY_SCOPES,
   RUNTIME_VERSION,
   RuntimeHttpError,
   createRuntime