@vellumai/assistant 0.12.2-staging.1 → 0.12.2-staging.2

package/src/live-voice/session-controls.ts

@@ -0,0 +1,111 @@
+import {
+  END_CALL_MARKER,
+  FEWER_UPDATES_MARKER,
+  MUTE_MARKER,
+  NORMAL_UPDATES_MARKER,
+  parseTerminalSessionControl,
+  type SessionControlRequest,
+} from "../calls/voice-control-protocol.js";
+import type { VoiceProgressConfig } from "../config/schemas/voice.js";
+import type { LiveVoiceSessionControl } from "./protocol.js";
+
+/**
+ * Spoken session controls: the user asks out loud to end the call, mute their
+ * microphone, or hear fewer progress updates, the reply acknowledges it and
+ * ends with a marker, and the session carries it out once that
+ * acknowledgement has been spoken.
+ *
+ * A marker rather than a tool, because these are the turns a front-door leg
+ * answers on its own: "okay, I'm gonna go" should not wait on an escalation to
+ * a stronger model before the call can end. The marker is judged by the
+ * model, never by matching the user's words, so "I'm all done with that
+ * email" does not hang up.
+ */
+
+const CLIENT_CONTROL_LINES: Record<LiveVoiceSessionControl, string> = {
+  end: `- To end the call (for example "I'm all done" or "okay, I'm gonna go"), say a brief goodbye, then end your reply with ${END_CALL_MARKER}. Being done with a task is not the same as leaving the call; end only when they are leaving.`,
+  mute: `- To mute their microphone (for example "mute for 30 seconds" or "mute yourself, I need to take this"), confirm in a few words, then end your reply with [MUTE:<seconds>] when they gave a duration or ${MUTE_MARKER} when they did not. While muted you cannot hear them, so mention they can unmute from the call controls unless the mute is timed.`,
+};
+
+// Always taught: narration is the session's own, so no client has to be able
+// to carry it out.
+const UPDATES_LINE = `- To hear fewer spoken progress updates while you work (for example "don't give me updates so often"), confirm that you will only check in now and then and will tell them when it is done, then end your reply with ${FEWER_UPDATES_MARKER}. If they later want regular updates back, confirm and end with ${NORMAL_UPDATES_MARKER}.`;
+
+/**
+ * The control-prompt block that teaches the session controls: the ones the
+ * client declared plus the progress-update cadence. Every leg gets it,
+ * including the toolless front-door leg: these turns are its to answer.
+ *
+ * The no-other-markers rule is withheld from the front-door leg, whose
+ * routing rule teaches it leading verdict tokens and already confines
+ * everything else to speech.
+ */
+export function sessionControlTeaching(
+  controls: readonly LiveVoiceSessionControl[],
+  leg: { frontDoor?: boolean },
+): string {
+  return [
+    "The user can also control this call by asking you. Only when they clearly ask:",
+    ...controls.map((control) => CLIENT_CONTROL_LINES[control]),
+    UPDATES_LINE,
+    `The marker must be the very last thing in your reply. It is never spoken and does nothing anywhere else.${leg.frontDoor === true ? "" : " Never emit any other bracketed marker."}`,
+  ].join("\n");
+}
+
+/** A session control the client carries out, sent as a `session_control` frame. */
+export type ClientSessionControlRequest = Exclude<
+  SessionControlRequest,
+  { action: "updates" }
+>;
+
+/**
+ * The control a completed leg's raw text asks for; null when there is none or
+ * when it is a client control the client did not declare. An undeclared
+ * control is dropped rather than sent: the client said it cannot carry it out.
+ * The update cadence always passes, since the session carries it out itself.
+ */
+export function requestedSessionControl(
+  rawText: string,
+  controls: readonly LiveVoiceSessionControl[],
+): SessionControlRequest | null {
+  const request = parseTerminalSessionControl(rawText);
+  if (request === null) {
+    return null;
+  }
+  if (request.action === "updates") {
+    return request;
+  }
+  return controls.includes(request.action) ? request : null;
+}
+
+/**
+ * Silence (ms) a session that asked for fewer updates waits through before a
+ * progress update. Long enough that a minute-long task runs without a word;
+ * short enough that a really long one still proves the call is alive.
+ */
+export const FEWER_UPDATES_INTERVAL_MS = 60_000;
+
+/**
+ * The progress config a turn runs on under the session's update cadence.
+ *
+ * Fewer updates means no update for tool activity (a burst of ops or a long
+ * op finishing, each normally its own beat) and the silence tick stretched to
+ * {@link FEWER_UPDATES_INTERVAL_MS}, so the only thing that speaks is a long
+ * stretch of silence. Done is still said: the reply itself is the "it's done".
+ */
+export function progressConfigForCadence(
+  config: VoiceProgressConfig,
+  cadence: "fewer" | "normal",
+): VoiceProgressConfig {
+  if (cadence === "normal") {
+    return config;
+  }
+  const intervalMs = Math.max(FEWER_UPDATES_INTERVAL_MS, config.maxSilenceMs);
+  return {
+    ...config,
+    opsThreshold: Number.MAX_SAFE_INTEGER,
+    longOpMs: Number.MAX_SAFE_INTEGER,
+    idleIntervalMs: intervalMs,
+    maxSilenceMs: intervalMs,
+  };
+}

package/src/oauth/__tests__/seed-providers-managed.test.ts

@@ -60,6 +60,26 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
       );
     }
 
+    // `folders:read` is documented too, but the app's scope picker only
+    // offers `folder_metadata:read` under Folders, so Figma answers
+    // "Invalid scopes for app" whenever it is requested.
+    expect(figma.defaultScopes).not.toContain("folders:read");
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "folders:read",
+      );
+    }
+
+    // `file_code_connect:write` is only offered to apps owned by an
+    // Organization-plan team. Managed apps in other environments are not,
+    // so requesting it fails the whole authorization there.
+    expect(figma.defaultScopes).not.toContain("file_code_connect:write");
+    if (Array.isArray(availableScopes)) {
+      expect(availableScopes.map(({ scope }) => scope)).toContain(
+        "file_code_connect:write",
+      );
+    }
+
     // GET /v1/me backs both the ping and the identity label.
     expect(figma.defaultScopes).toContain("current_user:read");
   });
@@ -181,6 +201,81 @@ describe("PROVIDER_SEED_DATA managed mode wiring", () => {
     expect(template?.hostPattern).toBe("*.myshopify.com");
   });
 
+  test("quickbooks is wired up for managed mode behind its flag", () => {
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks).toBeDefined();
+    expect(quickbooks.managedServiceConfigKey).toBe("quickbooks-oauth");
+    expect("quickbooks-oauth" in ServicesSchema.shape).toBe(true);
+    // Hidden until the platform side and client ids are live, like Figma
+    // and Shopify.
+    expect(quickbooks.featureFlag).toBe("quickbooks-oauth");
+  });
+
+  test("quickbooks uses Intuit's OAuth endpoints with HTTP Basic", () => {
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.authorizeUrl).toBe(
+      "https://appcenter.intuit.com/connect/oauth2",
+    );
+    expect(quickbooks.tokenExchangeUrl).toBe(
+      "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    );
+    expect(quickbooks.refreshUrl).toBe(quickbooks.tokenExchangeUrl);
+    expect(quickbooks.tokenEndpointAuthMethod).toBe("client_secret_basic");
+  });
+
+  test("quickbooks keeps its per-company URL templates", () => {
+    // Every Accounting API path is scoped to the realm the user picked on
+    // Intuit's consent screen. The platform fills {realm_id} from the
+    // connection; a hardcoded realm here would send every company's calls
+    // to the wrong books.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    for (const url of [quickbooks.baseUrl, quickbooks.identityUrl]) {
+      expect(url).toContain("/v3/company/{realm_id}");
+    }
+  });
+
+  test("quickbooks seeds no ping or revoke URL", () => {
+    // The ping route sends the URL's origin as a base override and cannot
+    // fill {realm_id}; the daemon's revoke helper posts an unauthenticated
+    // form body that Intuit's JSON + Basic-auth endpoint rejects. Either
+    // would fail silently on every your-own connection.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.pingUrl).toBeUndefined();
+    expect(quickbooks.revokeUrl).toBeUndefined();
+  });
+
+  test("quickbooks requests only the accounting scope by default", () => {
+    // Payments needs a Payments-enabled app and the OpenID scopes only add
+    // the user's profile; requesting either widens the consent screen for
+    // nothing the Accounting API needs.
+    const quickbooks = PROVIDER_SEED_DATA.quickbooks;
+    expect(quickbooks.defaultScopes).toEqual([
+      "com.intuit.quickbooks.accounting",
+    ]);
+    const available = quickbooks.availableScopes;
+    expect(Array.isArray(available)).toBe(true);
+    if (Array.isArray(available)) {
+      expect(available.map(({ scope }) => scope)).toContain(
+        "com.intuit.quickbooks.payment",
+      );
+    }
+  });
+
+  test("quickbooks allows the credential on both Intuit API hosts", () => {
+    // Development keys only work against sandbox companies, which live on
+    // the sandbox host. Both hosts belong to Intuit and take the same
+    // bearer token.
+    const templates = PROVIDER_SEED_DATA.quickbooks.injectionTemplates ?? [];
+    expect(templates.map((t) => t.hostPattern).sort()).toEqual([
+      "quickbooks.api.intuit.com",
+      "sandbox-quickbooks.api.intuit.com",
+    ]);
+    for (const template of templates) {
+      expect(template.headerName).toBe("Authorization");
+      expect(template.valuePrefix).toBe("Bearer ");
+    }
+  });
+
   test("every managedServiceConfigKey resolves to a ServicesSchema key", () => {
     // Cross-repo invariant: a provider with managedServiceConfigKey but no
     // matching ServicesSchema entry silently falls back to BYO mode in

package/src/oauth/connection-resolver.test.ts

@@ -72,6 +72,7 @@ import { setConfig } from "../__tests__/helpers/set-config.js";
 import { BYOOAuthConnection } from "./byo-connection.js";
 import {
   formatNoConnectionError,
+  platformProxyBaseUrl,
   resolveEffectiveBaseUrl,
   resolveOAuthConnection,
   resolveOAuthConnectionWithMeta,
@@ -755,6 +756,32 @@ describe("resolveEffectiveBaseUrl", () => {
   });
 });
 
+describe("platformProxyBaseUrl", () => {
+  test("forwards a concrete seed base URL", () => {
+    expect(platformProxyBaseUrl("https://api.figma.com")).toBe(
+      "https://api.figma.com",
+    );
+  });
+
+  test("withholds a templated base URL so the platform fills it", () => {
+    // Shopify's host and QuickBooks' realm are pinned to the connection on
+    // the platform. Forwarding the unfilled template would fail the proxy's
+    // allowlist check and shadow the platform's own default.
+    expect(platformProxyBaseUrl("https://{tenant_host}")).toBeUndefined();
+    expect(
+      platformProxyBaseUrl(
+        "https://quickbooks.api.intuit.com/v3/company/{realm_id}",
+      ),
+    ).toBeUndefined();
+  });
+
+  test("treats a missing base URL as no override", () => {
+    expect(platformProxyBaseUrl(undefined)).toBeUndefined();
+    expect(platformProxyBaseUrl(null)).toBeUndefined();
+    expect(platformProxyBaseUrl("")).toBeUndefined();
+  });
+});
+
 describe("resolveTokenHeader", () => {
   const shopify = JSON.stringify([
     {

package/src/oauth/connection-resolver.ts

@@ -129,7 +129,10 @@ export async function resolveOAuthConnectionWithMeta(
         accountInfo: resolution.accountLabel ?? account ?? null,
         client,
         connectionId: resolution.id,
-        baseUrl: providerRow?.baseUrl ?? undefined,
+        // A templated base URL (`https://{tenant_host}`, `.../{realm_id}`) is
+        // filled in by the platform from what it pinned to the connection;
+        // sent as-is it would fail the proxy's allowlist and shadow that.
+        baseUrl: platformProxyBaseUrl(providerRow?.baseUrl),
       });
       return {
         connection,
@@ -317,6 +320,24 @@ function hostMatchesPattern(host: string, pattern: string): boolean {
   return host === p;
 }
 
+/**
+ * The base URL a managed connection sends to the platform proxy, or
+ * `undefined` to let the proxy use the provider's configured default.
+ *
+ * Per-tenant and per-realm providers seed a template the platform fills from
+ * the connection (`{tenant_host}`, `{realm_id}`). Forwarding the unfilled
+ * template would fail the proxy's allowlist check, so those fall through to
+ * the platform's own default.
+ */
+export function platformProxyBaseUrl(
+  seedBaseUrl: string | null | undefined,
+): string | undefined {
+  if (!seedBaseUrl || /\{[a-z_]+\}/.test(seedBaseUrl)) {
+    return undefined;
+  }
+  return seedBaseUrl;
+}
+
 /**
  * Resolve the effective API base URL for a connection, preferring per-tenant
  * values stored on the connection's `metadata` over the provider's static
@@ -394,6 +415,9 @@ interface PlatformConnectionEntry {
   /** Scopes the platform actually granted this connection. May be absent for
    *  older connections or providers that don't report scopes. */
   scopes_granted?: string[] | null;
+  /** Provider-supplied values the connection is scoped by (QuickBooks'
+   *  `realm_id`). Absent from older platforms; empty for most providers. */
+  provider_params?: Record<string, string> | null;
 }
 
 interface PlatformConnectionResolution {

package/src/oauth/provider-serializer.ts

@@ -20,6 +20,8 @@ export type SerializedProvider = ReturnType<typeof serializeProvider> &
 
 import { isChannelBotProvider } from "@vellumai/service-contracts/channels";
 
+import { PROVIDER_SEED_DATA } from "./seed-providers.js";
+
 /**
  * Lightweight summary projection of an OAuth provider, suitable for API
  * list responses where full detail is not needed. All keys are snake_case
@@ -36,6 +38,12 @@ export interface SerializedProviderSummary {
   supports_managed_mode: boolean;
   managed_service_is_paid: boolean;
   feature_flag: string | null;
+  /**
+   * Per-tenant providers only (Shopify): what a client must collect before
+   * starting a managed connect, since the provider's OAuth endpoints live on
+   * the customer's own host. `null` for providers with one global host.
+   */
+  tenant_host: { pattern: string; label: string; placeholder: string } | null;
   /**
    * Which sense of "connected" this provider represents: `assistant` for a bot
    * credential people reach the assistant through, `user` for a grant letting
@@ -164,6 +172,7 @@ export function serializeProviderSummary(
     supports_managed_mode: !!row.managedServiceConfigKey,
     managed_service_is_paid: !!row.managedServiceIsPaid,
     feature_flag: row.featureFlag ?? null,
+    tenant_host: PROVIDER_SEED_DATA[row.provider]?.tenantHost ?? null,
     acts_as: isChannelBotProvider(row.provider) ? "assistant" : "user",
   };
 }

package/src/oauth/seed-providers.ts

@@ -90,6 +90,13 @@ export const PROVIDER_SEED_DATA: Record<
     }>;
     appType?: string;
     setupNotes?: string[];
+    /**
+     * Per-tenant providers only: the host the user supplies at connect time,
+     * which the platform substitutes into `{tenant_host}` URL placeholders.
+     * `pattern` mirrors the platform registry's validation so clients can
+     * reject a malformed host before the request leaves the browser.
+     */
+    tenantHost?: { pattern: string; label: string; placeholder: string };
     identityUrl?: string;
     identityMethod?: string;
     identityHeaders?: Record<string, string>;
@@ -1003,7 +1010,12 @@ export const PROVIDER_SEED_DATA: Record<
     // default, because Figma rejects the whole authorization request if the
     // app cannot grant a requested scope. `selections:read` is withheld for
     // that same reason: it is not offered in the app's OAuth scope list, so
-    // requesting it would fail the entire authorization.
+    // requesting it would fail the entire authorization. `folders:read` is
+    // withheld likewise: Figma documents it, but the app's scope picker only
+    // offers `folder_metadata:read` under Folders. `file_code_connect:write`
+    // is withheld because Figma only offers it to apps owned by an
+    // Organization-plan team, which not every managed app is, and nothing
+    // here uses Code Connect; it stays in availableScopes for BYO apps.
     defaultScopes: [
       "current_user:read",
       "file_content:read",
@@ -1013,7 +1025,6 @@ export const PROVIDER_SEED_DATA: Record<
       "file_comments:write",
       "file_dev_resources:read",
       "file_dev_resources:write",
-      "folders:read",
       "folder_metadata:read",
       "library_content:read",
       "library_assets:read",
@@ -1053,6 +1064,10 @@ export const PROVIDER_SEED_DATA: Record<
         scope: "file_dev_resources:write",
         description: "Write dev resources to files",
       },
+      {
+        scope: "file_code_connect:write",
+        description: "Write and change component code (Code Connect)",
+      },
       {
         scope: "folders:read",
         description: "List folders and files in folders",
@@ -1485,6 +1500,12 @@ export const PROVIDER_SEED_DATA: Record<
     ],
     loopbackPort: 17341,
     managedServiceConfigKey: "shopify-oauth",
+    // Mirrors `extra_config.tenant_host` in the platform provider registry.
+    tenantHost: {
+      pattern: "^[a-z0-9][a-z0-9-]*\\.myshopify\\.com$",
+      label: "Shop domain",
+      placeholder: "your-store.myshopify.com",
+    },
     injectionTemplates: [
       {
         hostPattern: "*.myshopify.com",
@@ -1508,6 +1529,93 @@ export const PROVIDER_SEED_DATA: Record<
     // cannot complete.
     featureFlag: "shopify-oauth",
   },
+
+  quickbooks: {
+    provider: "quickbooks",
+    authorizeUrl: "https://appcenter.intuit.com/connect/oauth2",
+    tokenExchangeUrl:
+      "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    // Access tokens live an hour; refresh tokens 100 days and are rotated on
+    // every refresh, which the platform persists. Both token endpoints
+    // authenticate the client with HTTP Basic.
+    refreshUrl: "https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer",
+    tokenEndpointAuthMethod: "client_secret_basic",
+    // No revokeUrl: Intuit's revocation endpoint wants a JSON body under HTTP
+    // Basic client auth, and the daemon's revoke helper only posts an
+    // unauthenticated form body, so a seeded URL would fail silently on every
+    // your-own disconnect. The platform registry revokes managed tokens itself.
+    // Every Accounting API path is scoped to the company (realm) the user
+    // picked on Intuit's consent screen. The realm arrives only as the
+    // callback's `realmId` query parameter; the platform captures it into the
+    // connection's `provider_params` and fills the `{realm_id}` placeholder
+    // server-side, so managed callers send paths relative to the company
+    // (`/query`, `/customer/123`). Production and sandbox keys use different
+    // hosts; the platform picks the host per environment.
+    baseUrl: "https://quickbooks.api.intuit.com/v3/company/{realm_id}",
+    // No pingUrl: the only company-independent probe would still need the
+    // realm in its path, which the ping route cannot fill in (it sends the
+    // URL's origin as a per-request base override, which would also pin a
+    // managed sandbox connection to the production host).
+    displayLabel: "QuickBooks",
+    description: "Invoices, customers, vendors, and accounting data",
+    dashboardUrl: "https://developer.intuit.com/app/developer/dashboard",
+    clientIdPlaceholder: null,
+    logoUrl: "https://cdn.simpleicons.org/quickbooks",
+    // The Accounting scope covers the QuickBooks Online API. Payments is a
+    // separate product the app must be enabled for, and the OpenID scopes
+    // only add the signing-in user's profile, so none are on by default.
+    defaultScopes: ["com.intuit.quickbooks.accounting"],
+    availableScopes: [
+      {
+        scope: "com.intuit.quickbooks.accounting",
+        description:
+          "Read and write QuickBooks Online accounting data: customers, vendors, invoices, bills, payments, items, accounts, and reports",
+      },
+      {
+        scope: "com.intuit.quickbooks.payment",
+        description:
+          "QuickBooks Payments: charges, refunds, bank accounts, and cards (requires a Payments-enabled app)",
+      },
+      { scope: "openid", description: "Sign in with Intuit (OpenID Connect)" },
+      { scope: "profile", description: "The signing-in user's name" },
+      { scope: "email", description: "The signing-in user's email address" },
+      { scope: "phone", description: "The signing-in user's phone number" },
+      { scope: "address", description: "The signing-in user's address" },
+    ],
+    loopbackPort: 17342,
+    managedServiceConfigKey: "quickbooks-oauth",
+    injectionTemplates: [
+      {
+        hostPattern: "quickbooks.api.intuit.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+      {
+        hostPattern: "sandbox-quickbooks.api.intuit.com",
+        injectionType: "header",
+        headerName: "Authorization",
+        valuePrefix: "Bearer ",
+      },
+    ],
+    appType: "App",
+    setupNotes: [
+      "QuickBooks scopes every Accounting API call to the company (realm) chosen on Intuit's consent screen. Managed connections carry the realm as provider_params.realm_id and requests are sent relative to /v3/company/{realmId}.",
+      "Intuit development keys only authorize sandbox companies, which live on sandbox-quickbooks.api.intuit.com; production keys use quickbooks.api.intuit.com.",
+      "The Accounting API returns XML unless the request carries Accept: application/json.",
+    ],
+    // CompanyInfo does not repeat the realm (its Id is always "1"); the
+    // platform keys the connection on the captured realm and labels it with
+    // the company name.
+    identityUrl:
+      "https://quickbooks.api.intuit.com/v3/company/{realm_id}/companyinfo/{realm_id}",
+    identityHeaders: { Accept: "application/json" },
+    identityResponsePaths: ["CompanyInfo.CompanyName", "CompanyInfo.LegalName"],
+    // Gated like figma/shopify: the platform side lands separately, and until
+    // the client ids are live a visible tile would offer a connect flow that
+    // cannot complete.
+    featureFlag: "quickbooks-oauth",
+  },
 };
 
 export const SEEDED_PROVIDER_KEYS = new Set(Object.keys(PROVIDER_SEED_DATA));

package/src/runtime/routes/__tests__/acp-claude-auth-routes.test.ts

@@ -48,7 +48,7 @@ mock.module("../../../security/oauth2.js", () => ({
 
 const actualClaudeOauth = await import("../../../acp/acp-claude-oauth.js");
 const { CLAUDE_MANUAL_REDIRECT_URI, CLAUDE_OAUTH_CONFIG } = actualClaudeOauth;
-const storeAcpClaudeTokenMock = mock(async (_token: string) => {});
+const storeAcpClaudeTokenMock = mock(async (_tokens: unknown) => {});
 // The connect-status route reads token presence; mock it so the route test
 // doesn't reach real secure storage.
 const hasAcpClaudeTokenMock = mock(async () => false);
@@ -228,9 +228,12 @@ describe("loopback capture", () => {
     const status = await waitForStatus(state, "connected");
     expect(status).toEqual({ status: "connected" });
 
-    // Access token persisted via storeAcpClaudeToken.
     expect(storeAcpClaudeTokenMock).toHaveBeenCalledTimes(1);
-    expect(storeAcpClaudeTokenMock).toHaveBeenCalledWith("sk-ant-oat-access");
+    expect(storeAcpClaudeTokenMock).toHaveBeenCalledWith({
+      accessToken: "sk-ant-oat-access",
+      refreshToken: "refresh-xyz",
+      expiresIn: 3600,
+    });
   });
 
   test("flips status to error when the exchange fails", async () => {
@@ -339,7 +342,11 @@ describe("acp_claude_auth_exchange", () => {
     expect(call[1]).toBe("auth-code-123");
     expect(call[2]).toBe(CLAUDE_MANUAL_REDIRECT_URI);
     expect(call[3]).toBeTruthy(); // PKCE verifier from the start call
-    expect(storeAcpClaudeTokenMock).toHaveBeenCalledWith("sk-ant-oat-manual");
+    expect(storeAcpClaudeTokenMock).toHaveBeenCalledWith({
+      accessToken: "sk-ant-oat-manual",
+      refreshToken: "refresh-manual",
+      expiresIn: 3600,
+    });
 
     // The pending entry is consumed — a second exchange fails.
     await expect(
@@ -360,7 +367,11 @@ describe("acp_claude_auth_exchange", () => {
       string,
     ];
     expect(call[1]).toBe("raw-code-xyz");
-    expect(storeAcpClaudeTokenMock).toHaveBeenCalledWith("sk-ant-oat-manual");
+    expect(storeAcpClaudeTokenMock).toHaveBeenCalledWith({
+      accessToken: "sk-ant-oat-manual",
+      refreshToken: "refresh-manual",
+      expiresIn: 3600,
+    });
   });
 
   test("malformed paste (no `#`, no state) is rejected", async () => {

package/src/runtime/routes/__tests__/apps-refresh-route.test.ts

@@ -5,7 +5,7 @@
  * implementations unless this file's tests are running.
  */
 
-import { mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { mkdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import {
@@ -33,6 +33,9 @@ const realCompiler = { ...(await import("../../../bundler/app-compiler.js")) };
 const realNotify = {
   ...(await import("../../../daemon/app-change-notify.js")),
 };
+const realPinStore = {
+  ...(await import("../../../apps/app-pin-store.js")),
+};
 
 const compileApp = mock(
   async (
@@ -70,6 +73,16 @@ mock.module("../../../daemon/app-change-notify.js", () => ({
   },
 }));
 
+mock.module("../../../apps/app-pin-store.js", () => ({
+  ...realPinStore,
+  listAppPins: () => {
+    if (!mockActive) {
+      return realPinStore.listAppPins();
+    }
+    return [];
+  },
+}));
+
 const { createApp } = await import("../../../apps/app-store.js");
 const { getWorkspacePluginsDir } = await import("../../../util/platform.js");
 const { ROUTES } = await import("../app-management-routes.js");
@@ -83,6 +96,7 @@ function findHandler(operationId: string) {
 }
 
 const handleRefreshApp = findHandler("apps_refresh");
+const handleListApps = findHandler("apps_list");
 
 let workspaceDir: string;
 let previousWorkspaceDir: string | undefined;
@@ -142,6 +156,30 @@ describe("apps_refresh route", () => {
     });
   });
 
+  test("advances the workspace app list revision when compiled output changes", async () => {
+    const created = createApp({
+      name: "Budget",
+      schemaJson: "{}",
+      htmlDefinition: "<h1>Budget</h1>",
+    });
+    const builtAt = Math.ceil(created.updatedAt) + 1_000;
+    compileApp.mockImplementationOnce(async (appDir) => {
+      const distDir = join(appDir, "dist");
+      mkdirSync(distDir, { recursive: true });
+      utimesSync(distDir, new Date(builtAt), new Date(builtAt));
+      return { ok: true, errors: [], warnings: [], durationMs: 11 };
+    });
+
+    await handleRefreshApp({ pathParams: { id: created.id } });
+    const listed = (await handleListApps({})) as {
+      apps: Array<{ id: string; updatedAt: number }>;
+    };
+
+    expect(listed.apps.find((app) => app.id === created.id)?.updatedAt).toBe(
+      builtAt,
+    );
+  });
+
   test("compiles a plugin app in place", async () => {
     const pluginName = `charts-${Math.random().toString(36).slice(2, 8)}`;
     const pluginDir = join(getWorkspacePluginsDir(), pluginName);
@@ -157,9 +195,7 @@ describe("apps_refresh route", () => {
       pathParams: { id: pluginAppId },
     });
 
-    expect(compileApp).toHaveBeenCalledWith(
-      join(pluginDir, "apps", "viewer"),
-    );
+    expect(compileApp).toHaveBeenCalledWith(join(pluginDir, "apps", "viewer"));
     expect(notifyAppSurfacesChanged).toHaveBeenCalledWith(pluginAppId, {
       fileChange: true,
     });
@@ -171,6 +207,40 @@ describe("apps_refresh route", () => {
     });
   });
 
+  test("advances the plugin app list revision when compiled output changes", async () => {
+    const pluginName = `charts-${Math.random().toString(36).slice(2, 8)}`;
+    const appDir = join(getWorkspacePluginsDir(), pluginName, "apps", "viewer");
+    mkdirSync(appDir, { recursive: true });
+    writeFileSync(
+      join(getWorkspacePluginsDir(), pluginName, "package.json"),
+      JSON.stringify({ name: pluginName, version: "1.0.0" }),
+    );
+    const pluginAppId = `plugins~${pluginName}~viewer`;
+    const before = (await handleListApps({})) as {
+      apps: Array<{ id: string; updatedAt: number }>;
+    };
+    const previousRevision = before.apps.find(
+      (app) => app.id === pluginAppId,
+    )?.updatedAt;
+    expect(previousRevision).toBeDefined();
+    const builtAt = Math.ceil(previousRevision!) + 1_000;
+    compileApp.mockImplementationOnce(async (sourceDir) => {
+      const distDir = join(sourceDir, "dist");
+      mkdirSync(distDir, { recursive: true });
+      utimesSync(distDir, new Date(builtAt), new Date(builtAt));
+      return { ok: true, errors: [], warnings: [], durationMs: 11 };
+    });
+
+    await handleRefreshApp({ pathParams: { id: pluginAppId } });
+    const after = (await handleListApps({})) as {
+      apps: Array<{ id: string; updatedAt: number }>;
+    };
+
+    expect(after.apps.find((app) => app.id === pluginAppId)?.updatedAt).toBe(
+      builtAt,
+    );
+  });
+
   test("returns compile errors without throwing", async () => {
     const created = createApp({
       name: "Budget",