@k2b/cloud 0.45.0 → 0.47.0

package/src/ai/tools.ts

@@ -4,6 +4,7 @@ import type { z } from "zod";
 import type { CapabilityActionCallReview } from "../contracts/capabilities";
 import type { RequestActor } from "../server";
 import { aiToolNeedsApproval } from "./approvals";
+import { resolveAiToolResultMaxChars } from "./tool-result-budget";
 import type {
   AiApprovalTarget,
   AiDataBoundary,
@@ -64,6 +65,8 @@ export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** A validated result snapshot while a server tool is still running. */
+          reportResult?: (result: z.infer<TOutput>) => Promise<void>;
           /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
           requestApprovalFor?: (message: string, target: AiApprovalTarget, review?: CapabilityActionCallReview) => Promise<boolean>;
           /** Relays a decision for an effect another platform component consumes and executes. */
@@ -117,6 +120,8 @@ export type AiToolPreparationContext = {
   locale?: string;
   timeZone?: string;
   reportToolProgress?: (callId: string, message: string) => Promise<void>;
+  reportToolResult?: (callId: string, result: unknown) => Promise<void>;
+  maxToolResultChars?: number;
   /** Uses the approved snapshot immediately before the tool executes its effect. */
   consumeApproval?: (approvalCallId: string, input: unknown) => Promise<AiApprovalUse>;
   /** Links a relayed decision to the record the effect owner will consume. */
@@ -241,6 +246,15 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
           locale: input.locale,
           timeZone: input.timeZone,
           reportProgress: callId && report ? (message) => report(callId, message) : undefined,
+          reportResult:
+            callId && input.reportToolResult
+              ? async (result) => {
+                  const validated = tool.def.outputSchema.parse(result);
+                  const maximum = input.maxToolResultChars ?? resolveAiToolResultMaxChars({ configuredMaxChars: Number.MAX_SAFE_INTEGER });
+                  if (JSON.stringify(validated).length > maximum) throw new Error("AI_TOOL_INTERIM_RESULT_TOO_LARGE");
+                  await input.reportToolResult!(callId, validated);
+                }
+              : undefined,
           reportWebsiteReceipts:
             callId && input.reportWebsiteReceipts ? (receipts) => input.reportWebsiteReceipts!(callId, receipts) : undefined,
         });

package/src/ai/types.ts

@@ -313,6 +313,7 @@ export type AiStoredMessage = {
     toolPresentations?: Record<string, AiToolPresentation>;
     toolReviews?: Record<string, AiStoredActionReview>;
     toolChecks?: Record<string, AiActionCheck>;
+    toolInterimResults?: Record<string, unknown>;
     /** How the person decided an approval; `expired` when the turn ended while it still waited. */
     toolOutcomes?: Record<string, "rejected" | "approved" | "expired">;
     /** Requests a website approval let through, by tool call and then by `AiWebsiteReceipt.index`. */
@@ -1159,6 +1160,8 @@ export type AiToolRuntime<TInput extends z.ZodType = z.ZodType, TOutput extends
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** A validated result snapshot while a server tool is still running. */
+          reportResult?: (result: z.infer<TOutput>) => Promise<void>;
           /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
           requestApprovalFor?: (message: string, target: AiApprovalTarget, review?: CapabilityActionCallReview) => Promise<boolean>;
           /** Relays a decision for an effect another platform component consumes and executes. */

package/src/api/admin-app-keys.ts

@@ -0,0 +1,66 @@
+import type { MiddlewareHandler } from "hono";
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { validateAppKeyAppId } from "../app-key";
+import { type AuthContext, auth, respond, v } from "../server";
+import { noTransform } from "../server/middleware/no-transform";
+import { appKeys } from "../services/app-keys";
+
+const appId = z.string().refine((value) => {
+  try {
+    validateAppKeyAppId(value);
+    return true;
+  } catch {
+    return false;
+  }
+}, "Invalid or reserved app ID");
+const params = z.object({ appId });
+const pagination = z.object({
+  page: z.coerce.number().int().min(1).default(1),
+  perPage: z.coerce.number().int().min(1).max(500).default(100),
+});
+const input = z
+  .object({ publicKey: z.string().length(43), name: z.string().trim().min(1).max(120).optional(), expiresAt: z.iso.datetime().optional() })
+  .strict();
+
+export const createAdminAppKeyRoutes = (
+  authenticate: MiddlewareHandler<AuthContext> = auth.requireRole("admin"),
+  service: typeof appKeys = appKeys,
+) =>
+  new Hono<AuthContext>()
+    .use("*", noTransform())
+    .use(authenticate)
+    .use("*", async (c, next) => {
+      c.header("Cache-Control", "no-store");
+      if (["POST", "DELETE"].includes(c.req.method)) return auth.requireOAuthScope("write", "admin")(c, next);
+      return next();
+    })
+    .get(
+      "/keys",
+      describeRoute({ tags: ["App keys"], summary: "List apps with enrolled keys and the installation ID" }),
+      v("query", pagination),
+      (c) => respond(c, () => service.listApps({ actor: c.get("user"), ...c.req.valid("query") })),
+    )
+    .get(
+      "/:appId/keys",
+      describeRoute({ tags: ["App keys"], summary: "List app public keys and lifecycle metadata" }),
+      v("param", params),
+      v("query", pagination),
+      (c) => respond(c, () => service.list({ actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("query") })),
+    )
+    .post(
+      "/:appId/keys",
+      describeRoute({ tags: ["App keys"], summary: "Idempotently enroll an Ed25519 public key; at most two active keys per app" }),
+      v("param", params),
+      v("json", input),
+      (c) => respond(c, () => service.register({ actor: c.get("user"), ...c.req.valid("param"), ...c.req.valid("json") })),
+    )
+    .delete(
+      "/:appId/keys/:keyId",
+      describeRoute({ tags: ["App keys"], summary: "Idempotently revoke an app key" }),
+      v("param", params.extend({ keyId: z.uuid() })),
+      (c) => respond(c, () => service.revoke({ actor: c.get("user"), ...c.req.valid("param") })),
+    );
+
+export default createAdminAppKeyRoutes();

package/src/api/admin-core-settings.ts

@@ -27,6 +27,7 @@ import { SETTINGS_MAP, validateSettingValue } from "../services/settings/default
 import { assertGeoBudgetPair, GeoBudgetSettingError } from "../services/settings/geo-budget";
 import { invalidateSettingsCacheForAdmin } from "../services/settings/store";
 import { assertSettingVersions } from "../services/settings/versions";
+import { adminSettingsEnvRoutes } from "./admin-settings-env";
 
 const BulkUpdatesSchema = z
   .object({
@@ -72,6 +73,7 @@ const invalidateCommittedSettings = async (keys: readonly string[]): Promise<voi
 const liveSettingKeys = async () => (await listApps()).flatMap((app) => [...(app.settingKeys ?? [])]);
 
 const app = new Hono<AuthContext>()
+  .route("/env", adminSettingsEnvRoutes)
   .get("/web-vitals", auth.requireRole("admin"), async (c) =>
     c.json({ enabled: (await settings.get("observability.web_vitals.enabled")) === true }),
   )

package/src/api/admin-identity.ts

@@ -86,7 +86,10 @@ type IdentityAdminDependencies = {
   status: typeof getIdentitySigningKeyStatus;
   rewrap: typeof rewrapIdentitySigningKeys;
   revoke: typeof revokeIdentitySigningKey;
-  serviceAccounts: Pick<typeof serviceAccounts, "getOrCreateResourceBound" | "createStandalone" | "listStandalone" | "get" | "setStatus">;
+  serviceAccounts: Pick<
+    typeof serviceAccounts,
+    "getByResource" | "getOrCreateResourceBound" | "createStandalone" | "listStandalone" | "get" | "setStatus"
+  >;
   credentials: Pick<
     typeof serviceAccountCredentials,
     "createResourceApiToken" | "createStandaloneApiToken" | "getOverview" | "listOverview" | "revoke"
@@ -151,6 +154,29 @@ export const createAdminIdentityRoutes = (
           }),
         ),
     )
+    .patch(
+      "/workloads/:appId",
+      describeRoute({ tags: ["App credentials"], summary: "Enable or disable app workload issuance and calls across all instances" }),
+      v("param", WorkloadAppParamsSchema),
+      v("json", ServiceAccountStatusInputSchema),
+      async (c) =>
+        respond(c, async () => {
+          const { appId } = c.req.valid("param");
+          const { status } = c.req.valid("json");
+          const account = await service.serviceAccounts.getByResource({ appId, resourceType: "cloud.app", resourceId: appId });
+          if (!account) return fail(err.notFound("Workload service account"));
+          const updated = await service.serviceAccounts.setStatus({ id: account.id, status });
+          if (!updated.ok) return updated;
+          await service.audit.record({
+            action: status === "disabled" ? "service_account.disable" : "service_account.enable",
+            outcome: "allowed",
+            actor: auditActor(c.get("user")),
+            target: { type: "service_account", id: account.id, label: account.name },
+            metadata: { appId, serviceAccountId: account.id, status },
+          });
+          return ok({ appId, status });
+        }),
+    )
     .post(
       "/workloads/:appId/credentials",
       describeRoute({ tags: ["App credentials"], summary: "Create an app-bound credential; return its token once" }),

package/src/api/admin-settings-env.ts

@@ -0,0 +1,120 @@
+import { Hono } from "hono";
+import { describeRoute } from "hono-openapi";
+import { z } from "zod";
+import { readBoundedJson } from "../_internal/bounded-json";
+import { getApp, listApps } from "../_internal/registry";
+import { EnvSettingStatusSchema, type EnvSettingsProcessSchema, EnvSettingsStatusSchema } from "../contracts/settings-env";
+import { type AuthContext, auth, jsonResponse, requiresAdmin, setRequestTimeout, v } from "../server";
+import { listGatewayRouteSnapshots } from "../services/gateway";
+import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
+import { issueInvocationToken } from "../services/identity/issue-invocation";
+import { withActiveIdentitySigner } from "../services/identity/key-ring";
+import { readEnvSettingsStatus } from "../services/settings/env-status";
+import { settingsInvocationOperation } from "./settings-ops";
+
+const reply = z.object({ settings: z.array(EnvSettingStatusSchema) });
+export const adminSettingsEnvRoutes = new Hono<AuthContext>()
+  .use("*", auth.requireRole("admin"))
+  .use("*", auth.requireOAuthScope("admin"))
+  .get(
+    "/status",
+    describeRoute({
+      tags: ["Administration"],
+      summary: "Check environment-backed settings without returning values",
+      ...requiresAdmin,
+      responses: { 200: jsonResponse(EnvSettingsStatusSchema, "Migration status") },
+    }),
+    async (c) => {
+      setRequestTimeout(c, 240);
+      const signal = AbortSignal.any([c.req.raw.signal, AbortSignal.timeout(230_000)]);
+      try {
+        const processes: z.infer<typeof EnvSettingsProcessSchema>[] = [
+          { appId: "core", status: "ok", settings: await readEnvSettingsStatus() },
+        ];
+        for (const app of await listApps()) {
+          if (app.id === "core") continue;
+          try {
+            const response = await requestSettings(app, "GET", "env", auth.getAuthority(c), undefined, signal);
+            const data = await readBoundedJson(response, 4 * 1024 * 1024);
+            if (!response.ok || !data.ok) throw new Error("Unavailable");
+            processes.push({ appId: app.id, status: "ok", settings: reply.parse(data.data).settings });
+          } catch {
+            processes.push({ appId: app.id, status: "unavailable", settings: [] });
+          }
+        }
+        const gateways = await listGatewayRouteSnapshots();
+        if (!gateways.length) processes.push({ appId: "gateway", status: "unavailable", settings: [] });
+        for (const gateway of gateways) {
+          const parsed = z.array(EnvSettingStatusSchema).safeParse(gateway.envSettings);
+          processes.push({
+            appId: "gateway",
+            instanceId: gateway.instanceId,
+            sampledAt: gateway.updatedAt,
+            status: parsed.success ? "ok" : "unavailable",
+            settings: parsed.success ? parsed.data : [],
+          });
+        }
+        return c.json(
+          { needsAttention: processes.some((p) => p.status !== "ok" || p.settings.some((s) => s.needsAttention)), processes },
+          200,
+          { "cache-control": "no-store" },
+        );
+      } finally {
+        setRequestTimeout(c, 10);
+      }
+    },
+  )
+  .put("/:appId/:key", v("json", z.object({ value: z.unknown(), replaceUnreadable: z.boolean().optional() })), async (c) => {
+    const app = await getApp(c.req.param("appId") ?? "");
+    if (!app) return c.json({ message: "App is not registered; start it before changing its settings" }, 404);
+    try {
+      const response = await requestSettings(
+        app,
+        "PUT",
+        c.req.param("key") ?? "",
+        auth.getAuthority(c),
+        c.req.valid("json"),
+        c.req.raw.signal,
+      );
+      const body = await readBoundedJson(response, 4 * 1024 * 1024);
+      if (!body.ok) throw new Error("Unavailable");
+      return Response.json(body.data, { status: response.status, headers: { "cache-control": "no-store" } });
+    } catch {
+      return c.json({ message: "Application settings unavailable" }, 502);
+    }
+  });
+
+const requestSettings = async (
+  app: { id: string; baseUrl: string },
+  method: "GET" | "PUT",
+  key: string,
+  authority: Parameters<typeof invocationAuthorityFromRequest>[0],
+  body: unknown,
+  parentSignal: AbortSignal,
+) => {
+  const signal = AbortSignal.any([parentSignal, AbortSignal.timeout(5_000)]);
+  const signed = await withActiveIdentitySigner(
+    "invocation",
+    (signer, db) =>
+      issueInvocationToken(
+        {
+          targetAppId: app.id,
+          callingAppId: "core",
+          operation: settingsInvocationOperation(method, key),
+          schemaHash: null,
+          authority: invocationAuthorityFromRequest(authority),
+          signer,
+          issuer: signer.issuer,
+        },
+        { db, groupsAdmin: signer.groupsAdmin, signal },
+      ),
+    { signal, timeoutMs: 5_000 },
+  );
+  return fetch(new URL(`/_internal/settings/${encodeURIComponent(key)}`, app.baseUrl), {
+    method,
+    headers: { authorization: `Bearer ${signed.token}`, "content-type": "application/json" },
+    body: body === undefined ? undefined : JSON.stringify(body),
+    signal,
+    redirect: "manual",
+  });
+};

package/src/api/capabilities.ts

@@ -3,14 +3,14 @@ import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { type CatalogSubscription, projectAppEventCatalog, readCatalogSubscriptions } from "../_internal/app-event-catalog";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { isPersonVisibleCapabilityQuery, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import {
   capabilityActionReceiptIssues,
   capabilityActionReviewIssues,
   capabilityQueryChecksActionOutcome,
 } from "../_internal/capability-reviews";
 import { capabilityTimeoutMs, createCapabilityDeadline, withCapabilityRequestTimeout } from "../_internal/capability-timeout";
-import { getCapability, listApps } from "../_internal/registry";
+import { getApp, getCapability, listApps } from "../_internal/registry";
 import { resolveCommandLink } from "../capabilities/command-link";
 import {
   type CapabilityClaimScope,
@@ -59,12 +59,13 @@ import { AppAccessDeniedError, appAccessDeniedBody } from "../server/middleware/
 import { oauthScopeByOperation } from "../server/middleware/auth";
 import { noTransform } from "../server/middleware/no-transform";
 import { hasOAuthScope } from "../server/oauth-scope";
+import { ratelimit } from "../server/ratelimit";
 import { appAccessAuthority, canUseApp } from "../services/app-access";
 import { discoverableApps } from "../services/app-discovery";
 import { authorityFromParentInvocation, invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { capabilityInvocationOperation } from "../services/identity/invocation-operations";
 import type { CloudInvocationClaims, InvocationAuthority } from "../services/identity/invocation-token";
-import { normalizeInvocationRequestId } from "../services/identity/invocation-token";
+import { normalizeInvocationRequestId, signAppQueryInvocation } from "../services/identity/invocation-token";
 import { issueInvocationToken as signInvocationToken } from "../services/identity/issue-invocation";
 import { withActiveIdentitySigner } from "../services/identity/key-ring";
 import {
@@ -73,6 +74,7 @@ import {
   nestedInvocationLeases,
   nestedSourceDeadline,
 } from "../services/identity/nested-invocation";
+import type { AuthenticatedWorkload } from "../services/identity/workload-auth";
 import { logger } from "../services/logging";
 import { withMandateIssueAuthority } from "../services/mandates";
 import * as settings from "../services/settings";
@@ -80,6 +82,9 @@ import { resolveAppPresentation } from "../shared/app-presentation";
 import { capabilityMessages } from "../shared/capability-messages";
 import { dispatchCapabilityStream, sealCapabilityStream } from "./capability-streams";
 
+// Approved reader-check budget, shared across targets for each calling application.
+export const APP_QUERY_REQUESTS_PER_MINUTE = 1_501;
+const appQueryLimit = ratelimit({ id: "app-queries", limit: APP_QUERY_REQUESTS_PER_MINUTE, windowSecs: 60 });
 const log = logger("capabilities");
 const DEFAULT_CATALOG_LIMIT = 10;
 const MAX_CATALOG_LIMIT = 25;
@@ -114,6 +119,7 @@ const CapabilityCatalogQuerySchema = z
 export type CapabilityRouteDependencies = {
   listApps?: () => Promise<AppRegistryEntry[]>;
   eventSubscriptions?: () => Promise<CatalogSubscription[]>;
+  getApp?: (appId: string) => Promise<AppRegistryEntry | null>;
   getCapability?: (appId: string) => Promise<CapabilityRegistryEntry | null>;
   fetch?: (input: string | URL | Request, init?: RequestInit) => Promise<Response>;
   authenticate?: MiddlewareHandler<AuthContext>;
@@ -122,12 +128,15 @@ export type CapabilityRouteDependencies = {
   withMandateIssueAuthority?: typeof withMandateIssueAuthority;
   queryTimeoutMs?: number;
   actionTimeoutMs?: number;
+  checkAppQueryRate?: (appId: string) => Promise<{ limited: boolean }>;
   reviewTimeoutMs?: number;
   appUrl?: () => Promise<string>;
 };
 
 export type CapabilityDispatchDependencies = Pick<
   CapabilityRouteDependencies,
+  | "checkAppQueryRate"
+  | "getApp"
   | "getCapability"
   | "fetch"
   | "queryTimeoutMs"
@@ -223,7 +232,7 @@ export const loadCapabilityCatalogPage = async (
       appName: presentedEntry.name,
       appIcon: capability.appIcon,
       appDescription: presentedEntry.description,
-      manifest,
+      manifest: { ...manifest, queries: manifest.queries.filter(isPersonVisibleCapabilityQuery) },
       ...(manifest.events ? { events: projectAppEventCatalog(manifest, manifest.events.length ? await loadSubscribers() : []) } : {}),
     };
     const projectedBytes = new TextEncoder().encode(JSON.stringify(projected)).byteLength;
@@ -251,11 +260,17 @@ const errorResponse = (code: string, message: string, status: number, details?:
   status,
 });
 
-const capabilityJsonResponse = (body: unknown, status: number): Response =>
-  Response.json(body, {
+const capabilityJsonResponse = (body: unknown, status: number): Response => {
+  const limited =
+    status === 429 ? z.object({ details: z.object({ retryAfter: z.number().int().positive().safe() }) }).safeParse(body) : null;
+  return Response.json(body, {
     status,
-    headers: { "content-type": "application/json" },
+    headers: {
+      "content-type": "application/json",
+      ...(limited?.success ? { "retry-after": String(limited.data.details.retryAfter) } : {}),
+    },
   });
+};
 
 export type CapabilityDispatchParams = {
   /** Trusted Core continuation binding; never read from client headers. */
@@ -276,6 +291,8 @@ export type CapabilityDispatchParams = {
   assistantTurn?: { conversationId: string; turnId: string };
   /** Core-only absolute child deadline; cannot be extended by the application. */
   deadline?: number;
+  /** Core-only authenticated workload. Never populated from request JSON. */
+  workload?: AuthenticatedWorkload;
   mandate?: MandatedCapabilityAuthority;
   callingAppId?: string;
   /** Internal observation only: called immediately before attempting the app request. */
@@ -342,6 +359,43 @@ const runCapabilityDispatch = async (
     );
     return error;
   }
+  if ("appOnly" in operation && operation.appOnly !== undefined && !params.workload)
+    return errorResponse("FORBIDDEN", "App authority required for this query", 403);
+  if (params.workload) {
+    if (
+      params.authority ||
+      params.mandate ||
+      params.parentInvocation ||
+      params.review ||
+      params.kind !== "queries" ||
+      !("appOnly" in operation) ||
+      operation.appOnly !== true ||
+      operation.stream
+    )
+      return errorResponse("FORBIDDEN", "App caller is not allowed for this query", 403);
+    try {
+      const caller = await deadline.wait(() => (params.dependencies?.getApp ?? getApp)(params.workload!.appId));
+      if (!caller) return errorResponse("APP_UNAVAILABLE", "Calling app registry entry unavailable", 503);
+      if (!caller.platformPermissions?.includes("resources:readers"))
+        return errorResponse("APP_QUERY_NOT_ADMITTED", "App caller does not declare resources:readers", 403);
+    } catch {
+      deadline.check();
+      return errorResponse("APP_UNAVAILABLE", "App registry unavailable", 503);
+    }
+    try {
+      if (
+        (
+          await deadline.wait(() =>
+            (params.dependencies?.checkAppQueryRate ?? ((appId) => appQueryLimit.check(appId)))(params.workload!.appId),
+          )
+        ).limited
+      )
+        return errorResponse("RATE_LIMITED", "App query rate limit exceeded; retry after one minute", 429);
+    } catch {
+      deadline.check();
+      return errorResponse("APP_UNAVAILABLE", "App query rate limiter unavailable", 503);
+    }
+  }
   if (params.review && (params.kind !== "actions" || !("review" in operation) || operation.review !== true)) {
     const error = errorResponse(
       "CAPABILITY_NOT_FOUND",
@@ -488,6 +542,33 @@ const runCapabilityDispatch = async (
           });
         })()
       : await (async () => {
+          if (params.workload) {
+            const workload = params.workload;
+            return deadline.wait(() =>
+              (params.dependencies?.withActiveSigner ?? withActiveIdentitySigner)(
+                "invocation",
+                async (signer) => {
+                  deadline.check();
+                  const signed = await signAppQueryInvocation({
+                    workload,
+                    targetAppId: params.appId,
+                    capabilityId: params.capabilityId,
+                    schemaHash: operation.schemaHash,
+                    input: input.data,
+                    requestId,
+                    signer,
+                  });
+                  observed.invocationId = signed.claims.jti;
+                  return new Headers({
+                    "content-type": "application/json",
+                    accept: "application/json",
+                    authorization: `Bearer ${signed.token}`,
+                  });
+                },
+                { signal, timeoutMs: deadline.remainingMs() },
+              ),
+            );
+          }
           if (!params.authority) throw new Error("Resolved request authority is required for Cloud invocation issuance");
           const authority = params.authority;
           const signed = await deadline.wait(() =>
@@ -665,12 +746,15 @@ const runCapabilityDispatch = async (
   try {
     params.onUpstreamAttempt?.();
     const fetchResponse = () =>
-      fetchUpstream(`${entry.endpoint}/${params.kind}/${encodeURIComponent(params.capabilityId)}${params.review ? "/review" : ""}`, {
-        method: "POST",
-        headers,
-        body: requestBody,
-        signal,
-      });
+      fetchUpstream(
+        `${entry.endpoint}/${params.workload ? "app-queries" : params.kind}/${encodeURIComponent(params.capabilityId)}${params.review ? "/review" : ""}`,
+        {
+          method: "POST",
+          headers,
+          body: requestBody,
+          signal,
+        },
+      );
     // A read may be released at its deadline; Action effects retain their existing uncertainty handling.
     response = params.kind === "queries" || params.review ? await deadline.wait(fetchResponse) : await fetchResponse();
   } catch (error) {
@@ -895,12 +979,12 @@ export const dispatchCapability = async (params: CapabilityDispatchParams): Prom
         origin: params.origin,
         invocationId: observed.invocationId,
         parentInvocationId: params.parentInvocation?.jti,
-        viaAppId: params.parentInvocation ? params.callingAppId : undefined,
+        viaAppId: params.workload?.appId ?? (params.parentInvocation ? params.callingAppId : undefined),
         appId: params.appId,
         capability: `${params.appId}.${params.capabilityId}`,
         kind: params.kind === "queries" ? "query" : "action",
         destructive: observed.destructive,
-        actorKind: principal?.type ?? null,
+        actorKind: params.workload ? "app" : (principal?.type ?? null),
         actorId: principal?.id ?? null,
         userId: actor?.kind === "user" ? actor.user.id : (actor?.delegatedUser?.id ?? (principal?.type === "user" ? principal.id : null)),
         accessSubject: subject && subject.id !== principal?.id ? subject : null,

package/src/api/index.ts

@@ -26,6 +26,7 @@ import adminAiProjectsRoutes from "./admin-ai-projects";
 import adminAiQuotaRoutes from "./admin-ai-quotas";
 import adminAiSkillsRoutes from "./admin-ai-skills";
 import adminAiUsageRoutes from "./admin-ai-usage";
+import adminAppKeyRoutes from "./admin-app-keys";
 import adminCoreSettingsRoutes from "./admin-core-settings";
 import adminDirectorySharesRoutes from "./admin-directory-shares";
 import adminGeoRoutes from "./admin-geo";
@@ -106,6 +107,7 @@ const buildCoreApi = (options: CoreApiOptions) => {
     .route("/admin/core/geo", adminGeoRoutes)
     .route("/admin/identity/directory-shares", adminDirectorySharesRoutes)
     .route("/admin/identity", adminIdentityRoutes)
+    .route("/admin/apps", adminAppKeyRoutes)
     .route("/admin/sync", createSyncOpsProxyRoutes())
     .route("/admin/lifecycle", adminLifecycleRoutes)
     .route("/ai/approval-preferences", approvalPreferenceRoutes)
@@ -133,6 +135,7 @@ export const createCoreApiRouter = (options: CoreApiOptions) => {
   return { api };
 };
 
+export { createAdminAppKeyRoutes } from "./admin-app-keys";
 export { createAppAccessRoutes } from "./app-access";
 export {
   CLOUD_MCP_PATH,

package/src/api/mcp.ts

@@ -16,7 +16,7 @@ import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { type CatalogSubscription, projectAppEventCatalog, readEventCatalogSubscriptions } from "../_internal/app-event-catalog";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
+import { isPersonVisibleCapabilityQuery, resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { capabilitySentenceText } from "../_internal/capability-sentences";
 import { withCapabilityRequestTimeout } from "../_internal/capability-timeout";
 import {
@@ -311,7 +311,9 @@ const orderedCapabilityEntries = function* (app: CapabilityRegistryEntry): Gener
   for (const operation of [...app.manifest.actions].sort((left, right) => left.localId.localeCompare(right.localId))) {
     yield { app, kind: "actions", operation };
   }
-  for (const operation of [...app.manifest.queries].sort((left, right) => left.localId.localeCompare(right.localId))) {
+  for (const operation of app.manifest.queries
+    .filter(isPersonVisibleCapabilityQuery)
+    .sort((left, right) => left.localId.localeCompare(right.localId))) {
     yield { app, kind: "queries", operation };
   }
 };

package/src/api/settings-ops.ts

@@ -0,0 +1,35 @@
+import { Hono } from "hono";
+import { z } from "zod";
+// Concrete modules, not the server barrel: defineApp imports this file, and the barrel imports defineApp.
+import { type AuthContext, auth } from "../server/middleware/auth";
+import { v } from "../server/middleware/validator";
+import { settingsService } from "../services/settings/app";
+import { SETTINGS_MAP } from "../services/settings/defaults";
+import { readEnvSettingsStatus } from "../services/settings/env-status";
+
+export const settingsInvocationOperation = (method: string, key: string) => {
+  try {
+    return `settings.${method === "GET" ? "env" : "set"}:${decodeURIComponent(key)}`;
+  } catch {
+    return "settings.invalid";
+  }
+};
+
+export const createSettingsOpsRoutes = (keys: readonly string[]) =>
+  new Hono<AuthContext>()
+    .use("*", async (c, next) => {
+      if (!c.get("user")?.roles.includes("admin")) return c.json({ message: "Insufficient permissions" }, 403);
+      return next();
+    })
+    .use("*", auth.requireOAuthScope("admin"))
+    .get("/env", async (c) => c.json({ settings: await readEnvSettingsStatus() }, 200, { "cache-control": "no-store" }))
+    .put("/:key", v("json", z.object({ value: z.unknown(), replaceUnreadable: z.boolean().optional() })), async (c) => {
+      const key = c.req.param("key") ?? "";
+      const def = SETTINGS_MAP.get(key);
+      if (!keys.includes(key) || !def || !(def.envBootstrap || def.envFallback))
+        return c.json({ message: "Unknown application setting" }, 400);
+      const body = c.req.valid("json");
+      const result = await settingsService.entry.update({ key, value: body.value, replaceUnreadable: body.replaceUnreadable });
+      if (!result.ok) return c.json({ message: result.error.message }, 400);
+      return c.json({ saved: true });
+    });