@collective-intelligence/extensions-sdk 0.1.9 → 0.1.10

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 CHANGED
@@ -89,6 +89,8 @@ capability, or `extractPage`. Package manifests use `apiVersion` `v4`.
89
89
 
90
90
  Workflow trigger node contracts can declare `triggerActivation`. Use
91
91
  `{ kind: "manual" }` or `{ kind: "schedule" }` for those activation categories.
92
+ A schedule trigger's backend implementation supplies its provider-neutral
93
+ schedule through `PackageWorkflowScheduleTrigger` in `extensions-sdk-backend`.
92
94
  Event triggers use `{ kind: "event", eventIngress }`, where `eventIngress`
93
95
  names the event kind, acquisition mode, exact listener FQN/version,
94
96
  required-listener policy, and JSON-only selector projections. Each selector
@@ -322,6 +324,16 @@ export default declarePackage({
322
324
  })
323
325
  ```
324
326
 
327
+ A tool `execute` may return its output, or a `ToolResultWithDisplay<Output>`
328
+ that carries `ToolDisplayPart` values next to the
329
+ output. A part is `{ type, data, title?, description?, metadata? }` with JSON
330
+ `data`; hosts show parts to the user and never send them to the model. The
331
+ declared `output` schema still encodes `output`. Build the result with
332
+ `withDisplayParts` from `@collective-intelligence/extensions-sdk-backend`.
333
+ The result requires the exported `toolResultBrand` symbol; an unbranded
334
+ `{ output, displayParts }` object remains ordinary output, subject to the
335
+ [reserved wire-envelope marker](../extensions-sdk-backend/README.md) limitation.
336
+
325
337
  Every source implements Standard Schema V1 validation and Standard JSON Schema
326
338
  V1 projection. Validation and encoding may be asynchronous; projection and
327
339
  manifest construction are synchronous. Output declaration positions require a
@@ -361,7 +373,7 @@ independent of relation record `localMutationPolicy`.
361
373
  `declareWorkflowTemplate` require per-item `LifecycleOptions`:
362
374
  `{ deployMode: "upsert" | "init_only", readonly: boolean }`. Entity schemas
363
375
  also require the persisted Organization entity schema capabilities other than
364
- relation schemas and parked `relationFields`: `autocompleteConfiguration`,
376
+ relation schemas: `autocompleteConfiguration`,
365
377
  `displayNameExpression`, `embeddingConfig`, `persistFullFieldContributions`,
366
378
  `usableAsDocumentScope`, and `versioningEnabled`. Domain declarations require
367
379
  `versioningEnabled`. External applications require `applicationType`,
@@ -403,6 +415,53 @@ rejects a raw `fieldSemantics` `file` entry, a `mediaVisibility` on a pointer
403
415
  that is not a declared File field (relation schemas have none), and a File field
404
416
  with both `visibility` and a raw `mediaVisibility`.
405
417
 
418
+ ### Relation fields
419
+
420
+ An entity schema declares an Entity Relation Field as
421
+ `fieldSemantics["/<key>"].relation`, typed `KnowledgeEntityRelationField`. Its
422
+ value holds Entity References to entities of exactly one target schema of the
423
+ same Organization:
424
+
425
+ ```ts
426
+ fieldSemantics: {
427
+ "/companies": {
428
+ relation: {
429
+ targetSchemaFqn: "core.schemas.crm.company",
430
+ cardinality: "many",
431
+ maxItems: 20,
432
+ onDelete: "restrict",
433
+ display: { fields: [{ field: "name", scope: "data" }] },
434
+ autocomplete: {
435
+ fields: [{ field: "name", scope: "data" }],
436
+ baseFilters: [{ field: "status", operator: "eq", value: "active" }]
437
+ }
438
+ }
439
+ }
440
+ }
441
+ ```
442
+
443
+ `cardinality` is `one` or `many`. `maxItems` is an optional positive item limit
444
+ of a `many` field; without it the field has no limit. `onDelete` is `clear` or
445
+ `restrict`; the platform applies `clear` when it is absent. `display.fields`
446
+ and `autocomplete.fields` name `{ field, scope: "data" | "entity" }` fields of
447
+ the target schema; `autocomplete.baseFilters` are ANDed schema-aware filters
448
+ `{ field, operator, value, caseSensitive? }` that limit the selectable targets.
449
+ The schema does not define the property: the platform generates its value
450
+ schema at install. Localization, presentation and semantics pointers may address
451
+ the relation field. Declaration rejects a relation entry whose pointer is not a
452
+ top-level property, a relation entry on a File field, and any relation entry on
453
+ a relation schema. Package deploy resolves `targetSchemaFqn` among the entity
454
+ schemas of the Organization. The metadata-only `relationFields` declaration
455
+ is removed; manifest parsing refuses a release that still declares it.
456
+
457
+ The host rejects `onDelete: "restrict"` for targets with `managedProjection`
458
+ and for `core.schemas.directory.organization` and
459
+ `core.schemas.strategy.organization-context`; use `clear` for these targets.
460
+ This check also applies to effective same-release declarations and to incoming
461
+ references when a target becomes managed. Ordinary target schemas may still use
462
+ `restrict`. Physical deletion clears references under `clear`; logical deletion
463
+ preserves them and does not grant access to the archived target.
464
+
406
465
  ## Agent and Skill declarations
407
466
 
408
467
  `declareSkill` declares a governed Skill: `instructions`, the `tools` it
@@ -979,12 +1038,7 @@ layout, create-step, and update-section metadata.
979
1038
 
980
1039
  ### Gateway declaration vocabulary
981
1040
 
982
- General knowledge entity schemas may retain an explicitly declared source
983
- reference as an `EntityRelationField`; its `field` is a canonical RFC 6901
984
- instance pointer and is checked against the projected entity schema with the
985
- other field metadata. This schema vocabulary is not gateway manifest input.
986
-
987
- The SDK also exports the JSON-only `PortableOperationDeclaration`,
1041
+ The SDK exports the JSON-only `PortableOperationDeclaration`,
988
1042
  `OperationDomainDeclaration`, and `PortableGatewayDeclarations` types. They
989
1043
  establish the shared operation manifest input vocabulary. Every portable
990
1044
  operation explicitly carries its effect class, idempotency and bounded retry
@@ -1151,6 +1205,40 @@ the guard. They apply to ID targets too.
1151
1205
  The core Invoke Workflow node exposes the same choice through its `target`
1152
1206
  (a selected Workflow) and `targetFqn` configuration; set exactly one.
1153
1207
 
1208
+ ### Tool settings option context
1209
+
1210
+ `ToolSettingsOptionsContext` contains only serializable values resolved by the
1211
+ Host before invoking an options provider. The optional `imageModelOptions`
1212
+ projection contains eligible image-output model IDs and human labels. Labels
1213
+ include the provider name when it distinguishes catalog entries. A missing
1214
+ projection supplies no image choices; packages must not infer eligibility from
1215
+ vision input or choose a replacement default.
1216
+
1217
+ The Host owns catalog authorization and model readiness. Portable options code
1218
+ can search and page this projection but receives no database access, service
1219
+ container, provider credentials or Host capability through it. Options execution
1220
+ keeps Host capabilities unavailable. The callback that fills the projection is
1221
+ a Host runtime binding; it is never portable declaration or manifest data.
1222
+
1223
+ ### Built-in code runtimes
1224
+
1225
+ Every deployment seeds the built-in code runtimes under the same ids, so a
1226
+ package Workflow's core Code Block node names one through
1227
+ `builtInCodeRuntimeIds` instead of a per-deployment id:
1228
+
1229
+ ```ts
1230
+ import { builtInCodeRuntimeIds } from "@collective-intelligence/extensions-sdk"
1231
+
1232
+ const parseNews = {
1233
+ language: "javascript",
1234
+ runtimeId: builtInCodeRuntimeIds.node24,
1235
+ source: "result = { items: [] }"
1236
+ }
1237
+ ```
1238
+
1239
+ `node24` runs JavaScript on Node.js 24 and `python312` runs Python 3.12. The
1240
+ runtime language must match the node's `language`.
1241
+
1154
1242
  ## Executable implementations
1155
1243
 
1156
1244
  The common declaration helpers accept structural implementation constructors,
@@ -1328,15 +1416,20 @@ portable `emailProvider` metadata: `connectionTemplateFqn` and `senderKind`.
1328
1416
  `connectionTemplateFqn` names the connection template whose credential form
1329
1417
  shapes the provider credentials. `senderKind` is `mailbox` for a provider that
1330
1418
  always sends from a real mailbox, and `address` for every other provider.
1331
- The optional `deploymentIdentity: "aws"` declares that the tenant may use the
1332
- deployment's own cloud identity instead of stored credentials; the host then
1333
- passes temporary `accessKeyId`, `secretAccessKey`, `sessionToken`, and `region`
1334
- as the credentials. An organization never uses it.
1419
+ The optional `deploymentIdentity: "aws" | "azure"` declares which installation
1420
+ identity the provider accepts for a tenant sender. The host authorizes the
1421
+ selection and supplies temporary AWS credentials or binds the backend SDK's
1422
+ `packageEmailToken` capability to the approved Azure resource. The declaration
1423
+ does not grant identity access or contain a tenant ID, client ID, token, or token
1424
+ file path. Organization senders use their authorized connection.
1335
1425
  Declaration and portable manifest admission both reject an empty
1336
1426
  `connectionTemplateFqn`, any other `senderKind`, and any other
1337
1427
  `deploymentIdentity`. The implementation remains a
1338
- runtime sidecar. Executable send and failure contracts belong to
1339
- `extensions-sdk-backend` (`PackageEmailProvider`).
1428
+ runtime sidecar. Network-free preparation, delivery attempts, acceptance,
1429
+ failure, replay, quota, and token capability contracts belong to
1430
+ [`extensions-sdk-backend`](../extensions-sdk-backend/README.md#email-providers).
1431
+ Keep provider protocol policy in the implementation; the declaration introduces
1432
+ no provider registry or credential acquisition behavior.
1340
1433
 
1341
1434
  ## Portable manifest admission
1342
1435
 
@@ -1376,25 +1469,39 @@ Declare `normalizesFieldMapValues: true` to let an adapter normalize each
1376
1469
  provider value read by an inbound field-map rule before path, cast, or transform
1377
1470
  handling. This leaves other providers' values untouched.
1378
1471
 
1379
- ## Exact dependencies and immutable release declarations
1472
+ ## FQN dependencies and immutable release declarations
1380
1473
 
1381
- Package `dependencies` contain exact immutable references, with no version ranges:
1474
+ Package `dependencies` contain only package identities:
1382
1475
 
1383
1476
  ```ts
1384
- dependencies: [
1385
- {
1386
- fqn: "com.acme.base",
1387
- releaseDigest: "a".repeat(64), // lowercase SHA-256 of the release archive
1388
- releaseId: "release-base"
1389
- }
1390
- ]
1477
+ dependencies: [{ fqn: "com.acme.base" }]
1391
1478
  ```
1392
1479
 
1393
- `declarePackage` and `parsePackageManifest` validate these pins, reject duplicate
1394
- package identities and sort dependencies by FQN without reordering caller arrays.
1395
- `parsePackageDependencyPins` exposes the same validation to host adapters.
1396
- `resolvePackageDependencyOrder` orders declarations by dependency FQN; authorization,
1397
- release availability and exact graph conflict checks remain host responsibilities.
1480
+ `declarePackage`, `parsePackageManifest` and `parsePackageDependencies` reject
1481
+ `releaseId`, `releaseDigest`, duplicate FQNs and unknown dependency fields, and
1482
+ sort requirements by FQN without reordering caller arrays. `PackageDependency`
1483
+ is the portable `{ fqn: string }` type. `resolvePackageDependencyOrder` orders
1484
+ local declarations by their FQN requirements.
1485
+
1486
+ Every new install or update chooses the catalog's latest eligible dependency
1487
+ release for the target organization, using promotion order rather than semantic
1488
+ version order. An older automatically installable dependency is updated. A
1489
+ missing or different manual prerequisite blocks the operation. The backend
1490
+ retains exact selected IDs/digests in its accepted operation plan, so retries
1491
+ keep their accepted selections while a new invocation evaluates latest again.
1492
+ Builds stay offline; the SDK and CLI do not query dependency versions at build time.
1493
+
1494
+ Existing pinned installations require the [staged bridge-release cutover](../../../docs/reference/package-release-cli.md#cut-over-existing-pinned-installations)
1495
+ before strict Host rollout. Rebuilding and republishing alone cannot update old
1496
+ Desired/Serving manifests in place; normal uninstall retains their provenance.
1497
+ Bridge releases use the same components and empty dependencies under the old
1498
+ Host, followed by final FQN-only releases. Historical immutable archives and
1499
+ organization data are not rewritten or reset.
1500
+
1501
+ Existing concrete deployment checks still apply to catalog selections. A later
1502
+ promotion can select a lower semantic version, but strict deployment refuses that
1503
+ downgrade and preserves the installed selection. It reports the blocker instead
1504
+ of silently falling back to another release.
1398
1505
 
1399
1506
  New release builders retain the portable declarations in
1400
1507
  `ExtensionReleaseManifest.packageManifest` and include their canonical JSON bytes
@@ -1686,6 +1793,49 @@ native semantics. Managed Datasets require `definition: DatasetDefinition` and
1686
1793
  may specify an existing `templateFqn`/`templateConfig`; External Datasets require
1687
1794
  `sourceLocation` and may retain a native `sourceMapping`.
1688
1795
 
1796
+ Two binding `fieldMap` rules fill Entity Relation Fields. A `reference` rule
1797
+ stores the remote ids at `remote` as Entity References to the entities of the
1798
+ target binding of the same connector instance. An `embedded` rule maps each
1799
+ nested object at `remote` through its own `fieldMap` into an entity of the
1800
+ target binding, creates it only when no entity has the remote id at `remoteId`,
1801
+ and stores Entity References to the result:
1802
+
1803
+ ```ts
1804
+ fieldMap: [
1805
+ {
1806
+ op: "reference",
1807
+ local: "companies",
1808
+ remote: "associations.companies.results[].id",
1809
+ direction: "inbound",
1810
+ skipIfNull: true
1811
+ },
1812
+ {
1813
+ op: "embedded",
1814
+ local: "owner",
1815
+ remote: "creator",
1816
+ remoteId: "id",
1817
+ target: "contacts",
1818
+ fieldMap: [
1819
+ {
1820
+ op: "path",
1821
+ local: "email",
1822
+ remote: "email",
1823
+ direction: "inbound",
1824
+ skipIfNull: true
1825
+ }
1826
+ ],
1827
+ direction: "inbound",
1828
+ skipIfNull: true
1829
+ }
1830
+ ]
1831
+ ```
1832
+
1833
+ `remote` is dot-separated keys, each optionally indexed (`results[0]`), with at
1834
+ most one `[]` segment that projects every array item. `target` is the binding
1835
+ key of the target schema; configuration validation requires it when the
1836
+ connector binds the target schema more than once. Manifest parsing refuses an
1837
+ `embedded` rule whose `fieldMap` holds another `embedded` rule.
1838
+
1689
1839
  ### Concrete Managed and External Datasets
1690
1840
 
1691
1841
  Install the existing provider packages in the target Organization, or pin their
@@ -7,7 +7,7 @@ import type { PackagePrimitiveKind } from "./base.js";
7
7
  import type { DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrivesPage, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, EmailProviderDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration, KnowledgeRelationAdapterDeclaration } from "./connectors.js";
8
8
  import type { PackagePrimitiveDeclaration } from "./declaration.js";
9
9
  import type { FieldOption, FieldOptionPage } from "./fields.js";
10
- import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
10
+ import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolDeclaration, ToolResultWithDisplay, ToolSettingsOptionsDeclaration } from "./tools.js";
11
11
  import type { WorkflowEditorOverrides, WorkflowFieldDeclaration, WorkflowFieldContract, WorkflowNodeContract, WorkflowNodePortDeclaration, WorkflowNodeDeclaration, WorkflowOutputChannelDeclaration, WorkflowPortSchemaResolution } from "./workflows.js";
12
12
  /** Identity is the only data stored in an executable component manifest. */
13
13
  export type ComponentManifest = Readonly<{
@@ -62,7 +62,7 @@ export type ClassDeclaration<Manifest, Constructor extends new () => object, Def
62
62
  }>;
63
63
  export type Awaitable<Value> = PromiseLike<Value> | Value;
64
64
  export type ToolImplementation<Input, Output> = Readonly<{
65
- execute(input: Input, context: unknown): Awaitable<Output>;
65
+ execute(input: Input, context: unknown): Awaitable<Output | ToolResultWithDisplay<Output>>;
66
66
  }>;
67
67
  export type ConnectionImplementation<Credentials> = Readonly<{
68
68
  discover?(credentials: Credentials, context: unknown): unknown;
@@ -231,6 +231,30 @@ export type KnowledgeConnectorFieldMapRule = ConnectorFieldMapRuleBase & (Readon
231
231
  op: "transform";
232
232
  remote: string;
233
233
  transformerId: string;
234
+ }> | Readonly<{
235
+ /**
236
+ * Stores the remote ids at `remote` as Entity References to the
237
+ * entities of the target binding; a `[]` segment projects every
238
+ * array item, as in `associations.companies.results[].id`.
239
+ */
240
+ op: "reference";
241
+ remote: string;
242
+ /** The target binding key; required when the connector binds the target schema more than once. */
243
+ target?: string;
244
+ }> | Readonly<{
245
+ /**
246
+ * Maps each nested object at `remote` through `fieldMap` into an
247
+ * entity of the target binding, created only when no entity has the
248
+ * remote id at `remoteId`, and stores Entity References to them. The
249
+ * nested field map holds no further `embedded` rule.
250
+ */
251
+ fieldMap: readonly Exclude<KnowledgeConnectorFieldMapRule, Readonly<{
252
+ op: "embedded";
253
+ }>>[];
254
+ op: "embedded";
255
+ remote: string;
256
+ remoteId: string;
257
+ target?: string;
234
258
  }>);
235
259
  export type KnowledgeConnectorBindingExtraConfig = Readonly<{
236
260
  displayName: string | null;
@@ -463,8 +487,10 @@ export type EmailProviderDeclaration = PackagePrimitiveBase<"emailProvider"> & R
463
487
  * The cloud identity of the deployment that the tenant may use instead of
464
488
  * stored credentials. For `aws`, the host passes temporary `accessKeyId`,
465
489
  * `secretAccessKey`, `sessionToken`, and `region` as the credentials.
490
+ * Azure token authority is Host-bound at execution; tokens never enter
491
+ * this portable declaration or persisted credentials.
466
492
  */
467
- deploymentIdentity?: "aws";
493
+ deploymentIdentity?: "aws" | "azure";
468
494
  /** `mailbox` always sends from a real mailbox; `address` is every other provider. */
469
495
  senderKind: "address" | "mailbox";
470
496
  }>;
@@ -48,6 +48,7 @@ export type KnowledgeFieldSemantics = Readonly<{
48
48
  */
49
49
  mediaVisibility?: "private" | "protected" | "public";
50
50
  queryGuidance?: string;
51
+ relation?: KnowledgeEntityRelationField;
51
52
  unique?: boolean;
52
53
  }>;
53
54
  export type KnowledgeManagedProjection = Readonly<{
@@ -102,23 +103,39 @@ export type KnowledgeDisplayDefaults = Readonly<{
102
103
  collections?: readonly string[];
103
104
  details?: readonly string[];
104
105
  }>;
106
+ export type KnowledgeAutocompleteFieldReference = Readonly<{
107
+ field: string;
108
+ scope: "data" | "entity";
109
+ }>;
110
+ /** A schema-aware filter over the fields of the target schema. */
111
+ type KnowledgeRelationBaseFilter = Readonly<{
112
+ caseSensitive?: boolean;
113
+ field: string;
114
+ operator: "contains" | "ends_with" | "eq" | "exists" | "gt" | "gte" | "in" | "is_empty" | "is_not_empty" | "lt" | "lte" | "ne" | "nin" | "not_contains" | "starts_with";
115
+ value: JsonValue;
116
+ }>;
105
117
  /**
106
- * Portable relation metadata retained inside an entity schema when a gateway
107
- * projects references as fields rather than first-class relation edges.
118
+ * Makes a top-level property of an entity schema an Entity Relation Field:
119
+ * its value holds Entity References to entities of exactly one target schema
120
+ * of the same organization. The schema does not define the property: the
121
+ * platform generates it. `onDelete` defaults to `clear`; without `maxItems` a
122
+ * `many` field has no item limit. `display.fields` label a referenced entity,
123
+ * `autocomplete.fields` are searched when picking one and
124
+ * `autocomplete.baseFilters` (ANDed) limit the selectable targets.
108
125
  */
109
- export type EntityRelationField = Readonly<{
126
+ export type KnowledgeEntityRelationField = Readonly<{
127
+ autocomplete?: Readonly<{
128
+ baseFilters?: readonly KnowledgeRelationBaseFilter[];
129
+ fields?: readonly KnowledgeAutocompleteFieldReference[];
130
+ }>;
110
131
  cardinality: "many" | "one";
111
- field: string;
112
- id: string;
113
- nullable: boolean;
114
- reference: "external_id";
115
- targetEntityId: string;
132
+ display?: Readonly<{
133
+ fields: readonly KnowledgeAutocompleteFieldReference[];
134
+ }>;
135
+ maxItems?: number;
136
+ onDelete?: "clear" | "restrict";
116
137
  targetSchemaFqn: string;
117
138
  }>;
118
- export type KnowledgeAutocompleteFieldReference = Readonly<{
119
- field: string;
120
- scope: "data" | "entity";
121
- }>;
122
139
  export type KnowledgeAutocompleteConfiguration = Readonly<{
123
140
  autocompleteFields: readonly KnowledgeAutocompleteFieldReference[];
124
141
  defaultAutocompleteFields: readonly KnowledgeAutocompleteFieldReference[];
@@ -144,7 +161,6 @@ export type KnowledgeEntitySchemaDeclaration = PackagePrimitiveBase<"knowledgeEn
144
161
  managedProjection?: KnowledgeManagedProjection;
145
162
  maxVersionsExpirationDays?: number | null;
146
163
  persistFullFieldContributions: boolean;
147
- relationFields?: readonly EntityRelationField[];
148
164
  schema: PackageSchemaProjection;
149
165
  syncable?: boolean;
150
166
  usableAsDocumentScope: boolean;
@@ -250,3 +266,4 @@ export type KnowledgePolicyBody = Readonly<{
250
266
  subjectMatch: KnowledgePolicyPredicate;
251
267
  rule?: KnowledgePolicyPredicate;
252
268
  }>;
269
+ export {};
@@ -69,6 +69,8 @@ export declare const declareOrganizationSettings: (input: MetadataClassDeclarati
69
69
  export declare const declareSkillTemplate: (input: MetadataClassDeclaration<SkillTemplateDeclaration>) => DeclaredComponent<SkillTemplateDeclaration>;
70
70
  /** Authored field semantics; File field entries come from `fileFields`. */
71
71
  type KnowledgeFieldSemanticsInput = Readonly<Record<string, Omit<KnowledgeFieldSemantics, "file">>>;
72
+ /** Relation schemas take no File or relation field entries. */
73
+ type KnowledgeRelationFieldSemanticsInput = Readonly<Record<string, Omit<KnowledgeFieldSemantics, "file" | "relation">>>;
72
74
  type KnowledgeEntityDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeEntitySchemaDeclaration>, "fieldSemantics" | "schema"> & Readonly<{
73
75
  fieldSemantics?: KnowledgeFieldSemanticsInput;
74
76
  /** The File fields of the schema, by top-level property key. */
@@ -76,7 +78,7 @@ type KnowledgeEntityDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeE
76
78
  schema: DecoderSource<Schema>;
77
79
  }>;
78
80
  type KnowledgeRelationDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeRelationSchemaDeclaration>, "fieldSemantics" | "schema" | "lifecycle"> & Readonly<{
79
- fieldSemantics?: KnowledgeFieldSemanticsInput;
81
+ fieldSemantics?: KnowledgeRelationFieldSemanticsInput;
80
82
  lifecycle: LifecycleOptions;
81
83
  schema: DecoderSource<Schema>;
82
84
  }>;
@@ -1,4 +1,4 @@
1
- import type { JsonObject } from "../foundation/json.js";
1
+ import type { JsonObject, JsonValue } from "../foundation/json.js";
2
2
  import type { PortableFormDefinition } from "../schema/forms.js";
3
3
  import type { PackageSchemaProjection } from "../schema/projection.js";
4
4
  import type { DeclarationReference } from "./authoring-core.js";
@@ -11,6 +11,21 @@ export type ToolGuidance = Readonly<{
11
11
  inputRequirementsSummary?: string;
12
12
  useWhen?: string;
13
13
  }>;
14
+ /** One unit of display data a tool returns next to its output; it never reaches the model. */
15
+ export type ToolDisplayPart = Readonly<{
16
+ data: JsonValue;
17
+ description?: string | null;
18
+ metadata?: JsonObject;
19
+ title?: string | null;
20
+ type: string;
21
+ }>;
22
+ export declare const toolResultBrand: unique symbol;
23
+ /** A branded tool result that carries Display Parts next to its output. */
24
+ export type ToolResultWithDisplay<Output> = Readonly<{
25
+ [toolResultBrand]: true;
26
+ displayParts: readonly ToolDisplayPart[];
27
+ output: Output;
28
+ }>;
14
29
  /** A companion tool bound alongside the declaring tool, e.g. a catalog lookup. */
15
30
  export type ToolExtraLoader = Readonly<{
16
31
  bindingName: string;
@@ -123,6 +138,8 @@ export type ToolSettingsOptionPage = Readonly<{
123
138
  options: readonly ToolSettingsOption[];
124
139
  }>;
125
140
  export type ToolSettingsOptionsContext = Readonly<{
141
+ /** Eligible image-output choices projected by the authorized Host; no runtime authority. */
142
+ imageModelOptions?: readonly Readonly<Pick<ToolSettingsOption, "id" | "label">>[];
126
143
  connectionCatalogs: Readonly<Record<string, JsonObject>>;
127
144
  connectionCredentials: Readonly<Record<string, Readonly<Record<string, string | null>>>>;
128
145
  dependencies: JsonObject;
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Well-known ids of the built-in workflow code runtimes. Every Collective
3
+ * Intelligence deployment seeds them, so a package `code-block` node sets its
4
+ * `runtimeId` to one of these instead of a per-deployment id.
5
+ */
6
+ export declare const builtInCodeRuntimeIds: {
7
+ /** JavaScript on Node.js 24. */
8
+ readonly node24: "65eda637-e41c-43ea-81aa-0596439e8513";
9
+ /** Python 3.12. */
10
+ readonly python312: "ff5aca6d-99b3-40cc-bccb-37951b919bcb";
11
+ };
package/dist/index.d.ts CHANGED
@@ -16,6 +16,7 @@ export { declareKnowledgeEntityAdapter, declareConnection, declareDocumentsConne
16
16
  export { declareWorkflowNode } from "./components/workflow-node-authoring.js";
17
17
  export { resolveWorkflowNodePorts, WorkflowPortIssueCodes } from "./components/workflow-ports.js";
18
18
  export type { WorkflowNodePortsContract, WorkflowPortIssue, WorkflowPortIssueCode, WorkflowResolvedPorts } from "./components/workflow-ports.js";
19
+ export { builtInCodeRuntimeIds } from "./components/workflow-code-runtimes.js";
19
20
  export { workflowSchemaAt } from "./components/workflow-schema.js";
20
21
  export type { WorkflowSchemaLocation } from "./components/workflow-schema.js";
21
22
  export { declareDatasetParser, declareDomain, declareDomainTemplate, declareExternalApplication, declareExternalAppGateway, declareExternalDatasetProvider, declareKnowledgeEntitySchema, declareKnowledgePolicy, declareKnowledgeRelationSchema, declareManagedDatasetProvider, declareOrganizationGroup, declareOrganizationSettings, declareRemoteToolCollection, declareSkillTemplate, declareStudioApp, declareStudioAppTemplate, declareStudioComponent, declareToolCollection, declareWorkflow, declareWorkflowFieldCollection, declareWorkflowNodeCollection, declareWorkflowTemplate } from "./components/metadata-authoring.js";
@@ -39,9 +40,9 @@ export type { FieldOption, FieldOptionGroup, FieldOptionPage, FieldOptionsInput,
39
40
  export type { PackageWorkflowNodeExecutionResult, PackageWorkflowNodeDirective, PackageWorkflowPauseResumeContract, PackageWorkflowNodeResult } from "./components/workflow-results.js";
40
41
  export type { ConnectionDiscoveryCatalog, ConnectionDiscoveryCollection, ConnectionDiscoveryField, ConnectionDiscoveryMetadata, ConnectionDiscoveryMetadataValue, ConnectionDiscoveryRelationship, ConnectionDiscoveryResource, PackageConnectionProgress } from "./components/connections.js";
41
42
  export { canonicalPackageManifest, packageManifestJson } from "./package/canonical.js";
42
- export { parsePackageDependencyPins, resolvePackageDependencyOrder } from "./package/dependencies.js";
43
+ export { parsePackageDependencies, resolvePackageDependencyOrder } from "./package/dependencies.js";
43
44
  export { PackageManifestVersion } from "./package/manifest.js";
44
- export type { InstallationWizard, InstallationWizardStep, PackageDependencyPin, PackageManifest } from "./package/manifest.js";
45
+ export type { InstallationWizard, InstallationWizardStep, PackageDependency, PackageManifest } from "./package/manifest.js";
45
46
  export { canonicalExtensionReleaseManifest, ExtensionReleaseManifestVersion, PACKAGE_MEDIA_SIZE_LIMIT_BYTES, PackageMediaArchivePrefix, parseExtensionReleaseManifest } from "./release/manifest.js";
46
47
  export { parseExtensionReleaseArchive, validateExtensionReleaseArchiveMetadata } from "./release/archive.js";
47
48
  export { parseStoredExtensionReleaseManifest, storedPrimitiveKind, withCurrentPrimitiveKinds } from "./release/stored-manifest.js";
@@ -60,8 +61,9 @@ export type { AgentActivityPolicy, AgentAudience, AgentAudienceDeclaration, Agen
60
61
  export type { DocumentsDeltaCursorExpired, DocumentsDeltaItem, DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrive, DocumentsDrivesPage, DocumentsFolder, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, KnowledgeConnectorContribution, KnowledgeConnectorBindingExtraConfig, KnowledgeConnectorDeclaration, KnowledgeConnectorFieldMapRule, KnowledgeEntitySchemaCapability, KnowledgeConnectorOAuthDeclaration, KnowledgeConnectorOAuthTokens, KnowledgeConnectorRemoteReference, EventListenerDeclaration, EventListenerInternalOccurrence, EventListenerPollRequest, EventListenerPollResult, EventListenerWebhookRequest, KnowledgePredefinedSchedule, ManagedDatasetProviderDeclaration, KnowledgeRelationAdapterDeclaration, KnowledgeRelationSchemaCapability } from "./components/connectors.js";
61
62
  export type { PackagePrimitiveDeclaration } from "./components/declaration.js";
62
63
  export type { DatasetBlueprintClassDeclaration, DatasetBlueprintDeclaration, DatasetTableTemplateClassDeclaration, DatasetTableTemplateDeclaration, DatasetTableTemplateHint, DatasetTableTemplatePhysicalCode, DatasetTableTemplateSemanticRole, DatasetTableTemplateUniqueness } from "./components/templates.js";
63
- export type { EntityRelationField, KnowledgeAutocompleteConfiguration, KnowledgeAutocompleteFieldReference, KnowledgeEntitySchemaDeclaration, KnowledgeDisplayDefaults, KnowledgeFieldLocalization, KnowledgeFieldPresentation, KnowledgeFieldSemantics, KnowledgeFileField, KnowledgeFileFieldDeclaration, KnowledgeManagedProjection, LocalizedFieldText, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./components/knowledge.js";
64
- export type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, RemoteToolCollectionDefinition, SetupInstructions, ToolCollectionDeclaration, ToolCollectionVisibilityGrant, ToolDeclaration, ToolExtraLoader, ToolGuidance, ToolHealthCheck, ToolSettingsOption, ToolSettingsOptionPage, ToolSettingsOptionsContext, ToolSettingsOptionsDeclaration } from "./components/tools.js";
64
+ export type { KnowledgeAutocompleteConfiguration, KnowledgeAutocompleteFieldReference, KnowledgeEntityRelationField, KnowledgeEntitySchemaDeclaration, KnowledgeDisplayDefaults, KnowledgeFieldLocalization, KnowledgeFieldPresentation, KnowledgeFieldSemantics, KnowledgeFileField, KnowledgeFileFieldDeclaration, KnowledgeManagedProjection, LocalizedFieldText, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./components/knowledge.js";
65
+ export { toolResultBrand } from "./components/tools.js";
66
+ export type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, RemoteToolCollectionDefinition, SetupInstructions, ToolCollectionDeclaration, ToolCollectionVisibilityGrant, ToolDeclaration, ToolDisplayPart, ToolExtraLoader, ToolGuidance, ToolHealthCheck, ToolResultWithDisplay, ToolSettingsOption, ToolSettingsOptionPage, ToolSettingsOptionsContext, ToolSettingsOptionsDeclaration } from "./components/tools.js";
65
67
  export type { WorkflowAuthoringActionEndpoint, WorkflowAuthoringDefinition, WorkflowAuthoringEdge, WorkflowAuthoringEdgeSource, WorkflowAuthoringEdgeTarget, WorkflowAuthoringFieldProjection, WorkflowAuthoringInputContract, WorkflowAuthoringInputEndpoint, WorkflowAuthoringNode, WorkflowAuthoringOutputBinding, WorkflowAuthoringOutputContract, WorkflowAuthoringOutputEndpoint, WorkflowAuthoringTemplateRef, WorkflowAuthoringTrigger, WorkflowAuthoringTriggerBinding, WorkflowAuthoringTriggerEndpoint, WorkflowAuthoredValue, WorkflowBindingExpression, WorkflowBindingSource, WorkflowBindingSpan, WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldContract, WorkflowFieldDeclaration, WorkflowConnectionRequirementDeclaration, WorkflowEditorDeclaration, WorkflowEditorFieldDeclaration, WorkflowEditorFieldOverride, WorkflowEditorOption, WorkflowEditorOptionSource, WorkflowEditorOverrides, WorkflowEditorSectionDeclaration, WorkflowEditorSectionOverride, WorkflowEditorValueSource, WorkflowEditorVisibilityRule, WorkflowEditorWidget, WorkflowEventIngressDeclaration, WorkflowEventSelectorProjection, WorkflowFieldBindingDeclaration, WorkflowDynamicPortDeclaration, WorkflowNodeContract, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowNodeExecutionContract, WorkflowNodeExecutionSettings, WorkflowNodeInstancePolicy, WorkflowNodePortDeclaration, WorkflowOutputChannelDeclaration, WorkflowPortSchemaInjection, WorkflowPortSchemaResolution, WorkflowReusableDependencyDeclaration, WorkflowTemplateKind, WorkflowTriggerActivationDeclaration, WorkflowTemplateDeclaration, WorkflowTemplateGraphDefinition, WorkflowTemplateGraphSchemaContract, WorkflowTemplateUiLayout, WorkflowTriggerInvocation } from "./components/workflows.js";
66
68
  export type { JsonObject, JsonPrimitive, JsonValue } from "./foundation/json.js";
67
69
  export type { Bounds, Compatibility, ConnectorContext, DatasetAggregateOperation, DatasetBindingMode, DatasetDefinition, DatasetDeleteInput, DatasetDeleteResult, DatasetHealth, DatasetIngestInput, DatasetIngestMode, DatasetIngestResult, DatasetInspectInput, DatasetInspectResult, DatasetFilter, DatasetOperation, DatasetOrder, DatasetPredicate, DatasetPredicateOperator, DatasetQueryIntent, DatasetTimeBucket, DatasetProviderCapabilities, DatasetProviderError, DatasetProviderResult, DatasetProvisionInput, DatasetProvisionResult, DatasetRecordPage, DatasetResultPage, DatasetScalarType, DatasetSourceItem, DatasetSourceLocation, DatasetValue, DefinitionProposal, DiscoverDefinitionInput, ExternalDatasetBinding, ListSourcesInput, QueryInput, Readiness, ReadinessInput, SafeDiagnostic, SourcePage } from "./components/datasets.js";