@collective-intelligence/extensions-sdk 0.0.0-stage → 0.1.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 (64) hide show
  1. package/README.md +1276 -2
  2. package/dist/components/agents.d.ts +155 -0
  3. package/dist/components/authoring-core.d.ts +253 -0
  4. package/dist/components/base.d.ts +25 -0
  5. package/dist/components/catalog.d.ts +21 -0
  6. package/dist/components/connections.d.ts +52 -0
  7. package/dist/components/connector-instances.d.ts +142 -0
  8. package/dist/components/connectors.d.ts +408 -0
  9. package/dist/components/dataset-parser-validation.d.ts +2 -0
  10. package/dist/components/dataset-parser.d.ts +74 -0
  11. package/dist/components/datasets.d.ts +356 -0
  12. package/dist/components/declaration.d.ts +12 -0
  13. package/dist/components/executable-authoring.d.ts +27 -0
  14. package/dist/components/external-app-gateway.d.ts +7 -0
  15. package/dist/components/external-application.d.ts +17 -0
  16. package/dist/components/fields.d.ts +34 -0
  17. package/dist/components/knowledge-remote-reference.d.ts +7 -0
  18. package/dist/components/knowledge.d.ts +188 -0
  19. package/dist/components/lifecycle.d.ts +7 -0
  20. package/dist/components/metadata-authoring.d.ts +66 -0
  21. package/dist/components/notification-channel-capabilities.d.ts +7 -0
  22. package/dist/components/remote-tool-collection.d.ts +3 -0
  23. package/dist/components/studio.d.ts +48 -0
  24. package/dist/components/templates.d.ts +50 -0
  25. package/dist/components/tools.d.ts +138 -0
  26. package/dist/components/workflow-editor.d.ts +28 -0
  27. package/dist/components/workflow-node-authoring.d.ts +4 -0
  28. package/dist/components/workflow-ports.d.ts +26 -0
  29. package/dist/components/workflow-results.d.ts +75 -0
  30. package/dist/components/workflow-rules.d.ts +20 -0
  31. package/dist/components/workflow-schema.d.ts +22 -0
  32. package/dist/components/workflows.d.ts +529 -0
  33. package/dist/foundation/json.d.ts +8 -0
  34. package/dist/foundation/string-order.d.ts +2 -0
  35. package/dist/gateway/declarations.d.ts +69 -0
  36. package/dist/gateway/operation-contract.d.ts +29 -0
  37. package/dist/hosted/contributions.d.ts +52 -0
  38. package/dist/index.d.ts +69 -0
  39. package/dist/index.js +1 -0
  40. package/dist/package/canonical.d.ts +9 -0
  41. package/dist/package/connector-readers.d.ts +171 -0
  42. package/dist/package/definition.d.ts +31 -0
  43. package/dist/package/dependencies.d.ts +10 -0
  44. package/dist/package/instance-readers.d.ts +4 -0
  45. package/dist/package/knowledge-readers.d.ts +137 -0
  46. package/dist/package/manifest.d.ts +42 -0
  47. package/dist/package/parse-manifest.d.ts +3 -0
  48. package/dist/package/policy-readers.d.ts +17 -0
  49. package/dist/package/presentation-readers.d.ts +61 -0
  50. package/dist/package/primitive-readers.d.ts +678 -0
  51. package/dist/package/readers.d.ts +230 -0
  52. package/dist/package/template-readers.d.ts +37 -0
  53. package/dist/package/workflow-readers.d.ts +167 -0
  54. package/dist/release/archive.d.ts +11 -0
  55. package/dist/release/manifest.d.ts +66 -0
  56. package/dist/release/paths.d.ts +5 -0
  57. package/dist/release/stored-manifest.d.ts +13 -0
  58. package/dist/schema/forms.d.ts +117 -0
  59. package/dist/schema/knowledge-record.d.ts +16 -0
  60. package/dist/schema/normalization.d.ts +7 -0
  61. package/dist/schema/profiles.d.ts +45 -0
  62. package/dist/schema/projection.d.ts +59 -0
  63. package/dist/schema/source.d.ts +65 -0
  64. package/package.json +46 -4
package/README.md CHANGED
@@ -1,3 +1,1277 @@
1
- # Temporary Holding Version
1
+ # `@collective-intelligence/extensions-sdk`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ The extensions SDK is the framework-neutral authoring contract for Collective
4
+ Intelligence packages. It produces deterministic JSON-only manifests while
5
+ retaining native validators and implementation constructors as local runtime
6
+ sidecars. It has no Effect, React, Zod, database, HTTP, or deployment
7
+ dependency.
8
+
9
+ Dataset file parsers use `declareDatasetParser({ manifest, presentation,
10
+ definition, implementation })`. The portable definition is `{ format: string,
11
+ extensions: readonly string[], mediaTypes: readonly string[], parserVersion: string }`.
12
+ Format identifiers match `^[a-z][a-z0-9._-]*$`, contain at most 128 characters,
13
+ and cannot be `external`. Parser versions are nonblank and at most 96 characters.
14
+ Both declaration and portable manifest admission enforce these bounds.
15
+ The no-argument implementation class provides `analyze(DatasetParserInput)` and
16
+ `parseRecords(DatasetParserRecordsInput)`. Inputs carry `bytes: Uint8Array` and
17
+ `maxRows`; records input also carries `fields: readonly DatasetParserField[]`.
18
+ Both methods return a value or PromiseLike `DatasetParserResult<T>`:
19
+ `{ status: "success", value: T }` or `{ status: "failure", error }`.
20
+ Analysis contains diagnostics, fields, fingerprint, and rowCount; records contain
21
+ diagnostics and rows. Errors preserve `DatasetCsvParseError`,
22
+ `DatasetCsvLimitExceededError`, and `DatasetImportParseError` tags and fields as
23
+ plain JSON objects. Unexpected failures reject. Constructors and bytes never
24
+ enter the portable manifest.
25
+
26
+ Dataset Table Templates use `declareDatasetTableTemplate({ manifest,
27
+ presentation, definition })`. The portable definition carries an immutable
28
+ physical code (`gen`, `snap`, `ts`, `evt`, `fact`, `stat`), semantic roles,
29
+ admitted ingestion modes, identity and uniqueness, index and partition hints,
30
+ requirements/configuration JSON Schema, and compatible Provider FQNs. Templates
31
+ do not prescribe business field names. Providers call
32
+ `rejectUnsupportedDatasetTableTemplate` before provision.
33
+
34
+ Dataset Blueprints use `declareDatasetBlueprint({ manifest, presentation,
35
+ definition })` so any extension package can contribute a reusable managed
36
+ Dataset shape. The portable definition references one Dataset Table Template
37
+ FQN, carries the provider-neutral `DatasetDefinition`, and may include a
38
+ JSON-only `configuration` object. Its positive integer `blueprintVersion` is
39
+ durable activation provenance and is distinct from the package component's
40
+ string `manifest.version`. Activation, provider selection, credentials, and
41
+ persistence remain Host responsibilities.
42
+
43
+ ```ts
44
+ import {
45
+ declareDatasetBlueprint,
46
+ declarePackage
47
+ } from "@collective-intelligence/extensions-sdk"
48
+
49
+ const simpleRecords = declareDatasetBlueprint({
50
+ definition: {
51
+ blueprintVersion: 1,
52
+ definition: {
53
+ fields: [{ id: "value", name: "Value", nullable: true, type: "string" }],
54
+ measures: [],
55
+ relationships: [],
56
+ version: 1
57
+ },
58
+ templateFqn: "builtin.core.datasets.templates.generic-table"
59
+ },
60
+ manifest: {
61
+ fqn: "com.acme.datasets.blueprints.simple-records",
62
+ version: "1.0.0"
63
+ },
64
+ presentation: { displayName: "Simple records" }
65
+ })
66
+
67
+ export default declarePackage({
68
+ components: [simpleRecords],
69
+ manifest: {
70
+ fqn: "com.acme.datasets",
71
+ name: "Acme Datasets",
72
+ version: "1.0.0"
73
+ }
74
+ })
75
+ ```
76
+
77
+ `datasetBlueprint`, `datasetParser`, `datasetTableTemplate`,
78
+ `managedDatasetProvider`, and `externalDatasetProvider` are separate
79
+ primitive kinds. `declareManagedDatasetProvider` requires an
80
+ implementation class with readiness, datasetProvision, datasetIngest,
81
+ datasetQuery, datasetInspect, and datasetDelete. `declareExternalDatasetProvider`
82
+ requires readiness, listSources, discoverDefinition, datasetQuery, and
83
+ datasetInspect. Metadata-only declarations must bind their implementation.
84
+ Provider methods use the portable dataset input types and
85
+ `DatasetProviderResult<T>` success/failure envelopes. Their errors use
86
+ `DatasetProviderError`, independently of parser errors. Provider declarations
87
+ carry no `engineKind`, `supportedBindingModes`, duplicated binding-mode
88
+ capability, or `extractPage`. Package manifests use `apiVersion` `v4`.
89
+
90
+ Workflow trigger node contracts can declare `triggerActivation`. Use
91
+ `{ kind: "manual" }` or `{ kind: "schedule" }` for those activation categories.
92
+ Event triggers use `{ kind: "event", eventIngress }`, where `eventIngress`
93
+ names the event kind, acquisition mode, exact listener FQN/version,
94
+ required-listener policy, and JSON-only selector projections. Each selector
95
+ entry copies a configuration value from `sourcePath` to `targetPath`, or writes
96
+ a literal `value` to `targetPath`. `connectionIdPath` identifies a connection
97
+ in trigger configuration; `requiredConfigPaths` and a projection's `required`
98
+ flag reject missing values during binding. Paths are arrays of object keys or
99
+ array indices, relative to the trigger configuration or selector respectively.
100
+ The Host owns validation, listener resolution, and subscription lifecycle;
101
+ `parseWorkflowTriggerActivation` validates an untrusted catalog value before
102
+ the Host uses it.
103
+ Manual triggers may also declare a `lifecycleAdapterId` from
104
+ `WorkflowTriggerLifecycleAdapterIds`; the Host resolves that exact ID to its
105
+ publication or binding behavior without inspecting the trigger FQN and rejects
106
+ IDs it does not implement.
107
+ Manual triggers may declare `invocationRole: "user" | "application"`, and
108
+ `triggerRefPath` for a Studio-addressable reference. Event ingress may declare
109
+ `callbackPathPath` for a token-authenticated webhook path. Publication copies
110
+ these values and the event kind/acquisition mode into normalized Host columns;
111
+ repositories select by those columns instead of extension identity or private
112
+ configuration keys.
113
+
114
+ Action nodes that invoke another Workflow declare `reusableDependency` paths
115
+ for the target Workflow ID and selected input contract, plus an optional
116
+ `modePath` fixed-mode marker. The Host resolves these paths from the pinned
117
+ declaration before persisting dependency edges.
118
+ `parseWorkflowReusableDependency` validates catalog values.
119
+
120
+ Workflow node ports declare connection rules next to their `valueSchema`:
121
+ `minConnections` (default 0), `maxConnections` (absent means 1, `null` means
122
+ unbounded), and optional non-empty `allowedTemplateKinds` (`trigger_node`,
123
+ `input_node`, `action_node`, `output_node`) and `allowedTemplateFqns`. A port
124
+ may declare `schemaResolution`: `configPath` names a configuration value, and
125
+ each variant's `schema` applies when that value equals `when`. A variant's
126
+ `schemaInjections` copy a JSON Schema configuration value (`configPath`) into
127
+ the variant schema at `schemaPath`. Variant schemas follow the port direction:
128
+ output ports need codecs.
129
+
130
+ `dynamicPorts.input` / `dynamicPorts.output` derive ports from configuration:
131
+ one port per item of the list at `configPath`, keyed by the item's `idPath`
132
+ (optional `requiredPath` and `schemaPath` per item). An optional
133
+ `defaultIdPath` names a configuration value that adds one more port with the
134
+ same rules; when unset, its id is that value's schema `default`. Paths are
135
+ dotted property paths.
136
+
137
+ `resolveWorkflowNodePorts(contract, config)` is the one resolver of a node's
138
+ effective ports, shared by hosts and editors. It returns `{ ports, issues }`
139
+ in legacy `compile_ports` order: static inputs, derived inputs, derived
140
+ outputs (list items, then the default id), and static outputs. A static
141
+ port with `schemaResolution` takes the variant whose `when` equals the
142
+ configuration value at its `configPath`, with each injection's configured
143
+ JSON Schema written over the existing member at `schemaPath`; with no
144
+ matching variant, or an unset or non-schema injected value, the port keeps its
145
+ base `valueSchema`. An expression at a selector or injection path yields
146
+ `port_schema_config_not_fixed`. Only a
147
+ configuration value's top-level key may be authored (`{ mode: "fixed", value }`
148
+ unwraps; an expression yields `dynamic_port_config_not_fixed`); deeper values
149
+ are plain JSON, and an unset value falls back to the configuration schema
150
+ `default`. Ids must be non-empty strings matching the item schema's id
151
+ `pattern` (`dynamic_port_id_invalid`); the list must honor its schema
152
+ `minItems` and `maxItems` (`dynamic_port_count_invalid`) and be a list, with
153
+ each `schemaPath` value a JSON Schema (`dynamic_port_config_invalid`). An id already used in its direction is dropped with
154
+ `dynamic_port_id_duplicate`. Derived outputs accept `action_node` and
155
+ `output_node` with no connection limit; derived inputs accept `action_node` and
156
+ `input_node`, with `minConnections` 1 unless the item's `requiredPath` value is
157
+ `false`. A derived port's `valueSchema` is the item's `schemaPath` value, else
158
+ an open object. Issues carry `{ code, path, message }`; `path` starts at the
159
+ top-level configuration key. `workflowSchemaAt(root, path)` exposes the
160
+ reference- and nullable-resolving schema lookup the resolver uses.
161
+
162
+ Hosts and editors that hold catalog JSON decode it before resolving:
163
+ `parseWorkflowNodeContract(value)` validates an untrusted node contract with
164
+ the same readers as manifest admission, and `parseJsonSchemaProjection(value,
165
+ fidelity = "structural")` wraps a bare JSON Schema object, such as an
166
+ unwrapped `configSchema`, as a `PackageSchemaProjection`. Both throw a
167
+ `TypeError` naming the first invalid location.
168
+
169
+ `declareWorkflowNode` rejects contracts whose parts disagree: port policies
170
+ (`minConnections` above the effective `maxConnections`, negative or
171
+ non-integer counts, empty `allowedTemplateKinds`, `allowedTemplateFqns`, or
172
+ `schemaResolution.variants`), duplicate `direction:key` ports, a
173
+ `mainOutputPort` that names neither a static output nor the dynamic output
174
+ default id's schema `default`, `schemaResolution` or injection `configPath`s
175
+ and connection `selector`s absent from `configSchema`, a dynamic-port
176
+ `configPath` that is not a list in `configSchema`, `idPath`, `requiredPath`,
177
+ or `schemaPath` absent from its item schema, and a `defaultIdPath` without a
178
+ schema `default`. An injection `schemaPath` must name an existing member of
179
+ its variant schema. Manifest admission applies the same port policies, requires
180
+ non-empty `connectionTemplateFqns`, and checks the editor rules below.
181
+
182
+ `execution` declares `sideEffect` (`none`, `read`, `write`, `external`) and
183
+ optional `mainOutputPort`, `resumable`, `testable`, and `itemModes`
184
+ (`single`, `each_item`, `all_items`). Triggers answering their caller declare
185
+ `outputChannels` (`key`, codec `valueSchema`, `cardinality`, `deliveryMode`,
186
+ `adapterId`, `required`). `connectionRequirements` name credential-free
187
+ connection selectors; each `selector` must be a `parameter` path present in
188
+ `configSchema`.
189
+
190
+ An external Dataset Provider may declare `sourceCapabilities` entries with a
191
+ `datasetOpaqueIdPrefix` and complete `capabilities`. When the selected Dataset
192
+ location's final opaque ID starts with that prefix, the host uses those
193
+ capabilities before intersecting them with the active Dataset policy. Without
194
+ a match, it uses the provider's package-wide capabilities. Prefixes and source
195
+ semantics belong to the provider; the host does not inspect provider FQNs.
196
+
197
+ Executable host contracts live in
198
+ `@collective-intelligence/extensions-sdk-backend`; hosted Studio and Dashboard
199
+ declarations live in `@collective-intelligence/extensions-sdk-frontend-react`. Install
200
+ only the specialized SDK needed by the extension. The common SDK does not
201
+ depend on either specialized package.
202
+
203
+ Published consumers load the compiled ESM and declarations from `dist`; source,
204
+ tests, build tools, and type-test fixtures are not part of the package. Run
205
+ `bun run build` to produce the artifact and `bun run test:pack` to exercise a
206
+ strict isolated consumer before publication.
207
+
208
+ The package root is the only public entrypoint. Its internal source is grouped
209
+ by foundation, schema, component domain, hosted identity, gateway, package,
210
+ and release ownership; those paths are implementation details and must not be
211
+ deep-imported.
212
+
213
+ ## Authoring schemas
214
+
215
+ Install a provider adapter and author with its native validation library. The
216
+ core SDK has no provider-validator dependency. Knowledge entity records may use
217
+ `knowledgeRecordSchema` to compile Organization field definitions into a
218
+ `knowledge_record` source; other consumers still go through a provider adapter.
219
+
220
+ ```ts
221
+ import {
222
+ declarePackage,
223
+ declareTool
224
+ } from "@collective-intelligence/extensions-sdk"
225
+ import { PackageTool } from "@collective-intelligence/extensions-sdk-backend"
226
+ import { effectSchema } from "@collective-intelligence/extensions-sdk-backend-effect"
227
+ import * as Schema from "effect/Schema"
228
+
229
+ const input = effectSchema(Schema.Struct({ id: Schema.NonEmptyString }))
230
+ const output = effectSchema(Schema.Struct({ found: Schema.Boolean }), {
231
+ codec: true
232
+ })
233
+
234
+ class TicketLookup extends PackageTool<
235
+ { readonly id: string },
236
+ { readonly found: boolean }
237
+ > {
238
+ execute() {
239
+ return { found: true }
240
+ }
241
+ }
242
+
243
+ const lookup = declareTool({
244
+ definition: { input, output },
245
+ implementation: TicketLookup,
246
+ manifest: { fqn: "acme.tools.ticket-lookup", version: "1.0.0" },
247
+ presentation: { displayName: "Ticket lookup" }
248
+ })
249
+
250
+ export default declarePackage({
251
+ components: [lookup],
252
+ manifest: { fqn: "acme", name: "Acme", version: "1.0.0" }
253
+ })
254
+ ```
255
+
256
+ Every source implements Standard Schema V1 validation and Standard JSON Schema
257
+ V1 projection. Validation and encoding may be asynchronous; projection and
258
+ manifest construction are synchronous. Output declaration positions require a
259
+ `PackageCodec`, while decoder-only sources remain valid for input positions.
260
+
261
+ ## Event listener declarations
262
+
263
+ Event listeners that support an operator-configured webhook verification token
264
+ may declare `manualWebhookState: { keyFamily, stateKey }`. The same entry must
265
+ appear in `runtimeState` so the host can project the encrypted token to the
266
+ listener. A listener without this declaration is ineligible for manual webhook
267
+ token setup.
268
+
269
+ A listener whose provider validates subscription callback URLs may declare
270
+ `webhookHandshake: { kind: "echo_query_parameter", parameter }`. When a request
271
+ to one of the listener's webhook endpoints carries that query parameter, the
272
+ host answers `200 text/plain` with its value instead of admitting a callback.
273
+
274
+ ## Notification channel declarations
275
+
276
+ A notification channel may set `capabilities.supportsFixedDestinations` when
277
+ its provider supports a fixed route target. Generic notification administration
278
+ reads this flag without interpreting provider-specific recipient target names.
279
+ For older declarations without the flag, the SDK preserves the existing fixed
280
+ destination target kinds. An explicit `false` always takes precedence.
281
+
282
+ ## Knowledge declarations
283
+
284
+ `declareKnowledgeRelationSchema` requires explicit `LifecycleOptions`:
285
+ `{ deployMode: "upsert" | "init_only", readonly: boolean }`. Relation manifests
286
+ from older releases may omit `lifecycle`; parsing preserves that absence without
287
+ inventing a policy and validates any supplied policy. Definition `readonly` is
288
+ independent of relation record `localMutationPolicy`.
289
+
290
+ `declareDomain`, `declareKnowledgeEntitySchema`,
291
+ `declareExternalApplication`, `declareWorkflow`, and
292
+ `declareWorkflowTemplate` require per-item `LifecycleOptions`:
293
+ `{ deployMode: "upsert" | "init_only", readonly: boolean }`. Entity schemas
294
+ also require the persisted Organization entity schema capabilities other than
295
+ relation schemas and parked `relationFields`: `autocompleteConfiguration`,
296
+ `displayNameExpression`, `embeddingConfig`, `persistFullFieldContributions`,
297
+ `usableAsDocumentScope`, and `versioningEnabled`. Domain declarations require
298
+ `versioningEnabled`. External applications require `applicationType`,
299
+ `audience`, `allowedOrigins`, `redirectUris`, `postLogoutRedirectUris`, and
300
+ `scopes`. Tokens and client secrets are not declaration fields. Nullable
301
+ persisted columns may be declared as `null`. Later construct types
302
+ (`skillTemplate`) share the same `LifecycleOptions` type as an optional
303
+ field. This package does not deploy, persist, or lock those declarations.
304
+
305
+ `knowledgeRecordSchema` authors an entity `schema` from field definitions that
306
+ match Organization field types: per-field `required`, `options` for
307
+ `string_select`, `datetime`, and `number` with `numberKind: "integer"`. It
308
+ projects a Draft 2020-12 `knowledge_record` document (`enum`, `format`, root
309
+ `type: "object"`, `required` array). Adapter-owned codecs still use
310
+ `definePackageSchema`.
311
+
312
+ ## Agent and Skill declarations
313
+
314
+ `declareSkill` declares a governed Skill: `instructions`, the `tools` it
315
+ activates, and required `LifecycleOptions`. `declareAgent` declares an
316
+ Organization Agent: its Role (`responsibility`, `objectives`,
317
+ `operatingInstructions`, `behavioralBoundaries`), held `skills`, own `tools`,
318
+ required `LifecycleOptions`, and optional `output: { schema }`, `modelTier`,
319
+ `maxSteps`, `activity`, and `audience`. The output schema is a
320
+ `PackageCodec`, the same kind of source a Tool `output` takes, so an
321
+ application can keep one runtime schema in its own contracts package and
322
+ infer the consumer type from it. Install requires an administrator; built-in
323
+ packages cannot declare Agents or Skills.
324
+
325
+ `modelTier` names one of the standard Organization model tiers: `complex`,
326
+ `balanced`, `fast`, or `super_fast`. Each run uses the model that the
327
+ installing Organization configured for that tier. An omitted tier runs on
328
+ `balanced`. The former `modelPreset` field is retired; a manifest that still
329
+ declares it is rejected.
330
+
331
+ Reference fields (`skills`, `tools`, `audience.applications`) take a
332
+ `DeclarationReference<Kind>`:
333
+
334
+ - a same-package handle, which is what `declareSkill`, `declareTool`,
335
+ `declareExternalApplication`, and the other helpers return. A handle of the
336
+ wrong kind is a TypeScript error;
337
+ - an FQN string, for a built-in primitive or one that another package
338
+ declares. The SDK publishes no list of built-in FQNs.
339
+
340
+ ```ts
341
+ const enrichment = declareSkill({ ... })
342
+ declareAgent({
343
+ definition: {
344
+ ...role,
345
+ skills: [enrichment, "com.acme.shared.meeting-notes"],
346
+ tools: ["builtin.core.knowledge.tools.query"]
347
+ },
348
+ ...
349
+ })
350
+ ```
351
+
352
+ Strings are an escape hatch, not a checked reference: TypeScript accepts any
353
+ string, including a misspelled FQN. Install resolves every reference against
354
+ the installed catalog and rolls the package back when one does not exist: held
355
+ `skills` must be approved Skills, Agent and Skill `tools` must be enabled tools
356
+ of the Organization, and `audience.applications` must name applications of the
357
+ Organization or of the same package.
358
+
359
+ ### Agent audience
360
+
361
+ `audience` is the code maximum of who may converse with the Agent, per caller
362
+ class. An omitted field admits nobody of that class; an omitted `audience`
363
+ admits nobody.
364
+
365
+ | Field | Values | Admits |
366
+ | ------------------- | ------------------------------- | ---------------------------------------------------------------------- |
367
+ | `members` | `"all"`, `"selected"`, `"none"` | Organization members: every member, or the users administrators select |
368
+ | `organizationTeams` | `"selected"`, `"none"` | Organization Teams that administrators select |
369
+ | `applications` | application references | Applications that invoke the Agent as a service or bring visitors |
370
+ | `anonymous` | `true` | Anonymous visitors that a listed application brings |
371
+
372
+ ```ts
373
+ declareAgent({
374
+ definition: {
375
+ ...role,
376
+ audience: {
377
+ anonymous: true,
378
+ applications: [storefront],
379
+ members: "selected",
380
+ organizationTeams: "selected"
381
+ },
382
+ ...
383
+ },
384
+ ...
385
+ })
386
+ ```
387
+
388
+ - Administrators select concrete users and Organization Teams inside this
389
+ maximum. They can only narrow it; they cannot widen it.
390
+ - Organization administrators get no bypass for a declared Agent. An
391
+ administrator outside the audience must add themselves to converse.
392
+ - `anonymous: true` needs at least one application in `applications`:
393
+ visitors always arrive through an application. An anonymous visitor runs
394
+ only the Agent's own bindings, never the application's service authority.
395
+ - `declareAgent` throws a `TypeError` for `anonymous: true` without an
396
+ application and for an application listed more than once. Manifest readers
397
+ reject the same audiences.
398
+
399
+ ### Tool binding controls
400
+
401
+ A `tools` entry of an Agent or a Skill may be a `ToolBinding` instead of a bare
402
+ reference. Both helpers accept and normalize the same shape:
403
+
404
+ ```ts
405
+ declareSkill({
406
+ definition: {
407
+ instructions: "# Member search",
408
+ lifecycle,
409
+ tools: [
410
+ {
411
+ tool: "builtin.core.knowledge.tools.query",
412
+ name: "member-query", // optional; bind one tool several times by name
413
+ settings: { limit: 10 }, // checked against the tool's binding form
414
+ knowledge: {
415
+ domains: { include: [membersDomain] },
416
+ entitySchemas: { exclude: ["com.acme.schemas.contact"] }
417
+ },
418
+ approval: { rule: "Escalations" } // or "never" | "always"
419
+ }
420
+ ]
421
+ },
422
+ ...
423
+ })
424
+ ```
425
+
426
+ - `knowledge` selectors take handles of their own kind (`domain`,
427
+ `knowledgeEntitySchema`, `knowledgeRelationSchema`) or FQN strings. Install
428
+ resolves them to the Organization's definitions and rejects an unknown one,
429
+ or a `knowledge` boundary on a tool that has no Knowledge scope.
430
+ - `approval: { rule }` names an approval rule of the installing Organization;
431
+ install fails when no rule has that name.
432
+ - A `(tool, name)` pair binds once; a repeat throws at authoring and fails
433
+ install.
434
+
435
+ Manifests store every entry as a `ToolBindingDeclaration` with FQN strings.
436
+ Manifest readers also accept a bare FQN string, the form manifests used before
437
+ binding controls; `toolBindingDeclaration` reads either form.
438
+
439
+ ## Hosted contributions
440
+
441
+ `declarePackage` accepts lazy Backend, Studio, and Dashboard contributions in
442
+ one graph. Only stable identity and compatibility metadata enters the
443
+ canonical manifest; loader functions remain local runtime sidecars.
444
+ Declaration order does not affect `canonicalPackageManifest`.
445
+
446
+ Studio render-leaf declarations, including the `page` category, retain a
447
+ required `sourceRef` in the normalized package manifest. Set it to the FQN of
448
+ the same package's authoritative hosted Studio contribution so a Host can
449
+ validate the leaf and its executable contribution together.
450
+
451
+ ```ts
452
+ import {
453
+ declareHostedContribution,
454
+ declarePackage
455
+ } from "@collective-intelligence/extensions-sdk"
456
+
457
+ export default declarePackage({
458
+ components: [],
459
+ hostedContributions: [
460
+ declareHostedContribution({
461
+ exportName: "run",
462
+ fqn: "com.acme.crm.backend.sync",
463
+ host: "backend",
464
+ load: () => import("./sync")
465
+ })
466
+ ],
467
+ manifest: { fqn: "com.acme.crm", name: "CRM", version: "1.0.0" }
468
+ })
469
+ ```
470
+
471
+ ## Third-party adapters
472
+
473
+ `definePackageSchema` is the open structural boundary for adapter packages. An adapter supplies its
474
+ native object, validation, optional encoding, and immutable directional Draft
475
+ 2020-12 projections. `provider` is an open diagnostic string and is never used
476
+ for dispatch. No module augmentation or global registry is involved.
477
+
478
+ ```ts
479
+ const source = definePackageSchema({
480
+ native: librarySchema,
481
+ projections: {
482
+ input: {
483
+ dialect: Draft202012Dialect,
484
+ document: inputJsonSchema,
485
+ fidelity: "structural"
486
+ },
487
+ output: {
488
+ dialect: Draft202012Dialect,
489
+ document: outputJsonSchema,
490
+ fidelity: "structural"
491
+ }
492
+ },
493
+ provider: "example/library",
494
+ validate: (unknownValue) => librarySchema.decode(unknownValue),
495
+ encode: (domainValue) => librarySchema.encode(domainValue)
496
+ })
497
+ ```
498
+
499
+ The SDK freezes its projections and source envelope but never mutates
500
+ or freezes the provider-native object. Declaration materialization normalizes
501
+ even directly implemented structural sources, so mutable projections, older
502
+ dialects, and unresolved local references cannot leak into manifests. Effect
503
+ and Zod integrations belong in their optional adapter packages.
504
+
505
+ ## Manifests and consumer profiles
506
+
507
+ Declarations replace sources with `{ dialect, document, fidelity }`
508
+ `PackageSchemaProjection` values in the
509
+ manifest and retain sources in `schemaSidecars`. `canonicalPackageManifest`
510
+ therefore contains no native objects or functions. Projection changes are
511
+ intentional manifest and declaration-hash changes.
512
+
513
+ ### JSON value boundaries
514
+
515
+ `declareWorkflowNode` always derives the node editor from the projected
516
+ `configSchema` and `inputSchema`; `deriveWorkflowEditor` exposes the same pure
517
+ derivation. Each top-level configuration property becomes a `parameter` field
518
+ (`valueSources` `expression` and `literal`, `runtime` phase), and each input
519
+ property an `input_binding` field (`expression`, `literal`, `mapping`,
520
+ `runtime`). Trigger nodes derive configuration fields only: their
521
+ `inputSchema` is the event payload, so `input_binding` overrides on a trigger
522
+ fail. Nodes without configuration or input schemas get no sections. A configuration property marked with
523
+ `format: WorkflowJsonSchemaFormat` (`"json-schema"`) holds a JSON Schema value
524
+ and becomes a structural, literal-only `schema_builder` field. Configuration
525
+ keys that shape ports (dynamic-port `configPath` and `defaultIdPath`, and
526
+ `schemaResolution` and injection `configPath`s) derive as structural,
527
+ literal-only fields; an override that makes one `runtime` or adds
528
+ `expression` fails. `required`
529
+ follows the schema's `required` list. After resolving local `$ref`s and
530
+ unwrapping nullable values, widgets follow the schema: `enum` becomes `select`,
531
+ an array of `enum` items `multi_select` (both with static options labelled from
532
+ their values), `boolean` `checkbox`, `integer` or `number` `number`, `object`
533
+ `key_value`, `array` `list`, and everything else `text`. Labels are the
534
+ humanized property names. Fields are placed in the default `parameters`
535
+ section, configuration first, in the projection's canonical (alphabetical)
536
+ property order.
537
+
538
+ The authoring `contract.editor` holds overrides only:
539
+ `{ sections: [{ id, title?, order?, fields: [{ binding, ...attributes }] }] }`.
540
+ An override may set any field attribute (`label`, `help`, `placeholder`,
541
+ `widget`, `valueSources`, `resolutionPhase`, `required`, `sensitive`,
542
+ `readOnly`, `order`, `optionSource`, `visibleWhen`, `fieldFqn`,
543
+ `fieldVersion`, `fieldConfig`) and moves the field into its section. The
544
+ `parameters` section may be retitled or reordered; other sections need a
545
+ `title`. Override bindings are top-level property paths, as in legacy. Fields
546
+ sort by `order`, then placement; sections sort by `order`; empty sections are
547
+ omitted. Unknown or duplicate override bindings, duplicate section ids, and
548
+ `visibleWhen` or remote `optionSource.dependsOn` bindings that do not equal a
549
+ field binding exactly fail at declaration time. Manifest admission rejects
550
+ duplicate section ids, duplicate field bindings, and those dangling
551
+ references.
552
+
553
+ A field names a specialized renderer through `fieldFqn` and `fieldVersion`,
554
+ with JSON-only `fieldConfig`. `label`, `help`, `placeholder`, and static option
555
+ labels use `LocalizedFieldText` (`{ fallbackLocale, values }`). These
556
+ presentation fields survive canonical manifest serialization and are validated
557
+ when a manifest is parsed. Keep value types in the node schemas; editor
558
+ metadata does not replace schema validation.
559
+
560
+ `workflow_value` schemas admit `default`, and every profile rejects a
561
+ `default` that does not satisfy its own schema (`invalid_default`). Zod
562
+ projects `.default(value)`. Effect Schema projects only a `default`
563
+ annotation, not the opaque `withDecodingDefault*` Effect; use
564
+ `withWorkflowDefault(value)` from
565
+ `@collective-intelligence/extensions-sdk-backend-effect`, which applies both.
566
+
567
+ Portable manifest fields, forms, dataset values/results, connection discovery
568
+ values, and workflow directives use the recursive `JsonObject` and `JsonValue`
569
+ contracts. Canonicalization accepts
570
+ ordinary and null-prototype JSON objects (including `Object.create(null)`),
571
+ arrays, strings, booleans, `null`, and finite numbers. It rejects functions,
572
+ class instances and other non-plain objects, symbols, `undefined`, cyclic
573
+ values, and non-finite numbers instead of silently dropping or coercing them.
574
+
575
+ Each schema slot has an SDK-owned profile: `runtime_json`,
576
+ `ai_function_input`, `interactive_form`, `workflow_value`, `studio_props`, or
577
+ `knowledge_record`. Unsupported constructs fail with profile, location, and
578
+ reason rather than silently degrading.
579
+
580
+ `interactive_form` also admits `UnrestrictedScopeKeyword`
581
+ (`"x-unrestricted-scope": true`) on a boolean binding-settings field whose
582
+ enabled value lifts the binding's scope restrictions. The host, not the
583
+ package, decides which authority may enable it. The Effect adapter projects
584
+ this annotation; other custom annotations are not projected.
585
+
586
+ Tool inputs default to `ai_function_input`, matching the host's default skill
587
+ exposure. A tool that explicitly declares only non-AI scopes such as
588
+ `usageScopes: ["automation"]` uses `runtime_json`. Setup content belongs in
589
+ `setupInstructions`; AI selection copy belongs separately in `toolGuidance`.
590
+
591
+ Knowledge schemas keep validation separate from pointer-keyed field semantics,
592
+ localization, presentation, and schema-level display defaults. Forms likewise
593
+ keep their projected validation document separate from closed UI, visibility,
594
+ layout, create-step, and update-section metadata.
595
+
596
+ ### Gateway declaration vocabulary
597
+
598
+ General knowledge entity schemas may retain an explicitly declared source
599
+ reference as an `EntityRelationField`; its `field` is a canonical RFC 6901
600
+ instance pointer and is checked against the projected entity schema with the
601
+ other field metadata. This schema vocabulary is not gateway manifest input.
602
+
603
+ The SDK also exports the JSON-only `PortableOperationDeclaration`,
604
+ `OperationDomainDeclaration`, and `PortableGatewayDeclarations` types. They
605
+ establish the shared operation manifest input vocabulary. Every portable
606
+ operation explicitly carries its effect class, idempotency and bounded retry
607
+ policy, organization and delegated-subject authorization, execution mode and
608
+ timeout, request/response/event limits, and version. Retry `maxAttempts` counts
609
+ the initial call plus every permitted retry. These values are JSON-only and
610
+ reviewable; executable handlers, credentials, secrets, gateway identity, and
611
+ content hashing remain with
612
+ `@collective-intelligence/external-apps-server-sdk`.
613
+
614
+ Operations are always carried by one-level operation domains. Remote resource
615
+ definitions and access belong to the external-app server SDK. Organization
616
+ entity schemas, resource selection, field mapping, and relation projection
617
+ belong to the organization connector and never enter portable gateway
618
+ declarations.
619
+
620
+ ### Remote Tool collections
621
+
622
+ `declareRemoteToolCollection` groups existing Gateway Operations for package
623
+ installation through a declared Gateway whose expected contract CI verifies before
624
+ exposing the selected operations:
625
+
626
+ ```ts
627
+ import { declareRemoteToolCollection } from "@collective-intelligence/extensions-sdk"
628
+
629
+ const tools = declareRemoteToolCollection({
630
+ manifest: { fqn: "com.example.nest.tools", version: "1.0.0" },
631
+ presentation: { displayName: "Nest tools" },
632
+ definition: {
633
+ gatewayRef: "com.example.nest.gateways.main",
634
+ operationReferences: ["com.example.nest/greetings/greet@1.0.0"],
635
+ defaultVisibility: [{ effect: "allow", subject: "organization" }]
636
+ }
637
+ })
638
+ // Include tools and the referenced Gateway declaration in the package.
639
+ ```
640
+
641
+ The `gatewayRef` names an `externalAppGateway` declaration FQN included in the
642
+ package. The Gateway, domain and operation identifiers follow Gateway
643
+ manifest bounds: 1–128 ASCII letters, digits, dots, underscores or hyphens,
644
+ beginning with a letter or digit. References use
645
+ `gatewayId/domainId/operationId@version`; versions are nonempty trimmed
646
+ strings of at most 128 characters. Every reference must match the declared
647
+ Gateway, and the selection must be nonempty and unique.
648
+
649
+ The declaration shares `category` and `defaultVisibility` with ordinary Tool
650
+ collections and supports normal identity and presentation metadata. Its closed
651
+ metadata contains no executable implementation, schema sidecar, authorization
652
+ override or credential. These constraints apply during authoring and serialized
653
+ manifest admission. The Host validates the package-owned Gateway Connection and approved
654
+ operations at installation; this declaration grants no execution authority.
655
+
656
+ ### Portable workflow pauses
657
+
658
+ `PackageWorkflowNodeResult<Output>` admits a `directive: "pause"` result with
659
+ an `outputSnapshot` and `PackageWorkflowPauseResumeContract`. The resume
660
+ contract keeps an open `mode: string` and may carry a generic
661
+ `condition?: Readonly<{ kind: string; payload: JsonObject }>`:
662
+
663
+ ```ts
664
+ import type {
665
+ JsonObject,
666
+ PackageWorkflowNodeResult
667
+ } from "@collective-intelligence/extensions-sdk"
668
+
669
+ const pause: PackageWorkflowNodeResult<JsonObject> = {
670
+ directive: "pause",
671
+ outputSnapshot: { requestId: "request-1" },
672
+ resumeContract: {
673
+ condition: { kind: "acme_request", payload: { requestId: "request-1" } },
674
+ mode: "readiness",
675
+ resumePorts: ["completed", "expired"]
676
+ }
677
+ }
678
+ ```
679
+
680
+ The owning package and host define condition kinds, payload meaning, modes,
681
+ and resume ports. The base SDK carries JSON data without interpreting readiness
682
+ or Documents policy. Existing approval, timer, and custom-mode pauses can omit
683
+ `condition`; their other fields remain valid. `expiresAt` and `wakeAt` are still
684
+ optional, and the SDK adds no default expiration. Typed pause results can be
685
+ serialized with `canonicalJson`; execution, durable suspension, resume, and
686
+ cancellation remain host responsibilities.
687
+
688
+ ## Executable implementations
689
+
690
+ The common declaration helpers accept structural implementation constructors,
691
+ so canonical classes from `extensions-sdk-backend` bind without creating a
692
+ reverse dependency from the common SDK. Import executable base classes,
693
+ runtime context, capabilities, and workflow field implementations from that
694
+ specialized package. The common package deliberately does not export
695
+ `PackageTool`, `PackageRuntimeContext`, `defineCapability`,
696
+ `PackageFieldDefinition`, or `PackageWorkflowField`.
697
+
698
+ ### Connections and connectors
699
+
700
+ `PackageConnection` implementations own advertised `test` and `discover`
701
+ behavior. Declaration admission rejects metadata/method mismatches. The host
702
+ decodes credentials through the native schema sidecar once per operation,
703
+ injects package-declared capabilities, and passes the decoded credential value
704
+ to both test and discovery during a test-with-discovery run.
705
+ Connections created by a separate registration lifecycle declare
706
+ `creationMode: "registration_only"`. The default `self_service` mode permits
707
+ ordinary Organization connection creation.
708
+
709
+ A tool `connectionRefs` entry may set `catalogCollection` to the `key` of a
710
+ collection its connection's `discover` returns. Tool invocations then receive
711
+ that collection's resource ids as
712
+ `PackageRuntimeContext.connectionCatalogIds[slot]` (see
713
+ `@collective-intelligence/extensions-sdk-backend`).
714
+
715
+ `PackageKnowledgeConnector` implementations receive one decoded envelope containing
716
+ `settings`, exact named `connections`, and the operation `request`. Optional
717
+ `browse`, `discover`, `pull`, `push`, and `read` methods remain package-owned.
718
+ Open `contributions` identify package presentation/control integrations by FQN,
719
+ connection slot, connection template, capability, and portable JSON metadata;
720
+ hosts route those identities without provider-name unions or registries.
721
+ For inbound entity records, a connector may declare
722
+ `entityIdentityMode: "item_metadata"` when every page supplies validated item
723
+ identity metadata. The default `adapter` mode resolves a declared entity
724
+ adapter. The host applies the same identity validation to both modes.
725
+
726
+ Connector declarations may set `recommendedImportSchedules` for root bindings
727
+ created from discovered remote schemas. These are setup-wizard recommendations,
728
+ not install-time schedules; `predefinedSchedules` remains scoped to a static
729
+ schema capability and its `predefinedBindingKey`.
730
+
731
+ Connector declarations may set `remoteReference: { providerKey, urlTemplate }`
732
+ so hosts can label and link the remote records the connector imported.
733
+ `urlTemplate` must be an `https://` URL; its only placeholders are
734
+ `{remoteId}` (URI-component encoded) and `{remoteIdUuidHex}` (a UUID remote ID,
735
+ hyphens optional, as 32 lowercase hex digits). A remote ID that cannot fill
736
+ every placeholder gets no link. `renderKnowledgeRemoteReferenceUrl` renders a
737
+ template for one remote ID.
738
+
739
+ `declareDocumentsConnector` binds a zero-argument constructor that implements
740
+ `DocumentsConnectorImplementation`. Its `providerFamily` is an open, non-empty
741
+ provider identifier; the optional `providerDisplayName` names the provider in
742
+ reader links such as "Open in Google Drive", and hosts fall back to
743
+ `displayName` without it. `deltaPage` receives one concrete
744
+ `rootRemoteId`, the last committed opaque cursor (if any), and an optional
745
+ working continuation. It returns one page of file/folder upserts or removals
746
+ with a `next` token tagged `continuation` or `checkpoint`. Hosts persist a
747
+ checkpoint only after every page item and content fetch succeeds. The adapter
748
+ also implements `proveRootAncestry`, reading the remote provider to return the
749
+ root's ancestor IDs, canonical remote root ID, and a stable provider scope key
750
+ for comparing roots across separate credentials; browser-supplied ancestry is
751
+ not trusted. The proof also carries the selected root's provider-reported
752
+ `displayName` and `webUrl` when available; hosts must not construct a browser
753
+ URL from the remote ID. My Drive and `me:root` aliases resolve to provider-native IDs.
754
+ A provider's
755
+ expired cursor is reported with structural code `cursor_expired` so the host
756
+ can reconcile. For root selection the adapter also implements read-only
757
+ `listDrives({ cursor? })` and `listFolders({ parentRemoteId, cursor? })`, which
758
+ return `{ items, nextCursor? }` pages. A drive's `remoteId` is its root folder
759
+ id; drive and folder `remoteId`s are accepted as-is by `pull`,
760
+ `proveRootAncestry`, and `listFolders`. Folder pages list direct child folders
761
+ only, sorted by title, with `hasChildren` set only when the provider reports it
762
+ without an extra request. Existing `pull` receives
763
+ `{ cursor?, selectedRootRemoteIds? }` plus an erased host `context`, and
764
+ `fetchContent` receives `{ contentRevision, remoteFileId }` plus the same
765
+ `context` pattern used by tools and workflow nodes. The common SDK does not
766
+ import `PackageRuntimeContext` or provider clients; specialized runtimes resolve
767
+ connections from that context. Native schemas for pull/fetchContent are not
768
+ part of documents-connector admission.
769
+
770
+ The shared `DocumentsFetchedContent` result carries `bytes: Uint8Array` and,
771
+ when the provider reports them, the MIME type, extension, and filename of the
772
+ stored representation. A provider that exports a native file reports the export
773
+ format rather than the native source format. These fields remain optional for
774
+ connectors whose source cannot report them.
775
+
776
+ `DocumentsSource` carries `{ webUrl: string }`, the provider-reported browser
777
+ URL of the individual original live file. `DocumentsFetchedContent.source` and
778
+ `DocumentsDeltaItem.source` are optional and nullable: omission means the connector
779
+ has not observed source metadata, while `null` explicitly clears a previously
780
+ known destination. A delta item can update this metadata even when its content
781
+ revision is unchanged, without replacing immutable Version bytes. Existing
782
+ connectors can continue omitting the field.
783
+
784
+ Connectors may implement `fetchSource({ remoteFileId }, context)` to read
785
+ `DocumentsSource | null` without downloading content. Hosts can use this optional
786
+ hook to refresh existing imports or unchanged revisions even when no delta item
787
+ is emitted. A `null` result explicitly clears a previously known destination;
788
+ provider failures must fail the call rather than masquerade as a confirmed absence.
789
+ An omitted hook makes no new observation. The host supplies the same erased context
790
+ as `fetchContent`, whose public return type is `DocumentsFetchedContent`.
791
+
792
+ ```ts
793
+ import type {
794
+ DocumentsFetchedContent,
795
+ DocumentsDeltaItem
796
+ } from "@collective-intelligence/extensions-sdk"
797
+
798
+ const legacy: DocumentsFetchedContent = { bytes: new Uint8Array() }
799
+ const exported: DocumentsFetchedContent = {
800
+ bytes: new Uint8Array(),
801
+ filename: "Report.pdf",
802
+ mimeType: "application/pdf",
803
+ source: { webUrl: "https://provider.example/files/report" }
804
+ }
805
+ const unavailable: DocumentsDeltaItem = {
806
+ kind: "file",
807
+ remoteFileId: "report",
808
+ parentRemoteIds: ["root"],
809
+ title: "Report",
810
+ source: null
811
+ }
812
+ ```
813
+
814
+ The example destination stands for a URL returned by the provider. Never derive
815
+ one from a remote ID or substitute `DocumentsRootAncestry.webUrl`, which identifies
816
+ the selected collection root. Hosts authorize disclosure and validate URLs before
817
+ external opening. A source destination opens the live provider file; provider
818
+ login, access and editor support still apply, and it does not promise a historical
819
+ stored Version. Stored MIME type, extension, filename and bytes retain their
820
+ separate exported-representation semantics.
821
+
822
+ ### Knowledge adapter identity
823
+
824
+ Entity and relation adapter constructors, when used, must implement `remoteId(remote)`,
825
+ returning a string or `PromiseLike<string>`. This requirement also applies to
826
+ plain classes; using an executable SDK base class is optional. The provider owns
827
+ the stable, nonempty identity and any composite-key calculation. Mapping local
828
+ fields or relation endpoints does not supply identity implicitly.
829
+
830
+ Read identity from the remote record before mapping it. A local projection may
831
+ omit the source ID. Hosts invoke the declared `remoteId` operation and validate
832
+ its result before committing imported records; they do not assume a generic `id`
833
+ property. The method and its executable implementation remain outside serialized
834
+ manifests.
835
+
836
+ ### Dataset connectors
837
+
838
+ Dataset connectors expose a provider-neutral, JSON-only definition and a closed
839
+ query vocabulary: `records`, `aggregate`, and `time_series`. Every query returns
840
+ one bounded page with an opaque optional continuation cursor; consumers must
841
+ send that cursor back with the same logical command and exact definition
842
+ revision. Connectors advertise only the intents they implement and return the
843
+ typed `unsupported_operation` failure for an unsupported intent. Provider query
844
+ languages, credentials, policy decisions, and runtime principals never enter
845
+ these public contracts.
846
+
847
+ ### Organization SSO declarations
848
+
849
+ `declareOrganizationSso` binds a structurally admitted provider constructor to
850
+ portable `organizationSso` metadata: `providerId`, `connectionTemplateFqn`,
851
+ `requiredCredentialFields`, optional `secretCredentialFields`, and optional
852
+ `setupGuide` entries containing `locale` and `markdown`. It is an ordinary package
853
+ component, so presence and configuration participate in canonical declaration
854
+ identity. The implementation remains a runtime sidecar. Executable request and
855
+ context contracts belong to `extensions-sdk-backend` (`PackageOrganizationSso`);
856
+ this package has no host or Effect dependency.
857
+
858
+ ## Portable manifest admission
859
+
860
+ Hosts receiving untrusted portable JSON can call
861
+ `parsePackageManifest(value: unknown): PackageManifest`. It checks the v4
862
+ package envelope, all component kinds, hosted contribution metadata, and the
863
+ required, optional, and discriminated nested declaration fields. Invalid shapes
864
+ throw `TypeError` with the failing field path. The parser retains package-owned
865
+ JSON fields and open JSON Schema keywords without executing schemas or loading
866
+ runtime sidecars. It does not resolve dependencies, grant capabilities, or apply
867
+ host consumer-profile policy; those remain separate host checks.
868
+
869
+ Extension Release manifests use the current enum and primitive-kind spellings
870
+ and are read with `parseExtensionReleaseManifest(value)`. Use that parsed manifest
871
+ for runtime behavior and `validateExtensionReleaseArchiveMetadata` when
872
+ verifying the original archive bytes. Publication input uses the same strict
873
+ parser.
874
+
875
+ The returned manifest is a JSON copy. Sparse arrays are rejected before
876
+ serialization, including arrays nested in opaque JSON. FQNs must be non-empty;
877
+ hosted contribution FQNs and export names must also be trimmed, matching
878
+ `declareHostedContribution`. Namespace and version formats are not restricted.
879
+
880
+ Dashboard and Studio Hosted Contributions use one exact portable descriptor:
881
+ `contract: "frontend-catalog/v1"` and `exportName: "loadFrontendCatalog"`.
882
+ The exact package parser rejects older frontend leaf descriptors. Backend
883
+ contributions retain their own named exports.
884
+
885
+ Entity adapter declarations accept `entitySchemaFqn: "*"` for a connector-wide
886
+ fallback. Hosts prefer a unique exact schema match, then a unique wildcard;
887
+ ambiguous matches fail. Executable import normalization hooks are supplied by
888
+ `extensions-sdk-backend`; declare `normalizesImportedData: true` to enable their
889
+ post-field-map invocation. An omitted or false flag preserves import behavior for
890
+ releases built with older runtimes. The executable hook remains outside the
891
+ serialized manifest.
892
+ Declare `normalizesFieldMapValues: true` to let an adapter normalize each
893
+ provider value read by an inbound field-map rule before path, cast, or transform
894
+ handling. This leaves other providers' values untouched.
895
+
896
+ ## Exact dependencies and immutable release declarations
897
+
898
+ Package `dependencies` contain exact immutable references, with no version ranges:
899
+
900
+ ```ts
901
+ dependencies: [
902
+ {
903
+ fqn: "com.acme.base",
904
+ releaseDigest: "a".repeat(64), // lowercase SHA-256 of the release archive
905
+ releaseId: "release-base"
906
+ }
907
+ ]
908
+ ```
909
+
910
+ `declarePackage` and `parsePackageManifest` validate these pins, reject duplicate
911
+ package identities and sort dependencies by FQN without reordering caller arrays.
912
+ `parsePackageDependencyPins` exposes the same validation to host adapters.
913
+ `resolvePackageDependencyOrder` orders declarations by dependency FQN; authorization,
914
+ release availability and exact graph conflict checks remain host responsibilities.
915
+
916
+ New release builders retain the portable declarations in
917
+ `ExtensionReleaseManifest.packageManifest` and include their canonical JSON bytes
918
+ as the single reserved `package-manifest.json` archive entry. This binds declaration
919
+ and dependency changes into the archive digest even when runtime assets are unchanged.
920
+ The retained declarations must identify the same package FQN and version as the release.
921
+
922
+ After parsing the archive, call `validateExtensionReleaseArchiveMetadata(entries,
923
+ manifest)` to compare the archived bytes with the retained canonical declarations.
924
+ It rejects missing, duplicate or mismatched metadata and returns only runtime entries
925
+ for asset verification. The reserved entry cannot appear in the runtime asset inventory.
926
+ Historical releases without retained declarations remain readable only with their
927
+ original metadata-free archives; new publication requires retained declarations and
928
+ the canonical metadata entry at the publishing boundary.
929
+
930
+ Releases stored before primitive kinds became camelCase keep their published
931
+ bytes. Hosts verify such an archive against the stored manifest JSON verbatim,
932
+ then read it with `parseStoredExtensionReleaseManifest`, which maps each retired
933
+ kind (for example `tool_collection`) to its current spelling.
934
+ `withCurrentPrimitiveKinds` applies the same mapping to stored JSON without
935
+ parsing it. `parseExtensionReleaseManifest` and `parsePackageManifest` accept
936
+ only the current spelling.
937
+
938
+ ## Enum value spelling
939
+
940
+ Repository-owned enum values use lower `snake_case`. This includes dataset statuses, schema consumer profiles, and hosted contribution identity. Primitive component kinds are the exception: they use lower camelCase, for example `skillTemplate` and `toolCollection`. Notification enum values retain their existing spelling. External protocol values, including HTTP methods and JSON Schema keywords and formats, retain the protocol spelling.
941
+
942
+ ### Package-owned operation Gateways
943
+
944
+ Declare an operation-only Gateway as package metadata and reference it directly
945
+ from a Remote Tool collection. `buildOperationGatewayContract` takes the same
946
+ portable operation domains used by the server runtime and produces the complete
947
+ structural contract, including canonical operation references, protocol `2`,
948
+ installed-Organization binding, empty datasets/knowledge and disabled resources.
949
+ It sorts copied domain/operation lists by identifier without mutating the input.
950
+
951
+ ```ts
952
+ const gateway = declareExternalAppGateway({
953
+ manifest: { fqn: "com.example.gateways.nest", version: "1.0.0" },
954
+ presentation: { displayName: "Nest Gateway" },
955
+ definition: {
956
+ expectedContract: buildOperationGatewayContract({
957
+ id: "com.example.nest",
958
+ version: "1.0.0",
959
+ operationDomains
960
+ })
961
+ }
962
+ })
963
+
964
+ const tools = declareRemoteToolCollection({
965
+ manifest: { fqn: "com.example.tools.nest", version: "1.0.0" },
966
+ presentation: { displayName: "Nest tools" },
967
+ definition: {
968
+ gatewayRef: gateway, // An external declaration FQN is also accepted.
969
+ operationReferences: ["com.example.nest/greetings/greet@1.0.0"]
970
+ }
971
+ })
972
+ // Include both declarations in declarePackage({ components: [gateway, tools], ... }).
973
+ ```
974
+
975
+ The serialized `gatewayRef` is a declaration FQN. Each Gateway has its own
976
+ complete expected contract; multiple declarations can be included in one
977
+ package. Authoring and serialized admission reject unexpected Gateway fields,
978
+ runtime handlers, settings, credentials, endpoint fields, unsupported schema
979
+ projection fidelity and broader capabilities. Hashes and revisions are derived
980
+ from `canonicalJson(expectedContract)` by the consuming runtime; they are not
981
+ separate declared authority. Native validation and executable handlers stay in
982
+ the application runtime. Deployment URLs are supplied to deployment, outside
983
+ immutable release metadata.
984
+
985
+ `gatewayRef` and exact versioned `operationReferences` are the sole collection
986
+ binding contract. Obsolete `connectionRef` metadata is rejected at authoring and
987
+ release admission.
988
+
989
+ The [Nest declaration example](../../../demo/external-app-nest/apps/extensions/src/index.ts) shares this catalog with its detached runtime. [Exact deployment](../../../docs/reference/package-release-cli.md#deploy-an-exact-package-and-its-declared-gateways) supplies endpoint bindings, separate publisher/Organization credentials and bounded operation following.
990
+
991
+ ## Concrete connector configuration
992
+
993
+ `declareKnowledgeConnectorInstance` and `declareDatasetConnectorInstance` declare
994
+ JSON configuration for the existing executable connector/provider. The helpers
995
+ use `manifest`, `presentation`, and `definition`; they add no runtime implementation
996
+ or schema sidecar. References resolve within the package or its exact pinned
997
+ release dependencies at installation. Every bundle requires
998
+ `lifecycle: { deployMode: "init_only" | "upsert", readonly: boolean }`.
999
+ `init_only` creates absent configuration and preserves existing content; `upsert`
1000
+ reconciles owned content through baseline/live merge. `readonly` governs manual
1001
+ configuration edits across the bundle. Child bindings, pipelines, schedules and
1002
+ policies share that lifecycle; runtime data, cursors and authorized execution are
1003
+ separate.
1004
+
1005
+ ```ts
1006
+ import {
1007
+ declareKnowledgeConnectorInstance,
1008
+ declareDatasetConnectorInstance,
1009
+ declarePackage
1010
+ } from "@collective-intelligence/extensions-sdk"
1011
+
1012
+ const customers = declareKnowledgeConnectorInstance({
1013
+ manifest: { fqn: "com.acme.sales.instances.customers", version: "1.0.0" },
1014
+ presentation: { displayName: "CRM customers" },
1015
+ definition: {
1016
+ templateFqn: "com.acme.integrations.crm",
1017
+ lifecycle: { deployMode: "upsert", readonly: false },
1018
+ enabled: true,
1019
+ connections: { crm: { setupKey: "crm" } },
1020
+ entityBindings: [
1021
+ {
1022
+ key: "customers",
1023
+ schemaFqn: "com.acme.sales.customer",
1024
+ bindingMode: "managed",
1025
+ remoteCollectionId: "customers",
1026
+ fieldMap: [
1027
+ {
1028
+ op: "path",
1029
+ remote: "name",
1030
+ local: "name",
1031
+ direction: "inbound",
1032
+ skipIfNull: false
1033
+ }
1034
+ ]
1035
+ }
1036
+ ],
1037
+ pipelines: [
1038
+ {
1039
+ key: "nightly",
1040
+ definition: {
1041
+ steps: [{ tasks: [{ kind: "entity", bindingKey: "customers" }] }]
1042
+ },
1043
+ schedules: [
1044
+ {
1045
+ key: "nightly_delta",
1046
+ cronExpression: "0 2 * * *",
1047
+ timezone: "Europe/Rome",
1048
+ importMode: "delta",
1049
+ enabled: true
1050
+ }
1051
+ ]
1052
+ }
1053
+ ],
1054
+ dataPolicies: [
1055
+ {
1056
+ fqn: "com.acme.sales.policies.customer_read",
1057
+ targetKind: "entity_schema",
1058
+ targetFqn: "com.acme.sales.customer",
1059
+ policyType: "filter",
1060
+ effect: "allow",
1061
+ policyBody: {
1062
+ subjectMatch: {
1063
+ op: "eq",
1064
+ left: { kind: "subject", path: ["user", "id"] },
1065
+ right: {
1066
+ kind: "literal",
1067
+ value: "7f824c46-54f3-41aa-b0b5-3951fabf952a"
1068
+ }
1069
+ },
1070
+ rule: { op: "const", value: true }
1071
+ }
1072
+ }
1073
+ ]
1074
+ }
1075
+ })
1076
+ const orders = declareDatasetConnectorInstance({
1077
+ manifest: { fqn: "com.acme.sales.instances.orders", version: "1.0.0" },
1078
+ presentation: { displayName: "Warehouse orders" },
1079
+ definition: {
1080
+ lifecycle: { deployMode: "init_only", readonly: false },
1081
+ bindingMode: "external",
1082
+ providerFqn: "com.acme.integrations.warehouse",
1083
+ connection: { setupKey: "warehouse" },
1084
+ sourceLocation: {
1085
+ segments: [
1086
+ { kind: "container", opaqueId: "sales", label: "Sales" },
1087
+ { kind: "dataset", opaqueId: "table:orders", label: "Orders" }
1088
+ ]
1089
+ },
1090
+ schedules: [
1091
+ {
1092
+ key: "health",
1093
+ action: "health",
1094
+ cronExpression: "0 * * * *",
1095
+ timezone: "UTC"
1096
+ }
1097
+ ],
1098
+ dataPolicy: {
1099
+ principals: [
1100
+ { kind: "user", id: "7f824c46-54f3-41aa-b0b5-3951fabf952a" }
1101
+ ],
1102
+ allowedOperations: ["describe", "records"],
1103
+ allowedFields: ["id", "total"],
1104
+ maxRows: 1000,
1105
+ maxBytes: 1048576,
1106
+ maxTimeoutMs: 30000
1107
+ }
1108
+ }
1109
+ })
1110
+ export default declarePackage({
1111
+ manifest: {
1112
+ fqn: "com.acme.sales",
1113
+ name: "Acme Sales",
1114
+ version: "1.0.0",
1115
+ dependencies: [
1116
+ {
1117
+ fqn: "com.acme.integrations",
1118
+ releaseId: "exact-release-id",
1119
+ releaseDigest: "a".repeat(64)
1120
+ }
1121
+ ]
1122
+ },
1123
+ components: [customers, orders]
1124
+ })
1125
+ ```
1126
+
1127
+ Use your actual exact dependency release, executable/schema FQNs, source location,
1128
+ and authorized Organization reader UUID. Knowledge policies use the native
1129
+ `{ subjectMatch, rule? }` AST, including recursive comparisons and logical
1130
+ predicates. The old `{ version, rules }` shape is rejected. Schema/domain targets
1131
+ cover all sources. Dataset grants use existing user/service principals and native
1132
+ operations, fields, `sensitiveFields`, row filters and budgets.
1133
+
1134
+ Knowledge settings retain `{ type: "inline" | "linked", value }` entries;
1135
+ `remoteFilters` retain native `mode` and `selected_ids`. Binding `parentKey`,
1136
+ relation `sourceEntityKey`/`targetEntityKey`, pipeline `bindingKey`, and schedule
1137
+ `key` are stable local references. Pipeline budgets and mode overrides retain
1138
+ native semantics. Managed Datasets require `definition: DatasetDefinition` and
1139
+ may specify an existing `templateFqn`/`templateConfig`; External Datasets require
1140
+ `sourceLocation` and may retain a native `sourceMapping`.
1141
+
1142
+ ### Concrete Managed and External Datasets
1143
+
1144
+ Install the existing provider packages in the target Organization, or pin their
1145
+ exact releases as package dependencies. This example uses the built-in PostgreSQL
1146
+ provider/table template and the shipped Microsoft Fabric provider. Replace the
1147
+ Fabric workspace/item IDs, admitted field IDs and reader UUID with real values;
1148
+ use the provider's readiness, source discovery and definition admission results.
1149
+ An existing Fabric Entra connection is supplied separately through setup.
1150
+
1151
+ ```ts
1152
+ import {
1153
+ declareDatasetConnectorInstance,
1154
+ declarePackage
1155
+ } from "@collective-intelligence/extensions-sdk"
1156
+
1157
+ const ungrantedRecords = declareDatasetConnectorInstance({
1158
+ manifest: { fqn: "com.acme.datasets.records", version: "1.0.0" },
1159
+ presentation: { displayName: "Private records" },
1160
+ definition: {
1161
+ lifecycle: { deployMode: "init_only", readonly: false },
1162
+ bindingMode: "managed",
1163
+ providerFqn: "builtin.core.datasets.providers.postgres",
1164
+ templateFqn: "builtin.core.datasets.templates.generic-table",
1165
+ settings: {},
1166
+ definition: {
1167
+ version: 1,
1168
+ fields: [{ id: "id", name: "ID", type: "string", nullable: false }],
1169
+ measures: [],
1170
+ relationships: []
1171
+ }
1172
+ }
1173
+ })
1174
+ const fabricOrders = declareDatasetConnectorInstance({
1175
+ manifest: { fqn: "com.acme.datasets.fabric-orders", version: "1.0.0" },
1176
+ presentation: { displayName: "Fabric orders" },
1177
+ definition: {
1178
+ lifecycle: { deployMode: "upsert", readonly: true },
1179
+ bindingMode: "external",
1180
+ providerFqn:
1181
+ "builtin.integrations.microsoft-fabric.dataset-providers.fabric",
1182
+ connection: { setupKey: "fabric" },
1183
+ settings: {},
1184
+ sourceLocation: {
1185
+ segments: [
1186
+ { kind: "container", opaqueId: "workspace-id", label: "Sales" },
1187
+ { kind: "dataset", opaqueId: "semantic_model:item-id", label: "Orders" }
1188
+ ]
1189
+ },
1190
+ dataPolicy: {
1191
+ principals: [
1192
+ { kind: "user", id: "7f824c46-54f3-41aa-b0b5-3951fabf952a" }
1193
+ ],
1194
+ allowedOperations: ["describe", "records"],
1195
+ allowedFields: ["admitted-order-id-field"],
1196
+ maxRows: 100,
1197
+ maxBytes: 1048576,
1198
+ maxTimeoutMs: 30000
1199
+ },
1200
+ schedules: [
1201
+ {
1202
+ key: "health",
1203
+ action: "health",
1204
+ cronExpression: "0 * * * *",
1205
+ timezone: "UTC",
1206
+ enabled: true
1207
+ },
1208
+ {
1209
+ key: "definition",
1210
+ action: "refresh_definition",
1211
+ cronExpression: "0 2 * * *",
1212
+ timezone: "UTC",
1213
+ enabled: true
1214
+ }
1215
+ ]
1216
+ }
1217
+ })
1218
+ export default declarePackage({
1219
+ manifest: {
1220
+ fqn: "com.acme.datasets",
1221
+ name: "Acme Datasets",
1222
+ version: "1.0.0"
1223
+ },
1224
+ components: [ungrantedRecords, fabricOrders]
1225
+ })
1226
+ ```
1227
+
1228
+ The Managed declaration omits `dataPolicy`: a newly package-created Dataset grants
1229
+ query access to nobody, including the deploying actor. Explicit policies grant
1230
+ only the listed users/services and retain their field, operation, filter and
1231
+ budget bounds. Omission is not an instruction to erase protected adopted/manual
1232
+ grants; existing resources follow the selected lifecycle and preservation rules.
1233
+
1234
+ Installation configures empty Managed backing or admits a live External binding;
1235
+ it does not ingest business rows or trigger projection backfill. Managed file or
1236
+ batch ingestion remains an explicitly authorized manual action. Declare health
1237
+ and definition-refresh schedules only for External Datasets. Refresh discovery
1238
+ retains the active revision and policy until explicit validated review; it does
1239
+ not silently widen fields or permissions. Gateway-backed External sources also
1240
+ require their existing manifest approval; package installation grants no approval.
1241
+
1242
+ For the connection above, a private setup file contains:
1243
+
1244
+ ```json
1245
+ {
1246
+ "connections": {
1247
+ "fabric": { "connectionId": "0197f8ec-151c-7000-8000-000000000001" }
1248
+ }
1249
+ }
1250
+ ```
1251
+
1252
+ The UUID must identify the authorized existing Fabric connection in the target
1253
+ Organization. Keep credentials and provider tokens out of the declaration.
1254
+
1255
+ Supply connection credentials and optional explicit adoption in a separate setup
1256
+ file, outside immutable release bytes:
1257
+
1258
+ ```json
1259
+ {
1260
+ "connections": {
1261
+ "crm": { "connectionId": "2a4cb90a-0e00-4384-8a78-d5279fbb3a77" },
1262
+ "warehouse": {
1263
+ "newConnection": { "name": "Warehouse production", "fields": {} }
1264
+ }
1265
+ },
1266
+ "adoptions": {
1267
+ "com.acme.sales.instances.customers": {
1268
+ "instanceId": "42e62b11-1297-4ad3-ae87-19e6cc5b458d"
1269
+ }
1270
+ }
1271
+ }
1272
+ ```
1273
+
1274
+ Fill `fields` with the native connection template's required credentials.
1275
+ `connectionId` must match the Organization and expected template. The backend
1276
+ validates ownership, executable references and native configuration. Installation
1277
+ configures resources; native schedules and authorized manual actions execute work.