@collective-intelligence/extensions-sdk 0.1.8 → 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
@@ -115,6 +117,63 @@ Manual triggers may declare `invocationRole: "user" | "application"`, and
115
117
  these values and the event kind/acquisition mode into normalized Host columns;
116
118
  repositories select by those columns instead of extension identity or private
117
119
  configuration keys.
120
+ `withStudioTriggerForm(trigger, { organizationGroup })` gives a user-invoked
121
+ trigger of a declared Workflow a Studio form, stored under the trigger's
122
+ `metadata.studioForm`. `organizationGroup` takes an Organization Group
123
+ declaration or FQN; CI Studio shows and runs the form only for users of that
124
+ Group, directly or through a subgroup. `readStudioTriggerForm` reads the form
125
+ back, and manifest admission rejects a malformed one.
126
+ The form may declare `fields`. A file field
127
+ `{ key, label, type: "file", accept?, maxBytes? }` shows an upload control; it
128
+ accepts `defaultStudioTriggerFormFileAccept` (PDF, JPEG, PNG) and at most
129
+ `maxStudioTriggerFormFileBytes` (10 MiB, also the ceiling for `maxBytes`)
130
+ unless it declares narrower ones. `key` holds letters, digits and `_`, unique in
131
+ the form. Studio stores the upload as a private stored file of the Organization
132
+ and starts the run only once every file field holds an upload, with
133
+ `form.<key> = { storageFileId }`; nodes bind
134
+ `{{ trigger.form.<key>.storageFileId }}`.
135
+ Typed fields hold a value the user types or picks: `{ key, label, type }` with
136
+ `type` `"text"` (string), `"textarea"` (multi-line string, such as a Markdown
137
+ body), `"number"` (finite number) or `"boolean"`;
138
+ `{ key, label, type: "enum", options: [{ label, value }] }` (one option
139
+ `value`; values unique, at least one option); and
140
+ `{ key, label, type: "json", schema }` for nested objects and lists, whose
141
+ value must satisfy the Draft 2020-12 JSON Schema `schema` and which Studio
142
+ edits as JSON text. A `schema` CI cannot compile strictly closes the form. The
143
+ run starts only once every field holds a value of its type, takes only the
144
+ declared fields, and nodes bind `{{ trigger.form.<key> }}` (or a path inside a
145
+ `json` value, such as `{{ trigger.form.request.company.name }}`).
146
+ A link opens the form prefilled: add the query parameter
147
+ `prefill.<triggerRef>` to the URL of the Studio page that places
148
+ `builtin:view.trigger-form` for that trigger. Its value is base64url (RFC 4648
149
+ §5, unpadded) of the UTF-8 JSON object `{ "<key>": value }`, at most 8192
150
+ characters. It may hold any subset of the typed fields and no file field. CI
151
+ checks every value against its field before the form opens, and refuses the
152
+ whole link otherwise; the user can change every value, and the run checks the
153
+ submitted values again. The link travels in browser history and server logs:
154
+ put no secrets in it.
155
+ An entities field is a searchable multi-select of the Organization's Knowledge
156
+ entities of one schema: `{ key, label, type: "entities", schemaFqn, valueKey?,
157
+ labelKey? }`. Studio offers only entities of `schemaFqn` in the user's
158
+ Organization that the user's Knowledge policies let them read, matching the
159
+ typed text against the entity name, through
160
+ `GET /studio/triggers/:triggerRef/fields/:fieldKey/options?q=` (the form's
161
+ Group gate applies). Each option shows the `labelKey` data field (the entity
162
+ name when omitted). The value is `{ entityIds, values }`: the picked entity
163
+ ids and, at the same index, each entity's string `valueKey` data field (its
164
+ id when omitted; an entity without it cannot be picked), at most 100 picks,
165
+ none required. The run starts only once every id is such an entity and every
166
+ value is that entity's; nodes bind `{{ trigger.form.<key>.values }}` for the
167
+ list of, for example, tag slugs, and `{{ trigger.form.<key>.entityIds }}` for
168
+ the ids. A prefill link may carry the same value; it is checked the same way.
169
+ `withStudioAgentForm(agent, { fields })` gives a declared Agent a Studio form,
170
+ stored under the Agent's `metadata.studioForm`; `readStudioAgentForm` reads it
171
+ back. `fields` takes exactly the trigger-form field types above (`file`,
172
+ `text`, `textarea`, `number`, `boolean`, `enum`, `json`, `entities`); any other
173
+ type, or a repeated key, fails at declaration and at manifest admission.
174
+ `builtin:view.agent-form` names the Agent by FQN in `props.agentRef`. A submit
175
+ runs the Agent for the Studio user, within the Agent's audience, with the JSON
176
+ object of the declared field values as its task.
118
177
 
119
178
  Action nodes that invoke another Workflow declare `reusableDependency` paths
120
179
  for the target Workflow ID and selected input contract, plus an optional
@@ -265,6 +324,16 @@ export default declarePackage({
265
324
  })
266
325
  ```
267
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
+
268
337
  Every source implements Standard Schema V1 validation and Standard JSON Schema
269
338
  V1 projection. Validation and encoding may be asynchronous; projection and
270
339
  manifest construction are synchronous. Output declaration positions require a
@@ -304,7 +373,7 @@ independent of relation record `localMutationPolicy`.
304
373
  `declareWorkflowTemplate` require per-item `LifecycleOptions`:
305
374
  `{ deployMode: "upsert" | "init_only", readonly: boolean }`. Entity schemas
306
375
  also require the persisted Organization entity schema capabilities other than
307
- relation schemas and parked `relationFields`: `autocompleteConfiguration`,
376
+ relation schemas: `autocompleteConfiguration`,
308
377
  `displayNameExpression`, `embeddingConfig`, `persistFullFieldContributions`,
309
378
  `usableAsDocumentScope`, and `versioningEnabled`. Domain declarations require
310
379
  `versioningEnabled`. External applications require `applicationType`,
@@ -325,6 +394,74 @@ projects a Draft 2020-12 `knowledge_record` document (`enum`, `format`, root
325
394
  `type: "object"`, `required` array). Adapter-owned codecs still use
326
395
  `definePackageSchema`.
327
396
 
397
+ `declareKnowledgeEntitySchema` declares File fields in `fileFields`, keyed by
398
+ top-level property key. Each declaration takes `multiple`, `accepts` (matched
399
+ like the HTML `accept` attribute: MIME types, `type/*` wildcards or `.ext` file
400
+ name suffixes; empty for any) and an optional `visibility` (`public`, `protected` or
401
+ `private`; Protected when absent):
402
+
403
+ ```ts
404
+ fileFields: {
405
+ resume: { accepts: ["application/pdf"], multiple: false, visibility: "private" }
406
+ }
407
+ ```
408
+
409
+ The declaration compiles into `fieldSemantics["/resume"]`:
410
+ `{ file: { accepts, multiple }, mediaVisibility }`, merged with the other
411
+ authored semantics of that pointer. The schema must not define the property;
412
+ the platform generates the File value schema at install. Localization,
413
+ presentation and semantics pointers may address the File field. Declaration
414
+ rejects a raw `fieldSemantics` `file` entry, a `mediaVisibility` on a pointer
415
+ that is not a declared File field (relation schemas have none), and a File field
416
+ with both `visibility` and a raw `mediaVisibility`.
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
+
328
465
  ## Agent and Skill declarations
329
466
 
330
467
  `declareSkill` declares a governed Skill: `instructions`, the `tools` it
@@ -901,12 +1038,7 @@ layout, create-step, and update-section metadata.
901
1038
 
902
1039
  ### Gateway declaration vocabulary
903
1040
 
904
- General knowledge entity schemas may retain an explicitly declared source
905
- reference as an `EntityRelationField`; its `field` is a canonical RFC 6901
906
- instance pointer and is checked against the projected entity schema with the
907
- other field metadata. This schema vocabulary is not gateway manifest input.
908
-
909
- The SDK also exports the JSON-only `PortableOperationDeclaration`,
1041
+ The SDK exports the JSON-only `PortableOperationDeclaration`,
910
1042
  `OperationDomainDeclaration`, and `PortableGatewayDeclarations` types. They
911
1043
  establish the shared operation manifest input vocabulary. Every portable
912
1044
  operation explicitly carries its effect class, idempotency and bounded retry
@@ -990,7 +1122,11 @@ or Documents policy. Existing approval, timer, and custom-mode pauses can omit
990
1122
  `discloseSummary: true` when its author vouches that the rendered `summary` is
991
1123
  safe to show Approvers; the Host then shows it in the frozen approval context.
992
1124
  The field applies only to `mode: "approval"` and defaults to hidden. The Host
993
- still omits a disclosed summary that contains a credential or personal data. `expiresAt` and `wakeAt` are still
1125
+ still omits a disclosed summary that contains a credential or personal data. An
1126
+ approval pause may also set `invokerDecision: "explicit"`: the Host then opens
1127
+ the Request pending, with no automatic approval for the person who started the
1128
+ run, who stays an eligible Approver when the Rule allows it. The default,
1129
+ `"automatic"`, keeps that automatic approval. `expiresAt` and `wakeAt` are still
994
1130
  optional, and the SDK adds no default expiration. Typed pause results can be
995
1131
  serialized with `canonicalJson`; execution, durable suspension, resume, and
996
1132
  cancellation remain host responsibilities.
@@ -1069,6 +1205,40 @@ the guard. They apply to ID targets too.
1069
1205
  The core Invoke Workflow node exposes the same choice through its `target`
1070
1206
  (a selected Workflow) and `targetFqn` configuration; set exactly one.
1071
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
+
1072
1242
  ## Executable implementations
1073
1243
 
1074
1244
  The common declaration helpers accept structural implementation constructors,
@@ -1246,15 +1416,20 @@ portable `emailProvider` metadata: `connectionTemplateFqn` and `senderKind`.
1246
1416
  `connectionTemplateFqn` names the connection template whose credential form
1247
1417
  shapes the provider credentials. `senderKind` is `mailbox` for a provider that
1248
1418
  always sends from a real mailbox, and `address` for every other provider.
1249
- The optional `deploymentIdentity: "aws"` declares that the tenant may use the
1250
- deployment's own cloud identity instead of stored credentials; the host then
1251
- passes temporary `accessKeyId`, `secretAccessKey`, `sessionToken`, and `region`
1252
- 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.
1253
1425
  Declaration and portable manifest admission both reject an empty
1254
1426
  `connectionTemplateFqn`, any other `senderKind`, and any other
1255
1427
  `deploymentIdentity`. The implementation remains a
1256
- runtime sidecar. Executable send and failure contracts belong to
1257
- `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.
1258
1433
 
1259
1434
  ## Portable manifest admission
1260
1435
 
@@ -1294,25 +1469,39 @@ Declare `normalizesFieldMapValues: true` to let an adapter normalize each
1294
1469
  provider value read by an inbound field-map rule before path, cast, or transform
1295
1470
  handling. This leaves other providers' values untouched.
1296
1471
 
1297
- ## Exact dependencies and immutable release declarations
1472
+ ## FQN dependencies and immutable release declarations
1298
1473
 
1299
- Package `dependencies` contain exact immutable references, with no version ranges:
1474
+ Package `dependencies` contain only package identities:
1300
1475
 
1301
1476
  ```ts
1302
- dependencies: [
1303
- {
1304
- fqn: "com.acme.base",
1305
- releaseDigest: "a".repeat(64), // lowercase SHA-256 of the release archive
1306
- releaseId: "release-base"
1307
- }
1308
- ]
1477
+ dependencies: [{ fqn: "com.acme.base" }]
1309
1478
  ```
1310
1479
 
1311
- `declarePackage` and `parsePackageManifest` validate these pins, reject duplicate
1312
- package identities and sort dependencies by FQN without reordering caller arrays.
1313
- `parsePackageDependencyPins` exposes the same validation to host adapters.
1314
- `resolvePackageDependencyOrder` orders declarations by dependency FQN; authorization,
1315
- 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.
1316
1505
 
1317
1506
  New release builders retain the portable declarations in
1318
1507
  `ExtensionReleaseManifest.packageManifest` and include their canonical JSON bytes
@@ -1604,6 +1793,49 @@ native semantics. Managed Datasets require `definition: DatasetDefinition` and
1604
1793
  may specify an existing `templateFqn`/`templateConfig`; External Datasets require
1605
1794
  `sourceLocation` and may retain a native `sourceMapping`.
1606
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
+
1607
1839
  ### Concrete Managed and External Datasets
1608
1840
 
1609
1841
  Install the existing provider packages in the target Organization, or pin their
@@ -1740,3 +1972,46 @@ Fill `fields` with the native connection template's required credentials.
1740
1972
  `connectionId` must match the Organization and expected template. The backend
1741
1973
  validates ownership, executable references and native configuration. Installation
1742
1974
  configures resources; native schedules and authorized manual actions execute work.
1975
+
1976
+ Knowledge schemas select item embedding fields with
1977
+ `definition.fieldSemantics["/full/pointer"].includeInItemEmbedding: true`.
1978
+ Omitted and `false` values leave the field out. Select scalar values or lists of
1979
+ scalars; nested fields use full RFC 6901 JSON pointers (`~1` escapes `/`, `~0`
1980
+ escapes `~`). Objects, files, and relation traversal cannot be selected as item
1981
+ values. When the schema's `embedEntities` gate is enabled, its item vector contains
1982
+ only the selected values as one bounded YAML document, without chunking or an item overview. Empty selection
1983
+ produces no item vector and a visible configuration status. Unsupported selected
1984
+ values or input exceeding the embedding model's budget produce a visible failure;
1985
+ values are not silently truncated.
1986
+
1987
+ `embedded: true` independently enables passage indexing for an ordinary text
1988
+ field. Item selection never enables passage indexing, and existing `indexed`,
1989
+ `defaultSearch`, or file-content flags never select a field for the item vector.
1990
+ For example, `fieldSemantics: { "/name": { includeInItemEmbedding: true },
1991
+ "/notes": { includeInItemEmbedding: false, embedded: true } }` keeps the name in
1992
+ the item vector and searches notes as separate passages. These settings are
1993
+ portable schema declarations and use the same admission and live configuration
1994
+ rules as administration and Knowledge Setup.
1995
+
1996
+ ### File overview settings
1997
+
1998
+ Knowledge schema declarations can set nullable `overviewInputMaxChars` and
1999
+ `richEnrichment`. A FileField can override each setting through its pointer in
2000
+ `definition.fieldSemantics`. The budget is an integer from 1 to 1,000,000.
2001
+ Omission or `null` inherits; `false` explicitly disables rich enrichment.
2002
+ Resolution follows product defaults (4,000 characters and enrichment off),
2003
+ organization settings, schema settings, then the FileField override. The cheap
2004
+ overview summarizes the bounded extracted-text prefix in exactly three sentences;
2005
+ rich enrichment is separately opt-in.
2006
+
2007
+ Add these settings to the existing schema declaration's `definition` object:
2008
+
2009
+ ```ts
2010
+ {
2011
+ overviewInputMaxChars: 2000,
2012
+ richEnrichment: true,
2013
+ fieldSemantics: {
2014
+ "/cv": { overviewInputMaxChars: 500, richEnrichment: false }
2015
+ }
2016
+ }
2017
+ ```
@@ -99,6 +99,8 @@ export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
99
99
  audience?: AgentAudienceDeclaration;
100
100
  behavioralBoundaries: readonly string[];
101
101
  lifecycle: LifecycleOptions;
102
+ /** Open JSON for Studio extensions, such as `withStudioAgentForm`. */
103
+ metadata?: JsonObject;
102
104
  /** Step limit; omitted uses the CI safety-limit setting. */
103
105
  maxSteps?: number;
104
106
  /**
@@ -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;
@@ -1,6 +1,6 @@
1
1
  import type { VisibilityCondition } from "../schema/forms.js";
2
2
  export type BindingScope = "organization" | "tenant";
3
- export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
3
+ export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
4
4
  export type PackagePrimitiveBase<Kind extends PackagePrimitiveKind> = Readonly<{
5
5
  description?: string;
6
6
  displayName: string;
@@ -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
  }>;
@@ -7,8 +7,8 @@ import type { ExternalApplicationDeclaration } from "./external-application.js";
7
7
  import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
8
8
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
9
9
  import type { OrganizationSettingsDeclaration } from "./organization-settings.js";
10
- import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.js";
10
+ import type { StudioAppDeclaration, StudioAppTemplateDeclaration, StudioComponentDeclaration } from "./studio.js";
11
11
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
12
12
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
13
13
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
14
- export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
14
+ export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -7,21 +7,48 @@ export type LocalizedFieldText = Readonly<{
7
7
  fallbackLocale: string;
8
8
  values: Readonly<Record<string, string>>;
9
9
  }>;
10
+ /**
11
+ * Makes a top-level property a File field: its value is generated by the
12
+ * host, `accepts` lists accepted files like the HTML `accept` attribute
13
+ * (MIME types, `type/*` wildcards or `.ext` suffixes; empty for any) and
14
+ * `multiple` allows several files.
15
+ */
16
+ export type KnowledgeFileField = Readonly<{
17
+ accepts: readonly string[];
18
+ multiple: boolean;
19
+ }>;
20
+ /**
21
+ * Declares a File field by its top-level property key. It compiles into the
22
+ * File field entry and `mediaVisibility` of `fieldSemantics["/<key>"]`. The
23
+ * schema does not define the property: the platform generates its value
24
+ * schema. A `visibility` that is not declared is Protected.
25
+ */
26
+ export type KnowledgeFileFieldDeclaration = KnowledgeFileField & Readonly<{
27
+ visibility?: KnowledgeFieldSemantics["mediaVisibility"];
28
+ }>;
10
29
  export type KnowledgeFieldSemantics = Readonly<{
30
+ /** Extracted-text prefix budget; null or omission inherits the schema/organization default. */
31
+ overviewInputMaxChars?: number | null;
32
+ /** Separate whole-file enrichment; explicit false overrides an enabled ancestor. */
33
+ richEnrichment?: boolean | null;
11
34
  defaultSearch?: boolean;
12
35
  embedded?: boolean;
36
+ /** Include this scalar or scalar-list field in the item YAML vector; omitted means off. */
37
+ includeInItemEmbedding?: boolean;
13
38
  faceted?: boolean;
39
+ file?: KnowledgeFileField;
14
40
  indexContent?: boolean;
15
41
  indexOverview?: boolean;
16
42
  indexed?: boolean;
17
43
  managedProjectionSource?: "organization_group" | "organization_user";
18
44
  /**
19
- * Who may fetch the file of a file field through its Stable Media URL:
45
+ * Who may fetch the files of a File field through their Stable Media URL:
20
46
  * `public` anyone, `protected` (the default) a reader of the entity,
21
47
  * `private` a principal that may manage Knowledge.
22
48
  */
23
49
  mediaVisibility?: "private" | "protected" | "public";
24
50
  queryGuidance?: string;
51
+ relation?: KnowledgeEntityRelationField;
25
52
  unique?: boolean;
26
53
  }>;
27
54
  export type KnowledgeManagedProjection = Readonly<{
@@ -76,23 +103,39 @@ export type KnowledgeDisplayDefaults = Readonly<{
76
103
  collections?: readonly string[];
77
104
  details?: readonly string[];
78
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
+ }>;
79
117
  /**
80
- * Portable relation metadata retained inside an entity schema when a gateway
81
- * 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.
82
125
  */
83
- export type EntityRelationField = Readonly<{
126
+ export type KnowledgeEntityRelationField = Readonly<{
127
+ autocomplete?: Readonly<{
128
+ baseFilters?: readonly KnowledgeRelationBaseFilter[];
129
+ fields?: readonly KnowledgeAutocompleteFieldReference[];
130
+ }>;
84
131
  cardinality: "many" | "one";
85
- field: string;
86
- id: string;
87
- nullable: boolean;
88
- reference: "external_id";
89
- targetEntityId: string;
132
+ display?: Readonly<{
133
+ fields: readonly KnowledgeAutocompleteFieldReference[];
134
+ }>;
135
+ maxItems?: number;
136
+ onDelete?: "clear" | "restrict";
90
137
  targetSchemaFqn: string;
91
138
  }>;
92
- export type KnowledgeAutocompleteFieldReference = Readonly<{
93
- field: string;
94
- scope: "data" | "entity";
95
- }>;
96
139
  export type KnowledgeAutocompleteConfiguration = Readonly<{
97
140
  autocompleteFields: readonly KnowledgeAutocompleteFieldReference[];
98
141
  defaultAutocompleteFields: readonly KnowledgeAutocompleteFieldReference[];
@@ -106,6 +149,8 @@ export type KnowledgeEntitySchemaDeclaration = PackagePrimitiveBase<"knowledgeEn
106
149
  displayNameExpression: string | null;
107
150
  domainFqn: string;
108
151
  embedEntities?: boolean;
152
+ overviewInputMaxChars?: number | null;
153
+ richEnrichment?: boolean | null;
109
154
  embeddingConfig: JsonObject | null;
110
155
  extendsSchemaFqn?: string;
111
156
  fieldLocalization?: Readonly<Record<string, KnowledgeFieldLocalization>>;
@@ -116,7 +161,6 @@ export type KnowledgeEntitySchemaDeclaration = PackagePrimitiveBase<"knowledgeEn
116
161
  managedProjection?: KnowledgeManagedProjection;
117
162
  maxVersionsExpirationDays?: number | null;
118
163
  persistFullFieldContributions: boolean;
119
- relationFields?: readonly EntityRelationField[];
120
164
  schema: PackageSchemaProjection;
121
165
  syncable?: boolean;
122
166
  usableAsDocumentScope: boolean;
@@ -222,3 +266,4 @@ export type KnowledgePolicyBody = Readonly<{
222
266
  subjectMatch: KnowledgePolicyPredicate;
223
267
  rule?: KnowledgePolicyPredicate;
224
268
  }>;
269
+ export {};