@collective-intelligence/extensions-sdk-backend 0.3.2 → 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.
- package/docs/guide/ai/index.md +36 -17
- package/docs/guide/ai/studio.md +245 -0
- package/docs/guide/data/connectors.md +81 -18
- package/docs/guide/data/datasets.md +6 -17
- package/docs/guide/data/documents.md +235 -0
- package/docs/guide/data/index.md +62 -0
- package/docs/guide/data/knowledge.md +21 -18
- package/docs/guide/develop/extensions.md +68 -15
- package/docs/guide/develop/external-apps.md +48 -14
- package/docs/guide/develop/infrastructure.md +135 -0
- package/docs/guide/develop/sdks.md +2 -2
- package/docs/guide/index.md +12 -8
- package/docs/guide/platform/access.md +82 -17
- package/docs/guide/platform/architecture.md +27 -18
- package/docs/guide/platform/entrypoints.md +128 -47
- package/docs/guide/scenarios/index.md +69 -46
- package/docs/guide/template/index.md +22 -9
- package/docs/guide/template/state-machines.md +1 -1
- package/package.json +3 -3
|
@@ -1,8 +1,8 @@
|
|
|
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
|
-
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
|
|
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
|
|
|
7
7
|
The template's package declares the Lead and Opportunity schemas, the Sales group tree, the external application of the web app, Sales Access Profiles and grants, the Max Privileges of the application's tokens, the convert-lead workflow, the lead qualifier Agent with its Skill and tool, and the Sales desk Studio app. [SDKs](sdks.md) explains which `@collective-intelligence/*` package each part imports.
|
|
8
8
|
|
|
@@ -41,7 +41,7 @@ Executable kinds also take an `implementation` class from `@collective-intellige
|
|
|
41
41
|
|
|
42
42
|
A component refers to another component of the same package through the handle that its `declare*` call returned. For a built-in component or one from another package, pass the FQN string instead, for example `"builtin.core.knowledge.tools.query"`. TypeScript does not check these strings. Install resolves them and rolls the package back when one does not exist, and the SDK publishes no list of built-in FQNs, so the template pins its FQNs in a `bun test` that catches a typo before deploy.
|
|
43
43
|
|
|
44
|
-
A package that declares Agents or Skills needs
|
|
44
|
+
A package that declares Agents or Skills needs a person to install it; an install with no signed-in user fails. A package can depend on another package by FQN only, for example `dependencies: [{ fqn: "com.acme.base" }]`, and each install picks the latest eligible release of the dependency by promotion order.
|
|
45
45
|
|
|
46
46
|
## How the template wires the package
|
|
47
47
|
|
|
@@ -102,13 +102,13 @@ To add a component to the template:
|
|
|
102
102
|
|
|
103
103
|
Every content component sets `lifecycle: { deployMode, readonly }`.
|
|
104
104
|
|
|
105
|
-
| Option | Effect
|
|
106
|
-
| ------------------------- |
|
|
107
|
-
| `deployMode: "upsert"` | Each deploy brings the definition back in line with the package.
|
|
108
|
-
| `deployMode: "init_only"` | The first deploy creates the definition. Later deploys leave an
|
|
109
|
-
| `readonly: true` | Nobody can edit the definition by hand. Records of a schema stay editable.
|
|
105
|
+
| Option | Effect |
|
|
106
|
+
| ------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
107
|
+
| `deployMode: "upsert"` | Each deploy brings the definition back in line with the package. |
|
|
108
|
+
| `deployMode: "init_only"` | The first deploy creates the definition. Later deploys leave an Organization admin's edits alone. |
|
|
109
|
+
| `readonly: true` | Nobody can edit the definition by hand. Records of a schema stay editable. |
|
|
110
110
|
|
|
111
|
-
The template uses `upsert` with `readonly: true` for almost everything. The convert-lead workflow and the Sales reps grant use `init_only` with `readonly: false`, so an
|
|
111
|
+
The template uses `upsert` with `readonly: true` for almost everything. The convert-lead workflow and the Sales reps grant use `init_only` with `readonly: false`, so an Organization admin can change them after install and an update keeps that change.
|
|
112
112
|
|
|
113
113
|
## Package variables
|
|
114
114
|
|
|
@@ -131,7 +131,7 @@ const vars = packageVariables(variables)
|
|
|
131
131
|
export default declarePackage({ components, manifest, variables })
|
|
132
132
|
```
|
|
133
133
|
|
|
134
|
-
A variable has a type of `string`, `number`, `boolean`, `string[]`, `json` or `secret`. A variable without a default is required at deploy, and a `secret` cannot have a default. When a deploy provisions a secret without a value, the install still succeeds, but runtime use fails until
|
|
134
|
+
A variable has a type of `string`, `number`, `boolean`, `string[]`, `json` or `secret`. A variable without a default is required at deploy, and a `secret` cannot have a default. When a deploy provisions a secret without a value, the install still succeeds, but runtime use fails until a Tenant admin sets its value in the Organization variables. An Organization admin can read the variables but cannot change them.
|
|
135
135
|
|
|
136
136
|
A handle cannot go in `fqn`, `version`, `kind`, `lifecycle`, a schema projection, or a reference to another component by FQN such as `schemaFqn` or `templateFqn`. The package FQN cannot be a variable either.
|
|
137
137
|
|
|
@@ -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.
|
|
@@ -189,15 +239,18 @@ Every call gets an `AbortSignal` in `context.signal` and can have a deadline in
|
|
|
189
239
|
|
|
190
240
|
## After install
|
|
191
241
|
|
|
192
|
-
Some parts of
|
|
242
|
+
Some parts of a package need a person after the first deploy:
|
|
193
243
|
|
|
194
|
-
1.
|
|
195
|
-
2.
|
|
196
|
-
3.
|
|
197
|
-
4.
|
|
244
|
+
1. Write the app's sign-in values. A package-declared application refuses `ci apps enroll`, so run `ci apps env <application-id-or-fqn> --env-file apps/web/.env.local`, which writes the `CI_*` values the server SDK reads.
|
|
245
|
+
2. Rotate the sign-in secret. A confidential application has no secret after install. An Organization admin runs `ci apps rotate-secret <application-id>` or clicks Rotate secret on the Dashboard External Apps page. CI shows the secret once, and the web app stores it as `CI_CLIENT_SECRET`. This secret signs users in only.
|
|
246
|
+
3. Create a Server Credential for the app's own server calls with `ci apps credentials upsert <application-id-or-fqn> --name <name> --env-file <file>`. CI refuses the sign-in secret on server calls. [External apps](external-apps.md) explains both secrets.
|
|
247
|
+
4. Add users to the groups. The package creates groups empty and grants profiles to groups. In the template, an Organization admin adds users to the Sales group or its `managers` subgroup.
|
|
248
|
+
5. Set every secret variable that the deploy left without a value.
|
|
198
249
|
|
|
199
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.
|
|
200
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
|
+
|
|
201
254
|
## Related pages
|
|
202
255
|
|
|
203
256
|
- [SDKs](sdks.md)
|
|
@@ -18,6 +18,26 @@ You need one when the demo has its own UI outside Studio and the Dashboard, or w
|
|
|
18
18
|
| CI reaching your data or actions | A Gateway |
|
|
19
19
|
| Your own logic with your own store | The app API under `/api/app` |
|
|
20
20
|
|
|
21
|
+
## Put it in the app or in CI
|
|
22
|
+
|
|
23
|
+
Before you write a screen, decide where each piece of its data and logic lives. [Platform architecture](../platform/architecture.md) gives the first question: who owns the records. The same question also places rules, access decisions and UI state:
|
|
24
|
+
|
|
25
|
+
| Question | Put it in CI | Keep it in the external app |
|
|
26
|
+
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
|
|
27
|
+
| Do people in Studio, agents or workflows use these records? | A [Knowledge](../data/knowledge.md) schema. The app reads and writes the records through the BFF. | |
|
|
28
|
+
| Does the customer's database stay the source of truth? | Only what CI must read or act on, exposed through a Gateway | The records, in the app's database |
|
|
29
|
+
| Must agents, workflows and the app apply one business rule the same way? | A tool or a workflow in the package. The app starts it and does not write the rule again. | A rule that already runs in the customer's backend, exposed as a Gateway operation |
|
|
30
|
+
| Who may see or change a record? | Capabilities, Knowledge data policies and Access Grants | Only the choice to hide a control |
|
|
31
|
+
| Is it UI state, such as form steps, filters and drafts, or app-only data? | | State machines, query state and the app API store |
|
|
32
|
+
|
|
33
|
+
Records go to Knowledge when more than the app uses them. In the template, the Sales desk Studio app lists Leads and the lead qualifier agent reads them, so Leads live in Knowledge and the web app keeps no Lead table of its own. The template's lead score is a tool that the agent and a Skill call, and the convert-lead workflow is a package declaration that the app only starts through a [Fixed workflow route](external-apps.md#reads-and-writes-through-the-sdk).
|
|
34
|
+
|
|
35
|
+
Access stays in CI even when the app shows the screen. The BFF checks an Access Requirement before it calls CI, and CI then checks each record again. A page can use the same requirement to hide a button, but the server check makes the decision.
|
|
36
|
+
|
|
37
|
+
Data that no CI user, Studio page or agent reads stays in the app. The template's intake form keeps its requests in an in-memory store behind the app API, and you replace that store with a database. When the customer's database must stay the source of truth, the records stay there too. A Gateway then exposes only what CI needs: remote resources that an Organization admin maps onto a Knowledge schema through a [connector](../data/connectors.md), dataset queries, and business operations that agents call as tools. When agents need only a few fields, keep personal data in the app and put only the needed fields into Knowledge.
|
|
38
|
+
|
|
39
|
+
Secrets stay on the app's server. The browser gets no CI token and no client secret, and in the template `NEXT_PUBLIC_APPLICATION_ID` is the only value it sees. The sign-in secret, the session secrets and the Server Credential live in the server's environment. Deploy and management tokens never reach the web app. A secret that code inside CI needs, such as an API key for a third-party service, is a `secret` package variable that a Tenant admin sets in the Organization variables after deploy, as [Extensions](extensions.md) describes. An Organization admin can read the variables but cannot change them.
|
|
40
|
+
|
|
21
41
|
## Declare the app
|
|
22
42
|
|
|
23
43
|
A package declares the app as an OAuth client with `declareExternalApplication`. The template's declaration, with a placeholder origin:
|
|
@@ -40,19 +60,33 @@ export const acmeApplication = declareExternalApplication({
|
|
|
40
60
|
|
|
41
61
|
The declaration has no `scopes` field. What a user may do through the app comes from grants that hold the app gate and from the Max Privileges declared for the app's user tokens, both described on [Grants and permissions](../platform/access.md).
|
|
42
62
|
|
|
43
|
-
|
|
63
|
+
The CLI writes the app's connection values into an env file: `CI_ISSUER`, `CI_AUDIENCE`, `CI_APPLICATION_ID`, `CI_CLIENT_ID`, `CI_ORGANIZATION_ID`, `CI_JWKS_URL` and, when a secret is known, `CI_CLIENT_SECRET`. Server code reads them with `readApplicationEnrollment(process.env)` and never names them one by one. Two commands write these values, and the right one depends on who created the app:
|
|
64
|
+
|
|
65
|
+
| The app was created by | Command | Client secret |
|
|
66
|
+
| -------------------------- | ----------------------------------------------------- | ----------------------------------------------------------------- |
|
|
67
|
+
| A package, as the template | `ci apps env <application> --env-file <path>` | Left out; issue one with `ci apps rotate-secret <application-id>` |
|
|
68
|
+
| The CLI | `ci apps enroll --fqn <fqn> --redirect-uri <url> ...` | Written by the first confidential create or by `--rotate-secret` |
|
|
69
|
+
|
|
70
|
+
`ci apps env` accepts an Application Id or an FQN and changes nothing in CI. `ci apps enroll` creates or replaces an app by FQN, so it refuses an app that a package declared. The Application Id is the registration id (the `app_id` claim), and the Client Id is the OAuth `client_id`. They are different values, and every CLI output names both.
|
|
44
71
|
|
|
45
72
|
Next to the enrollment, the template reads `APP_ORIGIN` (the public HTTPS origin), `CI_TENANT_URL`, `SESSION_SECRETS` (comma-separated, current secret first, so you can rotate) and `NEXT_PUBLIC_APPLICATION_ID`, the only value the browser sees.
|
|
46
73
|
|
|
47
74
|
## After install
|
|
48
75
|
|
|
49
|
-
Installing the package registers the app. Users can sign in and see data only after the first
|
|
76
|
+
Installing the package registers the app as a confidential client with no secret. Users can sign in and see data only after the first five steps below; the sixth gives refused users a readable page. Run the CLI steps as an Organization admin, signed in with `ci login <api-url> --organization <organization-id>`.
|
|
77
|
+
|
|
78
|
+
1. Write the connection values with `ci apps env <application> --env-file apps/web/.env.local`. The command leaves out the client secret and prints the Application Id that the next step needs.
|
|
79
|
+
2. Rotate the sign-in secret with `ci apps rotate-secret <application-id>`, or with "Rotate secret" on the Dashboard External Apps page. CI shows the secret once, so store it as `CI_CLIENT_SECRET` at once. Each rotation ends the previous secret. Run `ci apps env` first: when the env file holds a secret for a different Client Id, `ci apps env` refuses to write the file.
|
|
80
|
+
3. Create a Server Credential for the app's server with `ci apps credentials upsert <application> --name <name> --env-file <server-env-file>`. Use a separate env file, because this file also stores its secret as `CI_CLIENT_SECRET`.
|
|
81
|
+
4. Add users to the Group whose grant holds the app gate. In the template that is Sales or Sales managers. The package declares the Groups and leaves them empty.
|
|
82
|
+
5. Give the app server read access to Leads. The template's Read Port reads with the server's own credential, and the package declares no grant for it.
|
|
83
|
+
6. Set `errorPath` on the federated auth so that a refused sign-in lands on a page instead of a JSON answer. The callback reports `access_denied`, `authorization_failed`, `invalid_state`, `invalid_request`, `invalid_identity` or `user_auth_unavailable`.
|
|
84
|
+
|
|
85
|
+
The app holds two different secrets. The sign-in secret from step 2 belongs to the OAuth client and only signs users in. The Server Credential from step 3, whose secret starts with `dsc_`, authenticates the server's own calls in service mode and acts with the Access Grants given to the app's server. CI refuses the sign-in secret on a server call, so a server that reads without a user needs the Server Credential.
|
|
50
86
|
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
4. Give the app server read access to Leads. The template's Read Port reads with the app's own credential, and the package declares no grant for it.
|
|
55
|
-
5. Set `errorPath` on the federated auth so that a refused sign-in lands on a page instead of a JSON answer. The callback reports `access_denied`, `authorization_failed`, `invalid_state`, `invalid_request`, `invalid_identity` or `user_auth_unavailable`.
|
|
87
|
+
> **Warning:** `ci apps enroll`, `ci apps redirect-uris` and `ci apps origins` refuse an app
|
|
88
|
+
> that a package declared. Change its redirect URIs and origins in
|
|
89
|
+
> `declareExternalApplication` and deploy a new package release.
|
|
56
90
|
|
|
57
91
|
## Sessions
|
|
58
92
|
|
|
@@ -74,7 +108,7 @@ const auth = createFederatedAuth({
|
|
|
74
108
|
})
|
|
75
109
|
```
|
|
76
110
|
|
|
77
|
-
`createFederatedAuth` handles the PKCE login, the callback, session reads and logout under `/api/auth`. Register `<origin>/api/auth/callback` with `ci apps redirect-uris add` and
|
|
111
|
+
`createFederatedAuth` handles the PKCE login, the callback, session reads and logout under `/api/auth`. Register `<origin>/api/auth/callback` as a redirect URI and the origin as an allowed origin. A package-declared app lists both in its declaration; an app created with the CLI adds them with `ci apps redirect-uris add` and `ci apps origins add`. The session cookie is `__Host-ci-federated` with `Secure`, `HttpOnly` and `SameSite=Lax`, which is why `APP_ORIGIN` must use HTTPS. On a laptop without a TLS proxy, `allowLoopbackHttp: true` lets `http://localhost:3000` work with a cookie named `ci-federated` and no `Secure` flag. Keep that option off in production.
|
|
78
112
|
|
|
79
113
|
Access tokens always live 300 seconds. A confidential client that passes its `clientSecret` to `createFederatedAuth` renews them silently: when a token has 30 seconds or less left, the session lookup gets a new one first. The renewed token stays in process memory and the cookie is written once at sign-in, so a server restart only triggers another renewal. The session itself lasts `sessionTtlSeconds`, 86400 by default and at most 604800, and never longer than the user's CI session.
|
|
80
114
|
|
|
@@ -137,7 +171,7 @@ The template mounts three route files:
|
|
|
137
171
|
| `app/api/leads/[id]/convert/route.ts` | Convert a Lead through a Fixed workflow route |
|
|
138
172
|
| `app/api/app/[[...path]]/route.ts` | The app's own Effect `HttpApi`, with OpenAPI at `/api/app/openapi.json` |
|
|
139
173
|
|
|
140
|
-
A server call to CI uses one of three identities. A delegated call, the default, uses the signed-in user's token, and the template's convert route works this way. `runAsApplication` switches one call to the app's confidential credentials and needs an audit subject. A service-mode client (`createServerClient({ authentication: { mode: "service", credentials } })`) always uses the app's
|
|
174
|
+
A server call to CI uses one of three identities. A delegated call, the default, uses the signed-in user's token, and the template's convert route works this way. `runAsApplication` switches one call to the app's confidential credentials and needs an audit subject. A service-mode client (`createServerClient({ authentication: { mode: "service", credentials } })`) always uses the app's Server Credential and gets the same answer for every user, which is what the template's Read Port does.
|
|
141
175
|
|
|
142
176
|
## Reads and writes through the SDK
|
|
143
177
|
|
|
@@ -159,7 +193,7 @@ const handle = createFixedWorkflowRoute<{ leadId: string }, { leadId: string }>(
|
|
|
159
193
|
|
|
160
194
|
The route rejects any `workflowId` or `workflowFqn` in the browser input, checks the Access Requirement, stamps `x-organization-id` from the session and returns `{ runId }`. The template's tests prove each refusal: an injected `workflowId` gets 400, no session gets 401, a missing capability gets 403, and two clicks reuse the idempotency key `convert-lead:<id>`.
|
|
161
195
|
|
|
162
|
-
The workflow must have an External application trigger bound to the app and an audience that includes it (`audience: { applications: [application] }`). A delegated call runs the workflow as the signed-in user. A service
|
|
196
|
+
The workflow must have an External application trigger bound to the app and an audience that includes it (`audience: { applications: [application] }`). A run acts as the identity that started it. A delegated call runs the workflow as the signed-in user. A call in service mode or with `runAsApplication` has no person, so the run uses the workflow's run-as service principal. CI publishes a triggered workflow only when it names one, which is why the template ships `convertLeadRunner`.
|
|
163
197
|
|
|
164
198
|
A run returns its `runId` at once. The template's `convertLeadTask` posts the convert route, follows the run with `runs.follow({ runId })` until it ends (10 minutes by default), and then invalidates the entity reads so every view reloads.
|
|
165
199
|
|
|
@@ -182,7 +216,7 @@ Tags cover all CI reads, a schema, a list, one entity and one Realtime topic. A
|
|
|
182
216
|
```mermaid
|
|
183
217
|
flowchart LR
|
|
184
218
|
W1[Write through the BFF] --> N[nextInvalidate]
|
|
185
|
-
W2[
|
|
219
|
+
W2[Write outside the BFF] --> RT[Realtime change in an open tab] --> RV[Revalidate route]
|
|
186
220
|
W3[Effect server write] --> L[CacheInvalidation.layerNext on the fiber]
|
|
187
221
|
N --> T[Entity, list and topic tags expire]
|
|
188
222
|
RV --> T
|
|
@@ -202,9 +236,9 @@ Realtime keeps open pages current without polling. The browser asks the BFF for
|
|
|
202
236
|
|
|
203
237
|
A topic is one entity schema, optionally filtered by one field: `{ schema, filter?: { field, eq } }`. Events carry ids only, and the page refetches. One connection per tab carries all of its topics. A `reset` event means the client missed too much and must refetch everything; the first open of a connection also resyncs once, so expect one extra refetch per page load. Pass `onReset`, or a change can be lost. `onAccessChanged` fires when the user's access changes.
|
|
204
238
|
|
|
205
|
-
When the BFF has `secrets`, each ticket answer includes a sealed topic grant, valid for 10 minutes and bound to the session. The revalidate route `POST /api/realtime/revalidate` accepts changes only on topics in that grant, which is how a change
|
|
239
|
+
When the BFF has `secrets`, each ticket answer includes a sealed topic grant, valid for 10 minutes and bound to the session. The revalidate route `POST /api/realtime/revalidate` accepts changes only on topics in that grant, which is how a change written outside the BFF expires the server cache. The client renews the ticket after 8 minutes.
|
|
206
240
|
|
|
207
|
-
To show this in a demo, open `/crm` in two windows and edit a Lead as a Sales manager in one of them. The other window updates without a reload
|
|
241
|
+
To show this in a demo, open `/crm` in two windows and edit a Lead as a Sales manager in one of them. The other window updates without a reload.
|
|
208
242
|
|
|
209
243
|
> **Warning:** Do not open the stream with a hand-written `EventSource`. It cannot send the
|
|
210
244
|
> `Authorization` and `X-Organization-Id` headers that CI needs, and the failure
|
|
@@ -234,7 +268,7 @@ const gateway = defineGateway({
|
|
|
234
268
|
})
|
|
235
269
|
```
|
|
236
270
|
|
|
237
|
-
Adapters for Next, Web Fetch, Express and Nest serve the same gateway kernel. A gateway exposes remote resources and never creates CI schemas: an
|
|
271
|
+
Adapters for Next, Web Fetch, Express and Nest serve the same gateway kernel. A gateway exposes remote resources and never creates CI schemas: an Organization admin connects them through a Knowledge connector and maps fields onto an Organization schema. In NestJS, `bindNestOperation` binds an existing service method without decorators, and the CI entry point does not inherit your HTTP guards, pipes or interceptors, so each entry point keeps its own checks. Start Nest with `NestFactory.create(AppModule, { bodyParser: false })` so the SDK parses bounded JSON, and keep a global prefix off the gateway's `/v1/*` routes.
|
|
238
272
|
|
|
239
273
|
## Related pages
|
|
240
274
|
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# Infrastructure
|
|
2
|
+
|
|
3
|
+
The resources that a CI deployment runs, what each one is for, and how the Amazon EKS blueprint maps them to AWS services.
|
|
4
|
+
|
|
5
|
+
The CI deployment that your demo connects to provides every resource on this page. You do not provision or run any of them. This page explains what runs where, so that you know what sits behind the API when your package or your web app calls CI. The [Platform architecture](../platform/architecture.md) page introduces the same parts from the builder's side.
|
|
6
|
+
|
|
7
|
+
## Runtime resources
|
|
8
|
+
|
|
9
|
+
```mermaid
|
|
10
|
+
flowchart LR
|
|
11
|
+
subgraph outside["Outside the CI deployment"]
|
|
12
|
+
browser["Browser"]
|
|
13
|
+
studio["Studio desktop app"]
|
|
14
|
+
webapp["Your web app (BFF)"]
|
|
15
|
+
end
|
|
16
|
+
subgraph deployment["CI deployment"]
|
|
17
|
+
gateway["Gateway"]
|
|
18
|
+
dashboard["Dashboard and Studio install page"]
|
|
19
|
+
api["Backend API"]
|
|
20
|
+
workers["Background and interactive workers"]
|
|
21
|
+
compute["Compute"]
|
|
22
|
+
media["Media"]
|
|
23
|
+
pg[("PostgreSQL with pgvector")]
|
|
24
|
+
broker["Message broker"]
|
|
25
|
+
storage[("Object storage")]
|
|
26
|
+
end
|
|
27
|
+
ai["AI model providers"]
|
|
28
|
+
browser --> gateway
|
|
29
|
+
studio --> gateway
|
|
30
|
+
webapp -->|"Application API"| gateway
|
|
31
|
+
gateway --> dashboard
|
|
32
|
+
gateway --> api
|
|
33
|
+
gateway --> media
|
|
34
|
+
api --> pg
|
|
35
|
+
workers --> pg
|
|
36
|
+
api -->|"wake signals"| broker
|
|
37
|
+
broker --> workers
|
|
38
|
+
broker -->|"Compute jobs"| compute
|
|
39
|
+
compute -->|"results"| api
|
|
40
|
+
compute -->|"presigned URLs"| storage
|
|
41
|
+
browser -->|"signed upload"| storage
|
|
42
|
+
media -->|"signed source links"| storage
|
|
43
|
+
workers --> ai
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
| Resource | What it is for |
|
|
47
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| Gateway | Receives all HTTP traffic and routes it to the Dashboard, the backend API and Media. |
|
|
49
|
+
| Dashboard | A static web app that calls the backend API for all its data. It also serves the public Studio install page of each Organization, where people download Studio and connect it with one button. |
|
|
50
|
+
| Backend API | Serves every HTTP route that the Dashboard, Studio, the CLI and your app call. It stores long work and returns at once; workers run that work. |
|
|
51
|
+
| Workers | Background workers run long jobs, and interactive workers run the agent and tool work that users wait for. |
|
|
52
|
+
| Compute | Runs transcription, transcoding and conversion from a queue. Each capability has its own slots, so a long transcode does not block transcription. |
|
|
53
|
+
| Media | Serves file bytes and image transforms from URLs that the backend signs. No file byte passes through a backend endpoint. |
|
|
54
|
+
| PostgreSQL | Holds the authoritative data in two databases: one for application data, Knowledge and queued work, and one for datasets. The pgvector extension stores embeddings for semantic search. |
|
|
55
|
+
| Message broker | Carries wake signals from the API to the workers, broadcast events between backend processes, and the job queues of Compute. A wake signal is only a hint: workers find their work in PostgreSQL. |
|
|
56
|
+
| Object storage | Holds every file. Studio installers and updates, and archived rows, have their own stores next to the store for application files. |
|
|
57
|
+
| Cache | There is no separate cache service. Each backend process keeps hot reads, such as schemas, policies and settings, in memory, and broadcast events clear stale entries in every process. |
|
|
58
|
+
| Email provider | Sends platform email. Every message goes through a durable queue in PostgreSQL before the provider receives it. |
|
|
59
|
+
| AI model providers | External model services that agents, Skills and embeddings call. A Tenant admin chooses the available models; the blueprints do not provision them. |
|
|
60
|
+
| Logs | Every backend process and Compute write structured logs, and the CI deployment forwards them to a log service. |
|
|
61
|
+
|
|
62
|
+
## What this means for your code
|
|
63
|
+
|
|
64
|
+
File uploads go straight from the browser to object storage. Your BFF asks CI for an upload slot, and the browser sends the bytes with one signed PUT. A Knowledge file field accepts a file up to its `maxBytes`, and never above the limit of the CI deployment, which is 1 GiB by default and at most 2 GiB. The browser must send the URL, the method and every header that CI returns. Your BFF never streams file bytes. The [External apps](external-apps.md) page shows the flow in the template.
|
|
65
|
+
|
|
66
|
+
Event streams, such as a chat answer, stay open through a heartbeat. The gateway closes a request that sends no bytes for 120 seconds and caps every response at 10 minutes. The backend sends a comment line on every event stream each 20 seconds, so a slow model does not cut the stream. If your BFF forwards a stream, pass each chunk on as it arrives so the heartbeat reaches the browser.
|
|
67
|
+
|
|
68
|
+
Long work is asynchronous. When your app starts an agent run or a workflow, the API stores the run and returns, and a worker runs it. A slow broker delays work, because workers always read their work from PostgreSQL.
|
|
69
|
+
|
|
70
|
+
Configuration changes reach every backend process. When a schema, a policy or a setting changes, a broadcast event clears the cached copy in each process after the write commits. If that event is lost, the cached copy still expires after a short time limit.
|
|
71
|
+
|
|
72
|
+
## The Amazon EKS blueprint
|
|
73
|
+
|
|
74
|
+
A blueprint is the infrastructure code and the deployment configuration that turn the resources above into cloud services. Running CI deployments use the Amazon Elastic Kubernetes Service (EKS) blueprint. Blueprints also exist for Azure Kubernetes Service (AKS) and Azure Container Apps (ACA).
|
|
75
|
+
|
|
76
|
+
The EKS blueprint has three layers. Infrastructure as code creates the AWS foundation: the network, the cluster, the image registry, DNS, and the managed databases and buckets of each CI deployment. Helm charts describe the workloads, and Argo CD keeps the cluster in line with them. Release pins name the exact image of each service, so a new CI release is a change of pins that Argo CD rolls out.
|
|
77
|
+
|
|
78
|
+
```mermaid
|
|
79
|
+
flowchart LR
|
|
80
|
+
users["Browser, Studio and your web app"]
|
|
81
|
+
cdn["Amazon CloudFront"]
|
|
82
|
+
nlb["Network Load Balancer"]
|
|
83
|
+
subgraph eks["Amazon EKS cluster"]
|
|
84
|
+
gateway["Envoy Gateway"]
|
|
85
|
+
dashboard["Dashboard"]
|
|
86
|
+
api["Backend API"]
|
|
87
|
+
workers["Workers"]
|
|
88
|
+
compute["Compute"]
|
|
89
|
+
media["Media"]
|
|
90
|
+
rabbit["RabbitMQ"]
|
|
91
|
+
end
|
|
92
|
+
rds[("Amazon RDS for PostgreSQL or CloudNativePG")]
|
|
93
|
+
s3[("Amazon S3")]
|
|
94
|
+
ses["Amazon SES"]
|
|
95
|
+
secrets["AWS Secrets Manager"]
|
|
96
|
+
ecr["Amazon ECR"]
|
|
97
|
+
users --> nlb
|
|
98
|
+
users -->|"media URLs"| cdn
|
|
99
|
+
cdn --> nlb
|
|
100
|
+
nlb --> gateway
|
|
101
|
+
gateway --> dashboard
|
|
102
|
+
gateway --> api
|
|
103
|
+
gateway --> media
|
|
104
|
+
api --> rds
|
|
105
|
+
workers --> rds
|
|
106
|
+
api --> rabbit
|
|
107
|
+
rabbit --> workers
|
|
108
|
+
rabbit --> compute
|
|
109
|
+
compute --> s3
|
|
110
|
+
media --> s3
|
|
111
|
+
eks -->|"email"| ses
|
|
112
|
+
secrets -.->|"credentials"| eks
|
|
113
|
+
ecr -.->|"images"| eks
|
|
114
|
+
```
|
|
115
|
+
|
|
116
|
+
| Resource | AWS service |
|
|
117
|
+
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
118
|
+
| Containers | Amazon EKS with a managed node group. Images come from Amazon Elastic Container Registry (ECR). |
|
|
119
|
+
| Gateway | Envoy Gateway behind a Network Load Balancer. Amazon Route 53 holds the DNS records, and cert-manager issues the certificates. |
|
|
120
|
+
| PostgreSQL | Amazon Relational Database Service (RDS) for PostgreSQL in private subnets, or CloudNativePG in the cluster on encrypted Amazon Elastic Block Store (EBS) volumes. Each CI deployment chooses one. |
|
|
121
|
+
| Message broker | RabbitMQ in the cluster. |
|
|
122
|
+
| Object storage | Amazon Simple Storage Service (S3) buckets for the files and the archive of each CI deployment, and shared buckets for Studio releases. |
|
|
123
|
+
| Media CDN | Amazon CloudFront in front of Media. |
|
|
124
|
+
| Email | Amazon Simple Email Service (SES). |
|
|
125
|
+
| Secrets | AWS Secrets Manager. External Secrets copies the values into the cluster. |
|
|
126
|
+
| Workload identity | EKS Pod Identity, so pods reach S3 and Secrets Manager without stored keys. |
|
|
127
|
+
| Logs and metrics | Datadog receives the logs. Amazon CloudWatch Container Insights collects the cluster metrics. |
|
|
128
|
+
|
|
129
|
+
One EKS cluster can host several CI deployments. Each CI deployment has its own Kubernetes namespace with its own backend, Compute, database, message broker and storage, and it can hold several Organizations. All CI deployments on the cluster share the gateway and Media.
|
|
130
|
+
|
|
131
|
+
## Next pages
|
|
132
|
+
|
|
133
|
+
- [Platform architecture](../platform/architecture.md): Tenants, Organizations, surfaces and the three integration models.
|
|
134
|
+
- [External apps](external-apps.md): Build the web app that calls CI, including direct uploads.
|
|
135
|
+
- [Knowledge](../data/knowledge.md): Records, schemas and semantic search on PostgreSQL.
|
|
@@ -124,9 +124,9 @@ import { useQuery } from "@tanstack/react-query"
|
|
|
124
124
|
|
|
125
125
|
The template's own pages use the template's shadcn/ui package, `@acme/ui`. `ui-react` appears in the Studio widget and in SDK toasts.
|
|
126
126
|
|
|
127
|
-
### Server SDK subpaths
|
|
127
|
+
### Server SDK subpaths an external app uses
|
|
128
128
|
|
|
129
|
-
`external-apps-server-sdk` runs only on your server, because it holds the application's client secret. Each framework peer loads only from its own subpath: `/next` loads `next`, while `/effect` loads no `next`, `pg` or `drizzle-orm`. Administrative APIs exist only on `/admin` and never reach the browser proxy.
|
|
129
|
+
`external-apps-server-sdk` runs only on your server, because it holds the application's client secret. Each framework peer loads only from its own subpath: `/next` loads `next`, while `/effect` loads no `next`, `pg` or `drizzle-orm`. Administrative APIs exist only on `/admin` and never reach the browser proxy. An external app uses four subpaths:
|
|
130
130
|
|
|
131
131
|
| Subpath | What you get |
|
|
132
132
|
| ----------------- | --------------------------------------------------------------------------------------------------------------------------- |
|
package/docs/guide/index.md
CHANGED
|
@@ -28,14 +28,14 @@ flowchart LR
|
|
|
28
28
|
|
|
29
29
|
1. Generate a new repository from `next-effect-app` and rename the `@acme` packages. [The solution template](template/index.md) explains the layout you get.
|
|
30
30
|
2. Choose the primitives for the scenario. [Choosing primitives](scenarios/index.md) maps common demo scenarios to the parts that fit them.
|
|
31
|
-
3. Declare entities, access and AI parts in the packages' `ci/` folders. The [Data](data/
|
|
31
|
+
3. Declare entities, access and AI parts in the packages' `ci/` folders. The [Data resources](data/index.md), [AI](ai/index.md) and [Grants and permissions](platform/access.md) pages describe each declaration.
|
|
32
32
|
4. Build the screens and server routes of the web app with the [SDKs](develop/sdks.md), following the patterns in [External apps](develop/external-apps.md).
|
|
33
33
|
5. Deploy the package to an Organization with `ci deploy`, as [Extensions](develop/extensions.md) describes, and point the web app at that Organization.
|
|
34
34
|
|
|
35
35
|
## Sections
|
|
36
36
|
|
|
37
37
|
- [Platform](platform/architecture.md): What CI is made of, how people and apps enter it, and how access works.
|
|
38
|
-
- [Data](data/
|
|
38
|
+
- [Data resources](data/index.md): Where data lives: the Data resources Knowledge, Datasets and Documents, and the connectors that fill them.
|
|
39
39
|
- [AI](ai/index.md): Tools, Skills, Agents and workflows, and how they combine.
|
|
40
40
|
- [Build](develop/sdks.md): The SDKs, extension packages and external apps you write.
|
|
41
41
|
- [Template](template/index.md): The layout of `next-effect-app` and its state machine approach.
|
|
@@ -43,7 +43,7 @@ flowchart LR
|
|
|
43
43
|
|
|
44
44
|
## Where to begin
|
|
45
45
|
|
|
46
|
-
If you are starting a new demo, read [Platform architecture](platform/architecture.md) first, then [The solution template](template/index.md), and use [Choosing primitives](scenarios/index.md) to plan the scenario. If you are adding a feature to a demo that already runs, go straight to the page for that part: data questions belong in Data, model and automation questions in AI, and code questions in Build.
|
|
46
|
+
If you are starting a new demo, read [Platform architecture](platform/architecture.md) first, then [The solution template](template/index.md), and use [Choosing primitives](scenarios/index.md) to plan the scenario. If you are adding a feature to a demo that already runs, go straight to the page for that part: data questions belong in Data resources, model and automation questions in AI, and code questions in Build.
|
|
47
47
|
|
|
48
48
|
## For agents
|
|
49
49
|
|
|
@@ -58,19 +58,23 @@ GITHUB_TOKEN=$(gh auth token) opensrc path collective-intelligence-solutions/sdk
|
|
|
58
58
|
## Pages
|
|
59
59
|
|
|
60
60
|
- Platform
|
|
61
|
-
- [Platform architecture](platform/architecture.md): The parts of Collective Intelligence, the three integration models, and how a
|
|
62
|
-
- [Entrypoints](platform/entrypoints.md): The ways people, apps and agents enter CI at runtime, and the package subpaths that
|
|
61
|
+
- [Platform architecture](platform/architecture.md): The parts of Collective Intelligence, the three integration models, and how a package moves from build to install.
|
|
62
|
+
- [Entrypoints](platform/entrypoints.md): The ways people, apps and agents enter CI at runtime, and the package subpaths that your code imports.
|
|
63
63
|
- [Grants and permissions](platform/access.md): How CI decides what a user, a Group, an app or an API key may do, and how to change it in the template.
|
|
64
|
-
- Data
|
|
65
|
-
- [
|
|
64
|
+
- Data resources
|
|
65
|
+
- [Data resources](data/index.md): Choose between Knowledge, Datasets and Documents, and see where each kind keeps its data.
|
|
66
|
+
- [Knowledge](data/knowledge.md): Declare schemas, store typed records, query them, and read and watch them from an external app.
|
|
66
67
|
- [Datasets](data/datasets.md): Query typed tables of measurements, events and warehouse data, and control who can read them.
|
|
68
|
+
- [Documents](data/documents.md): Keep files in Document Collections, sync them from Microsoft 365 or Google Drive, control who reads them, and know when their content becomes searchable.
|
|
67
69
|
- [Connectors](data/connectors.md): Connect outside systems, map their fields to Knowledge schemas, and run and watch imports.
|
|
68
70
|
- AI
|
|
69
71
|
- [AI primitives](ai/index.md): Tools, Skills, Agents, workflows and Studio chat, how they compose, and how audiences, approvals, models, runs and timeouts behave.
|
|
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.
|
|
70
73
|
- Build
|
|
71
74
|
- [SDKs](develop/sdks.md): Which @collective-intelligence package to import, from which subpath, with which Effect setup and which versions.
|
|
72
|
-
- [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.
|
|
73
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
|
+
- [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.
|
|
74
78
|
- Template
|
|
75
79
|
- [The solution template](template/index.md): What you get from next-effect-app, where each piece of code goes, and how to take a new demo from local dev to an installed package.
|
|
76
80
|
- [State machines](template/state-machines.md): How next-effect-app models UI flows as XState machines with Effect actors, keeps server data in the QueryCache, resends uncertain writes safely, and checks hard flows with Models.
|