@collective-intelligence/extensions-sdk-backend 0.2.11 → 0.2.12

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
@@ -521,6 +521,13 @@ const Config = Schema.Struct({
521
521
  })
522
522
  ```
523
523
 
524
+ An annotation added after a decoding default or another transformation stays
525
+ on Effect's decoded side, which the projection does not describe. For a struct
526
+ property, the adapter still projects its `title` and the form keywords
527
+ `x-fqn-of` and `x-unrestricted-scope` when the encoded side has none, so a
528
+ form shows the label. It copies no other annotation: put a `description`
529
+ before the default to project it.
530
+
524
531
  When the author has separately proved that the encoded Effect contract and
525
532
  its projected JSON Schema accept exactly the same wire values, an exact-only
526
533
  consumer can be selected explicitly:
package/dist/effect.js CHANGED
@@ -1 +1 @@
1
- import{canonicalJson,definePackageSchema,normalizeJsonSchemaProjection,parseJsonObject,UnrestrictedScopeKeyword}from"@collective-intelligence/extensions-sdk";import*as Schema from"effect/Schema";var isCodecSchema=(schema,options)=>schema!==undefined&&options?.codec===true;var asJsonSchemaDocument=(value)=>{if(value===null||value===true||value===false||Array.isArray(value)||Object(value)!==value){throw new TypeError("Effect projected an invalid root JSON Schema value")}return parseJsonObject(canonicalJson(value))};var projectEncoded=(schema,fidelity,onExcessProperty)=>{const document=Schema.toJsonSchemaDocument(schema,{includeAnnotationKey:(key)=>key===UnrestrictedScopeKeyword,onExcessProperty});const projection=Object.keys(document.definitions).length===0?document.schema:{...document.schema,$defs:document.definitions};const projectionJson=Schema.decodeUnknownSync(Schema.Json)(projection);if(!Schema.is(Schema.Record(Schema.String,Schema.Json))(projectionJson)){throw new TypeError("Effect projected a boolean JSON Schema, which is not supported by package manifests")}return normalizeJsonSchemaProjection(asJsonSchemaDocument(projectionJson),fidelity)};function effectSchema(schema,options){const fidelity=options?.fidelity??"structural";const onExcessProperty=options?.onExcessProperty??"ignore";const document=projectEncoded(schema,fidelity,options?.onExcessProperty??"error");const projection={dialect:"https://json-schema.org/draft/2020-12/schema",document,fidelity};const standard=Schema.toStandardSchemaV1(schema.annotate({}),{parseOptions:{onExcessProperty}})["~standard"];if(!isCodecSchema(schema,options)){return definePackageSchema({native:schema,projections:{input:projection},provider:"effect",validate:standard.validate})}const encoder=Schema.toStandardSchemaV1(Schema.flip(schema).annotate({}),{parseOptions:{onExcessProperty}})["~standard"];const source=definePackageSchema({encode:encoder.validate,native:schema,projections:{input:projection,output:projection},provider:"effect",validate:standard.validate});return source}import*as Effect from"effect/Effect";import*as Schema2 from"effect/Schema";import*as SchemaGetter from"effect/SchemaGetter";var withWorkflowDefault=(value)=>(self)=>Schema2.optionalKey(Schema2.toEncoded(self).check(Schema2.makeFilter(()=>true,{default:value,toJsonSchema:()=>({})}))).pipe(Schema2.decodeTo(self,{decode:SchemaGetter.withDefault(Effect.succeed(value)),encode:SchemaGetter.passthrough()}));import*as Context from"effect/Context";class ExternalDatasetProvider extends Context.Service()("@collective-intelligence/extensions-sdk-backend-effect/ExternalDatasetProvider"){}import*as Context2 from"effect/Context";class ManagedDatasetProvider extends Context2.Service()("@collective-intelligence/extensions-sdk-backend-effect/ManagedDatasetProvider"){}import{ExternalDatasetProvider as BackendExternalDatasetProvider,ManagedDatasetProvider as BackendManagedDatasetProvider}from"@collective-intelligence/extensions-sdk-backend";import*as Context3 from"effect/Context";import*as Effect2 from"effect/Effect";import*as Fiber from"effect/Fiber";var runProvider=async(acquireService,context,operation)=>{const result=Effect2.scoped(Effect2.flatMap(acquireService(context),operation)).pipe(Effect2.match({onFailure:(error)=>({error,status:"failure"}),onSuccess:(value)=>({status:"success",value})}));const{signal}=context;const callerContext=Fiber.getCurrent()?.context??Context3.empty();try{return await Effect2.runPromiseWith(callerContext)(result,signal===undefined?undefined:{signal})}catch(error){if(signal?.aborted===true){throw signal.reason}throw error}};var makeExternalDatasetProviderImplementation=(acquireService)=>class ExternalDatasetProviderImplementation extends BackendExternalDatasetProvider{async readiness(input,context){return await runProvider(acquireService,context,(service)=>service.readiness(input))}async listSources(input,context){return await runProvider(acquireService,context,(service)=>service.listSources(input))}async discoverDefinition(input,context){return await runProvider(acquireService,context,(service)=>service.discoverDefinition(input))}async datasetQuery(input,context){return await runProvider(acquireService,context,(service)=>service.datasetQuery(input))}async datasetInspect(input,context){return await runProvider(acquireService,context,(service)=>service.datasetInspect(input))}};var makeManagedDatasetProviderImplementation=(acquireService)=>class ManagedDatasetProviderImplementation extends BackendManagedDatasetProvider{async readiness(input,context){return await runProvider(acquireService,context,(service)=>service.readiness(input))}async datasetProvision(input,context){return await runProvider(acquireService,context,(service)=>service.datasetProvision(input))}async datasetIngest(input,context){return await runProvider(acquireService,context,(service)=>service.datasetIngest(input))}async datasetQuery(input,context){return await runProvider(acquireService,context,(service)=>service.datasetQuery(input))}async datasetInspect(input,context){return await runProvider(acquireService,context,(service)=>service.datasetInspect(input))}async datasetDelete(input,context){return await runProvider(acquireService,context,(service)=>service.datasetDelete(input))}};import*as Schema3 from"effect/Schema";var DatasetScalarType=Schema3.Literals(["boolean","string","int64","float64","decimal","date","timestamp","duration","json"]);var SafeDiagnostic=Schema3.Struct({code:Schema3.String,fieldId:Schema3.optionalKey(Schema3.String),message:Schema3.String});var DatasetValue=Schema3.Union([Schema3.Struct({kind:Schema3.Literal("null")}),Schema3.Struct({kind:Schema3.Literal("boolean"),value:Schema3.Boolean}),Schema3.Struct({kind:Schema3.Literal("string"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("int64"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("float64"),value:Schema3.Finite}),Schema3.Struct({kind:Schema3.Literal("decimal"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("date"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("timestamp"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("duration"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("json"),value:Schema3.Json})]);var DatasetPredicateOperator=Schema3.Literals(["eq","ne","lt","lte","gt","gte","in","not_in","is_null","is_not_null","contains","starts_with"]);var DatasetAggregateOperation=Schema3.Literals(["count","count_distinct","sum","min","max","avg"]);var DatasetBindingMode=Schema3.Literals(["external","managed"]);var DatasetQueryIntent=Schema3.Literals(["records","aggregate","time_series"]);var DatasetTimeBucket=Schema3.Literals(["hour","day","week","month"]);var DatasetIngestMode=Schema3.Literals(["append","upsert","replace"]);var DatasetPredicate=Schema3.Struct({fieldId:Schema3.String,kind:Schema3.Literal("predicate"),operator:DatasetPredicateOperator,values:Schema3.Array(DatasetValue)});var DatasetFilter=Schema3.suspend(()=>Schema3.Union([DatasetPredicate,Schema3.Struct({filters:Schema3.Array(DatasetFilter),kind:Schema3.Literals(["and","or"])}),Schema3.Struct({filter:DatasetFilter,kind:Schema3.Literal("not")})]));var DatasetOrder=Schema3.Struct({direction:Schema3.Literals(["asc","desc"]),fieldOrAlias:Schema3.String});var DatasetOperation=Schema3.Union([Schema3.Struct({cursor:Schema3.optionalKey(Schema3.String),filter:Schema3.optionalKey(DatasetFilter),kind:Schema3.Literal("records"),orderBy:Schema3.Array(DatasetOrder),projection:Schema3.Array(Schema3.String)}),Schema3.Struct({cursor:Schema3.optionalKey(Schema3.String),filter:Schema3.optionalKey(DatasetFilter),groupBy:Schema3.Array(Schema3.String),kind:Schema3.Literal("aggregate"),measures:Schema3.Array(Schema3.Struct({alias:Schema3.String,fieldId:Schema3.optionalKey(Schema3.String),operation:DatasetAggregateOperation})),orderBy:Schema3.Array(DatasetOrder)}),Schema3.Struct({bucket:DatasetTimeBucket,cursor:Schema3.optionalKey(Schema3.String),filter:Schema3.optionalKey(DatasetFilter),kind:Schema3.Literal("time_series"),measure:Schema3.Struct({alias:Schema3.String,fieldId:Schema3.optionalKey(Schema3.String),operation:DatasetAggregateOperation}),order:Schema3.Literals(["asc","desc"]),timeFieldId:Schema3.String})]);var DatasetProviderCapabilities=Schema3.Struct({aggregates:Schema3.Array(DatasetAggregateOperation),definitionRefresh:Schema3.Boolean,grouping:Schema3.Boolean,intents:Schema3.Array(DatasetQueryIntent),limits:Schema3.Struct({maxBytes:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),maxPageRows:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),maxRows:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),timeoutMs:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0)))}),ordering:Schema3.Boolean,pagination:Schema3.Boolean,predicates:Schema3.Array(DatasetPredicateOperator)});var ConnectorContext=Schema3.Struct({correlationId:Schema3.String,deadlineEpochMs:Schema3.Finite});var Bounds=Schema3.Struct({maxBytes:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),maxRows:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),timeoutMs:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0)))});var SourceSegment=Schema3.Struct({kind:Schema3.Literals(["container","dataset"]),label:Schema3.String,opaqueId:Schema3.String});var SourceRoot=Schema3.Struct({kind:Schema3.Literal("container"),label:Schema3.String,opaqueId:Schema3.String});var DatasetSourceLocation=Schema3.Struct({segments:Schema3.TupleWithRest(Schema3.Tuple([SourceRoot]),[SourceSegment])});var Compatibility=Schema3.Union([Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),status:Schema3.Literal("compatible")}),Schema3.Struct({diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literal("incompatible")})]);var DatasetSourceItem=Schema3.Struct({compatibility:Compatibility,description:Schema3.optionalKey(Schema3.String),kind:Schema3.Literals(["container","dataset"]),label:Schema3.String,location:DatasetSourceLocation,selectable:Schema3.Boolean});var Readiness=Schema3.Union([Schema3.Struct({capabilities:DatasetProviderCapabilities,status:Schema3.Literal("ready")}),Schema3.Struct({diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literal("not_ready")})]);var SourcePage=Schema3.Struct({items:Schema3.Array(DatasetSourceItem),nextCursor:Schema3.optionalKey(Schema3.String),truncated:Schema3.Boolean});var DatasetDefinition=Schema3.Struct({fields:Schema3.Array(Schema3.Struct({id:Schema3.String,name:Schema3.String,nullable:Schema3.Boolean,semantic:Schema3.optionalKey(Schema3.String),type:DatasetScalarType})),measures:Schema3.Array(Schema3.Struct({id:Schema3.String,name:Schema3.String,resultType:DatasetScalarType})),relationships:Schema3.Array(Schema3.Struct({cardinality:Schema3.Literals(["one_to_one","one_to_many","many_to_one","many_to_many"]),fromFieldId:Schema3.String,id:Schema3.String,toFieldId:Schema3.String})),version:Schema3.Literal(1)});var DefinitionProposal=Schema3.Struct({compatibility:Compatibility,definition:DatasetDefinition,diagnostics:Schema3.Array(SafeDiagnostic),label:Schema3.String,location:DatasetSourceLocation,observedAt:Schema3.String});var ReadinessInput=ConnectorContext;var ListSourcesInput=ConnectorContext.pipe(Schema3.fieldsAssign({cursor:Schema3.optionalKey(Schema3.String),limit:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),parent:Schema3.optionalKey(DatasetSourceLocation)}));var DiscoverDefinitionInput=ConnectorContext.pipe(Schema3.fieldsAssign({location:DatasetSourceLocation}));var QueryInput=ConnectorContext.pipe(Schema3.fieldsAssign({bounds:Bounds,definition:DatasetDefinition,definitionRevisionId:Schema3.String,location:DatasetSourceLocation,operation:DatasetOperation}));var DatasetHealth=Schema3.Union([Schema3.Struct({status:Schema3.Literal("unknown")}),Schema3.Struct({checkedAt:Schema3.String,status:Schema3.Literal("healthy")}),Schema3.Struct({checkedAt:Schema3.String,diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literals(["degraded","unavailable"])})]);var DatasetProvisionInput=ConnectorContext.pipe(Schema3.fieldsAssign({definition:DatasetDefinition,definitionRevisionId:Schema3.String,templateFqn:Schema3.String}));var DatasetProvisionResult=Schema3.Struct({physicalLocator:Schema3.String});var DatasetIngestResult=Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),rowCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0)))});var DatasetInspectInput=ConnectorContext.pipe(Schema3.fieldsAssign({definitionRevisionId:Schema3.String,location:Schema3.optionalKey(DatasetSourceLocation),physicalLocator:Schema3.optionalKey(Schema3.String)}));var DatasetInspectResult=Schema3.Struct({health:DatasetHealth});var DatasetDeleteInput=ConnectorContext.pipe(Schema3.fieldsAssign({definitionRevisionId:Schema3.String,physicalLocator:Schema3.String}));var DatasetDeleteResult=Schema3.Struct({status:Schema3.Literal("deleted")});var ExternalDatasetBinding=Schema3.Struct({admittedRevisionId:Schema3.String,compatibility:Compatibility,connectionId:Schema3.String,connectorFqn:Schema3.String,createdAt:Schema3.String,datasetId:Schema3.String,health:DatasetHealth,location:DatasetSourceLocation,mode:Schema3.Literal("external"),refresh:Schema3.Union([Schema3.Struct({status:Schema3.Literal("idle")}),Schema3.Struct({operationId:Schema3.String,status:Schema3.Literal("running")}),Schema3.Struct({proposalId:Schema3.String,status:Schema3.Literal("review_required")}),Schema3.Struct({diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literal("failed")})]),updatedAt:Schema3.String});var DatasetRecordPage=Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),columns:Schema3.Array(Schema3.Struct({fieldId:Schema3.String,type:DatasetScalarType})),nextCursor:Schema3.optionalKey(Schema3.String),observedAt:Schema3.String,rowCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),rows:Schema3.Array(Schema3.Array(DatasetValue))});var DatasetIngestInput=ConnectorContext.pipe(Schema3.fieldsAssign({definition:DatasetDefinition,definitionRevisionId:Schema3.String,mode:DatasetIngestMode,physicalLocator:Schema3.String,records:DatasetRecordPage}));var DatasetResultPage=Schema3.Union([DatasetRecordPage.pipe(Schema3.fieldsAssign({kind:Schema3.Literal("records")})),Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),columns:Schema3.Array(Schema3.Struct({alias:Schema3.String,type:DatasetScalarType})),kind:Schema3.Literal("aggregate"),nextCursor:Schema3.optionalKey(Schema3.String),observedAt:Schema3.String,rowCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),rows:Schema3.Array(Schema3.Array(DatasetValue))}),Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),kind:Schema3.Literal("time_series"),nextCursor:Schema3.optionalKey(Schema3.String),observedAt:Schema3.String,pointCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),points:Schema3.Array(Schema3.Struct({time:Schema3.String,value:DatasetValue})),valueType:DatasetScalarType})]);var DatasetProviderError=Schema3.Union([Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),kind:Schema3.Literals(["not_ready","incompatible_source","unsupported_operation","policy_not_pushable","invalid_cursor","timeout","permission_denied","provider_unavailable","provider_rejected","invalid_provider_response"])}),Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),kind:Schema3.Literal("limit_exceeded"),limit:Schema3.Literals(["rows","bytes","timeout"])}),Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),kind:Schema3.Literal("throttled"),retryAfterMs:Schema3.optionalKey(Schema3.Int)})]);export{Bounds,Compatibility,ConnectorContext,DatasetAggregateOperation,DatasetBindingMode,DatasetDefinition,DatasetDeleteInput,DatasetDeleteResult,DatasetFilter,DatasetHealth,DatasetIngestInput,DatasetIngestMode,DatasetIngestResult,DatasetInspectInput,DatasetInspectResult,DatasetOperation,DatasetOrder,DatasetPredicate,DatasetPredicateOperator,DatasetProviderCapabilities,DatasetProviderError,DatasetProvisionInput,DatasetProvisionResult,DatasetQueryIntent,DatasetRecordPage,DatasetResultPage,DatasetScalarType,DatasetSourceItem,DatasetSourceLocation,DatasetTimeBucket,DatasetValue,DefinitionProposal,DiscoverDefinitionInput,ExternalDatasetBinding,ExternalDatasetProvider,ListSourcesInput,ManagedDatasetProvider,QueryInput,Readiness,ReadinessInput,SafeDiagnostic,SourcePage,effectSchema,makeExternalDatasetProviderImplementation,makeManagedDatasetProviderImplementation,withWorkflowDefault};
1
+ import{canonicalJson,definePackageSchema,FqnOfKeyword,normalizeJsonSchemaProjection,parseJsonObject,UnrestrictedScopeKeyword}from"@collective-intelligence/extensions-sdk";import*as Schema from"effect/Schema";import*as SchemaAST from"effect/SchemaAST";var formKeywords=new Set([FqnOfKeyword,UnrestrictedScopeKeyword]);var formAnnotations=["title",...formKeywords];var annotationsOf=(ast)=>Schema.resolveAnnotations(Schema.make(ast));var withDecodedFormAnnotations=(ast,document)=>{const{properties}=document;if(!SchemaAST.isObjects(ast)||ast.encoding!==undefined||properties===undefined){return document}const decodedTypes=new Map(ast.propertySignatures.map(({name,type})=>[name,type]));return{...document,properties:Object.fromEntries(Object.entries(properties).map(([name,property])=>{const type=decodedTypes.get(name);if(type===undefined){return[name,property]}const decoded=annotationsOf(type);const encoded=annotationsOf(SchemaAST.toEncoded(type));const carried=formAnnotations.flatMap((key)=>{const value=decoded?.[key];return property[key]===undefined&&encoded?.[key]===undefined&&Schema.is(Schema.Json)(value)?[[key,value]]:[]});return[name,{...withDecodedFormAnnotations(type,property),...Object.fromEntries(carried)}]}))}};var isCodecSchema=(schema,options)=>schema!==undefined&&options?.codec===true;var asJsonSchemaDocument=(value)=>{if(value===null||value===true||value===false||Array.isArray(value)||Object(value)!==value){throw new TypeError("Effect projected an invalid root JSON Schema value")}return parseJsonObject(canonicalJson(value))};var projectEncoded=(schema,fidelity,onExcessProperty)=>{const document=Schema.toJsonSchemaDocument(schema,{includeAnnotationKey:(key)=>formKeywords.has(key),onExcessProperty});const projection=Object.keys(document.definitions).length===0?document.schema:{...document.schema,$defs:document.definitions};const projectionJson=Schema.decodeUnknownSync(Schema.Json)(projection);if(!Schema.is(Schema.Record(Schema.String,Schema.Json))(projectionJson)){throw new TypeError("Effect projected a boolean JSON Schema, which is not supported by package manifests")}return withDecodedFormAnnotations(schema.ast,normalizeJsonSchemaProjection(asJsonSchemaDocument(projectionJson),fidelity))};function effectSchema(schema,options){const fidelity=options?.fidelity??"structural";const onExcessProperty=options?.onExcessProperty??"ignore";const document=projectEncoded(schema,fidelity,options?.onExcessProperty??"error");const projection={dialect:"https://json-schema.org/draft/2020-12/schema",document,fidelity};const standard=Schema.toStandardSchemaV1(schema.annotate({}),{parseOptions:{onExcessProperty}})["~standard"];if(!isCodecSchema(schema,options)){return definePackageSchema({native:schema,projections:{input:projection},provider:"effect",validate:standard.validate})}const encoder=Schema.toStandardSchemaV1(Schema.flip(schema).annotate({}),{parseOptions:{onExcessProperty}})["~standard"];const source=definePackageSchema({encode:encoder.validate,native:schema,projections:{input:projection,output:projection},provider:"effect",validate:standard.validate});return source}import*as Effect from"effect/Effect";import*as Schema2 from"effect/Schema";import*as SchemaGetter from"effect/SchemaGetter";var withWorkflowDefault=(value)=>(self)=>Schema2.optionalKey(Schema2.toEncoded(self).check(Schema2.makeFilter(()=>true,{default:value,toJsonSchema:()=>({})}))).pipe(Schema2.decodeTo(self,{decode:SchemaGetter.withDefault(Effect.succeed(value)),encode:SchemaGetter.passthrough()}));import*as Context from"effect/Context";class ExternalDatasetProvider extends Context.Service()("@collective-intelligence/extensions-sdk-backend-effect/ExternalDatasetProvider"){}import*as Context2 from"effect/Context";class ManagedDatasetProvider extends Context2.Service()("@collective-intelligence/extensions-sdk-backend-effect/ManagedDatasetProvider"){}import{ExternalDatasetProvider as BackendExternalDatasetProvider,ManagedDatasetProvider as BackendManagedDatasetProvider}from"@collective-intelligence/extensions-sdk-backend";import*as Context3 from"effect/Context";import*as Effect2 from"effect/Effect";import*as Fiber from"effect/Fiber";var runProvider=async(acquireService,context,operation)=>{const result=Effect2.scoped(Effect2.flatMap(acquireService(context),operation)).pipe(Effect2.match({onFailure:(error)=>({error,status:"failure"}),onSuccess:(value)=>({status:"success",value})}));const{signal}=context;const callerContext=Fiber.getCurrent()?.context??Context3.empty();try{return await Effect2.runPromiseWith(callerContext)(result,signal===undefined?undefined:{signal})}catch(error){if(signal?.aborted===true){throw signal.reason}throw error}};var makeExternalDatasetProviderImplementation=(acquireService)=>class ExternalDatasetProviderImplementation extends BackendExternalDatasetProvider{async readiness(input,context){return await runProvider(acquireService,context,(service)=>service.readiness(input))}async listSources(input,context){return await runProvider(acquireService,context,(service)=>service.listSources(input))}async discoverDefinition(input,context){return await runProvider(acquireService,context,(service)=>service.discoverDefinition(input))}async datasetQuery(input,context){return await runProvider(acquireService,context,(service)=>service.datasetQuery(input))}async datasetInspect(input,context){return await runProvider(acquireService,context,(service)=>service.datasetInspect(input))}};var makeManagedDatasetProviderImplementation=(acquireService)=>class ManagedDatasetProviderImplementation extends BackendManagedDatasetProvider{async readiness(input,context){return await runProvider(acquireService,context,(service)=>service.readiness(input))}async datasetProvision(input,context){return await runProvider(acquireService,context,(service)=>service.datasetProvision(input))}async datasetIngest(input,context){return await runProvider(acquireService,context,(service)=>service.datasetIngest(input))}async datasetQuery(input,context){return await runProvider(acquireService,context,(service)=>service.datasetQuery(input))}async datasetInspect(input,context){return await runProvider(acquireService,context,(service)=>service.datasetInspect(input))}async datasetDelete(input,context){return await runProvider(acquireService,context,(service)=>service.datasetDelete(input))}};import*as Schema3 from"effect/Schema";var DatasetScalarType=Schema3.Literals(["boolean","string","int64","float64","decimal","date","timestamp","duration","json"]);var SafeDiagnostic=Schema3.Struct({code:Schema3.String,fieldId:Schema3.optionalKey(Schema3.String),message:Schema3.String});var DatasetValue=Schema3.Union([Schema3.Struct({kind:Schema3.Literal("null")}),Schema3.Struct({kind:Schema3.Literal("boolean"),value:Schema3.Boolean}),Schema3.Struct({kind:Schema3.Literal("string"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("int64"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("float64"),value:Schema3.Finite}),Schema3.Struct({kind:Schema3.Literal("decimal"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("date"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("timestamp"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("duration"),value:Schema3.String}),Schema3.Struct({kind:Schema3.Literal("json"),value:Schema3.Json})]);var DatasetPredicateOperator=Schema3.Literals(["eq","ne","lt","lte","gt","gte","in","not_in","is_null","is_not_null","contains","starts_with"]);var DatasetAggregateOperation=Schema3.Literals(["count","count_distinct","sum","min","max","avg"]);var DatasetBindingMode=Schema3.Literals(["external","managed"]);var DatasetQueryIntent=Schema3.Literals(["records","aggregate","time_series"]);var DatasetTimeBucket=Schema3.Literals(["hour","day","week","month"]);var DatasetIngestMode=Schema3.Literals(["append","upsert","replace"]);var DatasetPredicate=Schema3.Struct({fieldId:Schema3.String,kind:Schema3.Literal("predicate"),operator:DatasetPredicateOperator,values:Schema3.Array(DatasetValue)});var DatasetFilter=Schema3.suspend(()=>Schema3.Union([DatasetPredicate,Schema3.Struct({filters:Schema3.Array(DatasetFilter),kind:Schema3.Literals(["and","or"])}),Schema3.Struct({filter:DatasetFilter,kind:Schema3.Literal("not")})]));var DatasetOrder=Schema3.Struct({direction:Schema3.Literals(["asc","desc"]),fieldOrAlias:Schema3.String});var DatasetOperation=Schema3.Union([Schema3.Struct({cursor:Schema3.optionalKey(Schema3.String),filter:Schema3.optionalKey(DatasetFilter),kind:Schema3.Literal("records"),orderBy:Schema3.Array(DatasetOrder),projection:Schema3.Array(Schema3.String)}),Schema3.Struct({cursor:Schema3.optionalKey(Schema3.String),filter:Schema3.optionalKey(DatasetFilter),groupBy:Schema3.Array(Schema3.String),kind:Schema3.Literal("aggregate"),measures:Schema3.Array(Schema3.Struct({alias:Schema3.String,fieldId:Schema3.optionalKey(Schema3.String),operation:DatasetAggregateOperation})),orderBy:Schema3.Array(DatasetOrder)}),Schema3.Struct({bucket:DatasetTimeBucket,cursor:Schema3.optionalKey(Schema3.String),filter:Schema3.optionalKey(DatasetFilter),kind:Schema3.Literal("time_series"),measure:Schema3.Struct({alias:Schema3.String,fieldId:Schema3.optionalKey(Schema3.String),operation:DatasetAggregateOperation}),order:Schema3.Literals(["asc","desc"]),timeFieldId:Schema3.String})]);var DatasetProviderCapabilities=Schema3.Struct({aggregates:Schema3.Array(DatasetAggregateOperation),definitionRefresh:Schema3.Boolean,grouping:Schema3.Boolean,intents:Schema3.Array(DatasetQueryIntent),limits:Schema3.Struct({maxBytes:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),maxPageRows:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),maxRows:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),timeoutMs:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0)))}),ordering:Schema3.Boolean,pagination:Schema3.Boolean,predicates:Schema3.Array(DatasetPredicateOperator)});var ConnectorContext=Schema3.Struct({correlationId:Schema3.String,deadlineEpochMs:Schema3.Finite});var Bounds=Schema3.Struct({maxBytes:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),maxRows:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),timeoutMs:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0)))});var SourceSegment=Schema3.Struct({kind:Schema3.Literals(["container","dataset"]),label:Schema3.String,opaqueId:Schema3.String});var SourceRoot=Schema3.Struct({kind:Schema3.Literal("container"),label:Schema3.String,opaqueId:Schema3.String});var DatasetSourceLocation=Schema3.Struct({segments:Schema3.TupleWithRest(Schema3.Tuple([SourceRoot]),[SourceSegment])});var Compatibility=Schema3.Union([Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),status:Schema3.Literal("compatible")}),Schema3.Struct({diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literal("incompatible")})]);var DatasetSourceItem=Schema3.Struct({compatibility:Compatibility,description:Schema3.optionalKey(Schema3.String),kind:Schema3.Literals(["container","dataset"]),label:Schema3.String,location:DatasetSourceLocation,selectable:Schema3.Boolean});var Readiness=Schema3.Union([Schema3.Struct({capabilities:DatasetProviderCapabilities,status:Schema3.Literal("ready")}),Schema3.Struct({diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literal("not_ready")})]);var SourcePage=Schema3.Struct({items:Schema3.Array(DatasetSourceItem),nextCursor:Schema3.optionalKey(Schema3.String),truncated:Schema3.Boolean});var DatasetDefinition=Schema3.Struct({fields:Schema3.Array(Schema3.Struct({id:Schema3.String,name:Schema3.String,nullable:Schema3.Boolean,semantic:Schema3.optionalKey(Schema3.String),type:DatasetScalarType})),measures:Schema3.Array(Schema3.Struct({id:Schema3.String,name:Schema3.String,resultType:DatasetScalarType})),relationships:Schema3.Array(Schema3.Struct({cardinality:Schema3.Literals(["one_to_one","one_to_many","many_to_one","many_to_many"]),fromFieldId:Schema3.String,id:Schema3.String,toFieldId:Schema3.String})),version:Schema3.Literal(1)});var DefinitionProposal=Schema3.Struct({compatibility:Compatibility,definition:DatasetDefinition,diagnostics:Schema3.Array(SafeDiagnostic),label:Schema3.String,location:DatasetSourceLocation,observedAt:Schema3.String});var ReadinessInput=ConnectorContext;var ListSourcesInput=ConnectorContext.pipe(Schema3.fieldsAssign({cursor:Schema3.optionalKey(Schema3.String),limit:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThan(0))),parent:Schema3.optionalKey(DatasetSourceLocation)}));var DiscoverDefinitionInput=ConnectorContext.pipe(Schema3.fieldsAssign({location:DatasetSourceLocation}));var QueryInput=ConnectorContext.pipe(Schema3.fieldsAssign({bounds:Bounds,definition:DatasetDefinition,definitionRevisionId:Schema3.String,location:DatasetSourceLocation,operation:DatasetOperation}));var DatasetHealth=Schema3.Union([Schema3.Struct({status:Schema3.Literal("unknown")}),Schema3.Struct({checkedAt:Schema3.String,status:Schema3.Literal("healthy")}),Schema3.Struct({checkedAt:Schema3.String,diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literals(["degraded","unavailable"])})]);var DatasetProvisionInput=ConnectorContext.pipe(Schema3.fieldsAssign({definition:DatasetDefinition,definitionRevisionId:Schema3.String,templateFqn:Schema3.String}));var DatasetProvisionResult=Schema3.Struct({physicalLocator:Schema3.String});var DatasetIngestResult=Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),rowCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0)))});var DatasetInspectInput=ConnectorContext.pipe(Schema3.fieldsAssign({definitionRevisionId:Schema3.String,location:Schema3.optionalKey(DatasetSourceLocation),physicalLocator:Schema3.optionalKey(Schema3.String)}));var DatasetInspectResult=Schema3.Struct({health:DatasetHealth});var DatasetDeleteInput=ConnectorContext.pipe(Schema3.fieldsAssign({definitionRevisionId:Schema3.String,physicalLocator:Schema3.String}));var DatasetDeleteResult=Schema3.Struct({status:Schema3.Literal("deleted")});var ExternalDatasetBinding=Schema3.Struct({admittedRevisionId:Schema3.String,compatibility:Compatibility,connectionId:Schema3.String,connectorFqn:Schema3.String,createdAt:Schema3.String,datasetId:Schema3.String,health:DatasetHealth,location:DatasetSourceLocation,mode:Schema3.Literal("external"),refresh:Schema3.Union([Schema3.Struct({status:Schema3.Literal("idle")}),Schema3.Struct({operationId:Schema3.String,status:Schema3.Literal("running")}),Schema3.Struct({proposalId:Schema3.String,status:Schema3.Literal("review_required")}),Schema3.Struct({diagnostics:Schema3.NonEmptyArray(SafeDiagnostic),status:Schema3.Literal("failed")})]),updatedAt:Schema3.String});var DatasetRecordPage=Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),columns:Schema3.Array(Schema3.Struct({fieldId:Schema3.String,type:DatasetScalarType})),nextCursor:Schema3.optionalKey(Schema3.String),observedAt:Schema3.String,rowCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),rows:Schema3.Array(Schema3.Array(DatasetValue))});var DatasetIngestInput=ConnectorContext.pipe(Schema3.fieldsAssign({definition:DatasetDefinition,definitionRevisionId:Schema3.String,mode:DatasetIngestMode,physicalLocator:Schema3.String,records:DatasetRecordPage}));var DatasetResultPage=Schema3.Union([DatasetRecordPage.pipe(Schema3.fieldsAssign({kind:Schema3.Literal("records")})),Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),columns:Schema3.Array(Schema3.Struct({alias:Schema3.String,type:DatasetScalarType})),kind:Schema3.Literal("aggregate"),nextCursor:Schema3.optionalKey(Schema3.String),observedAt:Schema3.String,rowCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),rows:Schema3.Array(Schema3.Array(DatasetValue))}),Schema3.Struct({byteCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),kind:Schema3.Literal("time_series"),nextCursor:Schema3.optionalKey(Schema3.String),observedAt:Schema3.String,pointCount:Schema3.Int.pipe(Schema3.check(Schema3.isGreaterThanOrEqualTo(0))),points:Schema3.Array(Schema3.Struct({time:Schema3.String,value:DatasetValue})),valueType:DatasetScalarType})]);var DatasetProviderError=Schema3.Union([Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),kind:Schema3.Literals(["not_ready","incompatible_source","unsupported_operation","policy_not_pushable","invalid_cursor","timeout","permission_denied","provider_unavailable","provider_rejected","invalid_provider_response"])}),Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),kind:Schema3.Literal("limit_exceeded"),limit:Schema3.Literals(["rows","bytes","timeout"])}),Schema3.Struct({diagnostics:Schema3.Array(SafeDiagnostic),kind:Schema3.Literal("throttled"),retryAfterMs:Schema3.optionalKey(Schema3.Int)})]);export{Bounds,Compatibility,ConnectorContext,DatasetAggregateOperation,DatasetBindingMode,DatasetDefinition,DatasetDeleteInput,DatasetDeleteResult,DatasetFilter,DatasetHealth,DatasetIngestInput,DatasetIngestMode,DatasetIngestResult,DatasetInspectInput,DatasetInspectResult,DatasetOperation,DatasetOrder,DatasetPredicate,DatasetPredicateOperator,DatasetProviderCapabilities,DatasetProviderError,DatasetProvisionInput,DatasetProvisionResult,DatasetQueryIntent,DatasetRecordPage,DatasetResultPage,DatasetScalarType,DatasetSourceItem,DatasetSourceLocation,DatasetTimeBucket,DatasetValue,DefinitionProposal,DiscoverDefinitionInput,ExternalDatasetBinding,ExternalDatasetProvider,ListSourcesInput,ManagedDatasetProvider,QueryInput,Readiness,ReadinessInput,SafeDiagnostic,SourcePage,effectSchema,makeExternalDatasetProviderImplementation,makeManagedDatasetProviderImplementation,withWorkflowDefault};
@@ -144,20 +144,25 @@ The declaration of an Agent sets the most it can do: its tools, scopes, approval
144
144
 
145
145
  ## Approvals
146
146
 
147
- An entry in a `tools` list can be a `ToolBinding` instead of a bare reference. A binding can rename the tool, set its settings, narrow its Knowledge and choose an approval mode, and you can bind one tool several times under different names:
147
+ An entry in a `tools` list can be a `ToolBinding` instead of a bare reference. A binding can rename the tool, give it a Binding Description, set its Binding Settings and choose an approval mode, and you can bind one tool several times under different names:
148
148
 
149
149
  ```ts
150
150
  tools: [
151
151
  {
152
152
  tool: "builtin.core.knowledge.tools.query",
153
- name: "member-query",
154
- settings: { limit: 10 },
155
- knowledge: { domains: { include: [membersDomain] } },
153
+ name: "lead-query",
154
+ description: "Search the Leads of the CRM",
155
+ settings: {
156
+ // The Knowledge tools' form marks this field "x-fqn-of": "knowledge-entity-schema".
157
+ allowedEntitySchemaIds: [leadSchemaFqn]
158
+ },
156
159
  approval: { rule: "Escalations" }
157
160
  }
158
161
  ]
159
162
  ```
160
163
 
164
+ `name`, `description` and `approval` work the same way for every tool. The model sees the Binding Description in place of the tool's own description. `settings` holds the tool's own options, and the tool's Binding Settings Form defines them, so install fails on a key that the form does not define. A field that the form marks with `x-fqn-of` takes FQNs, and install translates each FQN into the id of the installing Organization's record. Install fails when an FQN names no record of that Organization, and the error names every such FQN of the binding. A binding has no tool-specific property.
165
+
161
166
  `approval` has three modes. `"never"` makes no approval request for the binding. `"always"` pauses for an explicit decision by the user who started the call, and that user's eligibility to approve does not approve the call. `{ rule: "<rule name>" }` uses an approval rule of the installing Organization, with that rule's reviewers and expiry. Install fails when no rule has the name, so create the rule in the target Organization before you install a demo package that uses one.
162
167
 
163
168
  Approval pauses the call and leaves the tool visible. With `"always"`, the model still sees the tool definition and can decide to call it, and the call then waits for a person.
@@ -312,7 +317,7 @@ An agent reads data only through the tools it is bound to. The core packages pro
312
317
 
313
318
  Knowledge Query has seven intents: `autocomplete`, `search`, `facets`, `facet_values`, `count`, `get` and `relation_members`. `search`, `count` and the two facet intents need an `entitySchemaId`, and `get` needs an `entityId`. A missing id fails with `invalid_input`, so tell the model in the Skill or the Role to find schema ids with Knowledge `catalog` first and never to invent one. When a schema has record or indexed-file embeddings, Query also runs semantic retrieval on PostgreSQL with pgvector, and the model never sees the vectors or the embedding provider.
314
319
 
315
- Two settings decide what these tools can read. A binding's `knowledge` field narrows a tool to included or excluded domains and entity schemas, as the `member-query` binding above does. `dataAccess` on `declareAgent`, `declareSkill` or `declareWorkflow` decides, separately for `knowledge`, `documents` and `datasets`, whose permission applies. With `"user"`, the run reads what the acting person can read. With the declaration's own kind (`"agent"`, `"skill"` or `"workflow"`), which is the default, the run reads its configured resources without the caller's permission on the source. `dataAccess` grants no extra tool bindings.
320
+ Two settings decide what these tools can read. The Binding Settings of a Knowledge tool narrow it to allowed or excluded domains and entity schemas (`allowedDomainIds`, `excludedDomainIds`, `allowedEntitySchemaIds` and `excludedEntitySchemaIds`), as the `lead-query` binding above does. The Information tools take `allowedEntitySchemaIds` in the same way, and when Advanced Retrieval loads Expand Passage and Read Source Range, they use its Binding Settings. `dataAccess` on `declareAgent`, `declareSkill` or `declareWorkflow` decides, separately for `knowledge`, `documents` and `datasets`, whose permission applies. With `"user"`, the run reads what the acting person can read. With the declaration's own kind (`"agent"`, `"skill"` or `"workflow"`), which is the default, the run reads its configured resources without the caller's permission on the source. `dataAccess` grants no extra tool bindings.
316
321
 
317
322
  ```ts
318
323
  const dataAccess = {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@collective-intelligence/extensions-sdk-backend",
3
- "version": "0.2.11",
3
+ "version": "0.2.12",
4
4
  "description": "Framework-neutral executable contracts for Collective Intelligence extension packages, with an Effect adapter at ./effect.",
5
5
  "type": "module",
6
6
  "sideEffects": false,
@@ -44,7 +44,7 @@
44
44
  "access": "public"
45
45
  },
46
46
  "dependencies": {
47
- "@collective-intelligence/extensions-sdk": "0.2.10"
47
+ "@collective-intelligence/extensions-sdk": "0.2.11"
48
48
  },
49
49
  "peerDependencies": {
50
50
  "effect": "^4.1.0"
@@ -64,5 +64,5 @@
64
64
  "typescript": "7.0.2",
65
65
  "ultracite": "7.10.7"
66
66
  },
67
- "gitHead": "4cefe91552731170db20795b65c41115fd65c62b"
67
+ "gitHead": "b0f4929291e18278637c715476bb981c6d63db15"
68
68
  }