@collective-intelligence/extensions-sdk-backend 0.3.3 → 0.3.4
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.
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Extensions
|
|
2
2
|
|
|
3
|
-
What a package declares, how the template wires it, how to deploy it with ci deploy, and the rules its code runs under.
|
|
3
|
+
What a package declares, how the template wires it, how to deploy it with ci deploy, how to read a failed deploy, and the rules its code runs under.
|
|
4
4
|
|
|
5
5
|
A package is a TypeScript module whose default export is `declarePackage({ manifest, components, hostedContributions })`. The `ci` CLI builds that module into a release, which is one immutable published version of the package. An Organization admin then installs the release into one Organization, and the installation records which release that Organization runs.
|
|
6
6
|
|
|
@@ -177,6 +177,56 @@ Install records a Desired Release. CI makes it the Serving Release only after ev
|
|
|
177
177
|
|
|
178
178
|
For a fast loop without releases, `ci package dev --backend-url <url> --declaration ./src/package.ts --host-origin <studio-or-dashboard-origin>` starts a Development Session. It serves modules with Vite and rebuilds on save until the command stops. It needs a `CI_MANAGEMENT_TOKEN` with `ai:manage`, and only one live command can own a package at a time.
|
|
179
179
|
|
|
180
|
+
## When a deploy fails
|
|
181
|
+
|
|
182
|
+
Every `ci` command shows a failure as one block on standard error. A deploy that a hand-made Skill blocks looks like this:
|
|
183
|
+
|
|
184
|
+
```text
|
|
185
|
+
Error: Skills still use the tool that this change removes.
|
|
186
|
+
Cause: AiToolInstanceRepositoryError (referenced_by_skills); skillIds: <skill-id>; toolFqn: acme.app.tools.lead-score; toolInstanceId: <tool-id>
|
|
187
|
+
Fix: 1. Remove the tool from these skills, or keep it declared in the package.
|
|
188
|
+
2. Start a new operation after the fix.
|
|
189
|
+
ci deploy --organization <organization-id> --declaration ./src/package.ts
|
|
190
|
+
Retry: terminal (the same command fails again until the Cause is fixed)
|
|
191
|
+
Reference: Operation ID <operation-id>; Diagnostic ID <diagnostic-id>
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
| Line | What it tells you |
|
|
195
|
+
| ----------- | ------------------------------------------------------------------------------------------------------------ |
|
|
196
|
+
| `Error` | What failed, in one sentence |
|
|
197
|
+
| `Cause` | The error name, its reason code in parentheses, and the IDs, FQNs and names that the error marks |
|
|
198
|
+
| `Fix` | The steps that remove the Cause, in order, with the exact command line under each step that needs one |
|
|
199
|
+
| `Retry` | `retryable` when a later attempt can succeed, `terminal` when the same command fails until you fix the Cause |
|
|
200
|
+
| `Reference` | The Operation ID and the Diagnostic ID of the failure |
|
|
201
|
+
|
|
202
|
+
A terminal failure never tells you to retry, so do the `Fix` steps instead. A step that starts a new operation prints your own command again, with `--idempotency-key <new-key>` in place of the old key and `--declaration <module>` in place of `--resume`. A step that continues the operation prints `ci package operation continue`, and a sign-in failure (HTTP 401) adds a `ci login` step. A block leaves out the `Fix` or `Reference` line when the failure has none.
|
|
203
|
+
|
|
204
|
+
With `--json`, the failure is one record on standard output with `kind: "error"`, `summary`, `cause`, `remedy` (each step with its `command`), `retryClass`, `reference`, `nextAction` and `diagnosticDetail`. `nextAction` is the command of the last fix step that has one. A failed command exits `1` and an interrupted command exits `130` for retryable and terminal failures alike, so a pipeline reads `retryClass` to decide whether a retry can help.
|
|
205
|
+
|
|
206
|
+
`--organization`, `--operation` and `--diagnostic` take UUIDs. The CLI refuses another value before it sends a request, and the error names the option, the value and where to find the right ID.
|
|
207
|
+
|
|
208
|
+
### Read the Diagnostic Detail
|
|
209
|
+
|
|
210
|
+
The block holds only text that the platform wrote and the identifiers that the error marks. The full failure behind a Diagnostic ID is its Diagnostic Detail: every wrapped error with its fields and message, the stack, and the log annotations. The backend keeps it for 30 days by default and stores at most 64 KiB for each failure.
|
|
211
|
+
|
|
212
|
+
After a failure with a Diagnostic ID, the CLI reads the Diagnostic Detail with your own credential. It prints the detail under the block, or puts it in `diagnosticDetail` with `--json`. When you may not read it, the CLI names who can and prints the command to read it later:
|
|
213
|
+
|
|
214
|
+
```bash
|
|
215
|
+
ci diagnostics show <diagnostic-id> --organization <organization-id>
|
|
216
|
+
```
|
|
217
|
+
|
|
218
|
+
Without `--organization`, the command uses the Current Organization of your CLI profile, and an Organization API key reads in its own Organization. `--json` prints the record. A missing or expired record fails as terminal.
|
|
219
|
+
|
|
220
|
+
The origin of the failure decides who can read its Diagnostic Detail. The person whose request failed gets no extra access:
|
|
221
|
+
|
|
222
|
+
| Failure origin | Who can read the Diagnostic Detail |
|
|
223
|
+
| --------------------------------------------------- | ------------------------------------------------------------------ |
|
|
224
|
+
| A package operation, such as a deploy or update | `extensions:manage` in the Organization, or `tenant:manage` |
|
|
225
|
+
| Another request in an Organization | `organization:self_manage` in the Organization, or `tenant:manage` |
|
|
226
|
+
| A tenant route, or a request with no signed-in user | `tenant:manage` |
|
|
227
|
+
|
|
228
|
+
A Host failure keeps its own Diagnostic ID, and `ci package diagnostics trace --organization <organization-id> --diagnostic <diagnostic-id>` reads its trace.
|
|
229
|
+
|
|
180
230
|
## Runtime rules for backend code
|
|
181
231
|
|
|
182
232
|
Built-in packages ship with each CI version, use FQNs under `builtin.`, and run their backend code inside the CI backend process. Third-party backend code runs in Bun Workers. Each backend process keeps one Worker Pool per package release, and every Organization that uses that release shares it. Workers start on demand and stop after an idle period. Built-in and third-party packages use the same public SDK contracts.
|
|
@@ -199,6 +249,8 @@ Some parts of a package need a person after the first deploy:
|
|
|
199
249
|
|
|
200
250
|
The Dashboard Extensions page lists packages on Installed and Available tabs. Install and uninstall show a spinner until the real outcome, and leaving the page does not cancel the operation. A configured Knowledge connector instance, even a disabled one, or a saved connection blocks uninstall, and the Dashboard shows the error next to the package.
|
|
201
251
|
|
|
252
|
+
When a package operation fails, the package card shows the same failure as the CLI: the summary, the Cause, the fix steps and the reference, without the CLI command lines. Show diagnostic reads the Diagnostic Detail as the signed-in person, or names who can read it. The card offers Retry only when a retry can help. After a terminal failure it offers Continue only when a fix step continues the operation, and otherwise only Dismiss.
|
|
253
|
+
|
|
202
254
|
## Related pages
|
|
203
255
|
|
|
204
256
|
- [SDKs](sdks.md)
|
package/docs/guide/index.md
CHANGED
|
@@ -72,7 +72,7 @@ GITHUB_TOKEN=$(gh auth token) opensrc path collective-intelligence-solutions/sdk
|
|
|
72
72
|
- [Studio](ai/studio.md): How Organization members work in the Studio desktop app, how a package ships Studio apps, forms and widgets, and how Studio shares one solution with your external application.
|
|
73
73
|
- Build
|
|
74
74
|
- [SDKs](develop/sdks.md): Which @collective-intelligence package to import, from which subpath, with which Effect setup and which versions.
|
|
75
|
-
- [Extensions](develop/extensions.md): What a package declares, how the template wires it, how to deploy it with ci deploy, and the rules its code runs under.
|
|
75
|
+
- [Extensions](develop/extensions.md): What a package declares, how the template wires it, how to deploy it with ci deploy, how to read a failed deploy, and the rules its code runs under.
|
|
76
76
|
- [External apps](develop/external-apps.md): Sign users in with CI, read and write their data through a BFF, cache shared reads and stay live with Realtime.
|
|
77
77
|
- [Infrastructure](develop/infrastructure.md): The resources that a CI deployment runs, what each one is for, and how the Amazon EKS blueprint maps them to AWS services.
|
|
78
78
|
- Template
|
|
@@ -87,6 +87,8 @@ The CLI takes credentials from a flag first, then from the environment (`CI_BACK
|
|
|
87
87
|
|
|
88
88
|
For a package, you use `ci package build`, `validate`, `publish`, `promote` and `install`, or the single `ci deploy` command, which publishes only when the release is absent, promotes only when needed, and then installs or updates. `ci package dev` runs a development session that serves your package modules from your machine to real Dashboard and Studio hosts. `ci package codegen` generates TypeScript types from the package schemas, and `ci doctor` checks discovery, signing keys, Organization access and redirect URIs.
|
|
89
89
|
|
|
90
|
+
When a command fails, the CLI prints one block: what failed, the Cause, the fix steps with the exact commands to run, whether a retry can help, and a reference with the Operation ID and Diagnostic ID. `ci diagnostics show <diagnostic-id>` reads the full failure when you may read it. [Extensions](../develop/extensions.md#when-a-deploy-fails) explains each line and who can read the full failure.
|
|
91
|
+
|
|
90
92
|
### HTTP API and API keys
|
|
91
93
|
|
|
92
94
|
The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas are the authority, and the SDKs and the CLI are generated from them. An external app meets these public route families:
|
|
@@ -99,6 +101,8 @@ The backend publishes its OpenAPI document at `/openapi.json`. Its wire schemas
|
|
|
99
101
|
|
|
100
102
|
Other route families serve the Dashboard and Studio. A generated operation is not safe for a client just because it exists in the OpenAPI document.
|
|
101
103
|
|
|
104
|
+
An unexpected server error answers HTTP 500 with the body `{"_tag":"InternalServerError"}` and the Diagnostic ID in the `x-diagnostic-id` header, which browsers can read. Log that ID in your app. `ci diagnostics show <diagnostic-id>` reads the full failure. For a request in an Organization, a reader needs `organization:self_manage` in that Organization or `tenant:manage`; for any other request, only `tenant:manage`.
|
|
105
|
+
|
|
102
106
|
An API key belongs to a service principal and acts with that principal's grants. API keys have no scopes. A key never acts beyond its Max Privileges template, and creating, rotating or revoking a key needs a person's session with manage access to API keys, which no API key has. You manage keys in the Dashboard under Developers > Service principals, or with the CLI:
|
|
103
107
|
|
|
104
108
|
```bash
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@collective-intelligence/extensions-sdk-backend",
|
|
3
|
-
"version": "0.3.
|
|
3
|
+
"version": "0.3.4",
|
|
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.3.
|
|
47
|
+
"@collective-intelligence/extensions-sdk": "0.3.4"
|
|
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": "
|
|
67
|
+
"gitHead": "dc0b867b4eb6fef705bc55ed670db4ac7deeaf4a"
|
|
68
68
|
}
|