@agent-native/core 0.153.9 → 0.154.0

package/dist/client/sse-event-processor.js

@@ -1,7 +1,7 @@
 import { LLM_MISSING_CREDENTIALS_ERROR_CODE, LLM_MISSING_CREDENTIALS_MESSAGE, } from "../agent/engine/credential-errors.js";
 import { emitChatFirstOpenApp } from "./chat-first.js";
 import { formatChatErrorText, normalizeChatError } from "./error-format.js";
-import { humanizeToolLabelText, humanizeToolName, runningToolLabel, } from "./tool-display.js";
+import { humanizeToolLabelText, humanizeToolName, isToolCallActive, runningToolLabel, } from "./tool-display.js";
 /**
  * Kept verbatim in sync with `INTERRUPTED_TOOL_RESULT_MARKER`
  * (agent/production-agent.ts): the server matches this substring in replayed
@@ -13,16 +13,21 @@ const INTERRUPTED_ACTIVITY_RESULT = "Stopped before this action started.";
 /**
  * Maximum number of assistant-ui repository updates we deliver in one browser
  * event-loop turn. Durable-run replay can put hundreds of SSE frames into the
- * stream queue before the client attaches; draining all of them through
- * assistant-ui without a macrotask boundary synchronously nests React external
- * store notifications until React throws "Maximum update depth exceeded."
+ * stream queue before the client attaches; allowing even a small burst through
+ * assistant-ui can synchronously nest React external-store notifications until
+ * React throws "Maximum update depth exceeded."
  *
- * A timer scheduled on the first result resets the count when the stream is
+ * A task scheduled on the first result resets the count when the stream is
  * naturally idle between network chunks. We only await it when results are
  * arriving densely enough to hit this bound, so normal live token streaming
  * keeps its existing latency while replay bursts yield cooperatively.
  */
-const SSE_RENDER_UPDATES_PER_EVENT_LOOP_TURN = 20;
+const SSE_RENDER_UPDATES_PER_EVENT_LOOP_TURN = 1;
+function waitForNextEventLoopTurn() {
+    return new Promise((resolve) => {
+        setTimeout(resolve, 0);
+    });
+}
 export function settleInterruptedToolCalls(content, result = INTERRUPTED_TOOL_RESULT, options) {
     let changed = false;
     for (const part of content) {
@@ -825,6 +830,8 @@ function hasCompletedCustomUi(content) {
     return hasCompletedTool && lastCompletedToolIsCustomUi;
 }
 export function appendMissingFinalResponseWarning(content, completedToolNames) {
+    if (content.some((part) => isToolCallActive(part)))
+        return null;
     const lastTextIndex = lastAssistantTextIndex(content);
     const successfulToolNames = [
         ...new Set(completedToolNames ?? completedToolNamesAfterLastAssistantText(content)),
@@ -1245,6 +1252,7 @@ export function processEvent(ev, content, toolCallCounter, tabId, state) {
                                 : "Done";
                     part.structuredMeta = {
                         ...part.structuredMeta,
+                        ...(ev.status === "pending" ? { agentPending: true } : {}),
                         ...(ev.durationMs != null
                             ? { agentDurationMs: ev.durationMs }
                             : {}),
@@ -1618,15 +1626,19 @@ export async function* readSSEStream(body, content, toolCallCounter, tabId, onSe
     const currentNoProgressTimeoutMs = () => inFlightWork > 0
         ? Math.max(noProgressTimeoutMs, SSE_IN_FLIGHT_WORK_TIMEOUT_MS)
         : noProgressTimeoutMs;
-    const paceRenderUpdate = async () => {
+    const paceRenderUpdate = async (hasBufferedEvent) => {
+        // A single event in a network chunk already has a natural read boundary.
+        // Avoid inserting a task into quiet streams so watchdogs and fake-clock
+        // consumers can continue to observe their own timers normally.
+        if (!hasBufferedEvent) {
+            renderUpdatesThisTurn = 0;
+            return;
+        }
         renderUpdatesThisTurn += 1;
         if (!nextEventLoopTurn) {
-            nextEventLoopTurn = new Promise((resolve) => {
-                setTimeout(() => {
-                    renderUpdatesThisTurn = 0;
-                    nextEventLoopTurn = null;
-                    resolve();
-                }, 0);
+            nextEventLoopTurn = waitForNextEventLoopTurn().then(() => {
+                renderUpdatesThisTurn = 0;
+                nextEventLoopTurn = null;
             });
         }
         if (renderUpdatesThisTurn >= SSE_RENDER_UPDATES_PER_EVENT_LOOP_TURN) {
@@ -1686,12 +1698,19 @@ export async function* readSSEStream(body, content, toolCallCounter, tabId, onSe
             const lines = buf.split("\n");
             buf = lines.pop() ?? "";
             let sawProgressEvent = false;
-            for (const line of lines) {
+            let bufferedDataEvents = lines.reduce((count, pendingLine) => count +
+                (pendingLine.startsWith("data: ") &&
+                    pendingLine.slice(6).trim().length > 0
+                    ? 1
+                    : 0), 0);
+            for (let lineIndex = 0; lineIndex < lines.length; lineIndex += 1) {
+                const line = lines[lineIndex];
                 if (!line.startsWith("data: "))
                     continue;
                 const raw = line.slice(6).trim();
                 if (!raw)
                     continue;
+                bufferedDataEvents -= 1;
                 let ev;
                 try {
                     ev = JSON.parse(raw);
@@ -1751,7 +1770,8 @@ export async function* readSSEStream(body, content, toolCallCounter, tabId, onSe
                     }
                     : result;
                 if (terminalResult) {
-                    await paceRenderUpdate();
+                    const hasBufferedEvent = bufferedDataEvents > 0;
+                    await paceRenderUpdate(hasBufferedEvent);
                     yield withStreamMetadata(terminalResult);
                 }
                 if (hasStalledPreparingAction(preparingActionState, Date.now(), preparationStallTimeoutMs)) {

package/dist/client/tool-display.d.ts

@@ -7,7 +7,16 @@ type ToolDisplayPart = {
     toolName?: string;
     argsText?: string;
     args?: Record<string, unknown>;
+    result?: unknown;
+    outcome?: "unknown";
+    activity?: boolean;
+    structuredMeta?: Record<string, unknown>;
 };
+export declare function isDelegatedAgentToolCall(part: ToolDisplayPart): boolean;
+/** True when a tool has not reported a result and the stream did not mark it unknown. */
+export declare function isToolCallInFlight(part: ToolDisplayPart): boolean;
+/** True when the UI must not present this tool as finished. */
+export declare function isToolCallActive(part: ToolDisplayPart): boolean;
 /**
  * `call-agent` emits both its ordinary tool row and a richer `agent:<name>`
  * progress row. Keep the ordinary part in message state for tool completion

package/dist/client/tool-display.js

@@ -33,6 +33,45 @@ export function humanizeToolLabelText(label, toolName) {
         return text;
     return text.split(tool).join(humanizeToolName(tool));
 }
+const ACTIVE_AGENT_ACTIVITY_PHASES = new Set([
+    "reasoning",
+    "tool",
+    "responding",
+]);
+export function isDelegatedAgentToolCall(part) {
+    return (part.type === "tool-call" && part.toolName?.startsWith("agent:") === true);
+}
+function hasActiveDelegatedAgentActivity(part) {
+    const snapshot = part.structuredMeta?.agentActivity;
+    if (!snapshot || typeof snapshot !== "object")
+        return false;
+    const record = snapshot;
+    if (typeof record.activePhase === "string" &&
+        ACTIVE_AGENT_ACTIVITY_PHASES.has(record.activePhase)) {
+        return true;
+    }
+    return (Array.isArray(record.toolCalls) &&
+        record.toolCalls.some((tool) => tool != null &&
+            typeof tool === "object" &&
+            tool.status === "running"));
+}
+/** True when a tool has not reported a result and the stream did not mark it unknown. */
+export function isToolCallInFlight(part) {
+    if (part.type !== "tool-call")
+        return false;
+    if (part.result !== undefined || part.outcome === "unknown")
+        return false;
+    return part.activity !== true || isDelegatedAgentToolCall(part);
+}
+/** True when the UI must not present this tool as finished. */
+export function isToolCallActive(part) {
+    if (isToolCallInFlight(part))
+        return true;
+    return (isDelegatedAgentToolCall(part) &&
+        part.outcome !== "unknown" &&
+        (part.structuredMeta?.agentPending === true ||
+            hasActiveDelegatedAgentActivity(part)));
+}
 function normalizedAgentName(value) {
     if (typeof value !== "string")
         return null;

package/dist/client/vite-dev-recovery-script.js

@@ -87,7 +87,7 @@ export function getViteDevRecoveryScript() {
       console.warn("[agent-native] Dev server keeps re-bundling. Manual refresh needed.", reason);
       showOverlay(
         "Dev server out of sync",
-        "Auto-reload gave up after " + MAX_RELOADS + " tries. Refresh the page (\\u2318R / Ctrl+R)."
+        "Auto-reload gave up after " + MAX_RELOADS + " tries. Refresh the page (\\u2318R / Ctrl R)."
       );
       return;
     }

package/dist/extensions/html-shell.js

@@ -147,6 +147,11 @@ export function buildExtensionHtml(content, themeVars, isDark, extensionId, bind
   </style>
 	  <style>
 	    *, *::before, *::after { border-color: hsl(var(--border)); }
+	    /* Alpine only honours x-cloak when a stylesheet hides it, and extension
+	       content is a body snippet that cannot supply one. Without this, an
+	       x-cloak overlay paints over the whole extension until Alpine boots —
+	       and forever if it never does. */
+	    [x-cloak] { display: none !important; }
 	    html, body {
 	      /* Transparent so the iframe inherits the host surface (dashboard panel,
 	         sidebar, chat) instead of painting the browser's default white canvas.

package/dist/integrations/catalog.js

@@ -5,6 +5,7 @@
  * Runtime behavior stays in adapters and plugins; consumers must use
  * availability and support maturity before offering a connection flow.
  */
+import { docsUrl } from "../shared/docs-url.js";
 export const INTEGRATION_CATEGORIES = [
     "channel",
     "provider",
@@ -26,7 +27,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Managed installations select encrypted credentials by workspace; legacy manual installs should use SLACK_ALLOWED_TEAM_IDS.",
         ],
         documentation: {
-            href: "/docs/messaging#slack",
+            href: docsUrl("messaging", { hash: "slack" }),
             externalHref: "https://api.slack.com/apps",
             externalLabel: "Open Slack apps",
         },
@@ -88,7 +89,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Production deployments must allowlist Microsoft Entra tenant IDs; proactive messaging without an inbound conversation reference is not implemented.",
         ],
         documentation: {
-            href: "/docs/messaging#microsoft-teams",
+            href: docsUrl("messaging", { hash: "microsoft-teams" }),
             externalHref: "https://dev.botframework.com/",
             externalLabel: "Open Bot Framework",
         },
@@ -148,7 +149,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Interaction tokens are retained only while the queued task is active and normally expire after 15 minutes.",
         ],
         documentation: {
-            href: "/docs/messaging#discord",
+            href: docsUrl("messaging", { hash: "discord" }),
             externalHref: "https://discord.com/developers/applications",
             externalLabel: "Open Discord applications",
         },
@@ -197,7 +198,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Webhook verification requires TELEGRAM_WEBHOOK_SECRET for production-safe setup.",
         ],
         documentation: {
-            href: "/docs/messaging#telegram",
+            href: docsUrl("messaging", { hash: "telegram" }),
             externalHref: "https://t.me/BotFather",
             externalLabel: "Open BotFather",
         },
@@ -246,7 +247,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Meta pricing and the customer-service conversation window can limit replies; template-message flows are not implemented by this adapter.",
         ],
         documentation: {
-            href: "/docs/messaging#whatsapp",
+            href: docsUrl("messaging", { hash: "whatsapp" }),
             externalHref: "https://developers.facebook.com/apps",
             externalLabel: "Open Meta developer console",
         },
@@ -303,7 +304,7 @@ const BUILT_IN_CHANNEL_CATALOG = [
             "Email replies preserve RFC email threads and reply-all when the agent was CC'd.",
         ],
         documentation: {
-            href: "/docs/messaging#email",
+            href: docsUrl("messaging", { hash: "email" }),
             externalHref: "https://resend.com/webhooks",
             externalLabel: "Open Resend webhooks",
         },
@@ -363,7 +364,7 @@ const AUTOMATION_CATALOG = [
             "Use a configured webhook URL or n8n credential; never put an n8n URL or credential in an agent prompt.",
         ],
         documentation: {
-            href: "/docs/automation-connectors#n8n",
+            href: docsUrl("automation-connectors", { hash: "n8n" }),
             externalHref: "https://docs.n8n.io/integrations/builtin/core-nodes/n8n-nodes-base.webhook/",
             externalLabel: "Open n8n Webhook docs",
         },
@@ -405,7 +406,7 @@ const AUTOMATION_CATALOG = [
             "Zapier MCP is a separately configured remote MCP connection with its own account and authorization flow.",
         ],
         documentation: {
-            href: "/docs/automation-connectors#zapier",
+            href: docsUrl("automation-connectors", { hash: "zapier" }),
             externalHref: "https://docs.zapier.com/mcp/home",
             externalLabel: "Open Zapier MCP docs",
         },

package/dist/observability/routes.d.ts

@@ -41,14 +41,14 @@ export declare function createObservabilityHandler(): import("h3").EventHandlerW
     thumbsUpRate: number;
     avgEvalScore: number;
 } | {
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
     summary: import("./types.js").TraceSummary;
     spans: import("./types.js").TraceSpan[];
     id?: undefined;
 } | {
-    error?: undefined;
     ok?: undefined;
+    error?: undefined;
     summary?: undefined;
     spans?: undefined;
     id: string;

package/dist/secrets/routes.d.ts

@@ -37,17 +37,17 @@ export declare function createWriteSecretHandler(): import("h3").EventHandlerWit
     ok?: undefined;
     status?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     status: string;
+    error?: undefined;
 } | {
     ok?: undefined;
     error: string;
     removed?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;
 /**
  * POST /_agent-native/secrets/:key/test — validate an optional candidate value
@@ -58,13 +58,13 @@ export declare function createTestSecretHandler(): import("h3").EventHandlerWith
     error: string;
     note?: undefined;
 } | {
-    error?: undefined;
     ok: boolean;
     note?: undefined;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     note: string;
+    error?: undefined;
 } | {
     note?: undefined;
     ok: boolean;
@@ -95,11 +95,11 @@ export interface AdHocSecretPayload {
 export declare function createAdHocSecretHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<AdHocSecretPayload[] | {
     error: string;
 } | {
-    error?: undefined;
     ok: boolean;
     key: string;
-} | {
     error?: undefined;
+} | {
     ok: boolean;
     removed: boolean;
+    error?: undefined;
 }>>;

package/dist/server/agent-chat/prompt-resources.js

@@ -416,21 +416,22 @@ export function resourceScopeForOwner(owner, currentOwner) {
     return "resource";
 }
 async function loadAgentsResourceForPrompt(owner, scope, maxChars = SHARED_PROMPT_RESOURCE_MAX_CHARS) {
+    let agents;
     try {
-        const agents = await resourceGetByPath(owner, "AGENTS.md");
-        if (!agents?.content?.trim())
-            return null;
-        return promptResourceBlock({
-            name: "AGENTS.md",
-            scope,
-            path: "AGENTS.md",
-            content: agents.content,
-            maxChars,
-        });
+        agents = await resourceGetByPath(owner, "AGENTS.md");
     }
-    catch {
-        return null;
+    catch (error) {
+        throw new Error(`Unable to read durable AGENTS.md instructions for ${scope} (${owner}). The run cannot safely continue without them.`, { cause: error });
     }
+    if (!agents?.content?.trim())
+        return null;
+    return promptResourceBlock({
+        name: "AGENTS.md",
+        scope,
+        path: "AGENTS.md",
+        content: agents.content,
+        maxChars,
+    });
 }
 async function loadInstructionResourcesForPrompt(owner, scope, maxChars = SHARED_PROMPT_RESOURCE_MAX_CHARS, summaryOnly = false) {
     try {
@@ -671,14 +672,14 @@ export async function loadResourcesForPrompt(owner, compact = false, selfAppId,
     // every app in the workspace, not copied into app scopes. They may come from
     // SQL, Dispatch, or local file mode.
     const workspaceAgents = await loadAgentsResourceForPrompt(WORKSPACE_OWNER, "workspace", promptResourceMaxChars);
-    addSection(workspaceAgents);
+    addSection(workspaceAgents, "required");
     addSections(await loadInstructionResourcesForPrompt(WORKSPACE_OWNER, "workspace-instruction", promptResourceMaxChars, compact));
     const organizationOwner = sharedResourceOwner(orgId);
     // 4. Legacy app-wide defaults. Existing deployments keep their seeded
     // shared guidance as an inherited fallback; organization writes never
     // mutate this owner.
     const appDefaultAgents = await loadAgentsResourceForPrompt(SHARED_OWNER, organizationOwner === SHARED_OWNER ? "shared" : "app-default", promptResourceMaxChars);
-    addSection(appDefaultAgents);
+    addSection(appDefaultAgents, "required");
     addSections(await loadInstructionResourcesForPrompt(SHARED_OWNER, organizationOwner === SHARED_OWNER
         ? "shared-instruction"
         : "app-default-instruction", promptResourceMaxChars, compact));
@@ -686,14 +687,14 @@ export async function loadResourcesForPrompt(owner, compact = false, selfAppId,
     // learnings that Slack/integration runs share with interactive app chat.
     if (organizationOwner !== SHARED_OWNER) {
         const organizationAgents = await loadAgentsResourceForPrompt(organizationOwner, "organization", promptResourceMaxChars);
-        addSection(organizationAgents);
+        addSection(organizationAgents, "required");
         addSections(await loadInstructionResourcesForPrompt(organizationOwner, "organization-instruction", promptResourceMaxChars, compact));
     }
     // 6. Personal SQL resources. These come last in the instruction stack so a
     // user can narrow or override organization/app and workspace defaults.
     if (owner !== SHARED_OWNER && owner !== WORKSPACE_OWNER) {
         const personalAgents = await loadAgentsResourceForPrompt(owner, "personal", promptResourceMaxChars);
-        addSection(personalAgents, "user");
+        addSection(personalAgents, "required");
         addSections(await loadInstructionResourcesForPrompt(owner, "personal-instruction", promptResourceMaxChars, compact), "user");
     }
     const resourceSkillsBlock = await loadResourceSkillsPromptBlock(owner, orgId);

package/dist/server/agent-chat-plugin.d.ts

@@ -16,6 +16,15 @@ export { loadResourcesForPrompt };
 export { _agentChatPromptSectionsForTests };
 export { buildPublicAgentA2ASkills };
 export { assembleA2AFinalResponse };
+export declare function buildLeanSystemPrompt(input: {
+    basePrompt: string;
+    resources: string;
+    additionalFramework?: string;
+    cacheSplit?: string;
+    extra?: string;
+    modelOverlay?: string;
+    runtimeContext?: string;
+}): string;
 export type { AgentChatPluginOptions };
 export { runA2AAgentLoop };
 export { runMCPAgentLoop };

package/dist/server/agent-chat-plugin.js

@@ -34,6 +34,7 @@ import { getSkillNameFromPath } from "../resources/metadata.js";
 import { resourceList, resourceListAccessible, resourceGet, ensurePersonalDefaults, SHARED_OWNER, WORKSPACE_OWNER, } from "../resources/store.js";
 import { normalizeDatabaseToolsMode } from "../scripts/db/tool-mode.js";
 import { getSetting, putSetting } from "../settings/store.js";
+import { docsUrl } from "../shared/docs-url.js";
 import { handleSharedThreadRequest, } from "./agent-chat/shared-thread.js";
 import { discoverAgents } from "./agent-discovery.js";
 import { resolveAgentRunOwnerContext, runWithAgentRunContext, seedBackgroundAgentRunOwnerContext, } from "./agent-run-context.js";
@@ -124,6 +125,15 @@ export { loadResourcesForPrompt };
 export { _agentChatPromptSectionsForTests };
 export { buildPublicAgentA2ASkills };
 export { assembleA2AFinalResponse };
+export function buildLeanSystemPrompt(input) {
+    return (input.basePrompt +
+        (input.additionalFramework ?? "") +
+        (input.cacheSplit ?? "") +
+        input.resources +
+        (input.extra ?? "") +
+        (input.modelOverlay ?? "") +
+        (input.runtimeContext ?? ""));
+}
 export { runA2AAgentLoop };
 export { runMCPAgentLoop };
 export { createA2AEngineToolSurface };
@@ -2600,20 +2610,25 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                     // so everything after it can change without a cache write.
                     if (leanPrompt) {
                         const leanRunPolicyPrompt = buildLeanRunPolicyPrompt(codeEditingSurfaceRestriction, prodCodeExecPromptNote);
+                        const resources = await loadResourcesForPrompt(owner, true, options?.appId, undefined, { disabledFrameworkGroups });
                         await emitContextXraySystemSections(event, {
                             frameworkPrompt: leanBasePrompt.slice(0, Math.max(0, leanBasePrompt.length - leanActionsPrompt.length)),
                             actionsPrompt: leanActionsPrompt,
                             additionalFramework: leanRunPolicyPrompt,
+                            resources,
                             extra,
                             modelOverlay,
                             runtimeContext,
                         });
-                        return setSystemPromptOnContext(leanBasePrompt +
-                            leanRunPolicyPrompt +
-                            SYSTEM_PROMPT_CACHE_SPLIT +
-                            extra +
-                            modelOverlay +
-                            runtimeContext);
+                        return setSystemPromptOnContext(buildLeanSystemPrompt({
+                            basePrompt: leanBasePrompt,
+                            additionalFramework: leanRunPolicyPrompt,
+                            cacheSplit: SYSTEM_PROMPT_CACHE_SPLIT,
+                            resources,
+                            extra,
+                            modelOverlay,
+                            runtimeContext,
+                        }));
                     }
                     const resources = await loadResourcesForPrompt(owner, lazyContext, options?.appId, undefined, { disabledFrameworkGroups });
                     // In lazy context mode, skip embedding the full schema. When database
@@ -2839,14 +2854,22 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                         // cached prompt prefix as possible. See the prod handler above
                         // for the same pattern.
                         if (leanPrompt) {
+                            const resources = await loadResourcesForPrompt(owner, true, options?.appId, undefined, { disabledFrameworkGroups });
                             await emitContextXraySystemSections(event, {
                                 frameworkPrompt: leanBasePrompt.slice(0, Math.max(0, leanBasePrompt.length - leanActionsPrompt.length)),
                                 actionsPrompt: leanActionsPrompt,
+                                resources,
                                 extra,
                                 modelOverlay,
                                 runtimeContext,
                             });
-                            return setSystemPromptOnContext(leanBasePrompt + extra + modelOverlay + runtimeContext);
+                            return setSystemPromptOnContext(buildLeanSystemPrompt({
+                                basePrompt: leanBasePrompt,
+                                resources,
+                                extra,
+                                modelOverlay,
+                                runtimeContext,
+                            }));
                         }
                         const resources = await loadResourcesForPrompt(owner, lazyContext, options?.appId, undefined, { disabledFrameworkGroups });
                         const schemaBlock = lazyContext || !databaseToolsEnabled
@@ -3510,8 +3533,7 @@ Non-code requests are still fine on this surface: read data, navigate the UI, su
                 }
                 const result = { skills };
                 if (skills.length === 0) {
-                    result.hint =
-                        "No skills found. Add skill files under skills/ in Resources. Learn more: https://agent-native.com/docs/resources#skills";
+                    result.hint = `No skills found. Add skill files under skills/ in Resources. Learn more: ${docsUrl("agent-resources", { hash: "skills" })}`;
                 }
                 return result;
             }));

package/dist/server/builder-design-systems.d.ts

@@ -39,6 +39,8 @@ export interface BuilderDesignSystemProxyFieldsOptions {
     description?: string;
     surface: "design" | "slides";
     sourceKind?: BuilderDesignSystemSourceKind;
+    githubSources?: BuilderDesignSystemGitHubSource[];
+    syncedAt?: string;
 }
 export type BuilderDesignSystemSourceKind = "figma" | "code" | "github" | "mixed";
 export interface BuilderDesignSystemProxyFields {
@@ -55,6 +57,8 @@ export interface BuilderDesignSystemProxyReference {
     builderProjectId?: string;
     builderUrl?: string;
     builderStatus?: string;
+    githubSources?: BuilderDesignSystemGitHubSource[];
+    syncedAt?: string;
 }
 export interface BuilderDesignSystemDocsOptions {
     page?: number;
@@ -82,11 +86,20 @@ export interface BuilderDesignSystemIndexOptions {
     projectName?: string;
     description?: string;
     githubRepoUrl?: string;
+    githubRepos?: BuilderDesignSystemGitHubSource[];
     connectedProjectId?: string;
     files?: BuilderDesignSystemIndexFile[];
     selection?: Record<string, string[]>;
     devToolsVersion?: string;
 }
+/** A durable, replayable GitHub source configuration for a Builder DSI kit. */
+export interface BuilderDesignSystemGitHubSource {
+    repoUrl: string;
+    ref?: string;
+    include?: string[];
+    exclude?: string[];
+    instructions?: string;
+}
 export interface BuilderDesignSystemIndexResult {
     ok: true;
     source: "builder";
@@ -124,6 +137,25 @@ export interface BuilderDesignSystemDecodeJobStatus {
     createdAt: number;
     updatedAt: number;
 }
+export interface BuilderDesignSystemGitHubFile {
+    path: string;
+    content: string;
+}
+export interface BuilderDesignSystemGitHubFileCollection {
+    source: BuilderDesignSystemGitHubSource;
+    owner: string;
+    repo: string;
+    ref?: string;
+    files: BuilderDesignSystemGitHubFile[];
+    totalBytes: number;
+    truncated: boolean;
+}
+/**
+ * Resolve an explicitly scoped/ref'd GitHub source into bounded file uploads.
+ * Native Builder public-repo sources are preferred for unscoped public repos;
+ * this path exists so branch, folder, and private-repo imports are replayable.
+ */
+export declare function collectBuilderDesignSystemGitHubFiles(input: BuilderDesignSystemGitHubSource): Promise<BuilderDesignSystemGitHubFileCollection>;
 export declare function fetchBuilderDesignSystemDecodeJobStatus(jobId: string): Promise<BuilderDesignSystemDecodeJobStatus>;
 export declare function getBuilderDesignSystemsBaseUrl(): string;
 export declare function mimeTypeForBuilderDesignSystemFilename(filename: string, explicit?: string): string;
@@ -131,7 +163,7 @@ export declare function buildBuilderDesignSystemIndexFiles({ codeFiles, designMd
 export declare function builderDesignSystemUrl(designSystemId?: string | null): string;
 export declare function builderProjectBranchUrl(projectId?: string | null, branchName?: string | null): string | undefined;
 export declare function localBuilderDesignSystemId(builderDesignSystemId: string): string;
-export declare function createBuilderDesignSystemProxyFields({ result, projectName, description, surface, sourceKind, }: BuilderDesignSystemProxyFieldsOptions): BuilderDesignSystemProxyFields;
+export declare function createBuilderDesignSystemProxyFields({ result, projectName, description, surface, sourceKind, githubSources, syncedAt, }: BuilderDesignSystemProxyFieldsOptions): BuilderDesignSystemProxyFields;
 export declare function parseBuilderDesignSystemProxyReference(data: unknown): BuilderDesignSystemProxyReference | null;
 export declare function fetchBuilderDesignSystemDocs(designSystemId: string, options?: BuilderDesignSystemDocsOptions): Promise<BuilderDesignSystemDocument[]>;
 export declare function hydrateBuilderDesignSystemReference(reference: BuilderDesignSystemProxyReference, options?: BuilderDesignSystemDocsOptions): Promise<BuilderDesignSystemHydratedReference>;