@collective-intelligence/extensions-sdk 0.1.1 → 0.1.3

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
@@ -104,6 +104,11 @@ Manual triggers may also declare a `lifecycleAdapterId` from
104
104
  `WorkflowTriggerLifecycleAdapterIds`; the Host resolves that exact ID to its
105
105
  publication or binding behavior without inspecting the trigger FQN and rejects
106
106
  IDs it does not implement.
107
+ A declared Workflow binds the `externalApplication` adapter to its own
108
+ package's application with `config: { applicationFqn }`; the Host resolves it
109
+ to that application's id in the installing Organization and fails the install
110
+ when it does not resolve. A declared Workflow must set `applicationFqn` and
111
+ must not set `applicationId`.
107
112
  Manual triggers may declare `invocationRole: "user" | "application"`, and
108
113
  `triggerRefPath` for a Studio-addressable reference. Event ingress may declare
109
114
  `callbackPathPath` for a token-authenticated webhook path. Publication copies
@@ -114,7 +119,10 @@ configuration keys.
114
119
  Action nodes that invoke another Workflow declare `reusableDependency` paths
115
120
  for the target Workflow ID and selected input contract, plus an optional
116
121
  `modePath` fixed-mode marker. The Host resolves these paths from the pinned
117
- declaration before persisting dependency edges.
122
+ declaration before persisting dependency edges. An optional
123
+ `targetWorkflowFqnPath` names a Workflow FQN alternative: when it holds a fixed
124
+ FQN, the Host persists no dependency edge and resolves the FQN at run time; a
125
+ node that sets both an FQN and a Workflow ID fails validation.
118
126
  `parseWorkflowReusableDependency` validates catalog values.
119
127
 
120
128
  Workflow node ports declare connection rules next to their `valueSchema`:
@@ -297,7 +305,11 @@ relation schemas and parked `relationFields`: `autocompleteConfiguration`,
297
305
  `usableAsDocumentScope`, and `versioningEnabled`. Domain declarations require
298
306
  `versioningEnabled`. External applications require `applicationType`,
299
307
  `audience`, `allowedOrigins`, `redirectUris`, `postLogoutRedirectUris`, and
300
- `scopes`. Tokens and client secrets are not declaration fields. Nullable
308
+ `scopes`. `redirectUris` lists every accepted callback. An optional
309
+ `primaryRedirectUri` names the default callback; it must be one of
310
+ `redirectUris`, and declaration and manifest parsing reject any other value.
311
+ When it is absent, the first redirect URI is the primary. Tokens and client
312
+ secrets are not declaration fields. Nullable
301
313
  persisted columns may be declared as `null`. Later construct types
302
314
  (`skillTemplate`) share the same `LifecycleOptions` type as an optional
303
315
  field. This package does not deploy, persist, or lock those declarations.
@@ -362,12 +374,12 @@ Organization or of the same package.
362
374
  class. An omitted field admits nobody of that class; an omitted `audience`
363
375
  admits nobody.
364
376
 
365
- | Field | Values | Admits |
366
- | ------------------- | ------------------------------- | ---------------------------------------------------------------------- |
367
- | `members` | `"all"`, `"selected"`, `"none"` | Organization members: every member, or the users administrators select |
368
- | `organizationTeams` | `"selected"`, `"none"` | Organization Teams that administrators select |
369
- | `applications` | application references | Applications that invoke the Agent as a service or bring visitors |
370
- | `anonymous` | `true` | Anonymous visitors that a listed application brings |
377
+ | Field | Values | Admits |
378
+ | -------------------- | ------------------------------- | ---------------------------------------------------------------------- |
379
+ | `members` | `"all"`, `"selected"`, `"none"` | Organization members: every member, or the users administrators select |
380
+ | `organizationGroups` | `"selected"`, `"none"` | Organization Groups that administrators select |
381
+ | `applications` | application references | Applications that invoke the Agent as a service or bring visitors |
382
+ | `anonymous` | `true` | Anonymous visitors that a listed application brings |
371
383
 
372
384
  ```ts
373
385
  declareAgent({
@@ -377,7 +389,7 @@ declareAgent({
377
389
  anonymous: true,
378
390
  applications: [storefront],
379
391
  members: "selected",
380
- organizationTeams: "selected"
392
+ organizationGroups: "selected"
381
393
  },
382
394
  ...
383
395
  },
@@ -385,7 +397,7 @@ declareAgent({
385
397
  })
386
398
  ```
387
399
 
388
- - Administrators select concrete users and Organization Teams inside this
400
+ - Administrators select concrete users and Organization Groups inside this
389
401
  maximum. They can only narrow it; they cannot widen it.
390
402
  - Organization administrators get no bypass for a declared Agent. An
391
403
  administrator outside the audience must add themselves to converse.
@@ -680,11 +692,89 @@ const pause: PackageWorkflowNodeResult<JsonObject> = {
680
692
  The owning package and host define condition kinds, payload meaning, modes,
681
693
  and resume ports. The base SDK carries JSON data without interpreting readiness
682
694
  or Documents policy. Existing approval, timer, and custom-mode pauses can omit
683
- `condition`; their other fields remain valid. `expiresAt` and `wakeAt` are still
695
+ `condition`; their other fields remain valid. An approval pause may set
696
+ `discloseSummary: true` when its author vouches that the rendered `summary` is
697
+ safe to show Approvers; the Host then shows it in the frozen approval context.
698
+ The field applies only to `mode: "approval"` and defaults to hidden. The Host
699
+ still omits a disclosed summary that contains a credential or personal data. `expiresAt` and `wakeAt` are still
684
700
  optional, and the SDK adds no default expiration. Typed pause results can be
685
701
  serialized with `canonicalJson`; execution, durable suspension, resume, and
686
702
  cancellation remain host responsibilities.
687
703
 
704
+ ### Workflow Prompt directives
705
+
706
+ A workflow node can ask the Host for a governed model call by returning
707
+ `directive: "prompt_text"` or `directive: "prompt_structured"`. Both carry
708
+ `system`, `user`, and an optional `model` tier. `prompt_structured` also
709
+ carries `responseSchema`, a JSON Schema `JsonObject` that the returned object
710
+ must satisfy:
711
+
712
+ ```ts
713
+ import type {
714
+ JsonObject,
715
+ PackageWorkflowNodeResult
716
+ } from "@collective-intelligence/extensions-sdk"
717
+
718
+ const tagging: PackageWorkflowNodeResult<JsonObject> = {
719
+ directive: "prompt_structured",
720
+ responseSchema: {
721
+ properties: { tags: { items: { type: "string" }, type: "array" } },
722
+ required: ["tags"],
723
+ type: "object"
724
+ },
725
+ system: "Tag the company.",
726
+ user: "Acme builds robots."
727
+ }
728
+ ```
729
+
730
+ The Host chooses the model and provider and emits the result on the node's
731
+ main output port: `{ kind: "text", text }` for `prompt_text`, and
732
+ `{ kind: "structured", object }` for `prompt_structured` once `object` satisfies
733
+ `responseSchema`. A schema
734
+ the Host cannot compile, or a model answer that is not valid JSON or does not
735
+ satisfy the schema, fails the step with a typed attempt error. The SDK carries
736
+ the schema as JSON data and does not validate it.
737
+
738
+ ### Workflow invocation directives
739
+
740
+ A workflow node starts a child Workflow run and waits for its terminal result
741
+ by returning `directive: "invoke_workflow"` with `childInput` and one target:
742
+ `childWorkflowId`, a Workflow ID in the run's Organization, or
743
+ `childWorkflowFqn`, the FQN of a Workflow a package installed there. A package
744
+ uses the FQN to name its own Workflows, whose IDs differ per installation:
745
+
746
+ ```ts
747
+ import type {
748
+ JsonObject,
749
+ PackageWorkflowNodeResult
750
+ } from "@collective-intelligence/extensions-sdk"
751
+
752
+ const enrich: PackageWorkflowNodeResult<JsonObject> = {
753
+ childInput: { entityId: "entity-1" },
754
+ childWorkflowFqn: "acme.sales.workflows.enrichment",
755
+ directive: "invoke_workflow"
756
+ }
757
+ ```
758
+
759
+ The Host resolves the FQN when the step runs, to the live Workflow installed
760
+ under that FQN in the run's Organization. Any installed package's Workflow
761
+ can be named, not only the invoking package's; resolution never leaves the
762
+ Organization. The step fails with a typed, non-retryable attempt error that an
763
+ authored `error` edge can route:
764
+
765
+ - `workflow_not_installed`: no live Workflow was installed under the FQN.
766
+ - `workflow_unavailable`: the installed Workflow is disabled or unpublished.
767
+ - `workflow_invocation_cycle`: the child is already running in the run's
768
+ invocation chain (it would invoke itself or an ancestor).
769
+ - `workflow_invocation_depth_exceeded`: the chain already holds 10 Workflows.
770
+
771
+ Publication records no dependency for an FQN target, so its cycles are not
772
+ caught when a Workflow is published; the run-time cycle and depth checks are
773
+ the guard. They apply to ID targets too.
774
+
775
+ The core Invoke Workflow node exposes the same choice through its `target`
776
+ (a selected Workflow) and `targetFqn` configuration; set exactly one.
777
+
688
778
  ## Executable implementations
689
779
 
690
780
  The common declaration helpers accept structural implementation constructors,
@@ -855,6 +945,23 @@ identity. The implementation remains a runtime sidecar. Executable request and
855
945
  context contracts belong to `extensions-sdk-backend` (`PackageOrganizationSso`);
856
946
  this package has no host or Effect dependency.
857
947
 
948
+ ### Email provider declarations
949
+
950
+ `declareEmailProvider` binds a structurally admitted provider constructor to
951
+ portable `emailProvider` metadata: `connectionTemplateFqn` and `senderKind`.
952
+ `connectionTemplateFqn` names the connection template whose credential form
953
+ shapes the provider credentials. `senderKind` is `mailbox` for a provider that
954
+ always sends from a real mailbox, and `address` for every other provider.
955
+ The optional `deploymentIdentity: "aws"` declares that the tenant may use the
956
+ deployment's own cloud identity instead of stored credentials; the host then
957
+ passes temporary `accessKeyId`, `secretAccessKey`, `sessionToken`, and `region`
958
+ as the credentials. An organization never uses it.
959
+ Declaration and portable manifest admission both reject an empty
960
+ `connectionTemplateFqn`, any other `senderKind`, and any other
961
+ `deploymentIdentity`. The implementation remains a
962
+ runtime sidecar. Executable send and failure contracts belong to
963
+ `extensions-sdk-backend` (`PackageEmailProvider`).
964
+
858
965
  ## Portable manifest admission
859
966
 
860
967
  Hosts receiving untrusted portable JSON can call
@@ -930,7 +1037,10 @@ the canonical metadata entry at the publishing boundary.
930
1037
  Releases stored before primitive kinds became camelCase keep their published
931
1038
  bytes. Hosts verify such an archive against the stored manifest JSON verbatim,
932
1039
  then read it with `parseStoredExtensionReleaseManifest`, which maps each retired
933
- kind (for example `tool_collection`) to its current spelling.
1040
+ kind (for example `tool_collection`) to its current spelling. The same read maps
1041
+ the Organization Team names of earlier releases to Organization Group names: the
1042
+ Agent audience key `organizationTeams`, and the managed projection names such as
1043
+ `directory_team`.
934
1044
  `withCurrentPrimitiveKinds` applies the same mapping to stored JSON without
935
1045
  parsing it. `parseExtensionReleaseManifest` and `parsePackageManifest` accept
936
1046
  only the current spelling.
@@ -1002,6 +1112,17 @@ configuration edits across the bundle. Child bindings, pipelines, schedules and
1002
1112
  policies share that lifecycle; runtime data, cursors and authorized execution are
1003
1113
  separate.
1004
1114
 
1115
+ An entity binding of a Knowledge gateway connector may declare
1116
+ `pushEntityMatch: "unique_fields"`. A pushed record then joins the live entity
1117
+ of the schema that already holds one of its unique field values, when no other
1118
+ connector owns it, and claims its unique values; a record whose unique value
1119
+ another connector's entity holds is quarantined instead of written. Declaring
1120
+ it lets the gateway take over any unowned entity whose unique value it pushes,
1121
+ such as an applicant a local workflow created, so reserve it for a gateway
1122
+ trusted to own those entities. The default `remote_ref` matches entities by
1123
+ remote record only. A push overwrites only the keys it carries in either mode.
1124
+ Pulls are unaffected.
1125
+
1005
1126
  ```ts
1006
1127
  import {
1007
1128
  declareKnowledgeConnectorInstance,
@@ -68,7 +68,7 @@ export declare const duplicateToolBinding: (tools: DeclaredToolBindings) => Tool
68
68
  export type AgentMemberAudience = "all" | "none" | "selected";
69
69
  /**
70
70
  * Code maximum of who may converse with an Agent, per caller class.
71
- * Administrators select concrete users and Organization Teams within it and
71
+ * Administrators select concrete users and Organization Groups within it and
72
72
  * may only narrow it. Omitted fields admit nobody of that class.
73
73
  */
74
74
  export type AgentAudience<Application = DeclarationReference<"externalApplication">> = Readonly<{
@@ -77,8 +77,8 @@ export type AgentAudience<Application = DeclarationReference<"externalApplicatio
77
77
  /** Applications that may invoke the Agent as a service or bring visitors. */
78
78
  applications?: readonly Application[];
79
79
  members?: AgentMemberAudience;
80
- /** "selected": administrators may admit Organization Teams. */
81
- organizationTeams?: "none" | "selected";
80
+ /** "selected": administrators may admit Organization Groups. */
81
+ organizationGroups?: "none" | "selected";
82
82
  }>;
83
83
  /** An `AgentAudience` in a manifest: applications are FQNs. */
84
84
  export type AgentAudienceDeclaration = AgentAudience<string>;
@@ -4,7 +4,7 @@ import type { ConsumerProfileId } from "../schema/profiles.js";
4
4
  import type { PackageSchemaProjection } from "../schema/projection.js";
5
5
  import type { PackageCodec, PackageCodecSource, PackageDecoder, PackageDecoderSource, PackageSchemaSource, SchemaDirection, SchemaValue } from "../schema/source.js";
6
6
  import type { PackagePrimitiveKind } from "./base.js";
7
- import type { DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrivesPage, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, KnowledgeRelationAdapterDeclaration } from "./connectors.js";
7
+ import type { DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrivesPage, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, EmailProviderDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, KnowledgeRelationAdapterDeclaration } from "./connectors.js";
8
8
  import type { PackagePrimitiveDeclaration } from "./declaration.js";
9
9
  import type { FieldOption, FieldOptionPage } from "./fields.js";
10
10
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
@@ -49,7 +49,7 @@ export type DeclarationHandle<Kind extends PackagePrimitiveKind> = DeclaredCompo
49
49
  export type DeclarationReference<Kind extends PackagePrimitiveKind> = DeclarationHandle<Kind> | string;
50
50
  /** The FQN a reference points at; manifests store references as FQNs. */
51
51
  export declare const referenceFqn: (reference: DeclarationReference<PackagePrimitiveKind>) => string;
52
- export type ExecutableManifest = DatasetParserDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | EventListenerDeclaration | ToolDeclaration | ToolSettingsOptionsDeclaration | WorkflowFieldDeclaration | WorkflowNodeDeclaration;
52
+ export type ExecutableManifest = DatasetParserDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ToolDeclaration | ToolSettingsOptionsDeclaration | WorkflowFieldDeclaration | WorkflowNodeDeclaration;
53
53
  export type MetadataComponentManifest = Exclude<PackagePrimitiveDeclaration, ExecutableManifest>;
54
54
  export type DefinitionInput<Manifest> = Omit<Manifest, "description" | "displayName" | "fqn" | "icon" | "kind" | "tags" | "version">;
55
55
  export type ClassDeclaration<Manifest, Constructor extends new () => object, Definition = DefinitionInput<Manifest>> = Readonly<{
@@ -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" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationSso" | "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" | "organizationSso" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "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;
@@ -32,11 +32,20 @@ export type KnowledgeConnectorInstanceBindingOptions = Readonly<{
32
32
  updateMode?: "full" | "partial";
33
33
  outboundStrategy?: "local_first" | "remote_first";
34
34
  }>;
35
+ export type KnowledgeConnectorPushEntityMatch = "remote_ref" | "unique_fields";
35
36
  export type KnowledgeConnectorInstanceEntityBinding = KnowledgeConnectorInstanceBindingOptions & Readonly<{
36
37
  schemaFqn: string;
37
38
  bindingMode: "managed" | "external";
38
39
  supportedBindingModes?: readonly ("managed" | "external")[];
39
40
  missingConnectorFieldsBehavior?: "prune" | "retain";
41
+ /**
42
+ * Which entity a Knowledge gateway push writes into. `remote_ref`
43
+ * (default) matches the entity attached to the pushed remote record.
44
+ * `unique_fields` also joins the live entity that already claims a
45
+ * pushed unique field value when no other connector owns it, and claims
46
+ * the unique values of every entity the push writes.
47
+ */
48
+ pushEntityMatch?: KnowledgeConnectorPushEntityMatch;
40
49
  suppressEntityEvents?: boolean;
41
50
  }>;
42
51
  export type KnowledgeConnectorInstanceRelationBinding = KnowledgeConnectorInstanceBindingOptions & Readonly<{
@@ -406,3 +406,16 @@ export type OrganizationSsoDeclaration = PackagePrimitiveBase<"organizationSso">
406
406
  markdown: string;
407
407
  }>[];
408
408
  }>;
409
+ /** Email provider metadata; the provider constructor remains a runtime sidecar. */
410
+ export type EmailProviderDeclaration = PackagePrimitiveBase<"emailProvider"> & Readonly<{
411
+ /** Connection template whose credential form shapes the provider credentials. */
412
+ connectionTemplateFqn: string;
413
+ /**
414
+ * The cloud identity of the deployment that the tenant may use instead of
415
+ * stored credentials. For `aws`, the host passes temporary `accessKeyId`,
416
+ * `secretAccessKey`, `sessionToken`, and `region` as the credentials.
417
+ */
418
+ deploymentIdentity?: "aws";
419
+ /** `mailbox` always sends from a real mailbox; `address` is every other provider. */
420
+ senderKind: "address" | "mailbox";
421
+ }>;
@@ -1,7 +1,7 @@
1
1
  import type { AgentDeclaration, SkillDeclaration } from "./agents.js";
2
2
  import type { DomainDeclaration, DomainTemplateDeclaration, SkillTemplateDeclaration } from "./catalog.js";
3
3
  import type { KnowledgeConnectorInstanceDeclaration, DatasetConnectorInstanceDeclaration } from "./connector-instances.js";
4
- import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, EventListenerDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration } from "./connectors.js";
4
+ import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, EmailProviderDeclaration, EventListenerDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration } from "./connectors.js";
5
5
  import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
6
6
  import type { ExternalApplicationDeclaration } from "./external-application.js";
7
7
  import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
@@ -9,4 +9,4 @@ import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.
9
9
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
10
10
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
11
11
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
12
- export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
12
+ 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 | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -2,7 +2,7 @@ import type { JsonValue } from "../foundation/json.js";
2
2
  import type { FormSchemaSource } from "../schema/forms.js";
3
3
  import type { SchemaValue } from "../schema/source.js";
4
4
  import type { ClassDeclaration, ClassDeclaredComponent, ConnectionClassDeclaration, ConnectionImplementation, EventListenerClassDeclaration, EventListenerImplementation, DocumentsConnectorClassDeclaration, DocumentsConnectorImplementation, FieldTransformerClassDeclaration, FieldTransformerImplementation, KnowledgeConnectorClassDeclaration, KnowledgeConnectorImplementation, KnowledgeConnectorOAuthClassDeclaration, KnowledgeConnectorOAuthImplementation, KnowledgeEntityAdapterClassDeclaration, KnowledgeEntityAdapterImplementation, KnowledgeRelationAdapterClassDeclaration, KnowledgeRelationAdapterImplementation, NotificationChannelClassDeclaration, NotificationChannelImplementation, ToolClassDeclaration, ToolImplementation, ToolSettingsOptionsClassDeclaration, ToolSettingsOptionsImplementation, WorkflowFieldClassDeclaration, WorkflowFieldImplementation, WorkflowFieldValue } from "./authoring-core.js";
5
- import type { ConnectionDeclaration, DocumentsConnectorDeclaration, EventListenerDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration } from "./connectors.js";
5
+ import type { ConnectionDeclaration, DocumentsConnectorDeclaration, EmailProviderDeclaration, EventListenerDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration } from "./connectors.js";
6
6
  import type { DatasetParserImplementation } from "./dataset-parser.js";
7
7
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
8
8
  import type { WorkflowFieldDeclaration } from "./workflows.js";
@@ -25,3 +25,8 @@ export type OrganizationSsoImplementation = Readonly<{
25
25
  exchangeCode: (...input: never[]) => object | PromiseLike<object>;
26
26
  }>;
27
27
  export declare const declareOrganizationSso: <Constructor extends new () => OrganizationSsoImplementation>(input: ClassDeclaration<OrganizationSsoDeclaration, Constructor>) => ClassDeclaredComponent<OrganizationSsoDeclaration, Constructor>;
28
+ /** Structural admission keeps host APIs and frameworks outside the base SDK. */
29
+ export type EmailProviderImplementation = Readonly<{
30
+ send: (...input: never[]) => object | PromiseLike<object>;
31
+ }>;
32
+ export declare const declareEmailProvider: <Constructor extends new () => EmailProviderImplementation>(input: ClassDeclaration<EmailProviderDeclaration, Constructor>) => ClassDeclaredComponent<EmailProviderDeclaration, Constructor>;
@@ -2,7 +2,7 @@ import type { PackagePrimitiveBase } from "./base.js";
2
2
  import type { LifecycleOptions } from "./lifecycle.js";
3
3
  export type ExternalApplicationType = "confidential" | "public";
4
4
  /**
5
- * Portable Public Application definition. Tokens and client secrets are never
5
+ * Portable External App definition. Tokens and client secrets are never
6
6
  * declared here; Dashboard rotate remains the credential path.
7
7
  */
8
8
  export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalApplication"> & Readonly<{
@@ -11,7 +11,15 @@ export type ExternalApplicationDeclaration = PackagePrimitiveBase<"externalAppli
11
11
  audience: string;
12
12
  lifecycle: LifecycleOptions;
13
13
  postLogoutRedirectUris: readonly string[];
14
+ /**
15
+ * Default callback of the application. It must be one of
16
+ * `redirectUris`; when absent, the first redirect URI is the primary.
17
+ */
18
+ primaryRedirectUri?: string;
19
+ /** Every accepted callback, including the primary redirect URI. */
14
20
  redirectUris: readonly string[];
15
21
  scopes: readonly string[];
16
22
  setupInstructions?: string;
17
23
  }>;
24
+ /** Shared authoring and serialized admission invariant for callbacks. */
25
+ export declare const externalApplicationViolation: ({ primaryRedirectUri, redirectUris }: Pick<ExternalApplicationDeclaration, "primaryRedirectUri" | "redirectUris">) => string | undefined;
@@ -14,15 +14,15 @@ export type KnowledgeFieldSemantics = Readonly<{
14
14
  indexContent?: boolean;
15
15
  indexOverview?: boolean;
16
16
  indexed?: boolean;
17
- managedProjectionSource?: "organization_team" | "organization_user";
17
+ managedProjectionSource?: "organization_group" | "organization_user";
18
18
  queryGuidance?: string;
19
19
  unique?: boolean;
20
20
  }>;
21
21
  export type KnowledgeManagedProjection = Readonly<{
22
22
  connectorPolicy: "allow" | "deny_schema";
23
23
  genericMutationPolicy: "deny_managed_fields" | "deny_schema";
24
- kind: "directory_person" | "directory_person_in_team" | "directory_team" | "directory_team_parent";
25
- source: "organization_team" | "organization_team_hierarchy" | "organization_team_membership" | "organization_user";
24
+ kind: "directory_person" | "directory_person_in_group" | "directory_group" | "directory_group_parent";
25
+ source: "organization_group" | "organization_group_hierarchy" | "organization_group_membership" | "organization_user";
26
26
  }>;
27
27
  export type KnowledgeFieldLocalization = Readonly<{
28
28
  description?: LocalizedFieldText;
@@ -6,6 +6,8 @@ export type PackageWorkflowPauseResumeContract = Readonly<{
6
6
  payload: JsonObject;
7
7
  }>;
8
8
  decisions?: readonly string[];
9
+ /** Approval only: the authored summary is safe to show Approvers. */
10
+ discloseSummary?: boolean;
9
11
  mode: string;
10
12
  payloadSchema?: JsonObject;
11
13
  resumePorts: readonly string[];
@@ -21,6 +23,11 @@ export type PackageWorkflowNodeDirective = Readonly<{
21
23
  childInput: JsonObject;
22
24
  childWorkflowId: string;
23
25
  directive: "invoke_workflow";
26
+ }> | Readonly<{
27
+ childInput: JsonObject;
28
+ /** Resolved at run time to the installed Workflow in the run's Organization. */
29
+ childWorkflowFqn: string;
30
+ directive: "invoke_workflow";
24
31
  }> | Readonly<{
25
32
  config: JsonObject;
26
33
  directive: "merge";
@@ -44,6 +51,13 @@ export type PackageWorkflowNodeDirective = Readonly<{
44
51
  model?: "balanced" | "complex" | "fast" | "super_fast";
45
52
  system: string;
46
53
  user: string;
54
+ }> | Readonly<{
55
+ directive: "prompt_structured";
56
+ model?: "balanced" | "complex" | "fast" | "super_fast";
57
+ /** JSON Schema the model's object must satisfy. */
58
+ responseSchema: JsonObject;
59
+ system: string;
60
+ user: string;
47
61
  }> | Readonly<{
48
62
  authorizedToolIds: readonly string[];
49
63
  directive: "skill";
@@ -179,10 +179,15 @@ export type WorkflowTriggerActivationDeclaration = Readonly<{
179
179
  }> | Readonly<{
180
180
  kind: "schedule";
181
181
  }>;
182
- /** Authored node paths used to persist a reusable Workflow dependency. */
182
+ /**
183
+ * Authored node paths used to persist a reusable Workflow dependency. A node
184
+ * whose `targetWorkflowFqnPath` holds a fixed FQN names its target by FQN; the
185
+ * Host resolves it at run time and persists no dependency.
186
+ */
183
187
  export type WorkflowReusableDependencyDeclaration = Readonly<{
184
188
  inputContractPath: readonly (number | string)[];
185
189
  modePath?: readonly (number | string)[];
190
+ targetWorkflowFqnPath?: readonly (number | string)[];
186
191
  targetWorkflowIdPath: readonly (number | string)[];
187
192
  }>;
188
193
  export type WorkflowNodeExecutionContract = Readonly<{
package/dist/index.d.ts CHANGED
@@ -12,7 +12,7 @@ export type { OperationDomainDeclaration, PortableGatewayDeclarations, PortableO
12
12
  export type { PackageCodec, PackageCodecSource, PackageDecoder, PackageDecoderSource, PackageSchemaDefinition, PackageSchemaIssue, PackageSchemaProjections, PackageSchemaResult, PackageSchemaSource, SchemaDirection, SchemaValue, SchemaWire } from "./schema/source.js";
13
13
  export type { JsonSchemaDocument, PackageSchemaProjection, ProjectionFidelity } from "./schema/projection.js";
14
14
  export type { ConsumerProfile, ConsumerProfileDiagnostic, ConsumerProfileId } from "./schema/profiles.js";
15
- export { declareKnowledgeEntityAdapter, declareConnection, declareDocumentsConnector, declareKnowledgeConnector, declareKnowledgeConnectorOAuth, declareEventListener, declareFieldTransformer, declareNotificationChannel, declareKnowledgeRelationAdapter, declareTool, declareToolSettingsOptions, declareWorkflowField, declareOrganizationSso } from "./components/executable-authoring.js";
15
+ export { declareKnowledgeEntityAdapter, declareConnection, declareDocumentsConnector, declareKnowledgeConnector, declareKnowledgeConnectorOAuth, declareEventListener, declareFieldTransformer, declareNotificationChannel, declareKnowledgeRelationAdapter, declareTool, declareToolSettingsOptions, declareWorkflowField, declareOrganizationSso, declareEmailProvider } from "./components/executable-authoring.js";
16
16
  export { declareWorkflowNode } from "./components/workflow-node-authoring.js";
17
17
  export { resolveWorkflowNodePorts, WorkflowPortIssueCodes } from "./components/workflow-ports.js";
18
18
  export type { WorkflowNodePortsContract, WorkflowPortIssue, WorkflowPortIssueCode, WorkflowResolvedPorts } from "./components/workflow-ports.js";
@@ -28,7 +28,8 @@ export type { BackendExecutionLane, BackendHostedContributionManifest, Extension
28
28
  export type { ComponentManifest, ComponentPresentation, DeclarationHandle, DeclarationReference, DeclaredComponent, DocumentsConnectorImplementation, PackageSchemaRuntimeSidecar, MetadataComponentManifest, ToolClassDeclaration, WorkflowFieldClassDeclaration, KnowledgeEntityAdapterClassDeclaration, ConnectionClassDeclaration, KnowledgeConnectorClassDeclaration, KnowledgeConnectorOAuthClassDeclaration, EventListenerClassDeclaration, FieldTransformerClassDeclaration, NotificationChannelClassDeclaration, KnowledgeRelationAdapterClassDeclaration, ToolSettingsOptionsClassDeclaration, WorkflowNodeClassDeclaration, WorkflowNodePortInput } from "./components/authoring-core.js";
29
29
  export type { DeclaredPackageComponent, DeclaredPackageManifest, PackageDefinition, PackageManifestInput, NormalizedPackageDefinition, PackageComponent } from "./package/definition.js";
30
30
  export type { StudioAppDeclaration, StudioAppDefinition, StudioAppPageDefinition, StudioAppSectionDefinition, StudioComponentDeclaration } from "./components/studio.js";
31
- export type { FieldUiSchema, FieldValidationRule, FieldVisibilityRule, FormMarkdownBlock, FormDefinition, FormMetadata, FormSchemaSource, FormLayout, FormSection, FormSectionItem, FormStep, FormWidget, PortableFormDefinition, SelectOption as FormSelectOption, SelectOptions, DynamicFormAiFillConfig, VisibilityCondition } from "./schema/forms.js";
31
+ export type { FieldUiSchema, FieldValidationRule, FieldVisibilityRule, FormMarkdownBlock, FormDefinition, FormMetadata, FormSchemaSource, FormLayout, FormSection, FormSectionItem, FormStep, FormWidget, PlainFormWidget, PortableFormDefinition, SelectFormWidget, SelectOption as FormSelectOption, SelectOptions, StructuredFileBrowserOptions, StructuredFileUploadOptions, DynamicFormAiFillConfig, VisibilityCondition } from "./schema/forms.js";
32
+ export { plainFormWidgets, selectFormWidgets } from "./schema/forms.js";
32
33
  export type { FieldOption, FieldOptionGroup, FieldOptionPage, FieldOptionsInput, FieldPart } from "./components/fields.js";
33
34
  export type { PackageWorkflowNodeExecutionResult, PackageWorkflowNodeDirective, PackageWorkflowPauseResumeContract, PackageWorkflowNodeResult } from "./components/workflow-results.js";
34
35
  export type { ConnectionDiscoveryCatalog, ConnectionDiscoveryCollection, ConnectionDiscoveryField, ConnectionDiscoveryMetadata, ConnectionDiscoveryMetadataValue, ConnectionDiscoveryRelationship, ConnectionDiscoveryResource, PackageConnectionProgress } from "./components/connections.js";
@@ -56,7 +57,7 @@ export type { JsonObject, JsonPrimitive, JsonValue } from "./foundation/json.js"
56
57
  export type { Bounds, Compatibility, ConnectorContext, DatasetAggregateOperation, DatasetBindingMode, DatasetDefinition, DatasetDeleteInput, DatasetDeleteResult, DatasetHealth, DatasetIngestInput, DatasetIngestMode, DatasetIngestResult, DatasetInspectInput, DatasetInspectResult, DatasetFilter, DatasetOperation, DatasetOrder, DatasetPredicate, DatasetPredicateOperator, DatasetQueryIntent, DatasetTimeBucket, DatasetProviderCapabilities, DatasetProviderError, DatasetProviderResult, DatasetProvisionInput, DatasetProvisionResult, DatasetRecordPage, DatasetResultPage, DatasetScalarType, DatasetSourceItem, DatasetSourceLocation, DatasetValue, DefinitionProposal, DiscoverDefinitionInput, ExternalDatasetBinding, ListSourcesInput, QueryInput, Readiness, ReadinessInput, SafeDiagnostic, SourcePage } from "./components/datasets.js";
57
58
  export type { DatasetParserAnalysis, DatasetParserColumnType, DatasetParserDefinition, DatasetParserDiagnostic, DatasetParserError, DatasetParserField, DatasetParserInput, DatasetParserRecord, DatasetParserRecordValue, DatasetParserRecords, DatasetParserRecordsInput, DatasetParserResult } from "./components/dataset-parser.js";
58
59
  export type { DatasetParserClassDeclaration, ExternalDatasetProviderClassDeclaration, ManagedDatasetProviderClassDeclaration } from "./components/metadata-authoring.js";
59
- export type { OrganizationSsoDeclaration } from "./components/connectors.js";
60
+ export type { EmailProviderDeclaration, OrganizationSsoDeclaration } from "./components/connectors.js";
60
61
  export { parsePackageManifest } from "./package/parse-manifest.js";
61
62
  export { WorkflowEditorWidgets, WorkflowTemplateKinds, WorkflowTriggerLifecycleAdapterIds } from "./components/workflows.js";
62
63
  export { parseWorkflowTriggerActivation } from "./package/workflow-readers.js";
@@ -65,5 +66,5 @@ export { parseJsonSchemaProjection } from "./package/readers.js";
65
66
  export { deriveWorkflowEditor, WorkflowJsonSchemaFormat } from "./components/workflow-editor.js";
66
67
  export type { WorkflowEditorDerivationInput } from "./components/workflow-editor.js";
67
68
  export { declareKnowledgeConnectorInstance, declareDatasetConnectorInstance } from "./components/metadata-authoring.js";
68
- export type { ConnectorInstanceConnection, KnowledgeConnectorInstanceDeclaration, DatasetConnectorInstanceDeclaration, KnowledgeConnectorInstanceSettings, KnowledgeConnectorInstanceRemoteFilters, KnowledgeConnectorInstanceBindingOptions, KnowledgeConnectorInstanceEntityBinding, KnowledgeConnectorInstanceRelationBinding, KnowledgeConnectorInstancePipeline, KnowledgeConnectorInstanceSchedule, KnowledgeConnectorInstanceDataPolicy, DatasetConnectorInstanceDataPolicy, DatasetConnectorInstanceSchedule } from "./components/connector-instances.js";
69
+ export type { ConnectorInstanceConnection, KnowledgeConnectorInstanceDeclaration, DatasetConnectorInstanceDeclaration, KnowledgeConnectorInstanceSettings, KnowledgeConnectorInstanceRemoteFilters, KnowledgeConnectorInstanceBindingOptions, KnowledgeConnectorInstanceEntityBinding, KnowledgeConnectorPushEntityMatch, KnowledgeConnectorInstanceRelationBinding, KnowledgeConnectorInstancePipeline, KnowledgeConnectorInstanceSchedule, KnowledgeConnectorInstanceDataPolicy, DatasetConnectorInstanceDataPolicy, DatasetConnectorInstanceSchedule } from "./components/connector-instances.js";
69
70
  export type { KnowledgePolicyBody, KnowledgePolicyPredicate, KnowledgePolicyRef } from "./components/knowledge.js";