@vellumai/assistant 0.11.8 → 0.11.9-staging.1

package/src/runtime/routes/platform-routes.ts

@@ -5,8 +5,9 @@
  *   - platform_status (GET platform/status): aggregates platform context,
  *     credentials, assistant ID, and webhook secret. (Velay tunnel status
  *     lives on the gateway — see gateway_status.)
- *   - platform_connect (POST platform/connect): checks existing credentials
- *     and emits the show_platform_login signal to connected clients.
+ *   - platform_connect (POST platform/connect): reports whether the stored
+ *     credentials still connect, and when the stored key has been rejected,
+ *     says so, so the caller can tell the user what replaces it.
  *   - platform_disconnect (POST platform/disconnect): deletes stored platform
  *     credentials and emits platform_disconnected signal.
  *   - platform_callback_routes_register (POST platform/callback-routes/register):
@@ -24,6 +25,11 @@
  *     invoice list and returns a single invoice by Stripe invoice ID.
  */
 
+import {
+  type PlatformCredentialVerificationStatus,
+  type PlatformVerifyCredentialResponse,
+  PlatformVerifyCredentialResponseSchema,
+} from "@vellumai/service-contracts/platform-credential";
 import { z } from "zod";
 
 import { isPlatformRemote } from "../../config/env-registry.js";
@@ -80,8 +86,16 @@ const PlatformConnectResponseSchema = z.object({
   alreadyConnected: z.boolean().optional(),
   baseUrl: z.string().optional(),
   showPlatformLogin: z.boolean().optional(),
+  /**
+   * The stored managed credential exists but the platform rejects it. Distinct
+   * from "nothing stored": the user is not setting up, they are recovering,
+   * and what replaces the key is a fresh sign-in, not a first one.
+   */
+  credentialRejected: z.boolean().optional(),
 });
-type PlatformConnectResponse = z.infer<typeof PlatformConnectResponseSchema>;
+export type PlatformConnectResponse = z.infer<
+  typeof PlatformConnectResponseSchema
+>;
 
 const PlatformDisconnectResponseSchema = z.object({
   disconnected: z.literal(true),
@@ -249,17 +263,72 @@ async function handlePlatformConnect(
     ),
   ]);
 
+  // Stored credentials only count as a connection while they still
+  // authenticate. Answering "already connected" for a key the platform has
+  // rejected would report nothing to do about the one thing that needs doing,
+  // and no client would get the signal to rotate it.
+  //
+  // Checked here rather than read from a cache: connect is a deliberate user
+  // action, so one request is affordable, and an answer computed now cannot go
+  // stale between the check and the answer. An unreachable platform leaves the
+  // stored credentials counting as a connection, so a network problem never
+  // strands a working install by reporting it disconnected.
+  let credentialRejected = false;
   if (existingUrl && existingApiKey) {
-    return {
-      alreadyConnected: true,
-      baseUrl: existingUrl,
-    };
+    const verified = await verifyStoredCredential();
+    if (verified !== "rejected") {
+      return {
+        alreadyConnected: true,
+        baseUrl: existingUrl,
+      };
+    }
+    credentialRejected = true;
   }
 
-  // Emit signal for connected clients to show the platform login UI
+  // The outcome travels in the response, where the CLI reads it and tells the
+  // user what to do. Nothing shipped consumes the signal below, so the
+  // response is the only path the answer reaches anyone by.
   broadcastMessage({ type: "show_platform_login" });
 
-  return { showPlatformLogin: true };
+  return credentialRejected
+    ? { showPlatformLogin: true, credentialRejected: true }
+    : { showPlatformLogin: true };
+}
+
+/**
+ * Ask the platform whether the stored managed credential authenticates.
+ * Nothing is stored: each caller that needs the answer asks, so there is no
+ * verdict to go stale.
+ *
+ * Shared by the verification route and by connect, so the two cannot disagree
+ * about what "connected" means. Never throws: an unsettled answer is
+ * `"unknown"`, which no caller treats as evidence of a dead credential.
+ */
+async function verifyStoredCredential(): Promise<PlatformCredentialVerificationStatus> {
+  try {
+    const { checkAssistantApiKey } =
+      await import("../../credential-health/credential-health-service.js");
+    const result = await checkAssistantApiKey();
+    if (result === null) {
+      // No platform identity at all, so there is nothing to verify.
+      return "unknown";
+    }
+    if (result.status === "healthy") {
+      return "valid";
+    }
+    if (result.status === "revoked" || result.status === "missing_token") {
+      return "rejected";
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+
+async function handlePlatformVerifyCredential(
+  _args: RouteHandlerArgs,
+): Promise<PlatformVerifyCredentialResponse> {
+  return { status: await verifyStoredCredential() };
 }
 
 async function handlePlatformDisconnect(
@@ -711,11 +780,31 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Connect to the Vellum Platform",
     description:
-      "Checks existing credentials and emits the show_platform_login signal for connected clients to show a login UI.",
+      "Checks whether the stored platform credentials still connect. Reports a stored key the platform rejects as credentialRejected, so the caller can direct the user to sign in again and replace it.",
     tags: ["platform"],
     handler: handlePlatformConnect,
     responseBody: PlatformConnectResponseSchema,
   },
+  {
+    operationId: "platform_verify_credential",
+    endpoint: "platform/verify-credential",
+    method: "POST",
+    // The in-app repair calls this through the gateway with an actor token,
+    // the same caller shape as platform_status, so it takes that route's
+    // principal bundle. A local-only policy would 403 every browser repair
+    // after it had already rotated and stored the replacement. Read scope:
+    // the route performs a check and mutates nothing.
+    policy: {
+      requiredScopes: ["settings.read"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Verify the Vellum-managed credential against the platform",
+    description:
+      "Asks the platform whether the stored assistant API key authenticates. POST because it performs a check; the result is returned, not stored.",
+    tags: ["platform"],
+    handler: handlePlatformVerifyCredential,
+    responseBody: PlatformVerifyCredentialResponseSchema,
+  },
   {
     operationId: "platform_disconnect",
     endpoint: "platform/disconnect",

package/src/runtime/routes/sight-frame-routes.ts

@@ -0,0 +1,136 @@
+/**
+ * Transport-agnostic route definition for ambient camera keeps.
+ *
+ * POST /v1/conversations/:id/sight-frame persists one already-uploaded camera
+ * frame into a conversation as its own sight-tagged user message. It runs no
+ * turn and starts no agent loop: it is the same standalone-image persist the
+ * live-voice `sight_frame` socket frame performs, reached over HTTP by the
+ * clients that have a camera tile but no voice socket. The rationale for
+ * persisting a kept frame on its own rather than attaching it to a turn is at
+ * the top of `live-voice/live-voice-photo.ts`.
+ *
+ * The response is the client's per-frame acknowledgement, which is why the
+ * handler waits on the persist rather than accepting and reporting later.
+ */
+
+import { z } from "zod";
+
+import { persistAmbientSightFrame } from "../../live-voice/live-voice-photo.js";
+import { getConversation } from "../../persistence/conversation-crud.js";
+import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { resolveOrThrow } from "./conversation-management-routes.js";
+import { BadRequestError, NotFoundError } from "./errors.js";
+import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
+import { resolveVellumActorTrustContext } from "./vellum-actor-trust.js";
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Persist a kept camera frame into an existing conversation.
+ *
+ * The DB existence check comes before the persist because the persist calls
+ * `getOrCreateConversation`, which mints a conversation for an id it has never
+ * seen. Without the gate a stale client id would silently create a phantom
+ * conversation holding nothing but camera frames.
+ *
+ * That read is also where the frame is accepted, so the row's `created_at` is
+ * taken from it and handed to the persist. Resolving the request's actor is
+ * awaited below, and a conversation deleted and recreated under this id inside
+ * that await leaves a row the gate never saw: the persist reading the id for
+ * itself afterwards would take the replacement for the conversation the client
+ * addressed. Nothing awaits between the check and the capture, so the two are
+ * one moment.
+ *
+ * The body is hand-validated because the HTTP adapter does not run a route's
+ * zod schema against the request and swallows a JSON parse failure, so a
+ * malformed send arrives here as an empty bag.
+ */
+async function handleConversationSightFrame({
+  pathParams = {},
+  body = {},
+  headers,
+}: RouteHandlerArgs) {
+  const rawId = pathParams.id!;
+  const conversationId = resolveOrThrow(rawId);
+  const accepted = getConversation(conversationId);
+  if (!accepted) {
+    throw new NotFoundError(`Conversation ${rawId} not found`);
+  }
+
+  const attachmentId = body.attachmentId;
+  if (typeof attachmentId !== "string" || attachmentId.length === 0) {
+    throw new BadRequestError("Missing attachmentId");
+  }
+
+  // The row is attributed to the actor this request was verified as, resolved
+  // the way every other vellum-channel route resolves it. Left to the
+  // conversation's resting trust, a frame would be stamped for whoever used
+  // the conversation last.
+  const trustContext = await resolveVellumActorTrustContext(
+    headers?.["x-vellum-actor-principal-id"],
+    { healResetDrift: true },
+  );
+
+  // Every non-fatal outcome the persist folds into `ok` is reported as a
+  // refusal rather than an error status: the frame is gone either way, the
+  // client's only move is to keep sampling, and the upload behind each one is
+  // the persist's to settle. It gives the bytes up as it refuses, or, where
+  // the store would not say whether a row landed, holds them until it answers
+  // and gives them up then. Either way the client is done with the frame,
+  // which is what the two-state response means.
+  const result = await persistAmbientSightFrame(
+    conversationId,
+    attachmentId,
+    "chat",
+    trustContext,
+    accepted.createdAt,
+  );
+  return {
+    persisted: result.ok,
+    ...(result.messageId === undefined ? {} : { messageId: result.messageId }),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Route definitions
+// ---------------------------------------------------------------------------
+
+export const ROUTES: RouteDefinition[] = [
+  {
+    operationId: "conversationSightFrame",
+    endpoint: "conversations/:id/sight-frame",
+    method: "POST",
+    policy: {
+      requiredScopes: ["chat.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    summary: "Persist an ambient camera frame",
+    description:
+      "Add an already-uploaded camera frame to a conversation as its own " +
+      "message, tagged so retention can age the image out of the model's " +
+      "context while the transcript keeps it. No reply is generated. " +
+      "Returns persisted=false when the frame was dropped, in which case the " +
+      "assistant owns the upload and there is nothing to clean up.",
+    tags: ["conversations"],
+    pathParams: [{ name: "id", type: "uuid" }],
+    requestBody: z.object({
+      attachmentId: z
+        .string()
+        .describe("Id of the uploaded attachment holding the frame."),
+    }),
+    responseBody: z.object({
+      persisted: z.boolean(),
+      messageId: z
+        .string()
+        .optional()
+        .describe("The message the frame landed on, when one was written."),
+    }),
+    additionalResponses: {
+      "400": { description: "Missing or empty attachmentId" },
+      "404": { description: "Conversation not found" },
+    },
+    handler: handleConversationSightFrame,
+  },
+];

package/src/runtime/sync/resource-sync-events.ts

@@ -1,4 +1,3 @@
-import type { ConversationListInvalidatedReason } from "../../api/events/conversation-list-invalidated.js";
 import type { IdentityFields } from "../../daemon/handlers/identity.js";
 import {
   conversationMessagesSyncTag,
@@ -160,42 +159,23 @@ export function publishPluginsChanged(originClientId?: string): void {
  * delivered exclusively via the per-conversation `sync_changed` tag, which
  * web consumes by GET-and-patching the single row.
  */
-const SHAPE_CHANGING_REASONS: ReadonlySet<ConversationListInvalidatedReason> =
-  new Set(["created", "deleted", "reordered"]);
+type ConversationListReason =
+  | "created"
+  | "renamed"
+  | "deleted"
+  | "reordered"
+  | "seen_changed";
 
-/**
- * Publish the legacy `conversation_list_invalidated` broadcast to macOS
- * subscribers only.
- *
- * Web consumes `sync_changed` (`conversationsList` for shape changes,
- * `conversation:<id>:metadata` for content changes) directly and patches
- * the cached list in place — see `useConversationSync` for the consumer
- * side. macOS (`ConversationRestorer.swift`) still listens for the typed
- * broadcast.
- *
- * TODO(electron-cutover): remove this helper and all callers once macOS
- * migrates to the Electron client and consumes `sync_changed` directly.
- * At that point the `conversation_list_invalidated` message type can be
- * retired entirely.
- */
-function broadcastConversationListInvalidatedToMacos(
-  reason: ConversationListInvalidatedReason,
-): void {
-  broadcastMessage(
-    {
-      type: "conversation_list_invalidated",
-      reason,
-    },
-    undefined,
-    { targetInterfaceId: "macos" },
-  );
-}
+const SHAPE_CHANGING_REASONS: ReadonlySet<ConversationListReason> = new Set([
+  "created",
+  "deleted",
+  "reordered",
+]);
 
 export function publishConversationListChanged(
-  reason: ConversationListInvalidatedReason,
+  reason: ConversationListReason,
   originClientId?: string,
 ): void {
-  broadcastConversationListInvalidatedToMacos(reason);
   void publishSyncInvalidation([SYNC_TAGS.conversationsList], originClientId);
 }
 
@@ -220,14 +200,13 @@ export function publishConversationMessagesChanged(
 }
 
 export function publishConversationListAndMetadataChanged(
-  reason: ConversationListInvalidatedReason,
+  reason: ConversationListReason,
   conversationIds: string | string[],
   originClientId?: string,
 ): void {
   const ids = Array.isArray(conversationIds)
     ? conversationIds
     : [conversationIds];
-  broadcastConversationListInvalidatedToMacos(reason);
 
   // Shape-changing reasons (`created`, `deleted`, `reordered`) add or
   // remove rows or change the order of the paginated window — web must
@@ -260,9 +239,7 @@ export function publishConversationTitleChanged(
     conversationId,
   );
   // Renames are content-only — the paired typed `conversation_title_updated`
-  // event already carries the new title and patches the row in place on
-  // web; macOS receives the per-interface `conversation_list_invalidated`
-  // emitted from `broadcastMessage` (see `assistant-event-hub.ts`). The
+  // event already carries the new title and patches the row in place; the
   // `sync_changed` metadata tag is included as a belt-and-suspenders signal
   // for any sibling-tab consumer that missed the typed event.
   void publishSyncInvalidation(

package/src/runtime/sync/sync-publisher.test.ts

@@ -78,7 +78,7 @@ describe("sync publisher", () => {
     const subscription = assistantEventHub.subscribe({
       type: "process",
       callback: async (event) => {
-        if (event.message.type === "conversation_list_invalidated") {
+        if (event.message.type === "conversation_title_updated") {
           await new Promise((resolve) => setTimeout(resolve, 25));
         }
         receivedTypes.push(event.message.type);
@@ -87,15 +87,16 @@ describe("sync publisher", () => {
 
     try {
       broadcastMessage({
-        type: "conversation_list_invalidated",
-        reason: "created",
+        type: "conversation_title_updated",
+        conversationId: "conv-1",
+        title: "Test",
       });
       await publishSyncInvalidation([SYNC_TAGS.conversationsList]);
 
       await waitFor(() => receivedTypes.length === 2);
 
       expect(receivedTypes).toEqual([
-        "conversation_list_invalidated",
+        "conversation_title_updated",
         "sync_changed",
       ]);
     } finally {

package/src/tools/__tests__/tool-input-schemas.test.ts

@@ -14,6 +14,7 @@ import { notifyParentTool } from "../subagent/notify-parent.js";
 import { requestSystemPermissionTool } from "../system/request-permission.js";
 import { shellTool } from "../terminal/shell.js";
 import { parseToolInput, TOOL_INPUT_SCHEMAS } from "../tool-input-schemas.js";
+import { watchRetroReportTool } from "../watch/watch-retro-report.js";
 
 describe("parseToolInput", () => {
   test("passes input through unchanged for a tool with no registered schema", () => {
@@ -142,6 +143,7 @@ describe("derived input_schema", () => {
     requestSystemPermissionTool,
     notifyParentTool,
     reactToMessageTool,
+    watchRetroReportTool,
   ];
 
   test("every registered schema belongs to a tool whose input_schema is derived from it", () => {

package/src/tools/client-os.ts

@@ -13,6 +13,15 @@ interface HostClientContext {
   sourceActorPrincipalId?: string;
 }
 
+export function desktopClientName(
+  context: HostClientContext,
+): "Windows" | "macOS" {
+  return context.clientOs === "windows" ||
+    context.transportInterface === "windows"
+    ? "Windows"
+    : "macOS";
+}
+
 export function supportsClientOs(
   supportedClientOs: readonly ClientOs[] | undefined,
   clientOs: ClientOs | undefined,
@@ -43,7 +52,8 @@ export function getEligibleHostClientOs(
   const eligible = new Set<ClientOs>();
   const sourceClientOs =
     context.transportInterface === "macos" ||
-    context.transportInterface === "windows"
+    context.transportInterface === "windows" ||
+    context.transportInterface === "linux"
       ? context.transportInterface
       : context.clientOs;
   if (

package/src/tools/host-filesystem/edit.ts

@@ -4,6 +4,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import { desktopClientName } from "../client-os.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatEditDiff } from "../shared/filesystem/format-diff.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
@@ -114,8 +115,7 @@ export const hostFileEditTool = {
       !HostFileProxy.instance.isAvailable()
     ) {
       return {
-        content:
-          "Error: no client with host_file capability is connected. Connect a macOS client to use host_file from a non-desktop interface.",
+        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
         isError: true,
       };
     }

package/src/tools/host-filesystem/read.ts

@@ -6,6 +6,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import { desktopClientName } from "../client-os.js";
 import {
   AUDIO_EXTENSIONS,
   readAudioFile,
@@ -120,8 +121,7 @@ export const hostFileReadTool = {
       !HostFileProxy.instance.isAvailable()
     ) {
       return {
-        content:
-          "Error: no client with host_file capability is connected. Connect a macOS client to use host_file from a non-desktop interface.",
+        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
         isError: true,
       };
     }

package/src/tools/host-filesystem/transfer.ts

@@ -6,6 +6,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostTransferProxy } from "../../daemon/host-transfer-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import { desktopClientName } from "../client-os.js";
 import { sandboxPolicy } from "../shared/filesystem/path-policy.js";
 import type {
   ToolContext,
@@ -124,8 +125,7 @@ export const hostFileTransferTool = {
       !HostTransferProxy.instance.isAvailable()
     ) {
       return {
-        content:
-          "Error: no client with host_file capability is connected. Connect a macOS client to use host_file from a non-desktop interface.",
+        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
         isError: true,
       };
     }

package/src/tools/host-filesystem/write.ts

@@ -4,6 +4,7 @@ import { supportsHostProxy } from "../../channels/types.js";
 import { HostFileProxy } from "../../daemon/host-file-proxy.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { assistantEventHub } from "../../runtime/assistant-event-hub.js";
+import { desktopClientName } from "../client-os.js";
 import { FileSystemOps } from "../shared/filesystem/file-ops-service.js";
 import { formatWriteSummary } from "../shared/filesystem/format-diff.js";
 import { hostPolicy } from "../shared/filesystem/path-policy.js";
@@ -89,8 +90,7 @@ export const hostFileWriteTool = {
       !HostFileProxy.instance.isAvailable()
     ) {
       return {
-        content:
-          "Error: no client with host_file capability is connected. Connect a macOS client to use host_file from a non-desktop interface.",
+        content: `Error: no client with host_file capability is connected. Connect a ${desktopClientName(context)} client to use host_file from a non-desktop interface.`,
         isError: true,
       };
     }

package/src/tools/host-terminal/host-shell.ts

@@ -39,6 +39,7 @@ import {
   registerBackgroundTool,
   removeBackgroundTool,
 } from "../background-tool-registry.js";
+import { desktopClientName } from "../client-os.js";
 import {
   attachBoundedStdio,
   MAX_OUTPUT_LENGTH,
@@ -225,8 +226,7 @@ export const hostShellTool = {
       !HostBashProxy.instance.isAvailable()
     ) {
       return {
-        content:
-          "Error: no client with host_bash capability is connected. Connect a macOS client to use host_bash from a non-desktop interface.",
+        content: `Error: no client with host_bash capability is connected. Connect a ${desktopClientName(context)} client to use host_bash from a non-desktop interface.`,
         isError: true,
       };
     }

package/src/tools/skills/load.ts

@@ -158,7 +158,7 @@ export const skillLoadTool = {
   name: "skill_load",
 
   description:
-    'Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and custom workspace skills. Bundled/first-party skills (like `app-builder`) are already installed — loading only activates their instructions for the current conversation, since skills unload between turns; treat "load" as activation, not installation, and don\'t tell users a bundled skill needs installing. Loading can still fail (e.g. a feature-gated skill returns "currently unavailable", or the load errors) — if it does, relay that specific error rather than claiming the skill is not installed or offering to install it. For app, website, dashboard, game, calculator, tracker, visualization, or interactive tool requests, load `app-builder` with `skill: "app-builder"`.',
+    'Load full instructions for a skill. Works for both bundled skills (listed in the catalog) and custom workspace skills. Bundled/first-party skills (like `app-builder`) are already installed: loading only activates their instructions for the current conversation, since skills unload between turns. Treat "load" as activation, not installation, and don\'t tell users a bundled skill needs installing. Loading can still fail (e.g. a feature-gated skill returns "currently unavailable", or the load errors). If it does, relay that specific error rather than claiming the skill is not installed or offering to install it. For app, website, dashboard, game, calculator, tracker, visualization, or interactive tool requests, load `app-builder` with `skill: "app-builder"`. For recurring monitoring of a page, dashboard, or status (check it later and notify), or for reminders and timed checks, load `schedule` with `skill: "schedule"`. When the user names Claude Code or Codex (including as a tool they will use elsewhere), load `acp` with `skill: "acp"`.',
 
   category: "skills",
 

package/src/tools/terminal/safe-env.ts

@@ -116,6 +116,10 @@ function isKataFamilyRuntime(runtime: string | undefined): boolean {
 
 function kataAptPaths(dataRoot: string): string[] {
   return [
+    // Shims for chroot wrapper scripts with hardcoded absolute paths must
+    // shadow the broken originals in the chroot bin dirs below (see
+    // docker-kata-apt-shims.sh).
+    `${dataRoot}/.host-shims`,
     `${dataRoot}/bin`,
     `${dataRoot}/usr/local/sbin`,
     `${dataRoot}/usr/local/bin`,

package/src/tools/tool-input-schemas.ts

@@ -14,6 +14,7 @@ import { formatToolInputError } from "./shared/zod-tool-schema.js";
 import { notifyParentInputSchema } from "./subagent/notify-parent.js";
 import { requestSystemPermissionInputSchema } from "./system/request-permission.js";
 import { shellInputSchema } from "./terminal/shell.js";
+import { watchRetroReportInputSchema } from "./watch/watch-retro-report.js";
 
 /**
  * Per-tool Zod input schemas, keyed by tool name. Tool calls are a
@@ -57,6 +58,7 @@ export const TOOL_INPUT_SCHEMAS: Readonly<Record<string, z.ZodType>> = {
   host_file_read: hostFileReadInputSchema,
   host_file_write: hostFileWriteInputSchema,
   notify_parent: notifyParentInputSchema,
+  watch_retro_report: watchRetroReportInputSchema,
   react_to_message: reactToMessageInputSchema,
   request_system_permission: requestSystemPermissionInputSchema,
 };

package/src/tools/tool-manifest.ts

@@ -36,6 +36,7 @@ import {
   uiShowTool,
   uiUpdateTool,
 } from "./ui-surface/definitions.js";
+import { watchRetroReportTool } from "./watch/watch-retro-report.js";
 
 // ── Explicit tool instances ─────────────────────────────────────────
 // Core tools registered by initializeTools(). Tool modules only export
@@ -75,4 +76,5 @@ export const explicitTools: ToolDefinition[] = [
   uiShowTool,
   uiUpdateTool,
   uiDismissTool,
+  watchRetroReportTool,
 ];

package/src/tools/ui-surface/definitions.ts

@@ -2,7 +2,7 @@
  * UI surface tool definitions.
  *
  * These tools allow the model to show, update, and dismiss just-in-time UI
- * surfaces (cards, tables, forms, confirmations) on a connected macOS client.
+ * surfaces (cards, tables, forms, confirmations) on a connected desktop client.
  * They are proxy tools -- execution is forwarded to the client and never
  * handled locally by the daemon.
  */
@@ -13,6 +13,7 @@ import {
 } from "../../api/surfaces.js";
 import { RiskLevel } from "../../permissions/types.js";
 import { isWeakOpenModel } from "../../providers/weak-open-model.js";
+import { desktopClientName } from "../client-os.js";
 import type {
   ToolContext,
   ToolDefinition,
@@ -37,7 +38,7 @@ const APP_BUILDER_BUILD_RE =
   /\b(build|building|built|create|creating|created|make|making|made|generate|generating|generated)\b/i;
 
 /**
- * Forward execution to the connected macOS client via the request-bound
+ * Forward execution to the connected desktop client via the request-bound
  * `proxyToolResolver`. Returns a structured error when no resolver is
  * configured (e.g. no client connected) so callers see a normal tool
  * failure rather than an unhandled throw.
@@ -88,7 +89,7 @@ function proxyExecute(toolName: string) {
 
     if (!context.proxyToolResolver) {
       return {
-        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires an external resolver (e.g. a connected macOS client).`,
+        content: `No proxy resolver configured for proxy tool "${toolName}". This tool requires an external resolver (e.g. a connected ${desktopClientName(context)} client).`,
         isError: true,
       };
     }