@collective-intelligence/extensions-sdk 0.0.0-stage → 0.1.0
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.
- package/README.md +1276 -2
- package/dist/components/agents.d.ts +155 -0
- package/dist/components/authoring-core.d.ts +253 -0
- package/dist/components/base.d.ts +25 -0
- package/dist/components/catalog.d.ts +21 -0
- package/dist/components/connections.d.ts +52 -0
- package/dist/components/connector-instances.d.ts +142 -0
- package/dist/components/connectors.d.ts +408 -0
- package/dist/components/dataset-parser-validation.d.ts +2 -0
- package/dist/components/dataset-parser.d.ts +74 -0
- package/dist/components/datasets.d.ts +356 -0
- package/dist/components/declaration.d.ts +12 -0
- package/dist/components/executable-authoring.d.ts +27 -0
- package/dist/components/external-app-gateway.d.ts +7 -0
- package/dist/components/external-application.d.ts +17 -0
- package/dist/components/fields.d.ts +34 -0
- package/dist/components/knowledge-remote-reference.d.ts +7 -0
- package/dist/components/knowledge.d.ts +188 -0
- package/dist/components/lifecycle.d.ts +7 -0
- package/dist/components/metadata-authoring.d.ts +66 -0
- package/dist/components/notification-channel-capabilities.d.ts +7 -0
- package/dist/components/remote-tool-collection.d.ts +3 -0
- package/dist/components/studio.d.ts +48 -0
- package/dist/components/templates.d.ts +50 -0
- package/dist/components/tools.d.ts +138 -0
- package/dist/components/workflow-editor.d.ts +28 -0
- package/dist/components/workflow-node-authoring.d.ts +4 -0
- package/dist/components/workflow-ports.d.ts +26 -0
- package/dist/components/workflow-results.d.ts +75 -0
- package/dist/components/workflow-rules.d.ts +20 -0
- package/dist/components/workflow-schema.d.ts +22 -0
- package/dist/components/workflows.d.ts +529 -0
- package/dist/foundation/json.d.ts +8 -0
- package/dist/foundation/string-order.d.ts +2 -0
- package/dist/gateway/declarations.d.ts +69 -0
- package/dist/gateway/operation-contract.d.ts +29 -0
- package/dist/hosted/contributions.d.ts +52 -0
- package/dist/index.d.ts +69 -0
- package/dist/index.js +1 -0
- package/dist/package/canonical.d.ts +9 -0
- package/dist/package/connector-readers.d.ts +171 -0
- package/dist/package/definition.d.ts +31 -0
- package/dist/package/dependencies.d.ts +10 -0
- package/dist/package/instance-readers.d.ts +4 -0
- package/dist/package/knowledge-readers.d.ts +137 -0
- package/dist/package/manifest.d.ts +42 -0
- package/dist/package/parse-manifest.d.ts +3 -0
- package/dist/package/policy-readers.d.ts +17 -0
- package/dist/package/presentation-readers.d.ts +61 -0
- package/dist/package/primitive-readers.d.ts +678 -0
- package/dist/package/readers.d.ts +230 -0
- package/dist/package/template-readers.d.ts +37 -0
- package/dist/package/workflow-readers.d.ts +167 -0
- package/dist/release/archive.d.ts +11 -0
- package/dist/release/manifest.d.ts +66 -0
- package/dist/release/paths.d.ts +5 -0
- package/dist/release/stored-manifest.d.ts +13 -0
- package/dist/schema/forms.d.ts +117 -0
- package/dist/schema/knowledge-record.d.ts +16 -0
- package/dist/schema/normalization.d.ts +7 -0
- package/dist/schema/profiles.d.ts +45 -0
- package/dist/schema/projection.d.ts +59 -0
- package/dist/schema/source.d.ts +65 -0
- package/package.json +46 -4
package/README.md
CHANGED
|
@@ -1,3 +1,1277 @@
|
|
|
1
|
-
#
|
|
1
|
+
# `@collective-intelligence/extensions-sdk`
|
|
2
2
|
|
|
3
|
-
|
|
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.
|