@vellumai/assistant 0.11.4 → 0.11.5-staging.2

package/src/plugin-api/resolve-credential.ts

@@ -9,18 +9,20 @@
  *
  * ## Plugin scoping
  *
- * When a plugin is in context — its hook or tool is executing, tracked by
- * {@link ../plugins/plugin-execution-context.getCurrentPluginName} — resolution
- * is restricted: the plugin may only resolve credentials whose `field` equals
- * the plugin's own manifest name. A plugin named `acme` can therefore read
- * `openai/acme` or `stripe/acme` but not `openai/api_key`. Outside any plugin
- * context (host-internal callers, CLI, tests) the resolver is unscoped and
- * behaves like a direct reveal.
+ * When a plugin is in context (its hook, tool, or one of its own
+ * `/x/plugins/<name>/` routes is executing, tracked by
+ * {@link ../plugins/plugin-execution-context.getCurrentPluginName}), resolution
+ * is restricted: the plugin may only resolve credentials whose `service`
+ * equals its manifest name (`imessage/api_key` for plugin `imessage`). It
+ * cannot read another service (`openai/api_key`, `openai/imessage`). Outside
+ * any plugin context (host-internal callers, CLI, tests) the resolver is
+ * unscoped and behaves like a direct reveal.
  */
 
 import { getCurrentPluginName } from "../plugins/plugin-execution-context.js";
 import { getSecureKeyResultAsync } from "../security/secure-keys.js";
 import { resolveCredentialRef } from "../tools/credentials/resolve.js";
+import { credentialInPluginScope } from "./credential-scope.js";
 
 /**
  * Raised when a credential cannot be resolved: the reference does not match a
@@ -48,13 +50,16 @@ export async function resolveCredential(ref: string): Promise<string> {
     throw new CredentialResolutionError(`Credential not found: ${ref}`);
   }
 
-  // Scope the resolution to the plugin in context, if any. The field-name gate
+  // Scope the resolution to the plugin in context, if any. The ownership gate
   // is enforced before the plaintext is read so an out-of-scope plugin never
   // touches the secure backend.
   const pluginName = getCurrentPluginName();
-  if (pluginName !== undefined && resolved.field !== pluginName) {
+  if (
+    pluginName !== undefined &&
+    !credentialInPluginScope(pluginName, resolved.service)
+  ) {
     throw new CredentialResolutionError(
-      `Plugin "${pluginName}" may only resolve credentials whose field matches its name; ` +
+      `Plugin "${pluginName}" may only resolve credentials under its own service; ` +
         `"${resolved.service}/${resolved.field}" is out of scope.`,
     );
   }

package/src/plugin-api/store-credential.ts

@@ -0,0 +1,148 @@
+/**
+ * Plugin-facing credential storage.
+ *
+ * {@link storeCredential} writes a credential's plaintext to the secure store,
+ * the same write `assistant credentials set` performs, naming it either by an
+ * existing credential's UUID or by a `"service/field"` string, the same
+ * vocabulary {@link ./resolve-credential.resolveCredential} reads back. A
+ * plugin that obtains a token for itself (an OAuth exchange it drives, a key a
+ * user hands it through its own route) persists it here instead of inventing
+ * its own on-disk secret file.
+ *
+ * ## Plugin scoping
+ *
+ * A plugin may only write credentials whose `service` equals its manifest
+ * name (`imessage/api_key` for plugin `imessage`). It cannot write another
+ * service (`openai/api_key`, `openai/imessage`). The name comes from the
+ * execution context
+ * ({@link ../plugins/plugin-execution-context.getCurrentPluginName}), which the
+ * host establishes around a plugin's hook, tool, and route invocations.
+ *
+ * Unlike the read path, this **fails closed**: with no plugin in context there
+ * is nobody to scope the write to, so it is refused rather than treated as an
+ * unscoped host write. A plugin's module body is evaluated by the loader
+ * outside any context, and an unscoped branch there would let top-level code
+ * overwrite the user's own credentials. Host-internal callers that legitimately
+ * write unscoped (the `credentials/set` route, the CLI behind it) compose
+ * {@link ../tools/credentials/store.storeCredentialValue} directly. This
+ * matches the plugin-owned index (`indexDocument`), which likewise requires a
+ * context because a write with no owner has nothing to attribute.
+ */
+
+import { getCurrentPluginName } from "../plugins/plugin-execution-context.js";
+import { parseServiceFieldRef } from "../tools/credentials/ref-parse.js";
+import { resolveCredentialRef } from "../tools/credentials/resolve.js";
+import { storeCredentialValue } from "../tools/credentials/store.js";
+import { credentialInPluginScope } from "./credential-scope.js";
+
+/**
+ * Raised when a credential cannot be stored: the reference is malformed, the
+ * value is empty or invalid for its service, the secure backend rejected the
+ * write, or the calling plugin is not permitted to write the credential.
+ */
+export class CredentialStoreError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialStoreError";
+  }
+}
+
+export interface StoreCredentialOptions {
+  /** Human-friendly alias shown in credential listings. */
+  label?: string;
+  /** What the credential is for, surfaced to the agent. */
+  description?: string;
+  /**
+   * Skip the retroactive sweep that removes the value from recent transcripts.
+   * The sweep exists because a secret is often pasted into chat before it is
+   * stored; pass `true` only for a value that provably never transited a
+   * conversation, such as a token minted by an OAuth refresh.
+   */
+  skipTranscriptScrub?: boolean;
+}
+
+/** Identity of the credential that was written. */
+export interface StoredCredentialRef {
+  credentialId: string;
+  service: string;
+  field: string;
+}
+
+/**
+ * Store a credential's plaintext value, creating it or replacing the value of
+ * an existing one.
+ *
+ * @param ref A credential UUID (an existing credential) or a `"service/field"`
+ *   string (created when no such credential exists).
+ * @param value The plaintext value. Edge whitespace is trimmed.
+ * @returns The identity of the stored credential, which
+ *   {@link ./resolve-credential.resolveCredential} accepts as a ref.
+ * @throws {CredentialStoreError} when no plugin is in context, the ref is
+ *   malformed or names no credential, the value is empty or invalid for its
+ *   service, the store rejects the write, or the calling plugin is not scoped
+ *   to the credential.
+ */
+export async function storeCredential(
+  ref: string,
+  value: string,
+  options: StoreCredentialOptions = {},
+): Promise<StoredCredentialRef> {
+  // Both gates run before anything is written, so a refused write never
+  // touches the secure backend. Fail closed when there is no plugin to scope
+  // to: a plugin's module body is evaluated outside any context, and an
+  // unscoped branch there would be a way to overwrite the user's credentials.
+  const pluginName = getCurrentPluginName();
+  if (pluginName === undefined) {
+    throw new CredentialStoreError(
+      "storeCredential requires an active plugin execution context (no calling plugin found). " +
+        "Call it from a hook, tool, or route handler rather than at module scope.",
+    );
+  }
+
+  const target = resolveStoreTarget(ref);
+  if (!credentialInPluginScope(pluginName, target.service)) {
+    throw new CredentialStoreError(
+      `Plugin "${pluginName}" may only store credentials under its own service; ` +
+        `"${target.service}/${target.field}" is out of scope.`,
+    );
+  }
+
+  try {
+    return await storeCredentialValue({
+      service: target.service,
+      field: target.field,
+      value,
+      alias: options.label,
+      usageDescription: options.description,
+      skipTranscriptScrub: options.skipTranscriptScrub,
+    });
+  } catch (err) {
+    throw new CredentialStoreError(
+      err instanceof Error ? err.message : String(err),
+    );
+  }
+}
+
+/**
+ * Resolve the `ref` a write targets. An existing credential (by UUID or by
+ * `"service/field"`) keeps its identity; otherwise the ref must name the
+ * service and field of the credential to create, which a bare UUID cannot.
+ */
+function resolveStoreTarget(ref: string): { service: string; field: string } {
+  if (!ref || ref.trim().length === 0) {
+    throw new CredentialStoreError("Credential reference is required");
+  }
+
+  const existing = resolveCredentialRef(ref);
+  if (existing) {
+    return { service: existing.service, field: existing.field };
+  }
+
+  const parsed = parseServiceFieldRef(ref);
+  if (!parsed) {
+    throw new CredentialStoreError(
+      `Cannot store credential: "${ref}" matches no stored credential and is not a "service/field" reference`,
+    );
+  }
+  return parsed;
+}

package/src/plugin-api/system-card.ts

@@ -0,0 +1,36 @@
+/**
+ * Plugin-facing facade over the host's system-card writer: a daemon-authored
+ * transcript notice, persisted as an assistant row stamped
+ * `messageKind: "system_card"` so clients render it as a standalone system
+ * notice rather than assistant-persona speech. Plugins use it to tell the user
+ * about something the turn did to their input that the model's own reply
+ * cannot explain (e.g. an attachment the turn could not send).
+ *
+ * The writer is loaded through a dynamic `import()` inside the wrapper, for the
+ * same reason `persistence/conversation-plugin-facade.ts` does: it carries the
+ * DB/drizzle import graph, whose named exports must not be forced to resolve
+ * merely because a plugin imported `@vellumai/plugin-api`. Suites that
+ * partial-mock a module in that graph would otherwise fail to instantiate.
+ */
+
+/**
+ * Persist a system card in a conversation's transcript and announce it to
+ * connected clients through the sync invalidation that drives a refetch.
+ * Returns the persisted message id.
+ *
+ * A plugin card is non-terminal: it never emits `message_complete`, so a card
+ * written from a hook that runs inside a turn leaves that turn's streaming and
+ * processing state untouched. It is also not appended to the conversation's
+ * in-memory working history, so it cannot leave a trailing assistant message
+ * for the turn's next provider call to continue from.
+ */
+export async function persistSystemCard(opts: {
+  conversationId: string;
+  text: string;
+  metadata: Record<string, unknown>;
+}): Promise<string> {
+  const { persistSystemCard: persistHostSystemCard } =
+    await import("../runtime/routes/canned-message-complete.js");
+  const { id } = await persistHostSystemCard({ ...opts, endsTurn: false });
+  return id;
+}

package/src/plugin-api/vision-support.test.ts

@@ -2,8 +2,14 @@ import { beforeEach, describe, expect, test } from "bun:test";
 
 import { setConfig } from "../__tests__/helpers/set-config.js";
 import { getConfig } from "../config/loader.js";
+import { getDb } from "../persistence/db-connection.js";
+import { initializeDb } from "../persistence/db-init.js";
+import { providerConnections } from "../persistence/schema/inference.js";
 import type { ModelProfileInfo } from "./types.js";
 
+// Entry-name translation reads provider_connections rows through the real DB.
+await initializeDb();
+
 // ─── Fixture config ─────────────────────────────────────────────────────────
 
 interface MockProfileEntry {
@@ -211,6 +217,82 @@ describe("doesSupportVision with a BYO default provider", () => {
   });
 });
 
+describe("doesSupportVision with connection entry-name providers", () => {
+  function seedConnection(opts: { name: string; provider: string }): void {
+    const now = Date.now();
+    getDb()
+      .insert(providerConnections)
+      .values({
+        name: opts.name,
+        provider: opts.provider,
+        auth: JSON.stringify({
+          type: "api_key",
+          credential: `${opts.provider}/api_key`,
+        }),
+        createdAt: now,
+        updatedAt: now,
+      })
+      .run();
+  }
+
+  beforeEach(() => {
+    getDb().delete(providerConnections).run();
+  });
+
+  test("judges an entry-name profile by its row's vendor (vision-capable)", () => {
+    seedConnection({ name: "openrouter-personal", provider: "openrouter" });
+    setMockConfig({
+      "personal-opus": {
+        provider: "openrouter-personal",
+        model: "anthropic/claude-opus-4.6",
+      },
+    });
+    expect(doesSupportVision(profile("personal-opus"))).toBe(true);
+  });
+
+  test("judges an entry-name profile by its row's vendor (text-only)", () => {
+    seedConnection({ name: "openrouter-personal", provider: "openrouter" });
+    setMockConfig({
+      "personal-deepseek": {
+        provider: "openrouter-personal",
+        model: "deepseek/deepseek-v4-pro",
+      },
+    });
+    expect(doesSupportVision(profile("personal-deepseek"))).toBe(false);
+  });
+
+  test("an entry name naming no row fails safe to false", () => {
+    setMockConfig({
+      dangling: {
+        provider: "ghost-connection",
+        model: "anthropic/claude-opus-4.6",
+      },
+    });
+    expect(doesSupportVision(profile("dangling"))).toBe(false);
+  });
+
+  test("mix arms with entry-name providers translate the same way", () => {
+    seedConnection({ name: "openrouter-personal", provider: "openrouter" });
+    setMockConfig({
+      "mix-profile": {
+        mix: [
+          { profile: "personal-deepseek", weight: 0.5 },
+          { profile: "personal-opus", weight: 0.5 },
+        ],
+      },
+      "personal-deepseek": {
+        provider: "openrouter-personal",
+        model: "deepseek/deepseek-v4-pro",
+      },
+      "personal-opus": {
+        provider: "openrouter-personal",
+        model: "anthropic/claude-opus-4.6",
+      },
+    });
+    expect(doesSupportVision(profile("mix-profile"))).toBe(true);
+  });
+});
+
 describe("doesSupportVision with a bare string", () => {
   test("returns true for a known vision-capable model id", () => {
     expect(doesSupportVision("claude-opus-4-6")).toBe(true);

package/src/plugin-api/vision-support.ts

@@ -10,7 +10,9 @@
  *   resolved through `llm.profiles` to an effective `(provider, model)`.
  *   Default profile keys resolve through `llm.defaultProvider`'s column of the
  *   intent × provider matrix, so the judged model is the one that actually
- *   runs on a BYO install.
+ *   runs on a BYO install. A profile whose provider names a connection entry
+ *   row (e.g. a `<vendor>-personal` binding) is judged by the row's
+ *   dispatchable vendor, sharing dispatch's entry-name translation.
  *
  * A bare string is tried as a model id first and then as a profile key, so the
  * two callers share one function. Resolution returns `false` when nothing
@@ -21,6 +23,7 @@
 
 import { resolveDefaultProfileForProvider } from "../config/default-profile-catalog.js";
 import { getConfig } from "../config/loader.js";
+import { resolveEntryProviderKind } from "../providers/connection-resolution.js";
 import { ROUTING_IDENTITY_PROVIDERS } from "../providers/inference/auth.js";
 import {
   getCatalogProviderForModel,
@@ -117,12 +120,21 @@ function resolveEntryVision(entry: {
 }): boolean | undefined {
   // Routing identities ("vellum"/"chatgpt") are not catalog providers; the
   // model's catalog owner is the capability source for them.
-  const provider =
+  const declared =
     entry.provider != null && ROUTING_IDENTITY_PROVIDERS.has(entry.provider)
       ? undefined
       : entry.provider;
   const model = entry.model;
 
+  // A provider naming a connection entry row (e.g. a "<vendor>-personal"
+  // binding) translates to the row's dispatchable kind, the same translation
+  // dispatch uses, so the catalog judges the vendor actually serving the
+  // profile. Vendor ids pass through untranslated.
+  const provider =
+    declared != null
+      ? (resolveEntryProviderKind(declared, model) ?? declared)
+      : undefined;
+
   // Infer provider from model when missing (mirrors the resolver's catalog
   // provider implication).
   const effectiveProvider =