@k2b/cloud 0.6.0-rc.0 → 0.7.0

package/src/api/capabilities.ts

@@ -1,20 +1,37 @@
+import { sealCapabilityStream, dispatchCapabilityStream } from "./capability-streams";
+import { CapabilityStreamSchema } from "../contracts/capability-streams";
 import { Hono, type MiddlewareHandler } from "hono";
 import { describeRoute } from "hono-openapi";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
 import { resolveCapabilityManifestPresentation } from "../_internal/capabilities";
 import { getCapability, listApps } from "../_internal/registry";
+import {
+  type CapabilityClaimScope,
+  type CapabilityExecutionStatus,
+  capabilityIdempotencyKeyHash,
+  capabilityRequestHash,
+  capabilityValueMeta,
+  claimCapabilityIdempotency,
+  completeCapabilityClaim,
+  markCapabilityClaimUncertain,
+  recordCapabilityExecution,
+  releaseCapabilityClaim,
+  resolveCapabilityClaim,
+} from "../capabilities/executions";
 import {
   CAPABILITY_FRAMEWORK_ERROR_CODES,
   CAPABILITY_MAX_CATALOG_BYTES,
   CAPABILITY_MAX_REQUEST_BYTES,
   CAPABILITY_MAX_RESULT_BYTES,
+  CAPABILITY_ORIGIN_HEADER,
   CAPABILITY_PROTOCOL_VERSION,
   CapabilityActionReviewSchema,
   type CapabilityCatalog,
   CapabilityCatalogSchema,
   CapabilityErrorSchema,
   CapabilityIdempotencyKeySchema,
+  type CapabilityOrigin,
   capabilityResultJsonSchema,
 } from "../contracts/capabilities";
 import type { AppRegistryEntry, CapabilityRegistryEntry } from "../contracts/registry";
@@ -30,7 +47,9 @@ import {
   requiresAuth,
   v,
 } from "../server";
-import { logger } from "../services";
+import { logger, settings } from "../services";
+import { resolveCommandLink } from "../capabilities/command-link";
+import { CommandRequestSchema, CommandLinkSchema } from "../contracts/commands";
 import { invocationAuthorityFromRequest } from "../services/identity/invocation-authority";
 import { capabilityInvocationOperation } from "../services/identity/invocation-operations";
 import type { InvocationAuthority } from "../services/identity/invocation-token";
@@ -83,6 +102,7 @@ export type CapabilityRouteDependencies = {
   withMandateIssueAuthority?: typeof withMandateIssueAuthority;
   queryTimeoutMs?: number;
   actionTimeoutMs?: number;
+  appUrl?: () => Promise<string>;
 };
 
 export type CapabilityDispatchDependencies = Pick<
@@ -203,12 +223,9 @@ const waitWithin = <T>(value: Promise<T>, signal: AbortSignal): Promise<T> =>
     );
   });
 
-/**
- * Dispatch one already-parsed capability invocation through the live registry.
- * HTTP, CLI, and MCP callers share this exact app lookup, credential forwarding,
- * schema pinning, timeout, and response validation path.
- */
-export const dispatchCapability = async (params: {
+export type CapabilityDispatchParams = {
+  /** Trusted Core continuation binding; never read from client headers. */
+  continuation?: string;
   request: Request;
   kind: "queries" | "actions";
   review?: boolean;
@@ -216,11 +233,37 @@ export const dispatchCapability = async (params: {
   capabilityId: string;
   input: unknown;
   locale?: string;
+  /** Cloud surface this invocation came from; recorded on the execution row. */
+  origin: CapabilityOrigin;
   authority?: RequestAuthority;
   mandate?: MandatedCapabilityAuthority;
   callingAppId?: string;
   dependencies?: CapabilityDispatchDependencies;
-}): Promise<Response> => {
+};
+
+type CapabilityDispatchOutcome = { body: unknown; status: number; replayed?: boolean };
+
+/** Principal resolved while dispatching. A mandate only reveals it during issuance. */
+type CapabilityDispatchObservation = {
+  subject: { type: "user" | "service_account"; id: string } | null;
+  destructive: boolean;
+};
+
+type CapabilityPrincipal = { type: "user" | "service_account"; id: string } | null;
+
+/** Acting principal for the execution row and the idempotency claim scope. A mandate reveals it during issuance. */
+const dispatchPrincipal = (params: CapabilityDispatchParams, observed: CapabilityDispatchObservation): CapabilityPrincipal => {
+  const actor = params.authority?.actor;
+  if (actor?.kind === "user") return { type: "user", id: actor.user.id };
+  if (actor?.kind === "service_account") return { type: "service_account", id: actor.serviceAccount.id };
+  return observed.subject;
+};
+
+const runCapabilityDispatch = async (
+  params: CapabilityDispatchParams,
+  requestId: string,
+  observed: CapabilityDispatchObservation,
+): Promise<CapabilityDispatchOutcome> => {
   const messages = capabilityMessages(params.locale ?? preferredLocale(params.request.headers));
   const registryEntry = params.dependencies?.getCapability ?? getCapability;
   const fetchUpstream = params.dependencies?.fetch ?? globalThis.fetch;
@@ -233,15 +276,16 @@ export const dispatchCapability = async (params: {
       error: error instanceof Error ? error.message : String(error),
     });
     const unavailable = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, messages.registryUnavailable, 503);
-    return capabilityJsonResponse(unavailable.body, unavailable.status);
+    return unavailable;
   }
   if (!entry) {
     const error = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable, messages.appUnavailable({ appId: params.appId }), 503);
-    return capabilityJsonResponse(error.body, error.status);
+    return error;
   }
 
   const operations = params.kind === "queries" ? entry.manifest.queries : entry.manifest.actions;
   const operation = operations.find((candidate) => candidate.localId === params.capabilityId);
+  if (operation && "destructive" in operation) observed.destructive = operation.destructive;
   if (!operation) {
     const label = params.kind === "queries" ? messages.query : messages.action;
     const error = errorResponse(
@@ -249,7 +293,7 @@ export const dispatchCapability = async (params: {
       messages.notFound({ kind: label, reference: `${params.appId}.${params.capabilityId}` }),
       404,
     );
-    return capabilityJsonResponse(error.body, error.status);
+    return error;
   }
   if (params.review && (params.kind !== "actions" || !("review" in operation) || operation.review !== true)) {
     const error = errorResponse(
@@ -257,7 +301,7 @@ export const dispatchCapability = async (params: {
       messages.notFound({ kind: messages.review, reference: `${params.appId}.${params.capabilityId}` }),
       404,
     );
-    return capabilityJsonResponse(error.body, error.status);
+    return error;
   }
 
   const rawIdempotencyKey = params.request.headers.get("idempotency-key");
@@ -265,47 +309,49 @@ export const dispatchCapability = async (params: {
     const action = operation as (typeof entry.manifest.actions)[number];
     if (action.idempotency === "required" && rawIdempotencyKey === null) {
       const error = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyKeyRequired, messages.idempotencyRequired, 400);
-      return capabilityJsonResponse(error.body, error.status);
+      return error;
     }
     if (action.idempotency === "none" && rawIdempotencyKey !== null) {
       const error = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyKeyNotAllowed, messages.idempotencyNotAllowed, 400);
-      return capabilityJsonResponse(error.body, error.status);
+      return error;
     }
   } else if (rawIdempotencyKey !== null) {
     const error = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyKeyNotAllowed, messages.idempotencyOnlyActions, 400);
-    return capabilityJsonResponse(error.body, error.status);
+    return error;
   }
   const idempotencyKey = rawIdempotencyKey === null ? null : CapabilityIdempotencyKeySchema.safeParse(rawIdempotencyKey);
   if (idempotencyKey && !idempotencyKey.success) {
     const error = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, messages.idempotencyInvalid, 400, {
       issues: idempotencyKey.error.issues.map((issue) => ({ message: issue.message })),
     });
-    return capabilityJsonResponse(error.body, error.status);
+    return error;
   }
 
   const inputValidator = schemaValidator(`${operation.schemaHash}:input`, operation.inputSchema);
   if (!inputValidator) {
     const invalid = errorResponse("INVALID_APP_RESPONSE", messages.unsupportedSchema({ appId: params.appId }), 502);
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return invalid;
   }
   const input = inputValidator.safeParse(params.input);
   if (!input.success) {
     const invalid = errorResponse("VALIDATION_FAILED", messages.inputSchemaMismatch, 400, {
       issues: input.error.issues.slice(0, 20).map((issue) => ({ path: issue.path.join("."), message: issue.message })),
     });
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return invalid;
   }
 
+  if (params.mandate && operation.stream) return errorResponse("STREAM_UNSUPPORTED_AUTHORITY", "Streams require an interactive user or service-account request", 403);
+
   let requestBody: string;
   try {
     requestBody = JSON.stringify({ input: input.data });
   } catch {
     const invalid = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, messages.inputNotSerializable, 400);
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return invalid;
   }
   if (new TextEncoder().encode(requestBody).byteLength > CAPABILITY_MAX_REQUEST_BYTES) {
     const invalid = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.validationFailed, messages.requestTooLarge, 400);
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return invalid;
   }
 
   const invocationOperation = capabilityInvocationOperation(params.kind, params.capabilityId, params.review);
@@ -332,17 +378,20 @@ export const dispatchCapability = async (params: {
                     targetAppId: params.appId,
                     operation: invocationOperation,
                     actionApproval: mandate.actionApproval ?? "none",
-                    requestId: normalizeInvocationRequestId(params.request.headers.get("x-request-id")),
+                    input: params.input,
+                    capabilityApproval: "approval" in operation ? (operation.approval ?? "always") : "always",
+                    requestId,
                   },
                   async (mandateAuthority) => {
                     signal.throwIfAborted();
+                    observed.subject = mandateAuthority.subject;
                     return (params.dependencies?.signInvocation ?? signInvocationToken)({
                       targetAppId: params.appId,
                       callingAppId: mandate.ownerAppId,
                       operation: invocationOperation,
                       schemaHash: operation.schemaHash,
                       authority: invocationAuthorityFromMandate(mandateAuthority),
-                      requestId: normalizeInvocationRequestId(params.request.headers.get("x-request-id")),
+                      requestId,
                       signer,
                       issuer: signer.issuer,
                     });
@@ -376,7 +425,7 @@ export const dispatchCapability = async (params: {
                   operation: invocationOperation,
                   schemaHash: operation.schemaHash,
                   authority: invocationAuthorityFromRequest(authority),
-                  requestId: normalizeInvocationRequestId(params.request.headers.get("x-request-id")),
+                  requestId,
                   signer,
                   issuer: signer.issuer,
                 }),
@@ -397,7 +446,7 @@ export const dispatchCapability = async (params: {
         error.status === 409 ? "Mandate revision changed" : "Mandate does not authorize this capability invocation",
         error.status,
       );
-      return capabilityJsonResponse(denied.body, denied.status);
+      return denied;
     }
     if (params.request.signal.aborted || timeout.aborted) {
       const cancelled = params.request.signal.aborted;
@@ -407,15 +456,16 @@ export const dispatchCapability = async (params: {
         cancelled ? 499 : 504,
         { retrySafe: true },
       );
-      return capabilityJsonResponse(failure.body, failure.status);
+      return failure;
     }
     console.error("[capabilities] Invocation issuance failed", { appId: params.appId, operation: invocationOperation });
     const failure = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.internal, messages.issuanceFailed, 500, { retrySafe: true });
-    return capabilityJsonResponse(failure.body, failure.status);
+    return failure;
   }
-  for (const name of ["x-request-id", "traceparent", "tracestate"] as const) {
-    const value =
-      name === "x-request-id" ? normalizeInvocationRequestId(params.request.headers.get(name)) : params.request.headers.get(name);
+  headers.set("x-request-id", requestId);
+  headers.set(CAPABILITY_ORIGIN_HEADER, params.origin);
+  for (const name of ["traceparent", "tracestate"] as const) {
+    const value = params.request.headers.get(name);
     if (value) headers.set(name, value);
   }
   const invocationLocale = preferredLocale(params.request.headers);
@@ -424,11 +474,74 @@ export const dispatchCapability = async (params: {
   headers.set("x-cloud-capability-schema-hash", operation.schemaHash);
   const actionWithoutRetrySafety =
     params.kind === "actions" && !params.review && "idempotency" in operation && operation.idempotency === "none";
-  const outcomeUnknown = (): Response => {
+  const outcomeUnknown = (): CapabilityDispatchOutcome => {
     const unknown = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.actionOutcomeUnknown, messages.actionOutcomeUnknown, 502, {
       retrySafe: false,
     });
-    return capabilityJsonResponse(unknown.body, unknown.status);
+    return unknown;
+  };
+
+  const claimPrincipal = dispatchPrincipal(params, observed);
+  const claimScope: CapabilityClaimScope | null =
+    params.kind === "actions" &&
+    !params.review &&
+    "idempotency" in operation &&
+    operation.idempotency === "required" &&
+    idempotencyKey?.success
+      ? {
+          appId: params.appId,
+          capability: `${params.appId}.${params.capabilityId}`,
+          principal: claimPrincipal ? `${claimPrincipal.type}:${claimPrincipal.id}` : "anonymous",
+          keyHash: capabilityIdempotencyKeyHash(idempotencyKey.data),
+        }
+      : null;
+  if (claimScope) {
+    let claim: Awaited<ReturnType<typeof claimCapabilityIdempotency>>;
+    try {
+      claim = await claimCapabilityIdempotency(claimScope, capabilityRequestHash(input.data));
+    } catch (error) {
+      // Nothing has been forwarded yet, so refusing the call is the safe answer.
+      log.error("Capability idempotency claim failed", {
+        appId: params.appId,
+        capabilityId: params.capabilityId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      return errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.internal, messages.cloudUnavailable, 503, { retrySafe: true });
+    }
+    if (claim.state === "replay") return { body: claim.body, status: claim.status, replayed: true };
+    if (claim.state === "conflict")
+      return errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyConflict, messages.idempotencyConflict, 409);
+    if (claim.state === "in_flight") {
+      return errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyInProgress, messages.idempotencyInProgress, 409, {
+        retrySafe: false,
+      });
+    }
+    if (claim.state === "uncertain") {
+      return errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyUncertain, messages.idempotencyUncertain, 409, { retrySafe: false });
+    }
+    if (claim.state === "not_retained") {
+      return errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.idempotencyUncertain, messages.idempotencyResultNotRetained, 409, {
+        retrySafe: false,
+      });
+    }
+  }
+
+  /**
+   * Resolve the claim once the outcome is known: a definitive success is
+   * replayable, a failure that proves nothing happened frees the key for a
+   * corrected retry, and anything ambiguous freezes the key.
+   */
+  const settle = async (outcome: CapabilityDispatchOutcome, disposition: "succeeded" | "nothing_happened" | "uncertain") => {
+    if (!claimScope) return outcome;
+    await resolveCapabilityClaim(
+      disposition === "succeeded"
+        ? completeCapabilityClaim(claimScope, outcome.status, outcome.body)
+        : disposition === "nothing_happened"
+          ? releaseCapabilityClaim(claimScope)
+          : markCapabilityClaimUncertain(claimScope),
+      claimScope,
+    );
+    return outcome;
   };
 
   let response: Response;
@@ -449,18 +562,18 @@ export const dispatchCapability = async (params: {
       kind: params.kind,
       error: error instanceof Error ? error.message : String(error),
     });
-    if (actionWithoutRetrySafety) return outcomeUnknown();
+    if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");
     if (params.request.signal.aborted) {
       const cancelled = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.requestCancelled, messages.requestCancelled, 499, {
         retrySafe: params.kind === "queries" || ("idempotency" in operation && operation.idempotency === "required"),
       });
-      return capabilityJsonResponse(cancelled.body, cancelled.status);
+      return settle(cancelled, "uncertain");
     }
     if (timeout.aborted) {
       const deadline = errorResponse(CAPABILITY_FRAMEWORK_ERROR_CODES.deadlineExceeded, messages.deadlineExceeded, 504, {
         retrySafe: params.kind === "queries" || ("idempotency" in operation && operation.idempotency === "required"),
       });
-      return capabilityJsonResponse(deadline.body, deadline.status);
+      return settle(deadline, "uncertain");
     }
     const unavailable = errorResponse(
       CAPABILITY_FRAMEWORK_ERROR_CODES.appUnavailable,
@@ -468,28 +581,30 @@ export const dispatchCapability = async (params: {
       503,
       { retrySafe: params.kind === "queries" || ("idempotency" in operation && operation.idempotency === "required") },
     );
-    return capabilityJsonResponse(unavailable.body, unavailable.status);
+    return settle(unavailable, "uncertain");
   }
 
   const upstreamBody = await readBoundedJson(response, CAPABILITY_MAX_RESULT_BYTES);
   if (!upstreamBody.ok) {
-    if (actionWithoutRetrySafety) return outcomeUnknown();
+    if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");
     const code =
       upstreamBody.reason === "too_large"
         ? CAPABILITY_FRAMEWORK_ERROR_CODES.responseTooLarge
         : CAPABILITY_FRAMEWORK_ERROR_CODES.invalidAppResponse;
     const invalid = errorResponse(code, messages.invalidCapabilityJson({ appId: params.appId }), 502);
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return settle(invalid, "uncertain");
   }
 
   if (!response.ok) {
     const parsed = CapabilityErrorSchema.safeParse(upstreamBody.data);
     if (parsed.success && response.status >= 400 && response.status <= 599) {
-      return capabilityJsonResponse(parsed.data, response.status);
+      // A 4xx from the owning app is a decision about the request itself and
+      // proves the effect did not happen; a 5xx proves nothing.
+      return settle({ body: parsed.data, status: response.status }, response.status < 500 ? "nothing_happened" : "uncertain");
     }
-    if (actionWithoutRetrySafety) return outcomeUnknown();
+    if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");
     const invalid = errorResponse("INVALID_APP_RESPONSE", messages.invalidCapabilityError({ appId: params.appId }), 502);
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return settle(invalid, "uncertain");
   }
 
   const resultValidator = params.review
@@ -503,12 +618,93 @@ export const dispatchCapability = async (params: {
     !parsedReview?.success ||
     (operation.approval === "rememberable" ? parsedReview.data.approvalScope !== undefined : parsedReview.data.approvalScope === undefined);
   if (!resultValidator || !parsedResult?.success || !reviewApprovalScopeIsValid) {
-    if (actionWithoutRetrySafety) return outcomeUnknown();
+    if (actionWithoutRetrySafety) return settle(outcomeUnknown(), "uncertain");
     const invalid = errorResponse("INVALID_APP_RESPONSE", messages.outsideResultSchema({ appId: params.appId }), 502);
-    return capabilityJsonResponse(invalid.body, invalid.status);
+    return settle(invalid, "uncertain");
+  }
+
+  const body = upstreamBody.data as Record<string, unknown>;
+  if (!params.review && body.stream !== undefined) {
+    const stream = CapabilityStreamSchema.safeParse(body.stream);
+    if (!stream.success || !operation.stream || stream.data.direction !== operation.stream.direction || stream.data.size > operation.stream.maxBytes || Date.parse(stream.data.expiresAt) <= Date.now() || Date.parse(stream.data.expiresAt) > Date.now() + 86_400_000 || !params.authority)
+      return settle(errorResponse("INVALID_APP_RESPONSE", "Invalid stream offer", 502), "uncertain");
+    try {
+      body.stream = await sealCapabilityStream(stream.data, { appId: params.appId, kind: params.kind, capabilityId: params.capabilityId, schemaHash: operation.schemaHash, authority: params.authority, requestId, origin: params.origin, continuation: params.continuation });
+      if (Buffer.byteLength(JSON.stringify(body)) > CAPABILITY_MAX_RESULT_BYTES) throw new Error("Stream result too large");
+    } catch { return settle(errorResponse("INVALID_APP_RESPONSE", "Invalid stream offer", 502), "uncertain"); }
   }
+  return settle({ body, status: 200 }, "succeeded");
+};
+
+const executionStatus = (status: number, code: string | null): CapabilityExecutionStatus => {
+  if (status < 400) return "succeeded";
+  if (status === 400) return "invalid_input";
+  if (status === 401 || status === 403) return "denied";
+  if (status === 504 || code === CAPABILITY_FRAMEWORK_ERROR_CODES.deadlineExceeded) return "timed_out";
+  return "failed";
+};
+
+const bodyErrorCode = (body: unknown): string | null =>
+  body && typeof body === "object" && "code" in body && typeof body.code === "string" ? body.code : null;
 
-  return capabilityJsonResponse(upstreamBody.data, 200);
+const resultDataMeta = (body: unknown) =>
+  capabilityValueMeta(body && typeof body === "object" && "data" in body ? (body as { data: unknown }).data : body);
+
+/**
+ * Dispatch one already-parsed capability invocation through the live registry.
+ * HTTP, MCP, and assistant callers share this exact app lookup, credential
+ * forwarding, schema pinning, timeout, and response validation path.
+ *
+ * One invocation
+ * produces exactly one execution row, whatever its outcome. Binary stream
+ * continuations record their own row under the same request ID. Action reviews are a
+ * read-only preview and are not executions, so they are not recorded.
+ */
+export const dispatchCapability = async (params: CapabilityDispatchParams): Promise<Response> => {
+  const requestId = normalizeInvocationRequestId(params.request.headers.get("x-request-id")) ?? crypto.randomUUID();
+  const observed: CapabilityDispatchObservation = { subject: null, destructive: false };
+  const startedAt = new Date();
+  const outcome = await runCapabilityDispatch(params, requestId, observed);
+  if (!params.review) {
+    const actor = params.authority?.actor;
+    const principal = dispatchPrincipal(params, observed);
+    const accessSubject = params.authority?.accessSubject;
+    const subject =
+      accessSubject?.type === "user"
+        ? ({ type: "user", id: accessSubject.userId } as const)
+        : accessSubject?.type === "service_account"
+          ? ({ type: "service_account", id: accessSubject.serviceAccountId } as const)
+          : null;
+    const errorCode = outcome.status >= 400 ? bodyErrorCode(outcome.body) : null;
+    await recordCapabilityExecution({
+      requestId,
+      origin: params.origin,
+      appId: params.appId,
+      capability: `${params.appId}.${params.capabilityId}`,
+      kind: params.kind === "queries" ? "query" : "action",
+      destructive: observed.destructive,
+      actorKind: 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,
+      status: executionStatus(outcome.status, errorCode),
+      errorCode,
+      inputMeta: capabilityValueMeta(params.input),
+      outputMeta: outcome.status < 400 ? resultDataMeta(outcome.body) : null,
+      idempotencyKey: CapabilityIdempotencyKeySchema.safeParse(params.request.headers.get("idempotency-key")).data ?? null,
+      replayed: outcome.replayed === true,
+      startedAt,
+      completedAt: new Date(),
+    }).catch((error) => {
+      // History is operational evidence; losing a row must not fail the call.
+      log.error("Capability execution could not be recorded", {
+        appId: params.appId,
+        capabilityId: params.capabilityId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+    });
+  }
+  return capabilityJsonResponse(outcome.body, outcome.status);
 };
 
 class MandateDispatchError extends Error {
@@ -526,6 +722,11 @@ export const createCapabilityRoutes = (dependencies: CapabilityRouteDependencies
   return new Hono<AuthContext>()
     .use("/capabilities/v1/*", dependencies.authenticate ?? auth.requireRole("authenticated"))
     .use("/capabilities/v1/*", rejectReservedWorkloadCredential)
+    .post("/capabilities/v1/streams/:verb", describeRoute({
+      tags:["Capabilities"],summary:"Transfer or inspect one authorized binary stream",...requiresAuth,
+      description:"POST read/write/status/abort with x-cloud-stream-id. Write sends raw bytes; read returns raw bytes. Status and abort return the upload state. No automatic retries.",
+      responses:{200:{description:"Binary content, write receipt, or transfer state"},403:{description:"Stream does not belong to this caller"},409:{description:"Transfer or contract changed"},410:{description:"Stream expired"}},
+    }), async c => dispatchCapabilityStream(c.req.raw, auth.getAuthority(c), c.req.param("verb"), dependencies))
     .get(
       "/capabilities/v1/catalog",
       describeRoute({
@@ -554,6 +755,52 @@ export const createCapabilityRoutes = (dependencies: CapabilityRouteDependencies
         }
       },
     )
+    .post(
+      "/capabilities/v1/commands/:appId/:capabilityId",
+      describeRoute({
+        tags: ["Capabilities"],
+        summary: "Resolve an interactive Command link",
+        ...requiresAuth,
+        responses: {
+          200: jsonResponse(CommandLinkSchema, "Command entry URL"),
+          400: jsonResponse(CapabilityErrorSchema, "Invalid command input"),
+          404: jsonResponse(CapabilityErrorSchema, "Command unavailable"),
+          503: jsonResponse(CapabilityErrorSchema, "Route owner unavailable"),
+        },
+      }),
+      requireReadScope,
+      async (c) => {
+        const body = await readBoundedJson(c.req.raw, CAPABILITY_MAX_REQUEST_BYTES);
+        const request = body.ok ? CommandRequestSchema.safeParse(body.data) : null;
+        if (!request?.success) return c.json({ code: "VALIDATION_FAILED", message: capabilityMessages(getLocale(c)).requestBodyJson }, 400);
+        const appId = c.req.param("appId");
+        const entry = await (dependencies.getCapability ?? getCapability)(appId);
+        const command = entry?.manifest.commands.find((command) => command.localId === c.req.param("capabilityId"));
+        if (!command)
+          return c.json(
+            {
+              code: "CAPABILITY_NOT_FOUND",
+              message: capabilityMessages(getLocale(c)).notFound({ kind: "Command", reference: `${appId}.${c.req.param("capabilityId")}` }),
+            },
+            404,
+          );
+        const apps = await (dependencies.listApps ?? listApps)();
+        const pathname = new URL(command.path, "https://cloud.invalid").pathname;
+        const owner = apps
+          .flatMap((app) => app.routes.map((prefix) => ({ app, prefix })))
+          .filter(({ prefix }) => pathname === prefix || pathname.startsWith(`${prefix}/`))
+          .sort((a, b) => b.prefix.length - a.prefix.length)[0]?.app;
+        if (owner?.id !== appId)
+          return c.json({ code: "APP_UNAVAILABLE", message: capabilityMessages(getLocale(c)).appUnavailable({ appId }) }, 503);
+        try {
+          const appUrl = await (dependencies.appUrl ?? (() => settings.get<string>("app.url")))();
+          return c.json(resolveCommandLink(appId, command, request.data.input, { returnTo: request.data.returnTo }, appUrl));
+        } catch (error) {
+          if (!(error instanceof z.ZodError) && !(error instanceof Error && error.message === "Command link is too large")) throw error;
+          return c.json({ code: "VALIDATION_FAILED", message: capabilityMessages(getLocale(c)).inputSchemaMismatch }, 400);
+        }
+      },
+    )
     .post(
       "/capabilities/v1/actions/:appId/:capabilityId/review",
       describeRoute({
@@ -594,6 +841,7 @@ export const createCapabilityRoutes = (dependencies: CapabilityRouteDependencies
           request: c.req.raw,
           kind: "actions",
           review: true,
+          origin: "http",
           appId: c.req.param("appId") ?? "",
           capabilityId: c.req.param("capabilityId") ?? "",
           input: request.data.input,
@@ -644,6 +892,7 @@ export const createCapabilityRoutes = (dependencies: CapabilityRouteDependencies
         return dispatchCapability({
           request: c.req.raw,
           kind: c.req.param("kind") as "queries" | "actions",
+          origin: "http",
           appId: c.req.param("appId") ?? "",
           capabilityId: c.req.param("capabilityId") ?? "",
           input: request.data.input,