@nimbalyst/extension-sdk 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (65) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/dist/__tests__/createTextCollabContentAdapter.test.d.ts +2 -0
  3. package/dist/__tests__/createTextCollabContentAdapter.test.d.ts.map +1 -0
  4. package/dist/__tests__/createTextCollabContentAdapter.test.js +60 -0
  5. package/dist/__tests__/hasSeedableContent.test.d.ts +2 -0
  6. package/dist/__tests__/hasSeedableContent.test.d.ts.map +1 -0
  7. package/dist/__tests__/hasSeedableContent.test.js +25 -0
  8. package/dist/__tests__/manifestValidation.agentProviders.test.d.ts +2 -0
  9. package/dist/__tests__/manifestValidation.agentProviders.test.d.ts.map +1 -0
  10. package/dist/__tests__/manifestValidation.agentProviders.test.js +44 -0
  11. package/dist/agents/AgentProtocol.d.ts +227 -0
  12. package/dist/agents/AgentProtocol.d.ts.map +1 -0
  13. package/dist/agents/AgentProtocol.js +23 -0
  14. package/dist/agents/AgentProtocolHost.d.ts +190 -0
  15. package/dist/agents/AgentProtocolHost.d.ts.map +1 -0
  16. package/dist/agents/AgentProtocolHost.js +42 -0
  17. package/dist/agents/index.d.ts +26 -0
  18. package/dist/agents/index.d.ts.map +1 -0
  19. package/dist/agents/index.js +24 -0
  20. package/dist/collab/createTextCollabContentAdapter.d.ts +26 -0
  21. package/dist/collab/createTextCollabContentAdapter.d.ts.map +1 -0
  22. package/dist/collab/createTextCollabContentAdapter.js +79 -0
  23. package/dist/index.d.ts +3 -0
  24. package/dist/index.d.ts.map +1 -1
  25. package/dist/index.js +2 -0
  26. package/dist/manifestValidation.d.ts +118 -0
  27. package/dist/manifestValidation.d.ts.map +1 -0
  28. package/dist/manifestValidation.js +475 -0
  29. package/dist/types/collab.d.ts +138 -0
  30. package/dist/types/collab.d.ts.map +1 -0
  31. package/dist/types/collab.js +1 -0
  32. package/dist/types/editor.d.ts +71 -0
  33. package/dist/types/editor.d.ts.map +1 -1
  34. package/dist/types/editors.d.ts +4 -0
  35. package/dist/types/editors.d.ts.map +1 -1
  36. package/dist/types/extension.d.ts +364 -5
  37. package/dist/types/extension.d.ts.map +1 -1
  38. package/dist/types/extension.js +11 -1
  39. package/dist/types/index.d.ts +3 -0
  40. package/dist/types/index.d.ts.map +1 -1
  41. package/dist/types/index.js +3 -0
  42. package/dist/types/panel.d.ts +50 -0
  43. package/dist/types/panel.d.ts.map +1 -1
  44. package/dist/types/permissions.d.ts +117 -0
  45. package/dist/types/permissions.d.ts.map +1 -0
  46. package/dist/types/permissions.js +33 -0
  47. package/dist/types/theme.d.ts +50 -0
  48. package/dist/types/theme.d.ts.map +1 -1
  49. package/dist/types/theme.js +7 -1
  50. package/dist/types/trackerImporter.d.ts +147 -0
  51. package/dist/types/trackerImporter.d.ts.map +1 -0
  52. package/dist/types/trackerImporter.js +33 -0
  53. package/dist/useCollaborativeEditor.d.ts +84 -30
  54. package/dist/useCollaborativeEditor.d.ts.map +1 -1
  55. package/dist/useCollaborativeEditor.js +95 -7
  56. package/dist/validate.browser.d.ts +5 -0
  57. package/dist/validate.browser.d.ts.map +1 -0
  58. package/dist/validate.browser.js +27 -0
  59. package/dist/validate.d.ts +2 -8
  60. package/dist/validate.d.ts.map +1 -1
  61. package/dist/validate.js +117 -0
  62. package/dist/validationTypes.d.ts +9 -0
  63. package/dist/validationTypes.d.ts.map +1 -0
  64. package/dist/validationTypes.js +1 -0
  65. package/package.json +4 -1
@@ -0,0 +1,42 @@
1
+ /**
2
+ * AgentProtocolHost
3
+ * -----------------
4
+ *
5
+ * Surface that the host (Nimbalyst) provides to an extension-owned
6
+ * `AgentProtocol` implementation at runtime. The protocol implementation
7
+ * lives in an extension's backend module and is brokered to the host by
8
+ * the privileged-host backend-module runtime; it must never reach for
9
+ * host internals directly.
10
+ *
11
+ * Identity fields are immutable for the lifetime of the host: they
12
+ * identify which extension contribution this protocol instance belongs
13
+ * to and which backend module is hosting it. Per-turn inputs (session
14
+ * id, workspace path, model, abort signal, permission mode, MCP
15
+ * servers, environment) are immutable for the lifetime of a single
16
+ * turn but may differ between turns on the same host instance.
17
+ *
18
+ * All async methods reject when the underlying broker call is rejected
19
+ * by the host (missing permission, unknown session, workspace
20
+ * mismatch, etc.) -- the protocol implementation is expected to
21
+ * surface those rejections as protocol-level errors rather than
22
+ * swallowing them.
23
+ *
24
+ * -------------------------------------------------------------------
25
+ * Q7 -- scope of this host (Phase-4 SDK proposal, resolved 2026-06-02)
26
+ * -------------------------------------------------------------------
27
+ *
28
+ * Per Q7 (Phase-4 SDK proposal, resolved 2026-06-02):
29
+ * emitEvent / requestPermission / askUserQuestion stay provider-private
30
+ * per the established upstream pattern (OpenAICodexProvider:1422-1491,
31
+ * claudeCode/askUserQuestion.ts:10, ProviderSessionManager.ts:49).
32
+ * Section 4.3's full facade is the agreed end-state, hoisted
33
+ * incrementally when each in-tree provider is next touched. Phase 4
34
+ * therefore ships the minimal 5-method host below; the missing
35
+ * methods are NOT a regression -- they live on the provider's own
36
+ * surface today and migrate behind a stable facade as each provider
37
+ * is reworked.
38
+ *
39
+ * See `docs/EXTENSION_ARCHITECTURE.md` and the Phase 4 SDK design doc
40
+ * (Section 4.3) for the full host contract.
41
+ */
42
+ export {};
@@ -0,0 +1,26 @@
1
+ /**
2
+ * Public agent-provider surface for the Nimbalyst extension SDK.
3
+ *
4
+ * Extensions that ship an `AiAgentProviderContribution` import the
5
+ * `AgentProtocol`, `AgentProtocolHost`, and supporting types from
6
+ * this subpath:
7
+ *
8
+ * import type {
9
+ * AgentProtocol,
10
+ * AgentProtocolHost,
11
+ * PermissionMode,
12
+ * } from '@nimbalyst/extension-sdk/agents';
13
+ *
14
+ * Ownership model (post Phase-4 dependency inversion):
15
+ *
16
+ * - The transport types (`AgentProtocol`, `ProtocolEvent`, ...) are
17
+ * owned by the SDK in `./AgentProtocol`. The runtime re-exports
18
+ * them from its own `ProtocolInterface` module so existing
19
+ * runtime imports stay source-stable.
20
+ * - The host-surface types (`AgentProtocolHost`, `PermissionMode`,
21
+ * `McpToolDefinition`) live in this package because they only
22
+ * have meaning at the extension boundary.
23
+ */
24
+ export type { AgentProtocol, ProtocolEvent, ProtocolMessage, ProtocolSession, ProtocolAttachment, SessionOptions, ProtocolEventType, ToolResult, MCPServerConfig, RawProtocolSession, } from './AgentProtocol.js';
25
+ export type { AgentProtocolHost, PermissionMode, McpToolDefinition, } from './AgentProtocolHost.js';
26
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agents/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,cAAc,EACd,iBAAiB,EACjB,UAAU,EACV,eAAe,EACf,kBAAkB,GACnB,MAAM,oBAAoB,CAAC;AAc5B,YAAY,EACV,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,wBAAwB,CAAC"}
@@ -0,0 +1,24 @@
1
+ /**
2
+ * Public agent-provider surface for the Nimbalyst extension SDK.
3
+ *
4
+ * Extensions that ship an `AiAgentProviderContribution` import the
5
+ * `AgentProtocol`, `AgentProtocolHost`, and supporting types from
6
+ * this subpath:
7
+ *
8
+ * import type {
9
+ * AgentProtocol,
10
+ * AgentProtocolHost,
11
+ * PermissionMode,
12
+ * } from '@nimbalyst/extension-sdk/agents';
13
+ *
14
+ * Ownership model (post Phase-4 dependency inversion):
15
+ *
16
+ * - The transport types (`AgentProtocol`, `ProtocolEvent`, ...) are
17
+ * owned by the SDK in `./AgentProtocol`. The runtime re-exports
18
+ * them from its own `ProtocolInterface` module so existing
19
+ * runtime imports stay source-stable.
20
+ * - The host-surface types (`AgentProtocolHost`, `PermissionMode`,
21
+ * `McpToolDefinition`) live in this package because they only
22
+ * have meaning at the extension boundary.
23
+ */
24
+ export {};
@@ -0,0 +1,26 @@
1
+ import type { CollabAdapterDescriptor, CollabContentAdapter } from '../types/collab.js';
2
+ /** Default `Y.Text` field name used when none is supplied. */
3
+ export declare const TEXT_COLLAB_DEFAULT_FIELD = "content";
4
+ export interface TextCollabContentAdapterOptions {
5
+ /** Logical document type. Matches the shared doc's documentType and, by
6
+ * convention, the custom-editor suffix without its dot (e.g. 'calc.md'). */
7
+ documentType: string;
8
+ /** On-disk extensions this adapter is the codec for (leading dot). The
9
+ * first entry is the default for save-a-copy / export. */
10
+ fileExtensions: string[];
11
+ /** Optional MIME type for save dialogs / asset uploads. */
12
+ mimeType?: string;
13
+ /** Y.Text field name carrying the document text. Default 'content'. The
14
+ * live binding MUST use the same field. */
15
+ textField?: string;
16
+ /** Layout schema version. Default 1. */
17
+ layoutVersion?: number;
18
+ }
19
+ export declare function createTextCollabContentAdapter(options: TextCollabContentAdapterOptions): CollabContentAdapter;
20
+ /**
21
+ * Rebuild a CollabContentAdapter from a serializable descriptor (produced by a
22
+ * host factory and shipped across the process boundary). Returns null for an
23
+ * unknown descriptor kind so callers can fall back gracefully.
24
+ */
25
+ export declare function reconstructCollabContentAdapterFromDescriptor(descriptor: CollabAdapterDescriptor): CollabContentAdapter | null;
26
+ //# sourceMappingURL=createTextCollabContentAdapter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"createTextCollabContentAdapter.d.ts","sourceRoot":"","sources":["../../src/collab/createTextCollabContentAdapter.ts"],"names":[],"mappings":"AAkBA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EAErB,MAAM,oBAAoB,CAAC;AAE5B,8DAA8D;AAC9D,eAAO,MAAM,yBAAyB,YAAY,CAAC;AAEnD,MAAM,WAAW,+BAA+B;IAC9C;iFAC6E;IAC7E,YAAY,EAAE,MAAM,CAAC;IACrB;+DAC2D;IAC3D,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;gDAC4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAWD,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,+BAA+B,GACvC,oBAAoB,CAoDtB;AAED;;;;GAIG;AACH,wBAAgB,6CAA6C,CAC3D,UAAU,EAAE,uBAAuB,GAClC,oBAAoB,GAAG,IAAI,CAW7B"}
@@ -0,0 +1,79 @@
1
+ /** Default `Y.Text` field name used when none is supplied. */
2
+ export const TEXT_COLLAB_DEFAULT_FIELD = 'content';
3
+ function decodeSource(source) {
4
+ if (typeof source === 'string')
5
+ return source;
6
+ try {
7
+ return new TextDecoder('utf-8').decode(source);
8
+ }
9
+ catch {
10
+ return '';
11
+ }
12
+ }
13
+ export function createTextCollabContentAdapter(options) {
14
+ const field = options.textField ?? TEXT_COLLAB_DEFAULT_FIELD;
15
+ const layoutVersion = options.layoutVersion ?? 1;
16
+ const getText = (yDoc) => yDoc.getText(field);
17
+ return {
18
+ documentType: options.documentType,
19
+ fileExtensions: options.fileExtensions,
20
+ mimeType: options.mimeType,
21
+ layoutVersion,
22
+ // Lets the host rebuild this adapter in another process (e.g. Electron
23
+ // main) without loading the extension. See reconstruct fn below.
24
+ serializableDescriptor: {
25
+ kind: 'text',
26
+ documentType: options.documentType,
27
+ fileExtensions: options.fileExtensions,
28
+ mimeType: options.mimeType,
29
+ textField: field,
30
+ layoutVersion,
31
+ },
32
+ isEmpty(yDoc) {
33
+ return getText(yDoc).length === 0;
34
+ },
35
+ seedFromFile(yDoc, source) {
36
+ const text = decodeSource(source);
37
+ if (!text)
38
+ return;
39
+ const yText = getText(yDoc);
40
+ // Guard against a concurrent seed during the open race.
41
+ if (yText.length > 0)
42
+ return;
43
+ yText.insert(0, text);
44
+ },
45
+ applyFromFile(yDoc, source) {
46
+ const text = decodeSource(source);
47
+ yDoc.transact(() => {
48
+ const yText = getText(yDoc);
49
+ if (yText.length > 0)
50
+ yText.delete(0, yText.length);
51
+ if (text.length > 0)
52
+ yText.insert(0, text);
53
+ });
54
+ },
55
+ exportToFile(yDoc) {
56
+ return getText(yDoc).toString();
57
+ },
58
+ toPlainText(yDoc) {
59
+ return getText(yDoc).toString();
60
+ },
61
+ };
62
+ }
63
+ /**
64
+ * Rebuild a CollabContentAdapter from a serializable descriptor (produced by a
65
+ * host factory and shipped across the process boundary). Returns null for an
66
+ * unknown descriptor kind so callers can fall back gracefully.
67
+ */
68
+ export function reconstructCollabContentAdapterFromDescriptor(descriptor) {
69
+ if (descriptor.kind === 'text') {
70
+ return createTextCollabContentAdapter({
71
+ documentType: descriptor.documentType,
72
+ fileExtensions: descriptor.fileExtensions,
73
+ mimeType: descriptor.mimeType,
74
+ textField: descriptor.textField,
75
+ layoutVersion: descriptor.layoutVersion,
76
+ });
77
+ }
78
+ return null;
79
+ }
package/dist/index.d.ts CHANGED
@@ -26,9 +26,12 @@ export { REQUIRED_EXTERNALS, EXTERNAL_PATTERNS, ROLLUP_EXTERNALS, type RequiredE
26
26
  export * from './types/index.js';
27
27
  export { useEditorLifecycle, type UseEditorLifecycleOptions, type UseEditorLifecycleResult, type DiffState, } from './useEditorLifecycle.js';
28
28
  export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, type UseCollaborativeEditorConfig, type UseCollaborativeEditorResult, } from './useCollaborativeEditor.js';
29
+ export { createTextCollabContentAdapter, reconstructCollabContentAdapterFromDescriptor, TEXT_COLLAB_DEFAULT_FIELD, type TextCollabContentAdapterOptions, } from './collab/createTextCollabContentAdapter.js';
29
30
  export { useDocumentPath, type DocumentPathContextValue, } from './documentPath.js';
30
31
  export { MaterialSymbol } from './MaterialSymbol.js';
31
32
  export { createReadOnlyHost, type ReadOnlyHost, type ReadOnlyHostOptions, } from './createReadOnlyHost.js';
32
33
  export { copyToClipboard, readClipboard } from './clipboard.js';
33
34
  export { validateExtensionBundle, printValidationResult, type ValidationResult, } from './validate.js';
35
+ export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, type BackendModuleValidationIssue, type AgentProviderValidationIssue, } from './manifestValidation.js';
36
+ export type { AgentProtocol, ProtocolEvent, ProtocolMessage, ProtocolSession, SessionOptions, ProtocolEventType, ToolResult as ProtocolToolResult, MCPServerConfig, RawProtocolSession, AgentProtocolHost, PermissionMode, McpToolDefinition, } from './agents/index.js';
34
37
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,SAAS,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,gBAAgB,EAChB,KAAK,gBAAgB,GACtB,MAAM,gBAAgB,CAAC;AAGxB,cAAc,kBAAkB,CAAC;AAGjC,OAAO,EACL,kBAAkB,EAClB,KAAK,yBAAyB,EAC9B,KAAK,wBAAwB,EAC7B,KAAK,SAAS,GACf,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,6BAA6B,CAAC;AAErC,OAAO,EACL,8BAA8B,EAC9B,6CAA6C,EAC7C,yBAAyB,EACzB,KAAK,+BAA+B,GACrC,MAAM,4CAA4C,CAAC;AAGpD,OAAO,EACL,eAAe,EACf,KAAK,wBAAwB,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAGrD,OAAO,EACL,kBAAkB,EAClB,KAAK,YAAY,EACjB,KAAK,mBAAmB,GACzB,MAAM,yBAAyB,CAAC;AAGjC,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAGhE,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,KAAK,gBAAgB,GACtB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,0BAA0B,EAC1B,sBAAsB,EACtB,yBAAyB,EACzB,uBAAuB,EACvB,iCAAiC,EACjC,KAAK,4BAA4B,EACjC,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AAYjC,YAAY,EACV,aAAa,EACb,aAAa,EACb,eAAe,EACf,eAAe,EACf,cAAc,EACd,iBAAiB,EACjB,UAAU,IAAI,kBAAkB,EAChC,eAAe,EACf,kBAAkB,EAClB,iBAAiB,EACjB,cAAc,EACd,iBAAiB,GAClB,MAAM,mBAAmB,CAAC"}
package/dist/index.js CHANGED
@@ -29,6 +29,7 @@ export * from './types/index.js';
29
29
  // Re-export hooks
30
30
  export { useEditorLifecycle, } from './useEditorLifecycle.js';
31
31
  export { useCollaborativeEditor, COLLAB_INIT_ORIGIN, } from './useCollaborativeEditor.js';
32
+ export { createTextCollabContentAdapter, reconstructCollabContentAdapterFromDescriptor, TEXT_COLLAB_DEFAULT_FIELD, } from './collab/createTextCollabContentAdapter.js';
32
33
  // Re-export host-provided editor context and UI helpers for extensions.
33
34
  export { useDocumentPath, } from './documentPath.js';
34
35
  export { MaterialSymbol } from './MaterialSymbol.js';
@@ -38,3 +39,4 @@ export { createReadOnlyHost, } from './createReadOnlyHost.js';
38
39
  export { copyToClipboard, readClipboard } from './clipboard.js';
39
40
  // Re-export validation
40
41
  export { validateExtensionBundle, printValidationResult, } from './validate.js';
42
+ export { validateBackendModules, assertBackendModulesValid, effectiveModulePermissions, validateAgentProviders, assertAgentProvidersValid, extractBackendModuleIds, MAX_AGENT_PROVIDERS_PER_EXTENSION, } from './manifestValidation.js';
@@ -0,0 +1,118 @@
1
+ /**
2
+ * Pure (no Node/Electron deps) validation helpers for manifest fields.
3
+ *
4
+ * Runs at both build time (via validate.ts, which reads manifest.json from
5
+ * disk) and runtime (when the host loads an extension and needs to refuse
6
+ * invalid contributions). Keep this file dependency-free so it can be bundled
7
+ * into either context without dragging in fs/path.
8
+ */
9
+ import type { ExtensionPermissionId } from './types/permissions.js';
10
+ /**
11
+ * Manifest validation rejects extensions declaring more than this many AI
12
+ * agent providers. Chosen by symmetry with
13
+ * {@link MAX_BACKEND_MODULES_PER_EXTENSION}: an extension that ships more than
14
+ * a handful of agent providers is almost certainly mis-modeled (split it into
15
+ * multiple extensions, or surface them as models on one provider). The cap
16
+ * also keeps the settings UI -- which lists each provider as its own row --
17
+ * from running away.
18
+ */
19
+ export declare const MAX_AGENT_PROVIDERS_PER_EXTENSION = 4;
20
+ export interface BackendModuleValidationIssue {
21
+ /** The module being validated, or undefined for whole-extension issues */
22
+ moduleId?: string;
23
+ message: string;
24
+ /**
25
+ * Non-fatal issues (e.g., a deprecated permission id that the validator
26
+ * silently drops) carry `severity: "warning"`. Callers that fail builds
27
+ * on issues should ignore warnings.
28
+ */
29
+ severity?: 'error' | 'warning';
30
+ }
31
+ /**
32
+ * Validate the `contributions.backendModules` array on a manifest.
33
+ * Returns the list of problems found - empty means valid.
34
+ *
35
+ * Callers decide whether to treat issues as fatal (host loader: refuse the
36
+ * extension) or as warnings (build-time validator: print and continue with
37
+ * non-zero exit).
38
+ */
39
+ export declare function validateBackendModules(backendModules: unknown): BackendModuleValidationIssue[];
40
+ /**
41
+ * Convenience wrapper that throws if any fatal issues are found. Warnings
42
+ * (currently: deprecated permission ids) are surfaced via the issues array
43
+ * but never throw, so an extension that still references `spawn-process`
44
+ * keeps loading -- the host just drops the id when computing effective
45
+ * permissions.
46
+ *
47
+ * Use this in main-process load paths where invalid manifests should refuse
48
+ * the extension outright.
49
+ */
50
+ export declare function assertBackendModulesValid(extensionId: string, backendModules: unknown): void;
51
+ /**
52
+ * Filter a raw `permissions` array on a backend-module contribution down to
53
+ * the ids the host actually understands. Deprecated catalog ids
54
+ * (`spawn-process`, `network-loopback`, `network-internet`, `filesystem`)
55
+ * are dropped silently -- they never gated anything inside the backend
56
+ * runtime, so the host treats them as no-ops. Unknown ids are also dropped;
57
+ * `validateBackendModules` raises a separate error for those, so the loader
58
+ * will refuse the module before this is consulted in earnest.
59
+ */
60
+ export declare function effectiveModulePermissions(raw: unknown): ExtensionPermissionId[];
61
+ /**
62
+ * Issue surface used by {@link validateAgentProviders}. Shaped to mirror
63
+ * {@link BackendModuleValidationIssue} so callers can pool the two streams
64
+ * (build-time validator, runtime loader) through one error pipeline.
65
+ */
66
+ export interface AgentProviderValidationIssue {
67
+ /** The provider being validated, or undefined for whole-extension issues */
68
+ providerId?: string;
69
+ message: string;
70
+ /**
71
+ * Non-fatal issues carry `severity: "warning"`. Callers that fail builds
72
+ * on issues should ignore warnings.
73
+ */
74
+ severity?: 'error' | 'warning';
75
+ }
76
+ /**
77
+ * Extract the set of declared backend-module ids from a manifest's
78
+ * `contributions.backendModules` array. Used by
79
+ * {@link validateAgentProviders} so the `backendModuleId` cross-check does
80
+ * not need the caller to pre-compute the set.
81
+ *
82
+ * Returns an empty set if `backendModules` is missing or malformed. Exported
83
+ * so build tooling can reuse the same extraction logic when checking entry
84
+ * files against the declared modules.
85
+ */
86
+ export declare function extractBackendModuleIds(backendModules: unknown): Set<string>;
87
+ /**
88
+ * Validate the `contributions.aiAgentProviders` array on a manifest.
89
+ *
90
+ * AI agent providers are surfaced in Nimbalyst's chat / agent UI as selectable
91
+ * providers (alongside built-in Claude Code, Claude, OpenAI, etc.). Each
92
+ * provider is implemented by a backend module that runs outside the renderer
93
+ * (so it can drive a CLI, hold long-lived processes, or speak a custom
94
+ * protocol). The contribution shape, in practice:
95
+ *
96
+ * {
97
+ * id: string, // unique within the extension
98
+ * displayName: string, // shown in the provider dropdown
99
+ * backendModuleId: string, // must match a declared backendModule
100
+ * models?: Array<{ id, name, ... }> // models the provider advertises
101
+ * toolFileLinks?: { [toolName]: ... } // optional UI hint table
102
+ * }
103
+ *
104
+ * This validator checks the manifest-side wiring; it does not introspect the
105
+ * bundle. See {@link validateExtensionBundle} (Node-only) for the bundle-side
106
+ * check that the referenced backend module actually exports an
107
+ * `activate`/`createAgentProvider` function.
108
+ *
109
+ * Returns the list of problems found - empty means valid.
110
+ */
111
+ export declare function validateAgentProviders(aiAgentProviders: unknown, backendModules: unknown): AgentProviderValidationIssue[];
112
+ /**
113
+ * Convenience wrapper that throws if any fatal aiAgentProviders issues are
114
+ * found. Mirrors {@link assertBackendModulesValid}. Use this in main-process
115
+ * load paths where invalid manifests should refuse the extension outright.
116
+ */
117
+ export declare function assertAgentProvidersValid(extensionId: string, aiAgentProviders: unknown, backendModules: unknown): void;
118
+ //# sourceMappingURL=manifestValidation.d.ts.map
@@ -0,0 +1 @@
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"}