esoul-sdk 0.19.1 → 0.21.0

package/CHANGELOG.md

@@ -0,0 +1,72 @@
+# esoul-sdk changelog
+
+Releases before 0.20.0 are recorded in the repository history only.
+
+## 0.21.0
+
+### Added
+
+- **Model calls, billed: `llm` in `plugin.json` and `llm(ctx).generate(req)` in `esoul-sdk/server`.**
+  Declare `"llm": { "why", "dailyBudgetUsd"? (default 5, at most 100), "models"? }` and call
+  `llm(ctx).generate({ purpose, model?, system?, messages, tools?, schema?, maxOutputTokens?, temperature? })`
+  from an op or a route — or `ctx.llm.generate(…)` from a task. The app instance's workspace **owner**
+  pays from their AI credits; every call is recorded with the app, the instance and `purpose`; the
+  app's spend per owner per UTC day is capped by `dailyBudgetUsd`. `model` is a tier (`fast`,
+  `balanced`, `best`) or a gateway id on the platform's allowlist (DeepSeek, Claude, GPT mini/nano,
+  Gemini Flash) or in `llm.models`. `tools` are definitions: the model's calls come back in
+  `toolCalls`, never executed by the platform. `schema` (JSON Schema) returns the answer parsed in
+  `object`. A refusal throws `LlmUnavailable` (`isLlmUnavailable`) with `code` `not_declared` |
+  `not_allowed` | `no_credits` | `budget_exceeded` | `model_not_allowed` | `provider_unavailable`.
+  Schema: `PluginLlmSchema`. See `docs/19-model-calls.md`.
+- **`scriptedModel(policy?)` in `esoul-sdk/testing`.** A deterministic stand-in for `llm(ctx)`: scripted
+  texts, objects and tool calls by matching the last user message (or a function), a short echo by
+  default, zero cost, every request in `.calls`. The Forge box answers every model call with one.
+
+### Changed
+
+- **App files may not import a model SDK** (`ai`, `@ai-sdk/*`, `openai`, `@anthropic-ai/*`,
+  `@google/genai`, `@inngest/ai`) — the box check and the install inspection refuse it, tests
+  included. Apps call models through `llm(ctx)`.
+
+## 0.20.0
+
+### Added
+
+- **Platform accounts (Google): `credentials` in `plugin.json`.** An app declares one slot,
+  `credentials: { <slot>: { family: "google", scopes, why, label?, background? } }`, with scopes
+  from `gmail.readonly`, `gmail.modify`, `gmail.send`, `gmail.compose`, `gmail.labels`,
+  `calendar.events`, `calendar.readonly`, `contacts`, `contacts.readonly`, `drive.readonly`,
+  `drive.file` (short or full URL). The person assigns a Google account to the app in Account
+  settings → Google. Schema: `PluginCredentialsSchema`, `GOOGLE_CREDENTIAL_SCOPES`,
+  `normaliseCredentialScopes`. See `docs/08-connections.md` → "Platform accounts (Google)".
+- **`credentials(ctx).slot(name)` in `esoul-sdk/server`: a proxy, never a token.** `.fetch(url, init)`
+  is the standard `fetch` with the account's access added by the platform, sent only when the URL
+  is a clean `https://` Google API URL that one of the slot's scopes reaches for that method, and
+  the caller is the account's owner (or the app's own background work when the slot declares
+  `background: true`). `.status()` answers `{ state: "ready" | "not_bound" | "needs_consent" |
+  "reconnect" | "not_allowed", account?, missingScopes?, connectUrl?, reason? }`. A refusal throws
+  `CredentialUnavailable` (`isCredentialUnavailable`) with a `code` a tool can relay.
+- **`useCredential(slot, { nodeId })` and `<ConnectAccount/>` in `esoul-sdk/react`.** The screen
+  asks the same question `status()` answers, for the person looking at it; `connect()` sends the
+  owner to consent, a reconnect, or Account settings → Google.
+- **`simGmail()` in `esoul-sdk/testing`: a fake Gmail at the HTTP level.** The endpoints the
+  platform's mail code calls, with Gmail's wire shapes and error envelopes; mailboxes that deliver
+  to each other and thread like Gmail; history and push; scripted counterparties (`addPersona`,
+  `crowd`) on a virtual clock (`advance`); deterministic faults; a seeded, production-shaped
+  synthetic corpus (300 messages by default); `snapshot()` / `simGmail({ restore })`.
+  Also `DEFAULT_SIM_ACCOUNT`, `DEFAULT_CROWD_MIX`. See `src/testing/sim-gmail/README.md` in the
+  repository. No Node built-ins: it runs in jest, Node, Next.js and the browser.
+- In a Forge box (esoul-app-host 0.3.0), the Google slot is bound to one simulated account and
+  answered by `simGmail`; the installed app uses the person's real account.
+
+### Changed
+
+- **The env-name rule (W-060).** A `connections` entry's `clientIdEnv` / `clientSecretEnv` must
+  name the app's OWN env vars: `PLUGIN_<APP ID upper-cased, - as _>__<NAME>`, e.g.
+  `PLUGIN_MY_APP__CLIENT_ID`. Any other name is refused by the manifest schema; a name ending in
+  `_WEBHOOK_TOKEN` is the platform's and is refused too (`pluginEnvPrefix`,
+  `pluginEnvNameProblem`). An app that named `GOOGLE_CLIENT_ID` or any other platform variable
+  must rename it and have the owner set the new name.
+- `authorizeUrl` / `tokenUrl` must be `https://` (plain `http://` only to the loopback, for a mock
+  provider such as `startMockOAuth`) — `pluginEndpointProblem`.
+- The package no longer ships compiled test files (`src/**/*.test.ts` are excluded from `dist/`).

package/README.md

@@ -573,6 +573,7 @@ Exits 0 when the folder is a well-formed application package; otherwise prints e
 | [14. Your own tables](docs/14-database.md) | `db`, rules, scopes, sealed fields, indexes, migrations |
 | [15. Realtime](docs/15-realtime.md) | Topics, audiences, addressing |
 | [16. Bindings](docs/16-bindings.md) | Slots, contracts, reaching another application |
+| [19. Model calls](docs/19-model-calls.md) | `llm(ctx)`: billed model calls, budgets, `scriptedModel()` for tests |
 
 ## Versions