@astram/guide 0.2.21 → 0.2.23

package/CAPABILITIES.md

@@ -239,7 +239,9 @@ imports: [
   "wire IdentityFeatureModule in AppModule before running bootstrap:org".
 - **File.** `{ "version": 1, "roots": [{ username, email, homeCompany }], "tenants": [company] }`;
   `company` = `{ name, departments?, branches?, roles?: [{ name, permissions }], users?:
-  [{ username, email, company?, postings?: [{ role, department?, branch? }] }], children? }`.
+  [{ username, email, company?, postings?: [{ role, department?, branch? }] }], agent?: { mode },
+  children? }`. `agent.mode` (`off` | `synthetic`, identity 0.26) sets that company's AI assistant
+  mode (below); no `agent` key leaves it unchanged.
   Unknown fields, unknown permission keys (allowed: catalog keys plus `<feature>:*` and
   `<feature>:<type>:*`), duplicate usernames or emails and references to undeclared roles,
   departments or branches are refused before any write. No password, uuid or secret in the file.
@@ -263,6 +265,9 @@ imports: [
   another company. A posting must use a role declared on its own company (a role declared only on a
   parent is a file error). After renaming a department or branch in the app, rename it in the file
   too, or a re-run creates the old name again.
+- **The one overwrite.** A company's `agent.mode` is planned `create`, `unchanged` or `update` (either
+  direction); `--apply` writes it with an `agent.tenant_mode.set` audit row. It is the only stored
+  value a re-run changes.
 - **What it does NOT do.** No deletes, renames, moves or revokes (differences are reported only);
   it never activates an inactive membership or updates a changed email. No upload from the UI.
   Department and branch admin routes are separate. With `emailSender` configured, `--email-links`
@@ -474,10 +479,25 @@ imports: [
   (`{ announcement, personal, total }`), `POST /account/notifications/:uuid/read` (204),
   `POST /account/notifications/read-all?category=` (`{ updated }`). Another user's or company's
   notice is a 404, like a missing one. Restricted sessions (re-enrolment, mandatory 2FA) get 403.
+- **Notification center (G-035):** the list also takes `kind`, `status=unread|read|archived`
+  (absent ⇒ not archived), `from` / `to` (UTC days `YYYY-MM-DD`, inclusive) and `search` (title or
+  body, case- and accent-insensitive, ≤ 100 characters; blank ⇒ no search); rows carry
+  `kindLabel`, `severity` and `archivedAt`. `GET /account/notifications/kinds` (`{ kinds: [{ kind,
+  label, category }] }`), `POST /account/notifications/:uuid/{unread,archive,unarchive}` (204;
+  archive also marks read, archived notices are never counted as unread) and `POST
+  /account/notifications/bulk` `{ action: read|unread|archive|unarchive, uuids (1–100) }` ⇒
+  `{ updated }` (only the caller's own notices in the active company change). Archive never
+  keeps a notice past retention. The scaffold's dropdowns show unread notices only and link to
+  the `/notifications` page; `server/src/notifications/app-notifications.service.ts` is an example
+  for posting your own.
 - **Register your kinds** once: `ShieldModule.forRoot({ notificationKinds: [{ kind:
-  'naes.import_review', category: 'personal' }] })`. A kind is dotted lower-case
-  (`^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$`, ≤ 64); `shield.` is reserved. A bad or duplicate entry
-  fails boot. `category` is `announcement` (release news, notices to many) or `personal`.
+  'naes.import_review', category: 'personal', label: 'Import review', severity: 'warning' }] })`.
+  A kind is dotted lower-case (`^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$`, ≤ 64); `shield.` is
+  reserved. A bad or duplicate entry fails boot. `category` is `announcement` (release news,
+  notices to many) or `personal`. `label` (optional, 1–40 characters, plain text, shown to every
+  company: no company or person names) is the type users see; unset ⇒ made from the kind's last
+  segment (`Import review`), cut to 40 with "…", and boot logs one warning listing such kinds.
+  `severity` is `info` (default), `success` or `warning`; a bad label or severity fails boot.
 - **Post** with `NotificationService` (inject `SHIELD_NOTIFICATIONS` from `@astram/guard`):
   `post({ tenantId, recipients, kind, title, body?, link?, dedupeKey? }, { query? })` ⇒
   `{ created, skipped }`. `post` trusts its caller: take `tenantId` (and the recipients) from the
@@ -751,6 +771,67 @@ upload(@Req() req: Record<string, unknown>) {
   grace banner, the Security page (policies), and Users-page 2FA status, sign-in name and admin
   actions.
 
+## AI assistant (`@astram/agent`, G-036 M1, ADR-0049; agent 0.1, core 1.15, engine 0.17, guard 0.28, identity 0.26, frontend-core 0.12)
+- **What it is.** A governed agent layer: the model (in a separate agent runtime) proposes, your
+  server executes. The runtime never calls your app; each capability call it asks for runs inside the
+  user's own streaming request, as that user, through the record pipe and `decide()`, recorded in
+  `agent_action` before it runs. M1: **`read` and `compute` capabilities only**; no workers, no
+  writes or proposals (M3), no chat UI in the template, synthetic data only (Rule 8).
+- **Capabilities.** `defineCapability({ id, version, title, description, effect: 'read' |
+  'compute', dataClass: 'internal' | 'confidential' | 'restricted', requires: [keys], input,
+  output, limits?, handler, toEvidence?, partial? })`, or `inject` + `factory` for app services.
+  `requires` are exact registered keys, all required, re-checked by `decide()` on every call.
+  `ctx.records` (`RecordsApi`, engine) is the only data path: writes throw `scope_violation`; a
+  `list`/`aggregate` `limit` above `maxRows` is refused (`invalid_args`), absent ⇒ `maxRows`.
+  `ctx.handle` / `ctx.resolve` turn uuids into task-scoped handles; uuids in output fail the call.
+  `toEvidence` returns `metric` / `table` / `series` evidence for the UI (never sent to the model).
+  Validation runs at every boot, also when disabled.
+- **Wiring.** `AgentModule.forRoot({ capabilities, modelProfiles, defaultModelProfile, limits?,
+  stepLabels?, allowOpaqueProviders? })` beside `ShieldModule.forRoot({ auth: true })`,
+  `IdentityFeatureModule.forRoot` and `EngineModule`. `main.ts`: `NestFactory.create(AppModule,
+  { rawBody: true })` (else every agent POST is `503 agent_unavailable`). Registration of the app
+  types a capability `requires`: `EngineModule.forRoot` (called inside `IdentityFeatureModule.forRoot`)
+  snapshots the `EngineModule.forFeature` registrations at the moment it is called. A `forFeature`
+  inside a feature module file's own `@Module` decorator runs when that file is imported, so it is
+  always included, wherever that module sits in `imports`. Only an inline
+  `EngineModule.forFeature([...])` written in `app.module`'s `imports` array **after**
+  `IdentityFeatureModule.forRoot(...)` is missed; `AgentModule` then fails the boot with
+  `requires_not_registered`, naming the capability and the key. (The type also goes in
+  `extraObjects` so its keys are in the catalog.) An app table
+  compared with framework tables (shares, record rules) needs `COLLATE=utf8mb4_unicode_ci`: MariaDB
+  11.4's default `uca1400` collation breaks the engine's share subquery.
+- **Env.** `AGENT_ENABLED` (`0` default: routes answer `403 agent_disabled`, nothing else read),
+  `AGENT_RUNTIME_URL` (`https:`, or `http:` in development/test or to a loopback host),
+  `AGENT_RUNTIME_KEY_ID`, `AGENT_RUNTIME_KEY` (`secret-ref:` outside development/test).
+- **Who may use it.** Keys `identity:agent:chat` (use it), `identity:agent:restricted_data` (send
+  `restricted` data to an approved provider), `identity:agent:propose` (M3). A tenant also needs
+  mode `synthetic` (org bootstrap `agent: { mode }`); each company is set on its own. `identity:*`
+  holders get all three keys, including `restricted_data` (GAPS #23): grant `identity:agent:chat`
+  explicitly on production roles.
+- **Freshness.** Every call re-checks the session (logout, disable, scope switch, restriction), the
+  tenant mode, the user's roles and permission version, `identity:agent:chat` and the capability's
+  keys. Any grant change in the tenant stops running tasks (`access_revoked`; the user asks again).
+  Access-token expiry does not cut a running stream.
+- **Accepted replay edges (M1).** The task's owner can replay its events (`GET :taskId/events`)
+  for 10 minutes, also after their access was revoked; a reused `callId` within a task returns the
+  earlier recorded result instead of running again (that content already went to the runtime in
+  the same task). Both are bounded to the owner's own task and to synthetic data.
+- **Routes** (`/agent/tasks`, session principals only): `POST` open (SSE), `POST :taskId/continue`,
+  `POST :taskId/cancel`, `GET :taskId`, `GET :taskId/events` (read-only replay). Disconnect cancels
+  the task. Browser client: `createAgentService(http, transport)` in `@astram/frontend-core`;
+  `createRefreshingHttp(...).refreshAfterUnauthorized` shares the token refresh with the stream.
+- **Testing.** `@astram/agent/testing`: `createFakeRuntime`, `runCapabilityCase`, `withTenantMode`
+  (`NODE_ENV=test`), the shipped synthetic scenarios and `demoCapabilities()`.
+- **Lint.** Add by hand (not in the scaffolded template yet): `agentLintConfig()` from
+  `@astram/agent/eslint` (plain flat-config blocks): no model SDK
+  in any server file; no `mariadb`, `ioredis`, framework pool or Redis token, `RECORD_ENGINE`,
+  `RecordsService` or `ModuleRef` in `*.capability.ts`. ESLint replaces (not merges) a rule's
+  options across blocks, so merge `agentRestrictedImports()` into an existing
+  `no-restricted-imports` rule for the same files. Exact lists: the `@astram/agent` README.
+- **Migrations** 111–113 (identity) add `agent_task`, `agent_action`, `agent_tenant_setting` to
+  `<ns>_identity`. Single layout: re-run `db-provision --layout single` after migrating; check with
+  `db-verify-grants` and the app's layout flags.
+
 ## Available, but NOT wired to a data path (do not assume they protect data yet)
 - **Envelope encryption / per-tenant DEKs** (`createEncryptionService`, `LocalKekCrypto`): the
   engine exists, but no record field is encrypted and no production `DekStore` ships. Stored

package/FRAMEWORK_RULES.md

@@ -31,7 +31,7 @@ the current rules, not a stale memory of them. Your project's own rules in
 
 The framework packages (`@astram/core`, `@astram/guard`, `@astram/engine`,
 `@astram/identity`, `@astram/migrate`, `@astram/frontend-core`, `@astram/sdk`,
-`@astram/guide`) live in `node_modules` and are **immutable**. Do not edit them, patch
+`@astram/agent`, `@astram/agent-protocol`, `@astram/guide`) live in `node_modules` and are **immutable**. Do not edit them, patch
 them, monkey-patch them, or reach around their public API. You register your app through
 the ONE seam — `ShieldModule.forRoot(...)`, plus `IdentityFeatureModule.forRoot(...)` for
 the identity surface — and consume the exported building blocks. That is the entire
@@ -155,6 +155,35 @@ or identity surface lacks something you need, that's Rule 4 (flag the gap).
 On any ambiguity or error in a security path — deny. Never "allow on error", never
 default-open, never swallow a security failure into a success.
 
+## 8. AI assistant: capabilities only, through `@astram/agent`
+
+The model proposes; your server authorises and executes. The agent runtime (a separate service)
+makes every model call and never calls your app.
+
+- **No model SDK in app server code.** No `openai`, `@anthropic-ai/*`, `langchain`, `@langchain/*`,
+  `ai`, `@ai-sdk/*`, `@google/genai`, `@google/generative-ai`, `cohere-ai`, `@mistralai/*`,
+  `ollama`, `groq-sdk` or `together-ai` import, and no direct LLM HTTP call. Talk to the runtime only
+  through `AgentModule.forRoot(...)`; never call the runtime yourself.
+- **Capabilities only via `defineCapability`** (`@astram/agent`), registered in
+  `AgentModule.forRoot({ capabilities })`. Never write your own tool route, tool loop or tool
+  dispatcher.
+- **A capability reads data only through `ctx.records`**: the request's own records API, so every
+  read is the live user's `decide()` and list scope. The `read`/`compute` effect is enforced only
+  there; data reached any other way is outside it. In a `*.capability.ts` file never import
+  `mariadb`, `ioredis`, a framework pool or Redis token, `RECORD_ENGINE`, `RecordsService` or
+  `ModuleRef`. An app that mounts `AgentModule` adds the `agentLintConfig()` rules from
+  `@astram/agent/eslint` to `server/eslint.config.mjs`, so lint fails on these imports.
+- **Inject only your own app services** (`inject` + `factory`), typed against `RecordsApi` and
+  given `ctx.records` per call. A service that reaches a framework, Nest-internal, request-scoped or
+  opaque provider fails the boot; do not work around that check (Rule 4).
+- **Put `total` in a list output.** The model sees only the returned content, so a capability that
+  lists rows returns how many exist, not only the page.
+- **No uuids to the model.** Return handles (`ctx.handle(uuid, typeKey)`) and declare handle inputs
+  with `"x-astram-handle"`; never put a uuid, id or hex digest in a capability's output.
+- **Synthetic data only.** Enable a tenant (`agent: { mode: "synthetic" }` in the org bootstrap
+  file) only when it holds synthetic data. Never set a model profile's `providerApproval.scope` to
+  `client_data`; the framework refuses it until real data is approved.
+
 ---
 
 *These rules are the framework floor. Your project's rules (in `.astram/guide/`) add to

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guide",
-  "version": "0.2.21",
+  "version": "0.2.23",
   "license": "MIT",
   "description": "Astram framework — the AI/dev GUIDE layer (ADR-0025). Ships the framework's hard rules + capabilities manifest as installed, upgrade-refreshed docs. A consumer app's CLAUDE.md references FRAMEWORK_RULES.md from this package; `npm update` replaces it wholesale so new rules arrive cleanly, while the app's own .astram/guide/ layer is never touched. This is the framework-owned FLOOR: an app rule may tighten it, never weaken it.",
   "type": "commonjs",