@aglyn/plugins-ai 1.0.0-beta.143 → 1.0.0-beta.144

package/README.md

@@ -1,25 +1,78 @@
 # @aglyn/plugins-ai
 
-The Aglyn AI plugin (AGL-2939): the in-console assistant, the besigner copy
-assistant, generative building and automation jobs, and the AI add-on's
-billing and access keys — one first-party plugin, provider-generic.
-
-- `providers/` — the provider contract, the registry (a marketplace plugin
-  registers a provider against `AI_PROVIDER_CONTRACT`), the model catalog
-  with rates and capabilities, the routing table, and two adapters:
-  `anthropic.ts` and `openai-compatible.ts`.
-- `runtime/` — the one runtime every door calls, the gate ladder, the answer
-  cache, the palette and the node-tree validator.
-- `jobs/` — the generation job machine, its steps and the beat.
-- `activity/` — the activity codes the feed and the staff facet read.
-- `usage/` — the meter every door reserves and records through: the org
-  and per-user monthly rollups, the refusal counters, the Free taste's
-  account and platform halves, the account-erasure sweep, and the staff
-  readouts' arithmetic.
-- `model/` — the generation job model and the per-user usage shapes and
-  arithmetic the cards and the doors share, free of any server dependency.
-- `server/` — the API handlers, registered under the `ai` and `assist`
-  prefixes with `registerPluginApiRoute`.
-- `components/` — the assistant dock, the billing, member and staff cards
-  mounted through the console's widget zones, and the Assist signal staff
-  page.
+The AI plugin for Aglyn: the in-console assistant, the Besigner copy assistant, generative building and automation jobs, and the usage metering and access controls around them. It is provider-generic: every feature talks to a provider contract, and vendor specifics live only under `src/lib/providers`. Install it if you run the Aglyn console and want AI features in it; it is a first-party plugin, not a standalone library.
+
+> Beta. Published from the Aglyn monorepo under the `beta` dist-tag; APIs can change between beta releases.
+
+## Install
+
+    npm install @aglyn/plugins-ai@beta
+
+Peer dependencies: `react`, `next`, `@mui/material`, `@mui/x-data-grid`, `firebase`, and `firebase-admin` for the server entries.
+
+## What's in it
+
+**On a published site.** Nothing. The plugin has no site registrar, and the tenant runtime loads no server surface of it, so nothing that serves a published site can reach a provider. What a job builds (a page, a component, a form) is saved as ordinary Aglyn documents.
+
+**Console** (`registerAiConsole`, the `console` and `staff` registrar in `plugins.config.json`). The plugin adds no nav item. Everything is mounted through zones the console shell and other plugins host, so no console page imports it:
+
+- The assistant dock (`assistPanel`) and a provider the shell mounts around every console page for the Besigner copy assistant, with controls in the `besignerToolbar` and `besignerInspector` slots.
+- "Describe it" entry points and cards on the site's screens, components, layouts, templates, forms, theme, SEO and automations pages (`hostScreens`, `hostComponents`, `hostLayouts`, `hostTemplates`, `hostForms`, `hostTheme`, `hostSeo`, `seoFields`, `hostAutomations`, `automationEditor`, `automationRun`, `hostFirstRun`, `orgSites`).
+- Cards in zones other plugins host: product copy, import and the products hub (`productEditor`, `productImport`, `productsHub`), record insights, email drafts and import column matching (`recordInsights`, `recordEmail`, `importMapping`), and A/B test variants and results (`experimentVariants`, `experimentResult`).
+- Usage and access: credit and usage cards on billing (`orgBillingUsage`), per-member cards and columns (`orgMember`, `orgMembersListColumn`, `hostMembers`), and staff cards, columns and one staff page (`staffOrg`, `staffUser`, `staffOrgsListColumn`, `staffOrgUsageColumn`).
+
+**Server** (`registerAiConsoleApi`, the `consoleApi` registrar, exported from `@aglyn/plugins-ai/server`). It registers the first-party providers, every job kind, and the routes under the `ai` and `assist` prefixes with `registerPluginApiRoute`:
+
+- Assistant: `assist/chat`, `assist/feedback`, `assist/edit-applied`, `ai/assist`.
+- Jobs: `ai/jobs`, `ai/jobs/batch`, `ai/jobs/:jobId/cancel`, `ai/jobs/:jobId/resume`, `ai/jobs/:jobId/events`, the scheduled jobs beat, `ai/insights/:jobId`, `ai/crm/:jobId`, `ai/seo/apply`, `ai/generate/component`.
+- Usage and access: `ai/usage`, `ai/allotments`, `ai/models`, `ai/host-permissions`, `ai/billing/credits`, `ai/billing/overage`.
+- Staff: `ai/admin/org`, `ai/admin/orgs-spend`, `ai/admin/user`, `ai/admin/signals`, `ai/admin/overage`.
+
+**Declarations.** Three light entries the core reads before any surface loads:
+
+- `registerAiDeclarations` (`@aglyn/plugins-ai/declarations`, also exported from `.`): the plugin's entitlements, its config schema and its activity codes. Idempotent.
+- `registerAiServerDeclarations` (`@aglyn/plugins-ai/declarations.server`): platform event subscriptions, the account-erasure sweep for a person's AI usage, and the usage alert contributor.
+- `aiSubprocessors` (`@aglyn/plugins-ai/subprocessors`): the third-party hosts the registered providers send data to, for the subprocessor inventory.
+
+**Source layout under `src/lib`**
+
+- `providers/`: the provider contract (`AiProvider`), the registry (`AI_PROVIDER_CONTRACT`, `registerAiProvider`), the model catalog, the routing table, and two adapters, `anthropic.ts` and `openai-compatible.ts`.
+- `runtime/`: the one runtime every route calls (`runAiRequest`), the gate, the answer cache, the palette and the node-tree validator.
+- `jobs/`: the generation job machine, its steps and the beat.
+- `tools/`: the tool definitions the job steps hand a provider.
+- `usage/` and `billing/`: the meter every route reserves and records through, per-member allotments, and overage.
+- `insights/`, `activity/`, `model/`: figure readers and the digest, activity codes, and the job and usage shapes the cards and routes share, free of any server dependency.
+- `components/`: the dock, the cards and the staff page.
+
+## Usage
+
+The plugin is loaded through Aglyn's plugin manager: the console's generated loader manifests import the package and call the registrars named in `plugins.config.json`. An app that wires plugins by hand calls them once at startup:
+
+```ts
+// console, client side
+import { registerAiConsole } from '@aglyn/plugins-ai'
+registerAiConsole()
+
+// console, server side
+import { registerAiConsoleApi } from '@aglyn/plugins-ai/server'
+registerAiConsoleApi()
+```
+
+Adding a provider. Another plugin registers its own adapter against the same contract from its server entry; the first-party adapters register themselves only when no provider is registered yet, so one registered earlier is not displaced:
+
+```ts
+import { registerAiProvider, type AiProvider } from '@aglyn/plugins-ai/server'
+
+declare const myProvider: AiProvider
+registerAiProvider(myProvider, { pluginId: 'my-plugin' })
+```
+
+An `AiProvider` names the environment variable that carries its key (`apiKeyEnv`), reads it itself (`readApiKey`), lists its models, and implements `complete` and `stream`. The platform default provider is the one named by the `AI_PROVIDER` environment variable when it is registered, otherwise the first registered; `AI_DEFAULT_MODEL` overrides the model for every step kind.
+
+## How it fits
+
+A plugin package (`scope:plugin`). It depends on the core (`@aglyn/aglyn`), the tenant packages (`@aglyn/tenant-runtime`, `@aglyn/tenant-data-admin`, `@aglyn/tenant-feature-instance`) and generic `@aglyn/shared-*` packages. It imports no other plugin. Where a job writes another plugin's resource, such as a campaign, an email design or an automation, that plugin registers a draft writer on a core seam and this one calls the seam; where a job reads another plugin's figures or records, that plugin registers a reader. The core never imports this package, and only `src/lib/server.*` is declared as having side effects.
+
+## License
+
+Apache-2.0. Source: https://github.com/aglyn/aglyn/tree/main/libs/plugins/ai

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aglyn/plugins-ai",
-  "version": "1.0.0-beta.143",
+  "version": "1.0.0-beta.144",
   "license": "Apache-2.0",
   "homepage": "https://aglyn.com",
   "repository": {
@@ -25,22 +25,22 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@aglyn/aglyn": "1.0.0-beta.143",
-    "@aglyn/shared-data-enums": "1.0.0-beta.143",
-    "@aglyn/shared-data-mdi": "1.0.0-beta.143",
-    "@aglyn/shared-data-types": "1.0.0-beta.143",
-    "@aglyn/shared-ui-email-campaigns": "1.0.0-beta.143",
-    "@aglyn/shared-ui-jsx": "1.0.0-beta.143",
-    "@aglyn/shared-ui-snackstack": "1.0.0-beta.143",
-    "@aglyn/shared-ui-theme": "1.0.0-beta.143",
-    "@aglyn/shared-util-email": "1.0.0-beta.143",
-    "@aglyn/shared-util-errors": "1.0.0-beta.143",
-    "@aglyn/shared-util-http": "1.0.0-beta.143",
-    "@aglyn/shared-util-timestamp": "1.0.0-beta.143",
-    "@aglyn/shared-util-tools": "1.0.0-beta.143",
-    "@aglyn/tenant-data-admin": "1.0.0-beta.143",
-    "@aglyn/tenant-feature-instance": "1.0.0-beta.143",
-    "@aglyn/tenant-runtime": "1.0.0-beta.143",
+    "@aglyn/aglyn": "1.0.0-beta.144",
+    "@aglyn/shared-data-enums": "1.0.0-beta.144",
+    "@aglyn/shared-data-mdi": "1.0.0-beta.144",
+    "@aglyn/shared-data-types": "1.0.0-beta.144",
+    "@aglyn/shared-ui-email-campaigns": "1.0.0-beta.144",
+    "@aglyn/shared-ui-jsx": "1.0.0-beta.144",
+    "@aglyn/shared-ui-snackstack": "1.0.0-beta.144",
+    "@aglyn/shared-ui-theme": "1.0.0-beta.144",
+    "@aglyn/shared-util-email": "1.0.0-beta.144",
+    "@aglyn/shared-util-errors": "1.0.0-beta.144",
+    "@aglyn/shared-util-http": "1.0.0-beta.144",
+    "@aglyn/shared-util-timestamp": "1.0.0-beta.144",
+    "@aglyn/shared-util-tools": "1.0.0-beta.144",
+    "@aglyn/tenant-data-admin": "1.0.0-beta.144",
+    "@aglyn/tenant-feature-instance": "1.0.0-beta.144",
+    "@aglyn/tenant-runtime": "1.0.0-beta.144",
     "@swc/helpers": "0.5.23"
   },
   "peerDependencies": {