@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 +30 -0
- package/README.md +10 -4
- package/docs/effect.md +75 -0
- package/docs/errors.md +29 -0
- package/package.json +7 -4
- package/skills/extensions-sdk-backend-move-to-effect/SKILL.md +28 -0
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.
|
|
441
|
-
|
|
442
|
-
|
|
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
|
|
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.
|
|
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.
|
|
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": "
|
|
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.
|