@collective-intelligence/extensions-sdk-backend 0.2.0 → 0.2.2

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/AGENTS.md ADDED
@@ -0,0 +1,30 @@
1
+ # `@collective-intelligence/extensions-sdk-backend`: agent guide
2
+
3
+ The executable contracts of Collective Intelligence (CI) backend extensions:
4
+ component base classes, host capabilities and the runtime context. Portable
5
+ declarations, schemas and manifests stay in `extensions-sdk`. The package
6
+ `README.md` holds the full API.
7
+
8
+ ## Rules
9
+
10
+ - Import executable contracts from the root `.`, and the Effect adapter
11
+ (`effectSchema`, `withWorkflowDefault`, the Dataset Provider ports) from
12
+ `/effect`. The package `extensions-sdk-backend-effect` is removed after
13
+ 0.2.0.
14
+ - Keep one `effect` (`^4.1.0`) in the extension package. It is a required
15
+ peer.
16
+ - Read tenant data, capabilities and configuration only from the `context` of
17
+ the current call; keep none in module state.
18
+ - Report a failure that the author can act on with the error class of its
19
+ component, for example `PackageWorkflowNodeError({ code, message })`. Keep
20
+ secrets out of `message`.
21
+
22
+ ## Index
23
+
24
+ - [docs/effect.md](docs/effect.md): read when you author an extension with
25
+ Effect: schemas, codecs, Dataset Providers.
26
+ - [docs/errors.md](docs/errors.md): read when a component must report a
27
+ failure, or you map a Dataset Provider error.
28
+ - [skills/extensions-sdk-backend-move-to-effect/SKILL.md](skills/extensions-sdk-backend-move-to-effect/SKILL.md):
29
+ run when code imports `extensions-sdk-backend-effect`, or a Dataset Provider
30
+ runs Effect code without the `/effect` ports.
package/README.md CHANGED
@@ -437,9 +437,15 @@ errors. The wildcard uses the existing declaration shape.
437
437
 
438
438
  `@collective-intelligence/extensions-sdk-backend/effect` holds the Effect Schema
439
439
  adapter for `@collective-intelligence/extensions-sdk` and the Effect Dataset
440
- Provider ports. Use it only when an extension is authored with Effect. It was
441
- the package `@collective-intelligence/extensions-sdk-backend-effect`, which now
442
- re-exports these names and is deprecated.
440
+ Provider ports. Use it only when an extension is authored with Effect.
441
+
442
+ **Breaking:** the release after 0.2.0 removes the packages
443
+ `@collective-intelligence/extensions-sdk-backend-effect` and
444
+ `@collective-intelligence/extensions-sdk-backend-zod`. Their last version is
445
+ 0.2.0. Import `@collective-intelligence/extensions-sdk-backend/effect`
446
+ instead of `extensions-sdk-backend-effect`: the names are the same. Declare
447
+ package schemas with Effect Schema from `./effect` instead of
448
+ `extensions-sdk-backend-zod`.
443
449
 
444
450
  `ExternalDatasetProvider` and `ManagedDatasetProvider` have two meanings. At
445
451
  `./effect` they are the Effect tags of the provider services; at `.` they are
@@ -448,7 +454,7 @@ the abstract base classes. The class that
448
454
  `makeManagedDatasetProviderImplementation` returns extends the `.` class.
449
455
  The tag keys keep the prefix
450
456
  `@collective-intelligence/extensions-sdk-backend-effect/`, so a tag of an older
451
- copy of the deprecated package still matches.
457
+ copy of the removed package still matches.
452
458
 
453
459
  `ci package build` bundles `./effect` into the release and keeps `.`
454
460
  Host-provided. An earlier CLI keeps `./effect` external, and
package/docs/effect.md ADDED
@@ -0,0 +1,75 @@
1
+ # Effect adapter
2
+
3
+ `/effect` holds the Effect Schema adapter for `extensions-sdk` and the Effect
4
+ Dataset Provider ports. Use it only when an extension is authored with
5
+ Effect. It was the package `extensions-sdk-backend-effect`. Its last version
6
+ is 0.2.0; the release after it removes the package.
7
+
8
+ `ci package build` bundles `/effect` into the release and keeps `.`
9
+ Host-provided. An earlier `ci` CLI keeps `/effect` external, and
10
+ `ci package validate` rejects that release.
11
+
12
+ ## Schemas
13
+
14
+ ```ts
15
+ import {
16
+ effectSchema,
17
+ withWorkflowDefault
18
+ } from "@collective-intelligence/extensions-sdk-backend/effect"
19
+ import * as Schema from "effect/Schema"
20
+
21
+ const Count = effectSchema(Schema.NumberFromString, { codec: true })
22
+ const Config = effectSchema(
23
+ Schema.Struct({
24
+ mode: Schema.Literals(["text", "structured"]).pipe(
25
+ withWorkflowDefault("text")
26
+ )
27
+ })
28
+ )
29
+ ```
30
+
31
+ - `effectSchema(schema)` is decode-only. An output declaration needs
32
+ `{ codec: true }`; decoding and encoding must then need no service.
33
+ - The JSON Schema projection is an interchange artifact; Effect stays the
34
+ runtime authority. Fidelity is `structural` by default. Assert
35
+ `fidelity: "exact"` only when a test proves the wire values match.
36
+ - An interactive form needs a closed object:
37
+ `{ codec: true, fidelity: "exact", onExcessProperty: "error" }`.
38
+ - `withWorkflowDefault(value)` makes a key optional, applies `value` on decode
39
+ and shows it as the projected `default`.
40
+
41
+ ## Dataset Providers
42
+
43
+ At `/effect`, `ManagedDatasetProvider` and `ExternalDatasetProvider` are the
44
+ Effect tags of the provider services; at `.` they are the abstract base
45
+ classes.
46
+
47
+ ```ts
48
+ import {
49
+ ExternalDatasetProvider,
50
+ makeExternalDatasetProviderImplementation
51
+ } from "@collective-intelligence/extensions-sdk-backend/effect"
52
+ import type { PackageRuntimeContext } from "@collective-intelligence/extensions-sdk-backend"
53
+ import * as Context from "effect/Context"
54
+ import * as Effect from "effect/Effect"
55
+ import * as Layer from "effect/Layer"
56
+
57
+ const acquireService = (context: PackageRuntimeContext) =>
58
+ Effect.gen(function* acquireProvider() {
59
+ const config = yield* decodeProviderConfig(context.config)
60
+ const credentials = yield* resolveProviderCredentials(context, config)
61
+ const services = yield* Layer.build(providerLayer({ config, credentials }))
62
+ return Context.get(services, ExternalDatasetProvider)
63
+ })
64
+
65
+ export const ExampleExternalDatasetProvider =
66
+ makeExternalDatasetProviderImplementation(acquireService)
67
+ ```
68
+
69
+ - The acquisition callback decodes the package configuration, resolves the
70
+ host-authorized credentials and builds the provider Layer.
71
+ - The adapter opens and closes one Effect scope per operation, forwards the
72
+ host `AbortSignal`, and keeps `DatasetProviderError` in the portable
73
+ `DatasetProviderResult`. It holds no state between invocations.
74
+ - Bind the result with `declareExternalDatasetProvider` or
75
+ `declareManagedDatasetProvider` of `extensions-sdk`.
package/docs/errors.md ADDED
@@ -0,0 +1,29 @@
1
+ # Errors
2
+
3
+ Each component kind reports a failure that its author can act on with its own
4
+ error class from the root `.`. Its fields are own JSON fields, so a host that
5
+ serializes the rejection still reads them. Keep secrets out of `message`.
6
+
7
+ | Component | Class | Host result |
8
+ | --------------------------- | ------------------------------------------------------------ | --------------------------------------------------------- |
9
+ | Workflow node | `PackageWorkflowNodeError({ code, message })` | The node ends on its `error` port; no retry of that node |
10
+ | Email provider | `PackageEmailSendError({ category, message, outcome, ... })` | `outcome` `rejected` or `unknown`; `retry` sets `retryAt` |
11
+ | Outbound Messaging Provider | `PackageMessageSendError` (`code`, `statusCode`) | A failed send |
12
+ | Inbound Messaging Provider | `PackageWebhookRejectedError` (`reason`) | A rejected webhook request, apart from a crash |
13
+ | Runtime store | `PackageRuntimeStoreConstraintError` | A `put` broke a store limit |
14
+ | Runtime store | `PackageRuntimeStoreMissingError` | The invocation has no runtime store |
15
+ | Schema decode | `BackendPackageSchemaError` (`stage`, `location`, `issues`) | The input or output did not decode |
16
+ | Dataset Provider (Effect) | `DatasetProviderError` of `/effect` | Kept in the portable `DatasetProviderResult` |
17
+
18
+ ## Rules
19
+
20
+ - `code` is a stable lower `snake_case` string.
21
+ - A workflow node throws `PackageWorkflowNodeError`; it does not return
22
+ `outputs.error` itself. Any other rejection shows the author the code
23
+ `attempt_failed` only, and the host can repeat it.
24
+ - An email provider returns retry data in the error; it does not sleep or
25
+ retry inside `send`.
26
+ - A provider failure rejects the invocation; it does not look like a missing
27
+ value.
28
+ - Expected parser errors are plain JSON failure envelopes; an unexpected
29
+ exception stays a rejection.
package/package.json CHANGED
@@ -1,12 +1,15 @@
1
1
  {
2
2
  "name": "@collective-intelligence/extensions-sdk-backend",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
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,
7
7
  "files": [
8
8
  "dist",
9
- "README.md"
9
+ "README.md",
10
+ "AGENTS.md",
11
+ "docs",
12
+ "skills"
10
13
  ],
11
14
  "main": "./dist/index.js",
12
15
  "types": "./dist/index.d.ts",
@@ -41,7 +44,7 @@
41
44
  "access": "public"
42
45
  },
43
46
  "dependencies": {
44
- "@collective-intelligence/extensions-sdk": "0.2.0"
47
+ "@collective-intelligence/extensions-sdk": "0.2.2"
45
48
  },
46
49
  "peerDependencies": {
47
50
  "effect": "^4.1.0"
@@ -60,5 +63,5 @@
60
63
  "typescript": "7.0.2",
61
64
  "ultracite": "7.10.7"
62
65
  },
63
- "gitHead": "399369a97e85b54b43aeac887e7ba9c960cb7505"
66
+ "gitHead": "51fdea833e25fe215b3cf0d70adf1984b8e0f81c"
64
67
  }
@@ -0,0 +1,28 @@
1
+ ---
2
+ name: extensions-sdk-backend-move-to-effect
3
+ description: Move a backend extension that uses Effect to the `/effect` entry of `@collective-intelligence/extensions-sdk-backend`. Use when code imports `@collective-intelligence/extensions-sdk-backend-effect`, a Dataset Provider runs Effect code with its own runtime bridge, or lint reports `ci-solution/effect-subpath`.
4
+ ---
5
+
6
+ # Move a backend extension to `/effect`
7
+
8
+ Reference: [effect.md](../../docs/effect.md), [errors.md](../../docs/errors.md).
9
+
10
+ ## Steps
11
+
12
+ 1. **Find the old imports.** Search for
13
+ `@collective-intelligence/extensions-sdk-backend-effect` in imports and in
14
+ `package.json`. Done when you have each site.
15
+ 2. **Rewrite them** to `@collective-intelligence/extensions-sdk-backend/effect`.
16
+ The names are the same, and the tag keys still match an older copy. Done
17
+ when step 1 finds nothing.
18
+ 3. **Use the provider ports.** For each Dataset Provider that runs Effect with
19
+ its own `Effect.runPromise` bridge, write an acquisition callback and wrap
20
+ it with `makeExternalDatasetProviderImplementation` or
21
+ `makeManagedDatasetProviderImplementation`. Remove the hand-written scope,
22
+ abort and error mapping. Done when no provider calls `Effect.runPromise`
23
+ itself.
24
+ 4. **Fix the dependencies.** Remove `extensions-sdk-backend-effect`; keep one
25
+ `effect` `^4.1.0`. Done when the lockfile holds one `effect` version.
26
+ 5. **Verify.** Run the type-check, the package tests, oxlint with the
27
+ `recommended` config of `@collective-intelligence/lint`, and
28
+ `ci package build` and `ci package validate`. Done when all pass.