@k2b/cloud 0.36.0 → 0.37.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@k2b/cloud",
-  "version": "0.36.0",
+  "version": "0.37.0",
   "description": "Application platform library for independently deployed Hono and SolidJS services behind a dynamic gateway.",
   "license": "AGPL-3.0-or-later",
   "repository": {
@@ -106,8 +106,8 @@
     "@tabler/icons": "3.48.0",
     "@tailwindcss/typography": "0.5.20",
     "@k2b/nessi": "0.18.0",
-    "@k2b/ssr": "0.16.0",
-    "@k2b/ui": "0.26.0",
+    "@k2b/ssr": "0.17.0",
+    "@k2b/ui": "0.27.0",
     "@k2b/stdlib": "0.29.0",
     "@k2b/sync": "7.0.0",
     "@nats-io/jetstream": "3.4.0",

package/scripts/README.md

@@ -3,6 +3,7 @@
 - `build.ts` — production build for one Cloud app (`APP_ID`); used by the Dockerfiles and `bun run build` targets.
 - `preload.ts` — dev-mode preload that registers the SSR plugin and builds CSS before app code loads.
 - `build-canvas-workers.ts` — packages the isolated canvas workers (PDF pages, mobile app icons) and the native canvas for bundles that start them.
+- `cli-pack.ts` — packs a standalone `cld` module with its verified manifest and skill references: `bun run packages/cloud/scripts/cli-pack.ts <module.ts> --references <dir> --out <dir>`. Reads the package name and version from the current directory; publish the output with `npm publish <dir>` or archive it with `npm pack <dir>`.
 - `app-favicon.ts` — generates app favicons from Tabler icons; imported by `build.ts` and `preload.ts`.
 - `browser-performance.ts` — bundles the web-vitals browser asset for core; imported by `build.ts` and `preload.ts`.
 - `runtime-recovery-acceptance.ts` — shared-runtime recovery acceptance on disposable Docker containers: `bun packages/cloud/scripts/runtime-recovery-acceptance.ts` (also `bun run test:runtime-recovery`).

package/scripts/cli-pack.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env bun
+/**
+ * Pack a `cld` module as a package plugin, for authors without a Cloud
+ * application:
+ *
+ *   bun run node_modules/@k2b/cloud/scripts/cli-pack.ts src/cli.ts --references src/cli-references --out dist/cld-plugin
+ *
+ * Writes the same verified bundle the application build writes to
+ * `dist/cli/<name>/` (`cli.js`, `references/`, `manifest.json`), plus a
+ * `package.json` whose `cld.manifest` points at the manifest. Name and version
+ * come from `package.json` in the current directory.
+ */
+import { lstat, readdir, readFile, realpath, rm, writeFile } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { buildCliPlugin, writeCliPlugin } from "../src/_internal/cli-plugins";
+import { validateCloudCliModule } from "../src/cli/plugin";
+
+const USAGE = "Usage: bun run node_modules/@k2b/cloud/scripts/cli-pack.ts <module.ts> --references <dir> --out <dir>";
+
+const HELP = `${USAGE}
+
+Packs a cld module as a package plugin: the bundled module cli.js, the skill
+references (index.md plus further Markdown files), manifest.json with the
+SHA-512 of every file, and a package.json with "cld": { "manifest": "manifest.json" }.
+Name and version come from package.json in the current directory.
+
+--out must be missing, empty, or an earlier pack output, which is replaced.
+Ship the result with \`npm publish <out>\` or \`npm pack <out>\`.`;
+
+const isRecord = (value: unknown): value is Record<string, unknown> => typeof value === "object" && value !== null && !Array.isArray(value);
+
+const readJson = (path: string): Promise<unknown> =>
+  readFile(path, "utf8")
+    .then(JSON.parse)
+    .catch(() => null);
+
+const parseArgs = (args: string[]) => {
+  const [module, ...rest] = args;
+  const flags = new Map<string, string>();
+  for (let index = 0; index < rest.length; index += 2) {
+    const [flag, value] = [rest[index]!, rest[index + 1]];
+    if (!["--references", "--out"].includes(flag) || !value || value.startsWith("-") || flags.has(flag)) throw new Error(USAGE);
+    flags.set(flag, value);
+  }
+  const references = flags.get("--references");
+  const out = flags.get("--out");
+  if (!module || module.startsWith("-") || !references || !out) throw new Error(USAGE);
+  return { module: resolve(module), references: resolve(references), out: resolve(out) };
+};
+
+const containsPath = (directory: string, path: string): boolean => {
+  const inside = relative(directory, path);
+  return inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside);
+};
+
+/** Empty `out` for a fresh pack; anything but an earlier pack output stays untouched. */
+const prepareOut = async (out: string, inputs: string[]): Promise<void> => {
+  const refusal = `Refusing --out ${out}: it must be missing, empty, or an earlier pack output.`;
+  const output = await realpath(out).catch(() => out);
+  for (const input of inputs) {
+    const path = await realpath(input).catch(() => input);
+    if (containsPath(out, input) || containsPath(output, path)) throw new Error(refusal);
+  }
+  const info = await lstat(out).catch(() => null);
+  if (!info) return;
+  if (!info.isDirectory()) throw new Error(refusal);
+  const entries = await readdir(out);
+  if (entries.length === 0) return;
+  const previous = await readJson(join(out, "package.json"));
+  if (
+    entries.some((entry) => !["package.json", "manifest.json", "cli.js", "references"].includes(entry)) ||
+    !isRecord(previous) ||
+    !isRecord(previous.cld) ||
+    previous.cld.manifest !== "manifest.json"
+  )
+    throw new Error(refusal);
+  await rm(out, { recursive: true });
+};
+
+const pack = async (args: string[]): Promise<void> => {
+  if (args.includes("--help") || args.includes("-h")) {
+    console.log(HELP);
+    return;
+  }
+  const options = parseArgs(args);
+  const cwd = process.cwd();
+  const manifest = await readJson(join(cwd, "package.json"));
+  if (
+    !isRecord(manifest) ||
+    typeof manifest.name !== "string" ||
+    !manifest.name ||
+    typeof manifest.version !== "string" ||
+    !manifest.version
+  ) {
+    throw new Error(`${join(cwd, "package.json")} needs a string name and version.`);
+  }
+  const { name: packageName, version } = manifest;
+  await prepareOut(options.out, [cwd, options.module, options.references]);
+  const loaded: unknown = await import(pathToFileURL(options.module).href);
+  const module = validateCloudCliModule(isRecord(loaded) ? loaded.default : undefined);
+  const plugin = await buildCliPlugin({
+    appDir: cwd,
+    appId: packageName,
+    name: module.name,
+    declaration: { module: options.module, references: options.references },
+    version,
+  });
+  await writeCliPlugin(options.out, plugin);
+  await writeFile(
+    join(options.out, "package.json"),
+    `${JSON.stringify({ name: packageName, version, type: "module", cld: { manifest: "manifest.json" } }, null, 2)}\n`,
+  );
+  const references = plugin.manifest.files.filter((file) => file.path.startsWith("references/")).length;
+  console.log(
+    `Packed ${packageName}@${version} (module "${module.name}", ${references} reference files) to ${options.out}. Ship it with \`npm publish ${options.out}\` or \`npm pack ${options.out}\`.`,
+  );
+};
+
+pack(Bun.argv.slice(2)).catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message.replace(/\s*\n\s*/g, " ") : String(error));
+  process.exitCode = 1;
+});

package/src/_internal/shell-focus.ts

@@ -0,0 +1,11 @@
+export const SHELL_FOCUS_COOKIE = "cloud_shell_focus";
+
+export const readShellFocusCookie = (cookieHeader: string | null | undefined): boolean =>
+  cookieHeader
+    ?.split(";")
+    .map((part) => part.trim())
+    .find((part) => part.startsWith(`${SHELL_FOCUS_COOKIE}=`))
+    ?.slice(SHELL_FOCUS_COOKIE.length + 1) === "1";
+
+export const shellFocusCookie = (hidden: boolean, secure: boolean): string =>
+  `${SHELL_FOCUS_COOKIE}=${hidden ? "1" : ""}; Path=/; Max-Age=${hidden ? 31536000 : 0}; SameSite=Lax${secure ? "; Secure" : ""}`;

package/src/access/PermissionEditor.browser-harness.tsx

@@ -0,0 +1,46 @@
+import { LocaleProvider } from "@k2b/ui";
+import { render } from "solid-js/web";
+import PermissionEditor from "./PermissionEditor";
+
+const host = document.getElementById("root");
+if (!host) throw new Error("Missing harness root");
+render(
+  () => (
+    <LocaleProvider locale="en">
+      <PermissionEditor
+        initialEntries={["Mara Lind", "Lea Sommer", "Jonas Weber"].map((displayName, index) => ({
+          id: `access-${index}`,
+          principal: { type: "user", userId: `user-${index}` },
+          displayName,
+          permission: "read",
+          createdAt: "2026-10-15T07:00:00.000Z",
+        }))}
+        // Equal-width labels isolate pending-state layout from a normal change in label width.
+        allowedLevels={[
+          { level: "read", label: "Level 1" },
+          { level: "write", label: "Level 2" },
+        ]}
+        allowAuthenticated={false}
+        grantAccess={async () => {
+          throw new Error("Not used");
+        }}
+        updateAccess={() =>
+          new Promise<void>((resolve) => {
+            // The test waits for this mark, so it does not depend on how the editor shows a pending change.
+            document.documentElement.dataset.saving = "true";
+            document.addEventListener(
+              "settle-access",
+              () => {
+                delete document.documentElement.dataset.saving;
+                resolve();
+              },
+              { once: true },
+            );
+          })
+        }
+        revokeAccess={async () => {}}
+      />
+    </LocaleProvider>
+  ),
+  host,
+);

package/src/access/PermissionEditor.tsx

@@ -236,8 +236,16 @@ export default function PermissionEditor(props: PermissionEditorProps) {
   };
 
   type LevelChange = { accessId: string; permission: GrantableLevel; scope: string | undefined };
+  // The row whose change is saving: it shows the chosen level with a spinner, the other rows wait.
+  const [updating, setUpdating] = createSignal<LevelChange | null>(null);
+  const [revoking, setRevoking] = createSignal<string | null>(null);
+  const updatingRow = (accessId: string) => {
+    const change = updating();
+    return change?.accessId === accessId ? change : undefined;
+  };
   const updateMut = mutation.create<LevelChange, LevelChange>({
     mutation: async (data) => {
+      setUpdating(data);
       await props.updateAccess(data.accessId, data.permission, data.scope);
       return data;
     },
@@ -247,6 +255,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
       }
     },
     onError: (err) => prompts.error(err.message),
+    onFinally: () => {
+      if (!disposed) setUpdating(null);
+    },
   });
 
   const revokeMut = mutation.create<string | null, AccessEntry>({
@@ -257,6 +268,7 @@ export default function PermissionEditor(props: PermissionEditorProps) {
         variant: "danger",
       });
       if (!confirmed) return null;
+      setRevoking(entry.id);
       await props.revokeAccess(entry.id);
       return entry.id;
     },
@@ -264,6 +276,9 @@ export default function PermissionEditor(props: PermissionEditorProps) {
       if (accessId) setEntries((current) => current.filter((entry) => entry.id !== accessId));
     },
     onError: (err) => prompts.error(err.message),
+    onFinally: () => {
+      if (!disposed) setRevoking(null);
+    },
   });
   const busy = () => grantPending() || updateMut.loading() || revokeMut.loading();
   // The service refuses to remove the last manager; the row says so up front.
@@ -288,6 +303,8 @@ export default function PermissionEditor(props: PermissionEditorProps) {
                 coverage={coverage}
                 canEdit={canEdit()}
                 pending={entry.id === pending()}
+                updating={updatingRow(entry.id)}
+                revoking={entry.id === revoking()}
                 disabled={busy()}
                 lastManager={entry.id === lastManagerId()}
                 allowed={allowed(entry.principal)}
@@ -332,8 +349,14 @@ export default function PermissionEditor(props: PermissionEditorProps) {
 function AccessEntryRow(props: {
   entry: AccessEntry;
   canEdit: boolean;
+  /** Another change is saving: the row keeps its controls, disabled. */
   disabled: boolean;
+  /** This row's grant is saving. */
   pending?: boolean;
+  /** This row's level change is saving. */
+  updating?: { permission: GrantableLevel; scope: string | undefined };
+  /** This row's removal is saving. */
+  revoking?: boolean;
   /** The only entry that manages the resource: it keeps its level and cannot be removed. */
   lastManager: boolean;
   allowed: ResolvedLevel[];
@@ -352,8 +375,14 @@ function AccessEntryRow(props: {
   const display = () => resolveEntryDisplay(props.entry.permission, props.entry.scope, props.allowed, t());
   const manageLabel = () => resolveEntryDisplay("admin", undefined, props.allowed, t()).label;
   const removeLabel = () => (props.lastManager ? t().lastManager({ level: manageLabel() }) : t().remove({ name: displayName() }));
-  const isInteractive = () =>
-    props.canEdit && !props.disabled && !props.pending && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
+  // Whether the row offers a picker depends only on what the viewer may do, never on a change in flight, so a
+  // saving change never swaps the picker for the badge and the rows keep their size.
+  const hasPicker = () => props.canEdit && !props.singlePicker && props.allowed.some((option) => option.key === entryKey());
+  const saving = () => props.pending || props.updating !== undefined || props.revoking === true;
+  // While a level change saves, the picker already shows the chosen level.
+  const shownKey = () => (props.updating ? levelKey(props.updating.permission, props.updating.scope) : entryKey());
+  const shownDisplay = () =>
+    props.updating ? resolveEntryDisplay(props.updating.permission, props.updating.scope, props.allowed, t()) : display();
 
   const badgeClass =
     "flex min-h-7 items-center gap-1 rounded-full border border-transparent bg-[var(--ui-surface-muted)] px-2.5 py-1 text-xs text-secondary";
@@ -362,15 +391,12 @@ function AccessEntryRow(props: {
     <>
       <i class={props.pending ? "ti ti-loader-2 animate-spin" : `ti ${display().icon}`} />
       <span>{display().label}</span>
-      <Show when={isInteractive()}>
-        <i class="ti ti-chevron-down text-[10px]" />
-      </Show>
     </>
   );
 
   return (
     <div>
-      <div class="group/access-row flex items-center gap-2 py-1.5" aria-busy={props.pending ? "true" : undefined}>
+      <div class="group/access-row flex items-center gap-2 py-1.5" aria-busy={saving() ? "true" : undefined}>
         <Show
           when={props.entry.principal.type === "user"}
           fallback={
@@ -415,10 +441,12 @@ function AccessEntryRow(props: {
 
         {/* Permission badge — interactive single-value picker when editable,
           plain span otherwise. */}
-        <Show when={isInteractive()} fallback={<span class={`${badgeClass} cursor-default`}>{badgeContent}</span>}>
+        <Show when={hasPicker()} fallback={<span class={`${badgeClass} cursor-default`}>{badgeContent}</span>}>
           <SelectChip
             aria-label={t().permissionFor({ name: displayName() })}
-            value={entryKey}
+            value={shownKey}
+            disabled={props.disabled}
+            loading={props.pending || props.updating !== undefined}
             options={props.allowed.map((option) => {
               const locked = props.lastManager && (option.level !== "admin" || option.scope !== undefined);
               return {
@@ -429,7 +457,7 @@ function AccessEntryRow(props: {
                 description: locked ? t().lastManagerOption({ level: manageLabel() }) : option.description,
               };
             })}
-            icon={`ti ${display().icon}`}
+            icon={`ti ${shownDisplay().icon}`}
             position="bottom-left"
             onValueChange={(key) => {
               const option = props.allowed.find((candidate) => candidate.key === key);
@@ -452,6 +480,7 @@ function AccessEntryRow(props: {
               size="xs"
               onClick={props.onRevoke}
               disabled={props.disabled || props.pending || props.lastManager}
+              loading={props.revoking}
               aria-label={t().remove({ name: displayName() })}
               // A disabled button takes no focus and touch has no hover, so the reason also reaches assistive technology.
               aria-description={props.lastManager ? removeLabel() : undefined}

package/src/access/ui.ts

@@ -6,6 +6,7 @@
  * from depending on Cloud's broad legacy UI entrypoint.
  */
 
+export { isManagerEntry, type ManagerCandidate } from "./managers";
 export type { AllowedLevel, GrantableLevel } from "./PermissionEditor";
 export { default as PermissionEditor } from "./PermissionEditor";
 export { default as PrincipalPicker, principalKey } from "./PrincipalPicker";

package/src/ai/chat/answer-links.ts

@@ -0,0 +1,8 @@
+/**
+ * Root scheme-less Cloud resource links in sanitized Assistant answer HTML.
+ * Normalized links stay root-relative under /app/ or /open/ and can never change origin.
+ */
+export function rootResourceLinks(html: string): string {
+  // sanitize-html emits double-quoted attributes with ", <, and > escaped in values.
+  return html.replace(/<a\b[^>]*>/g, (tag) => tag.replace(/(\shref=")((?:app|open)\/)/g, "$1/$2"));
+}

package/src/ai/chat/messages.ts

@@ -34,6 +34,7 @@ const messages = i18n.define({
       turnErrorReason: ({ code, limitMinutes }: AiTurnError) => {
         if (code === "model_unavailable") return "The model service did not answer.";
         if (code === "provider_stopped") return "The model provider ended this answer early.";
+        if (code === "tool_failed") return "A step failed, and the model stopped without an answer.";
         if (code === "quota_exhausted") return "Your AI usage limit for this period is reached. You can continue once it resets.";
         if (code === "context_full") return "This chat is too long for the model. Start a new chat to continue; this one stays as it is.";
         if (code === "time_limit")
@@ -336,6 +337,7 @@ const messages = i18n.define({
       turnErrorReason: ({ code, limitMinutes }) => {
         if (code === "model_unavailable") return "Der KI-Dienst hat nicht geantwortet.";
         if (code === "provider_stopped") return "Der KI-Anbieter hat diese Antwort vorzeitig beendet.";
+        if (code === "tool_failed") return "Ein Schritt ist fehlgeschlagen, und das Modell hat danach nicht geantwortet.";
         if (code === "quota_exhausted")
           return "Dein KI-Kontingent für diesen Zeitraum ist aufgebraucht. Du kannst weiterarbeiten, sobald es sich erneuert.";
         if (code === "context_full")

package/src/ai/chat/primitives.tsx

@@ -1,4 +1,5 @@
 import { createEffect, onCleanup, onMount } from "solid-js";
+import { rootResourceLinks } from "./answer-links";
 import { useAiChatActions } from "./message-actions";
 
 export function AssistantMarkdownBlock(props: { html: string }) {
@@ -41,5 +42,5 @@ export function AssistantMarkdownBlock(props: { html: string }) {
     element.addEventListener("click", handleClick);
     onCleanup(() => element.removeEventListener("click", handleClick));
   });
-  return <div ref={element} class="assistant-markdown-block" innerHTML={props.html} />;
+  return <div ref={element} class="assistant-markdown-block" innerHTML={rootResourceLinks(props.html)} />;
 }

package/src/ai/executor.ts

@@ -23,6 +23,7 @@ import { CODE_RUNTIME_TOOL_NAMES } from "./browser-code-contracts";
 import { type AiCapabilityCatalogEntry, createAiToolResolver, createRunToolStore } from "./capabilities";
 import { AiCapabilityExecutionError, executeAiCapability, resolveAiCapabilityActor, reviewAiCapability } from "./capability-execution";
 import { aiChatMessages } from "./chat/messages";
+import { isFailedTool } from "./chat/tool-groups";
 import { aiTurnErrorText } from "./chat/turn-error";
 import { AiChatTaskAuthorityError, aiChatTasks } from "./chat-tasks";
 import { createCloudCompactFn } from "./compaction";
@@ -134,6 +135,17 @@ const toolRoundState = (messages: AiStoredMessage[]): { issued: number; complete
   };
 };
 
+const lastToolRoundFailed = (messages: AiStoredMessage[], blocks: AiTurnBlock[]): boolean => {
+  const latest = messages.findLast(({ message }) => message.role === "assistant")?.message;
+  if (latest?.role !== "assistant") return false;
+  const callIds = new Set(latest.content.flatMap((block) => (block.type === "tool_call" ? [block.id] : [])));
+  // A worker may have stored a malformed call but crashed before its error result; load repairs that result without an event.
+  return (
+    [...callIds].some(isMalformedToolCallId) ||
+    blocks.some((block) => block.kind === "tool" && callIds.has(block.callId) && isFailedTool(block))
+  );
+};
+
 const indexConversationResources = async (input: Parameters<typeof aiConversations.indexConversationResources>[0]): Promise<void> => {
   try {
     await aiConversations.indexConversationResources(input);
@@ -1500,6 +1512,7 @@ export class AiTurnExecutor {
     const outcome = await this.driveChatLoop({
       loop,
       pipeline,
+      initialRoundFailed: lastToolRoundFailed(turnMessages, turnBlocks),
       conversationId,
       turnId,
       abortController,
@@ -1572,6 +1585,7 @@ export class AiTurnExecutor {
   private async driveChatLoop(input: {
     loop: NessiLoop;
     pipeline: StreamPipeline;
+    initialRoundFailed: boolean;
     conversationId: string;
     turnId: string;
     abortController: AbortController;
@@ -1613,6 +1627,10 @@ export class AiTurnExecutor {
     } = input;
     const stopHeartbeat = this.startHeartbeat(conversationId, turnId, abortController);
     let lastIssueMessage: string | null = null;
+    let lastResponse: AssistantMessage | undefined;
+    let roundFailed = input.initialRoundFailed;
+    let followedFailedRound = false;
+    const malformedCallIds = new Set<string>();
 
     try {
       for await (const event of loop) {
@@ -1672,6 +1690,7 @@ export class AiTurnExecutor {
             .noteToolCompleted({ turnId, callId: event.callId, isError: event.isError })
             .catch(() => log.warn("AI tool audit write failed", { code: "tool_audit_complete_failed", turnId, callId: event.callId }));
           const toolBlock = pipeline.blocks.find((block) => block.kind === "tool" && block.callId === event.callId);
+          if (toolBlock?.kind === "tool" && isFailedTool(toolBlock)) roundFailed = true;
           // The policy keys calls by the name the model called, as the persisted calls it seeds from.
           noteToolCall(
             toolBlock?.kind === "tool"
@@ -1687,20 +1706,44 @@ export class AiTurnExecutor {
             result: event.result,
             isError: event.isError === true,
           });
-        } else if (event.type === "turn_end" && !abortController.signal.aborted && isToolRound(event.message)) {
-          noteToolRound();
+        } else if (event.type === "turn_end") {
+          lastResponse = event.message;
+          followedFailedRound = roundFailed;
+          const calls = new Set(event.message.content.flatMap((block) => (block.type === "tool_call" ? [block.id] : [])));
+          // nessi closes a round after executing its tools. Malformed calls have stored failed blocks,
+          // but are added by Cloud's store wrapper, so they are absent from the event's message.
+          roundFailed = pipeline.blocks.some(
+            (block) => block.kind === "tool" && (calls.has(block.callId) || malformedCallIds.has(block.callId)) && isFailedTool(block),
+          );
+          malformedCallIds.clear();
+          if (!abortController.signal.aborted && isToolRound(event.message)) noteToolRound();
         } else if (event.type === "issue") {
+          if (event.issue.kind === "malformed_tool_call" && event.issue.callId) malformedCallIds.add(event.issue.callId);
           lastIssueMessage = event.issue.message;
           log.warn("AI turn issue", { conversationId, turnId, kind: event.issue.kind, message: event.issue.message });
         } else if (event.type === "loop_end") {
+          const stoppedAfterFailure =
+            event.reason === "stop" &&
+            !abortController.signal.aborted &&
+            followedFailedRound &&
+            lastResponse !== undefined &&
+            !lastResponse.content.some((block) => block.type === "tool_call" || (block.type === "text" && block.text.trim() !== ""));
+          const doneReason = stoppedAfterFailure ? "error" : event.reason;
           const aggregate = await withDurableTurnTiming(turnId, event.aggregate);
           if (aggregate.assistantMessageCount > 0) {
             await aiConversations
-              .setLatestAssistantLoopAggregate({ conversationId, loopId: turnId, aggregate, doneReason: event.reason })
+              .setLatestAssistantLoopAggregate({ conversationId, loopId: turnId, aggregate, doneReason })
               .catch(() => undefined);
           }
           const timing = aggregate.timing;
           if (event.reason === "aborted") return { kind: "finished", status: "aborted", failure: null, timing };
+          if (stoppedAfterFailure)
+            return {
+              kind: "finished",
+              status: "failed",
+              failure: { error: { code: "tool_failed" }, detail: "The model stopped without an answer after a failed tool call." },
+              timing,
+            };
           if (event.reason === "stop") return { kind: "finished", status: "completed", failure: null, timing };
           const detail = lastIssueMessage ?? `AI turn ended: ${event.reason}`;
           const reason: AiTurnFailureReason =

package/src/ai/types.ts

@@ -337,6 +337,7 @@ export type AiConversationTimelineEntry = {
 export type AiTurnErrorCode =
   | "model_unavailable"
   | "provider_stopped"
+  | "tool_failed"
   | "quota_exhausted"
   | "context_full"
   | "time_limit"

package/src/browser/shell-focus.ts

@@ -0,0 +1,67 @@
+import { shellFocusCookie } from "../_internal/shell-focus";
+
+export const SHELL_FOCUS_CHANGE_EVENT = "cloud:shell-focus-change";
+
+const canvas = () => document.querySelector<HTMLElement>(".cloud-app-canvas[data-layout-authenticated]");
+
+export const readShellFocus = (): boolean => canvas()?.dataset.shellFocus === "true";
+
+export const setShellFocus = (hidden: boolean): void => {
+  const element = canvas();
+  if (!element) return;
+  const focused = document.activeElement;
+  document.cookie = shellFocusCookie(hidden, location.protocol === "https:");
+  if (hidden) element.dataset.shellFocus = "true";
+  else delete element.dataset.shellFocus;
+  window.dispatchEvent(new CustomEvent(SHELL_FOCUS_CHANGE_EVENT, { detail: { hidden } }));
+  if (
+    window.matchMedia("(min-width: 768px)").matches &&
+    (!focused ||
+      focused === document.body ||
+      focused.matches("[data-cloud-shell-focus-toggle]") ||
+      !focused.isConnected ||
+      focused.getClientRects().length === 0)
+  ) {
+    element.querySelector<HTMLElement>(`[data-cloud-shell-focus-toggle="${hidden ? "show" : "hide"}"]`)?.focus({ preventScroll: true });
+  }
+};
+
+export const toggleShellFocus = (): void => setShellFocus(!readShellFocus());
+
+/** Delegation also handles the server's buttons before their islands hydrate. */
+export const attachShellFocusControls = (): (() => void) => {
+  const click = (event: MouseEvent) => {
+    if (!(event.target instanceof Element)) return;
+    const button = event.target.closest<HTMLElement>("[data-cloud-shell-focus-toggle]");
+    if (button) setShellFocus(button.dataset.cloudShellFocusToggle === "hide");
+  };
+  let drag: { pointerId: number; x: number; y: number } | undefined;
+  const start = (event: PointerEvent) => {
+    if (event.pointerType === "mouse" || !(event.target instanceof Element) || !event.target.closest("[data-cloud-shell-reveal]")) return;
+    drag = { pointerId: event.pointerId, x: event.clientX, y: event.clientY };
+  };
+  const move = (event: PointerEvent) => {
+    if (!drag || event.pointerId !== drag.pointerId) return;
+    const dx = event.clientX - drag.x;
+    if (dx >= 40 && dx > Math.abs(event.clientY - drag.y)) {
+      drag = undefined;
+      setShellFocus(false);
+    }
+  };
+  const stop = (event: PointerEvent) => {
+    if (event.pointerId === drag?.pointerId) drag = undefined;
+  };
+  document.addEventListener("click", click);
+  document.addEventListener("pointerdown", start);
+  window.addEventListener("pointermove", move);
+  window.addEventListener("pointerup", stop);
+  window.addEventListener("pointercancel", stop);
+  return () => {
+    document.removeEventListener("click", click);
+    document.removeEventListener("pointerdown", start);
+    window.removeEventListener("pointermove", move);
+    window.removeEventListener("pointerup", stop);
+    window.removeEventListener("pointercancel", stop);
+    drag = undefined;
+  };
+};

package/src/cli/commands.ts

@@ -244,6 +244,8 @@ export const readCliInput = async (input: CliInputFlagValue, options: ReadCliInp
 
 export const defineCliCommands = (config: CliCommandsConfig): CloudCliModule => {
   const root = buildCommandTree(config.commands, config.groupSummaries);
+  // `cld <module> reference` prints the module's skill references instead.
+  if (root.children.has("reference")) throw new Error(`CLI module "${config.name}" must not declare the reserved command "reference"`);
   if (config.alias !== undefined && !isCloudCliAlias(config.alias, config.name)) {
     throw new Error("CLI alias must be a lowercase kebab-case name different from the module name");
   }

package/src/cli/plugin.ts

@@ -1,6 +1,6 @@
 /**
- * `cld` plugin contract shared by the applications that serve plugins and by
- * `cld`, which installs and loads them.
+ * Verified `cld` bundle contract shared by application-served plugins,
+ * package plugins, and `cld`, which installs and loads them.
  *
  * An application serves each declared CLI module under
  * `/cli/plugins/<name>/`: `manifest.json`, the bundled module `cli.js`, and
@@ -34,9 +34,9 @@ export type CloudCliPluginManifest = {
   apiVersion: number;
   /** Module name and plugin ID. */
   name: string;
-  /** ID of the application that serves the plugin. */
+  /** ID of the serving application, or name of the publishing package. */
   app: string;
-  /** Version of the serving application build. */
+  /** Application build or package version. */
   version: string;
   entry: typeof CLOUD_CLI_PLUGIN_ENTRY;
   /** SHA-512 over the file list; see {@link cloudCliPluginDigest}. */
@@ -88,7 +88,7 @@ export const isCloudCliShortcuts = (value: unknown, name: string, alias?: string
         .every((segment) => !segment.startsWith("-")),
   );
 
-/** Validate a served manifest, including its digest. Throws an `Error` naming the first problem. */
+/** Validate a bundle manifest, including its digest. Throws an `Error` naming the first problem. */
 export const parseCloudCliPluginManifest = (value: unknown): CloudCliPluginManifest => {
   if (!isRecord(value)) throw new Error("plugin manifest is not an object");
   const { apiVersion, name, app, version, entry, digest, files } = value;

package/src/services/index.ts

@@ -221,6 +221,7 @@ export type {
 
 export {
   NetworkTargetBlockedError,
+  isNetworkTargetBlocked,
   pinnedNetworkLookup,
   resolvePublicNetworkAddresses,
   resolveAllowedNetworkAddresses,