@collective-intelligence/extensions-sdk 0.1.9 → 0.1.11
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 +599 -109
- package/dist/components/agents.d.ts +3 -0
- package/dist/components/authoring-core.d.ts +2 -2
- package/dist/components/base.d.ts +2 -1
- package/dist/components/connection-instances.d.ts +9 -0
- package/dist/components/connector-instances.d.ts +5 -1
- package/dist/components/connectors.d.ts +27 -1
- package/dist/components/data-access.d.ts +11 -0
- package/dist/components/declaration.d.ts +3 -1
- package/dist/components/external-application.d.ts +76 -28
- package/dist/components/knowledge.d.ts +52 -14
- package/dist/components/metadata-authoring.d.ts +27 -12
- package/dist/components/organization-settings.d.ts +1 -1
- package/dist/components/service-principal.d.ts +12 -0
- package/dist/components/tools.d.ts +18 -1
- package/dist/components/workflow-code-runtimes.d.ts +11 -0
- package/dist/components/workflow-results.d.ts +5 -0
- package/dist/components/workflows.d.ts +3 -0
- package/dist/index.d.ts +12 -6
- package/dist/index.js +2 -2
- package/dist/package/connector-readers.d.ts +1 -0
- package/dist/package/dependencies.d.ts +3 -3
- package/dist/package/knowledge-readers.d.ts +54 -0
- package/dist/package/manifest.d.ts +2 -4
- package/dist/package/primitive-readers.d.ts +20 -37
- package/dist/package/workflow-readers.d.ts +1 -0
- package/dist/release/stored-manifest.d.ts +3 -2
- package/package.json +1 -1
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
|
|
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,216 @@ 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_to_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` describes source-to-target limits, independently of whether an
|
|
444
|
+
inverse field is exposed. One means at most one, not a required link.
|
|
445
|
+
|
|
446
|
+
| Cardinality | Targets per source | Sources per target | Forward / inverse shape |
|
|
447
|
+
| -------------- | ------------------ | ------------------ | ----------------------- |
|
|
448
|
+
| `one_to_one` | At most one | At most one | Scalar / scalar |
|
|
449
|
+
| `one_to_many` | Many | At most one | Array / scalar |
|
|
450
|
+
| `many_to_one` | At most one | Many | Scalar / array |
|
|
451
|
+
| `many_to_many` | Many | Many | Array / array |
|
|
452
|
+
|
|
453
|
+
`maxItems` is an optional positive item limit for `one_to_many` and
|
|
454
|
+
`many_to_many` owners; scalar owners reject it. `onDelete` is `clear` or
|
|
455
|
+
`restrict`; the platform applies `clear` when it is absent. `display.fields`
|
|
456
|
+
and `autocomplete.fields` name `{ field, scope: "data" | "entity" }` fields of
|
|
457
|
+
the target schema; `autocomplete.baseFilters` are ANDed schema-aware filters
|
|
458
|
+
`{ field, operator, value, caseSensitive? }` that limit the selectable targets.
|
|
459
|
+
The schema does not define the property: the platform generates its value
|
|
460
|
+
schema at install. Localization, presentation and semantics pointers may address
|
|
461
|
+
the relation field. Declaration rejects a relation entry whose pointer is not a
|
|
462
|
+
top-level property, a relation entry on a File field, and any relation entry on
|
|
463
|
+
a relation schema. Package deploy resolves `targetSchemaFqn` among the entity
|
|
464
|
+
schemas of the Organization. The metadata-only `relationFields` declaration
|
|
465
|
+
is removed; manifest parsing refuses a release that still declares it.
|
|
466
|
+
|
|
467
|
+
An optional inverse names the owner by schema FQN and exact top-level RFC 6901
|
|
468
|
+
pointer. For example, Company can expose Contact.company through:
|
|
469
|
+
|
|
470
|
+
```ts
|
|
471
|
+
fieldSemantics: {
|
|
472
|
+
"/contacts": {
|
|
473
|
+
relation: {
|
|
474
|
+
inverseOf: { schemaFqn: "core.schemas.crm.contact", field: "/company" },
|
|
475
|
+
display: { fields: [{ field: "name", scope: "data" }] }
|
|
476
|
+
}
|
|
477
|
+
}
|
|
478
|
+
}
|
|
479
|
+
```
|
|
480
|
+
|
|
481
|
+
Inverse declarations accept `inverseOf` and optional `display`; they reject a
|
|
482
|
+
target, cardinality, picker (`autocomplete`), `maxItems`, or delete policy.
|
|
483
|
+
The host resolves the member schema and value shape from the owner. Authors
|
|
484
|
+
omit both forward and inverse properties from their ordinary value schema;
|
|
485
|
+
the host generates read contracts and excludes inverse fields from writes.
|
|
486
|
+
Pair resolution, permissions and database enforcement belong to the host,
|
|
487
|
+
not this portable SDK. Removing an inverse does not change owner constraints.
|
|
488
|
+
The legacy `one` and `many` authoring literals are rejected; migrate them to
|
|
489
|
+
`many_to_one` and `many_to_many`, respectively, to preserve reverse sharing.
|
|
490
|
+
|
|
491
|
+
### Complete cardinality example
|
|
492
|
+
|
|
493
|
+
These five declarations belong to one package with the declared Directory domain
|
|
494
|
+
(or a dependency supplying it). Person owns every relationship. Passport.holder
|
|
495
|
+
and Asset.owner are scalar inverses; Company.employees and Group.members are
|
|
496
|
+
list inverses. Every inverse is optional: removing it preserves the corresponding
|
|
497
|
+
owner's constraints and links. A local helper repeats ordinary schema settings;
|
|
498
|
+
it is not an additional SDK API.
|
|
499
|
+
|
|
500
|
+
```ts
|
|
501
|
+
import {
|
|
502
|
+
declareKnowledgeEntitySchema,
|
|
503
|
+
knowledgeRecordSchema,
|
|
504
|
+
type KnowledgeFieldSemantics
|
|
505
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
506
|
+
|
|
507
|
+
// The package also supplies com.acme.domains.directory, or depends on its owner.
|
|
508
|
+
// This local helper only avoids repeating the ordinary schema settings.
|
|
509
|
+
function entity(
|
|
510
|
+
key: string,
|
|
511
|
+
displayName: string,
|
|
512
|
+
fieldSemantics: Readonly<Record<string, KnowledgeFieldSemantics>>
|
|
513
|
+
) {
|
|
514
|
+
return declareKnowledgeEntitySchema({
|
|
515
|
+
manifest: { fqn: `com.acme.schemas.directory.${key}`, version: "1.0.0" },
|
|
516
|
+
presentation: { displayName },
|
|
517
|
+
definition: {
|
|
518
|
+
domainFqn: "com.acme.domains.directory",
|
|
519
|
+
lifecycle: { deployMode: "upsert", readonly: false },
|
|
520
|
+
schema: knowledgeRecordSchema({
|
|
521
|
+
properties: { name: { type: "string" } }
|
|
522
|
+
}),
|
|
523
|
+
fieldSemantics,
|
|
524
|
+
autocompleteConfiguration: {
|
|
525
|
+
autocompleteFields: [],
|
|
526
|
+
defaultAutocompleteFields: []
|
|
527
|
+
},
|
|
528
|
+
displayNameExpression: null,
|
|
529
|
+
embeddingConfig: null,
|
|
530
|
+
persistFullFieldContributions: false,
|
|
531
|
+
usableAsDocumentScope: false,
|
|
532
|
+
versioningEnabled: null
|
|
533
|
+
}
|
|
534
|
+
})
|
|
535
|
+
}
|
|
536
|
+
|
|
537
|
+
export const Person = entity("person", "Person", {
|
|
538
|
+
"/passport": {
|
|
539
|
+
relation: {
|
|
540
|
+
targetSchemaFqn: "com.acme.schemas.directory.passport",
|
|
541
|
+
cardinality: "one_to_one"
|
|
542
|
+
}
|
|
543
|
+
},
|
|
544
|
+
"/assets": {
|
|
545
|
+
relation: {
|
|
546
|
+
targetSchemaFqn: "com.acme.schemas.directory.asset",
|
|
547
|
+
cardinality: "one_to_many"
|
|
548
|
+
}
|
|
549
|
+
},
|
|
550
|
+
"/company": {
|
|
551
|
+
relation: {
|
|
552
|
+
targetSchemaFqn: "com.acme.schemas.directory.company",
|
|
553
|
+
cardinality: "many_to_one"
|
|
554
|
+
}
|
|
555
|
+
},
|
|
556
|
+
"/groups": {
|
|
557
|
+
relation: {
|
|
558
|
+
targetSchemaFqn: "com.acme.schemas.directory.group",
|
|
559
|
+
cardinality: "many_to_many"
|
|
560
|
+
}
|
|
561
|
+
}
|
|
562
|
+
})
|
|
563
|
+
|
|
564
|
+
export const Passport = entity("passport", "Passport", {
|
|
565
|
+
"/holder": {
|
|
566
|
+
relation: {
|
|
567
|
+
inverseOf: {
|
|
568
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
569
|
+
field: "/passport"
|
|
570
|
+
}
|
|
571
|
+
}
|
|
572
|
+
}
|
|
573
|
+
})
|
|
574
|
+
export const Asset = entity("asset", "Asset", {
|
|
575
|
+
"/owner": {
|
|
576
|
+
relation: {
|
|
577
|
+
inverseOf: {
|
|
578
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
579
|
+
field: "/assets"
|
|
580
|
+
}
|
|
581
|
+
}
|
|
582
|
+
}
|
|
583
|
+
})
|
|
584
|
+
export const Company = entity("company", "Company", {
|
|
585
|
+
"/employees": {
|
|
586
|
+
relation: {
|
|
587
|
+
inverseOf: {
|
|
588
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
589
|
+
field: "/company"
|
|
590
|
+
}
|
|
591
|
+
}
|
|
592
|
+
}
|
|
593
|
+
})
|
|
594
|
+
export const Group = entity("group", "Group", {
|
|
595
|
+
"/members": {
|
|
596
|
+
relation: {
|
|
597
|
+
inverseOf: {
|
|
598
|
+
schemaFqn: "com.acme.schemas.directory.person",
|
|
599
|
+
field: "/groups"
|
|
600
|
+
}
|
|
601
|
+
}
|
|
602
|
+
}
|
|
603
|
+
})
|
|
604
|
+
|
|
605
|
+
// Add these declarations to the existing package's primitives collection.
|
|
606
|
+
export const relationSchemas = [Person, Passport, Asset, Company, Group]
|
|
607
|
+
```
|
|
608
|
+
|
|
609
|
+
Only Person's forward properties accept writes. For example, `passport` and
|
|
610
|
+
`company` accept an ID or null; `assets` and `groups` accept ID arrays. One means
|
|
611
|
+
at most one, not required participation. Two independent forward declarations
|
|
612
|
+
would create two relationships; use `inverseOf` to expose the same links.
|
|
613
|
+
|
|
614
|
+
See the [relation field operator reference](../../../docs/reference/knowledge-relation-fields.md)
|
|
615
|
+
for SQL enforcement, safe cardinality changes, rollout and read limits. Package
|
|
616
|
+
comparison uses source-owned definitions; the host independently validates the
|
|
617
|
+
resolved inverse runtime shape. Authors never copy generated properties into
|
|
618
|
+
their ordinary schema.
|
|
619
|
+
|
|
620
|
+
The host rejects `onDelete: "restrict"` for targets with `managedProjection`
|
|
621
|
+
and for `core.schemas.directory.organization` and
|
|
622
|
+
`core.schemas.strategy.organization-context`; use `clear` for these targets.
|
|
623
|
+
This check also applies to effective same-release declarations and to incoming
|
|
624
|
+
references when a target becomes managed. Ordinary target schemas may still use
|
|
625
|
+
`restrict`. Physical deletion clears references under `clear`; logical deletion
|
|
626
|
+
preserves them and does not grant access to the archived target.
|
|
627
|
+
|
|
406
628
|
## Agent and Skill declarations
|
|
407
629
|
|
|
408
630
|
`declareSkill` declares a governed Skill: `instructions`, the `tools` it
|
|
@@ -576,6 +798,42 @@ export const salesGroup = declareOrganizationGroup({
|
|
|
576
798
|
The manifest stores the FQN string. A subgroup has no handle; name it by its
|
|
577
799
|
FQN string, also inside the same package.
|
|
578
800
|
|
|
801
|
+
## Service principal declarations
|
|
802
|
+
|
|
803
|
+
`servicePrincipal` declares one non-human identity with one Organization Role
|
|
804
|
+
and memberships in Groups declared by the same package. `version` is required
|
|
805
|
+
common SDK primitive metadata; it has no default and is independent of the
|
|
806
|
+
package version. `name` becomes the manifest's `displayName`.
|
|
807
|
+
|
|
808
|
+
```ts
|
|
809
|
+
import {
|
|
810
|
+
declarePackage,
|
|
811
|
+
servicePrincipal
|
|
812
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
813
|
+
|
|
814
|
+
const importer = servicePrincipal({
|
|
815
|
+
fqn: "acme.directory.importer",
|
|
816
|
+
name: "Importer",
|
|
817
|
+
version: "1.0.0",
|
|
818
|
+
organizationRole: "organization_operator",
|
|
819
|
+
groups: [salesGroup, "acme.directory.groups.sales.inside-sales.emea"]
|
|
820
|
+
})
|
|
821
|
+
|
|
822
|
+
export const directory = declarePackage({
|
|
823
|
+
manifest: { fqn: "acme.directory", name: "Directory", version: "1.0.0" },
|
|
824
|
+
components: [salesGroup, importer]
|
|
825
|
+
})
|
|
826
|
+
```
|
|
827
|
+
|
|
828
|
+
`organizationRole` is `organization_admin`, `organization_operator`, or
|
|
829
|
+
`organization_member`. `groups` is a required array; use `[]` for no memberships.
|
|
830
|
+
A root Group handle or a root/subgroup FQN is accepted and serialized as an FQN
|
|
831
|
+
string. Both `declarePackage` and `parsePackageManifest` require each referenced
|
|
832
|
+
Group to be declared in that same manifest. A matching FQN prefix, a package
|
|
833
|
+
dependency, or a Group's external parent does not make a Group package-owned.
|
|
834
|
+
The declaration contains no credentials or runtime implementation. Deployment
|
|
835
|
+
confirmation and runtime authorization belong to the Host.
|
|
836
|
+
|
|
579
837
|
## Organization Settings declarations
|
|
580
838
|
|
|
581
839
|
`declareOrganizationSettings` declares the settings of the Organization that
|
|
@@ -599,7 +857,7 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
599
857
|
domains: ["acme.example"],
|
|
600
858
|
connection: { setupKey: "okta" },
|
|
601
859
|
provisionMembers: true,
|
|
602
|
-
defaultRole: "
|
|
860
|
+
defaultRole: "organization_member"
|
|
603
861
|
}
|
|
604
862
|
],
|
|
605
863
|
applicationConsent: "ask"
|
|
@@ -626,8 +884,9 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
626
884
|
Organization SSO declaration of the same package or `{ providerId }` of a
|
|
627
885
|
pinned dependency; the manifest stores `{ fqn }` or `{ providerId }`.
|
|
628
886
|
Credentials arrive only through `connection: { setupKey }`.
|
|
629
|
-
`provisionMembers` and `defaultRole` (`organization_admin
|
|
630
|
-
`
|
|
887
|
+
`provisionMembers` and `defaultRole` (`organization_admin`,
|
|
888
|
+
`organization_operator`, or `organization_member`) are required. Retired roles
|
|
889
|
+
such as `organization_user` and Tenant roles are rejected by manifest admission. `applicationConsent` is `ask` or `skip`.
|
|
631
890
|
- `locale` holds `defaultLanguage`, `languages` and `timezone`. `governance`
|
|
632
891
|
holds `accessAuditRetentionMonths` and `maxGroupHierarchyDepth`, positive
|
|
633
892
|
integers. Domain claims, language codes and the depth range are host checks.
|
|
@@ -636,109 +895,133 @@ export const acmeSettings = declareOrganizationSettings({
|
|
|
636
895
|
manifest readers reject the same declarations; both use
|
|
637
896
|
`organizationSettingsViolation`.
|
|
638
897
|
|
|
639
|
-
## External application roles
|
|
898
|
+
## External application roles
|
|
640
899
|
|
|
641
|
-
`declareExternalApplication`
|
|
642
|
-
|
|
643
|
-
|
|
900
|
+
`declareExternalApplication` requires `userRoles` and accepts three optional
|
|
901
|
+
access fields: `serverRoles`, `defaultServerRole` and `groupBindings`. A
|
|
902
|
+
further optional field, `applicationConsent`, overrides the Application Consent
|
|
644
903
|
rule of the Organization for this application: `inherit` (the default) follows
|
|
645
904
|
the Organization, `ask` always prompts, `skip` never prompts.
|
|
646
905
|
|
|
647
|
-
The host stores and checks the roles, the Admitted Classes and the
|
|
648
|
-
[Declared Grants](#declared-grants) at install, and shows them to the
|
|
649
|
-
Organization admin. It does not yet read them when a user signs in to the
|
|
650
|
-
application or calls it.
|
|
651
|
-
|
|
652
906
|
```ts
|
|
653
|
-
export const
|
|
907
|
+
export const clinic = declareExternalApplication({
|
|
654
908
|
definition: {
|
|
655
909
|
// ...applicationType, audience, redirectUris, scopes, lifecycle
|
|
656
|
-
|
|
657
|
-
|
|
658
|
-
|
|
659
|
-
|
|
660
|
-
|
|
910
|
+
userRoles: [
|
|
911
|
+
{
|
|
912
|
+
key: "doctor",
|
|
913
|
+
platformPermissions: ["knowledge:read", "knowledge:manage"],
|
|
914
|
+
appPermissions: ["appointments:book"],
|
|
915
|
+
users: { create: true },
|
|
916
|
+
assignRoles: ["patient"],
|
|
917
|
+
visibility: "user"
|
|
918
|
+
},
|
|
919
|
+
{
|
|
920
|
+
key: "patient",
|
|
921
|
+
platformPermissions: [],
|
|
922
|
+
visibility: "declared",
|
|
923
|
+
bindings: {
|
|
924
|
+
knowledge: {
|
|
925
|
+
schemas: [
|
|
926
|
+
{ fqn: "acme.clinic.schemas.appointment", policy: "own-rows" }
|
|
927
|
+
]
|
|
928
|
+
},
|
|
929
|
+
agents: ["acme.clinic.agents.booking"]
|
|
930
|
+
}
|
|
931
|
+
},
|
|
932
|
+
{
|
|
933
|
+
key: "anonymous",
|
|
934
|
+
platformPermissions: [],
|
|
935
|
+
visibility: "declared",
|
|
936
|
+
bindings: { agents: ["acme.clinic.agents.booking"] }
|
|
937
|
+
}
|
|
938
|
+
],
|
|
939
|
+
serverRoles: [
|
|
940
|
+
{
|
|
941
|
+
key: "server",
|
|
942
|
+
platformPermissions: ["knowledge:read"],
|
|
943
|
+
users: { create: true },
|
|
944
|
+
assignRoles: ["patient"],
|
|
945
|
+
bindings: { workflows: "all" }
|
|
946
|
+
}
|
|
947
|
+
],
|
|
948
|
+
defaultServerRole: "server",
|
|
949
|
+
groupBindings: [
|
|
950
|
+
{
|
|
951
|
+
group: doctorsGroup,
|
|
952
|
+
role: "doctor",
|
|
953
|
+
lifecycle: { deployMode: "upsert", readonly: true }
|
|
954
|
+
}
|
|
661
955
|
]
|
|
662
956
|
},
|
|
663
|
-
manifest: { fqn: "acme.
|
|
664
|
-
presentation: { displayName: "
|
|
957
|
+
manifest: { fqn: "acme.clinic.application", version: "1.0.0" },
|
|
958
|
+
presentation: { displayName: "Clinic" }
|
|
665
959
|
})
|
|
666
960
|
```
|
|
667
961
|
|
|
668
|
-
-
|
|
669
|
-
`parent`,
|
|
962
|
+
- Every role has `key`, `platformPermissions`, and the optional fields
|
|
963
|
+
`parent`, `appPermissions`, `users: { create }`, `assignRoles` and
|
|
964
|
+
`replaces` (`ExternalApplicationRoleBase`).
|
|
965
|
+
- A User Role (`ExternalApplicationUserRole`) has `visibility`. `"user"`
|
|
966
|
+
(User Visibility) shows the resources that CI grants to the user; such a
|
|
967
|
+
role declares no `bindings`. `"declared"` (Declared Visibility) shows the
|
|
968
|
+
optional `bindings` of the role.
|
|
969
|
+
- A Server Role (`ExternalApplicationServerRole`) is the role of a call that
|
|
970
|
+
the application server makes. It has the optional `bindings`. When
|
|
971
|
+
`serverRoles` is not empty, `defaultServerRole` is required and names one of
|
|
972
|
+
them; the host uses it when a server call names no role.
|
|
973
|
+
- `bindings` is an `ExternalApplicationDeclaredBindings`: `knowledge.schemas`
|
|
974
|
+
and `knowledge.domains` list `{ fqn, policy? }` targets; `agents`, `skills`,
|
|
975
|
+
`workflows` and `documents` list FQNs. Each kind is `"all"` or a list; an
|
|
976
|
+
omitted kind binds nothing. The SDK checks the shape only; the host resolves
|
|
977
|
+
the FQNs.
|
|
670
978
|
- A `key` matches `^[a-z][a-z0-9]*(?:_[a-z0-9]+)*$`, holds at most 64
|
|
671
|
-
characters, and is declared one time
|
|
672
|
-
|
|
673
|
-
|
|
674
|
-
-
|
|
675
|
-
|
|
676
|
-
|
|
677
|
-
|
|
979
|
+
characters, and is declared one time among the User Roles and the Server
|
|
980
|
+
Roles of the application. A role keyed `anonymous` is a User Role with
|
|
981
|
+
Declared Visibility.
|
|
982
|
+
- A Platform Permission is a `resource:action` string. A resource may be
|
|
983
|
+
namespaced, as in `ai:catalog:read`. Each colon-separated segment starts with
|
|
984
|
+
a lowercase letter and contains only lowercase letters, digits or underscores;
|
|
985
|
+
empty segments are invalid. The SDK checks syntax only: `a:b:c` is valid
|
|
986
|
+
syntax, but the backend rejects permissions outside its known catalog.
|
|
987
|
+
App Permissions are strings that the application defines.
|
|
988
|
+
- `parent` is the key of another declared role of the same kind. A parent role
|
|
989
|
+
holds every Platform Permission and App Permission of each of its children,
|
|
990
|
+
and a role is not its own ancestor.
|
|
991
|
+
- `assignRoles` lists keys of User Roles of the same application that a holder
|
|
992
|
+
of the role can assign. `users.create` lets a holder create users.
|
|
678
993
|
- `replaces` is the key of a role that an earlier release declared and this
|
|
679
994
|
release removed. It cannot be a key of this release, and two roles cannot
|
|
680
995
|
replace the same key.
|
|
681
|
-
-
|
|
682
|
-
`
|
|
683
|
-
|
|
684
|
-
|
|
996
|
+
- The helper infers the declared keys, so TypeScript rejects a `parent`, an
|
|
997
|
+
`assignRoles` entry, a `defaultServerRole` or a Group Role Binding `role`
|
|
998
|
+
that is not a declared key of the right kind; the manifest stores plain
|
|
999
|
+
strings.
|
|
685
1000
|
- `declareExternalApplication` throws a `TypeError` for each violation and
|
|
686
1001
|
manifest readers reject the same declarations; both use
|
|
687
|
-
`externalApplicationViolation`.
|
|
1002
|
+
`externalApplicationViolation`. A violation message starts with the field
|
|
1003
|
+
path, for example `userRoles[1].parent:`.
|
|
688
1004
|
|
|
689
|
-
##
|
|
1005
|
+
## Group Role Bindings
|
|
690
1006
|
|
|
691
|
-
`
|
|
692
|
-
|
|
693
|
-
|
|
694
|
-
separate Grant declaration.
|
|
695
|
-
|
|
696
|
-
```ts
|
|
697
|
-
export const partnerPortal = declareExternalApplication({
|
|
698
|
-
definition: {
|
|
699
|
-
// ...applicationType, audience, redirectUris, scopes, lifecycle
|
|
700
|
-
roles: [
|
|
701
|
-
{ key: "manager", permissions: ["knowledge:read", "knowledge:manage"] },
|
|
702
|
-
{ key: "rep", parent: "manager", permissions: ["knowledge:read"] }
|
|
703
|
-
],
|
|
704
|
-
grants: [
|
|
705
|
-
{
|
|
706
|
-
group: salesGroup,
|
|
707
|
-
role: "rep",
|
|
708
|
-
lifecycle: { deployMode: "init_only", readonly: false }
|
|
709
|
-
},
|
|
710
|
-
{
|
|
711
|
-
group: "acme.directory.groups.sales.managers",
|
|
712
|
-
role: "manager",
|
|
713
|
-
lifecycle: { deployMode: "upsert", readonly: true }
|
|
714
|
-
}
|
|
715
|
-
]
|
|
716
|
-
},
|
|
717
|
-
manifest: { fqn: "acme.portal.application", version: "2.0.0" },
|
|
718
|
-
presentation: { displayName: "Partner portal" }
|
|
719
|
-
})
|
|
720
|
-
```
|
|
1007
|
+
`groupBindings` lists Group Role Bindings: the members of one Organization
|
|
1008
|
+
Group hold one User Role of the application. A package declares bindings only
|
|
1009
|
+
on its own external application.
|
|
721
1010
|
|
|
722
1011
|
- `group` is a `DeclarationReference<"organizationGroup">`: the handle that
|
|
723
1012
|
`declareOrganizationGroup` returns for a root Group of the same package, or
|
|
724
1013
|
the FQN string of any Group. Use the FQN string for a subgroup and for a
|
|
725
1014
|
Group that another package declares. TypeScript rejects a handle of another
|
|
726
1015
|
primitive kind. The manifest stores the FQN string in an
|
|
727
|
-
`
|
|
728
|
-
- The SDK does not check that the Group exists
|
|
729
|
-
|
|
730
|
-
|
|
731
|
-
|
|
732
|
-
|
|
733
|
-
|
|
734
|
-
|
|
735
|
-
lifecycle of the application. An item with no `deployMode` or no `readonly`
|
|
736
|
-
is rejected.
|
|
1016
|
+
`ExternalApplicationGroupBinding` item.
|
|
1017
|
+
- The SDK does not check that the Group exists; the host does.
|
|
1018
|
+
- `role` is the key of a User Role of the same declaration.
|
|
1019
|
+
- `coverage` is `"inherited"` (the default when omitted: members of subgroups
|
|
1020
|
+
also hold the role) or `"direct"` (members of the Group only).
|
|
1021
|
+
- `lifecycle` is a required `LifecycleOptions` of the binding, separate from
|
|
1022
|
+
the lifecycle of the application. An item with no `deployMode` or no
|
|
1023
|
+
`readonly` is rejected.
|
|
737
1024
|
- Two items cannot name the same Group and the same role.
|
|
738
|
-
- `declareExternalApplication` throws a `TypeError` for each violation and
|
|
739
|
-
manifest readers reject the same declarations. Both use
|
|
740
|
-
`externalApplicationViolation` for the Group, the role and the repeated
|
|
741
|
-
pair.
|
|
742
1025
|
|
|
743
1026
|
## Package Variables
|
|
744
1027
|
|
|
@@ -813,8 +1096,9 @@ export default declarePackage({
|
|
|
813
1096
|
- A handle never fits `fqn`, `version`, `kind`, a reference to another
|
|
814
1097
|
component by FQN (`templateFqn`, `schemaFqn`, ...), `lifecycle` or a schema
|
|
815
1098
|
projection (`VaryingExcludedKey`); manifest readers reject a marker there
|
|
816
|
-
with its path. The access model of an External Application (`
|
|
817
|
-
`
|
|
1099
|
+
with its path. The access model of an External Application (`userRoles`,
|
|
1100
|
+
`serverRoles`, `defaultServerRole`, `groupBindings`) and the `provider` of
|
|
1101
|
+
an SSO entry keep their shape.
|
|
818
1102
|
- Manifest readers admit the marker in every other definition value and keep
|
|
819
1103
|
it; cross-field rules that need the value run after substitution. The host
|
|
820
1104
|
owns substitution; `isVariableReference(value)` recognizes a marker and
|
|
@@ -979,12 +1263,7 @@ layout, create-step, and update-section metadata.
|
|
|
979
1263
|
|
|
980
1264
|
### Gateway declaration vocabulary
|
|
981
1265
|
|
|
982
|
-
|
|
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`,
|
|
1266
|
+
The SDK exports the JSON-only `PortableOperationDeclaration`,
|
|
988
1267
|
`OperationDomainDeclaration`, and `PortableGatewayDeclarations` types. They
|
|
989
1268
|
establish the shared operation manifest input vocabulary. Every portable
|
|
990
1269
|
operation explicitly carries its effect class, idempotency and bounded retry
|
|
@@ -1151,6 +1430,40 @@ the guard. They apply to ID targets too.
|
|
|
1151
1430
|
The core Invoke Workflow node exposes the same choice through its `target`
|
|
1152
1431
|
(a selected Workflow) and `targetFqn` configuration; set exactly one.
|
|
1153
1432
|
|
|
1433
|
+
### Tool settings option context
|
|
1434
|
+
|
|
1435
|
+
`ToolSettingsOptionsContext` contains only serializable values resolved by the
|
|
1436
|
+
Host before invoking an options provider. The optional `imageModelOptions`
|
|
1437
|
+
projection contains eligible image-output model IDs and human labels. Labels
|
|
1438
|
+
include the provider name when it distinguishes catalog entries. A missing
|
|
1439
|
+
projection supplies no image choices; packages must not infer eligibility from
|
|
1440
|
+
vision input or choose a replacement default.
|
|
1441
|
+
|
|
1442
|
+
The Host owns catalog authorization and model readiness. Portable options code
|
|
1443
|
+
can search and page this projection but receives no database access, service
|
|
1444
|
+
container, provider credentials or Host capability through it. Options execution
|
|
1445
|
+
keeps Host capabilities unavailable. The callback that fills the projection is
|
|
1446
|
+
a Host runtime binding; it is never portable declaration or manifest data.
|
|
1447
|
+
|
|
1448
|
+
### Built-in code runtimes
|
|
1449
|
+
|
|
1450
|
+
Every deployment seeds the built-in code runtimes under the same ids, so a
|
|
1451
|
+
package Workflow's core Code Block node names one through
|
|
1452
|
+
`builtInCodeRuntimeIds` instead of a per-deployment id:
|
|
1453
|
+
|
|
1454
|
+
```ts
|
|
1455
|
+
import { builtInCodeRuntimeIds } from "@collective-intelligence/extensions-sdk"
|
|
1456
|
+
|
|
1457
|
+
const parseNews = {
|
|
1458
|
+
language: "javascript",
|
|
1459
|
+
runtimeId: builtInCodeRuntimeIds.node24,
|
|
1460
|
+
source: "result = { items: [] }"
|
|
1461
|
+
}
|
|
1462
|
+
```
|
|
1463
|
+
|
|
1464
|
+
`node24` runs JavaScript on Node.js 24 and `python312` runs Python 3.12. The
|
|
1465
|
+
runtime language must match the node's `language`.
|
|
1466
|
+
|
|
1154
1467
|
## Executable implementations
|
|
1155
1468
|
|
|
1156
1469
|
The common declaration helpers accept structural implementation constructors,
|
|
@@ -1161,6 +1474,84 @@ specialized package. The common package deliberately does not export
|
|
|
1161
1474
|
`PackageTool`, `PackageRuntimeContext`, `defineCapability`,
|
|
1162
1475
|
`PackageFieldDefinition`, or `PackageWorkflowField`.
|
|
1163
1476
|
|
|
1477
|
+
### Declared connection instances
|
|
1478
|
+
|
|
1479
|
+
`declareConnectionInstance` provisions an Organization connection from an existing
|
|
1480
|
+
connection template. It uses the same `lifecycle` options as connector instances:
|
|
1481
|
+
`upsert` reconciles the package-owned resource, while `init_only` initializes it.
|
|
1482
|
+
The declaration FQN identifies the connection across deployments. Credentials use
|
|
1483
|
+
existing package variables; keep secret values outside release manifests.
|
|
1484
|
+
|
|
1485
|
+
```ts
|
|
1486
|
+
import {
|
|
1487
|
+
declareConnectionInstance,
|
|
1488
|
+
declareKnowledgeConnectorInstance,
|
|
1489
|
+
declarePackage,
|
|
1490
|
+
packageVariables
|
|
1491
|
+
} from "@collective-intelligence/extensions-sdk"
|
|
1492
|
+
|
|
1493
|
+
const variables = { notionToken: { type: "secret" } } as const
|
|
1494
|
+
const vars = packageVariables(variables)
|
|
1495
|
+
const templateFqn =
|
|
1496
|
+
"builtin.integrations.notion.connections.internal-integration-token"
|
|
1497
|
+
const connectionInstanceFqn = "acme.connections.notion"
|
|
1498
|
+
const lifecycle = { deployMode: "upsert", readonly: false } as const
|
|
1499
|
+
|
|
1500
|
+
const notionConnection = declareConnectionInstance({
|
|
1501
|
+
manifest: { fqn: connectionInstanceFqn, version: "1.0.0" },
|
|
1502
|
+
presentation: { displayName: "Company Notion" },
|
|
1503
|
+
definition: {
|
|
1504
|
+
templateFqn,
|
|
1505
|
+
lifecycle,
|
|
1506
|
+
credentials: { integrationToken: vars.notionToken }
|
|
1507
|
+
}
|
|
1508
|
+
})
|
|
1509
|
+
const notionConnector = declareKnowledgeConnectorInstance({
|
|
1510
|
+
manifest: { fqn: "acme.connectors.notion", version: "1.0.0" },
|
|
1511
|
+
presentation: { displayName: "Company Notion content" },
|
|
1512
|
+
definition: {
|
|
1513
|
+
templateFqn: "builtin.integrations.notion.connectors.api",
|
|
1514
|
+
lifecycle,
|
|
1515
|
+
connections: { notion: { connectionInstanceFqn } }
|
|
1516
|
+
}
|
|
1517
|
+
})
|
|
1518
|
+
export default declarePackage({
|
|
1519
|
+
manifest: {
|
|
1520
|
+
fqn: "acme",
|
|
1521
|
+
name: "Acme",
|
|
1522
|
+
version: "1.0.0",
|
|
1523
|
+
dependencies: [{ fqn: "builtin.integrations.notion" }]
|
|
1524
|
+
},
|
|
1525
|
+
variables,
|
|
1526
|
+
components: [notionConnection, notionConnector]
|
|
1527
|
+
})
|
|
1528
|
+
```
|
|
1529
|
+
|
|
1530
|
+
Use the connector template FQN and slot declared by your installed package.
|
|
1531
|
+
A Dataset connector selects the same reference in `definition.connection`.
|
|
1532
|
+
Connector selections accept exactly one of `{ setupKey }` and
|
|
1533
|
+
`{ connectionInstanceFqn }`. Tool and connector template `connectionRefs` can
|
|
1534
|
+
also set `connectionInstanceFqn` beside their required `connectionTemplateFqn`,
|
|
1535
|
+
`slot`, and `label`. The selected instance must use that exact template.
|
|
1536
|
+
FQNs and lifecycle remain static; they cannot be package-variable references.
|
|
1537
|
+
|
|
1538
|
+
Supply the secret through the existing deploy inputs:
|
|
1539
|
+
|
|
1540
|
+
```json
|
|
1541
|
+
{
|
|
1542
|
+
"variables": {
|
|
1543
|
+
"notionToken": { "link": "NOTION_INTEGRATION_TOKEN" }
|
|
1544
|
+
}
|
|
1545
|
+
}
|
|
1546
|
+
```
|
|
1547
|
+
|
|
1548
|
+
Declared connection references do not require an additional manual connection
|
|
1549
|
+
setup slot. A `secret` variable has no default. A missing linked Organization
|
|
1550
|
+
secret is created pending; fill its value through Organization variables before
|
|
1551
|
+
using the connection. Pending credentials stop provider calls. The Host validates
|
|
1552
|
+
template eligibility, credential fields, and secret references before provisioning.
|
|
1553
|
+
References may target this package or its declared dependencies.
|
|
1554
|
+
|
|
1164
1555
|
### Connections and connectors
|
|
1165
1556
|
|
|
1166
1557
|
`PackageConnection` implementations own advertised `test` and `discover`
|
|
@@ -1328,15 +1719,20 @@ portable `emailProvider` metadata: `connectionTemplateFqn` and `senderKind`.
|
|
|
1328
1719
|
`connectionTemplateFqn` names the connection template whose credential form
|
|
1329
1720
|
shapes the provider credentials. `senderKind` is `mailbox` for a provider that
|
|
1330
1721
|
always sends from a real mailbox, and `address` for every other provider.
|
|
1331
|
-
The optional `deploymentIdentity: "aws"` declares
|
|
1332
|
-
|
|
1333
|
-
|
|
1334
|
-
|
|
1722
|
+
The optional `deploymentIdentity: "aws" | "azure"` declares which installation
|
|
1723
|
+
identity the provider accepts for a tenant sender. The host authorizes the
|
|
1724
|
+
selection and supplies temporary AWS credentials or binds the backend SDK's
|
|
1725
|
+
`packageEmailToken` capability to the approved Azure resource. The declaration
|
|
1726
|
+
does not grant identity access or contain a tenant ID, client ID, token, or token
|
|
1727
|
+
file path. Organization senders use their authorized connection.
|
|
1335
1728
|
Declaration and portable manifest admission both reject an empty
|
|
1336
1729
|
`connectionTemplateFqn`, any other `senderKind`, and any other
|
|
1337
1730
|
`deploymentIdentity`. The implementation remains a
|
|
1338
|
-
runtime sidecar.
|
|
1339
|
-
|
|
1731
|
+
runtime sidecar. Network-free preparation, delivery attempts, acceptance,
|
|
1732
|
+
failure, replay, quota, and token capability contracts belong to
|
|
1733
|
+
[`extensions-sdk-backend`](../extensions-sdk-backend/README.md#email-providers).
|
|
1734
|
+
Keep provider protocol policy in the implementation; the declaration introduces
|
|
1735
|
+
no provider registry or credential acquisition behavior.
|
|
1340
1736
|
|
|
1341
1737
|
## Portable manifest admission
|
|
1342
1738
|
|
|
@@ -1376,25 +1772,39 @@ Declare `normalizesFieldMapValues: true` to let an adapter normalize each
|
|
|
1376
1772
|
provider value read by an inbound field-map rule before path, cast, or transform
|
|
1377
1773
|
handling. This leaves other providers' values untouched.
|
|
1378
1774
|
|
|
1379
|
-
##
|
|
1775
|
+
## FQN dependencies and immutable release declarations
|
|
1380
1776
|
|
|
1381
|
-
Package `dependencies` contain
|
|
1777
|
+
Package `dependencies` contain only package identities:
|
|
1382
1778
|
|
|
1383
1779
|
```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
|
-
]
|
|
1780
|
+
dependencies: [{ fqn: "com.acme.base" }]
|
|
1391
1781
|
```
|
|
1392
1782
|
|
|
1393
|
-
`declarePackage` and `
|
|
1394
|
-
|
|
1395
|
-
|
|
1396
|
-
`
|
|
1397
|
-
|
|
1783
|
+
`declarePackage`, `parsePackageManifest` and `parsePackageDependencies` reject
|
|
1784
|
+
`releaseId`, `releaseDigest`, duplicate FQNs and unknown dependency fields, and
|
|
1785
|
+
sort requirements by FQN without reordering caller arrays. `PackageDependency`
|
|
1786
|
+
is the portable `{ fqn: string }` type. `resolvePackageDependencyOrder` orders
|
|
1787
|
+
local declarations by their FQN requirements.
|
|
1788
|
+
|
|
1789
|
+
Every new install or update chooses the catalog's latest eligible dependency
|
|
1790
|
+
release for the target organization, using promotion order rather than semantic
|
|
1791
|
+
version order. An older automatically installable dependency is updated. A
|
|
1792
|
+
missing or different manual prerequisite blocks the operation. The backend
|
|
1793
|
+
retains exact selected IDs/digests in its accepted operation plan, so retries
|
|
1794
|
+
keep their accepted selections while a new invocation evaluates latest again.
|
|
1795
|
+
Builds stay offline; the SDK and CLI do not query dependency versions at build time.
|
|
1796
|
+
|
|
1797
|
+
Existing pinned installations require the [staged bridge-release cutover](../../../docs/reference/package-release-cli.md#cut-over-existing-pinned-installations)
|
|
1798
|
+
before strict Host rollout. Rebuilding and republishing alone cannot update old
|
|
1799
|
+
Desired/Serving manifests in place; normal uninstall retains their provenance.
|
|
1800
|
+
Bridge releases use the same components and empty dependencies under the old
|
|
1801
|
+
Host, followed by final FQN-only releases. Historical immutable archives and
|
|
1802
|
+
organization data are not rewritten or reset.
|
|
1803
|
+
|
|
1804
|
+
Existing concrete deployment checks still apply to catalog selections. A later
|
|
1805
|
+
promotion can select a lower semantic version, but strict deployment refuses that
|
|
1806
|
+
downgrade and preserves the installed selection. It reports the blocker instead
|
|
1807
|
+
of silently falling back to another release.
|
|
1398
1808
|
|
|
1399
1809
|
New release builders retain the portable declarations in
|
|
1400
1810
|
`ExtensionReleaseManifest.packageManifest` and include their canonical JSON bytes
|
|
@@ -1416,7 +1826,13 @@ then read it with `parseStoredExtensionReleaseManifest`, which maps each retired
|
|
|
1416
1826
|
kind (for example `tool_collection`) to its current spelling. The same read maps
|
|
1417
1827
|
the Organization Team names of earlier releases to Organization Group names: the
|
|
1418
1828
|
Agent audience key `organizationTeams`, and the managed projection names such as
|
|
1419
|
-
`directory_team`.
|
|
1829
|
+
`directory_team`. Historical Entity Relation Field cardinalities map `one` to
|
|
1830
|
+
`many_to_one` and `many` to `many_to_many`, preserving unbounded reverse sharing.
|
|
1831
|
+
The stored reader removes a valid redundant `maxItems` from legacy scalar `one`;
|
|
1832
|
+
list limits and all other relation settings remain intact. Malformed values still
|
|
1833
|
+
fail declaration validation. This conversion creates a read projection: retained
|
|
1834
|
+
release JSON, archive bytes and their provenance remain unchanged and must be
|
|
1835
|
+
verified before conversion.
|
|
1420
1836
|
`withCurrentPrimitiveKinds` applies the same mapping to stored JSON without
|
|
1421
1837
|
parsing it. `parseExtensionReleaseManifest` and `parsePackageManifest` accept
|
|
1422
1838
|
only the current spelling.
|
|
@@ -1686,6 +2102,49 @@ native semantics. Managed Datasets require `definition: DatasetDefinition` and
|
|
|
1686
2102
|
may specify an existing `templateFqn`/`templateConfig`; External Datasets require
|
|
1687
2103
|
`sourceLocation` and may retain a native `sourceMapping`.
|
|
1688
2104
|
|
|
2105
|
+
Two binding `fieldMap` rules fill Entity Relation Fields. A `reference` rule
|
|
2106
|
+
stores the remote ids at `remote` as Entity References to the entities of the
|
|
2107
|
+
target binding of the same connector instance. An `embedded` rule maps each
|
|
2108
|
+
nested object at `remote` through its own `fieldMap` into an entity of the
|
|
2109
|
+
target binding, creates it only when no entity has the remote id at `remoteId`,
|
|
2110
|
+
and stores Entity References to the result:
|
|
2111
|
+
|
|
2112
|
+
```ts
|
|
2113
|
+
fieldMap: [
|
|
2114
|
+
{
|
|
2115
|
+
op: "reference",
|
|
2116
|
+
local: "companies",
|
|
2117
|
+
remote: "associations.companies.results[].id",
|
|
2118
|
+
direction: "inbound",
|
|
2119
|
+
skipIfNull: true
|
|
2120
|
+
},
|
|
2121
|
+
{
|
|
2122
|
+
op: "embedded",
|
|
2123
|
+
local: "owner",
|
|
2124
|
+
remote: "creator",
|
|
2125
|
+
remoteId: "id",
|
|
2126
|
+
target: "contacts",
|
|
2127
|
+
fieldMap: [
|
|
2128
|
+
{
|
|
2129
|
+
op: "path",
|
|
2130
|
+
local: "email",
|
|
2131
|
+
remote: "email",
|
|
2132
|
+
direction: "inbound",
|
|
2133
|
+
skipIfNull: true
|
|
2134
|
+
}
|
|
2135
|
+
],
|
|
2136
|
+
direction: "inbound",
|
|
2137
|
+
skipIfNull: true
|
|
2138
|
+
}
|
|
2139
|
+
]
|
|
2140
|
+
```
|
|
2141
|
+
|
|
2142
|
+
`remote` is dot-separated keys, each optionally indexed (`results[0]`), with at
|
|
2143
|
+
most one `[]` segment that projects every array item. `target` is the binding
|
|
2144
|
+
key of the target schema; configuration validation requires it when the
|
|
2145
|
+
connector binds the target schema more than once. Manifest parsing refuses an
|
|
2146
|
+
`embedded` rule whose `fieldMap` holds another `embedded` rule.
|
|
2147
|
+
|
|
1689
2148
|
### Concrete Managed and External Datasets
|
|
1690
2149
|
|
|
1691
2150
|
Install the existing provider packages in the target Organization, or pin their
|
|
@@ -1865,3 +2324,34 @@ Add these settings to the existing schema declaration's `definition` object:
|
|
|
1865
2324
|
}
|
|
1866
2325
|
}
|
|
1867
2326
|
```
|
|
2327
|
+
|
|
2328
|
+
### Per-source run data access
|
|
2329
|
+
|
|
2330
|
+
`declareAgent`, `declareSkill`, and `declareWorkflow` accept optional
|
|
2331
|
+
`definition.dataAccess`. Its optional `knowledge`, `datasets`, and `documents`
|
|
2332
|
+
entries select `"user"` or the declaration's own kind (`"agent"`, `"skill"`, or
|
|
2333
|
+
`"workflow"`). The exported `DataAccess<Own>` type describes this portable
|
|
2334
|
+
contract. For example, an Agent can declare:
|
|
2335
|
+
|
|
2336
|
+
```ts
|
|
2337
|
+
import type { DataAccess } from "@collective-intelligence/extensions-sdk"
|
|
2338
|
+
|
|
2339
|
+
const dataAccess = {
|
|
2340
|
+
knowledge: "user",
|
|
2341
|
+
documents: "agent"
|
|
2342
|
+
} satisfies DataAccess<"agent">
|
|
2343
|
+
```
|
|
2344
|
+
|
|
2345
|
+
An omitted object or entry means the runtime's own kind. `user` selects the
|
|
2346
|
+
visibility of the identity the run acts for. The own-kind setting selects its
|
|
2347
|
+
configured resources, still limited by their own bindings. Each source is
|
|
2348
|
+
independent; the setting grants no additional tool or resource bindings.
|
|
2349
|
+
|
|
2350
|
+
Workflow declarations copy this setting into `definition.definition.dataAccess`
|
|
2351
|
+
(the portable authored graph) and retain it at `definition.dataAccess`. A
|
|
2352
|
+
setting supplied only on the graph is also accepted. When both locations are
|
|
2353
|
+
supplied, they must agree for every source after omitted entries default to
|
|
2354
|
+
`workflow`; conflicts are rejected. Canonical package manifests preserve these
|
|
2355
|
+
settings and reject unknown sources or another runtime's kind. These SDK checks
|
|
2356
|
+
validate declarations; the Host implements runtime authorization and per-step
|
|
2357
|
+
rechecks.
|