@nimbalyst/extension-sdk 0.2.0 → 0.2.2

package/dist/manifestValidation.d.ts

@@ -0,0 +1,118 @@
+/**
+ * Pure (no Node/Electron deps) validation helpers for manifest fields.
+ *
+ * Runs at both build time (via validate.ts, which reads manifest.json from
+ * disk) and runtime (when the host loads an extension and needs to refuse
+ * invalid contributions). Keep this file dependency-free so it can be bundled
+ * into either context without dragging in fs/path.
+ */
+import type { ExtensionPermissionId } from './types/permissions.js';
+/**
+ * Manifest validation rejects extensions declaring more than this many AI
+ * agent providers. Chosen by symmetry with
+ * {@link MAX_BACKEND_MODULES_PER_EXTENSION}: an extension that ships more than
+ * a handful of agent providers is almost certainly mis-modeled (split it into
+ * multiple extensions, or surface them as models on one provider). The cap
+ * also keeps the settings UI -- which lists each provider as its own row --
+ * from running away.
+ */
+export declare const MAX_AGENT_PROVIDERS_PER_EXTENSION = 4;
+export interface BackendModuleValidationIssue {
+    /** The module being validated, or undefined for whole-extension issues */
+    moduleId?: string;
+    message: string;
+    /**
+     * Non-fatal issues (e.g., a deprecated permission id that the validator
+     * silently drops) carry `severity: "warning"`. Callers that fail builds
+     * on issues should ignore warnings.
+     */
+    severity?: 'error' | 'warning';
+}
+/**
+ * Validate the `contributions.backendModules` array on a manifest.
+ * Returns the list of problems found - empty means valid.
+ *
+ * Callers decide whether to treat issues as fatal (host loader: refuse the
+ * extension) or as warnings (build-time validator: print and continue with
+ * non-zero exit).
+ */
+export declare function validateBackendModules(backendModules: unknown): BackendModuleValidationIssue[];
+/**
+ * Convenience wrapper that throws if any fatal issues are found. Warnings
+ * (currently: deprecated permission ids) are surfaced via the issues array
+ * but never throw, so an extension that still references `spawn-process`
+ * keeps loading -- the host just drops the id when computing effective
+ * permissions.
+ *
+ * Use this in main-process load paths where invalid manifests should refuse
+ * the extension outright.
+ */
+export declare function assertBackendModulesValid(extensionId: string, backendModules: unknown): void;
+/**
+ * Filter a raw `permissions` array on a backend-module contribution down to
+ * the ids the host actually understands. Deprecated catalog ids
+ * (`spawn-process`, `network-loopback`, `network-internet`, `filesystem`)
+ * are dropped silently -- they never gated anything inside the backend
+ * runtime, so the host treats them as no-ops. Unknown ids are also dropped;
+ * `validateBackendModules` raises a separate error for those, so the loader
+ * will refuse the module before this is consulted in earnest.
+ */
+export declare function effectiveModulePermissions(raw: unknown): ExtensionPermissionId[];
+/**
+ * Issue surface used by {@link validateAgentProviders}. Shaped to mirror
+ * {@link BackendModuleValidationIssue} so callers can pool the two streams
+ * (build-time validator, runtime loader) through one error pipeline.
+ */
+export interface AgentProviderValidationIssue {
+    /** The provider being validated, or undefined for whole-extension issues */
+    providerId?: string;
+    message: string;
+    /**
+     * Non-fatal issues carry `severity: "warning"`. Callers that fail builds
+     * on issues should ignore warnings.
+     */
+    severity?: 'error' | 'warning';
+}
+/**
+ * Extract the set of declared backend-module ids from a manifest's
+ * `contributions.backendModules` array. Used by
+ * {@link validateAgentProviders} so the `backendModuleId` cross-check does
+ * not need the caller to pre-compute the set.
+ *
+ * Returns an empty set if `backendModules` is missing or malformed. Exported
+ * so build tooling can reuse the same extraction logic when checking entry
+ * files against the declared modules.
+ */
+export declare function extractBackendModuleIds(backendModules: unknown): Set<string>;
+/**
+ * Validate the `contributions.aiAgentProviders` array on a manifest.
+ *
+ * AI agent providers are surfaced in Nimbalyst's chat / agent UI as selectable
+ * providers (alongside built-in Claude Code, Claude, OpenAI, etc.). Each
+ * provider is implemented by a backend module that runs outside the renderer
+ * (so it can drive a CLI, hold long-lived processes, or speak a custom
+ * protocol). The contribution shape, in practice:
+ *
+ *   {
+ *     id: string,                       // unique within the extension
+ *     displayName: string,              // shown in the provider dropdown
+ *     backendModuleId: string,          // must match a declared backendModule
+ *     models?: Array<{ id, name, ... }> // models the provider advertises
+ *     toolFileLinks?: { [toolName]: ... } // optional UI hint table
+ *   }
+ *
+ * This validator checks the manifest-side wiring; it does not introspect the
+ * bundle. See {@link validateExtensionBundle} (Node-only) for the bundle-side
+ * check that the referenced backend module actually exports an
+ * `activate`/`createAgentProvider` function.
+ *
+ * Returns the list of problems found - empty means valid.
+ */
+export declare function validateAgentProviders(aiAgentProviders: unknown, backendModules: unknown): AgentProviderValidationIssue[];
+/**
+ * Convenience wrapper that throws if any fatal aiAgentProviders issues are
+ * found. Mirrors {@link assertBackendModulesValid}. Use this in main-process
+ * load paths where invalid manifests should refuse the extension outright.
+ */
+export declare function assertAgentProvidersValid(extensionId: string, aiAgentProviders: unknown, backendModules: unknown): void;
+//# sourceMappingURL=manifestValidation.d.ts.map

package/dist/manifestValidation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifestValidation.d.ts","sourceRoot":"","sources":["../src/manifestValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAGV,qBAAqB,EACtB,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;GAQG;AACH,eAAO,MAAM,iCAAiC,IAAI,CAAC;AAuCnD,MAAM,WAAW,4BAA4B;IAC3C,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,OAAO,GACtB,4BAA4B,EAAE,CAoKhC;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,cAAc,EAAE,OAAO,GACtB,IAAI,CAYN;AAED;;;;;;;;GAQG;AACH,wBAAgB,0BAA0B,CACxC,GAAG,EAAE,OAAO,GACX,qBAAqB,EAAE,CAazB;AAED;;;;GAIG;AACH,MAAM,WAAW,4BAA4B;IAC3C,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,OAAO,GAAG,GAAG,CAAC,MAAM,CAAC,CAW5E;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,sBAAsB,CACpC,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,OAAO,GACtB,4BAA4B,EAAE,CAgMhC;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,WAAW,EAAE,MAAM,EACnB,gBAAgB,EAAE,OAAO,EACzB,cAAc,EAAE,OAAO,GACtB,IAAI,CAYN"}

package/dist/manifestValidation.js

@@ -0,0 +1,475 @@
+/**
+ * Pure (no Node/Electron deps) validation helpers for manifest fields.
+ *
+ * Runs at both build time (via validate.ts, which reads manifest.json from
+ * disk) and runtime (when the host loads an extension and needs to refuse
+ * invalid contributions). Keep this file dependency-free so it can be bundled
+ * into either context without dragging in fs/path.
+ */
+import { MAX_BACKEND_MODULES_PER_EXTENSION } from './types/extension.js';
+/**
+ * Manifest validation rejects extensions declaring more than this many AI
+ * agent providers. Chosen by symmetry with
+ * {@link MAX_BACKEND_MODULES_PER_EXTENSION}: an extension that ships more than
+ * a handful of agent providers is almost certainly mis-modeled (split it into
+ * multiple extensions, or surface them as models on one provider). The cap
+ * also keeps the settings UI -- which lists each provider as its own row --
+ * from running away.
+ */
+export const MAX_AGENT_PROVIDERS_PER_EXTENSION = 4;
+const AGENT_PROVIDER_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * Mirrors the host's permission registry. We duplicate the list here so
+ * extensions don't have to depend on Electron internals to validate locally.
+ * Adding a new id requires updating both this list AND
+ * `packages/electron/src/main/extensions/permissionRegistry.ts`.
+ */
+const KNOWN_PERMISSION_IDS = [
+    'workspace-files',
+    'nimbalyst-database-read',
+    'nimbalyst-database-write',
+    'secrets-read',
+    'mcp-server-register',
+];
+/**
+ * Permission ids that used to be in the catalog but never enforced anything
+ * meaningful at the backend boundary (ambient Node capabilities). Manifests
+ * that still reference them are accepted -- the validator silently drops the
+ * id from the effective list -- so we don't break older extensions during
+ * the catalog cleanup. Authors get a non-fatal warning issue back.
+ */
+const DEPRECATED_PERMISSION_IDS = [
+    'spawn-process',
+    'network-loopback',
+    'network-internet',
+    'filesystem',
+];
+const KNOWN_RUNTIMES = [
+    'utility-process',
+    'worker-thread',
+];
+const BACKEND_MODULE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+/**
+ * Validate the `contributions.backendModules` array on a manifest.
+ * Returns the list of problems found - empty means valid.
+ *
+ * Callers decide whether to treat issues as fatal (host loader: refuse the
+ * extension) or as warnings (build-time validator: print and continue with
+ * non-zero exit).
+ */
+export function validateBackendModules(backendModules) {
+    if (backendModules === undefined) {
+        return [];
+    }
+    if (!Array.isArray(backendModules)) {
+        return [{ message: 'contributions.backendModules must be an array' }];
+    }
+    const issues = [];
+    if (backendModules.length > MAX_BACKEND_MODULES_PER_EXTENSION) {
+        issues.push({
+            message: `contributions.backendModules declares ${backendModules.length} modules; ` +
+                `the maximum is ${MAX_BACKEND_MODULES_PER_EXTENSION}. ` +
+                'Consolidate modules to keep the consent prompt manageable.',
+        });
+    }
+    const seenIds = new Set();
+    for (let i = 0; i < backendModules.length; i += 1) {
+        const raw = backendModules[i];
+        if (!raw || typeof raw !== 'object') {
+            issues.push({ message: `backendModules[${i}] must be an object` });
+            continue;
+        }
+        const module = raw;
+        const moduleLabel = typeof module.id === 'string' ? module.id : `index ${i}`;
+        if (typeof module.id !== 'string' || !BACKEND_MODULE_ID_PATTERN.test(module.id)) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].id must be a lowercase string matching ` +
+                    `${BACKEND_MODULE_ID_PATTERN.source} (got ${JSON.stringify(module.id)})`,
+            });
+        }
+        else if (seenIds.has(module.id)) {
+            issues.push({
+                moduleId: module.id,
+                message: `backendModules contains duplicate id "${module.id}"`,
+            });
+        }
+        else {
+            seenIds.add(module.id);
+        }
+        if (typeof module.entry !== 'string' || module.entry.length === 0) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].entry must be a non-empty relative path string`,
+            });
+        }
+        else if (module.entry.startsWith('/') || module.entry.includes('..')) {
+            // Refuse absolute paths and parent-directory traversal so a module
+            // can't escape its extension root. The host resolves entry relative
+            // to the extension directory; only safe relative paths belong here.
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].entry must be a relative path within the extension root ` +
+                    `(no leading "/", no ".." segments)`,
+            });
+        }
+        if (!KNOWN_RUNTIMES.includes(module.runtime)) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].runtime must be one of: ${KNOWN_RUNTIMES.join(', ')} ` +
+                    `(got ${JSON.stringify(module.runtime)})`,
+            });
+        }
+        if (module.permissions !== undefined && !Array.isArray(module.permissions)) {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].permissions must be an array of ` +
+                    `host-brokered capability ids (or omitted). The implicit "run native ` +
+                    `code" grant is conferred by enabling the module itself, not by an ` +
+                    `entry in this array.`,
+            });
+        }
+        else if (Array.isArray(module.permissions)) {
+            const uniquePermissions = new Set();
+            for (const permission of module.permissions) {
+                if (typeof permission !== 'string') {
+                    issues.push({
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions contains non-string entry`,
+                    });
+                    continue;
+                }
+                if (DEPRECATED_PERMISSION_IDS.includes(permission)) {
+                    // Older manifests still ship these. They never meaningfully gated
+                    // anything inside the backend runtime (ambient Node access), and
+                    // the catalog cleanup removed them. Warn the author and silently
+                    // drop the id from the effective list.
+                    issues.push({
+                        severity: 'warning',
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions includes deprecated id "${permission}". ` +
+                            `This id is unenforceable inside a Node backend (the module can require child_process/fs/net ` +
+                            `directly) and has been removed from the catalog. Granting the module is itself the consent ` +
+                            `to run native code; drop this id from your manifest.`,
+                    });
+                    continue;
+                }
+                if (!KNOWN_PERMISSION_IDS.includes(permission)) {
+                    issues.push({
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions contains unknown id "${permission}". ` +
+                            `Valid ids: ${KNOWN_PERMISSION_IDS.join(', ')}`,
+                    });
+                }
+                if (uniquePermissions.has(permission)) {
+                    issues.push({
+                        moduleId: typeof module.id === 'string' ? module.id : undefined,
+                        message: `backendModules[${moduleLabel}].permissions contains duplicate "${permission}"`,
+                    });
+                }
+                uniquePermissions.add(permission);
+            }
+        }
+        const enablement = module.enablement;
+        if (!enablement || typeof enablement !== 'object') {
+            issues.push({
+                moduleId: typeof module.id === 'string' ? module.id : undefined,
+                message: `backendModules[${moduleLabel}].enablement is required`,
+            });
+        }
+        else {
+            if (enablement.default !== 'disabled') {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.default must be "disabled". ` +
+                        'Privileged capabilities are always opt-in.',
+                });
+            }
+            if (enablement.promptOn !== 'firstUse') {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.promptOn must be "firstUse"`,
+                });
+            }
+            if (typeof enablement.purpose !== 'string' || enablement.purpose.trim().length === 0) {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.purpose must be a non-empty string. ` +
+                        'This is shown verbatim in the consent prompt - write it from the user\'s perspective.',
+                });
+            }
+            else if (enablement.purpose.length > 280) {
+                issues.push({
+                    moduleId: typeof module.id === 'string' ? module.id : undefined,
+                    message: `backendModules[${moduleLabel}].enablement.purpose is too long (${enablement.purpose.length} chars). ` +
+                        'Keep it under 280 characters; long copy doesn\'t fit the consent prompt.',
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Convenience wrapper that throws if any fatal issues are found. Warnings
+ * (currently: deprecated permission ids) are surfaced via the issues array
+ * but never throw, so an extension that still references `spawn-process`
+ * keeps loading -- the host just drops the id when computing effective
+ * permissions.
+ *
+ * Use this in main-process load paths where invalid manifests should refuse
+ * the extension outright.
+ */
+export function assertBackendModulesValid(extensionId, backendModules) {
+    const issues = validateBackendModules(backendModules);
+    const fatal = issues.filter((i) => i.severity !== 'warning');
+    if (fatal.length === 0) {
+        return;
+    }
+    const lines = fatal.map((i) => i.moduleId ? `  - [${i.moduleId}] ${i.message}` : `  - ${i.message}`);
+    throw new Error(`Extension ${extensionId} has invalid backendModules declarations:\n${lines.join('\n')}`);
+}
+/**
+ * Filter a raw `permissions` array on a backend-module contribution down to
+ * the ids the host actually understands. Deprecated catalog ids
+ * (`spawn-process`, `network-loopback`, `network-internet`, `filesystem`)
+ * are dropped silently -- they never gated anything inside the backend
+ * runtime, so the host treats them as no-ops. Unknown ids are also dropped;
+ * `validateBackendModules` raises a separate error for those, so the loader
+ * will refuse the module before this is consulted in earnest.
+ */
+export function effectiveModulePermissions(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    const seen = new Set();
+    for (const entry of raw) {
+        if (typeof entry !== 'string')
+            continue;
+        if (seen.has(entry))
+            continue;
+        seen.add(entry);
+        if (KNOWN_PERMISSION_IDS.includes(entry)) {
+            out.push(entry);
+        }
+    }
+    return out;
+}
+/**
+ * Extract the set of declared backend-module ids from a manifest's
+ * `contributions.backendModules` array. Used by
+ * {@link validateAgentProviders} so the `backendModuleId` cross-check does
+ * not need the caller to pre-compute the set.
+ *
+ * Returns an empty set if `backendModules` is missing or malformed. Exported
+ * so build tooling can reuse the same extraction logic when checking entry
+ * files against the declared modules.
+ */
+export function extractBackendModuleIds(backendModules) {
+    const ids = new Set();
+    if (!Array.isArray(backendModules))
+        return ids;
+    for (const raw of backendModules) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const id = raw.id;
+        if (typeof id === 'string' && id.length > 0) {
+            ids.add(id);
+        }
+    }
+    return ids;
+}
+/**
+ * Validate the `contributions.aiAgentProviders` array on a manifest.
+ *
+ * AI agent providers are surfaced in Nimbalyst's chat / agent UI as selectable
+ * providers (alongside built-in Claude Code, Claude, OpenAI, etc.). Each
+ * provider is implemented by a backend module that runs outside the renderer
+ * (so it can drive a CLI, hold long-lived processes, or speak a custom
+ * protocol). The contribution shape, in practice:
+ *
+ *   {
+ *     id: string,                       // unique within the extension
+ *     displayName: string,              // shown in the provider dropdown
+ *     backendModuleId: string,          // must match a declared backendModule
+ *     models?: Array<{ id, name, ... }> // models the provider advertises
+ *     toolFileLinks?: { [toolName]: ... } // optional UI hint table
+ *   }
+ *
+ * This validator checks the manifest-side wiring; it does not introspect the
+ * bundle. See {@link validateExtensionBundle} (Node-only) for the bundle-side
+ * check that the referenced backend module actually exports an
+ * `activate`/`createAgentProvider` function.
+ *
+ * Returns the list of problems found - empty means valid.
+ */
+export function validateAgentProviders(aiAgentProviders, backendModules) {
+    if (aiAgentProviders === undefined) {
+        return [];
+    }
+    if (!Array.isArray(aiAgentProviders)) {
+        return [
+            { message: 'contributions.aiAgentProviders must be an array' },
+        ];
+    }
+    const issues = [];
+    if (aiAgentProviders.length > MAX_AGENT_PROVIDERS_PER_EXTENSION) {
+        issues.push({
+            message: `contributions.aiAgentProviders declares ${aiAgentProviders.length} providers; ` +
+                `the maximum is ${MAX_AGENT_PROVIDERS_PER_EXTENSION}. ` +
+                'Split into multiple extensions, or surface variants as models on a single provider.',
+        });
+    }
+    const knownBackendModuleIds = extractBackendModuleIds(backendModules);
+    const seenProviderIds = new Set();
+    for (let i = 0; i < aiAgentProviders.length; i += 1) {
+        const raw = aiAgentProviders[i];
+        if (!raw || typeof raw !== 'object') {
+            issues.push({
+                message: `aiAgentProviders[${i}] must be an object`,
+            });
+            continue;
+        }
+        const provider = raw;
+        const providerLabel = typeof provider.id === 'string' && provider.id.length > 0
+            ? provider.id
+            : `index ${i}`;
+        // (b) id presence + shape + uniqueness within the extension.
+        if (typeof provider.id !== 'string' ||
+            !AGENT_PROVIDER_ID_PATTERN.test(provider.id)) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].id must be a lowercase string matching ` +
+                    `${AGENT_PROVIDER_ID_PATTERN.source} (got ${JSON.stringify(provider.id)})`,
+            });
+        }
+        else if (seenProviderIds.has(provider.id)) {
+            issues.push({
+                providerId: provider.id,
+                message: `aiAgentProviders contains duplicate id "${provider.id}"`,
+            });
+        }
+        else {
+            seenProviderIds.add(provider.id);
+        }
+        // displayName: non-empty string. Surfaced verbatim in the provider
+        // dropdown, so it has to be readable; not currently length-capped because
+        // we have no signal yet on what the UI tolerates. Matches the
+        // AiAgentProviderContribution type, which names this field `displayName`.
+        if (typeof provider.displayName !== 'string' || provider.displayName.trim().length === 0) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].displayName must be a non-empty string ` +
+                    '(shown verbatim in the provider dropdown).',
+            });
+        }
+        // (a) backendModuleId must reference a real backendModules[*].id.
+        if (typeof provider.backendModuleId !== 'string' ||
+            provider.backendModuleId.length === 0) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].backendModuleId must be a non-empty string ` +
+                    'referencing a backendModules[*].id declared on the same manifest.',
+            });
+        }
+        else if (!knownBackendModuleIds.has(provider.backendModuleId)) {
+            issues.push({
+                providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                message: `aiAgentProviders[${providerLabel}].backendModuleId "${provider.backendModuleId}" ` +
+                    'does not match any contributions.backendModules[*].id. ' +
+                    'Agent providers must be implemented by a declared backend module on the same extension.',
+            });
+        }
+        // (c) models, if present, must be an array of { id, name }. These are
+        // the only required fields on the AiAgentProviderModel type; the host
+        // derives the provider from the contribution id, so models carry no
+        // per-entry provider field.
+        if (provider.models !== undefined) {
+            if (!Array.isArray(provider.models)) {
+                issues.push({
+                    providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                    message: `aiAgentProviders[${providerLabel}].models must be an array (or omitted).`,
+                });
+            }
+            else {
+                const seenModelIds = new Set();
+                for (let m = 0; m < provider.models.length; m += 1) {
+                    const rawModel = provider.models[m];
+                    const modelLabel = `models[${m}]`;
+                    if (!rawModel || typeof rawModel !== 'object') {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].${modelLabel} must be an object`,
+                        });
+                        continue;
+                    }
+                    const model = rawModel;
+                    if (typeof model.id !== 'string' ||
+                        model.id.trim().length === 0) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].${modelLabel}.id must be a non-empty string`,
+                        });
+                    }
+                    else if (seenModelIds.has(model.id)) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].models contains duplicate id "${model.id}"`,
+                        });
+                    }
+                    else {
+                        seenModelIds.add(model.id);
+                    }
+                    if (typeof model.name !== 'string' ||
+                        model.name.trim().length === 0) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].${modelLabel}.name must be a non-empty string`,
+                        });
+                    }
+                }
+            }
+        }
+        // (d) toolFileLinks, if present, must be a plain object whose keys are
+        // non-empty strings (tool names). We deliberately do NOT validate the
+        // values: the host-side schema for the link payload is still in flux,
+        // and rejecting unknown value shapes here would force every shape change
+        // through this SDK file. Keys are the only contract this validator
+        // pins.
+        if (provider.toolFileLinks !== undefined) {
+            if (typeof provider.toolFileLinks !== 'object' ||
+                provider.toolFileLinks === null ||
+                Array.isArray(provider.toolFileLinks)) {
+                issues.push({
+                    providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                    message: `aiAgentProviders[${providerLabel}].toolFileLinks must be a plain object ` +
+                        'mapping tool names to link descriptors (or omitted).',
+                });
+            }
+            else {
+                for (const key of Object.keys(provider.toolFileLinks)) {
+                    if (typeof key !== 'string' || key.length === 0) {
+                        issues.push({
+                            providerId: typeof provider.id === 'string' ? provider.id : undefined,
+                            message: `aiAgentProviders[${providerLabel}].toolFileLinks contains an empty/invalid tool name key`,
+                        });
+                    }
+                }
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Convenience wrapper that throws if any fatal aiAgentProviders issues are
+ * found. Mirrors {@link assertBackendModulesValid}. Use this in main-process
+ * load paths where invalid manifests should refuse the extension outright.
+ */
+export function assertAgentProvidersValid(extensionId, aiAgentProviders, backendModules) {
+    const issues = validateAgentProviders(aiAgentProviders, backendModules);
+    const fatal = issues.filter((i) => i.severity !== 'warning');
+    if (fatal.length === 0) {
+        return;
+    }
+    const lines = fatal.map((i) => i.providerId ? `  - [${i.providerId}] ${i.message}` : `  - ${i.message}`);
+    throw new Error(`Extension ${extensionId} has invalid aiAgentProviders declarations:\n${lines.join('\n')}`);
+}

package/dist/trackerReferences.d.ts

@@ -0,0 +1,32 @@
+import type { ComponentType } from 'react';
+export interface ResolvedTrackerReference {
+    id: string;
+    issueKey?: string;
+    title: string;
+    status?: string;
+    type?: string;
+    priority?: string;
+    owner?: string;
+    updatedAt?: string;
+}
+export interface TrackerReferenceChipProps {
+    referenceKey: string;
+    nodeKey?: string;
+    variant?: 'default' | 'compact';
+}
+export interface TrackerReferencePickerProps {
+    value: readonly string[];
+    onChange(value: string[]): void;
+    multiple?: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    className?: string;
+    maxResults?: number;
+}
+/** Host-provided live tracker reference chip. */
+export declare const TrackerReferenceChip: ComponentType<TrackerReferenceChipProps>;
+/** Host-provided canonical tracker search and selection UI. */
+export declare const TrackerReferencePicker: ComponentType<TrackerReferencePickerProps>;
+export declare const useResolvedTrackerReference: (referenceKey: string) => ResolvedTrackerReference | null;
+export declare const navigateToTrackerReference: (reference: ResolvedTrackerReference) => void;
+//# sourceMappingURL=trackerReferences.d.ts.map

package/dist/trackerReferences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trackerReferences.d.ts","sourceRoot":"","sources":["../src/trackerReferences.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAQ3C,MAAM,WAAW,wBAAwB;IACvC,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,SAAS,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,2BAA2B;IAC1C,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,iDAAiD;AACjD,eAAO,MAAM,oBAAoB,EAA+B,aAAa,CAAC,yBAAyB,CAAC,CAAC;AAEzG,+DAA+D;AAC/D,eAAO,MAAM,sBAAsB,EAAiC,aAAa,CAAC,2BAA2B,CAAC,CAAC;AAE/G,eAAO,MAAM,2BAA2B,EAAsC,CAC5E,YAAY,EAAE,MAAM,KACjB,wBAAwB,GAAG,IAAI,CAAC;AAErC,eAAO,MAAM,0BAA0B,EAAqC,CAC1E,SAAS,EAAE,wBAAwB,KAChC,IAAI,CAAC"}

package/dist/trackerReferences.js

@@ -0,0 +1,7 @@
+import { TrackerReferenceChip as HostTrackerReferenceChip, TrackerReferencePicker as HostTrackerReferencePicker, navigateToTrackerReference as hostNavigateToTrackerReference, useResolvedTrackerReference as hostUseResolvedTrackerReference, } from '@nimbalyst/runtime';
+/** Host-provided live tracker reference chip. */
+export const TrackerReferenceChip = HostTrackerReferenceChip;
+/** Host-provided canonical tracker search and selection UI. */
+export const TrackerReferencePicker = HostTrackerReferencePicker;
+export const useResolvedTrackerReference = hostUseResolvedTrackerReference;
+export const navigateToTrackerReference = hostNavigateToTrackerReference;