anbaric-cloud-hosting 1.25.0 → 1.27.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.25.0",
+  "version": "1.27.0",
   "description": "Anbaric Cloud hosting service: Postgres-backed job persistence and queuing exposed over an HTTP API",
   "license": "MIT",
   "author": "chris@anbaric.ai",
@@ -18,18 +18,18 @@
     "@aws-sdk/client-s3": "^3.1110.0",
     "@aws-sdk/client-secrets-manager": "^3.700.0",
     "@aws-sdk/client-servicediscovery": "^3.1110.0",
-    "anbaric-data-store": "^1.25.0",
-    "anbaric-plugins": "^1.25.0",
-    "anbaric-tsapi": "^1.25.0",
-    "anbaric-web": "^1.25.0",
+    "anbaric-data-store": "^1.27.0",
+    "anbaric-plugins": "^1.27.0",
+    "anbaric-tsapi": "^1.27.0",
+    "anbaric-web": "^1.27.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.25.0",
-    "anbaric-state-machine": "^1.25.0",
+    "anbaric-impl-cloud": "^1.27.0",
+    "anbaric-state-machine": "^1.27.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/app-management/BaseBuildLayer.ts

@@ -2,6 +2,7 @@ import {ChildProcess, spawn} from "node:child_process";
 import {mkdir, readFile, rm, symlink, writeFile} from "node:fs/promises";
 import {join} from "node:path";
 import {adminPing} from "../app-admin/adminPing";
+import {DocGenerator} from "../docs/DocGenerator";
 import {BuildLayer, DeploymentStatus, DeploymentSummary} from "./BuildLayer";
 
 type Deployment = {
@@ -30,6 +31,7 @@ const adminProbe : Probe = (host, port) => adminPing(host, port, LIVENESS_PROBE_
 abstract class BaseBuildLayer implements BuildLayer {
 
     protected deployments = new Map<string, Deployment>();
+    protected docGenerator? : DocGenerator;
     private nextAppIndex = 0;
     private hydration? : Promise<void>;
 
@@ -127,6 +129,12 @@ abstract class BaseBuildLayer implements BuildLayer {
         this.log(deployment, "extracting application bundle");
         await this.run(deployment, "tar", ["-xzf", tarballPath, "-C", appDir]);
 
+        // Documentation is generated off the critical path: fire-and-forget from
+        // the extracted source, before the build, so a slow model call can never
+        // delay or fail the deploy. Regenerated on every deploy, replaces=redeploy.
+        void this.docGenerator?.generate(deployment.appName, appDir, { redeploy: !!deployment.replaces })
+            .catch(error => this.log(deployment, `doc generation skipped: ${error instanceof Error ? error.message : error}`));
+
         this.log(deployment, "linking anbaric workspace packages");
         const manifest = JSON.parse(await readFile(join(appDir, "package.json"), "utf8"));
         await this.linkWorkspacePackages(appDir, manifest);
@@ -155,9 +163,27 @@ abstract class BaseBuildLayer implements BuildLayer {
             await new Promise(resolve => setTimeout(resolve, LIVENESS_PROBE_INTERVAL_MS));
         }
 
+        // The admin port never answering almost always means the app process
+        // crashed on boot, so pull whatever it logged and put the real cause in
+        // the deploy result - not just the timeout, which says nothing.
+        const diagnostics = await this.diagnostics(deployment).catch(() => []);
+
         await this.stop(deployment);
         deployment.status = "failed";
         this.log(deployment, `app admin port ${deployment.adminPort} did not answer within ${this.livenessTimeoutMs / 1000}s`);
+        if (diagnostics.length > 0) {
+            this.log(deployment, "the app's last output before it stopped:");
+            for (const line of diagnostics) this.log(deployment, `  ${line}`);
+        } else {
+            this.log(deployment, "no output was captured - the app may have failed before logging, or is still starting");
+        }
+    }
+
+    // The app's recent output, for diagnosing a boot that never became live.
+    // Each build layer reads it from where its apps log (container logs,
+    // CloudWatch); the default has nothing to offer.
+    protected async diagnostics(_deployment : Deployment) : Promise<Array<string>> {
+        return [];
     }
 
     private async linkWorkspacePackages(appDir : string, manifest : { dependencies? : Record<string, string> }) : Promise<void> {

package/src/app-management/DockerBuildLayer.ts

@@ -2,6 +2,7 @@ import {spawn} from "node:child_process";
 import {writeFile} from "node:fs/promises";
 import {join} from "node:path";
 import {BaseBuildLayer, Deployment, Probe} from "./BaseBuildLayer";
+import {DocGenerator} from "../docs/DocGenerator";
 import {childLines} from "./childLines";
 
 type LogStreamer = (container : string, signal : AbortSignal) => AsyncIterable<string>;
@@ -15,6 +16,7 @@ type DockerBuildLayerOptions = {
     platformUrl : string,
     sqlDatabaseUrl? : string,
     sqlSchema? : string,
+    docGenerator? : DocGenerator,
 };
 
 type CommandRunner = (command : string, args : Array<string>, onOutput : (line : string) => void) => Promise<void>;
@@ -51,6 +53,21 @@ class DockerBuildLayer extends BaseBuildLayer {
                 private runCommand : CommandRunner = spawnRunner, probe? : Probe,
                 private logStreamer : LogStreamer = dockerLogStreamer) {
         super(appsDir, consumerPortBase, probe);
+        this.docGenerator = options.docGenerator;
+    }
+
+    protected async diagnostics(deployment : Deployment) : Promise<Array<string>> {
+        return new Promise((resolve) => {
+            const lines : Array<string> = [];
+            const take = (buffer : Buffer) => {
+                for (const line of buffer.toString().split("\n")) if (line.trim()) lines.push(line);
+            };
+            const logs = spawn("docker", ["logs", "--tail", "30", this.appHostFor(deployment.appName)]);
+            logs.stdout.on("data", take);
+            logs.stderr.on("data", take);
+            logs.on("close", () => resolve(lines.slice(-30)));
+            logs.on("error", () => resolve([]));
+        });
     }
 
     protected appHostFor(appName : string) : string {
@@ -90,6 +107,7 @@ class DockerBuildLayer extends BaseBuildLayer {
             "--env", "ANBARIC_SECRET_STORE_TYPE=cloud",
             "--env", "ANBARIC_AUDITOR_TYPE=cloud",
             "--env", "ANBARIC_SESSION_RESOLVER_TYPE=cloud",
+            "--env", "ANBARIC_NOTIFIER_TYPE=cloud",
             "--env", `ANBARIC_CONSUMER_PORT=${deployment.consumerPort}`,
             "--env", `ANBARIC_CONSUMER_URL=http://${container}:${deployment.consumerPort}`,
             ...sqlEnv,

package/src/app-management/FargateBuildLayer.ts

@@ -7,8 +7,9 @@ import {ECSClient, CreateServiceCommand, DeleteServiceCommand, DescribeServicesC
 import {S3Client, PutObjectCommand} from "@aws-sdk/client-s3";
 import {ServiceDiscoveryClient, CreateServiceCommand as CreateDiscoveryServiceCommand,
     ListServicesCommand} from "@aws-sdk/client-servicediscovery";
-import {CloudWatchLogsClient, StartLiveTailCommand} from "@aws-sdk/client-cloudwatch-logs";
+import {CloudWatchLogsClient, FilterLogEventsCommand, StartLiveTailCommand} from "@aws-sdk/client-cloudwatch-logs";
 import {BaseBuildLayer, Deployment, Probe} from "./BaseBuildLayer";
+import {DocGenerator} from "../docs/DocGenerator";
 import {dockerfileFor} from "./DockerBuildLayer";
 
 type FargateBuildLayerOptions = {
@@ -30,6 +31,7 @@ type FargateBuildLayerOptions = {
     servicesApiKey? : string,
     sqlDatabaseUrlSecretArn? : string,
     sqlSchema? : string,
+    docGenerator? : DocGenerator,
 };
 
 type AwsClients = {
@@ -61,6 +63,20 @@ class FargateBuildLayer extends BaseBuildLayer {
                 private buildPollIntervalMs : number = 5000) {
         super(appsDir, consumerPortBase, probe, FARGATE_LIVENESS_TIMEOUT_MS);
         this.aws = aws ?? defaultClients(options.awsRegion);
+        this.docGenerator = options.docGenerator;
+    }
+
+    protected async diagnostics(deployment : Deployment) : Promise<Array<string>> {
+        const response = await this.aws.cloudWatchLogs.send(new FilterLogEventsCommand({
+            logGroupName: this.options.appsLogGroup,
+            logStreamNamePrefix: deployment.appName,
+            startTime: Date.now() - 10 * 60_000,
+            limit: 40,
+        }));
+        return (response.events ?? [])
+            .map((event : any) => (event.message ?? "").trimEnd())
+            .filter((line : string) => line.length > 0)
+            .slice(-30);
     }
 
     protected appHostFor(appName : string) : string {
@@ -179,6 +195,7 @@ class FargateBuildLayer extends BaseBuildLayer {
                     { name: "ANBARIC_SECRET_STORE_TYPE", value: "cloud" },
                     { name: "ANBARIC_AUDITOR_TYPE", value: "cloud" },
                     { name: "ANBARIC_SESSION_RESOLVER_TYPE", value: "cloud" },
+                    { name: "ANBARIC_NOTIFIER_TYPE", value: "cloud" },
                     { name: "ANBARIC_CONSUMER_PORT", value: String(deployment.consumerPort) },
                     { name: "ANBARIC_CONSUMER_URL", value: `http://${deployment.appHost}:${deployment.consumerPort}` },
                     ...(this.options.servicesUrl ? [{ name: "ANBARIC_SERVICES_URL", value: this.options.servicesUrl }] : []),

package/src/data-store/AppDocsStore.ts

@@ -0,0 +1,19 @@
+type AppDoc = {
+    slug : string,
+    title : string,
+    markdown : string,
+};
+
+/* Generated user documentation for an app. Docs are regenerated wholesale on
+   every deploy, so the store replaces an app's whole set at once rather than
+   upserting doc by doc - a doc that no longer applies after a redeploy must not
+   linger. */
+interface AppDocsStore {
+
+    replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void>;
+
+    listForApp(appId : string) : Promise<Array<AppDoc>>;
+
+}
+
+export type { AppDoc, AppDocsStore };

package/src/data-store/InMemoryAppDocsStore.ts

@@ -0,0 +1,17 @@
+import {AppDoc, AppDocsStore} from "./AppDocsStore";
+
+class InMemoryAppDocsStore implements AppDocsStore {
+
+    private byApp = new Map<string, Array<AppDoc>>();
+
+    async replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void> {
+        this.byApp.set(appId, docs.map(doc => ({ ...doc })));
+    }
+
+    async listForApp(appId : string) : Promise<Array<AppDoc>> {
+        return (this.byApp.get(appId) ?? []).map(doc => ({ ...doc }));
+    }
+
+}
+
+export { InMemoryAppDocsStore }

package/src/data-store/PostgresAppDocsStore.ts

@@ -0,0 +1,43 @@
+import {Pool} from "pg";
+import {AppDoc, AppDocsStore} from "./AppDocsStore";
+
+/* Replacing an app's docs is a delete-then-insert in one transaction, so a
+   redeploy swaps the whole set atomically - a reader never sees a mix of old
+   and new, and a crash mid-write leaves the previous docs intact. */
+class PostgresAppDocsStore implements AppDocsStore {
+
+    constructor(private pool : Pool) {}
+
+    async replaceForApp(appId : string, docs : Array<AppDoc>) : Promise<void> {
+        const client = await this.pool.connect();
+
+        try {
+            await client.query("BEGIN");
+            await client.query("DELETE FROM app_docs WHERE app_id = $1", [appId]);
+
+            if (docs.length > 0) {
+                await client.query(
+                    `INSERT INTO app_docs (app_id, slug, title, markdown)
+                     SELECT $1, * FROM unnest($2::text[], $3::text[], $4::text[])`,
+                    [appId, docs.map(doc => doc.slug), docs.map(doc => doc.title), docs.map(doc => doc.markdown)],
+                );
+            }
+
+            await client.query("COMMIT");
+        } catch (error) {
+            await client.query("ROLLBACK").catch(() => {});
+            throw error;
+        } finally {
+            client.release();
+        }
+    }
+
+    async listForApp(appId : string) : Promise<Array<AppDoc>> {
+        const result = await this.pool.query(
+            "SELECT slug, title, markdown FROM app_docs WHERE app_id = $1 ORDER BY slug", [appId]);
+        return result.rows.map(row => ({ slug: row.slug, title: row.title, markdown: row.markdown }));
+    }
+
+}
+
+export { PostgresAppDocsStore }

package/src/data-store/Schema.ts

@@ -94,6 +94,18 @@ const ensureSchema = async (pool : Pool) : Promise<void> => {
         ON job_run_schedule (app_id, workflow_id, run_at)`);
     await pool.query(`CREATE INDEX IF NOT EXISTS job_run_schedule_due
         ON job_run_schedule (run_at) WHERE claimed_at IS NULL`);
+    // User documentation the platform generates from an app's source on deploy,
+    // keyed by (app_id, slug). A redeploy replaces the whole set for an app.
+    await pool.query(`
+        CREATE TABLE IF NOT EXISTS app_docs (
+            app_id       TEXT NOT NULL,
+            slug         TEXT NOT NULL,
+            title        TEXT NOT NULL DEFAULT '',
+            markdown     TEXT NOT NULL,
+            generated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+            PRIMARY KEY (app_id, slug)
+        )
+    `);
     await pool.query("CREATE SCHEMA IF NOT EXISTS anbaric_system");
     await pool.query(`
         CREATE TABLE IF NOT EXISTS anbaric_system.cli_keys (

package/src/docs/DocGenerator.ts

@@ -0,0 +1,31 @@
+import {AppDocsStore} from "../data-store/AppDocsStore";
+import {DocModel} from "./DocModel";
+import {gatherSources} from "./gatherSources";
+
+/* Generates an app's user documentation from its source and stores it. It runs
+   off the deploy's critical path (the build layer calls it fire-and-forget), so
+   it is deliberately all-or-nothing and never throws: any failure - no model
+   configured, a slow or erroring model, unreadable source - is logged and the
+   existing docs are left as they are. */
+class DocGenerator {
+
+    constructor(private model : DocModel, private store : AppDocsStore) {}
+
+    async generate(appName : string, appDir : string, options : { redeploy : boolean }) : Promise<void> {
+        try {
+            const { files, truncated } = await gatherSources(appDir);
+            if (files.length === 0) return;
+
+            const docs = await this.model.writeDocs({ appName, files, truncated });
+            if (docs.length === 0) return;
+
+            await this.store.replaceForApp(appName, docs);
+            console.log(`[docs] ${options.redeploy ? "regenerated" : "generated"} ${docs.length} doc(s) for "${appName}"`);
+        } catch (error) {
+            console.error(`[docs] could not generate documentation for "${appName}": ${error instanceof Error ? error.message : error}`);
+        }
+    }
+
+}
+
+export { DocGenerator }

package/src/docs/DocModel.ts

@@ -0,0 +1,18 @@
+import {AppDoc} from "../data-store/AppDocsStore";
+
+type DocContext = {
+    appName : string,
+    files : Array<{ path : string, content : string }>,
+    truncated : boolean,
+};
+
+/* Turns an app's source into a set of user-facing docs. An implementation that
+   cannot reach a model (nothing configured) returns an empty set rather than
+   throwing, so doc generation quietly does nothing. */
+interface DocModel {
+
+    writeDocs(context : DocContext) : Promise<Array<AppDoc>>;
+
+}
+
+export type { DocContext, DocModel };

package/src/docs/GatewayDocModel.ts

@@ -0,0 +1,82 @@
+import {AppDoc} from "../data-store/AppDocsStore";
+import {DocContext, DocModel} from "./DocModel";
+
+type FetchFn = (url : string, init : RequestInit) => Promise<Response>;
+
+const SYSTEM_PROMPT = `You write user documentation for an application deployed on Anbaric.
+
+Anbaric apps model their domain as state machines: long-lived jobs move through named states, driven by actions and transitions, with data validated against a schema and every change attributed to an actor. Read the whole source you are given and write documentation for the people who will USE this app - what it does, the workflows it runs, how someone drives it, and anything they need to know. Write clear markdown. Prefer several focused docs over one long one; give each a short kebab-case slug and a human title. Do not invent features the source does not show. If the source was truncated, document only what you can see.`;
+
+const OUTPUT_SCHEMA = {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+        docs: {
+            type: "array",
+            items: {
+                type: "object",
+                additionalProperties: false,
+                properties: {
+                    slug: { type: "string" },
+                    title: { type: "string" },
+                    markdown: { type: "string" },
+                },
+                required: ["slug", "title", "markdown"],
+            },
+        },
+    },
+    required: ["docs"],
+};
+
+/* The platform's doc writer over an OpenAI-compatible chat endpoint - the same
+   gateway the agentic actions use (ANBARIC_AI_GATEWAY_*), so no new config.
+   With no token there is nothing to call, so it returns no docs and the
+   generator does nothing. */
+class GatewayDocModel implements DocModel {
+
+    constructor(private baseUrl : string = process.env.ANBARIC_AI_GATEWAY_URL ?? "https://api.openai.com/v1",
+                private apiKey : string = process.env.ANBARIC_AI_GATEWAY_TOKEN ?? "",
+                private model : string = process.env.ANBARIC_AGENTIC_MODEL ?? "gpt-5.4-mini",
+                private fetchFn : FetchFn = (url, init) => fetch(url, init)) {}
+
+    async writeDocs(context : DocContext) : Promise<Array<AppDoc>> {
+        if (!this.apiKey) {
+            console.warn(`[docs] no ANBARIC_AI_GATEWAY_TOKEN - skipping documentation for "${context.appName}"`);
+            return [];
+        }
+
+        const response = await this.fetchFn(`${this.baseUrl.replace(/\/$/, "")}/chat/completions`, {
+            method: "POST",
+            headers: { "content-type": "application/json", "authorization": `Bearer ${this.apiKey}` },
+            body: JSON.stringify({
+                model: this.model,
+                messages: [
+                    { role: "system", content: SYSTEM_PROMPT },
+                    { role: "user", content: this.render(context) },
+                ],
+                response_format: {
+                    type: "json_schema",
+                    json_schema: { name: "docs", strict: true, schema: OUTPUT_SCHEMA },
+                },
+            }),
+        });
+
+        if (!response.ok) {
+            const problem = await response.json().catch(() => ({}));
+            throw new Error(`Doc model request failed with status ${response.status}${problem.error?.message ? `: ${problem.error.message}` : ""}`);
+        }
+
+        const message = (await response.json()).choices?.[0]?.message?.content;
+        const docs = message ? JSON.parse(message).docs : [];
+        return Array.isArray(docs) ? docs : [];
+    }
+
+    private render(context : DocContext) : string {
+        const header = `App "${context.appName}"${context.truncated ? " (source was truncated - some files are omitted)" : ""}. Source:`;
+        const files = context.files.map(file => `\n\n=== ${file.path} ===\n${file.content}`).join("");
+        return header + files;
+    }
+
+}
+
+export { GatewayDocModel }

package/src/docs/gatherSources.ts

@@ -0,0 +1,79 @@
+import {readFile, readdir} from "node:fs/promises";
+import {join, relative} from "node:path";
+
+const INCLUDE = /\.(ts|tsx|js|jsx|json|md|css|html)$/;
+const SKIP_DIRS = new Set(["node_modules", "dist", ".git", ".next", "build", "coverage"]);
+const SKIP_FILES = new Set(["package-lock.json"]);
+
+// A file this big that isn't a manifest is almost always baked data or an
+// inlined asset - noise that would crowd out code and burn tokens.
+const MAX_FILE_BYTES = 30_000;
+// ~60K tokens of source, a generous ceiling; real apps are far under it.
+const MAX_TOTAL_BYTES = 240_000;
+
+type GatheredFile = { path : string, content : string };
+type Gathered = { files : Array<GatheredFile>, truncated : boolean };
+
+const isManifest = (path : string) : boolean =>
+    /(^|\/)package\.json$/.test(path) || /(^|\/)\.anbaric\/app-config\.json$/.test(path) || /(^|\/)readme\.md$/i.test(path);
+
+// Manifests and docs first, then source, then the rest - so a truncated
+// snapshot keeps the files that describe the app best.
+const priority = (path : string) : number => {
+    if (isManifest(path)) return 0;
+    if (path.toLowerCase().endsWith(".md")) return 1;
+    if (/\.(ts|tsx|js|jsx)$/.test(path)) return 2;
+    return 3;
+};
+
+const walk = async (dir : string, root : string, found : Array<string>) : Promise<void> => {
+    let entries;
+    try {
+        entries = await readdir(dir, { withFileTypes: true });
+    } catch {
+        return;
+    }
+
+    for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!SKIP_DIRS.has(entry.name)) await walk(full, root, found);
+        } else if (INCLUDE.test(entry.name) && !SKIP_FILES.has(entry.name)) {
+            found.push(relative(root, full));
+        }
+    }
+};
+
+/* The whole of an app's source, small enough to hand to a model in one go:
+   manifests, docs and code, skipping dependencies, build output and oversized
+   data files, and capped in total. `truncated` is true when the cap dropped
+   files, so the caller can tell the model not to assume it saw everything. */
+const gatherSources = async (appDir : string) : Promise<Gathered> => {
+    const paths : Array<string> = [];
+    await walk(appDir, appDir, paths);
+    paths.sort((left, right) => priority(left) - priority(right) || left.localeCompare(right));
+
+    const files : Array<GatheredFile> = [];
+    let total = 0;
+    let truncated = false;
+
+    for (const path of paths) {
+        let content : string;
+        try {
+            content = await readFile(join(appDir, path), "utf8");
+        } catch {
+            continue;
+        }
+
+        if (!isManifest(path) && content.length > MAX_FILE_BYTES) continue;
+        if (total + content.length > MAX_TOTAL_BYTES) { truncated = true; continue; }
+
+        files.push({ path, content });
+        total += content.length;
+    }
+
+    return { files, truncated };
+};
+
+export { gatherSources };
+export type { Gathered, GatheredFile };

package/src/hosting/HostingServer.ts

@@ -1,4 +1,4 @@
-import {JobPersistence, JobRunSchedulePersistence, JsonStore, SecretStore} from "anbaric-tsapi";
+import {JobPersistence, JobRunSchedulePersistence, JsonStore, Notifier, SecretStore} from "anbaric-tsapi";
 import {BuildLayer} from "../app-management/BuildLayer";
 import {AuditRecordStore} from "../auditing/AuditRecordStore";
 import {Authenticator} from "../auth/Authenticator";
@@ -19,6 +19,7 @@ import {DocumentsHandler} from "./handlers/DocumentsHandler";
 import {JobsHandler} from "./handlers/JobsHandler";
 import {FaviconHandler} from "./handlers/FaviconHandler";
 import {JobRunSchedulesHandler} from "./handlers/JobRunSchedulesHandler";
+import {NotificationsHandler} from "./handlers/NotificationsHandler";
 import {LogoutHandler} from "./handlers/LogoutHandler";
 import {PagesHandler} from "./handlers/PagesHandler";
 import {PingHandler} from "./handlers/PingHandler";
@@ -56,7 +57,8 @@ class HostingServer {
                 tenant? : string,
                 auditRecords? : AuditRecordStore,
                 plugins : Array<LoadedPlugin> = [],
-                jobRunSchedules? : JobRunSchedulePersistence) {
+                jobRunSchedules? : JobRunSchedulePersistence,
+                notifier? : Notifier) {
         const pages = new PagesHandler();
         const ping = new PingHandler(tenant);
         const jobs = new JobsHandler(persistence);
@@ -84,6 +86,7 @@ class HostingServer {
         if (secrets) publicRouter.registerApi("secrets", secrets);
         if (audits) publicRouter.registerApi("audits", audits);
         if (jobRunSchedules) publicRouter.registerApi("job-run-schedules", new JobRunSchedulesHandler(jobRunSchedules));
+        if (notifier) publicRouter.registerApi("notifications", new NotificationsHandler(notifier));
         if (cliAuthorizer) {
             publicRouter.register("authorize-cli", new AuthorizeCliHandler(cliAuthorizer, pages, tenant));
             publicRouter.registerApi("keys", new KeysHandler(cliAuthorizer));
@@ -107,6 +110,7 @@ class HostingServer {
         if (secrets) internalRouter.registerApi("secrets", secrets);
         if (audits) internalRouter.registerApi("audits", audits);
         if (jobRunSchedules) internalRouter.registerApi("job-run-schedules", new JobRunSchedulesHandler(jobRunSchedules));
+        if (notifier) internalRouter.registerApi("notifications", new NotificationsHandler(notifier));
 
         // The favicon is requested by the browser before anyone has signed in,
         // and by deployed apps' pages, so gating it behind a session would send

package/src/hosting/handlers/NotificationsHandler.ts

@@ -0,0 +1,26 @@
+import {Notifier, deserializeJob, deserializeWaitForInput} from "anbaric-tsapi";
+import {Request} from "../Request";
+import {RequestHandler} from "../RequestHandler";
+
+/* Receives a deployed app's notification request and hands it to the platform's
+   server-side notifier. Delivery is the notifier's business - the platform just
+   reconstructs the job and its wait from the wire and passes them on. */
+class NotificationsHandler implements RequestHandler {
+
+    constructor(private notifier : Notifier) {}
+
+    async handle(request : Request) : Promise<void> {
+        if (request.method !== "POST" || request.id) return request.notFound();
+
+        const { targets, job, waitingFor } = await request.body();
+        if (!Array.isArray(targets) || !job || !waitingFor) {
+            return request.reply(400, { error: "Expected { targets, job, waitingFor }" });
+        }
+
+        await this.notifier.notify(targets, deserializeJob(job), deserializeWaitForInput(waitingFor));
+        request.reply(204);
+    }
+
+}
+
+export { NotificationsHandler }

package/src/index.ts

@@ -9,6 +9,7 @@ export * from "./auth/CliKeyStore";
 export * from "./auth/HttpCliKeyStore";
 export * from "./auth/InMemoryCliKeyStore";
 export * from "./auth/AuthenticatorLoader";
+export * from "./notifications/NotifierLoader";
 export * from "./auth/KeyPair";
 export * from "./auth/Role";
 export * from "./auth/SessionSigner";
@@ -23,6 +24,12 @@ export * from "./app-admin/adminPing";
 export * from "./data-store/PostgresCliKeyStore";
 export * from "./data-store/PostgresJobPersistence";
 export * from "./data-store/PostgresJobRunSchedulePersistence";
+export * from "./data-store/AppDocsStore";
+export * from "./data-store/PostgresAppDocsStore";
+export * from "./data-store/InMemoryAppDocsStore";
+export * from "./docs/DocModel";
+export * from "./docs/GatewayDocModel";
+export * from "./docs/DocGenerator";
 export * from "./data-store/PostgresJsonStore";
 export * from "./data-store/Schema";
 export * from "./data-store/SecretsManagerSecretStore";
@@ -49,6 +56,7 @@ export * from "./plugins/PluginLoader";
 export * from "./plugins/PageDirectory";
 export * from "./hosting/handlers/QueueHandler";
 export * from "./hosting/handlers/JobRunSchedulesHandler";
+export * from "./hosting/handlers/NotificationsHandler";
 export * from "./hosting/handlers/SecretsHandler";
 export * from "./hosting/handlers/StateMachinesHandler";
 export * from "./hosting/handlers/auth/AuthorizeCliHandler";

package/src/main.ts

@@ -3,6 +3,7 @@ import {SecretStore} from "anbaric-tsapi";
 import {InMemorySecretStore} from "anbaric-data-store";
 import {Pool} from "pg";
 import {loadAuthenticator} from "./auth/AuthenticatorLoader";
+import {loadNotifier} from "./notifications/NotifierLoader";
 import {CliAuthorizer} from "./auth/CliAuthorizer";
 import {HttpCliKeyStore} from "./auth/HttpCliKeyStore";
 import {TokenAuthenticator} from "./auth/TokenAuthenticator";
@@ -16,6 +17,9 @@ import {PostgresJsonStore} from "./data-store/PostgresJsonStore";
 import {PostgresQueue} from "./queuing/PostgresQueue";
 import {DockerBuildLayer} from "./app-management/DockerBuildLayer";
 import {FargateBuildLayer} from "./app-management/FargateBuildLayer";
+import {DocGenerator} from "./docs/DocGenerator";
+import {GatewayDocModel} from "./docs/GatewayDocModel";
+import {PostgresAppDocsStore} from "./data-store/PostgresAppDocsStore";
 import {ConsumerRegistry} from "./queuing/ConsumerRegistry";
 import {Dispatcher} from "./queuing/Dispatcher";
 import {HostingServer} from "./hosting/HostingServer";
@@ -31,6 +35,10 @@ const hostingPort = Number(process.env.ANBARIC_HOSTING_PORT ?? 8787);
 const internalPort = Number(process.env.ANBARIC_INTERNAL_PORT ?? 8788);
 const appsDir = process.env.ANBARIC_APPS_DIR ?? "/tmp/anbaric-apps";
 
+// Generates user docs from an app's source on deploy; no-ops without an AI
+// gateway token. The build layer calls it fire-and-forget off the deploy path.
+const docGenerator = new DocGenerator(new GatewayDocModel(), new PostgresAppDocsStore(pool));
+
 const buildLayer = process.env.ANBARIC_BUILD_LAYER === "docker"
     ? new DockerBuildLayer(appsDir, {
         baseImage: process.env.ANBARIC_APP_BASE_IMAGE ?? "anbaric-v2-platform:local",
@@ -38,6 +46,7 @@ const buildLayer = process.env.ANBARIC_BUILD_LAYER === "docker"
         platformUrl: process.env.ANBARIC_PLATFORM_INTERNAL_URL ?? `http://localhost:${internalPort}`,
         sqlDatabaseUrl: process.env.ANBARIC_APP_SQL_DATABASE_URL,
         sqlSchema: process.env.ANBARIC_SQL_SCHEMA,
+        docGenerator,
     })
     : process.env.ANBARIC_BUILD_LAYER === "fargate"
     ? new FargateBuildLayer(appsDir, {
@@ -59,6 +68,7 @@ const buildLayer = process.env.ANBARIC_BUILD_LAYER === "docker"
         servicesApiKey: process.env.ANBARIC_SERVICES_API_KEY,
         sqlDatabaseUrlSecretArn: process.env.ANBARIC_AWS_APP_SQL_URL_SECRET,
         sqlSchema: process.env.ANBARIC_SQL_SCHEMA,
+        docGenerator,
     })
     : undefined;
 
@@ -84,7 +94,7 @@ const plugins = await new PluginLoader().load(process.env.ANBARIC_PLUGINS ?? "an
 const server = new HostingServer(new PostgresJobPersistence(pool), queue, registry, buildLayer,
     (appId, collection) => new PostgresJsonStore(pool, appId, collection), secretStoreFor, authenticator, cliAuthorizer,
     tokenAuthenticator, process.env.ANBARIC_TENANT, new PostgresAuditRecordStore(pool), plugins,
-    new PostgresJobRunSchedulePersistence(pool));
+    new PostgresJobRunSchedulePersistence(pool), await loadNotifier(process.env.ANBARIC_NOTIFIER_MODULE));
 const port = await server.listen(hostingPort);
 const internal = await server.listenInternal(internalPort);
 

package/src/notifications/NotifierLoader.ts

@@ -0,0 +1,18 @@
+import {Notifier} from "anbaric-tsapi";
+
+/* Loads the server-side notifier by module name, the same way the authenticator
+   is loaded (see AuthenticatorLoader). The platform is open source and cannot
+   name a proprietary delivery mechanism, so a host names its module through
+   ANBARIC_NOTIFIER_MODULE and that module exports a createNotifier factory.
+   With nothing named, the platform accepts notifications but delivers nothing. */
+const loadNotifier = async (moduleName? : string) : Promise<Notifier | undefined> => {
+    if (!moduleName) return undefined;
+
+    const module = await import(moduleName);
+    if (typeof module.createNotifier !== "function") {
+        throw new Error(`Notifier module "${moduleName}" does not export a createNotifier function`);
+    }
+    return module.createNotifier();
+};
+
+export { loadNotifier }