@collective-intelligence/extensions-sdk 0.1.7 → 0.1.9

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
@@ -115,6 +115,63 @@ Manual triggers may declare `invocationRole: "user" | "application"`, and
115
115
  these values and the event kind/acquisition mode into normalized Host columns;
116
116
  repositories select by those columns instead of extension identity or private
117
117
  configuration keys.
118
+ `withStudioTriggerForm(trigger, { organizationGroup })` gives a user-invoked
119
+ trigger of a declared Workflow a Studio form, stored under the trigger's
120
+ `metadata.studioForm`. `organizationGroup` takes an Organization Group
121
+ declaration or FQN; CI Studio shows and runs the form only for users of that
122
+ Group, directly or through a subgroup. `readStudioTriggerForm` reads the form
123
+ back, and manifest admission rejects a malformed one.
124
+ The form may declare `fields`. A file field
125
+ `{ key, label, type: "file", accept?, maxBytes? }` shows an upload control; it
126
+ accepts `defaultStudioTriggerFormFileAccept` (PDF, JPEG, PNG) and at most
127
+ `maxStudioTriggerFormFileBytes` (10 MiB, also the ceiling for `maxBytes`)
128
+ unless it declares narrower ones. `key` holds letters, digits and `_`, unique in
129
+ the form. Studio stores the upload as a private stored file of the Organization
130
+ and starts the run only once every file field holds an upload, with
131
+ `form.<key> = { storageFileId }`; nodes bind
132
+ `{{ trigger.form.<key>.storageFileId }}`.
133
+ Typed fields hold a value the user types or picks: `{ key, label, type }` with
134
+ `type` `"text"` (string), `"textarea"` (multi-line string, such as a Markdown
135
+ body), `"number"` (finite number) or `"boolean"`;
136
+ `{ key, label, type: "enum", options: [{ label, value }] }` (one option
137
+ `value`; values unique, at least one option); and
138
+ `{ key, label, type: "json", schema }` for nested objects and lists, whose
139
+ value must satisfy the Draft 2020-12 JSON Schema `schema` and which Studio
140
+ edits as JSON text. A `schema` CI cannot compile strictly closes the form. The
141
+ run starts only once every field holds a value of its type, takes only the
142
+ declared fields, and nodes bind `{{ trigger.form.<key> }}` (or a path inside a
143
+ `json` value, such as `{{ trigger.form.request.company.name }}`).
144
+ A link opens the form prefilled: add the query parameter
145
+ `prefill.<triggerRef>` to the URL of the Studio page that places
146
+ `builtin:view.trigger-form` for that trigger. Its value is base64url (RFC 4648
147
+ §5, unpadded) of the UTF-8 JSON object `{ "<key>": value }`, at most 8192
148
+ characters. It may hold any subset of the typed fields and no file field. CI
149
+ checks every value against its field before the form opens, and refuses the
150
+ whole link otherwise; the user can change every value, and the run checks the
151
+ submitted values again. The link travels in browser history and server logs:
152
+ put no secrets in it.
153
+ An entities field is a searchable multi-select of the Organization's Knowledge
154
+ entities of one schema: `{ key, label, type: "entities", schemaFqn, valueKey?,
155
+ labelKey? }`. Studio offers only entities of `schemaFqn` in the user's
156
+ Organization that the user's Knowledge policies let them read, matching the
157
+ typed text against the entity name, through
158
+ `GET /studio/triggers/:triggerRef/fields/:fieldKey/options?q=` (the form's
159
+ Group gate applies). Each option shows the `labelKey` data field (the entity
160
+ name when omitted). The value is `{ entityIds, values }`: the picked entity
161
+ ids and, at the same index, each entity's string `valueKey` data field (its
162
+ id when omitted; an entity without it cannot be picked), at most 100 picks,
163
+ none required. The run starts only once every id is such an entity and every
164
+ value is that entity's; nodes bind `{{ trigger.form.<key>.values }}` for the
165
+ list of, for example, tag slugs, and `{{ trigger.form.<key>.entityIds }}` for
166
+ the ids. A prefill link may carry the same value; it is checked the same way.
167
+ `withStudioAgentForm(agent, { fields })` gives a declared Agent a Studio form,
168
+ stored under the Agent's `metadata.studioForm`; `readStudioAgentForm` reads it
169
+ back. `fields` takes exactly the trigger-form field types above (`file`,
170
+ `text`, `textarea`, `number`, `boolean`, `enum`, `json`, `entities`); any other
171
+ type, or a repeated key, fails at declaration and at manifest admission.
172
+ `builtin:view.agent-form` names the Agent by FQN in `props.agentRef`. A submit
173
+ runs the Agent for the Studio user, within the Agent's audience, with the JSON
174
+ object of the declared field values as its task.
118
175
 
119
176
  Action nodes that invoke another Workflow declare `reusableDependency` paths
120
177
  for the target Workflow ID and selected input contract, plus an optional
@@ -325,6 +382,27 @@ projects a Draft 2020-12 `knowledge_record` document (`enum`, `format`, root
325
382
  `type: "object"`, `required` array). Adapter-owned codecs still use
326
383
  `definePackageSchema`.
327
384
 
385
+ `declareKnowledgeEntitySchema` declares File fields in `fileFields`, keyed by
386
+ top-level property key. Each declaration takes `multiple`, `accepts` (matched
387
+ like the HTML `accept` attribute: MIME types, `type/*` wildcards or `.ext` file
388
+ name suffixes; empty for any) and an optional `visibility` (`public`, `protected` or
389
+ `private`; Protected when absent):
390
+
391
+ ```ts
392
+ fileFields: {
393
+ resume: { accepts: ["application/pdf"], multiple: false, visibility: "private" }
394
+ }
395
+ ```
396
+
397
+ The declaration compiles into `fieldSemantics["/resume"]`:
398
+ `{ file: { accepts, multiple }, mediaVisibility }`, merged with the other
399
+ authored semantics of that pointer. The schema must not define the property;
400
+ the platform generates the File value schema at install. Localization,
401
+ presentation and semantics pointers may address the File field. Declaration
402
+ rejects a raw `fieldSemantics` `file` entry, a `mediaVisibility` on a pointer
403
+ that is not a declared File field (relation schemas have none), and a File field
404
+ with both `visibility` and a raw `mediaVisibility`.
405
+
328
406
  ## Agent and Skill declarations
329
407
 
330
408
  `declareSkill` declares a governed Skill: `instructions`, the `tools` it
@@ -990,7 +1068,11 @@ or Documents policy. Existing approval, timer, and custom-mode pauses can omit
990
1068
  `discloseSummary: true` when its author vouches that the rendered `summary` is
991
1069
  safe to show Approvers; the Host then shows it in the frozen approval context.
992
1070
  The field applies only to `mode: "approval"` and defaults to hidden. The Host
993
- still omits a disclosed summary that contains a credential or personal data. `expiresAt` and `wakeAt` are still
1071
+ still omits a disclosed summary that contains a credential or personal data. An
1072
+ approval pause may also set `invokerDecision: "explicit"`: the Host then opens
1073
+ the Request pending, with no automatic approval for the person who started the
1074
+ run, who stays an eligible Approver when the Rule allows it. The default,
1075
+ `"automatic"`, keeps that automatic approval. `expiresAt` and `wakeAt` are still
994
1076
  optional, and the SDK adds no default expiration. Typed pause results can be
995
1077
  serialized with `canonicalJson`; execution, durable suspension, resume, and
996
1078
  cancellation remain host responsibilities.
@@ -1740,3 +1822,46 @@ Fill `fields` with the native connection template's required credentials.
1740
1822
  `connectionId` must match the Organization and expected template. The backend
1741
1823
  validates ownership, executable references and native configuration. Installation
1742
1824
  configures resources; native schedules and authorized manual actions execute work.
1825
+
1826
+ Knowledge schemas select item embedding fields with
1827
+ `definition.fieldSemantics["/full/pointer"].includeInItemEmbedding: true`.
1828
+ Omitted and `false` values leave the field out. Select scalar values or lists of
1829
+ scalars; nested fields use full RFC 6901 JSON pointers (`~1` escapes `/`, `~0`
1830
+ escapes `~`). Objects, files, and relation traversal cannot be selected as item
1831
+ values. When the schema's `embedEntities` gate is enabled, its item vector contains
1832
+ only the selected values as one bounded YAML document, without chunking or an item overview. Empty selection
1833
+ produces no item vector and a visible configuration status. Unsupported selected
1834
+ values or input exceeding the embedding model's budget produce a visible failure;
1835
+ values are not silently truncated.
1836
+
1837
+ `embedded: true` independently enables passage indexing for an ordinary text
1838
+ field. Item selection never enables passage indexing, and existing `indexed`,
1839
+ `defaultSearch`, or file-content flags never select a field for the item vector.
1840
+ For example, `fieldSemantics: { "/name": { includeInItemEmbedding: true },
1841
+ "/notes": { includeInItemEmbedding: false, embedded: true } }` keeps the name in
1842
+ the item vector and searches notes as separate passages. These settings are
1843
+ portable schema declarations and use the same admission and live configuration
1844
+ rules as administration and Knowledge Setup.
1845
+
1846
+ ### File overview settings
1847
+
1848
+ Knowledge schema declarations can set nullable `overviewInputMaxChars` and
1849
+ `richEnrichment`. A FileField can override each setting through its pointer in
1850
+ `definition.fieldSemantics`. The budget is an integer from 1 to 1,000,000.
1851
+ Omission or `null` inherits; `false` explicitly disables rich enrichment.
1852
+ Resolution follows product defaults (4,000 characters and enrichment off),
1853
+ organization settings, schema settings, then the FileField override. The cheap
1854
+ overview summarizes the bounded extracted-text prefix in exactly three sentences;
1855
+ rich enrichment is separately opt-in.
1856
+
1857
+ Add these settings to the existing schema declaration's `definition` object:
1858
+
1859
+ ```ts
1860
+ {
1861
+ overviewInputMaxChars: 2000,
1862
+ richEnrichment: true,
1863
+ fieldSemantics: {
1864
+ "/cv": { overviewInputMaxChars: 500, richEnrichment: false }
1865
+ }
1866
+ }
1867
+ ```
@@ -99,6 +99,8 @@ export type AgentDeclaration = PackagePrimitiveBase<"agent"> & Readonly<{
99
99
  audience?: AgentAudienceDeclaration;
100
100
  behavioralBoundaries: readonly string[];
101
101
  lifecycle: LifecycleOptions;
102
+ /** Open JSON for Studio extensions, such as `withStudioAgentForm`. */
103
+ metadata?: JsonObject;
102
104
  /** Step limit; omitted uses the CI safety-limit setting. */
103
105
  maxSteps?: number;
104
106
  /**
@@ -1,6 +1,6 @@
1
1
  import type { VisibilityCondition } from "../schema/forms.js";
2
2
  export type BindingScope = "organization" | "tenant";
3
- export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
3
+ export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgeRelationSchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "knowledgeRelationAdapter" | "skill" | "skillTemplate" | "studioApp" | "studioAppTemplate" | "studioComponent" | "tool" | "toolCollection" | "toolSettingsOptions" | "workflow" | "workflowField" | "workflowFieldCollection" | "workflowNode" | "workflowNodeCollection" | "workflowTemplate";
4
4
  export type PackagePrimitiveBase<Kind extends PackagePrimitiveKind> = Readonly<{
5
5
  description?: string;
6
6
  displayName: string;
@@ -7,8 +7,8 @@ import type { ExternalApplicationDeclaration } from "./external-application.js";
7
7
  import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
8
8
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
9
9
  import type { OrganizationSettingsDeclaration } from "./organization-settings.js";
10
- import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.js";
10
+ import type { StudioAppDeclaration, StudioAppTemplateDeclaration, StudioComponentDeclaration } from "./studio.js";
11
11
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
12
12
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
13
13
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
14
- export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
14
+ export type PackagePrimitiveDeclaration = KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | KnowledgeRelationSchemaDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | KnowledgeRelationAdapterDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;
@@ -7,14 +7,46 @@ export type LocalizedFieldText = Readonly<{
7
7
  fallbackLocale: string;
8
8
  values: Readonly<Record<string, string>>;
9
9
  }>;
10
+ /**
11
+ * Makes a top-level property a File field: its value is generated by the
12
+ * host, `accepts` lists accepted files like the HTML `accept` attribute
13
+ * (MIME types, `type/*` wildcards or `.ext` suffixes; empty for any) and
14
+ * `multiple` allows several files.
15
+ */
16
+ export type KnowledgeFileField = Readonly<{
17
+ accepts: readonly string[];
18
+ multiple: boolean;
19
+ }>;
20
+ /**
21
+ * Declares a File field by its top-level property key. It compiles into the
22
+ * File field entry and `mediaVisibility` of `fieldSemantics["/<key>"]`. The
23
+ * schema does not define the property: the platform generates its value
24
+ * schema. A `visibility` that is not declared is Protected.
25
+ */
26
+ export type KnowledgeFileFieldDeclaration = KnowledgeFileField & Readonly<{
27
+ visibility?: KnowledgeFieldSemantics["mediaVisibility"];
28
+ }>;
10
29
  export type KnowledgeFieldSemantics = Readonly<{
30
+ /** Extracted-text prefix budget; null or omission inherits the schema/organization default. */
31
+ overviewInputMaxChars?: number | null;
32
+ /** Separate whole-file enrichment; explicit false overrides an enabled ancestor. */
33
+ richEnrichment?: boolean | null;
11
34
  defaultSearch?: boolean;
12
35
  embedded?: boolean;
36
+ /** Include this scalar or scalar-list field in the item YAML vector; omitted means off. */
37
+ includeInItemEmbedding?: boolean;
13
38
  faceted?: boolean;
39
+ file?: KnowledgeFileField;
14
40
  indexContent?: boolean;
15
41
  indexOverview?: boolean;
16
42
  indexed?: boolean;
17
43
  managedProjectionSource?: "organization_group" | "organization_user";
44
+ /**
45
+ * Who may fetch the files of a File field through their Stable Media URL:
46
+ * `public` anyone, `protected` (the default) a reader of the entity,
47
+ * `private` a principal that may manage Knowledge.
48
+ */
49
+ mediaVisibility?: "private" | "protected" | "public";
18
50
  queryGuidance?: string;
19
51
  unique?: boolean;
20
52
  }>;
@@ -100,6 +132,8 @@ export type KnowledgeEntitySchemaDeclaration = PackagePrimitiveBase<"knowledgeEn
100
132
  displayNameExpression: string | null;
101
133
  domainFqn: string;
102
134
  embedEntities?: boolean;
135
+ overviewInputMaxChars?: number | null;
136
+ richEnrichment?: boolean | null;
103
137
  embeddingConfig: JsonObject | null;
104
138
  extendsSchemaFqn?: string;
105
139
  fieldLocalization?: Readonly<Record<string, KnowledgeFieldLocalization>>;
@@ -8,11 +8,11 @@ import type { DatasetParserImplementation } from "./dataset-parser.js";
8
8
  import type { ExternalDatasetProviderImplementation, ManagedDatasetProviderImplementation } from "./datasets.js";
9
9
  import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
10
10
  import type { ExternalApplicationAccessKey, ExternalApplicationDeclaration, ExternalApplicationRole } from "./external-application.js";
11
- import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
11
+ import type { KnowledgeEntitySchemaDeclaration, KnowledgeFieldSemantics, KnowledgeFileFieldDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
12
12
  import type { LifecycleOptions } from "./lifecycle.js";
13
13
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
14
14
  import type { OrganizationSettingsDeclaration, VaryingOrganizationSettingsAuthentication, VaryingOrganizationSettingsSso } from "./organization-settings.js";
15
- import type { StudioAppDeclaration, StudioComponentDeclaration } from "./studio.js";
15
+ import type { StudioAppDeclaration, StudioAppDeclarationInput, StudioAppTemplateDeclaration, StudioComponentDeclaration } from "./studio.js";
16
16
  import type { RemoteToolCollectionDeclaration, RemoteToolCollectionDefinition, ToolCollectionDeclaration } from "./tools.js";
17
17
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowNodeCollectionDeclaration, WorkflowTemplateDeclaration, WorkflowTemplateGraphDefinition } from "./workflows.js";
18
18
  type MetadataDefinition<Manifest> = Manifest extends MetadataComponentManifest ? Omit<Manifest, "description" | "displayName" | "fqn" | "icon" | "kind" | "tags" | "version"> : never;
@@ -67,10 +67,16 @@ type OrganizationSettingsDefinitionInput = VaryingDefinition<Omit<MetadataDefini
67
67
  /** Declares the settings of the Organization that installs the package. */
68
68
  export declare const declareOrganizationSettings: (input: MetadataClassDeclaration<OrganizationSettingsDeclaration, OrganizationSettingsDefinitionInput>) => DeclaredComponent<OrganizationSettingsDeclaration>;
69
69
  export declare const declareSkillTemplate: (input: MetadataClassDeclaration<SkillTemplateDeclaration>) => DeclaredComponent<SkillTemplateDeclaration>;
70
- type KnowledgeEntityDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeEntitySchemaDeclaration>, "schema"> & Readonly<{
70
+ /** Authored field semantics; File field entries come from `fileFields`. */
71
+ type KnowledgeFieldSemanticsInput = Readonly<Record<string, Omit<KnowledgeFieldSemantics, "file">>>;
72
+ type KnowledgeEntityDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeEntitySchemaDeclaration>, "fieldSemantics" | "schema"> & Readonly<{
73
+ fieldSemantics?: KnowledgeFieldSemanticsInput;
74
+ /** The File fields of the schema, by top-level property key. */
75
+ fileFields?: Readonly<Record<string, KnowledgeFileFieldDeclaration>>;
71
76
  schema: DecoderSource<Schema>;
72
77
  }>;
73
- type KnowledgeRelationDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeRelationSchemaDeclaration>, "schema" | "lifecycle"> & Readonly<{
78
+ type KnowledgeRelationDefinitionInput<Schema> = Omit<MetadataDefinition<KnowledgeRelationSchemaDeclaration>, "fieldSemantics" | "schema" | "lifecycle"> & Readonly<{
79
+ fieldSemantics?: KnowledgeFieldSemanticsInput;
74
80
  lifecycle: LifecycleOptions;
75
81
  schema: DecoderSource<Schema>;
76
82
  }>;
@@ -95,7 +101,14 @@ export declare const declareExternalAppGateway: (input: MetadataClassDeclaration
95
101
  export declare const declareRemoteToolCollection: (input: MetadataClassDeclaration<RemoteToolCollectionDeclaration, RemoteToolCollectionDefinition>) => DeclaredComponent<RemoteToolCollectionDeclaration>;
96
102
  export declare const declareWorkflowFieldCollection: (input: MetadataClassDeclaration<WorkflowFieldCollectionDeclaration>) => DeclaredComponent<WorkflowFieldCollectionDeclaration>;
97
103
  export declare const declareWorkflowNodeCollection: (input: MetadataClassDeclaration<WorkflowNodeCollectionDeclaration>) => DeclaredComponent<WorkflowNodeCollectionDeclaration>;
98
- export declare const declareStudioApp: (input: MetadataClassDeclaration<StudioAppDeclaration>) => DeclaredComponent<StudioAppDeclaration>;
104
+ /**
105
+ * Declares a Declared Studio App: CI creates and publishes it on install, and
106
+ * the package owns it. References become FQNs; a view's `triggerRef` prop
107
+ * also accepts the trigger handle.
108
+ */
109
+ export declare const declareStudioApp: (input: StudioAppDeclarationInput) => DeclaredComponent<StudioAppDeclaration>;
110
+ /** Declares a Studio App Template that the builder copies into a new app. */
111
+ export declare const declareStudioAppTemplate: (input: MetadataClassDeclaration<StudioAppTemplateDeclaration>) => DeclaredComponent<StudioAppTemplateDeclaration>;
99
112
  type StudioComponentDefinitionInput<Schema> = Omit<MetadataDefinition<StudioComponentDeclaration>, "propsSchema"> & Readonly<{
100
113
  propsSchema: DecoderSource<Schema>;
101
114
  }>;
@@ -0,0 +1,25 @@
1
+ import type { JsonObject } from "../foundation/json.js";
2
+ import type { ReadValue } from "../package/readers.js";
3
+ import type { AgentDeclaration } from "./agents.js";
4
+ import type { DeclaredComponent } from "./authoring-core.js";
5
+ import type { StudioTriggerFormField } from "./studio.js";
6
+ /**
7
+ * The Studio form of an Agent. `builtin:view.agent-form` renders its fields
8
+ * and runs the Agent with the filled values as the task. The fields are the
9
+ * trigger-form fields.
10
+ */
11
+ export type StudioAgentFormDeclaration = Readonly<{
12
+ fields: readonly StudioTriggerFormField[];
13
+ }>;
14
+ /** Admits Agent metadata whose Studio form, when present, is well formed. */
15
+ export declare const studioAgentMetadata: (read: ReadValue<JsonObject>) => ReadValue<JsonObject>;
16
+ /**
17
+ * Gives an Agent a Studio form. A field type that trigger forms do not
18
+ * declare, or a repeated field key, fails here with a `TypeError`.
19
+ */
20
+ export declare const withStudioAgentForm: (agent: DeclaredComponent<AgentDeclaration>, form: StudioAgentFormDeclaration) => DeclaredComponent<AgentDeclaration>;
21
+ /**
22
+ * The Studio form an Agent declares in its `metadata`, or `undefined` when it
23
+ * declares none. Throws a `TypeError` naming the first invalid location.
24
+ */
25
+ export declare const readStudioAgentForm: (metadata: JsonObject) => StudioAgentFormDeclaration | undefined;
@@ -1,7 +1,107 @@
1
1
  import type { JsonObject } from "../foundation/json.js";
2
- import type { PackageSchemaProjection } from "../schema/projection.js";
2
+ import type { ReadValue } from "../package/readers.js";
3
+ import type { JsonSchemaDocument, PackageSchemaProjection } from "../schema/projection.js";
4
+ import type { ComponentManifest, ComponentPresentation, DeclarationReference } from "./authoring-core.js";
3
5
  import type { PackagePrimitiveBase } from "./base.js";
4
6
  import type { LocalizedFieldText } from "./knowledge.js";
7
+ import type { WorkflowAuthoringTrigger } from "./workflows.js";
8
+ /** Content types a file field accepts unless it declares its own. */
9
+ export declare const defaultStudioTriggerFormFileAccept: readonly string[];
10
+ /** The largest file a file field accepts, and its default limit: 10 MiB. */
11
+ export declare const maxStudioTriggerFormFileBytes: number;
12
+ /**
13
+ * A field that uploads one file. Studio stores it as a private stored file of
14
+ * the Organization; the run reads `{{ trigger.form.<key>.storageFileId }}`.
15
+ */
16
+ export type StudioTriggerFormFileField = Readonly<{
17
+ /** Accepted content types; PDF, JPEG and PNG when omitted. */
18
+ accept?: readonly string[];
19
+ /** Names the value under the run's `form`; letters, digits and `_`. */
20
+ key: string;
21
+ label: string;
22
+ /** Largest accepted size in bytes; 10 MiB, also the ceiling, when omitted. */
23
+ maxBytes?: number;
24
+ type: "file";
25
+ }>;
26
+ /**
27
+ * A field that holds one value: a string (`text`, or multi-line `textarea`
28
+ * such as a Markdown body), a finite `number`, or a `boolean`.
29
+ */
30
+ export type StudioTriggerFormValueField = Readonly<{
31
+ key: string;
32
+ label: string;
33
+ type: "boolean" | "number" | "text" | "textarea";
34
+ }>;
35
+ /** A choice the user makes in an `enum` field. */
36
+ export type StudioTriggerFormOption = Readonly<{
37
+ label: string;
38
+ value: string;
39
+ }>;
40
+ /** A field that holds the `value` of one of its `options`. */
41
+ export type StudioTriggerFormEnumField = Readonly<{
42
+ key: string;
43
+ label: string;
44
+ options: readonly StudioTriggerFormOption[];
45
+ type: "enum";
46
+ }>;
47
+ /**
48
+ * A field that holds structured data, such as a nested object or list. Its
49
+ * value must satisfy the Draft 2020-12 JSON Schema `schema`; Studio edits it
50
+ * as JSON text.
51
+ */
52
+ export type StudioTriggerFormJsonField = Readonly<{
53
+ key: string;
54
+ label: string;
55
+ schema: JsonSchemaDocument;
56
+ type: "json";
57
+ }>;
58
+ /**
59
+ * A searchable multi-select of the Organization's Knowledge entities of the
60
+ * schema `schemaFqn`, among those the user may read. The run reads
61
+ * `{ entityIds, values }`: the picked entities' ids and, at the same index,
62
+ * each one's `valueKey` data field (its id when omitted), so
63
+ * `{{ trigger.form.<key>.values }}` binds the list of, for example, slugs.
64
+ */
65
+ export type StudioTriggerFormEntitiesField = Readonly<{
66
+ key: string;
67
+ label: string;
68
+ /** Data field each option shows; the entity name when omitted. */
69
+ labelKey?: string;
70
+ /** FQN of the Knowledge entity schema whose entities the user picks. */
71
+ schemaFqn: string;
72
+ type: "entities";
73
+ /**
74
+ * String data field the run takes for each pick, such as a unique `slug`;
75
+ * the entity id when omitted. An entity without it cannot be picked.
76
+ */
77
+ valueKey?: string;
78
+ }>;
79
+ /** A field of a Studio trigger form; its value lands at `form.<key>` of the run. */
80
+ export type StudioTriggerFormField = StudioTriggerFormEntitiesField | StudioTriggerFormEnumField | StudioTriggerFormFileField | StudioTriggerFormJsonField | StudioTriggerFormValueField;
81
+ /**
82
+ * The Studio form of a user-invoked Workflow trigger. Studio shows and runs
83
+ * the trigger only for users of `organizationGroup`.
84
+ */
85
+ export type StudioTriggerFormDeclaration = Readonly<{
86
+ /** Fields the user fills before running; none when omitted. */
87
+ fields?: readonly StudioTriggerFormField[];
88
+ /** FQN of the Organization Group whose users see and run the form. */
89
+ organizationGroup: string;
90
+ }>;
91
+ export type StudioTriggerFormInput = Omit<StudioTriggerFormDeclaration, "organizationGroup"> & Readonly<{
92
+ organizationGroup: DeclarationReference<"organizationGroup">;
93
+ }>;
94
+ /** Reads the fields of a Studio form; trigger and agent forms share them. */
95
+ export declare const studioFormFields: ReadValue<readonly StudioTriggerFormField[]>;
96
+ /** Admits trigger metadata whose Studio form, when present, is well formed. */
97
+ export declare const studioTriggerMetadata: (read: ReadValue<JsonObject>) => ReadValue<JsonObject>;
98
+ /** Gives a user-invoked Workflow trigger a Studio form. */
99
+ export declare const withStudioTriggerForm: (trigger: WorkflowAuthoringTrigger, { organizationGroup, ...form }: StudioTriggerFormInput) => WorkflowAuthoringTrigger;
100
+ /**
101
+ * The Studio form a trigger declares in its `metadata`, or `undefined` when it
102
+ * declares none. Throws a `TypeError` naming the first invalid location.
103
+ */
104
+ export declare const readStudioTriggerForm: (metadata: JsonObject) => StudioTriggerFormDeclaration | undefined;
5
105
  export type StudioComponentDeclaration = PackagePrimitiveBase<"studioComponent"> & Readonly<{
6
106
  category: "layout" | "page" | "primitive" | "view" | "widget";
7
107
  composition?: Readonly<{
@@ -16,10 +116,14 @@ export type StudioComponentDeclaration = PackagePrimitiveBase<"studioComponent">
16
116
  propsSchema: PackageSchemaProjection;
17
117
  sourceRef: string;
18
118
  }>;
19
- export type StudioAppDeclaration = PackagePrimitiveBase<"studioApp"> & Readonly<{
20
- definition: StudioAppDefinition;
119
+ /**
120
+ * A Studio App Template: a starting tree the builder copies into a new Studio
121
+ * app. The copy keeps no link to the template.
122
+ */
123
+ export type StudioAppTemplateDeclaration = PackagePrimitiveBase<"studioAppTemplate"> & Readonly<{
124
+ definition: StudioAppTemplateDefinition;
21
125
  }>;
22
- export type StudioAppPageDefinition = Readonly<{
126
+ export type StudioAppTemplatePageDefinition = Readonly<{
23
127
  fullWidth?: boolean;
24
128
  icon?: string;
25
129
  kind: "predefined";
@@ -29,8 +133,98 @@ export type StudioAppPageDefinition = Readonly<{
29
133
  routeSegment: string;
30
134
  slug: string;
31
135
  }>;
136
+ export type StudioAppTemplateSectionDefinition = Readonly<{
137
+ description?: string;
138
+ icon?: string;
139
+ label: string;
140
+ orderIndex: number;
141
+ pages: readonly StudioAppTemplatePageDefinition[];
142
+ slug: string;
143
+ }>;
144
+ export type StudioAppTemplateDefinition = Readonly<{
145
+ color?: string;
146
+ description?: string;
147
+ icon?: string;
148
+ isDefaultTemplate?: boolean;
149
+ name: string;
150
+ sections: readonly StudioAppTemplateSectionDefinition[];
151
+ slug: string;
152
+ }>;
153
+ /** The Studio role a Declared Grant gives its Group on a Declared Studio App. */
154
+ export type StudioAppRole = "manage" | "view";
155
+ /** A Declared Grant: one Organization Group holds one Studio role. */
156
+ export type StudioAppGrant = Readonly<{
157
+ /** FQN of the Organization Group. */
158
+ group: string;
159
+ role: StudioAppRole;
160
+ }>;
161
+ /**
162
+ * The only lifecycle of a Declared Studio App: each deploy upserts it, and
163
+ * nobody edits it in the builder.
164
+ */
165
+ export type StudioAppLifecycle = Readonly<{
166
+ deployMode: "upsert";
167
+ readonly: true;
168
+ }>;
169
+ /**
170
+ * Shows a Declared Studio Node only to users of `groups` (Organization Group
171
+ * FQNs). A node without it shows to every user who can open the app.
172
+ */
173
+ export type StudioNodeAccess = Readonly<{
174
+ groups: readonly string[];
175
+ }>;
176
+ /** The app shell: the built-in left sidebar, or a layout Studio Component. */
177
+ export type StudioAppLayoutDefinition = Readonly<{
178
+ componentRef: string;
179
+ kind: "custom";
180
+ props?: JsonObject;
181
+ }> | Readonly<{
182
+ kind: "left_sidebar";
183
+ }>;
184
+ /** Binds a view to the entities of one Knowledge entity schema (its FQN). */
185
+ export type StudioAppViewDataBinding = Readonly<{
186
+ filter?: JsonObject;
187
+ kind: "schema";
188
+ schema: string;
189
+ }>;
190
+ /**
191
+ * A view, or a Widget, placed in `slot` of its page at `orderIndex`. A
192
+ * built-in component is referenced by its FQN, such as
193
+ * `builtin:view.trigger-form@0.1.0`.
194
+ */
195
+ export type StudioAppViewDefinition = Readonly<{
196
+ access?: StudioNodeAccess;
197
+ componentRef: string;
198
+ dataBinding?: StudioAppViewDataBinding;
199
+ fqn: string;
200
+ orderIndex: number;
201
+ props?: JsonObject;
202
+ slot: string;
203
+ }>;
204
+ type StudioAppPageBase = Readonly<{
205
+ access?: StudioNodeAccess;
206
+ fqn: string;
207
+ fullHeight?: boolean;
208
+ fullWidth?: boolean;
209
+ icon?: string;
210
+ label: string;
211
+ orderIndex: number;
212
+ /** The page's stable route; prefill links stay valid across deploys. */
213
+ routeSegment: string;
214
+ slug: string;
215
+ }>;
216
+ /** A page that holds views, or a predefined page that a built-in renders. */
217
+ export type StudioAppPageDefinition = StudioAppPageBase & (Readonly<{
218
+ kind: "generic";
219
+ views: readonly StudioAppViewDefinition[];
220
+ }> | Readonly<{
221
+ kind: "predefined";
222
+ predefinedPageRef: string;
223
+ }>);
32
224
  export type StudioAppSectionDefinition = Readonly<{
225
+ access?: StudioNodeAccess;
33
226
  description?: string;
227
+ fqn: string;
34
228
  icon?: string;
35
229
  label: string;
36
230
  orderIndex: number;
@@ -41,8 +235,101 @@ export type StudioAppDefinition = Readonly<{
41
235
  color?: string;
42
236
  description?: string;
43
237
  icon?: string;
44
- isDefaultTemplate?: boolean;
238
+ /** The built-in left sidebar when omitted. */
239
+ layout?: StudioAppLayoutDefinition;
45
240
  name: string;
46
241
  sections: readonly StudioAppSectionDefinition[];
47
242
  slug: string;
48
243
  }>;
244
+ /**
245
+ * A Declared Studio App: CI creates and publishes it on install, the package
246
+ * owns it, and Organization Groups open it through its Declared Grants.
247
+ */
248
+ export type StudioAppDeclaration = PackagePrimitiveBase<"studioApp"> & Readonly<{
249
+ definition: StudioAppDefinition;
250
+ grants: Readonly<{
251
+ groups: readonly StudioAppGrant[];
252
+ }>;
253
+ lifecycle: StudioAppLifecycle;
254
+ }>;
255
+ type GroupReference = DeclarationReference<"organizationGroup">;
256
+ type ComponentReference = DeclarationReference<"studioComponent">;
257
+ /** A trigger handle, or the `triggerRef` of a user-invoked trigger. */
258
+ export type StudioTriggerReference = string | WorkflowAuthoringTrigger;
259
+ export type StudioNodeAccessInput = Readonly<{
260
+ groups: readonly GroupReference[];
261
+ }>;
262
+ /** View props; `triggerRef` also accepts the trigger handle. */
263
+ export type StudioAppViewPropsInput = JsonObject & Readonly<{
264
+ triggerRef?: StudioTriggerReference;
265
+ }>;
266
+ export type StudioAppViewInput = Omit<StudioAppViewDefinition, "access" | "componentRef" | "dataBinding" | "props"> & Readonly<{
267
+ access?: StudioNodeAccessInput;
268
+ componentRef: ComponentReference;
269
+ dataBinding?: Omit<StudioAppViewDataBinding, "schema"> & Readonly<{
270
+ schema: DeclarationReference<"knowledgeEntitySchema">;
271
+ }>;
272
+ props?: StudioAppViewPropsInput;
273
+ }>;
274
+ export type StudioAppPageInput = Omit<StudioAppPageBase, "access"> & Readonly<{
275
+ access?: StudioNodeAccessInput;
276
+ }> & (Readonly<{
277
+ kind: "generic";
278
+ views: readonly StudioAppViewInput[];
279
+ }> | Readonly<{
280
+ kind: "predefined";
281
+ predefinedPageRef: ComponentReference;
282
+ }>);
283
+ export type StudioAppSectionInput = Omit<StudioAppSectionDefinition, "access" | "pages"> & Readonly<{
284
+ access?: StudioNodeAccessInput;
285
+ pages: readonly StudioAppPageInput[];
286
+ }>;
287
+ export type StudioAppDefinitionInput = Omit<StudioAppDefinition, "layout" | "sections"> & Readonly<{
288
+ layout?: Readonly<{
289
+ componentRef: ComponentReference;
290
+ kind: "custom";
291
+ props?: JsonObject;
292
+ }> | Readonly<{
293
+ kind: "left_sidebar";
294
+ }>;
295
+ sections: readonly StudioAppSectionInput[];
296
+ }>;
297
+ /** What `declareStudioApp` takes. */
298
+ export type StudioAppDeclarationInput = Readonly<{
299
+ definition: Readonly<{
300
+ definition: StudioAppDefinitionInput;
301
+ grants: Readonly<{
302
+ groups: readonly Readonly<{
303
+ group: GroupReference;
304
+ role: StudioAppRole;
305
+ }>[];
306
+ }>;
307
+ lifecycle: StudioAppLifecycle;
308
+ }>;
309
+ manifest: ComponentManifest;
310
+ presentation: ComponentPresentation;
311
+ }>;
312
+ /** The manifest fields of a Declared Studio App, references as FQNs. */
313
+ export declare const studioAppManifestFields: ({ definition: { layout, sections, ...definition }, grants, lifecycle }: StudioAppDeclarationInput["definition"]) => Pick<StudioAppDeclaration, "definition" | "grants" | "lifecycle">;
314
+ /**
315
+ * The key of a declared view in its slot: the last segment of its FQN as a
316
+ * kebab-case name. Two views of one page slot cannot share it.
317
+ */
318
+ export declare const studioViewKey: (fqn: string) => string;
319
+ /** Reads a Declared Studio App; its lifecycle must be `upsert` + `readonly`. */
320
+ export declare const studioAppDeclaration: ReadValue<Readonly<{
321
+ description?: string;
322
+ displayName: string;
323
+ fqn: string;
324
+ icon?: string;
325
+ kind: "studioApp";
326
+ tags?: readonly string[];
327
+ version: string;
328
+ }> & Readonly<{
329
+ definition: StudioAppDefinition;
330
+ grants: Readonly<{
331
+ groups: readonly StudioAppGrant[];
332
+ }>;
333
+ lifecycle: StudioAppLifecycle;
334
+ }> & JsonObject>;
335
+ export {};