@builder.io/ai-utils 0.55.0 → 0.56.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@builder.io/ai-utils",
-  "version": "0.55.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,6 +35,18 @@ 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<{
@@ -98,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;
 }
@@ -159,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;
@@ -172,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;
@@ -1006,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;
     /**
@@ -1967,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 {

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;