@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 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,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: "organization_user"
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` or
630
- `organization_user`) are required. `applicationConsent` is `ask` or `skip`.
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 and Admitted Classes
898
+ ## External application roles
640
899
 
641
- `declareExternalApplication` accepts two optional access fields: `roles`, the
642
- role tree of the application, and `admits`, the Admitted Classes ceiling. A
643
- third optional field, `applicationConsent`, overrides the Application Consent
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 partnerPortal = declareExternalApplication({
907
+ export const clinic = declareExternalApplication({
654
908
  definition: {
655
909
  // ...applicationType, audience, redirectUris, scopes, lifecycle
656
- admits: ["internal", "external"],
657
- roles: [
658
- { key: "admin", permissions: ["knowledge:read", "knowledge:manage"] },
659
- { key: "viewer", parent: "admin", permissions: ["knowledge:read"] },
660
- { key: "owner", permissions: ["knowledge:read"], replaces: "superuser" }
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.portal.application", version: "2.0.0" },
664
- presentation: { displayName: "Partner portal" }
957
+ manifest: { fqn: "acme.clinic.application", version: "1.0.0" },
958
+ presentation: { displayName: "Clinic" }
665
959
  })
666
960
  ```
667
961
 
668
- - A role is an `ExternalApplicationRole`: `key`, `permissions`, an optional
669
- `parent`, and an optional `replaces`.
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 in the application.
672
- - A permission is a `resource:action` string with one colon and no empty side.
673
- The SDK checks the shape only; the host checks that it knows the permission.
674
- - `parent` is the key of another declared role. A parent role holds every
675
- permission of each of its children, and a role is not its own ancestor. The
676
- helper infers the declared keys, so TypeScript rejects a `parent` that is not
677
- a declared key; the manifest stores plain strings.
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
- - `admits` is a list of `ExternalApplicationUserClass` values (`internal`,
682
- `external`) with at least one value and no repeated value. The Organization
683
- admin can narrow the list but cannot admit a class outside it. When `admits`
684
- is absent, the application admits internal users only.
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
- ## Declared Grants
1005
+ ## Group Role Bindings
690
1006
 
691
- `declareExternalApplication` accepts an optional `grants` list. Each item is a
692
- Declared Grant: one Organization Group holds one role of the application. A
693
- package declares Grants only on its own external application; there is no
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
- `ExternalApplicationGrant` item.
728
- - The SDK does not check that the Group exists. The host refuses the install
729
- when no Group of the Organization has that FQN and no package of the same
730
- operation declares it.
731
- - `role` is the key of a role that the same declaration declares. The helper
732
- infers the declared keys, so TypeScript rejects another key; the manifest
733
- stores a plain string.
734
- - `lifecycle` is a required `LifecycleOptions` of the Grant, separate from the
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 (`admits`,
817
- `grants`, `roles`) and the `provider` of an SSO entry keep their shape.
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
- 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`,
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 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.
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. Executable send and failure contracts belong to
1339
- `extensions-sdk-backend` (`PackageEmailProvider`).
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
- ## Exact dependencies and immutable release declarations
1775
+ ## FQN dependencies and immutable release declarations
1380
1776
 
1381
- Package `dependencies` contain exact immutable references, with no version ranges:
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 `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.
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.