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

package/src/persistence/migrations/__tests__/382-create-client-connection-events.test.ts

@@ -0,0 +1,56 @@
+/**
+ * Migration 382 creates `client_connection_events`, the durable hub
+ * subscribe/dispose ledger used by `assistant clients history`.
+ */
+
+import { Database } from "bun:sqlite";
+import { describe, expect, test } from "bun:test";
+
+import { drizzle } from "drizzle-orm/bun-sqlite";
+
+import { getSqliteFrom } from "../../db-connection.js";
+import * as schema from "../../schema.js";
+import { migrateCreateClientConnectionEvents } from "../382-create-client-connection-events.js";
+
+function createTestDb() {
+  const sqlite = new Database(":memory:");
+  sqlite.exec("PRAGMA journal_mode=WAL");
+  return drizzle(sqlite, { schema });
+}
+
+function tableNames(db: ReturnType<typeof createTestDb>): string[] {
+  const rows = getSqliteFrom(db)
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'table'")
+    .all() as { name: string }[];
+  return rows.map((row) => row.name);
+}
+
+function indexNames(db: ReturnType<typeof createTestDb>): string[] {
+  const rows = getSqliteFrom(db)
+    .prepare("SELECT name FROM sqlite_master WHERE type = 'index'")
+    .all() as { name: string }[];
+  return rows.map((row) => row.name);
+}
+
+describe("migrateCreateClientConnectionEvents", () => {
+  test("creates the table and its lookup indexes", () => {
+    const db = createTestDb();
+
+    migrateCreateClientConnectionEvents(db);
+
+    expect(tableNames(db)).toContain("client_connection_events");
+    expect(indexNames(db)).toContain(
+      "idx_client_connection_events_client_occurred",
+    );
+    expect(indexNames(db)).toContain("idx_client_connection_events_occurred");
+  });
+
+  test("re-running is a no-op", () => {
+    const db = createTestDb();
+
+    migrateCreateClientConnectionEvents(db);
+    migrateCreateClientConnectionEvents(db);
+
+    expect(tableNames(db)).toContain("client_connection_events");
+  });
+});

package/src/persistence/schema/conversations.ts

@@ -1,5 +1,6 @@
 import { sql } from "drizzle-orm";
 import {
+  check,
   index,
   integer,
   primaryKey,
@@ -141,6 +142,72 @@ export const conversations = sqliteTable(
   ],
 );
 
+export const conversationModeSessions = sqliteTable(
+  "conversation_mode_sessions",
+  {
+    id: text("id").primaryKey(),
+    conversationId: text("conversation_id")
+      .notNull()
+      .references(() => conversations.id, { onDelete: "cascade" }),
+    mode: text("mode", {
+      enum: ["computer_use", "browser", "live_vision", "ambient"],
+    }).notNull(),
+    status: text("status", {
+      enum: ["active", "completed", "interrupted"],
+    }).notNull(),
+    sourceStartedAt: integer("source_started_at").notNull(),
+    firstIncludedAt: integer("first_included_at"),
+    firstIncludedMessageId: text("first_included_message_id"),
+    lastActivityAt: integer("last_activity_at").notNull(),
+    lastOwnedMessageId: text("last_owned_message_id"),
+    endedAt: integer("ended_at"),
+    endReason: text("end_reason"),
+    revision: integer("revision").notNull().default(1),
+  },
+  (table) => [
+    check(
+      "conversation_mode_sessions_mode_check",
+      sql`${table.mode} IN ('computer_use', 'browser', 'live_vision', 'ambient')`,
+    ),
+    check(
+      "conversation_mode_sessions_status_check",
+      sql`${table.status} IN ('active', 'completed', 'interrupted')`,
+    ),
+    check(
+      "conversation_mode_sessions_revision_check",
+      sql`${table.revision} > 0`,
+    ),
+    check(
+      "conversation_mode_sessions_first_included_boundary_check",
+      sql`(${table.firstIncludedAt} IS NULL) = (${table.firstIncludedMessageId} IS NULL)`,
+    ),
+    check(
+      "conversation_mode_sessions_terminal_fields_check",
+      sql`(
+        (${table.status} = 'active' AND ${table.endedAt} IS NULL AND ${table.endReason} IS NULL)
+        OR (${table.status} = 'completed' AND ${table.endedAt} IS NOT NULL AND ${table.endReason} IS NOT NULL AND length(${table.endReason}) > 0)
+        OR (${table.status} = 'interrupted' AND ${table.endReason} IS NOT NULL AND length(${table.endReason}) > 0)
+      )`,
+    ),
+    check(
+      "conversation_mode_sessions_end_after_activity_check",
+      sql`${table.endedAt} IS NULL OR ${table.endedAt} >= ${table.lastActivityAt}`,
+    ),
+    check(
+      "conversation_mode_sessions_activity_after_source_check",
+      sql`${table.lastActivityAt} >= ${table.sourceStartedAt}`,
+    ),
+    check(
+      "conversation_mode_sessions_first_included_before_activity_check",
+      sql`${table.firstIncludedAt} IS NULL OR ${table.firstIncludedAt} <= ${table.lastActivityAt}`,
+    ),
+    index("idx_conversation_mode_sessions_conversation_status").on(
+      table.conversationId,
+      table.status,
+    ),
+  ],
+);
+
 export const messages = sqliteTable(
   "messages",
   {

package/src/persistence/schema/infrastructure.ts

@@ -359,3 +359,32 @@ export const telemetryEvents = sqliteTable(
     index("idx_telemetry_events_conversation_id").on(table.conversationId),
   ],
 );
+
+/**
+ * Append-only hub subscribe/dispose ledger. Support reconstructs client
+ * uptime and reconnect flaps from these rows. No message bodies or page
+ * URLs: client UUID, interface, close reason, and optional build
+ * fingerprint only.
+ */
+export const clientConnectionEvents = sqliteTable(
+  "client_connection_events",
+  {
+    id: text("id").primaryKey(),
+    clientId: text("client_id").notNull(),
+    interfaceId: text("interface_id").notNull(),
+    connectionId: text("connection_id").notNull(),
+    reason: text("reason").notNull(),
+    occurredAt: integer("occurred_at").notNull(),
+    actorPrincipalId: text("actor_principal_id"),
+    clientVersion: text("client_version"),
+    sseWatchdog: integer("sse_watchdog", { mode: "boolean" }),
+    machineName: text("machine_name"),
+  },
+  (table) => [
+    index("idx_client_connection_events_client_occurred").on(
+      table.clientId,
+      table.occurredAt,
+    ),
+    index("idx_client_connection_events_occurred").on(table.occurredAt),
+  ],
+);

package/src/persistence/steps.ts

@@ -488,6 +488,11 @@ import { migrateAddSubagentBudgetStopReason } from "./migrations/377-add-subagen
 import { migrateCreateConversationToolSurfaces } from "./migrations/378-create-conversation-tool-surfaces.js";
 import { migrateOAuthProvidersResponseOkField } from "./migrations/379-oauth-providers-response-ok-field.js";
 import { migrateConversationToolSurfacesDelegateIndependentTasks } from "./migrations/380-conversation-tool-surfaces-delegate-independent-tasks.js";
+import {
+  downCreateConversationModeSessions,
+  migrateCreateConversationModeSessions,
+} from "./migrations/381-create-conversation-mode-sessions.js";
+import { migrateCreateClientConnectionEvents } from "./migrations/382-create-client-connection-events.js";
 import type { MigrationStep } from "./migrations/run-migrations.js";
 
 export const migrationSteps: MigrationStep[] = [
@@ -1632,4 +1637,16 @@ export const migrationSteps: MigrationStep[] = [
     // step must be checkpointed first.
     dependsOn: ["migrateCreateConversationToolSurfaces"],
   },
+  {
+    name: "migrateCreateConversationModeSessions",
+    run: migrateCreateConversationModeSessions,
+    rollback: [
+      {
+        version: 58,
+        description: "Create conversation-owned mode session lifecycle records",
+        down: downCreateConversationModeSessions,
+      },
+    ],
+  },
+  migrateCreateClientConnectionEvents,
 ];

package/src/plugin-api/__tests__/plugin-name-env.test.ts

@@ -0,0 +1,249 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { runInPluginContext } from "../../plugins/plugin-execution-context.js";
+import {
+  derivePluginNameFromProcess,
+  derivePluginNameFromSkillScriptPath,
+  PLUGIN_NAME_ENV,
+  readPluginNameFromEnv,
+  resolveCallingPluginName,
+} from "../plugin-name-env.js";
+
+const pluginsDir = "/tmp/vellum-workspace/plugins";
+
+describe("readPluginNameFromEnv", () => {
+  test("returns a trimmed install name", () => {
+    expect(readPluginNameFromEnv({ [PLUGIN_NAME_ENV]: "  sms  " })).toBe("sms");
+  });
+
+  test("ignores empty or whitespace-only values", () => {
+    expect(readPluginNameFromEnv({ [PLUGIN_NAME_ENV]: "" })).toBeUndefined();
+    expect(readPluginNameFromEnv({ [PLUGIN_NAME_ENV]: "   " })).toBeUndefined();
+    expect(readPluginNameFromEnv({})).toBeUndefined();
+  });
+});
+
+describe("derivePluginNameFromSkillScriptPath", () => {
+  test("returns the plugin install name for a scripts path", () => {
+    expect(
+      derivePluginNameFromSkillScriptPath(
+        join(pluginsDir, "sms/skills/sms-setup/scripts/twilio-numbers.ts"),
+        pluginsDir,
+      ),
+    ).toBe("sms");
+  });
+
+  test("returns the plugin install name for a tools path", () => {
+    expect(
+      derivePluginNameFromSkillScriptPath(
+        join(pluginsDir, "sms/skills/sms-setup/tools/list.ts"),
+        pluginsDir,
+      ),
+    ).toBe("sms");
+  });
+
+  test("accepts a file URL", () => {
+    const filePath = join(
+      pluginsDir,
+      "sms/skills/sms-setup/scripts/twilio-numbers.ts",
+    );
+    expect(
+      derivePluginNameFromSkillScriptPath(`file://${filePath}`, pluginsDir),
+    ).toBe("sms");
+  });
+
+  test("rejects a path outside plugins/", () => {
+    expect(
+      derivePluginNameFromSkillScriptPath(
+        "/tmp/other/skills/sms-setup/scripts/twilio-numbers.ts",
+        pluginsDir,
+      ),
+    ).toBeUndefined();
+  });
+
+  test("rejects a plugin file that is not under scripts/ or tools/", () => {
+    expect(
+      derivePluginNameFromSkillScriptPath(
+        join(pluginsDir, "sms/skills/sms-setup/SKILL.md"),
+        pluginsDir,
+      ),
+    ).toBeUndefined();
+    expect(
+      derivePluginNameFromSkillScriptPath(
+        join(pluginsDir, "sms/register.ts"),
+        pluginsDir,
+      ),
+    ).toBeUndefined();
+  });
+
+  test("rejects a truncated plugins path", () => {
+    expect(
+      derivePluginNameFromSkillScriptPath(
+        join(pluginsDir, "sms/skills/scripts/too-short.ts"),
+        pluginsDir,
+      ),
+    ).toBeUndefined();
+  });
+});
+
+describe("derivePluginNameFromProcess", () => {
+  test("scans argv for a plugin-resident skill script", () => {
+    expect(
+      derivePluginNameFromProcess(
+        ["bun", join(pluginsDir, "sms/skills/sms-setup/scripts/twilio-numbers.ts")],
+        "/tmp",
+        pluginsDir,
+      ),
+    ).toBe("sms");
+  });
+
+  test("resolves a relative argv path against cwd", () => {
+    expect(
+      derivePluginNameFromProcess(
+        ["bun", "sms/skills/sms-setup/scripts/twilio-numbers.ts"],
+        pluginsDir,
+        pluginsDir,
+      ),
+    ).toBe("sms");
+  });
+
+  test("skips flags", () => {
+    expect(
+      derivePluginNameFromProcess(
+        ["bun", "--hot", join(pluginsDir, "sms/skills/sms-setup/scripts/twilio-numbers.ts")],
+        "/tmp",
+        pluginsDir,
+      ),
+    ).toBe("sms");
+  });
+});
+
+describe("resolveCallingPluginName", () => {
+  const prior = process.env[PLUGIN_NAME_ENV];
+
+  afterEach(() => {
+    if (prior === undefined) {
+      delete process.env[PLUGIN_NAME_ENV];
+    } else {
+      process.env[PLUGIN_NAME_ENV] = prior;
+    }
+  });
+
+  test("prefers AsyncLocalStorage over env", () => {
+    process.env[PLUGIN_NAME_ENV] = "from-env";
+    const name = runInPluginContext("from-als", () =>
+      resolveCallingPluginName(process.env, [], "/tmp"),
+    );
+    expect(name).toBe("from-als");
+  });
+
+  test("uses VELLUM_PLUGIN_NAME when ALS is empty", () => {
+    expect(
+      resolveCallingPluginName({ [PLUGIN_NAME_ENV]: "sms" }, [], "/tmp"),
+    ).toBe("sms");
+  });
+
+  test("falls back to the process entry path", () => {
+    expect(
+      resolveCallingPluginName(
+        {},
+        ["bun", join(pluginsDir, "sms/skills/sms-setup/scripts/twilio-numbers.ts")],
+        "/tmp",
+        pluginsDir,
+      ),
+    ).toBe("sms");
+  });
+});
+
+describe("resolveCallingPluginName real child", () => {
+  test("recovers the plugin name from a scripts path without env", async () => {
+    const workspace = mkdtempSync(join(tmpdir(), "plugin-name-child-"));
+    const scriptDir = join(
+      workspace,
+      "plugins/sms/skills/sms-setup/scripts",
+    );
+    mkdirSync(scriptDir, { recursive: true });
+    const helper = join(
+      import.meta.dir,
+      "..",
+      "plugin-name-env.ts",
+    );
+    const scriptPath = join(scriptDir, "echo-plugin-name.ts");
+    writeFileSync(
+      scriptPath,
+      `import { resolveCallingPluginName } from ${JSON.stringify(helper)};
+console.log(JSON.stringify({ name: resolveCallingPluginName() ?? null }));
+`,
+    );
+
+    try {
+      const child = Bun.spawn(
+        ["bun", scriptPath],
+        {
+          cwd: scriptDir,
+          env: {
+            PATH: process.env.PATH,
+            HOME: process.env.HOME,
+            VELLUM_WORKSPACE_DIR: workspace,
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      );
+      const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+        child.exited,
+      ]);
+      expect(stderr).toBe("");
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout.trim())).toEqual({ name: "sms" });
+    } finally {
+      rmSync(workspace, { recursive: true, force: true });
+    }
+  }, 15_000);
+
+  test("recovers the plugin name from VELLUM_PLUGIN_NAME without a plugin path", async () => {
+    const workspace = mkdtempSync(join(tmpdir(), "plugin-name-env-child-"));
+    const scriptDir = join(workspace, "scratch");
+    mkdirSync(scriptDir, { recursive: true });
+    const helper = join(import.meta.dir, "..", "plugin-name-env.ts");
+    const scriptPath = join(scriptDir, "echo-plugin-name.ts");
+    writeFileSync(
+      scriptPath,
+      `import { resolveCallingPluginName } from ${JSON.stringify(helper)};
+console.log(JSON.stringify({ name: resolveCallingPluginName() ?? null }));
+`,
+    );
+
+    try {
+      const child = Bun.spawn(
+        ["bun", scriptPath],
+        {
+          cwd: scriptDir,
+          env: {
+            PATH: process.env.PATH,
+            HOME: process.env.HOME,
+            VELLUM_WORKSPACE_DIR: workspace,
+            VELLUM_PLUGIN_NAME: "sms",
+          },
+          stdout: "pipe",
+          stderr: "pipe",
+        },
+      );
+      const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(child.stdout).text(),
+        new Response(child.stderr).text(),
+        child.exited,
+      ]);
+      expect(stderr).toBe("");
+      expect(exitCode).toBe(0);
+      expect(JSON.parse(stdout.trim())).toEqual({ name: "sms" });
+    } finally {
+      rmSync(workspace, { recursive: true, force: true });
+    }
+  }, 15_000);
+});

package/src/plugin-api/effective-context-window.ts

@@ -0,0 +1,33 @@
+import { resolveEffectiveContextWindow } from "../config/llm-context-resolution.js";
+import type { ResolveCallSiteOpts } from "../config/llm-resolver.js";
+import { getConfig } from "../config/loader.js";
+import type { LLMCallSite } from "../config/schemas/llm.js";
+
+export interface EffectiveContextWindowInfo {
+  provider: string;
+  model: string;
+  maxInputTokens: number;
+}
+
+export type EffectiveContextWindowOptions = Pick<
+  ResolveCallSiteOpts,
+  "overrideProfile" | "forceOverrideProfile" | "selectionSeed"
+>;
+
+/**
+ * Resolve the provider, model, and effective input limit for one configured
+ * call site. The result applies both the workspace override and the selected
+ * model's catalog limit, using the same profile-selection options accepted by
+ * {@link getConfiguredProvider}.
+ */
+export function getEffectiveContextWindow(
+  callSite: LLMCallSite,
+  options: EffectiveContextWindowOptions = {},
+): EffectiveContextWindowInfo {
+  const { provider, model, maxInputTokens } = resolveEffectiveContextWindow({
+    llm: getConfig().llm,
+    callSite,
+    ...options,
+  });
+  return { provider, model, maxInputTokens };
+}

package/src/plugin-api/index.ts

@@ -33,9 +33,11 @@
  * - {@link assistantEventHub} — the assistant's pub/sub hub for runtime events
  * - {@link getModelProfiles} — list the workspace inference profiles a plugin
  *   can route to (e.g. a model router building its category → profile map)
- * - {@link getConfiguredProvider} — resolve a {@link Provider} for a call site
+ * - {@link getConfiguredProvider}: resolve a {@link Provider} for a call site
  *   (optionally overriding the profile) and run inference through the
- *   workspace's configured profiles and credentials — no plugin-supplied API key
+ *   workspace's configured profiles and credentials, with no plugin-supplied API key
+ * - {@link getEffectiveContextWindow}: resolve that call site's provider,
+ *   model, and effective maximum input size
  *
  * - {@link InitContext} — passed to `init` hook at bootstrap
  * - {@link ShutdownContext} — passed to `shutdown` hook at teardown
@@ -169,10 +171,12 @@ export { publishEvent } from "./publish-event.js";
 // `inputModalities.image` override winning when set (mix profiles are
 // vision-capable if any arm is). Returns false when nothing resolves.
 export { doesSupportVision } from "./vision-support.js";
-// Resolve a stored credential to its plaintext value — the same value
-// `assistant credentials reveal` prints — from a UUID or a "service/field"
+// Resolve a stored credential to its plaintext value (the same value
+// `assistant credentials reveal` prints) from a UUID or a "service/field"
 // reference. When a plugin is in context, resolution is scoped to credentials
-// whose service matches the plugin's manifest name; outside any plugin it is
+// whose service matches the plugin's runtime name. A plugin-resident skill
+// script or skill-tool child presents a daemon-issued invocation grant and is
+// scoped the same way. Outside any plugin context or grant the resolver is
 // unscoped. Throws CredentialResolutionError when the ref does not resolve, the
 // store is unreachable, or the credential is out of the plugin's scope.
 export {
@@ -218,6 +222,11 @@ export { resolveOauthCallbackUrl } from "../inbound/oauth-callback-url.js";
 // float the chosen profile above the call-site layers when the plugin must
 // run on a specific profile regardless of workspace tuning.
 export { getConfiguredProvider } from "../providers/provider-send-message.js";
+export type {
+  EffectiveContextWindowInfo,
+  EffectiveContextWindowOptions,
+} from "./effective-context-window.js";
+export { getEffectiveContextWindow } from "./effective-context-window.js";
 // Resolve an image/file block's media `source` to its bytes as inline base64,
 // whether the source is inline base64 or a persisted workspace reference
 // (attachment-store row or a file on disk). Returns null when a reference can no
@@ -401,6 +410,16 @@ export { persistSystemCard } from "./system-card.js";
 // what makes that true. Host tools and plugin tools share this one guard.
 export type { CancellableToolContext } from "./tool-cancellation.js";
 export { throwIfCancelled } from "./tool-cancellation.js";
+// Tool input from a Zod schema: derive the advertised `input_schema` from the
+// schema the tool parses its input with, so what the model is told and what
+// the tool accepts share one source. The host validates built-in tools'
+// input centrally; a plugin tool parses its own, and answers a failed parse
+// with `invalidToolInputResult` so its message reads the same as the host's.
+export {
+  invalidToolInputResult,
+  nullAsOmitted,
+  toToolInputSchema,
+} from "../tools/shared/zod-tool-schema.js";
 // Synthesize text to speech through the assistant's globally configured TTS
 // provider (ElevenLabs, Fish Audio, etc.). Plugins that need voice output —
 // e.g. a meeting bot speaking into a live call — use this instead of managing

package/src/plugin-api/plugin-name-env.ts

@@ -0,0 +1,125 @@
+/**
+ * How a child process learns which plugin it is running as.
+ *
+ * In-process plugin hooks, tools, and routes use AsyncLocalStorage
+ * ({@link getCurrentPluginName}). A bash or skill-sandbox child does not
+ * inherit that store. Those children recover the install-directory basename
+ * from `VELLUM_PLUGIN_NAME` (injected after env sanitization) or from the
+ * entry script path under `plugins/<service>/skills/<skill>/{scripts,tools}/`.
+ */
+
+import { isAbsolute, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getCurrentPluginName } from "../plugins/plugin-execution-context.js";
+import { getWorkspacePluginsDir } from "../util/platform.js";
+
+export const PLUGIN_NAME_ENV = "VELLUM_PLUGIN_NAME";
+
+const SKILL_SCRIPT_ROOTS = new Set(["scripts", "tools"]);
+
+/**
+ * Read a plugin install-directory name from the process environment.
+ * Empty or whitespace-only values are ignored.
+ */
+export function readPluginNameFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  const raw = env[PLUGIN_NAME_ENV];
+  if (typeof raw !== "string") {
+    return undefined;
+  }
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * If `filePath` is a skill script or tool under an installed plugin, return
+ * that plugin's install-directory basename (the runtime service name).
+ *
+ * Expected layout:
+ * `plugins/<service>/skills/<skill-id>/scripts|tools/<file>`.
+ */
+export function derivePluginNameFromSkillScriptPath(
+  filePath: string,
+  pluginsDir: string = getWorkspacePluginsDir(),
+): string | undefined {
+  if (filePath.length === 0) {
+    return undefined;
+  }
+  let resolved = filePath;
+  if (filePath.startsWith("file:")) {
+    try {
+      resolved = fileURLToPath(filePath);
+    } catch {
+      return undefined;
+    }
+  }
+  if (!isAbsolute(resolved)) {
+    resolved = resolve(process.cwd(), resolved);
+  }
+  const pluginsRoot = resolve(pluginsDir);
+  const rel = relative(pluginsRoot, resolved);
+  if (rel.length === 0 || rel.startsWith("..") || isAbsolute(rel)) {
+    return undefined;
+  }
+  const parts = rel.split(sep).filter((part) => part.length > 0);
+  if (parts.length < 5) {
+    return undefined;
+  }
+  const [service, skillsSeg, skillId, root] = parts;
+  if (
+    service === undefined ||
+    skillsSeg !== "skills" ||
+    skillId === undefined ||
+    root === undefined ||
+    !SKILL_SCRIPT_ROOTS.has(root)
+  ) {
+    return undefined;
+  }
+  return service;
+}
+
+/**
+ * Scan argv for a plugin-resident skill script path, resolving relative
+ * entries against `cwd`.
+ */
+export function derivePluginNameFromProcess(
+  argv: readonly string[] = process.argv,
+  cwd: string = process.cwd(),
+  pluginsDir: string = getWorkspacePluginsDir(),
+): string | undefined {
+  for (const candidate of argv.slice(1)) {
+    if (typeof candidate !== "string" || candidate.length === 0) {
+      continue;
+    }
+    if (candidate.startsWith("-")) {
+      continue;
+    }
+    const absolute = isAbsolute(candidate)
+      ? candidate
+      : resolve(cwd, candidate);
+    const name = derivePluginNameFromSkillScriptPath(absolute, pluginsDir);
+    if (name !== undefined) {
+      return name;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Plugin identity for credential scoping: in-process AsyncLocalStorage,
+ * then the injected env var, then the process entry script path.
+ */
+export function resolveCallingPluginName(
+  env: NodeJS.ProcessEnv = process.env,
+  argv: readonly string[] = process.argv,
+  cwd: string = process.cwd(),
+  pluginsDir: string = getWorkspacePluginsDir(),
+): string | undefined {
+  return (
+    getCurrentPluginName() ??
+    readPluginNameFromEnv(env) ??
+    derivePluginNameFromProcess(argv, cwd, pluginsDir)
+  );
+}