@collective-intelligence/extensions-sdk-backend 0.1.32 → 0.2.1

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,29 @@
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`. `extensions-sdk-backend-effect` is deprecated.
13
+ - Keep one `effect` (`^4.1.0`) in the extension package. It is a required
14
+ peer.
15
+ - Read tenant data, capabilities and configuration only from the `context` of
16
+ the current call; keep none in module state.
17
+ - Report a failure that the author can act on with the error class of its
18
+ component, for example `PackageWorkflowNodeError({ code, message })`. Keep
19
+ secrets out of `message`.
20
+
21
+ ## Index
22
+
23
+ - [docs/effect.md](docs/effect.md): read when you author an extension with
24
+ Effect: schemas, codecs, Dataset Providers.
25
+ - [docs/errors.md](docs/errors.md): read when a component must report a
26
+ failure, or you map a Dataset Provider error.
27
+ - [skills/extensions-sdk-backend-move-to-effect/SKILL.md](skills/extensions-sdk-backend-move-to-effect/SKILL.md):
28
+ run when code imports `extensions-sdk-backend-effect`, or a Dataset Provider
29
+ runs Effect code without the `/effect` ports.
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`, which now
6
+ re-exports these names and is deprecated.
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.1.32",
3
+ "version": "0.2.1",
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.1.32"
47
+ "@collective-intelligence/extensions-sdk": "0.2.1"
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": "089c82bce0e7fb8319514787d67489aef7a0ee01"
66
+ "gitHead": "7b3d604c39db3969749b14174d660a814a1f3a72"
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.