@vellumai/assistant 0.10.9 → 0.10.10-dev.202607162206.d08e98e

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

@@ -16,10 +16,13 @@
 
 import { z } from "zod";
 
+import { isAssistantFeatureFlagEnabled } from "../../config/assistant-feature-flags.js";
+import { getConfig } from "../../config/loader.js";
 import {
   fetchManagedCatalog,
   type ManagedCredentialDescriptor,
 } from "../../credential-execution/managed-catalog.js";
+import { buildForChatSentinel } from "../../daemon/chat-credential-redaction.js";
 import { syncManualTokenConnection } from "../../oauth/manual-token-connection.js";
 import {
   disconnectOAuthProvider,
@@ -48,6 +51,8 @@ import {
 } from "../../tools/credentials/metadata-store.js";
 import type { CredentialInjectionTemplate } from "../../tools/credentials/policy-types.js";
 import { ACTOR_PRINCIPALS } from "../auth/route-policy.js";
+import { recordForChatMint } from "../for-chat-mint-registry.js";
+import { recordRevealSuccess } from "../reveal-success-registry.js";
 import { InjectionTemplateSchema } from "./credential-prompt-routes.js";
 import { BadRequestError, InternalError } from "./errors.js";
 import type { RouteDefinition, RouteHandlerArgs } from "./types.js";
@@ -296,11 +301,30 @@ async function handleCredentialsInspect({ body }: RouteHandlerArgs) {
   return output;
 }
 
-async function handleCredentialsReveal({ body }: RouteHandlerArgs) {
+async function handleCredentialsReveal({ body, headers }: RouteHandlerArgs) {
   if (!body || typeof body !== "object") {
     throw new BadRequestError("Request body is required");
   }
 
+  const forChat = (body as { forChat?: unknown }).forChat === true;
+  if (
+    forChat &&
+    !isAssistantFeatureFlagEnabled("chat-credential-reveal", getConfig())
+  ) {
+    throw new BadRequestError(
+      "--for-chat requires the chat-credential-reveal feature flag",
+    );
+  }
+
+  // Conversation-bound reveal nonce (see reveal-nonce.ts), forwarded by
+  // the CLI from the tool-shell env. Required for RECORDING any
+  // reveal-derived chat authority below; the reveal itself works without
+  // it (Settings rows, direct terminal use) — those calls just create no
+  // authority for any conversation's transcript.
+  const rawNonce = (body as { revealNonce?: unknown }).revealNonce;
+  const revealNonce =
+    typeof rawNonce === "string" && rawNonce.length > 0 ? rawNonce : undefined;
+
   const lookup = resolveCredentialLookup(body);
   const { value: secret, unreachable } = await getSecureKeyResultAsync(
     lookup.storageKey,
@@ -315,6 +339,79 @@ async function handleCredentialsReveal({ body }: RouteHandlerArgs) {
     throw new BadRequestError("Credential not found");
   }
 
+  // Recording gate shared by both registries below: only a DIRECT tool-shell
+  // CLI invocation may create authority. The `local` principal is the
+  // identity a CLI invocation arrives with over the unix-socket IPC
+  // (verified by the adapters, never caller-supplied), but the principal
+  // check alone is not enough: in local mode the gateway derives `local`
+  // from the verified JWT sub and forwards it for web calls too, stamping
+  // `x-vellum-proxy-server: ipc` — a header a direct CLI never sends — so
+  // proxied Settings-row/chat-chip reveals are excluded.
+  const directLocalInvocation =
+    headers?.["x-vellum-principal-type"] === "local" &&
+    headers?.["x-vellum-proxy-server"] !== "ipc";
+
+  if (forChat) {
+    // Both lookup forms resolve service+field (or throw); the narrow check
+    // keeps the sentinel's vault coordinates provably non-empty.
+    if (!lookup.service || !lookup.field) {
+      throw new BadRequestError(
+        "Credential identity could not be resolved for --for-chat",
+      );
+    }
+    // Chat-safe reveal: return the enriched redaction sentinel instead of
+    // the plaintext. The caller (the model, echoing a tool result) can
+    // paste this into its reply to render a click-to-reveal chip without
+    // the secret ever entering model context or the conversation stream.
+    // The persist-path forgery guard re-mints it on identity match — see
+    // guardForChatSentinels in chat-credential-redaction.ts. No plaintext
+    // reaches the tool, so no reveal-success proof is recorded: that
+    // registry authorizes plaintext-echo swaps, and retaining the secret
+    // for a path that never emits it would widen retention for nothing.
+    const sentinel = buildForChatSentinel({
+      service: lookup.service,
+      field: lookup.field,
+      value: secret,
+    });
+    // Record the mint AFTER the reveal provably succeeded. This registry —
+    // not any parse of the requested shell command — is what authorizes the
+    // persist guard to re-mint a sentinel with this identity: a command
+    // that merely quotes or comments out a reveal invocation never reaches
+    // this route, so it never allowlists anything. Like the plaintext proof
+    // below, the mint records only for a direct tool-shell invocation, and
+    // only with the conversation-bound nonce that scopes it to the
+    // conversation whose tool shell made this call (see the registry
+    // module doc — no predictable identifier can do this job).
+    if (directLocalInvocation && revealNonce !== undefined) {
+      recordForChatMint({
+        service: lookup.service,
+        field: lookup.field,
+        sentinel,
+        nonce: revealNonce,
+      });
+    }
+    return { value: sentinel };
+  }
+
+  // Ground truth for the chat-credential-reveal persist seams: this route
+  // is the only place a reveal legitimately reads plaintext, so a success
+  // recorded here is the proof the agent loop requires before promoting
+  // staged reveal candidates (a shell command can "succeed" without ever
+  // reaching this handler — `… || true`, or an echo of the command text).
+  // Recording a proxied UI reveal would let a click promote a staged ref
+  // in a concurrent turn whose command merely echoed (or was denied) the
+  // invocation. An unproven ref degrades to a plain sentinel — the safe
+  // direction. Both lookup branches populate service/field; the guard only
+  // satisfies the loose `CredentialLookup` type.
+  if (
+    directLocalInvocation &&
+    revealNonce !== undefined &&
+    lookup.service !== undefined &&
+    lookup.field !== undefined
+  ) {
+    recordRevealSuccess(lookup.service, lookup.field, secret, revealNonce);
+  }
+
   return { value: secret };
 }
 
@@ -523,15 +620,31 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Reveal a credential's plaintext value",
     description:
-      "Return the raw plaintext value of a stored credential. Blocked in untrusted shell mode.",
+      "Return the raw plaintext value of a stored credential. Blocked in untrusted shell mode. With forChat, returns a chat-safe redaction sentinel instead of the plaintext.",
     tags: ["credentials"],
     requestBody: z.object({
       service: z.string().optional().describe("Service namespace"),
       field: z.string().optional().describe("Field name"),
       id: z.string().optional().describe("Credential UUID for lookup by ID"),
+      forChat: z
+        .boolean()
+        .optional()
+        .describe(
+          "Return the credential's redaction sentinel (renders as a click-to-reveal chip in chat) instead of the plaintext. Requires the chat-credential-reveal feature flag.",
+        ),
+      revealNonce: z
+        .string()
+        .optional()
+        .describe(
+          "Conversation-bound reveal nonce from the tool-shell environment. Scopes any recorded chat-redaction authority (plaintext proof or forChat mint) to the conversation whose tool executed this reveal; without it the reveal succeeds but records no authority.",
+        ),
     }),
     responseBody: z.object({
-      value: z.string().describe("The plaintext credential value"),
+      value: z
+        .string()
+        .describe(
+          "The plaintext credential value (or its redaction sentinel when forChat is set)",
+        ),
     }),
     handler: handleCredentialsReveal,
   },

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

@@ -240,13 +240,18 @@ async function handleEmailDownload({ queryParams = {} }: RouteHandlerArgs) {
 }
 
 async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
-  const { to, text, subject, html, cc, bcc, reply_to } = body as {
+  const { to, text, subject, html, cc, bcc, attachments, reply_to } = body as {
     to: string[];
     text: string;
     subject?: string;
     html?: string;
     cc?: string[];
     bcc?: string[];
+    attachments?: {
+      filename: string;
+      content_type: string;
+      content: string;
+    }[];
     reply_to?: string;
   };
 
@@ -293,6 +298,7 @@ async function handleEmailSend({ body = {} }: RouteHandlerArgs) {
   if (resolvedHtml) payload.html = resolvedHtml;
   if (cc && cc.length > 0) payload.cc = cc;
   if (bcc && bcc.length > 0) payload.bcc = bcc;
+  if (attachments && attachments.length > 0) payload.attachments = attachments;
   if (reply_to) payload.reply_to = reply_to;
 
   const response = await client.fetch("/v1/runtime-proxy/email/send/", {
@@ -567,6 +573,16 @@ export const ROUTES: RouteDefinition[] = [
         .describe("HTML body (auto-generated from text if omitted)"),
       cc: z.array(z.string()).optional().describe("CC recipients"),
       bcc: z.array(z.string()).optional().describe("BCC recipients"),
+      attachments: z
+        .array(
+          z.object({
+            filename: z.string(),
+            content_type: z.string(),
+            content: z.string().describe("Base64-encoded file content"),
+          }),
+        )
+        .optional()
+        .describe("File attachments"),
       reply_to: z.string().optional().describe("Reply-to email ID"),
     }),
     responseBody: z.object({

package/src/runtime/routes/inbound-stages/transcribe-audio.test.ts

@@ -151,7 +151,7 @@ describe("tryTranscribeAudioAttachments", () => {
     expect(reason).not.toContain("OpenAI");
   });
 
-  test("API failure returns error with reason", async () => {
+  test("API failure returns a friendly, non-raw reason naming the provider", async () => {
     const audio = makeAudioAttachment("a1");
     mockAttachments = [audio];
     mockTranscriber = {
@@ -165,9 +165,37 @@ describe("tryTranscribeAudioAttachments", () => {
     const result = await tryTranscribeAudioAttachments(["a1"]);
 
     expect(result.status).toBe("error");
-    expect((result as { reason: string }).reason).toBe(
-      "API rate limit exceeded",
-    );
+    const reason = (result as { reason: string }).reason;
+    // Friendly copy replaces the raw provider string.
+    expect(reason).not.toContain("API rate limit exceeded");
+    expect(reason).toContain("OpenAI Whisper");
+  });
+
+  test("auth failure returns a friendly, JSON-free reason that names the API key", async () => {
+    const audio = makeAudioAttachment("a1");
+    mockAttachments = [audio];
+    mockTranscriber = {
+      providerId: "deepgram",
+      boundaryId: "daemon-batch",
+      transcribe: async () => {
+        // Mocked normalizeSttError returns an SttError as-is, so throw the
+        // categorized error directly (a plain 401 string would classify as
+        // provider-error under the simplified mock).
+        throw new SttError(
+          "auth",
+          'Deepgram API error (401): {"err_code":"INVALID_AUTH"}',
+        );
+      },
+    };
+
+    const result = await tryTranscribeAudioAttachments(["a1"]);
+
+    expect(result.status).toBe("error");
+    const reason = (result as { reason: string }).reason;
+    expect(reason).not.toContain("{");
+    expect(reason).not.toContain("INVALID_AUTH");
+    expect(reason).toContain("API key");
+    expect(reason).toContain("Deepgram");
   });
 
   test("30-second timeout fires and returns error without blocking", async () => {
@@ -184,7 +212,7 @@ describe("tryTranscribeAudioAttachments", () => {
     const result = await tryTranscribeAudioAttachments(["a1"]);
 
     expect(result.status).toBe("error");
-    expect((result as { reason: string }).reason).toBe(
+    expect((result as { reason: string }).reason).toContain(
       "Transcription timed out",
     );
   });

package/src/runtime/routes/inbound-stages/transcribe-audio.ts

@@ -12,7 +12,9 @@ import {
   getAttachmentsByIds,
 } from "../../../persistence/attachments-store.js";
 import { resolveBatchTranscriber } from "../../../providers/speech-to-text/resolve.js";
+import { describeSttFailure } from "../../../providers/voice-error-copy.js";
 import { normalizeSttError } from "../../../stt/daemon-batch-transcriber.js";
+import type { SttProviderId } from "../../../stt/types.js";
 import { getLogger } from "../../../util/logger.js";
 
 const log = getLogger("transcribe-audio");
@@ -37,6 +39,8 @@ export type TranscribeResult =
 export async function tryTranscribeAudioAttachments(
   attachmentIds: string[],
 ): Promise<TranscribeResult> {
+  // Hoisted so the catch can name the provider in a friendly failure message.
+  let providerId: SttProviderId | undefined;
   try {
     // Look up attachments and filter to audio MIME types
     const resolved = getAttachmentsByIds(attachmentIds);
@@ -57,6 +61,7 @@ export async function tryTranscribeAudioAttachments(
           "No speech-to-text provider configured. Add an API key for your STT service to enable voice message transcription.",
       };
     }
+    providerId = transcriber.providerId;
 
     // Transcribe each audio attachment with a shared timeout
     const abortController = new AbortController();
@@ -103,11 +108,7 @@ export async function tryTranscribeAudioAttachments(
     }
   } catch (err: unknown) {
     const sttErr = normalizeSttError(err);
-    const reason =
-      sttErr.category === "timeout"
-        ? "Transcription timed out"
-        : sttErr.message;
     log.warn({ err }, "Audio transcription failed");
-    return { status: "error", reason };
+    return { status: "error", reason: describeSttFailure(sttErr, providerId) };
   }
 }

package/src/runtime/routes/inference-provider-connection-routes.ts

@@ -19,10 +19,12 @@ import { getIsPlatform } from "../../config/env-registry.js";
 import { getConfigReadOnly } from "../../config/loader.js";
 import { getDb } from "../../persistence/db-connection.js";
 import {
+  type Auth,
   AuthSchema,
   type ConnectionModel,
   ConnectionModelSchema,
   ConnectionProviderSchema,
+  deriveAuthForProvider,
   ProviderConnectionSchema,
   PROVIDERS_REQUIRING_BASE_URL_AND_MODELS,
   VALID_CONNECTION_PROVIDERS,
@@ -104,7 +106,9 @@ async function parseCustomProviderFields(
           throw new BadRequestError(`Invalid base_url: must be an http(s) URL`);
         }
       } catch (err) {
-        if (err instanceof BadRequestError) throw err;
+        if (err instanceof BadRequestError) {
+          throw err;
+        }
         throw new BadRequestError(
           `Invalid base_url: must be a valid http(s) URL`,
         );
@@ -159,6 +163,28 @@ async function parseCustomProviderFields(
   return out;
 }
 
+/**
+ * Derive the auth object for a body that omits `auth`, from the provider and
+ * the optional top-level `credential` field. Throws the 400s for the cases
+ * the derivation can't express: a malformed credential, or a provider that
+ * needs an API key when none was supplied.
+ */
+function deriveConnectionAuth(provider: string, credential: unknown): Auth {
+  if (
+    credential !== undefined &&
+    (typeof credential !== "string" || credential.length === 0)
+  ) {
+    throw new BadRequestError("credential must be a non-empty string");
+  }
+  const derived = deriveAuthForProvider(provider, credential);
+  if (!derived) {
+    throw new BadRequestError(
+      `Provider "${provider}" requires an API key. Pass "credential" (a vault credential key) or an explicit "auth" object.`,
+    );
+  }
+  return derived;
+}
+
 // ---------------------------------------------------------------------------
 // Handlers
 // ---------------------------------------------------------------------------
@@ -174,10 +200,14 @@ function handleListConnections({ queryParams = {} }: RouteHandlerArgs) {
 
 function handleGetConnection({ pathParams = {} }: RouteHandlerArgs) {
   const { name } = pathParams;
-  if (!name) throw new BadRequestError("name is required");
+  if (!name) {
+    throw new BadRequestError("name is required");
+  }
 
   const conn = getConnection(getDb(), name);
-  if (!conn) throw new NotFoundError(`Connection "${name}" not found.`);
+  if (!conn) {
+    throw new NotFoundError(`Connection "${name}" not found.`);
+  }
 
   return conn;
 }
@@ -197,7 +227,9 @@ async function handleCreateConnection({ body = {} }: RouteHandlerArgs) {
       `Invalid provider "${String(provider)}". Valid: ${VALID_CONNECTION_PROVIDERS.join(", ")}`,
     );
   }
-  const authResult = AuthSchema.safeParse(auth);
+  const authResult = AuthSchema.safeParse(
+    auth ?? deriveConnectionAuth(providerResult.data, body.credential),
+  );
   if (!authResult.success) {
     throw new BadRequestError(`Invalid auth: ${authResult.error.message}`);
   }
@@ -239,12 +271,12 @@ async function handleCreateConnection({ body = {} }: RouteHandlerArgs) {
     }
     if (result.error.code === "base_url_required") {
       throw new BadRequestError(
-        "base_url is required for openai-compatible connections.",
+        "base_url is required for openai-compatible providers.",
       );
     }
     if (result.error.code === "models_required") {
       throw new BadRequestError(
-        "At least one model is required for openai-compatible connections.",
+        "At least one model is required for openai-compatible providers.",
       );
     }
     throw new BadRequestError("Invalid auth configuration.");
@@ -258,12 +290,36 @@ async function handleUpdateConnection({
   body = {},
 }: RouteHandlerArgs) {
   const { name } = pathParams;
-  if (!name) throw new BadRequestError("name is required");
+  if (!name) {
+    throw new BadRequestError("name is required");
+  }
 
   const existing = getConnection(getDb(), name);
-  if (!existing) throw new NotFoundError(`Connection "${name}" not found.`);
+  if (!existing) {
+    throw new NotFoundError(`Connection "${name}" not found.`);
+  }
 
-  const auth = body.auth;
+  // `auth` is optional: an explicit object wins; a bare `credential` rotates
+  // the key by re-deriving from the provider; omitting both leaves the stored
+  // auth untouched (so label-only edits never disturb e.g. an
+  // oauth_subscription connection).
+  if (
+    body.auth === undefined &&
+    body.credential !== undefined &&
+    existing.auth.type === "oauth_subscription"
+  ) {
+    // Derivation would silently flip the auth type to api_key. Rotating a
+    // subscription token goes through the ChatGPT sign-in routes; switching
+    // to key auth requires an explicit `auth` object.
+    throw new BadRequestError(
+      `Connection "${name}" uses subscription auth, which "credential" cannot rotate. Re-run the ChatGPT sign-in flow, or pass an explicit "auth" object to switch auth types.`,
+    );
+  }
+  const auth =
+    body.auth ??
+    (body.credential !== undefined
+      ? deriveConnectionAuth(existing.provider, body.credential)
+      : existing.auth);
   const authResult = AuthSchema.safeParse(auth);
   if (!authResult.success) {
     throw new BadRequestError(`Invalid auth: ${authResult.error.message}`);
@@ -307,12 +363,12 @@ async function handleUpdateConnection({
     }
     if (result.error.code === "base_url_required") {
       throw new BadRequestError(
-        "base_url is required for openai-compatible connections.",
+        "base_url is required for openai-compatible providers.",
       );
     }
     if (result.error.code === "models_required") {
       throw new BadRequestError(
-        "At least one model is required for openai-compatible connections.",
+        "At least one model is required for openai-compatible providers.",
       );
     }
     throw new BadRequestError("Invalid auth configuration.");
@@ -323,9 +379,11 @@ async function handleUpdateConnection({
 
 function handleDeleteConnection({ pathParams = {} }: RouteHandlerArgs) {
   const { name } = pathParams;
-  if (!name) throw new BadRequestError("name is required");
+  if (!name) {
+    throw new BadRequestError("name is required");
+  }
 
-  // Existence check first so a stale `llm.default.provider_connection`
+  // Existence check first so a stale profile `provider_connection`
   // reference to a missing connection returns 404 (not 409).
   const existing = getConnection(getDb(), name);
   if (!existing) {
@@ -345,17 +403,6 @@ function handleDeleteConnection({ pathParams = {} }: RouteHandlerArgs) {
 
   const config = getConfigReadOnly();
 
-  // llm.default carries provider_connection (LLMConfigBase).
-  if (
-    (config.llm?.default as Record<string, unknown> | undefined)
-      ?.provider_connection === name
-  ) {
-    throw new ConflictError(
-      `Connection "${name}" is referenced by llm.default. Update llm.default.provider_connection before deleting.`,
-      { referencedBy: ["llm.default"] },
-    );
-  }
-
   // llm.defaultProvider: guards both the resolved connection name (explicit
   // `connectionName` or the `<provider>-personal` convention) and the case
   // where the convention name is dangling but this is the last remaining
@@ -471,12 +518,13 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Create a provider connection",
     description:
-      "Create a new named provider connection. Fails with 409 if a connection with this name already exists.",
+      "Create a new named provider connection. When auth is omitted it is derived from the provider (keyless providers get none, vellum gets platform, everything else needs credential for api_key auth). Fails with 409 if a connection with this name already exists.",
     tags: ["inference"],
     requestBody: z.object({
       name: z.string().min(1),
       provider: ConnectionProviderSchema,
-      auth: AuthSchema,
+      auth: AuthSchema.optional(),
+      credential: z.string().min(1).optional(),
       label: z.string().min(1).optional(),
       base_url: z.string().url().nullable().optional(),
       models: z.array(ConnectionModelSchema).nullable().optional(),
@@ -499,11 +547,12 @@ export const ROUTES: RouteDefinition[] = [
     },
     summary: "Update a provider connection",
     description:
-      "Update an existing connection. Cannot rename or change the provider. For the Vellum-managed connection (vellum) the auth is locked to platform; label remains editable.",
+      "Update an existing connection. Cannot rename or change the provider. Omitting auth keeps the stored auth; passing credential alone rotates the key via provider-derived api_key auth. For the Vellum-managed connection (vellum) the auth is locked to platform; label remains editable.",
     tags: ["inference"],
     pathParams: [{ name: "name", description: "Connection name" }],
     requestBody: z.object({
-      auth: AuthSchema,
+      auth: AuthSchema.optional(),
+      credential: z.string().min(1).optional(),
       label: z.string().min(1).nullable().optional(),
       base_url: z.string().url().nullable().optional(),
       models: z.array(ConnectionModelSchema).nullable().optional(),

package/src/runtime/routes/inference-send-routes.ts

@@ -53,7 +53,7 @@ async function handleInferenceSend({ body = {} }: RouteHandlerArgs) {
   });
   if (!provider) {
     throw new BadRequestError(
-      "No LLM provider is configured. Run 'assistant config set llm.default.provider <provider>' to set one up.",
+      "No LLM provider is configured. Connect a provider (assistant credentials) or set llm.defaultProvider to choose one.",
     );
   }
 

package/src/runtime/routes/internal-telemetry-routes.ts

@@ -16,7 +16,7 @@
 
 import { z } from "zod";
 
-import { getCachedShareAnalytics } from "../../platform/consent-cache.js";
+import { getRawShareAnalytics } from "../../platform/consent-cache.js";
 import {
   type AuthFallbackCount,
   recordAuthFallbackCounts,
@@ -61,15 +61,16 @@ function handleRecordAuthFallback({ body }: RouteHandlerArgs) {
 
   const recorded = recordAuthFallbackCounts(window_start, window_end, mapped);
   if (recorded === 0) {
-    if (getCachedShareAnalytics()) {
-      // Consent is on but nothing was recorded (the body guarantees counts),
-      // so the telemetry DB is unavailable. Fail so the gateway's reporter
-      // merges the batch back and retries next flush instead of losing it.
+    if (getRawShareAnalytics() !== false) {
+      // Consent is not a confirmed opt-out but nothing was recorded (the
+      // body guarantees counts), so the telemetry DB is unavailable. Fail so
+      // the gateway's reporter merges the batch back and retries next flush
+      // instead of losing it.
       throw new ServiceUnavailableError(
         "Telemetry database unavailable; retry the auth-fallback batch",
       );
     }
-    // share_analytics consent is off: drop the counts to honor the opt-out.
+    // Confirmed share_analytics opt-out: drop the counts to honor it.
     return { skipped: true };
   }
   log.debug({ recorded }, "Recorded auth-fallback counts");

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

@@ -91,6 +91,7 @@ import {
 import { getPlatformBaseUrl } from "../../config/env.js";
 import { isPluginDisabled } from "../../plugins/disabled-state.js";
 import { ensurePluginApiShim } from "../../plugins/ensure-plugin-api-shim.js";
+import { reconcilePluginSourcesNow } from "../../plugins/mtime-cache.js";
 import { getLocalCategorySlugs } from "../../skills/categories-cache.js";
 import { getLogger } from "../../util/logger.js";
 import { getWorkspacePluginsDir } from "../../util/platform.js";
@@ -1092,7 +1093,15 @@ async function handleUninstallPlugin({
   await ensurePluginApiShim().catch(() => {});
 
   try {
+    // `uninstallPlugin` runs the plugin's `shutdown` hook (while its files are
+    // still present) and then removes the directory — both in this daemon
+    // process. Following it with a reconcile drops the plugin's now-absent
+    // tools and hooks from the in-memory caches immediately (the `shutdown`
+    // already ran, so the reconcile's deactivation does not run it again),
+    // rather than leaving that to the background source watcher. Symmetric to
+    // the install route, which reconciles to bring a new plugin up.
     const result = await uninstallPlugin({ name: rawName });
+    await reconcilePluginSourcesNow();
     publishPluginsChanged(getOriginClientId(headers));
     return { name: result.name, target: result.target };
   } catch (err) {
@@ -1228,6 +1237,12 @@ async function handleInstallPlugin({ body = {}, headers }: RouteHandlerArgs) {
         { fetch: globalThis.fetch.bind(globalThis) },
       );
     }
+    // Bring the freshly materialized plugin up in-process right now — register
+    // its tools and run its `init` hook — instead of waiting for the resource
+    // monitor to republish the sentinel and a later turn to apply it. This is
+    // what makes `init` fire as part of the install rather than at the next
+    // daemon boot. Never throws; a failure is contained and logged.
+    await reconcilePluginSourcesNow();
     publishPluginsChanged(getOriginClientId(headers));
     return {
       ok: true as const,
@@ -1403,6 +1418,21 @@ async function handleUpgradePlugin({
       { name: rawName, dryRun, strategy },
       { fetch: globalThis.fetch.bind(globalThis) },
     );
+    // An upgrade that actually moved files (outcome `upgraded`) rewrites the
+    // plugin's on-disk source; bring the change up in-process right now — run
+    // the old version's `shutdown` and the new version's `init` via the
+    // reconcile — instead of waiting for the resource monitor to republish the
+    // sentinel and a later turn to apply it. This is what makes the lifecycle
+    // fire as part of the upgrade rather than at the next daemon boot,
+    // symmetric to the install and uninstall routes. A no-op or dry run leaves
+    // the tree unchanged, so there is nothing to reconcile. Ensure the
+    // workspace `@vellumai/plugin-api` shim first (as uninstall does) so a hook
+    // that imports the package resolves even inside the daemon boot window.
+    // Never throws; a failure is contained and logged.
+    if (result.outcome === "upgraded") {
+      await ensurePluginApiShim().catch(() => {});
+      await reconcilePluginSourcesNow();
+    }
     publishPluginsChanged(getOriginClientId(headers));
     return {
       name: result.name,
@@ -1435,9 +1465,10 @@ async function handleUpgradePlugin({
     if (err instanceof PluginMergeBaselineError) {
       throw new ConflictError(err.message);
     }
-    // The install exists but has no marketplace entry to advance to — a
-    // permanent state the caller cannot resolve by retrying. 409 marks the
-    // request as well-formed but not actionable in the current state.
+    // The install has neither a marketplace entry nor a recorded GitHub source
+    // to advance to — a permanent state the caller cannot resolve by retrying.
+    // 409 marks the request as well-formed but not actionable in the current
+    // state.
     if (err instanceof PluginNotUpgradableError) {
       throw new ConflictError(err.message);
     }
@@ -1866,9 +1897,9 @@ export const ROUTES: RouteDefinition[] = [
       requiredScopes: ["settings.write"],
       allowedPrincipalTypes: ACTOR_PRINCIPALS,
     },
-    summary: "Upgrade a plugin to the marketplace pin",
+    summary: "Upgrade a plugin to its source's current revision",
     description:
-      'Move an installed plugin to the marketplace\'s current pinned commit, re-materializing it under `<workspaceDir>/plugins/<name>/`. Always resolves against the curated marketplace pin (no caller-supplied ref), mirroring `plugins install`\'s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed commit already equals the pin; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching the install. Installs lacking provenance are re-pinned to the current SHA. The upgraded code is picked up live on the next read (no restart required). `strategy` controls how local edits are reconciled: `overwrite` (default) discards them and re-installs the pin wholesale; `ours`/`theirs`/`assistant` perform a three-way merge against the re-materialized install commit, carrying non-conflicting edits from both sides forward and resolving conflicting hunks toward the local edit (`ours`) or the pin (`theirs`), or writing git conflict markers into the file and reporting them in `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy whose install-time baseline cannot be reconstructed returns 409. Mirrors the CLI\'s `assistant plugins upgrade <name> [--strategy <s>]`.',
+      'Move an installed plugin to its source\'s current revision, re-materializing it under `<workspaceDir>/plugins/<name>/`. A marketplace plugin advances to the curated pin; a plugin installed directly from a GitHub URL (untrusted, not in the marketplace) advances to whatever its recorded ref now resolves to — a pinned SHA is immutable (a no-op), a branch/tag/HEAD moves as upstream does — re-materialized verbatim with no curated adapter overlay, exactly as the original untrusted install was. The target ref is never taken from the request (no caller-supplied ref), mirroring `plugins install`\'s curation boundary. A no-op (`outcome: "already-up-to-date"`) when the installed commit already equals the target; pass `dryRun` to preview the move (`outcome: "would-upgrade"`) without touching the install. Installs lacking provenance are re-pinned to the current SHA. The upgraded code is picked up live on the next read (no restart required). `strategy` controls how local edits are reconciled: `overwrite` (default) discards them and re-installs the target wholesale; `ours`/`theirs`/`assistant` perform a three-way merge against the re-materialized install commit, carrying non-conflicting edits from both sides forward and resolving conflicting hunks toward the local edit (`ours`) or the target (`theirs`), or writing git conflict markers into the file and reporting them in `conflicts`/`binaryConflicts` for the assistant to resolve (`assistant`). A merge strategy whose install-time baseline cannot be reconstructed returns 409. Mirrors the CLI\'s `assistant plugins upgrade <name> [--strategy <s>]`.',
     tags: ["plugins"],
     pathParams: [
       {
@@ -1891,7 +1922,7 @@ export const ROUTES: RouteDefinition[] = [
       },
       "409": {
         description:
-          "The install exists but has no marketplace entry to advance to, or a merge strategy was requested whose install-time baseline cannot be reconstructed.",
+          "The install has neither a marketplace entry nor a recorded GitHub source to advance to, or a merge strategy was requested whose install-time baseline cannot be reconstructed.",
       },
       "503": {
         description: