@vellumai/assistant 0.6.6 → 0.7.1

package/node_modules/@vellumai/skill-host-contracts/src/tool-types.ts

@@ -0,0 +1,444 @@
+/**
+ * Tool-related type declarations shared between the daemon and any
+ * skill-side package that needs to describe tools, permission risk, or tool
+ * execution results on the wire.
+ *
+ * Pure type-level declarations only (+ the `RiskLevel` enum, which is a value
+ * but is safely cross-package). No runtime helpers live here — the assistant
+ * keeps all behavior functions in `assistant/src/tools/` and re-exports the
+ * types from this file.
+ *
+ * Heavy daemon-internal references (CES client, host-proxy classes, trust
+ * classifications, interface IDs, content blocks, CES `ApprovalRequired`)
+ * are held as opaque `unknown` / broadened-`string` placeholders on this
+ * side so the contracts package never reaches into the assistant or the
+ * service-contracts runtime. The assistant redeclares `Tool`, `ToolContext`,
+ * `ToolExecutionResult`, `ToolExecutedEvent`, `ToolLifecycleEvent`,
+ * `ToolLifecycleEventHandler`, and `ProxyToolResolver` in
+ * `assistant/src/tools/types.ts` with the concrete types in place, so
+ * existing call sites keep their full type information. The two sides are
+ * structurally independent — no inheritance, no intersection — which
+ * avoids TypeScript's contravariance mismatches on lifecycle-event
+ * handlers.
+ */
+
+// ---------------------------------------------------------------------------
+// Simple type-level declarations — moved in full
+// ---------------------------------------------------------------------------
+
+export type ExecutionTarget = "sandbox" | "host";
+
+export enum RiskLevel {
+  Low = "low",
+  Medium = "medium",
+  High = "high",
+}
+
+export interface ToolDefinition {
+  name: string;
+  description: string;
+  input_schema: object;
+}
+
+export type ErrorCategory =
+  | "permission_denied"
+  | "auth"
+  | "tool_failure"
+  | "unexpected";
+
+export interface DiffInfo {
+  filePath: string;
+  oldContent: string;
+  newContent: string;
+  isNewFile: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Sensitive-output binding (pure data)
+// ---------------------------------------------------------------------------
+
+export type SensitiveOutputKind = "invite_code";
+
+export interface SensitiveOutputBinding {
+  kind: SensitiveOutputKind;
+  placeholder: string;
+  value: string;
+}
+
+// ---------------------------------------------------------------------------
+// Proxy approval contract (pure data + callback signature)
+// ---------------------------------------------------------------------------
+
+/** Approval request from the outbound proxy when a policy decision requires user confirmation. */
+export interface ProxyApprovalRequest {
+  decision: {
+    kind: "ask_missing_credential" | "ask_unauthenticated";
+    target: {
+      hostname: string;
+      port: number | null;
+      path: string;
+      scheme: "http" | "https";
+    };
+    /** Present when kind is "ask_missing_credential". */
+    matchingPatterns?: string[];
+  };
+  sessionId: string;
+  /** HTTP method (plain HTTP only; undefined for HTTPS CONNECT tunnels). */
+  method?: string;
+  /** Curated non-sensitive headers (plain HTTP only). */
+  requestHeaders?: Record<string, string>;
+}
+
+/** Callback for proxy policy decisions requiring user confirmation. Returns true if approved. */
+export type ProxyApprovalCallback = (
+  request: ProxyApprovalRequest,
+) => Promise<boolean>;
+
+/** Env vars a proxy session injects into child processes. */
+export interface ProxyEnvVars {
+  HTTP_PROXY: string;
+  HTTPS_PROXY: string;
+  NO_PROXY: string;
+  NODE_EXTRA_CA_CERTS?: string;
+  SSL_CERT_FILE?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Tool execution result
+//
+// `contentBlocks` is declared as `unknown[]` here; the assistant redeclares
+// this interface with the concrete `ContentBlock[]` in its own copy.
+// Skill-side consumers that don't care about typed content-block access are
+// unaffected.
+// ---------------------------------------------------------------------------
+
+export interface ToolExecutionResult {
+  content: string;
+  isError: boolean;
+  diff?: DiffInfo;
+  /** Optional status message for display (e.g. timeout, truncation). */
+  status?: string;
+  /** Optional rich content blocks (e.g. images) to include alongside text in the tool result. */
+  contentBlocks?: unknown[];
+  /**
+   * Runtime-internal sensitive output bindings (placeholder -> real value).
+   * Populated by the executor when tool output contains
+   * `<vellum-sensitive-output>` directives. The agent loop merges these
+   * into a per-run substitution map for deterministic post-generation
+   * replacement. MUST NOT be emitted in client-facing events or logs.
+   */
+  sensitiveBindings?: SensitiveOutputBinding[];
+  /**
+   * When true, the agent loop should yield control back to the user after
+   * returning this result — tool results are pushed to history and the loop
+   * breaks without another LLM call. Two callers set this: interactive
+   * surfaces (tables with action buttons, file uploads) that force-stop the
+   * loop so the LLM cannot bypass the "wait for user action" instruction,
+   * and tools like `remember` that expose a `finish_turn` parameter letting
+   * the LLM voluntarily end its turn.
+   */
+  yieldToUser?: boolean;
+  /** Risk level from the classifier (populated during permission check). */
+  riskLevel?: string;
+  /** Human-readable reason for the risk classification. */
+  riskReason?: string;
+  /** ID of the trust rule that matched this invocation (if any). */
+  matchedTrustRuleId?: string;
+  /** Whether the daemon is running in a containerized (Docker) environment. */
+  isContainerized?: boolean;
+  /** Scope options ladder for the rule editor (narrowest to broadest). */
+  riskScopeOptions?: Array<{ pattern: string; label: string }>;
+  /**
+   * When present, indicates that a CES tool returned an `approval_required`
+   * response. The executor uses the approval bridge to prompt the guardian,
+   * commit the grant decision to CES, and retry the original tool invocation
+   * with the granted grantId. CES tools populate this field rather than
+   * returning a textual error so the executor can intercept and handle the
+   * approval flow transparently.
+   *
+   * Declared as `unknown` here to keep this package free of CES runtime
+   * imports; the assistant narrows it back to the concrete `ApprovalRequired`
+   * shape via intersection.
+   */
+  cesApprovalRequired?: unknown;
+}
+
+export type ProxyToolResolver = (
+  toolName: string,
+  input: Record<string, unknown>,
+) => Promise<ToolExecutionResult>;
+
+// ---------------------------------------------------------------------------
+// Tool lifecycle events
+// ---------------------------------------------------------------------------
+
+interface ToolLifecycleEventBase {
+  toolName: string;
+  input: Record<string, unknown>;
+  workingDir: string;
+  conversationId: string;
+  requestId?: string;
+  executionTarget?: ExecutionTarget;
+}
+
+export interface AllowlistOption {
+  label: string;
+  description: string;
+  pattern: string;
+}
+
+export interface ScopeOption {
+  label: string;
+  scope: string;
+}
+
+export interface ToolExecutionStartEvent extends ToolLifecycleEventBase {
+  type: "start";
+  startedAtMs: number;
+}
+
+export interface ToolPermissionPromptEvent extends ToolLifecycleEventBase {
+  type: "permission_prompt";
+  riskLevel: string;
+  /** Classifier-provided reason explaining why the risk level was assigned (bash/host_bash only). */
+  riskReason?: string;
+  reason: string;
+  allowlistOptions: AllowlistOption[];
+  scopeOptions: ScopeOption[];
+  diff?: DiffInfo;
+  persistentDecisionsAllowed?: boolean;
+}
+
+export interface ToolPermissionDeniedEvent extends ToolLifecycleEventBase {
+  type: "permission_denied";
+  riskLevel: string;
+  /** Classifier-provided reason explaining why the risk level was assigned (bash/host_bash only). */
+  riskReason?: string;
+  /** ID of the trust rule that matched this invocation (if any). */
+  matchedTrustRuleId?: string;
+  decision: "deny" | "always_deny";
+  reason: string;
+  durationMs: number;
+}
+
+export interface ToolExecutedEvent extends ToolLifecycleEventBase {
+  type: "executed";
+  riskLevel: string;
+  /** ID of the trust rule that matched this invocation (if any). */
+  matchedTrustRuleId?: string;
+  decision: string;
+  durationMs: number;
+  result: ToolExecutionResult;
+}
+
+export interface ToolExecutionErrorEvent extends ToolLifecycleEventBase {
+  type: "error";
+  riskLevel: string;
+  /** ID of the trust rule that matched this invocation (if any). */
+  matchedTrustRuleId?: string;
+  decision: string;
+  durationMs: number;
+  errorMessage: string;
+  isExpected: boolean;
+  /** Classifies the error for downstream consumers (audit, alerting, monitoring). */
+  errorCategory: ErrorCategory;
+  errorName?: string;
+  errorStack?: string;
+}
+
+export type ToolLifecycleEvent =
+  | ToolExecutionStartEvent
+  | ToolPermissionPromptEvent
+  | ToolPermissionDeniedEvent
+  | ToolExecutedEvent
+  | ToolExecutionErrorEvent;
+
+export type ToolLifecycleEventHandler = (
+  event: ToolLifecycleEvent,
+) => void | Promise<void>;
+
+// ---------------------------------------------------------------------------
+// Tool context
+//
+// Heavy daemon-internal fields (CES client, host-proxy classes, trust
+// classification, interface ID, secret-prompt result shape) are declared
+// `unknown` here. The assistant redeclares `ToolContext` with the concrete
+// daemon types in its own copy.
+// ---------------------------------------------------------------------------
+
+export interface ToolContext {
+  workingDir: string;
+  conversationId: string;
+  /** Logical assistant scope for multi-assistant routing. */
+  assistantId?: string;
+  /** When set, the tool execution is part of a task run. Used to retrieve ephemeral permission rules. */
+  taskRunId?: string;
+  /** Per-message request ID for log correlation across conversation/connection boundaries. */
+  requestId?: string;
+  /** Optional callback for streaming incremental output to the client. */
+  onOutput?: (chunk: string) => void;
+  /** Abort signal for cooperative cancellation. Tools should check this periodically. */
+  signal?: AbortSignal;
+  /** Optional callback for tool lifecycle events (start/prompt/deny/execute/error). */
+  onToolLifecycleEvent?: ToolLifecycleEventHandler;
+  /** Optional resolver for proxy tools - delegates execution to an external client. */
+  proxyToolResolver?: ProxyToolResolver;
+  /** When set, only tools in this set may execute. Tools outside the set are blocked with an error. */
+  allowedToolNames?: Set<string>;
+  /**
+   * Prompt the user for a secret value via native SecureField UI.
+   *
+   * The concrete return shape is owned by the assistant
+   * (`SecretPromptResult`); declared as `unknown` here so this package stays
+   * free of daemon-side imports.
+   */
+  requestSecret?: (params: {
+    service: string;
+    field: string;
+    label: string;
+    description?: string;
+    placeholder?: string;
+    purpose?: string;
+    allowedTools?: string[];
+    allowedDomains?: string[];
+  }) => Promise<unknown>;
+  /** Optional callback to send a message to the connected client (e.g. open_url). */
+  sendToClient?: (msg: { type: string; [key: string]: unknown }) => void;
+  /** True when an interactive client is connected (not just a no-op callback). */
+  isInteractive?: boolean;
+  /** Memory scope ID from the conversation's memory policy, so memory tools can target the correct scope. */
+  memoryScopeId?: string;
+  /** When true, tools with side effects should always prompt for confirmation. */
+  forcePromptSideEffects?: boolean;
+  /**
+   * When true, the tool requires a fresh interactive approval for every
+   * invocation - no cached grants, temporary overrides, persistent
+   * "Always Allow" rules, or non-interactive auto-approve shortcuts may
+   * bypass the prompt. This flag is independently sufficient: it
+   * promotes allow → prompt decisions on its own and suppresses
+   * temporary override options in the prompt UI. Used by
+   * `manage_secure_command_tool` to ensure a human reviews each secure
+   * bundle installation.
+   */
+  requireFreshApproval?: boolean;
+  /** Approval callback for proxy policy decisions that require user confirmation. */
+  proxyApprovalCallback?: ProxyApprovalCallback;
+  /** Optional principal identifier propagated to sub-tool confirmation flows. */
+  principal?: string;
+  /**
+   * Trust classification of the actor who initiated this tool invocation.
+   * Broadened to `string` here; the assistant narrows this back to its
+   * concrete `TrustClass` union ("guardian" | "trusted_contact" | "unknown")
+   * in `assistant/src/tools/types.ts`.
+   */
+  trustClass: string;
+  /** Channel through which the tool invocation originates (e.g. 'telegram', 'phone'). Used for scoped grant consumption. */
+  executionChannel?: string;
+  /** Voice/call session ID, if the invocation originates from a call. Used for scoped grant consumption. */
+  callSessionId?: string;
+  /** True when the tool invocation was triggered by a user clicking a surface action button (not a regular message). */
+  triggeredBySurfaceAction?: boolean;
+  /** True when the user explicitly approved this tool invocation via the interactive permission prompt (not auto-approved by trust rules or temporary overrides). */
+  approvedViaPrompt?: boolean;
+  /**
+   * True when the invocation is inside a scheduled task run whose
+   * `required_tools` array pre-authorized this tool at task-creation time.
+   * Tools that normally require a surface-action click (e.g. bulk archive,
+   * unsubscribe) may treat this as equivalent consent, since the user
+   * already reviewed the tool list when the task was saved.
+   */
+  batchAuthorizedByTask?: boolean;
+  /** External user ID of the requester (non-guardian actor). Used for scoped grant consumption. */
+  requesterExternalUserId?: string;
+  /** Chat ID of the requester (non-guardian actor). Used for tool grant request escalation notifications. */
+  requesterChatId?: string;
+  /** Human-readable identifier for the requester (e.g., @username). */
+  requesterIdentifier?: string;
+  /** Preferred display name for the requester. */
+  requesterDisplayName?: string;
+  /** Slack channel ID for channel-scoped permission enforcement. When set, tools are checked against the channel's permission profile. */
+  channelPermissionChannelId?: string;
+  /** The tool_use block ID from the LLM response, used to correlate confirmation prompts with specific tool invocations. */
+  toolUseId?: string;
+  /**
+   * Optional proxy for delegating host_bash execution to a connected client
+   * (managed/cloud-hosted mode). Held as `unknown` here; the assistant
+   * narrows to the concrete `HostBashProxy` class.
+   */
+  hostBashProxy?: unknown;
+  /**
+   * Optional proxy for delegating CDP commands to a connected client
+   * (managed/cloud-hosted mode). Held as `unknown` here; the assistant
+   * narrows to the concrete `HostBrowserProxy` class.
+   */
+  hostBrowserProxy?: unknown;
+  /**
+   * Optional proxy for delegating host_file_read/write/edit execution to a
+   * connected client (managed/cloud-hosted mode). Held as `unknown` here;
+   * the assistant narrows to the concrete `HostFileProxy` class.
+   */
+  hostFileProxy?: unknown;
+  /** True when the assistant is running as a platform-managed remote instance. Used to auto-approve sandboxed bash tools. */
+  isPlatformHosted?: boolean;
+  /**
+   * CES RPC client for credential execution operations. Held as `unknown`
+   * here; the assistant narrows to the concrete `CesClient` class.
+   */
+  cesClient?: unknown;
+  /**
+   * The interface ID of the connected client driving the current turn (e.g.
+   * "macos", "chrome-extension"). Browser backend policy uses this to decide
+   * transport preference — for example, macOS-originated turns prefer the
+   * user's real Chrome session via the paired extension before falling back
+   * to cdp-inspect or local Playwright.
+   *
+   * Broadened to `string` here; the assistant narrows to its concrete
+   * `InterfaceId` union.
+   */
+  transportInterface?: string;
+  /**
+   * True when the host browser proxy's sender was overridden by an
+   * extension connection (WebSocket browser-relay).
+   * The CDP factory uses this to distinguish between an SSE-backed proxy
+   * (macOS, no extension) and an extension-backed proxy: only the latter
+   * should suppress desktop-auto cdp-inspect when temporarily unavailable,
+   * because the extension transport was explicitly expected and the
+   * disconnection is transient. An SSE-backed proxy that reports
+   * unavailable (e.g. non-interactive turn) should NOT suppress
+   * cdp-inspect — the proxy was never expected to service browser requests.
+   */
+  hostBrowserRegistryRouted?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Tool
+// ---------------------------------------------------------------------------
+
+export interface Tool {
+  name: string;
+  description: string;
+  category: string;
+  defaultRiskLevel: RiskLevel;
+  /** When set to 'proxy', the tool is forwarded to a connected client rather than executed locally. */
+  executionMode?: "local" | "proxy";
+  /** Whether this tool is a core built-in, provided by a skill, contributed by a plugin, or from an MCP server. */
+  origin?: "core" | "skill" | "mcp" | "plugin";
+  /** If origin is 'skill', the ID of the owning skill. */
+  ownerSkillId?: string;
+  /** If origin is 'mcp', the ID of the owning MCP server. */
+  ownerMcpServerId?: string;
+  /** If origin is 'plugin', the name of the owning plugin. */
+  ownerPluginId?: string;
+  /** Content-hash of the owning skill's source at registration time. */
+  ownerSkillVersionHash?: string;
+  /** Whether the owning skill is bundled with the daemon (trusted first-party). */
+  ownerSkillBundled?: boolean;
+  /** Declared execution target from the skill manifest. Used by resolveExecutionTarget
+   * to accurately label lifecycle events for skill-provided tools. */
+  executionTarget?: ExecutionTarget;
+  getDefinition(): ToolDefinition;
+  execute(
+    input: Record<string, unknown>,
+    context: ToolContext,
+  ): Promise<ToolExecutionResult>;
+}

package/node_modules/@vellumai/skill-host-contracts/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["bun-types"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/skill-host-contracts/tsconfig.test.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "noEmit": true,
+    "declaration": false,
+    "declarationMap": false,
+    "sourceMap": false
+  },
+  "include": ["src/**/*", "__tests__/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

package/node_modules/@vellumai/slack-text/bun.lock

@@ -0,0 +1,24 @@
+{
+  "lockfileVersion": 1,
+  "configVersion": 1,
+  "workspaces": {
+    "": {
+      "name": "@vellumai/slack-text",
+      "devDependencies": {
+        "@types/bun": "1.3.10",
+        "typescript": "5.9.3",
+      },
+    },
+  },
+  "packages": {
+    "@types/bun": ["@types/bun@1.3.10", "", { "dependencies": { "bun-types": "1.3.10" } }, "sha512-0+rlrUrOrTSskibryHbvQkDOWRJwJZqZlxrUs1u4oOoTln8+WIXBPmAuCF35SWB2z4Zl3E84Nl/D0P7803nigQ=="],
+
+    "@types/node": ["@types/node@25.6.0", "", { "dependencies": { "undici-types": "~7.19.0" } }, "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ=="],
+
+    "bun-types": ["bun-types@1.3.10", "", { "dependencies": { "@types/node": "*" } }, "sha512-tcpfCCl6XWo6nCVnpcVrxQ+9AYN1iqMIzgrSKYMB/fjLtV2eyAVEg7AxQJuCq/26R6HpKWykQXuSOq/21RYcbg=="],
+
+    "typescript": ["typescript@5.9.3", "", { "bin": { "tsc": "bin/tsc", "tsserver": "bin/tsserver" } }, "sha512-jl1vZzPDinLr9eUt3J/t7V6FgNEw9QjvBPdysz9KfQDD41fQrC2Y4vKQdiaUpFT4bXlb1RHhLpp8wtm6M5TgSw=="],
+
+    "undici-types": ["undici-types@7.19.2", "", {}, "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg=="],
+  }
+}

package/node_modules/@vellumai/slack-text/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@vellumai/slack-text",
+  "version": "0.0.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "bunx tsc --noEmit",
+    "test": "bun test src/"
+  },
+  "devDependencies": {
+    "@types/bun": "1.3.10",
+    "typescript": "5.9.3"
+  }
+}

package/node_modules/@vellumai/slack-text/src/index.test.ts

@@ -0,0 +1,153 @@
+import { describe, expect, test } from "bun:test";
+
+import {
+  buildSlackUserLabelMap,
+  extractSlackUserMentionIds,
+  renderSlackTextForModel,
+  stripLeadingSlackMentionFallback,
+  stripLeadingSlackUserMention,
+} from "./index.js";
+
+describe("extractSlackUserMentionIds", () => {
+  test("returns unique user mention IDs in encounter order", () => {
+    expect(
+      extractSlackUserMentionIds("<@U123> hi <@W456> and <@U123> again")
+    ).toEqual(["U123", "W456"]);
+  });
+});
+
+describe("stripLeadingSlackUserMention", () => {
+  test("strips only leading mentions for the exact bot ID", () => {
+    expect(stripLeadingSlackUserMention("<@U111> <@U222> hi", "U111")).toBe(
+      "<@U222> hi"
+    );
+  });
+
+  test("strips repeated leading mentions for the exact bot ID", () => {
+    expect(stripLeadingSlackUserMention(" <@U111> <@U111> hi", "U111")).toBe(
+      "hi"
+    );
+  });
+
+  test("preserves text when the leading mention is a different user", () => {
+    expect(stripLeadingSlackUserMention("<@U222> hi <@U111>", "U111")).toBe(
+      "<@U222> hi <@U111>"
+    );
+  });
+});
+
+describe("stripLeadingSlackMentionFallback", () => {
+  test("strips only the first leading Slack user mention", () => {
+    expect(stripLeadingSlackMentionFallback(" <@U111> <@U222> hi")).toBe(
+      "<@U222> hi"
+    );
+  });
+});
+
+describe("renderSlackTextForModel", () => {
+  test("renders resolved user mentions", () => {
+    expect(
+      renderSlackTextForModel("hello <@U123>", {
+        userLabels: { U123: "Alice" },
+      })
+    ).toBe("hello @Alice");
+  });
+
+  test("renders multiple mentions and never emits unresolved user IDs", () => {
+    const rendered = renderSlackTextForModel("<@U123> <@W456> <@U789>", {
+      userLabels: { U123: "Alice", W456: "Bob" },
+    });
+
+    expect(rendered).toBe("@Alice @Bob @unknown-user");
+    expect(rendered).not.toContain("U789");
+  });
+
+  test("treats ID-shaped resolved user labels as unresolved", () => {
+    expect(
+      renderSlackTextForModel("hello <@U123>", {
+        userLabels: { U123: "U123" },
+      })
+    ).toBe("hello @unknown-user");
+  });
+
+  test("renders channel references with labels and fallbacks", () => {
+    expect(
+      renderSlackTextForModel("<#C123|general> <#C456>", {
+        channelLabels: { C456: "support" },
+      })
+    ).toBe("#general #support");
+
+    expect(renderSlackTextForModel("<#C789>")).toBe("#unknown-channel");
+  });
+
+  test("renders special broadcasts", () => {
+    expect(renderSlackTextForModel("<!here> <!channel> <!everyone>")).toBe(
+      "@here @channel @everyone"
+    );
+  });
+
+  test("renders usergroups with labels and fallback", () => {
+    expect(renderSlackTextForModel("<!subteam^S123|eng> <!subteam^S456>")).toBe(
+      "@eng @usergroup"
+    );
+  });
+
+  test("renders labeled and unlabeled links", () => {
+    expect(
+      renderSlackTextForModel(
+        "<https://example.com|Example> <https://example.org>"
+      )
+    ).toBe("Example (https://example.com) https://example.org");
+  });
+
+  test("sanitizes malicious and empty labels before adding prefixes", () => {
+    expect(
+      renderSlackTextForModel(
+        "<@U123> <#C123> <#C456|#  > <!subteam^S123|@eng>",
+        {
+          userLabels: { U123: " @<system>  prompt " },
+          channelLabels: { C123: "#<ops>" },
+        }
+      )
+    ).toBe("@system prompt #ops #unknown-channel @eng");
+  });
+
+  test("uses sanitized custom fallbacks", () => {
+    expect(
+      renderSlackTextForModel("<@U123> <#C123>", {
+        userFallbackLabel: "@ missing user ",
+        channelFallbackLabel: "# missing channel ",
+      })
+    ).toBe("@missing user #missing channel");
+  });
+});
+
+describe("buildSlackUserLabelMap", () => {
+  test("dedupes mentioned users across text inputs and ignores configured IDs", async () => {
+    const resolved: string[] = [];
+    const labels = await buildSlackUserLabelMap(
+      ["<@U123> hi <@U999>", undefined, "<@U123> and <@W456>"],
+      async (userId) => {
+        resolved.push(userId);
+        return userId === "W456" ? "Bob" : "Alice";
+      },
+      { ignoredUserIds: ["U999"] }
+    );
+
+    expect(resolved).toEqual(["U123", "W456"]);
+    expect(labels).toEqual({ U123: "Alice", W456: "Bob" });
+  });
+
+  test("omits unresolved labels and labels equal to the Slack user ID", async () => {
+    const labels = await buildSlackUserLabelMap(
+      ["<@U123> <@U456> <@U789>"],
+      async (userId) => {
+        if (userId === "U123") return "U123";
+        if (userId === "U456") return "";
+        return "Alice";
+      }
+    );
+
+    expect(labels).toEqual({ U789: "Alice" });
+  });
+});