@collective-intelligence/extensions-sdk 0.1.26 → 0.1.28

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
@@ -397,18 +397,26 @@ destination target kinds. An explicit `false` always takes precedence.
397
397
 
398
398
  ## Knowledge declarations
399
399
 
400
- `declareKnowledgeRelationSchema` requires explicit `LifecycleOptions`:
401
- `{ deployMode: "upsert" | "init_only", readonly: boolean }`. Relation manifests
402
- from older releases may omit `lifecycle`; parsing preserves that absence without
403
- inventing a policy and validates any supplied policy. Definition `readonly` is
404
- independent of relation record `localMutationPolicy`.
400
+ Record Relations are retired: there is no relation schema or relation adapter
401
+ declaration. Manifest parsing refuses the kinds `knowledgeRelationSchema` and
402
+ `knowledgeRelationAdapter` with an error that names the kind; declare a
403
+ Reference Field (`fieldSemantics["/<key>"].relation`) instead. Manifest parsing
404
+ also names each retired key: `relationSchemaCapabilities` of a connector,
405
+ `relationBindings` of a connector instance, `relationSchemaFqns` of a domain
406
+ template, `knowledge.relationSchemas` of a tool binding, and the pipeline task
407
+ kind `relation`. Stored releases read with
408
+ `parseStoredExtensionReleaseManifest` drop only the components of a retired
409
+ kind, the retired keys, `relation` pipeline tasks and each step or pipeline
410
+ left without a task; `withCurrentPrimitive` reads one stored primitive
411
+ declaration the same way. A stored release that keeps a retired nested policy
412
+ form fails to parse.
405
413
 
406
414
  `declareDomain`, `declareKnowledgeEntitySchema`,
407
415
  `declareExternalApplication`, `declareWorkflow`, and
408
416
  `declareWorkflowTemplate` require per-item `LifecycleOptions`:
409
417
  `{ deployMode: "upsert" | "init_only", readonly: boolean }`. Entity schemas
410
- also require the persisted Organization entity schema capabilities other than
411
- relation schemas: `autocompleteConfiguration`,
418
+ also require the persisted Organization entity schema capabilities:
419
+ `autocompleteConfiguration`,
412
420
  `displayNameExpression`, `embeddingConfig`, `persistFullFieldContributions`,
413
421
  `usableAsDocumentScope`, and `versioningEnabled`. Domain declarations require
414
422
  `versioningEnabled`. External applications require `applicationType`,
@@ -444,7 +452,7 @@ These declarations compile to `fieldSemantics["/owner"].user` and
444
452
  value schemas. Declare requiredness through the existing authored schema;
445
453
  the host replaces the value shape while preserving its required list. Ordinary UUID properties do not
446
454
  implicitly become User fields. User fields cannot share File or Relation
447
- semantics and are not supported on relation schemas or nested properties.
455
+ semantics and are not supported on nested properties.
448
456
  Values contain IDs only; the host owns membership validation and profile
449
457
  resolution, duplicate rejection, and preservation of list order. Only the
450
458
  schema's accounts field (below) also accepts the Organization's External App
@@ -473,7 +481,7 @@ authored semantics of that pointer. The schema must not define the property;
473
481
  the platform generates the File value schema at install. Localization,
474
482
  presentation and semantics pointers may address the File field. Declaration
475
483
  rejects a raw `fieldSemantics` `file` entry, a `mediaVisibility` on a pointer
476
- that is not a declared File field (relation schemas have none), and a File field
484
+ that is not a declared File field, and a File field
477
485
  with both `visibility` and a raw `mediaVisibility`.
478
486
 
479
487
  ### Relation fields
@@ -524,8 +532,7 @@ spellings remain accepted. The target schema determines operand validation.
524
532
  The schema does not define the property: the platform generates its value
525
533
  schema at install. Localization, presentation and semantics pointers may address
526
534
  the relation field. Declaration rejects a relation entry whose pointer is not a
527
- top-level property, a relation entry on a File field, and any relation entry on
528
- a relation schema. Package deploy resolves `targetSchemaFqn` among the entity
535
+ top-level property and a relation entry on a File field. Package deploy resolves `targetSchemaFqn` among the entity
529
536
  schemas of the Organization. The metadata-only `relationFields` declaration
530
537
  is removed; manifest parsing refuses a release that still declares it.
531
538
 
@@ -668,7 +675,7 @@ export const Group = entity("group", "Group", {
668
675
  })
669
676
 
670
677
  // Add these declarations to the existing package's primitives collection.
671
- export const relationSchemas = [Person, Passport, Asset, Company, Group]
678
+ export const entitySchemas = [Person, Passport, Asset, Company, Group]
672
679
  ```
673
680
 
674
681
  Only Person's forward properties accept writes. For example, `passport` and
@@ -811,7 +818,7 @@ declareSkill({
811
818
  ```
812
819
 
813
820
  - `knowledge` selectors take handles of their own kind (`domain`,
814
- `knowledgeEntitySchema`, `knowledgeRelationSchema`) or FQN strings. Install
821
+ `knowledgeEntitySchema`) or FQN strings. Install
815
822
  resolves them to the Organization's definitions and rejects an unknown one,
816
823
  or a `knowledge` boundary on a tool that has no Knowledge scope.
817
824
  - `approval: { rule }` names an approval rule of the installing Organization;
@@ -1270,9 +1277,9 @@ export default declarePackage({
1270
1277
  - A handle is a `PackageVariable<T>` where `T` is the value of its type (a
1271
1278
  `secret` is a `string`). `Varying<T>` is a value or a handle of that type;
1272
1279
  the definition inputs of `declareOrganizationSettings`,
1273
- `declareOrganizationInstructions`,
1274
- `declareExternalApplication`, `declareKnowledgeConnectorInstance` and
1275
- `declareDatasetConnectorInstance` are typed with `VaryingDefinition`, so a
1280
+ `declareOrganizationInstructions`, `declareExternalApplication`,
1281
+ `declareKnowledgeConnectorInstance`, `declareDatasetConnectorInstance` and
1282
+ `declareDocumentCollection` are typed with `VaryingDefinition`, so a
1276
1283
  `string` handle does not compile on a `number` field or on a list of
1277
1284
  strings, while it fits a string literal field. A `json` handle fits a
1278
1285
  `JsonValue` field or a whole structured value; a `string[]` handle fits a
@@ -1878,13 +1885,45 @@ login, access and editor support still apply, and it does not promise a historic
1878
1885
  stored Version. Stored MIME type, extension, filename and bytes retain their
1879
1886
  separate exported-representation semantics.
1880
1887
 
1888
+ Optional sync fields let a connector help the host sync less and report more.
1889
+ A connector that sets none of them keeps working.
1890
+
1891
+ - `DocumentsDeltaRequest.providerScopeKey` is the stored drive identity of the
1892
+ root, as proved by `proveRootAncestry`.
1893
+ - `DocumentsDeltaItem.providerContentHash` (also on `pull` items) is the hash
1894
+ the provider reports, with the algorithm in the value: `quickxor:<value>` or
1895
+ `md5:<value>`. `contentHash` stays the SHA-256 that CI computes.
1896
+ - `DocumentsDeltaItem.shortcutTargetRemoteId` is the remote file id a File
1897
+ Shortcut points at.
1898
+ - `DocumentsDeltaItem.mimeType` (also on `pull` items) is the MIME type the
1899
+ provider declares in its listing. The host stores it when `fetchContent`
1900
+ reports no `mimeType`, so a connector that downloads bytes only keeps the
1901
+ declared type.
1902
+ - `DocumentsDeltaPage.warnings` lists `{ remoteItemKey, code, message,
1903
+ parentRemoteIds? }` for items the connector skipped, such as a Folder Shortcut
1904
+ with code `unsupported_folder_shortcut`. The host shows each as a Sync
1905
+ Warning. With `parentRemoteIds`, the host also clears the warning when a
1906
+ parent folder is deleted or leaves the scope.
1907
+ - `readFileRevisions({ remoteFileIds }, context)` returns one
1908
+ `DocumentsFileRevision` per id: `{ remoteFileId, contentRevision?,
1909
+ providerContentHash?, source? }`, or `{ remoteFileId, missing: true }` when the
1910
+ file is gone. Like `fetchSource`, an omitted hook is unsupported and the host
1911
+ skips the check that needs it.
1912
+
1913
+ A connector reports a failure kind with a structural `code` on the thrown error
1914
+ (`DocumentsConnectorErrorCode` in `@collective-intelligence/extensions-sdk-backend`):
1915
+ `cursor_expired`, `unsupported_folder_shortcut`,
1916
+ `unsupported_cross_drive_shortcut`, or `provider_unavailable` when the provider
1917
+ still refuses after the connector's own retries. The host fails the run for
1918
+ `provider_unavailable` and does not count it against one file.
1919
+
1881
1920
  ### Knowledge adapter identity
1882
1921
 
1883
- Entity and relation adapter constructors, when used, must implement `remoteId(remote)`,
1922
+ Entity adapter constructors, when used, must implement `remoteId(remote)`,
1884
1923
  returning a string or `PromiseLike<string>`. This requirement also applies to
1885
1924
  plain classes; using an executable SDK base class is optional. The provider owns
1886
1925
  the stable, nonempty identity and any composite-key calculation. Mapping local
1887
- fields or relation endpoints does not supply identity implicitly.
1926
+ fields does not supply identity implicitly.
1888
1927
 
1889
1928
  Read identity from the remote record before mapping it. A local projection may
1890
1929
  omit the source ID. Hosts invoke the declared `remoteId` operation and validate
@@ -2092,6 +2131,82 @@ release admission.
2092
2131
 
2093
2132
  The [Nest declaration example](../../../demo/external-app-nest/apps/extensions/src/index.ts) shares this catalog with its detached runtime. [Exact deployment](../../../docs/reference/package-release-cli.md#deploy-an-exact-package-and-its-declared-gateways) supplies endpoint bindings, separate publisher/Organization credentials and bounded operation following.
2094
2133
 
2134
+ ## Document Collection declarations
2135
+
2136
+ `declareDocumentCollection` declares one Declared Connected collection: a
2137
+ Connected collection whose identity is the declaration FQN. One
2138
+ `documentCollection` manifest holds the collection settings, its Connection,
2139
+ its Remote roots and its nested Declared rules; no other kind declares a rule,
2140
+ and no option creates a Local collection.
2141
+
2142
+ ```ts
2143
+ import {
2144
+ declareDocumentCollection,
2145
+ packageVariables
2146
+ } from "@collective-intelligence/extensions-sdk"
2147
+
2148
+ const vars = packageVariables({ hrDrive: { type: "string" } })
2149
+
2150
+ export const hrPolicies = declareDocumentCollection({
2151
+ manifest: { fqn: "acme.documents.hr-policies", version: "1.0.0" },
2152
+ presentation: {
2153
+ displayName: "HR policies",
2154
+ description: "Company HR policies"
2155
+ },
2156
+ definition: {
2157
+ connectorFqn:
2158
+ "builtin.integrations.microsoft-365.connectors.documents-drive",
2159
+ connection: { setupKey: "microsoft365" },
2160
+ title: "HR Policies",
2161
+ indexContent: true,
2162
+ remoteRoots: [{ drive: vars.hrDrive, folders: ["Policies"] }],
2163
+ rules: [
2164
+ {
2165
+ grantee: { kind: "group", fqn: "acme.hr" },
2166
+ target: { kind: "collection" },
2167
+ permission: "read",
2168
+ effect: "allow"
2169
+ },
2170
+ {
2171
+ grantee: { kind: "organization" },
2172
+ target: {
2173
+ kind: "folder",
2174
+ folder: { drive: vars.hrDrive, folders: ["Policies", "Board"] }
2175
+ },
2176
+ permission: "read",
2177
+ effect: "deny"
2178
+ }
2179
+ ]
2180
+ }
2181
+ })
2182
+ ```
2183
+
2184
+ - `connectorFqn`, optional, names the Documents connector that syncs the
2185
+ collection; a Package Variable never stands for it. When it is omitted, the
2186
+ deploy takes the one Documents connector of the declared dependencies whose
2187
+ Connection template matches `connection`, and refuses when none or more
2188
+ than one matches. `connection` is `{ connectionInstanceFqn }`, a Connection that a package
2189
+ declares, or `{ setupKey }`, whose value is an existing Connection ID given
2190
+ as `{ connectionId }` in the Inputs File `connections` section.
2191
+ - `title` is the collection title and the declaration `description` is the
2192
+ collection description. `indexContent` and `indexOverview` default to
2193
+ `false`; `overviewInputMaxChars` and `richEnrichment` follow "File overview
2194
+ settings". `syncEnabled` defaults to `true`.
2195
+ - A Remote root and a rule target folder are a path `{ drive, folders }` or a
2196
+ `{ remoteId }` for a path that is ambiguous. On Microsoft 365, `drive` is the
2197
+ drive title `<siteName> / <libraryName>` that the browse route shows; an
2198
+ empty `folders` names the drive. Each value may be a Package Variable, so
2199
+ one release serves environments with different folders.
2200
+ - A Declared rule needs a `grantee`, a `target`, a `permission` (`read`,
2201
+ `update`, `manage` or `view_history`) and an `effect` (`allow` or `deny`),
2202
+ with the meaning of the same rule made by an administrator. The grantee is a
2203
+ group or a Service principal by FQN, or the whole Organization; a user ID or
2204
+ an External App role is not a grantee. The target is the collection or a
2205
+ folder: a folder that a Remote root names is a Remote root target, any other
2206
+ folder a subfolder below a Remote root.
2207
+ - An `allow` of `view_history` needs an `allow` of `read` for the same grantee
2208
+ and target; the declaration and the manifest reader refuse it otherwise.
2209
+
2095
2210
  ## Concrete connector configuration
2096
2211
 
2097
2212
  `declareKnowledgeConnectorInstance` and `declareDatasetConnectorInstance` declare
@@ -2248,8 +2363,8 @@ the caller as CI built it: `user.id`, `groupIds`, `roles` and `access`.
2248
2363
  External App that makes the call, for example `["sales_manager"]`; it is empty
2249
2364
  for a call outside an External App. Match a role with `in` on the subject path
2250
2365
  `["roles"]`. CI sets `access` to `"read"` for get, list, search, facets,
2251
- autocomplete, traverse and retrieval, and to `"write"` for create, update,
2252
- delete and relation writes; a policy that does not test it applies to both. For
2366
+ autocomplete and retrieval, and to `"write"` for create, update and delete; a
2367
+ policy that does not test it applies to both. For
2253
2368
  example, this `deny` `filter` policy lets users with the `member` User Role read
2254
2369
  every company but write only the ones whose accounts field lists them:
2255
2370
 
@@ -2340,11 +2455,12 @@ A comment on a task follows its `task`, then the task's `project`, with the
2340
2455
  rule `{ op: "relation_field", field: "task", inner: { op: "relation_field",
2341
2456
  field: "project", inner: projectMembers } }`. A hop to a deleted entity names
2342
2457
  nothing. Hops belong in `rule`, never in `subjectMatch`, and only on a policy
2343
- that targets one entity schema; a hop does not mix `field` with
2344
- `relationSchemaId` or `direction`. CI refuses at deploy a `field` that is not a
2345
- forward relation field of the schema the hop starts from. The
2346
- older `{ op: "relation_field", relationSchemaId, direction, inner }` form names
2347
- a relation schema; CI does not evaluate it and treats it as true.
2458
+ that targets one entity schema; a hop holds no `direction`. CI refuses at
2459
+ deploy a `field` that is not a forward relation field of the schema the hop
2460
+ starts from. The Record Relation forms are retired: manifest parsing refuses
2461
+ `relation_exists`, the `{ op: "relation_field", relationSchemaId, direction,
2462
+ inner }` form and the policy kinds `relation_schema` and `relation_domain` with
2463
+ an error that names the retired form or kind.
2348
2464
 
2349
2465
  A field write rule limits what an `allow` `filter` policy on an entity schema
2350
2466
  or domain admits to updates of the listed `data` paths. `writableFields` is a
@@ -2589,7 +2705,7 @@ Knowledge schemas select item embedding fields with
2589
2705
  `definition.fieldSemantics["/full/pointer"].includeInItemEmbedding: true`.
2590
2706
  Omitted and `false` values leave the field out. Select scalar values or lists of
2591
2707
  scalars; nested fields use full RFC 6901 JSON pointers (`~1` escapes `/`, `~0`
2592
- escapes `~`). Objects, files, and relation traversal cannot be selected as item
2708
+ escapes `~`). Objects and files cannot be selected as item
2593
2709
  values. When the schema's `embedEntities` gate is enabled, its item vector contains
2594
2710
  only the selected values as one bounded YAML document, without chunking or an item overview. Empty selection
2595
2711
  produces no item vector and a visible configuration status. Unsupported selected
@@ -2628,6 +2744,42 @@ Add these settings to the existing schema declaration's `definition` object:
2628
2744
  }
2629
2745
  ```
2630
2746
 
2747
+ ### Knowledge pull contract
2748
+
2749
+ `PackageKnowledgeConnector.pull` receives `{ connections, request, settings }`
2750
+ and returns one `KnowledgePullPage`, or `{ fault }` with a `KnowledgePullFault`.
2751
+ The `request` is a `KnowledgePullRequest`; every key is always present:
2752
+
2753
+ ```ts
2754
+ type KnowledgePullRequest = {
2755
+ remoteId: string // the remote collection of the entity binding
2756
+ mode: "full" | "delta"
2757
+ cursor: string | null // page cursor of this phase; null on the first page
2758
+ deltaCursor: string | null // stored Feed cursor, passed through unchanged
2759
+ since: string | null // ISO 8601 delta restart point, overlap applied
2760
+ limit: number // the declared pullPageSize
2761
+ options: { watermarkColumn?: string } // binding options
2762
+ }
2763
+ ```
2764
+
2765
+ - **Page.** `nextCursor` is `null` on the last page. Any other page declares
2766
+ `nextCursorKind`: `provider_page_token`, `provider_delta_token`,
2767
+ `timestamp_checkpoint` or `stable_remote_id`. There is no offset kind: a page
2768
+ cannot assert a stable ordering. A page can carry
2769
+ `warnings: { code, message }[]` for the operator; the host keeps one warning
2770
+ per code in the run.
2771
+ - **Fault.** `KnowledgePullFault` is `{ code, message, retryable }`. The host
2772
+ retries a page with a `retryable` fault; any other fault fails the run.
2773
+ `KnowledgePullResult` is the page or `{ fault }` union that `pull` returns.
2774
+ - **Declaration.** `pullPageSize` sets the request `limit` (omission means 100).
2775
+ `deltaOverlapSeconds` moves the delta restart point back to read changes at
2776
+ the window edge again (omission means the host default, 300). Both are
2777
+ positive integers.
2778
+
2779
+ `PackageKnowledgeConnector<PullInput>` types `connections` and `settings`;
2780
+ `PullInput` must have `request: KnowledgePullRequest`. The backend SDK exports
2781
+ `KnowledgePullInput<Connections, Settings>` for that input.
2782
+
2631
2783
  ### Remote deletion propagation
2632
2784
 
2633
2785
  Author rule: a Knowledge connector must offer full deletion. A full import run
@@ -2656,9 +2808,9 @@ What a connector gives, by capability:
2656
2808
 
2657
2809
  - **Stable item ID.** `remoteId(remote)` of the Knowledge adapter returns the
2658
2810
  same ID for the same item on every run (see "Knowledge adapter identity").
2659
- `KnowledgeConnectorPullPage.itemMetadata` aligns provider identity and
2811
+ `KnowledgePullPage.itemMetadata` aligns provider identity and
2660
2812
  revision with `items` by index.
2661
- - **Census evidence.** Each `KnowledgeConnectorPullPage` carries `census`
2813
+ - **Census evidence.** Each `KnowledgePullPage` carries `census`
2662
2814
  (`KnowledgeConnectorCensusPageEvidence`): `sourceId`, `requestCursor` (`null`
2663
2815
  on the first page), `terminal` (true exactly when `nextCursor` is `null`), and
2664
2816
  `listing`. `listing` is `"complete"` when the page lists every item of the
@@ -2677,9 +2829,11 @@ What a connector gives, by capability:
2677
2829
  - **Tombstone feed (`full_and_delta` only).** A delta page lists tombstones in
2678
2830
  `itemMetadata` with `deletedAt` and `deletionKind`. The last page of a feed run
2679
2831
  gives the **Feed cursor** as `deltaCursor`; without it the next run has no start
2680
- point. When the source rejects the cursor, return a
2681
- `KnowledgeConnectorPullFault` with the code `cursor_expired`. The host then
2682
- clears the cursor, and the next run of the binding reads in full.
2832
+ point. When the source rejects the cursor, return `{ fault }` with a
2833
+ `KnowledgePullFault` of code `cursor_expired` and `retryable: false`. The host
2834
+ then clears only the Feed cursor and keeps the **Delta Since**. The next delta
2835
+ run reads the changes since then without tombstones; only a full run
2836
+ reconciles deletions.
2683
2837
 
2684
2838
  An entity binding can declare `remoteDeletionPropagation: "never" | "full" |
2685
2839
  "full_and_delta"`. The values are ordered `never` < `full` < `full_and_delta`. An
@@ -23,10 +23,9 @@ export type KnowledgeScopeSelection<Reference> = Readonly<{
23
23
  exclude?: readonly Reference[];
24
24
  include?: readonly Reference[];
25
25
  }>;
26
- type KnowledgeScopeOf<Domain, EntitySchema, RelationSchema> = Readonly<{
26
+ type KnowledgeScopeOf<Domain, EntitySchema> = Readonly<{
27
27
  domains?: KnowledgeScopeSelection<Domain>;
28
28
  entitySchemas?: KnowledgeScopeSelection<EntitySchema>;
29
- relationSchemas?: KnowledgeScopeSelection<RelationSchema>;
30
29
  /** Lifts the scope boundary; the installer still needs the bind permission. */
31
30
  unrestricted?: boolean;
32
31
  }>;
@@ -35,7 +34,7 @@ type KnowledgeScopeOf<Domain, EntitySchema, RelationSchema> = Readonly<{
35
34
  * to the Organization's definition and rejects one that does not resolve, or
36
35
  * a boundary on a tool that has no Knowledge scope.
37
36
  */
38
- export type ToolBindingKnowledgeScope = KnowledgeScopeOf<DeclarationReference<"domain">, DeclarationReference<"knowledgeEntitySchema">, DeclarationReference<"knowledgeRelationSchema">>;
37
+ export type ToolBindingKnowledgeScope = KnowledgeScopeOf<DeclarationReference<"domain">, DeclarationReference<"knowledgeEntitySchema">>;
39
38
  /**
40
39
  * One tool an Agent or Skill binds, with the controls the binding carries.
41
40
  * `settings` is validated at install against the tool's binding settings
@@ -51,7 +50,7 @@ export type ToolBinding = Readonly<{
51
50
  /** A `ToolBinding` in a manifest: every reference is an FQN. */
52
51
  export type ToolBindingDeclaration = Readonly<{
53
52
  approval?: ToolBindingApproval;
54
- knowledge?: KnowledgeScopeOf<string, string, string>;
53
+ knowledge?: KnowledgeScopeOf<string, string>;
55
54
  name?: string;
56
55
  settings?: JsonObject;
57
56
  tool: 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, EmailProviderDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration, KnowledgeRelationAdapterDeclaration } from "./connectors.js";
7
+ import type { DocumentsDeltaPage, DocumentsDeltaRequest, DocumentsDrivesPage, DocumentsFoldersPage, DocumentsFetchedContent, DocumentsFileRevision, DocumentsRootAncestry, DocumentsSource, KnowledgeEntityAdapterDeclaration, ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, EmailProviderDeclaration, EventListenerDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration } 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, ToolResultWithDisplay, ToolSettingsOptionsDeclaration } from "./tools.js";
@@ -92,6 +92,13 @@ export type DocumentsConnectorImplementation = Readonly<{
92
92
  fetchSource?(input: {
93
93
  readonly remoteFileId: string;
94
94
  }, context: unknown): Awaitable<DocumentsSource | null>;
95
+ /**
96
+ * Current revisions of files by id, one result per id. Optional for older
97
+ * connectors; hosts skip the check that needs it when it is missing.
98
+ */
99
+ readFileRevisions?(input: {
100
+ readonly remoteFileIds: readonly string[];
101
+ }, context: unknown): Awaitable<readonly DocumentsFileRevision[]>;
95
102
  pull(input: {
96
103
  readonly cursor?: string;
97
104
  readonly selectedRootRemoteIds?: readonly string[];
@@ -101,7 +108,9 @@ export type DocumentsConnectorImplementation = Readonly<{
101
108
  readonly contentRevision?: string;
102
109
  readonly deleted?: boolean;
103
110
  readonly kind: "file" | "folder";
111
+ readonly mimeType?: string;
104
112
  readonly parentRemoteIds: readonly string[];
113
+ readonly providerContentHash?: string;
105
114
  readonly remoteFileId: string;
106
115
  readonly title: string;
107
116
  }[];
@@ -136,12 +145,6 @@ export type KnowledgeEntityAdapterImplementation = Readonly<{
136
145
  toLocal(...input: never[]): unknown;
137
146
  toRemote(...input: never[]): unknown;
138
147
  }>;
139
- export type KnowledgeRelationAdapterImplementation = Readonly<{
140
- remoteId(...input: never[]): string | PromiseLike<string>;
141
- sourceRef(...input: never[]): unknown;
142
- targetRef(...input: never[]): unknown;
143
- toLocal(...input: never[]): unknown;
144
- }>;
145
148
  export type FieldTransformerImplementation = Readonly<{
146
149
  transform(...input: never[]): unknown;
147
150
  }>;
@@ -222,7 +225,6 @@ export type WorkflowNodeDefinitionInput<InputSchema, OutputSchema> = Omit<Defini
222
225
  export type WorkflowNodeClassDeclaration<InputSchema = PackageSchemaSource<unknown, unknown>, OutputSchema = PackageSchemaSource<unknown, unknown>, Constructor extends new () => WorkflowNodeImplementation<SchemaValue<InputSchema>, SchemaValue<OutputSchema>> = new () => WorkflowNodeImplementation<SchemaValue<InputSchema>, SchemaValue<OutputSchema>>> = ClassDeclaration<WorkflowNodeDeclaration, Constructor, WorkflowNodeDefinitionInput<InputSchema, OutputSchema>>;
223
226
  export type EventListenerClassDeclaration<Constructor extends new () => EventListenerImplementation = new () => EventListenerImplementation> = ClassDeclaration<EventListenerDeclaration, Constructor>;
224
227
  export type KnowledgeEntityAdapterClassDeclaration<Constructor extends new () => KnowledgeEntityAdapterImplementation = new () => KnowledgeEntityAdapterImplementation> = ClassDeclaration<KnowledgeEntityAdapterDeclaration, Constructor>;
225
- export type KnowledgeRelationAdapterClassDeclaration<Constructor extends new () => KnowledgeRelationAdapterImplementation = new () => KnowledgeRelationAdapterImplementation> = ClassDeclaration<KnowledgeRelationAdapterDeclaration, Constructor>;
226
228
  export type FieldTransformerClassDeclaration<Constructor extends new () => FieldTransformerImplementation = new () => FieldTransformerImplementation> = ClassDeclaration<FieldTransformerDeclaration, Constructor>;
227
229
  export type ToolSettingsOptionsClassDeclaration<Constructor extends new () => ToolSettingsOptionsImplementation = new () => ToolSettingsOptionsImplementation> = ClassDeclaration<ToolSettingsOptionsDeclaration, Constructor>;
228
230
  export type NotificationDefinitionInput<Schema extends FormSchemaSource, SetupSchema extends FormSchemaSource> = Omit<DefinitionInput<NotificationChannelDeclaration>, "credential" | "definition"> & 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" | "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";
3
+ export type PackagePrimitiveKind = "agent" | "knowledgeEntityAdapter" | "connection" | "connectionInstance" | "externalDatasetProvider" | "managedDatasetProvider" | "datasetParser" | "datasetBlueprint" | "datasetTableTemplate" | "documentCollection" | "documentsConnector" | "knowledgeConnectorInstance" | "datasetConnectorInstance" | "knowledgeConnector" | "knowledgeConnectorOauth" | "domain" | "domainTemplate" | "emailProvider" | "eventListener" | "externalApplication" | "externalAppGateway" | "fieldTransformer" | "knowledgeEntitySchema" | "knowledgePolicy" | "notificationChannel" | "organizationGroup" | "organizationInstructions" | "organizationSettings" | "organizationSso" | "outboundMessagingProvider" | "remoteToolCollection" | "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;
@@ -12,7 +12,6 @@ export type DomainTemplateDeclaration = PackagePrimitiveBase<"domainTemplate"> &
12
12
  domainFqn: string;
13
13
  domainName: string;
14
14
  entitySchemaFqns: readonly string[];
15
- relationSchemaFqns: readonly string[];
16
15
  }>;
17
16
  export type SkillTemplateDeclaration = PackagePrimitiveBase<"skillTemplate"> & Readonly<{
18
17
  catalogTags?: CatalogTags;
@@ -64,13 +64,6 @@ export type KnowledgeConnectorInstanceEntityBinding = KnowledgeConnectorInstance
64
64
  remoteDeletionPropagation?: KnowledgeConnectorRemoteDeletionPropagation;
65
65
  suppressEntityEvents?: boolean;
66
66
  }>;
67
- export type KnowledgeConnectorInstanceRelationBinding = KnowledgeConnectorInstanceBindingOptions & Readonly<{
68
- relationSchemaFqn: string;
69
- bindingMode?: "managed";
70
- relationImportMode?: "child_binding" | "relation_only";
71
- sourceEntityKey?: string | null;
72
- targetEntityKey?: string | null;
73
- }>;
74
67
  export type KnowledgeConnectorInstanceSchedule = Readonly<{
75
68
  key: string;
76
69
  cronExpression: string;
@@ -85,7 +78,7 @@ export type KnowledgeConnectorInstancePipeline = Readonly<{
85
78
  definition: Readonly<{
86
79
  steps: readonly Readonly<{
87
80
  tasks: readonly Readonly<{
88
- kind: "entity" | "relation";
81
+ kind: "entity";
89
82
  bindingKey: string;
90
83
  modeOverride?: "delta" | "full" | null;
91
84
  }>[];
@@ -108,7 +101,6 @@ export type KnowledgeConnectorInstanceDeclaration = PackagePrimitiveBase<"knowle
108
101
  remoteFilters?: KnowledgeConnectorInstanceRemoteFilters;
109
102
  connections?: Readonly<Record<string, ConnectorInstanceConnection>>;
110
103
  entityBindings?: readonly KnowledgeConnectorInstanceEntityBinding[];
111
- relationBindings?: readonly KnowledgeConnectorInstanceRelationBinding[];
112
104
  pipelines?: readonly KnowledgeConnectorInstancePipeline[];
113
105
  dataPolicies?: readonly KnowledgeConnectorInstanceDataPolicy[];
114
106
  }>;
@@ -60,12 +60,24 @@ export type DocumentsDeltaRequest = Readonly<{
60
60
  rootRemoteId: string;
61
61
  committedCursor?: string;
62
62
  continuation?: string;
63
+ /** Stored drive identity of the root, from `DocumentsRootAncestry.providerScopeKey`. */
64
+ providerScopeKey?: string;
63
65
  }>;
64
66
  type DocumentsDeltaItemFields = Readonly<{
67
+ /** SHA-256 of the stored bytes, computed by CI. */
65
68
  contentHash?: string;
66
69
  contentRevision?: string;
70
+ /** MIME type the provider declares for the file in its listing. */
71
+ mimeType?: string;
67
72
  parentRemoteIds: readonly string[];
73
+ /**
74
+ * Content hash the provider reports, with the algorithm as a prefix, such as
75
+ * `quickxor:<value>` or `md5:<value>`. Compare it only with a stored value.
76
+ */
77
+ providerContentHash?: string;
68
78
  remoteFileId: string;
79
+ /** Remote file id a File Shortcut points at. */
80
+ shortcutTargetRemoteId?: string;
69
81
  /** Live file metadata; omission means unobserved, null clears a previous source. */
70
82
  source?: DocumentsSource | null;
71
83
  title: string;
@@ -77,12 +89,21 @@ export type DocumentsDeltaItem = DocumentsDeltaItemFields & Readonly<{
77
89
  deleted: true;
78
90
  kind: "file" | "folder" | "unknown";
79
91
  }>;
92
+ /** A page item the connector skipped; the host shows it in the sync issues. */
93
+ export type DocumentsSyncWarning = Readonly<{
94
+ code: string;
95
+ message: string;
96
+ /** Parents of the skipped item, as on `DocumentsDeltaItem`; a removed parent folder clears the warning. */
97
+ parentRemoteIds?: readonly string[];
98
+ remoteItemKey: string;
99
+ }>;
80
100
  export type DocumentsDeltaPage = Readonly<{
81
101
  items: readonly DocumentsDeltaItem[];
82
102
  next: Readonly<{
83
103
  kind: "continuation" | "checkpoint";
84
104
  token: string;
85
105
  }>;
106
+ warnings?: readonly DocumentsSyncWarning[];
86
107
  }>;
87
108
  /** Proven by the provider adapter with its resolved connection, never browser input. */
88
109
  export type DocumentsRootAncestry = Readonly<{
@@ -140,6 +161,18 @@ export type DocumentsFetchedContent = Readonly<{
140
161
  extension?: string;
141
162
  filename?: string;
142
163
  }>;
164
+ /** Current revision of one requested file, or `missing` when the file is gone. */
165
+ export type DocumentsFileRevision = Readonly<{
166
+ contentRevision?: string;
167
+ missing?: false;
168
+ providerContentHash?: string;
169
+ remoteFileId: string;
170
+ /** Omission means unobserved; null clears a previous source. */
171
+ source?: DocumentsSource | null;
172
+ }> | Readonly<{
173
+ missing: true;
174
+ remoteFileId: string;
175
+ }>;
143
176
  export type DocumentsDeltaCursorExpired = Readonly<{
144
177
  code: "cursor_expired";
145
178
  message: string;
@@ -168,6 +201,11 @@ export type KnowledgeConnectorDeclaration = PackagePrimitiveBase<"knowledgeConne
168
201
  contributions?: readonly KnowledgeConnectorContribution[];
169
202
  defaultOutboundStrategy?: "local_first" | "remote_first";
170
203
  defaultUpdateMode?: "full" | "partial";
204
+ /**
205
+ * Seconds the host moves a delta restart point back, so changes at the
206
+ * window edge are read again. Omission means the host default, 300.
207
+ */
208
+ deltaOverlapSeconds?: number;
171
209
  discoveryDefaults?: KnowledgeConnectorDiscoveryDefaults;
172
210
  /** Entity identity is provided by an adapter unless item metadata is declared. */
173
211
  entityIdentityMode?: "adapter" | "item_metadata";
@@ -175,6 +213,8 @@ export type KnowledgeConnectorDeclaration = PackagePrimitiveBase<"knowledgeConne
175
213
  isSingleton?: boolean;
176
214
  /** Enables per-entity-binding outbound sync when the runtime implements it. */
177
215
  outboundCapability?: "declared_and_enablable" | "none";
216
+ /** Items per pull page, sent as the request `limit`. Omission means 100. */
217
+ pullPageSize?: number;
178
218
  /**
179
219
  * Author rule: a connector must offer full deletion. Omission means
180
220
  * `{ capability: "full" }`; there is no `none`. A connector therefore
@@ -186,7 +226,6 @@ export type KnowledgeConnectorDeclaration = PackagePrimitiveBase<"knowledgeConne
186
226
  remoteDeletion?: KnowledgeConnectorRemoteDeletion;
187
227
  /** Suggested schedules for root bindings created from discovered remotes. */
188
228
  recommendedImportSchedules?: readonly KnowledgePredefinedSchedule[];
189
- relationSchemaCapabilities?: readonly KnowledgeRelationSchemaCapability[];
190
229
  /** How hosts label and link references this connector imported. */
191
230
  remoteReference?: KnowledgeConnectorRemoteReference;
192
231
  settings?: PortableFormDefinition;
@@ -308,27 +347,6 @@ export type KnowledgeEntitySchemaCapability = Readonly<{
308
347
  syncIntervalSeconds?: number | null;
309
348
  updateMode?: "full" | "partial";
310
349
  }>;
311
- export type KnowledgeRelationSchemaCapability = Readonly<{
312
- extraPropsMode?: "ignore" | "import" | "inline";
313
- fieldMap?: readonly KnowledgeConnectorFieldMapRule[];
314
- fqn: string;
315
- outboundStrategy?: "local_first" | "remote_first";
316
- predefinedBindingExtras?: readonly KnowledgeConnectorBindingExtraConfig[];
317
- predefinedBindingKey?: string;
318
- predefinedBindingMode?: "external" | "managed";
319
- predefinedBindingParentEntityKey?: string;
320
- predefinedBindingRelationImportMode?: "child_binding" | "relation_only";
321
- predefinedBindingRemoteCollectionId?: string;
322
- predefinedBindingRemoteCollectionName?: string;
323
- predefinedBindingSourceEntityKey?: string;
324
- predefinedBindingTargetEntityKey?: string;
325
- predefinedSchedules?: readonly KnowledgePredefinedSchedule[];
326
- supportedSyncModes?: readonly ("delta" | "full")[];
327
- supportsInbound?: boolean;
328
- supportsOutbound?: boolean;
329
- syncIntervalSeconds?: number | null;
330
- updateMode?: "full" | "partial";
331
- }>;
332
350
  /**
333
351
  * A connector-scoped OAuth authorization-code provider. The declaration is
334
352
  * portable metadata; its runtime factory supplies the executable provider.
@@ -387,10 +405,6 @@ export type KnowledgeEntityAdapterDeclaration = PackagePrimitiveBase<"knowledgeE
387
405
  /** Opt in to post-field-map normalization; omitted flags support older runtimes. */
388
406
  normalizesImportedData?: boolean;
389
407
  }>;
390
- export type KnowledgeRelationAdapterDeclaration = PackagePrimitiveBase<"knowledgeRelationAdapter"> & Readonly<{
391
- connectorFqn: string;
392
- relationSchemaFqn: string;
393
- }>;
394
408
  export type EventListenerDeclaration = PackagePrimitiveBase<"eventListener"> & Readonly<{
395
409
  capabilities: readonly ("internal" | "poll" | "webhook")[];
396
410
  eventKind: string;
@@ -2,10 +2,11 @@ import type { AgentDeclaration, SkillDeclaration } from "./agents.js";
2
2
  import type { DomainDeclaration, DomainTemplateDeclaration, SkillTemplateDeclaration } from "./catalog.js";
3
3
  import type { ConnectionInstanceDeclaration } from "./connection-instances.js";
4
4
  import type { KnowledgeConnectorInstanceDeclaration, DatasetConnectorInstanceDeclaration } from "./connector-instances.js";
5
- import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, EmailProviderDeclaration, EventListenerDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, KnowledgeRelationAdapterDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration } from "./connectors.js";
5
+ import type { ConnectionDeclaration, DatasetParserDeclaration, ExternalDatasetProviderDeclaration, ManagedDatasetProviderDeclaration, EmailProviderDeclaration, EventListenerDeclaration, DocumentsConnectorDeclaration, KnowledgeConnectorDeclaration, KnowledgeConnectorOAuthDeclaration, KnowledgeEntityAdapterDeclaration, OrganizationSsoDeclaration, OutboundMessagingProviderDeclaration } from "./connectors.js";
6
+ import type { DocumentCollectionDeclaration } from "./document-collections.js";
6
7
  import type { ExternalAppGatewayDeclaration } from "./external-app-gateway.js";
7
8
  import type { ExternalApplicationDeclaration } from "./external-application.js";
8
- import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration, KnowledgeRelationSchemaDeclaration } from "./knowledge.js";
9
+ import type { KnowledgeEntitySchemaDeclaration, KnowledgePolicyDeclaration } from "./knowledge.js";
9
10
  import type { OrganizationGroupDeclaration } from "./organization-group.js";
10
11
  import type { OrganizationInstructionsDeclaration } from "./organization-instructions.js";
11
12
  import type { OrganizationSettingsDeclaration } from "./organization-settings.js";
@@ -14,4 +15,4 @@ import type { StudioAppDeclaration, StudioAppTemplateDeclaration, StudioComponen
14
15
  import type { DatasetBlueprintDeclaration, DatasetTableTemplateDeclaration } from "./templates.js";
15
16
  import type { FieldTransformerDeclaration, NotificationChannelDeclaration, RemoteToolCollectionDeclaration, ToolCollectionDeclaration, ToolDeclaration, ToolSettingsOptionsDeclaration } from "./tools.js";
16
17
  import type { WorkflowDeclaration, WorkflowFieldCollectionDeclaration, WorkflowFieldDeclaration, WorkflowNodeCollectionDeclaration, WorkflowNodeDeclaration, WorkflowTemplateDeclaration } from "./workflows.js";
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;
18
+ export type PackagePrimitiveDeclaration = ConnectionInstanceDeclaration | KnowledgeConnectorInstanceDeclaration | DatasetConnectorInstanceDeclaration | AgentDeclaration | OrganizationSsoDeclaration | KnowledgeEntityAdapterDeclaration | ConnectionDeclaration | DatasetParserDeclaration | DatasetBlueprintDeclaration | DatasetTableTemplateDeclaration | ExternalDatasetProviderDeclaration | ManagedDatasetProviderDeclaration | DocumentCollectionDeclaration | DocumentsConnectorDeclaration | KnowledgeConnectorDeclaration | KnowledgeConnectorOAuthDeclaration | DomainDeclaration | DomainTemplateDeclaration | EmailProviderDeclaration | EventListenerDeclaration | ExternalApplicationDeclaration | ExternalAppGatewayDeclaration | FieldTransformerDeclaration | KnowledgeEntitySchemaDeclaration | KnowledgePolicyDeclaration | NotificationChannelDeclaration | OrganizationGroupDeclaration | OrganizationInstructionsDeclaration | OrganizationSettingsDeclaration | OutboundMessagingProviderDeclaration | RemoteToolCollectionDeclaration | ServicePrincipalDeclaration | SkillDeclaration | SkillTemplateDeclaration | StudioAppDeclaration | StudioAppTemplateDeclaration | StudioComponentDeclaration | ToolCollectionDeclaration | ToolSettingsOptionsDeclaration | ToolDeclaration | WorkflowDeclaration | WorkflowFieldCollectionDeclaration | WorkflowFieldDeclaration | WorkflowNodeCollectionDeclaration | WorkflowNodeDeclaration | WorkflowTemplateDeclaration;