anbaric-cloud-hosting 1.69.0 → 1.70.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anbaric-cloud-hosting",
-  "version": "1.69.0",
+  "version": "1.70.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.69.0",
-    "anbaric-plugins": "^1.69.0",
-    "anbaric-tsapi": "^1.69.0",
-    "anbaric-web": "^1.69.0",
+    "anbaric-data-store": "^1.70.0",
+    "anbaric-plugins": "^1.70.0",
+    "anbaric-tsapi": "^1.70.0",
+    "anbaric-web": "^1.70.0",
     "esbuild": "^0.28.2",
     "pg": "^8.16.0"
   },
   "devDependencies": {
     "@types/node": "^26.2.0",
     "@types/pg": "^8.15.0",
-    "anbaric-impl-cloud": "^1.69.0",
-    "anbaric-state-machine": "^1.69.0",
+    "anbaric-impl-cloud": "^1.70.0",
+    "anbaric-state-machine": "^1.70.0",
     "tsx": "^4.20.0",
     "typescript": "^7.0.2"
   },

package/src/data-store/InMemorySkillStore.ts

@@ -0,0 +1,31 @@
+import {Skill, SkillDraft, SkillStore} from "./SkillStore";
+
+class InMemorySkillStore implements SkillStore {
+
+    private skills = new Map<string, Skill>();
+
+    async list() : Promise<Array<Skill>> {
+        return [...this.skills.values()]
+            .sort((left, right) => left.id.localeCompare(right.id))
+            .map(skill => ({ ...skill }));
+    }
+
+    async get(id : string) : Promise<Skill | undefined> {
+        const skill = this.skills.get(id);
+        return skill && { ...skill };
+    }
+
+    async save(draft : SkillDraft) : Promise<Skill> {
+        const now = new Date();
+        const saved : Skill = { ...draft, createdAt: this.skills.get(draft.id)?.createdAt ?? now, updatedAt: now };
+        this.skills.set(draft.id, saved);
+        return { ...saved };
+    }
+
+    async remove(id : string) : Promise<boolean> {
+        return this.skills.delete(id);
+    }
+
+}
+
+export { InMemorySkillStore };

package/src/data-store/PlatformMigrations.ts

@@ -273,6 +273,20 @@ const PLATFORM_MIGRATIONS : Array<Migration> = [
         )`,
     ),
 
+    /* Guidance the tenant's builders write for the agents that work on it:
+       usage hints say when to reach for a skill, the body says what to do.
+       A platform table rather than workflow data, since apps never see it. */
+    statements("008-skills",
+        `CREATE TABLE IF NOT EXISTS anbaric_system.skills (
+            id          TEXT PRIMARY KEY,
+            title       TEXT NOT NULL,
+            usage_hints TEXT NOT NULL,
+            body        TEXT NOT NULL,
+            created_at  TIMESTAMPTZ NOT NULL DEFAULT now(),
+            updated_at  TIMESTAMPTZ NOT NULL DEFAULT now()
+        )`,
+    ),
+
 ];
 
 export { PLATFORM_MIGRATIONS };

package/src/data-store/PostgresSkillStore.ts

@@ -0,0 +1,47 @@
+import {Pool} from "pg";
+import {Skill, SkillDraft, SkillStore} from "./SkillStore";
+
+const COLUMNS = "id, title, usage_hints, body, created_at, updated_at";
+
+const rowToSkill = (row : any) : Skill => ({
+    id: row.id,
+    title: row.title,
+    usageHints: row.usage_hints,
+    body: row.body,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+});
+
+class PostgresSkillStore implements SkillStore {
+
+    constructor(private pool : Pool) {}
+
+    async list() : Promise<Array<Skill>> {
+        const result = await this.pool.query(`SELECT ${COLUMNS} FROM anbaric_system.skills ORDER BY id`);
+        return result.rows.map(rowToSkill);
+    }
+
+    async get(id : string) : Promise<Skill | undefined> {
+        const result = await this.pool.query(`SELECT ${COLUMNS} FROM anbaric_system.skills WHERE id = $1`, [id]);
+        return result.rows[0] && rowToSkill(result.rows[0]);
+    }
+
+    async save(draft : SkillDraft) : Promise<Skill> {
+        const result = await this.pool.query(
+            `INSERT INTO anbaric_system.skills (id, title, usage_hints, body)
+             VALUES ($1, $2, $3, $4)
+             ON CONFLICT (id) DO UPDATE
+                 SET title = EXCLUDED.title, usage_hints = EXCLUDED.usage_hints, body = EXCLUDED.body, updated_at = now()
+             RETURNING ${COLUMNS}`,
+            [draft.id, draft.title, draft.usageHints, draft.body]);
+        return rowToSkill(result.rows[0]);
+    }
+
+    async remove(id : string) : Promise<boolean> {
+        const result = await this.pool.query("DELETE FROM anbaric_system.skills WHERE id = $1", [id]);
+        return (result.rowCount ?? 0) > 0;
+    }
+
+}
+
+export { PostgresSkillStore };

package/src/data-store/SkillStore.ts

@@ -0,0 +1,38 @@
+/* A skill is guidance a tenant writes for the agents that build on it: when to
+   reach for it (the usage hints, which an agent reads before deciding) and
+   what to do (the body, which it reads once it has decided). Kept by the
+   platform, managed from the console, and never handed to deployed apps. */
+type Skill = {
+    id : string,
+    title : string,
+    usageHints : string,
+    body : string,
+    createdAt : Date,
+    updatedAt : Date,
+};
+
+type SkillDraft = Omit<Skill, "createdAt" | "updatedAt">;
+
+/* The id ends up as the tail of a tool name an agent sees, after a fixed
+   prefix, and tool names are capped at 64 characters: hence the shape and
+   the length. */
+const SKILL_ID_SHAPE = /^[a-z0-9][a-z0-9-]{0,49}$/;
+
+const isSkillId = (value : unknown) : value is string =>
+    typeof value === "string" && SKILL_ID_SHAPE.test(value);
+
+interface SkillStore {
+
+    list() : Promise<Array<Skill>>;
+
+    get(id : string) : Promise<Skill | undefined>;
+
+    // Creates or replaces the skill with that id.
+    save(draft : SkillDraft) : Promise<Skill>;
+
+    remove(id : string) : Promise<boolean>;
+
+}
+
+export type { Skill, SkillDraft, SkillStore };
+export { SKILL_ID_SHAPE, isSkillId };

package/src/hosting/HostingServer.ts

@@ -14,6 +14,8 @@ import {MembersHandler} from "./handlers/auth/MembersHandler";
 import {BillingHandler} from "./handlers/BillingHandler";
 import {CentralBilling} from "../billing/CentralBilling";
 import {AppSettingsStore} from "../data-store/AppSettingsStore";
+import {SkillStore} from "../data-store/SkillStore";
+import {SkillsHandler} from "./handlers/SkillsHandler";
 import {Subdomains} from "../subdomains/Subdomains";
 import {AuditsHandler} from "./handlers/AuditsHandler";
 import {AuthorizeCliHandler} from "./handlers/auth/AuthorizeCliHandler";
@@ -83,7 +85,8 @@ class HostingServer {
                 fileStorageFor? : (appId : string) => FileStorage,
                 subdomains? : Subdomains,
                 billing? : CentralBilling,
-                appSettings? : AppSettingsStore) {
+                appSettings? : AppSettingsStore,
+                skills? : SkillStore) {
         const pages = new PagesHandler();
         const ping = new PingHandler(tenant);
         const jobs = new JobsHandler(persistence);
@@ -119,6 +122,8 @@ class HostingServer {
         if (memberships) publicRouter.registerApi("invitations", new InvitationsHandler(memberships, entitlements));
         if (memberships) publicRouter.registerApi("members", new MembersHandler(memberships, entitlements));
         if (billing) publicRouter.registerApi("billing", new BillingHandler(billing));
+        // People and their agents only: a deployed app has no business reading skills.
+        if (skills) publicRouter.registerApi("skills", new SkillsHandler(skills));
         const prompts = promptManagerFor && new PromptsHandler(promptManagerFor);
         if (prompts) publicRouter.registerApi("prompts", prompts);
         if (cliAuthorizer) {

package/src/hosting/handlers/SkillsHandler.ts

@@ -0,0 +1,81 @@
+import {deniesBuild} from "../../auth/TenantRole";
+import {isSkillId, Skill, SkillStore} from "../../data-store/SkillStore";
+import {Request} from "../Request";
+import {RequestHandler} from "../RequestHandler";
+
+/* The tenant's skills: guidance its builders write for the agents that work
+   on it. Anyone in the tenant may read them - an agent acting for a user
+   needs them as much as one acting for a builder - but writing them is a
+   builder's job. Served to people and their agents only, never to deployed
+   apps, which is why this is registered on the public entry point alone. */
+class SkillsHandler implements RequestHandler {
+
+    constructor(private skills : SkillStore) {}
+
+    async handle(request : Request) : Promise<void> {
+        if (request.subresource) return request.notFound();
+        if (request.id) return this.handleSkill(request, request.id);
+        return this.handleCollection(request);
+    }
+
+    private async handleCollection(request : Request) : Promise<void> {
+        if (request.method !== "GET") return request.notFound();
+        return request.reply(200, (await this.skills.list()).map(skill => this.publicSkill(skill)));
+    }
+
+    private async handleSkill(request : Request, id : string) : Promise<void> {
+        switch (request.method) {
+            case "GET": {
+                const skill = await this.skills.get(id);
+                if (! skill) return request.reply(404, { error: `No skill with id "${id}"` });
+                return request.reply(200, this.publicSkill(skill));
+            }
+            case "PUT": {
+                if (deniesBuild(request.user?.tenantRole)) return this.refuse(request);
+                if (! isSkillId(id)) {
+                    return request.reply(400, { error: `"${id}" is not a skill id: lower-case letters, digits and hyphens, up to 50 characters` });
+                }
+                const body = await request.body();
+                const draft = this.draftFrom(body);
+                if (! draft) return request.reply(400, { error: "Expected a body of { title : string, usageHints : string, body : string }, none empty" });
+
+                return request.reply(200, this.publicSkill(await this.skills.save({ id, ...draft })));
+            }
+            case "DELETE": {
+                if (deniesBuild(request.user?.tenantRole)) return this.refuse(request);
+                const removed = await this.skills.remove(id);
+                return removed ? request.reply(204) : request.reply(404, { error: `No skill with id "${id}"` });
+            }
+        }
+        request.notFound();
+    }
+
+    private refuse(request : Request) : void {
+        request.reply(403, { error: "Your role in this tenant cannot manage skills" });
+    }
+
+    private draftFrom(body : unknown) : { title : string, usageHints : string, body : string } | undefined {
+        const fields = body as Record<string, unknown> | undefined;
+        const text = (value : unknown) : string | undefined =>
+            typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+
+        const title = text(fields?.title);
+        const usageHints = text(fields?.usageHints);
+        const content = text(fields?.body);
+        return title && usageHints && content ? { title, usageHints, body: content } : undefined;
+    }
+
+    private publicSkill(skill : Skill) {
+        return {
+            id: skill.id,
+            title: skill.title,
+            usageHints: skill.usageHints,
+            body: skill.body,
+            createdAt: skill.createdAt.toISOString(),
+            updatedAt: skill.updatedAt.toISOString(),
+        };
+    }
+
+}
+
+export { SkillsHandler };

package/src/main.ts

@@ -27,6 +27,7 @@ import {DocGenerator} from "./docs/DocGenerator";
 import {GatewayDocModel} from "./docs/GatewayDocModel";
 import {PostgresAppDocsStore} from "./data-store/PostgresAppDocsStore";
 import {PostgresAppSettingsStore} from "./data-store/PostgresAppSettingsStore";
+import {PostgresSkillStore} from "./data-store/PostgresSkillStore";
 import {PostgresEntitlementStore} from "./data-store/PostgresEntitlementStore";
 import {PostgresUserDirectory} from "./data-store/PostgresUserDirectory";
 import {HttpMembershipService} from "./auth/HttpMembershipService";
@@ -156,7 +157,7 @@ const server = new HostingServer(jobs, queue, registry, buildLayer,
     tokenAuthenticator, process.env.ANBARIC_TENANT, auditRecords, plugins,
     new PostgresJobRunSchedulePersistence(pool), await loadNotifier(process.env.ANBARIC_NOTIFIER_MODULE),
     new PostgresEntitlementStore(pool), new PostgresUserDirectory(pool), memberships,
-    (appId) => new PostgresPromptManager(pool, appId), fileStorageFor, subdomains, billing, appSettings);
+    (appId) => new PostgresPromptManager(pool, appId), fileStorageFor, subdomains, billing, appSettings, new PostgresSkillStore(pool));
 const port = await server.listen(hostingPort);
 const internal = await server.listenInternal(internalPort);