@builder.io/ai-utils 0.54.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.54.0",
+  "version": "0.56.0",
   "description": "Builder.io AI utils",
   "files": [
     "src"

package/src/claw.d.ts

@@ -70,19 +70,14 @@ export declare function parseChannelId(channelId: string): ParsedChannelId;
  *     slack/dm/TEAM_ID/USER_ID
  *       → https://slack.com/app_redirect?team=TEAM_ID&channel=USER_ID
  *
- *   Jira:
- *     Returns null - needs integration.baseUrl from database
- *     (Future: jira/comment/CLOUD_ID/ISSUE_KEY → {baseUrl}/browse/ISSUE_KEY)
- *
  * Returns null for unsupported platforms or malformed channel IDs.
- *
- * TODO: Accept optional integration metadata parameter to construct proper
- * workspace-specific URLs (Slack teamDomain, Jira baseUrl).
  */
 export declare function convertChannelIdToUrl(channelId: string): string | null;
 export interface WorkerReportOptions {
     /** The original user's channel that triggered this work. */
     originChannelId?: string;
+    /** Clickable URL for the origin channel, if the integration already has one. */
+    channelUrl?: string;
     /** The report content. */
     content: string;
     /** Agent/tool ID (for sub-agent reports). */
@@ -91,6 +86,8 @@ export interface WorkerReportOptions {
 export interface WorkerMessageOptions {
     /** The original user's channel that triggered this work. */
     originChannelId?: string;
+    /** Clickable URL for the origin channel, if the integration already has one. */
+    channelUrl?: string;
     /** The report content. */
     content: string;
     /** Project ID (for branch reports). */
@@ -129,6 +126,8 @@ export declare function formatSystemMessage(opts: SystemMessageOptions): string;
 export interface IncomingMessageOptions {
     /** The source channel (e.g. slack/thread/TEAM/CHANNEL/TS). */
     channelId: string;
+    /** Clickable URL for channelId, if the integration already has one. */
+    channelUrl?: string;
     /** DM channel ID, if the message was a direct message. */
     dmId?: string;
     /** Display name of the sender. */

package/src/claw.js

@@ -30,14 +30,7 @@ export function parseChannelId(channelId) {
  *     slack/dm/TEAM_ID/USER_ID
  *       → https://slack.com/app_redirect?team=TEAM_ID&channel=USER_ID
  *
- *   Jira:
- *     Returns null - needs integration.baseUrl from database
- *     (Future: jira/comment/CLOUD_ID/ISSUE_KEY → {baseUrl}/browse/ISSUE_KEY)
- *
  * Returns null for unsupported platforms or malformed channel IDs.
- *
- * TODO: Accept optional integration metadata parameter to construct proper
- * workspace-specific URLs (Slack teamDomain, Jira baseUrl).
  */
 export function convertChannelIdToUrl(channelId) {
     let parsed;
@@ -51,11 +44,6 @@ export function convertChannelIdToUrl(channelId) {
     if (platform === "slack") {
         return slackChannelIdToUrl(type, ids);
     }
-    // Jira URLs need integration.baseUrl from database - not available here
-    // TODO: Add integration metadata parameter to support Jira URLs
-    if (platform === "jira") {
-        return null;
-    }
     return null;
 }
 function slackChannelIdToUrl(type, ids) {
@@ -105,10 +93,11 @@ const WORKER_REPORT_TRAILER = "This is a report from a background worker, NOT a
  * correct user channel.
  */
 export function formatWorkerReport(opts) {
+    var _a;
     let xml = `<worker_report>\n`;
     if (opts.originChannelId) {
         xml += `<origin_channel_id>${opts.originChannelId}</origin_channel_id>\n`;
-        const url = convertChannelIdToUrl(opts.originChannelId);
+        const url = (_a = opts.channelUrl) !== null && _a !== void 0 ? _a : convertChannelIdToUrl(opts.originChannelId);
         if (url) {
             xml += `<origin_channel_url>${url}</origin_channel_url>\n`;
         }
@@ -120,10 +109,11 @@ export function formatWorkerReport(opts) {
     return xml;
 }
 export function formatWorkerMessage(opts) {
+    var _a;
     let xml = `<worker_message>\n`;
     if (opts.originChannelId) {
         xml += `<origin_channel_id>${opts.originChannelId}</origin_channel_id>\n`;
-        const url = convertChannelIdToUrl(opts.originChannelId);
+        const url = (_a = opts.channelUrl) !== null && _a !== void 0 ? _a : convertChannelIdToUrl(opts.originChannelId);
         if (url) {
             xml += `<origin_channel_url>${url}</origin_channel_url>\n`;
         }
@@ -165,13 +155,14 @@ export function formatSystemMessage(opts) {
  * The org-agent uses `<channel_id>` to reply in the same medium.
  */
 export function formatIncomingMessage(opts) {
+    var _a;
     let result = "";
     if (opts.messageContext) {
         result += `${opts.messageContext}\n\n`;
     }
     result += `<incoming_message>\n`;
     result += `<channel_id>${opts.channelId}</channel_id>\n`;
-    const channelUrl = convertChannelIdToUrl(opts.channelId);
+    const channelUrl = (_a = opts.channelUrl) !== null && _a !== void 0 ? _a : convertChannelIdToUrl(opts.channelId);
     if (channelUrl) {
         result += `<channel_url>${channelUrl}</channel_url>\n`;
     }

package/src/claw.spec.js

@@ -45,10 +45,13 @@ describe("convertChannelIdToUrl", () => {
         });
     });
     describe("jira/comment format", () => {
-        it("returns null (needs integration.baseUrl from database)", () => {
+        it("returns null because Jira URLs are provided by the integration", () => {
             const url = convertChannelIdToUrl("jira/comment/cloud-id/PROJ-123");
             expect(url).toBeNull();
         });
+        it("returns null even when the issue key is present", () => {
+            expect(convertChannelIdToUrl("jira/comment/cloud-id/PROJ-123")).toBeNull();
+        });
     });
     describe("unsupported platforms", () => {
         it("returns null for telegram channel IDs", () => {
@@ -90,14 +93,15 @@ describe("formatIncomingMessage", () => {
         });
         expect(result).toContain("<channel_url>https://slack.com/app_redirect?team=TTEAM&channel=CCHAN</channel_url>");
     });
-    it("does not include channel_url for Jira (needs integration.baseUrl)", () => {
+    it("includes channel_url when provided by the integration", () => {
         const result = formatIncomingMessage({
             channelId: "jira/comment/cloud-id/PROJ-123",
+            channelUrl: "https://test.atlassian.net/browse/PROJ-123",
             sender: "Charlie",
             timestamp: "Wednesday, January 3, 2024 at 12:00 PM PST",
             content: "Jira comment",
         });
-        expect(result).not.toContain("<channel_url>");
+        expect(result).toContain("<channel_url>https://test.atlassian.net/browse/PROJ-123</channel_url>");
     });
     it("does not include channel_url for unsupported platforms", () => {
         const result = formatIncomingMessage({
@@ -142,12 +146,13 @@ describe("formatWorkerMessage", () => {
         });
         expect(result).toContain("<origin_channel_url>https://slack.com/app_redirect?team=TTEAM&channel=CCHAN&message_ts=1234567890.000100</origin_channel_url>");
     });
-    it("does not include origin_channel_url for Jira (needs integration.baseUrl)", () => {
+    it("includes origin_channel_url when provided by the integration", () => {
         const result = formatWorkerMessage({
             originChannelId: "jira/comment/cloud-id/PROJ-456",
+            channelUrl: "https://test.atlassian.net/browse/PROJ-456",
             content: "Worker result",
         });
-        expect(result).not.toContain("<origin_channel_url>");
+        expect(result).toContain("<origin_channel_url>https://test.atlassian.net/browse/PROJ-456</origin_channel_url>");
     });
     it("does not include origin_channel_url for unsupported platforms", () => {
         const result = formatWorkerMessage({
@@ -181,13 +186,14 @@ describe("formatWorkerReport", () => {
         });
         expect(result).toContain("<origin_channel_url>https://slack.com/app_redirect?team=TTEAM&channel=CCHAN</origin_channel_url>");
     });
-    it("does not include origin_channel_url for Jira (needs integration.baseUrl)", () => {
+    it("includes origin_channel_url when provided by the integration", () => {
         const result = formatWorkerReport({
             originChannelId: "jira/comment/cloud-id/PROJ-789",
+            channelUrl: "https://test.atlassian.net/browse/PROJ-789",
             content: "Report content",
             agentId: "agent-xyz",
         });
-        expect(result).not.toContain("<origin_channel_url>");
+        expect(result).toContain("<origin_channel_url>https://test.atlassian.net/browse/PROJ-789</origin_channel_url>");
     });
     it("does not include origin_channel_url for unsupported platforms", () => {
         const result = formatWorkerReport({

package/src/codegen.d.ts

@@ -35,13 +35,29 @@ export interface CustomInstruction {
     isSkill?: boolean;
     disableModelInvocation?: boolean;
     userInvocable?: boolean;
+    /**
+     * Where this instruction was discovered. Drives precedence on name
+     * collision: `project` > `user` > `plugin`. Set by the discovery loader,
+     * not by the parsed file itself.
+     */
+    scope?: "project" | "user" | "plugin";
+    /**
+     * Name of the plugin that contributed this instruction, if any. Set by
+     * the plugin loader (Phase 2); always `undefined` for project-level and
+     * user-level standalone files (Phase 1).
+     */
+    pluginName?: string;
 }
 /** Reasoning effort level for LLM completions. */
 export declare const ReasoningEffortSchema: z.ZodEnum<{
+    none: "none";
     low: "low";
     medium: "medium";
     high: "high";
+    auto: "auto";
     minimal: "minimal";
+    xhigh: "xhigh";
+    max: "max";
 }>;
 export type ReasoningEffort = z.infer<typeof ReasoningEffortSchema>;
 export interface CustomAgentInfo {
@@ -64,7 +80,6 @@ export interface CustomAgentDefinition {
     tools?: string[];
     model?: string;
     roundRobinModels?: string[];
-    mode?: CodeGenMode;
     position?: CodeGenPosition;
     needDevServer?: boolean;
     needValidation?: boolean;
@@ -72,6 +87,17 @@ export interface CustomAgentDefinition {
     resetAfterRun?: boolean;
     mcpServers?: boolean;
     asyncSubAgents?: boolean;
+    /**
+     * Expressive queue behavior for messages sent to this agent. See
+     * {@link QueueBehavior}. When both `queueBehavior` and `queueMode` are
+     * provided, `queueBehavior` wins.
+     */
+    queueBehavior?: QueueBehavior;
+    /**
+     * @deprecated Use {@link CustomAgentDefinition.queueBehavior} instead.
+     * Kept as a string alias for backwards compatibility with existing agent
+     * definitions in the wild.
+     */
     queueMode?: QueueMode;
     softContextWindow?: number;
     filePath?: string;
@@ -84,13 +110,31 @@ export interface CustomAgentDefinition {
     maxCompletions?: number;
     /** Default reasoning effort level for this agent type. Overrides the session default. */
     reasoning?: ReasoningEffort;
+    /**
+     * Where this agent was discovered. Drives precedence on name collision:
+     * `project` > `user` > `plugin`. Set by the discovery loader, not by the
+     * parsed file itself.
+     */
+    scope?: "project" | "user" | "plugin";
+    /**
+     * Name of the plugin that contributed this agent, if any. Set by the
+     * plugin loader (Phase 2); always `undefined` for project-level and
+     * user-level standalone files (Phase 1).
+     */
+    pluginName?: string;
 }
 export type CodeGenFramework = "react" | "html" | "mitosis" | "react-native" | "angular" | "vue" | "svelte" | "qwik" | "solid" | "marko" | "swiftui" | "jetpack-compose" | "flutter";
 export type CodeGenStyleLibrary = "tailwind" | "tailwind-precise" | "emotion" | "styled-components" | "styled-jsx" | "react-native" | undefined;
 export type CompletionStopReason = "max_tokens" | "stop_sequence" | "tool_use" | "end_turn" | "content_filter" | "error" | "aborted" | "pause_turn" | "refusal" | "compaction" | "model_context_window_exceeded" | null;
 export interface ReadToolInput {
+    /**
+     * Path of the file. Accepts a path relative to the project working directory,
+     * an absolute path (e.g. `/Users/.../skill.md`), or a tilde path
+     * (e.g. `~/.builder/skills/.../SKILL.md`). User-level Builder state under
+     * `~/.builder/**` is allowed by default for plugin operations; other absolute
+     * paths require an explicit ACL policy.
+     */
     file_path: string;
-    view_range?: [number, number];
     offset?: number | null;
     limit?: number | null;
 }
@@ -145,11 +189,23 @@ export interface WebSearchToolInput {
 }
 export interface WriteFileInput {
     title: string;
+    /**
+     * Path of the file. Accepts a path relative to the project working directory,
+     * an absolute path, or a tilde path (e.g. `~/.builder/...`). User-level Builder
+     * state under `~/.builder/**` is allowed by default; other absolute paths
+     * require an explicit ACL policy.
+     */
     file_path: string;
     content: string;
 }
 export interface SearchReplaceInput {
     title: string;
+    /**
+     * Path of the file. Accepts a path relative to the project working directory,
+     * an absolute path, or a tilde path (e.g. `~/.builder/...`). User-level Builder
+     * state under `~/.builder/**` is allowed by default; other absolute paths
+     * require an explicit ACL policy.
+     */
     file_path: string;
     old_str: string;
     new_str: string;
@@ -158,6 +214,12 @@ export interface SearchReplaceInput {
 }
 export interface MultiSearchReplaceInput {
     title: string;
+    /**
+     * Path of the file. Accepts a path relative to the project working directory,
+     * an absolute path, or a tilde path (e.g. `~/.builder/...`). User-level Builder
+     * state under `~/.builder/**` is allowed by default; other absolute paths
+     * require an explicit ACL policy.
+     */
     file_path: string;
     edits: {
         old_str: string;
@@ -737,19 +799,6 @@ export interface ReportIssueToolInput {
     body: string;
 }
 export interface CodeGenToolMap {
-    view_path: ReadToolInput;
-    glob_search: GlobSearchToolInput;
-    grep_search: GrepSearchToolInput;
-    get_rule: GetRuleToolInput;
-    get_style_inspiration: GetStyleInspirationToolInput;
-    get_screenshot: GetScreenshotToolInput;
-    dev_server_control: DevServerControlInput;
-    bash: BashToolInput;
-    powershell: PowerShellToolInput;
-    web_search: WebSearchToolInput;
-    write_file: WriteFileInput;
-    search_replace_file: SearchReplaceInput;
-    find_media: FindMediaToolInput;
     Read: ReadToolInput;
     Write: WriteFileInput;
     Edit: SearchReplaceInput;
@@ -812,6 +861,7 @@ export interface CodeGenToolMap {
     IDEDiagnostics: IDEDiagnosticsToolInput;
     EscalateToPlanner: EscalateToPlanner;
     PullPrototype: PullPrototypeToolInput;
+    ConnectMCP: ConnectMCPToolInput;
 }
 export interface EscalateToPlanner {
     /** What's blocking execution */
@@ -825,17 +875,80 @@ export interface EscalateToPlanner {
 }
 export interface GetLastBrowserTestToolInput {
 }
+export interface ConnectMCPToolInput {
+    /** Human-readable name of the MCP service, e.g. "Jira", "Linear", "Sentry" */
+    name: string;
+    /** Remote MCP endpoint URL. When omitted, discovery is performed for the named service. */
+    url?: string;
+}
 export type CodeGenTools = keyof CodeGenToolMap;
 export type AllCodeGenTools = CodeGenTools | "web_search";
 export type SessionMode = "planning" | "normal" | "auto-planning" | "deep-research";
-export type CodeGenMode = "quality" | "quality-v3" | "quality-v4"
+export type CodeGenMode = "quality" | "quality-v4"
 /**
  * @deprecated Use `quality-v4` instead. Kept for backwards compatibility
  * with older dev-tools clients in the wild that may still request this mode
  * for sub-agents. New code should not produce this value.
  */
  | "quality-v4-agent";
-export type QueueMode = "next-turn" | "until-idle";
+/**
+ * When a queued message gets picked up by the scheduler.
+ *
+ * - `next-turn`: process queued messages as soon as the current LLM turn
+ *   finishes (i.e. between turns of an in-flight run).
+ * - `until-idle`: hold queued messages until the agent is fully idle
+ *   (current run has ended). Messages never interrupt an in-flight run.
+ * - `interrupt`: abort the in-flight run as soon as a new message arrives
+ *   and start processing it. Reserved for high-priority/reactive cases.
+ * - `interrupt-clear`: like `interrupt`, but also clears the session
+ *   (turn history, queued messages, last user, accumulated credits) before
+ *   processing the new message. Use when the new message should start from
+ *   a clean slate.
+ * - `interrupt-replace`: equivalent to abort + rewind to the previous
+ *   user message + replace it with the new one. Use when a fresh
+ *   request supersedes the in-flight one (e.g. incremental code-review
+ *   requests where a newer review should replace the still-running
+ *   previous review). The in-flight user prompt and any partial
+ *   assistant output for it are discarded.
+ */
+export type QueueSchedule = "next-turn" | "until-idle" | "interrupt" | "interrupt-clear" | "interrupt-replace";
+/**
+ * What happens when multiple messages are pending in the queue.
+ *
+ * - `merge`: combine all pending messages into a single user message before
+ *   the next turn. This is the historical default for `"next-turn"`.
+ * - `replace-latest`: discard older pending messages and keep only the
+ *   most recently queued one (useful when stale inputs are obsolete, e.g.
+ *   a typing user replacing their previous draft).
+ * - `preserve-order`: never merge; pop one message at a time in FIFO order.
+ *   This is the historical behavior for `"until-idle"`.
+ */
+export type QueueCoalesce = "merge" | "replace-latest" | "preserve-order";
+/**
+ * Expressive queue behavior built from two orthogonal axes:
+ * `schedule` (when to dispatch) and `coalesce` (how to combine pending).
+ */
+export interface QueueBehavior {
+    schedule: QueueSchedule;
+    coalesce: QueueCoalesce;
+}
+/**
+ * Backwards-compatible queue mode. Accepts either a legacy string alias
+ * or the full {@link QueueBehavior} object.
+ *
+ * Legacy aliases:
+ * - `"next-turn"` → `{ schedule: "next-turn", coalesce: "merge" }`
+ * - `"until-idle"` → `{ schedule: "until-idle", coalesce: "preserve-order" }`
+ */
+export type QueueMode = "next-turn" | "until-idle" | QueueBehavior;
+export declare const DEFAULT_QUEUE_BEHAVIOR: QueueBehavior;
+/**
+ * Normalize any accepted queue-mode shape into a concrete {@link QueueBehavior}.
+ * `undefined` resolves to {@link DEFAULT_QUEUE_BEHAVIOR}.
+ */
+/** True for any schedule that aborts the in-flight run on enqueue. */
+export declare function isInterruptSchedule(schedule: QueueSchedule): boolean;
+export declare function normalizeQueueMode(mode: QueueMode | undefined): QueueBehavior;
 export declare const BASE_CODEGEN_POSITIONS: readonly ["fusion", "editor-ai", "repo-indexing", "cli", "create-app-firebase", "create-app-lovable", "builder-code-panel", "setup-project", "code-review-orchestrator", "project-configuration", "org-agent", "browser-testing", "projects-scheduler-memory-extraction", "builder-code", "unknown", "dsi-mcp"];
 export type BaseCodeGenPosition = (typeof BASE_CODEGEN_POSITIONS)[number];
 export type CodeGenPosition = BaseCodeGenPosition | `${BaseCodeGenPosition}-agent`;
@@ -941,17 +1054,6 @@ export interface CodeGenInputOptions {
     branchName?: string;
     repoHash?: string;
     repoBranch?: string;
-    /**
-     * Server-side branch.agentType cached from middleware Firestore lookup.
-     * Used to avoid redundant getBranch calls for billing exemption checks.
-     * @internal - Set by middleware, not by clients
-     */
-    branchAgentType?: string | null;
-    /**
-     * True when middleware performed a Firestore branch lookup; do not use source-based exemption.
-     * @internal - Set by middleware, not by clients
-     */
-    branchAgentTypeChecked?: boolean;
     /** Immediate parent session id when this completion runs inside a sub-agent. */
     parentSessionId?: string;
     /**
@@ -1108,7 +1210,7 @@ export interface ContextWindow {
      * the proportion (0-1) of total tokens used by that category.
      *
      * Common keys include:
-     * - `tool:<name>` - Tokens from tool calls and results (e.g., `tool:read_file`, `tool:bash`)
+     * - `tool:<name>` - Tokens from tool calls and results (e.g., `tool:Read`, `tool:Bash`)
      * - `tools:builtin` - Tokens from built-in tool definitions/schemas
      * - `tools:mcp:<server>` - Tokens from MCP server tool definitions (e.g., `tools:mcp:browser`)
      * - `images` - Tokens from image content (estimated at ~1200 tokens per image)
@@ -1902,6 +2004,17 @@ export interface MCPServerDefinition {
     env?: Record<string, string>;
     envFile?: string;
     retries?: number;
+    /**
+     * Where this server was discovered. Drives precedence on name collision:
+     * `project` > `user` > `plugin`. Set by the loader, not by the config file.
+     */
+    scope?: "project" | "user" | "plugin";
+    /**
+     * Name of the plugin that contributed this server, if any. Set by the
+     * plugin loader (Phase 2); always `undefined` for project-level and
+     * user-level standalone configs (Phase 1).
+     */
+    pluginName?: string;
 }
 export type MCPServerConfig = Record<string, MCPServerDefinition>;
 export interface FusionConfig {
@@ -2236,6 +2349,23 @@ export interface SyncChangesFromRemote {
     uncommittedChanges?: "stash" | "commit" | "fail";
     requestRefresh?: boolean;
     allowUnrelatedHistory?: boolean;
+    /**
+     * When true, reset the AI branch hard to the remote feature/base branch instead
+     * of merging. This gives a clean slate that exactly matches the checked-out
+     * feature branch on remote, avoiding any merge-style conflicts or divergence.
+     * Fails clearly if the feature/base branch cannot be determined or is absent
+     * from the remote.
+     */
+    resetToBase?: boolean;
+    /**
+     * Whether to update the internal "last AI commits" baseline after the sync
+     * completes. Defaults to `true` for backwards compatibility.
+     *
+     * Set to `false` when the caller wants `getChangesReport()` to keep diffing
+     * from the pre-sync baseline (e.g. so a downstream prompt can see exactly
+     * what changed since the last reset/sync).
+     */
+    updateLastCommits?: boolean;
 }
 export type PushChangesArgs = PushChangesOptions | boolean;
 export type CodegenApiResult = CodegenApiSuccess | CodegenApiFailure;

package/src/codegen.js

@@ -1,8 +1,31 @@
 import { z } from "zod";
 /** Reasoning effort level for LLM completions. */
 export const ReasoningEffortSchema = z
-    .enum(["low", "medium", "high", "minimal"])
+    .enum(["auto", "none", "minimal", "low", "medium", "high", "xhigh", "max"])
     .meta({ title: "ReasoningEffort" });
+export const DEFAULT_QUEUE_BEHAVIOR = {
+    schedule: "next-turn",
+    coalesce: "merge",
+};
+/**
+ * Normalize any accepted queue-mode shape into a concrete {@link QueueBehavior}.
+ * `undefined` resolves to {@link DEFAULT_QUEUE_BEHAVIOR}.
+ */
+/** True for any schedule that aborts the in-flight run on enqueue. */
+export function isInterruptSchedule(schedule) {
+    return (schedule === "interrupt" ||
+        schedule === "interrupt-clear" ||
+        schedule === "interrupt-replace");
+}
+export function normalizeQueueMode(mode) {
+    if (mode === undefined)
+        return { ...DEFAULT_QUEUE_BEHAVIOR };
+    if (mode === "next-turn")
+        return { schedule: "next-turn", coalesce: "merge" };
+    if (mode === "until-idle")
+        return { schedule: "until-idle", coalesce: "preserve-order" };
+    return { schedule: mode.schedule, coalesce: mode.coalesce };
+}
 export const BASE_CODEGEN_POSITIONS = [
     "fusion",
     "editor-ai",

package/src/codegen.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/src/codegen.spec.js

@@ -0,0 +1,58 @@
+import { describe, it, expect } from "vitest";
+import { DEFAULT_QUEUE_BEHAVIOR, isInterruptSchedule, normalizeQueueMode, } from "./codegen";
+describe("normalizeQueueMode", () => {
+    it("returns the default behavior when input is undefined", () => {
+        expect(normalizeQueueMode(undefined)).toEqual(DEFAULT_QUEUE_BEHAVIOR);
+    });
+    it("maps the legacy 'next-turn' alias to merge between turns", () => {
+        expect(normalizeQueueMode("next-turn")).toEqual({
+            schedule: "next-turn",
+            coalesce: "merge",
+        });
+    });
+    it("maps the legacy 'until-idle' alias to FIFO at idle", () => {
+        expect(normalizeQueueMode("until-idle")).toEqual({
+            schedule: "until-idle",
+            coalesce: "preserve-order",
+        });
+    });
+    it("returns an object input as a normalized copy", () => {
+        const input = {
+            schedule: "interrupt",
+            coalesce: "replace-latest",
+        };
+        const out = normalizeQueueMode(input);
+        expect(out).toEqual(input);
+        expect(out).not.toBe(input);
+    });
+    it("supports next-turn + preserve-order (FIFO between turns)", () => {
+        expect(normalizeQueueMode({ schedule: "next-turn", coalesce: "preserve-order" })).toEqual({ schedule: "next-turn", coalesce: "preserve-order" });
+    });
+    it("supports until-idle + replace-latest (debounce on idle)", () => {
+        expect(normalizeQueueMode({
+            schedule: "until-idle",
+            coalesce: "replace-latest",
+        })).toEqual({ schedule: "until-idle", coalesce: "replace-latest" });
+    });
+    it("supports interrupt-clear and interrupt-replace schedules", () => {
+        expect(normalizeQueueMode({
+            schedule: "interrupt-clear",
+            coalesce: "merge",
+        })).toEqual({ schedule: "interrupt-clear", coalesce: "merge" });
+        expect(normalizeQueueMode({
+            schedule: "interrupt-replace",
+            coalesce: "merge",
+        })).toEqual({ schedule: "interrupt-replace", coalesce: "merge" });
+    });
+});
+describe("isInterruptSchedule", () => {
+    it("returns true for every interrupt-* schedule", () => {
+        expect(isInterruptSchedule("interrupt")).toBe(true);
+        expect(isInterruptSchedule("interrupt-clear")).toBe(true);
+        expect(isInterruptSchedule("interrupt-replace")).toBe(true);
+    });
+    it("returns false for non-interrupt schedules", () => {
+        expect(isInterruptSchedule("next-turn")).toBe(false);
+        expect(isInterruptSchedule("until-idle")).toBe(false);
+    });
+});

package/src/events.d.ts

@@ -623,6 +623,8 @@ export type ClawMessageSentV1 = FusionEventVariant<"claw.message.sent", {
     senderId?: string;
     correlationId?: string;
     channelId?: string;
+    /** Optional clickable URL for channelId. */
+    channelUrl?: string;
     dmId?: string;
     senderDisplayName?: string;
     agentBranchName?: string;
@@ -771,6 +773,8 @@ export interface SendMessageToOrgAgentInput {
     content: string;
     senderType?: "user" | "sub-agent" | "system";
     channelId?: string;
+    /** Optional clickable URL for channelId. */
+    channelUrl?: string;
     senderDisplayName?: string;
     messageContext?: string;
     senderId?: string;

package/src/organization.d.ts

@@ -461,5 +461,11 @@ export interface Organization {
     fusionReferrals?: string;
     githubInstallationIds?: number[];
     disableFigmaImageUpload?: boolean;
+    blocked?: boolean;
+    archived?: boolean;
+    gatewaySuspended?: boolean;
+    gatewaySuspendedAt?: number;
+    gatewaySuspendedBy?: string;
+    gatewaySuspendedReason?: string;
 }
 export {};