@k2b/cloud 0.37.0 → 0.38.0

package/src/api/help.ts

@@ -1,14 +1,16 @@
+import { keyboardPlatform } from "@k2b/ui";
 import { Hono, type MiddlewareHandler } from "hono";
+import { helpAgentMarkdown } from "../_internal/help-catalog";
 import { type AuthContext, auth, getLocale } from "../server";
 import { createHelpReader, type HelpReaderFactory } from "../services/help";
-import type { HelpDocumentPayload, HelpSearchPayload } from "../shared/help";
+import { type HelpDocumentPayload, type HelpSearchPayload, parseHelpReference } from "../shared/help";
 import { renderHelpMarkdown } from "../shared/markdown";
 import { helpApiMessages } from "./help-messages";
 
 export type HelpRouteDependencies = {
   help?: HelpReaderFactory;
   authenticate?: MiddlewareHandler<AuthContext>;
-  renderMarkdown?: (markdown: string, locale: string) => string;
+  renderMarkdown?: typeof renderHelpMarkdown;
 };
 
 export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
@@ -34,12 +36,29 @@ export const createHelpRoutes = (dependencies: HelpRouteDependencies = {}) => {
       const { t } = helpApiMessages.resolve([locale]);
       const document = await reader(locale, c.get("actor")).read({ appId: c.req.param("appId"), documentId: c.req.param("documentId") });
       if (!document) return c.json({ code: "HELP_NOT_FOUND", message: t.notFound }, 404);
+      const links = (reference: { appId?: string; documentId: string }) =>
+        document.links[`${reference.appId ?? document.appId}/${reference.documentId}`];
+      const resolve = (reference: string) => {
+        const ref = parseHelpReference(reference);
+        return ref ? links(ref) : undefined;
+      };
       const payload: HelpDocumentPayload = {
         locale: document.locale,
         id: document.documentId,
         title: document.title,
-        markdown: document.markdown,
-        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown, document.locale),
+        markdown: helpAgentMarkdown(document),
+        kind: document.kind,
+        needs: document.needs,
+        next: document.next ? resolve(document.next) : undefined,
+        related: document.related.flatMap((reference) => {
+          const target = resolve(reference);
+          return target ? [target] : [];
+        }),
+        html: (dependencies.renderMarkdown ?? renderHelpMarkdown)(document.markdown, {
+          locale: document.locale,
+          platform: keyboardPlatform(c.req.header("User-Agent") ?? ""),
+          links,
+        }),
       };
       return c.json(payload);
     });

package/src/api/mcp.ts

@@ -15,7 +15,13 @@ import {
 import { Hono, type MiddlewareHandler } from "hono";
 import { z } from "zod";
 import { readBoundedJson } from "../_internal/bounded-json";
-import { HELP_SEARCH_MAX_LIMIT, helpResourceUri, parseHelpResourceUri, readHelpArticle } from "../_internal/help-catalog";
+import {
+  HELP_SEARCH_MAX_LIMIT,
+  helpAgentMarkdown,
+  helpResourceUri,
+  parseHelpResourceUri,
+  readHelpArticle,
+} from "../_internal/help-catalog";
 import { getCapability, listApps } from "../_internal/registry";
 import { addCloudResourceHrefs } from "../ai/resource-refs";
 import { capabilityValueMeta, recordCapabilityExecution } from "../capabilities/executions";
@@ -540,7 +546,7 @@ const createMcpServer = (
         {
           uri: message.params.uri,
           mimeType: "text/markdown",
-          text: document.markdown,
+          text: helpAgentMarkdown(document),
           _meta: { "cloud/manifestHash": document.manifestHash, "cloud/locale": document.locale },
         },
       ],

package/src/browser/FileChooser.tsx

@@ -14,7 +14,7 @@ import {
 } from "@k2b/ui";
 import { batch, createMemo, createSignal, For, type JSX, Match, onCleanup, Show, Switch } from "solid-js";
 import { createStore } from "solid-js/store";
-import type { FileProviderEntry, FileProviderTag } from "../contracts/file-provider";
+import type { FileProviderContext, FileProviderEntry, FileProviderTag } from "../contracts/file-provider";
 import { fileChooserMessages } from "./file-chooser-messages";
 import {
   type EntryProblem,
@@ -39,6 +39,14 @@ export type ChooseFilesOptions = {
    * above it, so it also bounds what the browser holds. The provider's own read limit applies to each file as well.
    */
   maxBytes?: number;
+  /**
+   * What the person is working on, as resource refs, for providers that understand it. Only providers whose `list`
+   * accepts `context` receive it; others list as before. A function runs only when the person opens such a provider,
+   * at most once per chooser, and again after it failed. Refs are hints, never access.
+   */
+  context?: FileProviderContext | ((signal: AbortSignal) => Promise<FileProviderContext>);
+  /** The empty root title for a provider that received context. Defaults to the chooser's "No matching files". */
+  noMatchingFiles?: string;
   /** Closes the chooser, or stops waiting for the device's dialog, and resolves `[]` when aborted. */
   signal?: AbortSignal;
 };
@@ -95,7 +103,7 @@ export function FileChooser(props: {
       if (first) (location() ? selection : sourceSelection).focus(first);
     });
   };
-  const folder = createProviderFolder({ caller: props.caller, t, settled: refocus });
+  const folder = createProviderFolder({ caller: props.caller, t, settled: refocus, context: props.options.context });
   const { location, items, openFolder } = folder;
   const [downloads, setDownloads] = createStore<Download[]>([]);
   const [downloading, setDownloading] = createSignal(false);
@@ -297,7 +305,7 @@ export function FileChooser(props: {
               </Switch>
             </Match>
             <Match when={true}>
-              <FolderContents folder={folder} t={t}>
+              <FolderContents folder={folder} t={t} noMatchingFiles={props.options.noMatchingFiles}>
                 <FileGrid
                   rows={items()}
                   getRowId={(entry) => entry.id}

package/src/browser/choose-files.browser-harness.tsx

@@ -3,7 +3,8 @@ import { chooseFiles } from "./files";
 
 /**
  * One "Attach" button that calls the real `chooseFiles` for a browser test, which answers the catalog, the
- * provider's Queries, and its read streams. `?single` chooses one file, `?accept=` and `?max=` pass through.
+ * provider's Queries, and its read streams. `?single` chooses one file, `?accept=` and `?max=` pass through,
+ * `?customer=` passes one `customers.customer` ref as context and `?noMatching=` its empty title.
  * Each call gets a fresh signal that `window.abortChoosing()` aborts. Each result lands in `window.chosen` as plain
  * facts. `?dropzone` opens, like Notebooks, a dialog whose `FileDropzone` chooses with
  * `chooseFiles`; what it hands over lands in `window.chosen` the same way.
@@ -43,6 +44,8 @@ button.addEventListener("click", () => {
     multiple: !params.has("single"),
     accept: params.get("accept") ?? undefined,
     maxBytes: params.has("max") ? Number(params.get("max")) : undefined,
+    context: params.has("customer") ? { refs: [{ type: "customers.customer", id: params.get("customer")! }] } : undefined,
+    noMatchingFiles: params.get("noMatching") ?? undefined,
     signal: choosing.signal,
   }).then(async (files) => void results.push(await facts(files)));
 });

package/src/browser/file-chooser-messages.ts

@@ -19,6 +19,8 @@ export const fileChooserMessages = i18n.define({
       loading: "Loading…",
       loadMore: "Load more",
       emptyFolder: "This folder is empty",
+      noMatchingFiles: "No matching files",
+      otherSource: "Choose another source",
       noMatches: ({ query }: { query: string }) => `Nothing matches “${query}”`,
       clearFilter: "Clear filter",
       offline: "You are offline",
@@ -92,6 +94,8 @@ export const fileChooserMessages = i18n.define({
       loading: "Wird geladen…",
       loadMore: "Mehr laden",
       emptyFolder: "Dieser Ordner ist leer",
+      noMatchingFiles: "Keine passenden Dateien",
+      otherSource: "Andere Quelle wählen",
       noMatches: ({ query }) => `Nichts passt zu „${query}“`,
       clearFilter: "Filter löschen",
       offline: "Du bist offline",

package/src/browser/file-providers.ts

@@ -6,12 +6,14 @@ import type { CapabilityCatalogApp, CapabilityClientError, CapabilityHttpOptions
 import { CapabilityErrorSchema, type CapabilityStream, capabilityResultSchema } from "../contracts/capabilities";
 import { CapabilityStreamStatusSchema } from "../contracts/capability-streams";
 import {
+  type FileProviderContext,
   type FileProviderEntry,
   type FileProviderIssue,
   FileProviderListDataSchema,
   FileProviderReadDataSchema,
   FileProviderSaveDataSchema,
   FileProviderSaveInputSchema,
+  fileProviderAcceptsContext,
   fileProviderIssues,
 } from "../contracts/file-provider";
 import { LOCALE_HEADER } from "../shared/locale";
@@ -25,6 +27,7 @@ export type FileProviderSource = {
   name: string;
   icon: string;
   list: string;
+  context: boolean;
   read: string;
   /** The provider's read limit; a consumer combines it with its own. */
   maxBytes: number;
@@ -61,6 +64,14 @@ const issuesOf = (app: CapabilityCatalogApp): FileProviderIssue[] | null => {
   }
 };
 
+const acceptsContext = (app: CapabilityCatalogApp): boolean => {
+  try {
+    return fileProviderAcceptsContext(app.manifest);
+  } catch {
+    return false;
+  }
+};
+
 /**
  * Keeps the catalog apps that offer files with a usable `list` and `read`. Core already drops invalid declarations;
  * the check repeats here because a manifest from another Cloud release may name an operation this reader left out.
@@ -81,6 +92,7 @@ export const fileProviderSources = (apps: readonly CapabilityCatalogApp[], local
           name: app.appName,
           icon: providerIcon(app.appIcon, "ti ti-folders"),
           list: declaration.list,
+          context: acceptsContext(app),
           read: declaration.read,
           maxBytes: read.stream.maxBytes,
           ...(save?.stream ? { save: { id: save.localId, maxBytes: save.stream.maxBytes } } : {}),
@@ -112,7 +124,7 @@ export type FileProviderPage = { items: FileProviderEntry[]; next: string | null
 /** One folder page. Without `parent` it is the provider's root. */
 export const listProviderFolder = async (
   provider: FileProviderSource,
-  input: { parent?: string; query?: string; cursor?: string },
+  input: { parent?: string; query?: string; cursor?: string; context?: FileProviderContext },
   caller: FileProviderCaller,
   signal?: AbortSignal,
 ): Promise<FileProviderPage> => {
@@ -125,6 +137,7 @@ export const listProviderFolder = async (
         ...(input.parent === undefined ? {} : { parent: input.parent }),
         ...(input.query ? { query: input.query } : {}),
         ...(input.cursor === undefined ? {} : { cursor: input.cursor }),
+        ...(provider.context === true && input.context !== undefined ? { context: input.context } : {}),
         limit: FILE_PROVIDER_PAGE_SIZE,
       },
       signal,

package/src/browser/provider-folder.tsx

@@ -1,7 +1,8 @@
 import { timed } from "@k2b/stdlib/solid";
 import { announce, Button, IconButton, Placeholder, TextInput } from "@k2b/ui";
 import { batch, createMemo, createSignal, For, type JSX, Match, onCleanup, Show, Switch } from "solid-js";
-import type { FileProviderEntry } from "../contracts/file-provider";
+import { CloudResourceRefSchema } from "../contracts/capabilities";
+import { FILE_PROVIDER_CONTEXT_MAX_REFS, type FileProviderContext, type FileProviderEntry } from "../contracts/file-provider";
 import type { fileChooserMessages } from "./file-chooser-messages";
 import { type FileProviderCaller, FileProviderError, type FileProviderSource, listProviderFolder } from "./file-providers";
 
@@ -18,7 +19,12 @@ const EMPTY_PAGES_FOLLOWED = 5;
  * and its load state. `settled` runs after a folder has loaded or the source list is back, so the dialog can move
  * focus to its first row.
  */
-export const createProviderFolder = (props: { caller: () => FileProviderCaller; t: () => Messages; settled: () => void }) => {
+export const createProviderFolder = (props: {
+  caller: () => FileProviderCaller;
+  t: () => Messages;
+  settled: () => void;
+  context?: FileProviderContext | ((signal: AbortSignal) => Promise<FileProviderContext>);
+}) => {
   const [location, setLocation] = createSignal<FolderLocation>(null);
   const [filter, setFilter] = createSignal("");
   const [query, setQuery] = createSignal("");
@@ -27,6 +33,26 @@ export const createProviderFolder = (props: { caller: () => FileProviderCaller;
   const [writable, setWritable] = createSignal(false);
   const [status, setStatus] = createSignal<"loading" | "ready" | "more" | "error">("ready");
   const [error, setError] = createSignal<FileProviderError | null>(null);
+  const [contextual, setContextual] = createSignal(false);
+  let resolvedContext: FileProviderContext | undefined;
+  const contextFor = async (signal: AbortSignal): Promise<FileProviderContext> => {
+    if (resolvedContext) return resolvedContext;
+    const raw = typeof props.context === "function" ? await props.context(signal) : props.context;
+    signal.throwIfAborted();
+    const refs: FileProviderContext["refs"] = [];
+    const seen = new Set<string>();
+    for (const value of raw?.refs ?? []) {
+      const parsed = CloudResourceRefSchema.safeParse(value);
+      if (!parsed.success) continue;
+      const key = JSON.stringify([parsed.data.type, parsed.data.id]);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      refs.push(parsed.data);
+      if (refs.length === FILE_PROVIDER_CONTEXT_MAX_REFS) break;
+    }
+    resolvedContext = { refs };
+    return resolvedContext;
+  };
   let request: AbortController | undefined;
   onCleanup(() => request?.abort());
 
@@ -48,12 +74,15 @@ export const createProviderFolder = (props: { caller: () => FileProviderCaller;
     setStatus(more ? "more" : "loading");
     setError(null);
     try {
+      const context = current.provider.context === true && props.context !== undefined ? await contextFor(pending.signal) : undefined;
+      if (pending.signal.aborted) return;
+      setContextual(context !== undefined);
       let cursor = more ? (next() ?? undefined) : undefined;
       let followed = 0;
       for (;;) {
         const page = await listProviderFolder(
           current.provider,
-          { parent: current.trail.at(-1)?.id, query: query() || undefined, cursor },
+          { parent: current.trail.at(-1)?.id, query: query() || undefined, cursor, context },
           props.caller(),
           pending.signal,
         );
@@ -103,6 +132,7 @@ export const createProviderFolder = (props: { caller: () => FileProviderCaller;
       setFilter("");
       setQuery("");
       setLocation(target);
+      setContextual(false);
       setItems([]);
       setNext(null);
       setWritable(false);
@@ -138,6 +168,7 @@ export const createProviderFolder = (props: { caller: () => FileProviderCaller;
 
   return {
     location,
+    contextual,
     filter,
     query,
     items,
@@ -236,7 +267,12 @@ export function FolderToolbar(props: { folder: ProviderFolder; t: () => Messages
  * One folder in the dialog body: loading, the error with Try again or Up, the empty folder, no matches, or `children`
  * with Load more below while the folder continues.
  */
-export function FolderContents(props: { folder: ProviderFolder; t: () => Messages; children: JSX.Element }): JSX.Element {
+export function FolderContents(props: {
+  folder: ProviderFolder;
+  t: () => Messages;
+  noMatchingFiles?: string;
+  children: JSX.Element;
+}): JSX.Element {
   const folder = props.folder;
   return (
     <Switch>
@@ -268,7 +304,24 @@ export function FolderContents(props: { folder: ProviderFolder; t: () => Message
       <Match when={folder.items().length === 0 && !folder.next()}>
         <Show
           when={folder.query()}
-          fallback={<Placeholder variant="panel" class="cloud-file-chooser__state" icon="ti ti-folder" title={props.t().emptyFolder} />}
+          fallback={
+            <Show
+              when={folder.contextual() && folder.location()?.trail.length === 1}
+              fallback={<Placeholder variant="panel" class="cloud-file-chooser__state" icon="ti ti-folder" title={props.t().emptyFolder} />}
+            >
+              <Placeholder
+                variant="panel"
+                class="cloud-file-chooser__state"
+                icon="ti ti-file-search"
+                title={props.noMatchingFiles ?? props.t().noMatchingFiles}
+                action={
+                  <Button size="sm" variant="secondary" onClick={() => folder.navigate(null)}>
+                    {props.t().otherSource}
+                  </Button>
+                }
+              />
+            </Show>
+          }
         >
           <Placeholder
             variant="panel"

package/src/browser/resource-picker.tsx

@@ -22,6 +22,10 @@ export const openCloudResourcePicker = (options: CloudResourcePickerOptions = {}
     (close) => (
       <CloudResourceSearch {...options} title={options.title ?? t.chooseResource} selectionMode onSelect={close} onClose={() => close()} />
     ),
-    resourceSearchDialogOptions(options.title ?? t.chooseResource),
+    // A phone shows the picker as a full-screen sheet; global search keeps its floating card.
+    {
+      ...resourceSearchDialogOptions(options.title ?? t.chooseResource),
+      panelClassName: "cloud-search-dialog cloud-search-dialog--picker",
+    },
   );
 };

package/src/cli/admin/workflows.ts

@@ -55,6 +55,7 @@ export type WorkflowRunDetailRow = WorkflowRunRow & {
   effectsUsed: Record<string, number>;
   effectBudget: Record<string, number>;
   eventData: Record<string, unknown> | null;
+  eventPayloadExpired: boolean;
   steps: WorkflowStepRow[];
   children: Record<RunState, number>;
 };

package/src/config/env.ts

@@ -91,6 +91,20 @@ const registry = defineEnv({
     doc: "Core only: temporary first-administrator or recovery login token; remove it after normal administrator sign-in works.",
   },
 
+  // Outbound network
+  OUTGOING_MAIL_ALLOWED_TARGETS: {
+    schema: envList,
+    default: [],
+    scope: "runtime",
+    doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for outgoing mail SMTP and bounce IMAP connections; unset allows only public targets, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
+  },
+  GEO_ALLOWED_TARGETS: {
+    schema: envList,
+    default: ["geo"],
+    scope: "runtime",
+    doc: "Comma-separated host names, IP addresses and CIDR ranges on internal networks allowed for Geo requests; unset allows public targets and `geo`, an explicit value replaces this default, and invalid entries including `/0` stop the owning process at startup.",
+  },
+
   // Identity and OAuth
   CLOUD_IDENTITY_KEY_ENCRYPTION_KEY: {
     schema: z.string(),

package/src/contracts/file-provider.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import type { CapabilityManifest } from "./capabilities";
+import { type CapabilityManifest, CloudResourceRefSchema } from "./capabilities";
 import { type CapabilityContract, type CapabilityContractIssue, capabilityContractIssues } from "./capability-compatibility";
 
 /**
@@ -34,6 +34,26 @@ export const FileProviderListInputSchema = z
   })
   .strict();
 
+/** Caller hints are bounded independently of provider pagination. */
+export const FILE_PROVIDER_CONTEXT_MAX_REFS = 20;
+export const FileProviderContextSchema = z
+  .object({
+    refs: z
+      .array(CloudResourceRefSchema)
+      .max(FILE_PROVIDER_CONTEXT_MAX_REFS)
+      .describe(
+        "Hints about what the caller works on, for example the contacts a mail goes to; never a permission. Empty means nothing resolved.",
+      ),
+  })
+  .strict()
+  .describe("Caller resource hints, never a permission or proof of access.");
+export const FileProviderContextListInputSchema = FileProviderListInputSchema.extend({
+  context: FileProviderContextSchema.optional().describe(
+    "Optional caller context; keep it unchanged with cursor like parent, query and limit.",
+  ),
+}).strict();
+export type FileProviderContext = z.output<typeof FileProviderContextSchema>;
+
 const entryFacts = {
   id: ProviderIdSchema,
   name: z.string().min(1).max(255),
@@ -123,6 +143,33 @@ export const fileProvider = {
   },
 } as const satisfies Record<string, CapabilityContract>;
 
+/** Optional context-aware list contract; the base provider contract stays unchanged. */
+export const fileProviderContextList = { ...fileProvider.list, input: FileProviderContextListInputSchema } satisfies CapabilityContract;
+
+/** Only explicitly named, compatible context inputs opt in; open input objects do not. */
+export const fileProviderAcceptsContext = (manifest: CapabilityManifest): boolean => {
+  if (!manifest.fileProvider) return false;
+  const operation = manifest.queries.find((query) => query.localId === manifest.fileProvider?.list);
+  if (!operation) return false;
+  const root = operation.inputSchema;
+  let schema: unknown = root;
+  const visited = new Set<unknown>();
+  const object = (value: unknown): value is Record<string, unknown> => value !== null && typeof value === "object" && !Array.isArray(value);
+  while (object(schema) && typeof schema.$ref === "string") {
+    if (visited.has(schema)) return false;
+    visited.add(schema);
+    if (!schema.$ref.startsWith("#/$defs/")) return false;
+    const defs = root.$defs;
+    schema = object(defs) ? defs[schema.$ref.slice(8)] : undefined;
+  }
+  return (
+    object(schema) &&
+    object(schema.properties) &&
+    Object.hasOwn(schema.properties, "context") &&
+    capabilityContractIssues(fileProviderContextList, { kind: "query", operation }).length === 0
+  );
+};
+
 export type FileProviderFunction = keyof typeof fileProvider;
 export const FILE_PROVIDER_FUNCTIONS = ["list", "read", "save"] as const satisfies readonly FileProviderFunction[];
 

package/src/contracts/outgoing-mail.ts

@@ -96,7 +96,14 @@ export const MailErrorCodeSchema = z.enum([
   "smtp_failed",
 ]);
 export type MailErrorCode = z.infer<typeof MailErrorCodeSchema>;
-export const MailBounceErrorCodeSchema = z.enum(["open_failed", "search_failed", "apply_failed", "save_failed", "interrupted"]);
+export const MailBounceErrorCodeSchema = z.enum([
+  "open_failed",
+  "target_blocked",
+  "search_failed",
+  "apply_failed",
+  "save_failed",
+  "interrupted",
+]);
 export type MailBounceErrorCode = z.infer<typeof MailBounceErrorCodeSchema>;
 export const AdminMailProfileSchema = MailProfileInputSchema.omit({ smtpPassword: true, revision: true, imap: true }).extend({
   key: MailProfileKeySchema,