@k2b/cloud 0.6.0 → 0.8.0

package/src/cli/index.ts

@@ -32,7 +32,7 @@ export type CloudCliContext = {
   setDefault: (key: string, value: string | undefined) => Promise<void>;
   createApiClient: <TApi extends Hono<any, any, any>>(basePath: string) => CloudApiClient<TApi>;
   fetch: (path: string, init?: RequestInit) => Promise<Response>;
-  readJson: <T>(response: Response) => Promise<T>;
+  readJson: <T>(response: Pick<Response, "json" | "text" | "ok" | "status" | "statusText">) => Promise<T>;
   print: (value?: string) => void;
   /** Write a stdout chunk without adding a newline. */
   /** Resolves once the value is flushed; await it when writing large output. */
@@ -51,7 +51,8 @@ export type CloudCliModule = {
   booleanFlags?: readonly string[];
   requiresCloud?: boolean;
   requiresCloudFor?: (args: string[], flags: CloudCliFlags) => boolean;
-  help?: () => string;
+  /** Render module help in the request locale; command syntax stays unchanged. */
+  help?: (locale?: string) => string;
   run: (context: CloudCliContext) => Promise<number | void> | number | void;
 };
 

package/src/config/define-env.ts

@@ -0,0 +1,97 @@
+/**
+ * Environment registry factory.
+ *
+ * Every runtime environment variable is declared once with a schema, a
+ * default, a scope and a one-sentence doc. Registries read `process.env`
+ * lazily: each key is parsed on access, so tests can change variables and
+ * consumers never depend on an import-time snapshot. `.env.example`,
+ * `.env.prod.example` and the configuration reference are generated from the
+ * `$specs` of every registry by `scripts/generate-config-docs.ts`.
+ */
+import { z } from "zod";
+
+/**
+ * `runtime` is read by deployed processes, `secret` is a runtime credential,
+ * `development` only matters for host-run development, builds or tooling.
+ */
+export type EnvScope = "runtime" | "secret" | "development";
+
+export type EnvSpec<T> = {
+  /** Parses the trimmed raw value. Empty and unset values never reach the schema. */
+  schema: z.ZodType<T, unknown>;
+  /** Used when the variable is unset or empty; a function is evaluated on every access. */
+  default?: T | (() => T);
+  /** One sentence for operators; rendered into the generated files. */
+  doc: string;
+  /** Default `runtime`. */
+  scope?: EnvScope;
+  /** Host-run development value written to `.env.example`. */
+  example?: string;
+  /** Throw on access when unset and no default exists. */
+  required?: boolean;
+  /** Alternative variable names, consulted after the canonical key. */
+  aliases?: string[];
+};
+
+export type EnvSpecs = Record<string, EnvSpec<unknown>>;
+
+type EnvValue<S extends EnvSpec<unknown>> = S extends { default: unknown } | { required: true }
+  ? z.output<S["schema"]>
+  : z.output<S["schema"]> | undefined;
+
+export type EnvRegistry<S extends EnvSpecs> = { readonly [K in keyof S]: EnvValue<S[K]> } & {
+  readonly $specs: S;
+  readonly $keys: readonly string[];
+};
+
+const rawValue = (key: string, aliases: string[] = []): string | undefined => {
+  for (const name of [key, ...aliases]) {
+    const value = process.env[name]?.trim();
+    if (value) return value;
+  }
+  return undefined;
+};
+
+const isFactory = <T>(value: T | (() => T)): value is () => T => typeof value === "function";
+
+export const readEnv = <T>(key: string, spec: EnvSpec<T>): T | undefined => {
+  const raw = rawValue(key, spec.aliases);
+  if (raw === undefined) {
+    if (spec.default !== undefined) return isFactory(spec.default) ? spec.default() : spec.default;
+    if (spec.required) throw new Error(`${key} is required`);
+    return undefined;
+  }
+  const parsed = spec.schema.safeParse(raw);
+  if (!parsed.success) {
+    const reason = parsed.error.issues.map((issue) => issue.message).join("; ") || "is invalid";
+    throw new Error(`${key} ${reason}`);
+  }
+  return parsed.data;
+};
+
+export const defineEnv = <S extends EnvSpecs>(specs: S): EnvRegistry<S> => {
+  const keys = Object.freeze(Object.keys(specs));
+  const registry: Record<string, unknown> = { $specs: specs, $keys: keys };
+  for (const key of keys) {
+    Object.defineProperty(registry, key, { enumerable: true, configurable: true, get: () => readEnv(key, specs[key]!) });
+  }
+  // The getters above are the only way to build a typed lazy object.
+  return registry as EnvRegistry<S>;
+};
+
+/** Any non-empty string; empty values are treated as unset before parsing. */
+export const envString = z.string();
+
+/** `true` or `1` (case-insensitive) is true; everything else is false. */
+export const envBoolean = z.string().transform((value) => {
+  const normalized = value.toLowerCase();
+  return normalized === "true" || normalized === "1";
+});
+
+/** Comma-separated entries; whitespace and empty entries are dropped. */
+export const envList = z.string().transform((value) =>
+  value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter(Boolean),
+);

package/src/config/env.ts

@@ -1,54 +1,150 @@
 /**
- * Environment variable parsing.
- * All env vars are parsed and validated here, then exported as typed `env` object.
+ * Platform environment registry.
+ * Every variable a Cloud process reads is declared here or in an application's
+ * `src/env.ts`; values are parsed lazily on access (see `define-env.ts`).
  */
+import { z } from "zod";
+import { defineEnv, envBoolean, envList } from "./define-env";
 
-const str = (key: string, fallback: string = ""): string => process.env[key] ?? fallback;
-
-const optional = (key: string): string | undefined => process.env[key]?.trim() || undefined;
-
-const int = (key: string, fallback: number): number => {
-  const value = process.env[key];
-  const parsed = parseInt(value ?? "", 10);
-  return isNaN(parsed) ? fallback : parsed;
-};
-
-const bool = (key: string, fallback: boolean): boolean => {
-  const value = process.env[key]?.trim().toLowerCase();
-  if (!value) return fallback;
-  return value === "true" || value === "1";
-};
-
-const list = (key: string): string[] =>
-  (process.env[key] ?? "")
-    .split(",")
-    .map((entry) => entry.trim())
-    .filter(Boolean);
-
-export const env = {
-  // Application (infrastructure — not changeable at runtime)
-  APP_SECRET: str("APP_SECRET"),
-  PORT: int("PORT", 3000),
-  IS_DEVELOPMENT: process.env.NODE_ENV === "development",
-
-  // Admin login (local emergency access — token-based, no IPA required)
-  ADMIN_LOGIN_TOKEN: str("ADMIN_LOGIN_TOKEN"),
-
-  // NATS / @k2b/sync (Postgres and Redis are read by Bun from DATABASE_URL / REDIS_URL)
-  /** Bootstrap servers, comma-separated `nats://host:port` URLs. Required by `connectNats()`. */
-  NATS_SERVERS: list("NATS_SERVERS"),
-  /** Sync namespace shared by every app of one Cloud installation (e.g. `dev`, `prod`). Required. */
-  SYNC_NAMESPACE: str("SYNC_NAMESPACE"),
-  /** Path to a mounted NATS `.creds` file (JWT + NKey). Unset = server-side no-auth. */
-  NATS_CREDS_FILE: optional("NATS_CREDS_FILE"),
-  /** Path to a mounted CA certificate; enables TLS with that CA. Unset = plain TCP. */
-  NATS_TLS_CA_FILE: optional("NATS_TLS_CA_FILE"),
-  /**
-   * Default true: only dial the servers listed in NATS_SERVERS. Clustered
-   * nodes gossip their peers' advertised addresses, which are Docker-internal
-   * hostnames (`ipa_nats_2`) that host-side clients (tests, `dev:cld` tooling)
-   * cannot resolve. Set to `false` when clients can reach every advertised
-   * address and should learn new nodes at runtime.
-   */
-  NATS_IGNORE_CLUSTER_UPDATES: bool("NATS_IGNORE_CLUSTER_UPDATES", true),
-} as const;
+const syncReplicas = z
+  .enum(["1", "3", "5"], { error: "must be 1, 3, or 5" })
+  .transform((value): 1 | 3 | 5 => (value === "1" ? 1 : value === "3" ? 3 : 5));
+
+const registry = defineEnv({
+  // Process
+  NODE_ENV: {
+    schema: z.string(),
+    doc: "Release images set `production`; `development` enables development-only behavior such as insecure cookies and HTTP issuers.",
+  },
+  HOSTNAME: {
+    schema: z.string(),
+    doc: "Container or host name; the default instance identity in worker leases and gateway registration.",
+  },
+
+  // Infrastructure
+  DATABASE_URL: {
+    schema: z.string(),
+    example: "postgresql://ipa:ipa@localhost:5432/ipa",
+    doc: "Postgres connection read by Bun SQL and by application-owned pools.",
+  },
+  REDIS_URL: {
+    schema: z.string(),
+    aliases: ["VALKEY_URL"],
+    example: "redis://localhost:6379",
+    doc: "Valkey connection used by Bun Redis for caches and rate limits.",
+  },
+  NATS_SERVERS: {
+    schema: envList,
+    default: [],
+    example: "nats://localhost:4222",
+    doc: "Comma-separated NATS JetStream bootstrap servers; the client dials all of them.",
+  },
+  SYNC_NAMESPACE: {
+    schema: z.string(),
+    default: "",
+    example: "dev",
+    doc: "Sync namespace shared by every app of one installation; isolates its NATS resources from other installations on the same cluster.",
+  },
+  SYNC_REPLICAS: {
+    schema: syncReplicas,
+    default: 3,
+    example: "1",
+    doc: "Persistent JetStream replica count (1, 3 or 5); keep it consistent across the installation and migrate existing resources before changing it.",
+  },
+  NATS_CREDS_FILE: {
+    schema: z.string(),
+    doc: "Path to a mounted NATS `.creds` file (JWT and NKey); unset means server-side no-auth.",
+  },
+  NATS_TLS_CA_FILE: {
+    schema: z.string(),
+    doc: "Path to a mounted CA certificate that enables TLS to NATS; unset means plain TCP.",
+  },
+  NATS_IGNORE_CLUSTER_UPDATES: {
+    schema: envBoolean,
+    default: true,
+    example: "true",
+    doc: "Only dial the listed servers and ignore cluster-advertised peer addresses; set to `false` when every advertised address is reachable.",
+  },
+
+  // Installation
+  APP_URL: {
+    schema: z.string(),
+    example: "localhost:3000",
+    doc: "Public Cloud URL used to bootstrap the `app.url` setting; the stored setting wins once written.",
+  },
+  APP_SECRET: {
+    schema: z.string(),
+    default: "",
+    scope: "secret",
+    example: "change-me-generate-with-openssl-rand-hex-32",
+    doc: "Deployment-wide secret for at-rest settings encryption and signed cursors; generate once with `openssl rand -hex 32` and never change it after data has been written.",
+  },
+  ADMIN_LOGIN_TOKEN: {
+    schema: z.string(),
+    default: "",
+    scope: "secret",
+    doc: "Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works.",
+  },
+
+  // Identity and OAuth
+  CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    example: "change-me-generate-with-openssl-rand-hex-32",
+    doc: "Core only: 64-hex KEK for platform identity signing keys stored in Postgres; generate once with `openssl rand -hex 32` and never distribute it to other apps.",
+  },
+  CLOUD_IDENTITY_NEXT_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "Core only: pre-distributed next KEK before promoting it to current; cannot be combined with `CLOUD_IDENTITY_PREVIOUS_KEY`.",
+  },
+  CLOUD_IDENTITY_PREVIOUS_KEY: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "Core only: old KEK set during an explicit rolling rewrap of stored identity signing keys, then removed.",
+  },
+  CLOUD_OAUTH_BROKER_SECRET: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "Core and OAuth only: 64-hex secret that lets the OAuth app request token signatures from Core; generate independently with `openssl rand -hex 32`.",
+  },
+  CLOUD_CORE_INTERNAL_ORIGIN: {
+    schema: z.string(),
+    doc: "Direct Core listener origin for OAuth issuance, mandate-backed background work and internal callbacks; host-run callers use the Core port, not the gateway.",
+  },
+  CLOUD_APP_CREDENTIAL: {
+    schema: z.string(),
+    scope: "secret",
+    doc: "App-bound workload credential provisioned through Core's admin workload API; background apps such as Mail need one with `identity:invoke`.",
+  },
+  CLOUD_IDENTITY_JWKS_ORIGIN: {
+    schema: z.string(),
+    doc: "Optional private origin of the Core listener for session and invocation JWKS; unset fetches keys from the public issuer origin.",
+  },
+  CLOUD_OAUTH_JWKS_ORIGIN: {
+    schema: z.string(),
+    doc: "Optional private origin of the OAuth listener for OAuth JWKS; unset fetches keys from the public issuer origin.",
+  },
+
+  // Build and standalone development
+  APP_DIR: {
+    schema: z.string(),
+    scope: "development",
+    doc: "Application directory for standalone consumers running `@k2b/cloud/scripts/build.ts` or the SSR dev server outside the monorepo; defaults to the package directory.",
+  },
+
+  // Desktop
+  CLOUD_DESKTOP_SQLITE_PATH: {
+    schema: z.string(),
+    scope: "development",
+    doc: "SQLite file used by `desktop.sql` in the Bun desktop process; defaults to `.local/desktop.sqlite` in the working directory.",
+  },
+});
+
+type PlatformEnv = typeof registry & { readonly IS_DEVELOPMENT: boolean };
+
+/** Platform environment; `IS_DEVELOPMENT` derives from `NODE_ENV === "development"`. */
+export const env: PlatformEnv = Object.defineProperty(registry as PlatformEnv, "IS_DEVELOPMENT", {
+  enumerable: true,
+  get: () => registry.NODE_ENV === "development",
+});

package/src/config/index.ts

@@ -1,6 +1,8 @@
 /**
  * Main config export.
- * Re-exports env vars. SSR config is per-app via defineApp().
+ * Re-exports the platform environment registry and the registry factory used
+ * by application `src/env.ts` files. SSR config is per-app via defineApp().
  */
 
+export { defineEnv, type EnvRegistry, type EnvScope, type EnvSpec, type EnvSpecs, envBoolean, envList, envString } from "./define-env";
 export { env } from "./env";

package/src/contracts/app.ts

@@ -1,5 +1,5 @@
 import type { Sync } from "@k2b/sync";
-import type { HelpManifest } from "../shared/help";
+import type { AppRegistryHelpSummary } from "./registry";
 import type { Role } from "./shared";
 import type { DashboardWidgetPresentation } from "./widgets";
 
@@ -14,6 +14,18 @@ export type LegalLink = {
   icon?: string;
 };
 
+/** Static page links for the global search UI, ranked after resource results.
+ * These declare navigation only; they do not create capabilities or readers.
+ */
+export type AppSearchLink = {
+  label: string;
+  /** Optional plain-text context shown with the result and its preview. */
+  description?: string;
+  href: string;
+  icon?: string;
+  keywords?: readonly string[];
+};
+
 export type AppAppearanceColor = `#${string}`;
 
 export type AppAppearance = {
@@ -35,6 +47,8 @@ export type AppAdminNavigationLink = {
 };
 
 export type AppAdminNavigationGroup = {
+  /** Contribute links to the platform AI section instead of a separate group. */
+  section?: "ai";
   /** Stable key used only to localize this presentation group. */
   id?: string;
   label: string;
@@ -50,10 +64,14 @@ export type AppPresentationTranslation = {
   adminLinks?: Readonly<Record<string, string>>;
   /** Legal-link labels keyed by their stable same-origin href. */
   legalLinks?: Readonly<Record<string, string>>;
+  /** Search-link labels keyed by their stable same-origin href. */
+  searchLinks?: Readonly<Record<string, string>>;
+  /** Search-link descriptions keyed by their stable same-origin href. */
+  searchLinkDescriptions?: Readonly<Record<string, string>>;
 };
 
 export type AppPresentationCatalog = {
-  /** Locale of the complete `name`, `description`, `adminNav`, and `legalLinks` declaration. */
+  /** Locale of the complete `name`, `description`, `adminNav`, `legalLinks`, and `searchLinks` declaration. */
   baseLocale: string;
   /** Partial presentation overlays with exact -> ancestor -> base fallback. */
   translations: Readonly<Record<string, AppPresentationTranslation>>;
@@ -87,6 +105,8 @@ export type AppMeta = {
    * contributes its own (e.g. settings → terms/privacy/imprint, faq → FAQ).
    */
   legalLinks?: LegalLink[];
+  /** Static search destinations, visible when the app is in the user's navigation catalog. */
+  searchLinks?: readonly AppSearchLink[];
   /**
    * Dashboard widget endpoints this app exposes. Each entry references an
    * HTTP endpoint that returns a `WidgetResponse` (see `contracts/widgets.ts`).
@@ -111,7 +131,7 @@ export type WidgetEndpoint = {
 };
 
 export type RuntimeAppMeta = AppMeta & {
-  help?: HelpManifest;
+  help?: AppRegistryHelpSummary;
   searchTags?: string[];
   searchHelp?: string;
   searchTagHelp?: AppSearchTagHelpEntry[];

package/src/contracts/capabilities.ts

@@ -1,7 +1,17 @@
+import {
+  type CapabilityStream,
+  type CapabilityStreamDefinition,
+  CapabilityStreamPolicySchema,
+  CapabilityStreamSchema,
+} from "./capability-streams";
+
+export * from "./capability-streams";
+
 import { z } from "zod";
+import { CommandPathSchema } from "./commands";
 import type { AccessSubject, RequestActor, User } from "./shared";
 
-export const CAPABILITY_PROTOCOL_VERSION = 1 as const;
+export const CAPABILITY_PROTOCOL_VERSION = 2 as const;
 export const CAPABILITY_MAX_REQUEST_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_RESULT_BYTES = 256 * 1024;
 export const CAPABILITY_MAX_CATALOG_BYTES = 2 * 1024 * 1024;
@@ -14,6 +24,8 @@ export const CAPABILITY_FRAMEWORK_ERROR_CODES = {
   idempotencyKeyRequired: "IDEMPOTENCY_KEY_REQUIRED",
   idempotencyKeyNotAllowed: "IDEMPOTENCY_KEY_NOT_ALLOWED",
   idempotencyConflict: "IDEMPOTENCY_CONFLICT",
+  idempotencyInProgress: "IDEMPOTENCY_IN_PROGRESS",
+  idempotencyUncertain: "IDEMPOTENCY_UNCERTAIN",
   deadlineExceeded: "DEADLINE_EXCEEDED",
   actionOutcomeUnknown: "ACTION_OUTCOME_UNKNOWN",
   requestCancelled: "REQUEST_CANCELLED",
@@ -32,6 +44,17 @@ export const capabilityIdempotencyConflict = (
   ...(details ? { details } : {}),
 });
 
+/**
+ * Cloud surface a capability invocation came from. The dispatcher resolves it
+ * once, records it on the execution row, and forwards it to the owning app.
+ */
+export const CAPABILITY_ORIGINS = ["assistant", "mcp", "http", "app"] as const;
+export type CapabilityOrigin = (typeof CAPABILITY_ORIGINS)[number];
+export const CapabilityOriginSchema = z.enum(CAPABILITY_ORIGINS);
+
+/** Transports the resolved origin from the Cloud dispatcher to the app endpoint. */
+export const CAPABILITY_ORIGIN_HEADER = "x-cloud-capability-origin";
+
 export const CapabilityIdempotencyKeySchema = z
   .string()
   .trim()
@@ -94,10 +117,13 @@ const CapabilityActionReviewDetailSchema = z
     label: z.string().min(1).max(120),
     value: z.string().max(10_000),
     display: z.enum(["inline", "block"]).optional(),
-    format: z.enum(["date", "date-time"]).optional(),
+    format: z.enum(["date", "date-time", "markdown"]).optional(),
   })
   .strict()
   .superRefine((detail, context) => {
+    if (detail.format === "markdown" && detail.display !== "block") {
+      context.addIssue({ code: "custom", path: ["display"], message: "Markdown review details require block display" });
+    }
     const schema =
       detail.format === "date" ? CapabilityReviewDateSchema : detail.format === "date-time" ? CapabilityReviewDateTimeSchema : null;
     if (schema?.safeParse(detail.value).success === false) {
@@ -175,6 +201,7 @@ export const capabilityDataAtPath = (data: unknown, path: readonly string[]): un
 
 export type CapabilityResult<T> = {
   data: T;
+  stream?: CapabilityStream;
   /** Provider-authored, user-facing summary of the successful result. Render as escaped plain text. */
   summary?: string;
   refs?: CloudResourceReference[];
@@ -190,6 +217,7 @@ export const capabilityResultSchema = <T extends z.ZodType>(
   z
     .object({
       data,
+      stream: CapabilityStreamSchema.optional(),
       summary: z.string().trim().min(1).max(500).optional(),
       refs: z.array(CloudResourceReferenceSchema).max(100).optional(),
       page: CapabilityPageSchema.optional(),
@@ -264,6 +292,9 @@ export const UniversalSearchInputSchema = z
   .object({
     query: z.string().max(500).describe("User-entered search text. Empty text is allowed when a facet narrows the query."),
     tags: z.array(z.string().min(1).max(64)).max(20).describe("Canonical search facets supported by this query."),
+    scope: CloudResourceRefSchema.optional().describe(
+      "Optional resource containing the search results; must be an explicitly supported scope type.",
+    ),
     limit: z.number().int().min(1).max(100).describe("Maximum number of results to return."),
   })
   .strict();
@@ -285,6 +316,14 @@ export type CapabilityExecutionContext = {
    * error codes and data must not depend on it.
    */
   locale: string;
+  /**
+   * Correlation id of the originating Cloud request. Write it into the app's
+   * own audit rows so a capability execution record and the app's domain trail
+   * can be joined without sharing payloads.
+   */
+  requestId: string;
+  /** Cloud surface that invoked this capability. */
+  origin: CapabilityOrigin;
   signal: AbortSignal;
 };
 
@@ -304,6 +343,8 @@ export type CapabilitySearchTagDefinition = {
 
 export type CapabilityUniversalSearchDefinition = {
   tags: readonly CapabilitySearchTagDefinition[];
+  /** Local resource types whose contents this Query can search. */
+  scopeTypes?: readonly string[];
 };
 
 export type CapabilitySchemaPresentation = Readonly<Record<string, string>>;
@@ -323,6 +364,7 @@ export type CapabilityPresentationTranslation = {
   types?: Readonly<Record<string, { title?: string; description?: string }>>;
   queries?: Readonly<Record<string, CapabilityOperationPresentationTranslation>>;
   actions?: Readonly<Record<string, CapabilityOperationPresentationTranslation>>;
+  commands?: Readonly<Record<string, Pick<CapabilityOperationPresentationTranslation, "title" | "description" | "input">>>;
 };
 
 export type CapabilityPresentationCatalog = {
@@ -338,6 +380,7 @@ export type CapabilityQueryDefinition<Input extends z.ZodType = z.ZodType<any>,
   input: Input;
   data: Data;
   openWorld: boolean;
+  stream?: CapabilityStreamDefinition;
   universalSearch?: CapabilityUniversalSearchDefinition;
   run: (
     input: z.output<Input>,
@@ -346,7 +389,7 @@ export type CapabilityQueryDefinition<Input extends z.ZodType = z.ZodType<any>,
 };
 
 export type CapabilityIdempotencyPolicy = "none" | "required";
-export type CapabilityActionApprovalPolicy = "rememberable";
+export type CapabilityActionApprovalPolicy = "rememberable" | "none";
 
 export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>, Data extends z.ZodType = z.ZodType<any>> = {
   title: string;
@@ -355,6 +398,7 @@ export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>,
   data: Data;
   destructive: boolean;
   openWorld: boolean;
+  stream?: CapabilityStreamDefinition;
   idempotency: CapabilityIdempotencyPolicy;
   approval?: CapabilityActionApprovalPolicy;
   review?: (
@@ -367,6 +411,29 @@ export type CapabilityActionDefinition<Input extends z.ZodType = z.ZodType<any>,
   ) => CapabilityInvocationResult<z.output<Data>> | Promise<CapabilityInvocationResult<z.output<Data>>>;
 };
 
+/** A declarative UI entry. Resolution never executes application code or writes domain data. */
+export type CapabilityCommandDefinition = {
+  title: string;
+  description: string;
+  icon?: string;
+  keywords?: readonly string[];
+  input: z.ZodType;
+  path: string;
+};
+
+export const CapabilityCommandManifestSchema = z
+  .object({
+    localId: CapabilityLocalIdSchema,
+    title: z.string().min(1).max(120),
+    description: z.string().min(1).max(1000),
+    icon: z.string().min(1).max(120).optional(),
+    keywords: z.array(z.string().min(1).max(120)).max(30),
+    inputSchema: z.record(z.string(), z.unknown()),
+    path: CommandPathSchema,
+  })
+  .strict();
+export type CapabilityCommandManifest = z.infer<typeof CapabilityCommandManifestSchema>;
+
 type CapabilityDefinitionCatalog<T> = Readonly<Record<string, T>>;
 
 export type CapabilityDefinitions = {
@@ -375,6 +442,7 @@ export type CapabilityDefinitions = {
   types?: CapabilityDefinitionCatalog<CapabilityResourceTypeDefinition>;
   queries?: CapabilityDefinitionCatalog<CapabilityQueryDefinition>;
   actions?: CapabilityDefinitionCatalog<CapabilityActionDefinition>;
+  commands?: CapabilityDefinitionCatalog<CapabilityCommandDefinition>;
 };
 
 /**
@@ -409,6 +477,7 @@ const CapabilityOperationManifestBaseSchema = z
     description: z.string().min(1).max(1000),
     inputSchema: z.record(z.string(), z.unknown()),
     dataSchema: z.record(z.string(), z.unknown()),
+    stream: CapabilityStreamPolicySchema.optional(),
     schemaHash: z.string().regex(/^[a-f0-9]{64}$/),
   })
   .strict();
@@ -416,7 +485,7 @@ const CapabilityOperationManifestBaseSchema = z
 export const CapabilityQueryManifestSchema = CapabilityOperationManifestBaseSchema.extend({
   openWorld: z.boolean(),
   universalSearch: z
-    .object({ tags: z.array(CapabilitySearchTagManifestSchema).max(100) })
+    .object({ tags: z.array(CapabilitySearchTagManifestSchema).max(100), scopeTypes: z.array(CapabilityLocalIdSchema).max(100).optional() })
     .strict()
     .optional(),
 }).strict();
@@ -425,7 +494,7 @@ export const CapabilityActionManifestSchema = CapabilityOperationManifestBaseSch
   destructive: z.boolean(),
   openWorld: z.boolean(),
   idempotency: z.enum(["none", "required"]),
-  approval: z.literal("rememberable").optional(),
+  approval: z.enum(["rememberable", "none"]).optional(),
   review: z.literal(true).optional(),
 }).strict();
 
@@ -443,6 +512,7 @@ export const CapabilityManifestSchema = z
     types: z.array(CapabilityResourceTypeManifestSchema).max(200),
     queries: z.array(CapabilityQueryManifestSchema).max(200),
     actions: z.array(CapabilityActionManifestSchema).max(200),
+    commands: z.array(CapabilityCommandManifestSchema).max(200),
   })
   .strict();
 

package/src/contracts/capability-streams.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { CapabilityExecutionContext, CapabilityResult } from "./capabilities";
+
+/** One binary payload. Provider IDs are limited to 2 KiB UTF-8; Core seals them into opaque references, never URLs. */
+export const CapabilityStreamSchema = z
+  .object({
+    id: z.string().min(1).max(8192),
+    direction: z.enum(["read", "write"]),
+    name: z.string().min(1).max(255).optional(),
+    mediaType: z
+      .string()
+      .min(1)
+      .max(255)
+      .regex(/^[\x20-\x7e]+$/),
+    size: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    expiresAt: z.iso.datetime(),
+  })
+  .strict();
+export type CapabilityStream = z.infer<typeof CapabilityStreamSchema>;
+export const CapabilityStreamPolicySchema = z
+  .object({
+    direction: z.enum(["read", "write"]),
+    maxBytes: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+  })
+  .strict();
+export const CapabilityStreamStatusSchema = z.discriminatedUnion("state", [
+  z.object({ state: z.literal("open") }).strict(),
+  z.object({ state: z.literal("aborted") }).strict(),
+  z.object({ state: z.literal("completed"), result: z.unknown() }).strict(),
+]);
+export type CapabilityStreamStatus = z.infer<typeof CapabilityStreamStatusSchema>;
+export type CapabilityStreamDefinition = z.infer<typeof CapabilityStreamPolicySchema> &
+  (
+    | { direction: "read"; read: (stream: CapabilityStream, context: CapabilityExecutionContext) => Promise<Response> }
+    | {
+        direction: "write";
+        /** Consume completely, then publish. Must reconcile retries using stream.id. */
+        write: (
+          stream: CapabilityStream,
+          body: ReadableStream<Uint8Array>,
+          context: CapabilityExecutionContext,
+        ) => Promise<CapabilityResult<unknown>>;
+        status: (stream: CapabilityStream, context: CapabilityExecutionContext) => Promise<CapabilityStreamStatus>;
+        abort: (stream: CapabilityStream, context: CapabilityExecutionContext) => Promise<void>;
+      }
+  );