@collective-intelligence/extensions-sdk 0.1.23 → 0.1.24

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
@@ -697,7 +697,7 @@ activates, and required `LifecycleOptions`. `declareAgent` declares an
697
697
  Organization Agent: its Role (`responsibility`, `objectives`,
698
698
  `operatingInstructions`, `behavioralBoundaries`), held `skills`, own `tools`,
699
699
  required `LifecycleOptions`, and optional `output: { schema }`, `modelTier`,
700
- `maxSteps`, `activity`, and `audience`. The output schema is a
700
+ `maxSteps`, `activity`, `audience`, and `bypassOrganizationInstructions`. The output schema is a
701
701
  `PackageCodec`, the same kind of source a Tool `output` takes, so an
702
702
  application can keep one runtime schema in its own contracts package and
703
703
  infer the consumer type from it. Install requires an administrator; built-in
@@ -709,6 +709,12 @@ installing Organization configured for that tier. An omitted tier runs on
709
709
  `balanced`. The former `modelPreset` field is retired; a manifest that still
710
710
  declares it is rejected.
711
711
 
712
+ `bypassOrganizationInstructions` is an optional boolean on `declareAgent`; an
713
+ omitted value is `false`. `true` runs the Agent without the Organization
714
+ Instructions of the Organization it is installed in. An administrator can force
715
+ the bypass off for one Organization, never on. Only an Agent declares it:
716
+ `declareSkill`, Studio Apps and Workflows have no such field.
717
+
712
718
  Reference fields (`skills`, `tools`, `audience.applications`) take a
713
719
  `DeclarationReference<Kind>`:
714
720
 
@@ -1034,6 +1040,44 @@ export const acmeSettings = declareOrganizationSettings({
1034
1040
  manifest readers reject the same declarations; both use
1035
1041
  `organizationSettingsViolation`.
1036
1042
 
1043
+ ## Organization Instructions declarations
1044
+
1045
+ `declareOrganizationInstructions` declares the organization-wide instructions
1046
+ that the platform gives the model in conversations with people, as one
1047
+ primitive of kind `organizationInstructions`. It is a component of its own, not
1048
+ a section of `declareOrganizationSettings`. A package declares at most one, and
1049
+ a package that declares one binds to the organization scope only:
1050
+ `declarePackage` rejects a second component of this kind and a manifest whose
1051
+ `bindingScopes` includes `tenant`.
1052
+
1053
+ ```ts
1054
+ export const acmeInstructions = declareOrganizationInstructions({
1055
+ definition: {
1056
+ enabled: true,
1057
+ toneOfVoice: "Warm and direct.",
1058
+ answerLength: "At most three sentences.",
1059
+ bannedQuestions: "Do not answer questions about salaries.",
1060
+ otherInstructions: "Always cite the knowledge source.",
1061
+ lifecycle: { deployMode: "upsert", readonly: true }
1062
+ },
1063
+ manifest: { fqn: "acme.directory.instructions", version: "1.0.0" },
1064
+ presentation: { displayName: "Acme instructions" }
1065
+ })
1066
+ ```
1067
+
1068
+ - `enabled` is a boolean. `toneOfVoice`, `answerLength`, `bannedQuestions` and
1069
+ `otherInstructions` are free text. Every one is optional, an omitted field
1070
+ leaves the current value of the Organization untouched, and the declaration
1071
+ needs at least one. The Host owns the length limit and the prompt wording.
1072
+ - Each value may be a Package Variable handle of its type.
1073
+ - `lifecycle` is a required `LifecycleOptions`.
1074
+ - `declareOrganizationInstructions` throws a `TypeError` for each violation and
1075
+ manifest readers reject the same declarations; both use
1076
+ `organizationInstructionsViolation`.
1077
+ - A package that declares the kind binds to the organization scope only.
1078
+ `declarePackage` and `parsePackageManifest` both reject `bindingScopes` that
1079
+ include `tenant`.
1080
+
1037
1081
  ## External application roles
1038
1082
 
1039
1083
  `declareExternalApplication` requires `userRoles` and accepts three optional
@@ -1226,6 +1270,7 @@ export default declarePackage({
1226
1270
  - A handle is a `PackageVariable<T>` where `T` is the value of its type (a
1227
1271
  `secret` is a `string`). `Varying<T>` is a value or a handle of that type;
1228
1272
  the definition inputs of `declareOrganizationSettings`,
1273
+ `declareOrganizationInstructions`,
1229
1274
  `declareExternalApplication`, `declareKnowledgeConnectorInstance` and
1230
1275
  `declareDatasetConnectorInstance` are typed with `VaryingDefinition`, so a
1231
1276
  `string` handle does not compile on a `number` field or on a list of
@@ -100,6 +100,12 @@ export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
100
100
  activity?: AgentActivityPolicy;
101
101
  audience?: AgentAudienceDeclaration;
102
102
  behavioralBoundaries: readonly string[];
103
+ /**
104
+ * Runs the Agent without the Organization Instructions. Omitted is
105
+ * `false`. An administrator may force it off for one Organization but
106
+ * never on.
107
+ */
108
+ bypassOrganizationInstructions?: boolean;
103
109
  lifecycle: LifecycleOptions;
104
110
  /** Open JSON for Studio extensions, such as `withStudioAgentForm`. */
105
111
  metadata?: JsonObject;
@@ -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" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "servicePrincipal" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
3
+ export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationInstructions" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "servicePrincipal" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
4
4
  export type PackagePrimitiveBase<Kind extends PackagePrimitiveKind> = Readonly<{
5
5
  description?: string;
6
6
  displayName: string;
@@ -7,10 +7,11 @@ import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
7
7
  import type { ExternalApplicationDeclaration } from "./external-application.js";
8
8
  import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
9
9
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
10
+ import type { OrganizationInstructionsDeclaration } from "./organization-instructions.js";
10
11
  import type { OrganizationSettingsDeclaration } from "./organization-settings.js";
11
12
  import type { ServicePrincipalDeclaration } from "./service-principal.js";
12
13
  import type { StudioAppDeclaration, StudioAppTemplateDeclaration, StudioComponentDeclaration } from "./studio.js";
13
14
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
14
15
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
15
16
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
16
- export type PackagePrimitiveDeclaration = ConnectionInstanceDeclaration | KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | ServicePrincipalDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
17
+ export type PackagePrimitiveDeclaration = ConnectionInstanceDeclaration | KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationInstructionsDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | ServicePrincipalDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -12,6 +12,7 @@ import type { ExternalApplicationAccessKey, ExternalApplicationDeclaration, Exte
12
12
  import type { KnowledgeEntitySchemaDeclaration, KnowledgeFieldSemantics, KnowledgeFileFieldDeclaration, KnowledgeUserFieldDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
13
13
  import type { LifecycleOptions } from "./lifecycle.js";
14
14
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
15
+ import type { OrganizationInstructionsDeclaration } from "./organization-instructions.js";
15
16
  import type { OrganizationSettingsDeclaration, VaryingOrganizationSettingsAuthentication, VaryingOrganizationSettingsSso } from "./organization-settings.js";
16
17
  import type { ServicePrincipalDeclaration } from "./service-principal.js";
17
18
  import type { StudioAppDeclaration, StudioAppDeclarationInput, StudioAppTemplateDeclaration, StudioComponentDeclaration } from "./studio.js";
@@ -68,6 +69,8 @@ type OrganizationSettingsAuthenticationInput = Omit<VaryingOrganizationSettingsA
68
69
  type OrganizationSettingsDefinitionInput = VaryingDefinition<Omit<MetadataDefinition<OrganizationSettingsDeclaration>, "authentication">> & Readonly<{
69
70
  authentication?: VaryingStructure<OrganizationSettingsAuthenticationInput>;
70
71
  }>;
72
+ /** Declares the conversation instructions of the Organization that installs the package. */
73
+ export declare const declareOrganizationInstructions: (input: MetadataClassDeclaration<OrganizationInstructionsDeclaration, VaryingMetadataDefinition<OrganizationInstructionsDeclaration>>) => DeclaredComponent<OrganizationInstructionsDeclaration>;
71
74
  /** Declares the settings of the Organization that installs the package. */
72
75
  export declare const declareOrganizationSettings: (input: MetadataClassDeclaration<OrganizationSettingsDeclaration, OrganizationSettingsDefinitionInput>) => DeclaredComponent<OrganizationSettingsDeclaration>;
73
76
  export declare const declareSkillTemplate: (input: MetadataClassDeclaration<SkillTemplateDeclaration>) => DeclaredComponent<SkillTemplateDeclaration>;
@@ -0,0 +1,25 @@
1
+ import type { VaryingDefinition } from "../package/variables.js";
2
+ import type { PackagePrimitiveBase } from "./base.js";
3
+ import type { LifecycleOptions } from "./lifecycle.js";
4
+ /**
5
+ * Portable Organization Instructions: organization-wide text for the model, in
6
+ * four labelled fields and an `enabled` flag. Every field is optional; an
7
+ * omitted field leaves the current value of the Organization untouched.
8
+ */
9
+ export type OrganizationInstructionsDeclaration = PackagePrimitiveBase<"organizationInstructions"> & Readonly<{
10
+ answerLength?: string;
11
+ bannedQuestions?: string;
12
+ enabled?: boolean;
13
+ lifecycle: LifecycleOptions;
14
+ otherInstructions?: string;
15
+ toneOfVoice?: string;
16
+ }>;
17
+ /** The declaration as manifest readers admit it, before substitution. */
18
+ export type VaryingOrganizationInstructions = VaryingDefinition<OrganizationInstructionsDeclaration>;
19
+ declare const fields: readonly ["answerLength", "bannedQuestions", "enabled", "otherInstructions", "toneOfVoice"];
20
+ /**
21
+ * Shared authoring and serialized admission invariant: at least one field. A
22
+ * Variable Reference counts as a field and is checked after substitution.
23
+ */
24
+ export declare const organizationInstructionsViolation: (definition: Pick<VaryingOrganizationInstructions, (typeof fields)[number]>) => string | undefined;
25
+ export {};
package/dist/index.d.ts CHANGED
@@ -20,7 +20,7 @@ export type { WorkflowNodePortsContract, WorkflowPortIssue, WorkflowPortIssueCod
20
20
  export { builtInCodeRuntimeIds } from "./components/workflow-code-runtimes.js";
21
21
  export { workflowSchemaAt } from "./components/workflow-schema.js";
22
22
  export type { WorkflowSchemaLocation } from "./components/workflow-schema.js";
23
- export { declareDatasetParser, declareDomain, declareDomainTemplate, declareExternalApplication, declareExternalAppGateway, declareExternalDatasetProvider, declareKnowledgeEntitySchema, declareKnowledgePolicy, declareKnowledgeRelationSchema, declareManagedDatasetProvider, declareOrganizationGroup, servicePrincipal, declareOrganizationSettings, declareRemoteToolCollection, declareSkillTemplate, declareStudioApp, declareStudioAppTemplate, declareStudioComponent, declareToolCollection, declareWorkflow, declareWorkflowFieldCollection, declareWorkflowNodeCollection, declareWorkflowTemplate } from "./components/metadata-authoring.js";
23
+ export { declareDatasetParser, declareDomain, declareDomainTemplate, declareExternalApplication, declareExternalAppGateway, declareExternalDatasetProvider, declareKnowledgeEntitySchema, declareKnowledgePolicy, declareKnowledgeRelationSchema, declareManagedDatasetProvider, declareOrganizationGroup, declareOrganizationInstructions, servicePrincipal, declareOrganizationSettings, declareRemoteToolCollection, declareSkillTemplate, declareStudioApp, declareStudioAppTemplate, declareStudioComponent, declareToolCollection, declareWorkflow, declareWorkflowFieldCollection, declareWorkflowNodeCollection, declareWorkflowTemplate } from "./components/metadata-authoring.js";
24
24
  export { DATASET_TABLE_TEMPLATE_PHYSICAL_CODES, DATASET_TABLE_TEMPLATE_SEMANTIC_ROLES, declareDatasetBlueprint, declareDatasetTableTemplate, rejectUnsupportedDatasetTableTemplate } from "./components/templates.js";
25
25
  export { declarePackage } from "./package/definition.js";
26
26
  export { isVariableReference, packageVariables, packageVariableTypes, packageVariableViolation, variableReference } from "./package/variables.js";
@@ -56,6 +56,8 @@ export { externalApplicationConsents, externalApplicationViolation } from "./com
56
56
  export type { ExternalApplicationAccessKey, ExternalApplicationBindingTargets, ExternalApplicationConsent, ExternalApplicationDeclaration, ExternalApplicationDeclaredBindings, ExternalApplicationGroupBinding, ExternalApplicationKnowledgeTarget, ExternalApplicationRoleBase, ExternalApplicationServerRole, ExternalApplicationType, ExternalApplicationUserRole, VaryingExternalApplication } from "./components/external-application.js";
57
57
  export { organizationGroupFqnMaxLength, organizationGroupNodes, organizationGroupViolation } from "./components/organization-group.js";
58
58
  export type { OrganizationGroupDeclaration, OrganizationSubgroup } from "./components/organization-group.js";
59
+ export { organizationInstructionsViolation } from "./components/organization-instructions.js";
60
+ export type { OrganizationInstructionsDeclaration, VaryingOrganizationInstructions } from "./components/organization-instructions.js";
59
61
  export { organizationSettingsViolation } from "./components/organization-settings.js";
60
62
  export type { OrganizationSettingsApplicationConsent, OrganizationSettingsAuthentication, OrganizationSettingsDeclaration, OrganizationSettingsLocalMethod, OrganizationSettingsMedia, OrganizationSettingsSso, OrganizationSettingsSsoRole, VaryingOrganizationSettings } from "./components/organization-settings.js";
61
63
  export { declareAgent, declareSkill, duplicateToolBinding, toolBindingDeclaration } from "./components/agents.js";