aimeat 3.1.0 → 3.3.0

package/dist/src/routes/admin-organisms.js

@@ -0,0 +1,99 @@
+/**
+ * @file src/routes/admin-organisms.ts
+ * @description The node operator's break-glass over organism ownership. An organism has exactly one
+ *   creator, and every gate below it defers to that one name: an admin cannot remove, demote or
+ *   replace a creator, and only the creator can hand the organism on or delete it. So an organism
+ *   whose creator account becomes unreachable — lost, handed away by mistake, or simply gone — had
+ *   no repair path on any surface, including for the operator whose node it runs on. This is that
+ *   path, and it is deliberately the only cross-account thing here.
+ *
+ *   It does NOT loosen the ordinary gates. The member-facing transfer route still refuses everyone
+ *   but the current creator; this door is separate, gated on the operator ACCOUNT plus an exact
+ *   scope word, and it performs the same three writes through the same service so the two cannot
+ *   drift apart.
+ *
+ * @structure
+ *   - adminOrganismsRouter(config, storage): Router factory
+ *   - GET  /v1/admin/organisms/:id/ownership: read the ownership state before changing it
+ *   - POST /v1/admin/organisms/:id/ownership: install `ghii` as the organism's creator
+ *
+ * @version-history
+ *   v1.0.0 — 2026-08-15 — Initial. Written after an unscoped agent transferred this node's own
+ *     development organism away in a test run and nothing on any surface could put it back.
+ */
+import { Router } from 'express';
+import { requireAuth, requireOperatorPrincipal } from '../auth/middleware.js';
+import { success, error } from '../middleware/envelope.js';
+import { emitChange } from '../services/event-bus.js';
+import { addOrganismOwner, organismOwners } from '../services/organism-ownership.js';
+import { logger } from '../utils/logger.js';
+export function adminOrganismsRouter(config, storage) {
+    const router = Router();
+    /* ── GET /v1/admin/organisms/:id/ownership ──
+     * Who holds this organism, and who else could. Read this before writing: the repair is a
+     * cross-account act, and the operator should see the roster it is about to re-point. */
+    router.get('/v1/admin/organisms/:id/ownership', requireAuth(), requireOperatorPrincipal(storage), async (req, res) => {
+        const id = req.params.id;
+        const organism = await storage.getOrganism(id);
+        if (!organism) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', 'Organism not found'));
+            return;
+        }
+        const members = await storage.listMembers(id);
+        res.json(success(config.nodeId, {
+            id: organism.id,
+            name: organism.name,
+            owners: organismOwners(organism),
+            created_by: organism.createdBy,
+            admins: organism.admins,
+            created_at: organism.createdAt,
+            updated_at: organism.updatedAt,
+            members: members.map(m => ({ ghii: m.ghii, role: m.role, status: m.status, joined_at: m.joinedAt })),
+        }, [{
+                description: 'Add an owner to this organism',
+                method: 'POST',
+                url: `/v1/admin/organisms/${id}/ownership`,
+            }]));
+    });
+    /* ── POST /v1/admin/organisms/:id/ownership — { ghii } ──
+     * Install `ghii` as the creator. The previous creator stays as an admin, and a target who is not
+     * a member is seated as one: the repair case is precisely the organism whose reachable people are
+     * on the outside of it. A BLOCKED target is refused — lifting a block is its own visible act. */
+    router.post('/v1/admin/organisms/:id/ownership', requireAuth(), requireOperatorPrincipal(storage), async (req, res) => {
+        const id = req.params.id;
+        const { ghii } = req.body ?? {};
+        if (!ghii || typeof ghii !== 'string') {
+            res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'Body field "ghii" (the bare owner name to install) is required'));
+            return;
+        }
+        const organism = await storage.getOrganism(id);
+        if (!organism) {
+            res.status(404).json(error(config.nodeId, 'NOT_FOUND', 'Organism not found'));
+            return;
+        }
+        const performedBy = req.auth.sub;
+        const outcome = await addOrganismOwner(storage, config, organism, ghii, {
+            seatNonMember: true,
+            performedBy: `operator repair by ${performedBy}`,
+        });
+        if (!outcome.ok) {
+            res.status(outcome.status).json(error(config.nodeId, outcome.code, outcome.message));
+            return;
+        }
+        // A cross-account write leaves a line in the log whatever else it leaves: this is the one
+        // door on the node where the caller is not the affected account and never was.
+        logger.warn('[operator-organism-repair] owner installed', {
+            organism: id, added: outcome.added, owners: outcome.owners,
+            seated: outcome.membershipCreated, by: performedBy,
+        });
+        res.json(success(config.nodeId, {
+            organism: id,
+            added: outcome.added,
+            owners: outcome.owners,
+            membership_created: outcome.membershipCreated,
+        }));
+        emitChange('organisms');
+    });
+    return router;
+}
+//# sourceMappingURL=admin-organisms.js.map

package/dist/src/routes/admin-organisms.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-organisms.js","sourceRoot":"","sources":["../../../src/routes/admin-organisms.ts"],"names":[],"mappings":"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"}

package/dist/src/routes/admin-usage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @file src/routes/admin-usage.ts
+ * @description The operator's cross-owner usage surface: node-wide reports off the precomputed
+ *   layer, a per-owner drill, the raw call list, and the two maintenance actions (rebuild a rollup
+ *   range, prune the archive). Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHY THE OPERATOR SEES PER-USER DETAIL AT ALL. The operator carries liability for what happens
+ *   on this node, so anything that can become a legal matter has to be visible to them. That is a
+ *   decision about consequences, not about convenience, and it is why this router exposes the raw
+ *   call level rather than only aggregates.
+ *
+ *   AND WHY LOOKING IS ITSELF AN EVENT. GET /v1/admin/usage/calls writes a UsageCall of its own —
+ *   surface 'operator', the inspected owner as the counterparty — which folds into the same rollups
+ *   as everything else. So an owner can see that their activity was inspected, and the operator's
+ *   access history is a first-class record instead of a line in a log file that rotates. No new
+ *   table for it: the same fact in the same stream is the whole reason there is one stream.
+ * @structure
+ *   - GET  /v1/admin/usage/summary        -- any node report, or one owner's slice of it
+ *   - GET  /v1/admin/usage/calls          -- raw call rows (audited)
+ *   - GET  /v1/admin/usage/status         -- fold freshness + hot-window settings
+ *   - POST /v1/admin/usage/rollup/rebuild -- clear a bucket range and re-fold it
+ *   - POST /v1/admin/usage/archive/prune  -- destroy archived rows before an explicit date
+ * @usage
+ *   import { adminUsageRouter } from './routes/admin-usage.js';
+ *   app.use(adminUsageRouter(config, storage));
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: the operator usage surface.
+ */
+import { Router } from 'express';
+import type { AimeatConfig } from '../config.js';
+import type { Storage } from '../storage/interface.js';
+export declare function adminUsageRouter(config: AimeatConfig, storage: Storage): Router;
+//# sourceMappingURL=admin-usage.d.ts.map

package/dist/src/routes/admin-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-usage.d.ts","sourceRoot":"","sources":["../../../src/routes/admin-usage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAA8B,MAAM,yBAAyB,CAAC;AAenF,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,MAAM,CAwL/E"}

package/dist/src/routes/admin-usage.js

@@ -0,0 +1,198 @@
+/**
+ * @file src/routes/admin-usage.ts
+ * @description The operator's cross-owner usage surface: node-wide reports off the precomputed
+ *   layer, a per-owner drill, the raw call list, and the two maintenance actions (rebuild a rollup
+ *   range, prune the archive). Design: docs/internal/telemetria/02-design.md
+ *
+ *   WHY THE OPERATOR SEES PER-USER DETAIL AT ALL. The operator carries liability for what happens
+ *   on this node, so anything that can become a legal matter has to be visible to them. That is a
+ *   decision about consequences, not about convenience, and it is why this router exposes the raw
+ *   call level rather than only aggregates.
+ *
+ *   AND WHY LOOKING IS ITSELF AN EVENT. GET /v1/admin/usage/calls writes a UsageCall of its own —
+ *   surface 'operator', the inspected owner as the counterparty — which folds into the same rollups
+ *   as everything else. So an owner can see that their activity was inspected, and the operator's
+ *   access history is a first-class record instead of a line in a log file that rotates. No new
+ *   table for it: the same fact in the same stream is the whole reason there is one stream.
+ * @structure
+ *   - GET  /v1/admin/usage/summary        -- any node report, or one owner's slice of it
+ *   - GET  /v1/admin/usage/calls          -- raw call rows (audited)
+ *   - GET  /v1/admin/usage/status         -- fold freshness + hot-window settings
+ *   - POST /v1/admin/usage/rollup/rebuild -- clear a bucket range and re-fold it
+ *   - POST /v1/admin/usage/archive/prune  -- destroy archived rows before an explicit date
+ * @usage
+ *   import { adminUsageRouter } from './routes/admin-usage.js';
+ *   app.use(adminUsageRouter(config, storage));
+ * @version-history
+ *   v1.0.0 — 2026-08-14 — Initial: the operator usage surface.
+ */
+import { Router } from 'express';
+import { requireAuth, requireRole } from '../auth/middleware.js';
+import { success, error } from '../middleware/envelope.js';
+import { resolveIdentity, ownerGhiiOf } from '../utils/gaii.js';
+import { readUsageReport, NODE_REPORTS, OWNER_REPORTS, UnknownReportError, usageComputedThrough, dayNDaysAgo, } from '../services/usage/usage-read.js';
+import { rebuildUsageRollup } from '../services/usage/rollup-engine.js';
+import { recordUsageCall, pendingUsageCalls } from '../services/usage/usage-buffer.js';
+import { logger } from '../utils/logger.js';
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+const HOT_DAYS = Number(process.env.AIMEAT_USAGE_HOT_DAYS) || 90;
+export function adminUsageRouter(config, storage) {
+    const router = Router();
+    // ── GET /v1/admin/usage/summary ── node-wide, or scoped to one owner.
+    //
+    // `owner` is what makes this two endpoints in one: absent, it reads a cross-owner cut; present,
+    // it reads the owner-scoped cut for that person. The operator role is the gate on BOTH — there is
+    // no shape of this request a non-operator can reach.
+    router.get('/v1/admin/usage/summary', requireAuth(), requireRole('operator'), async (req, res) => {
+        const report = typeof req.query.report === 'string' ? req.query.report : 'day';
+        const owner = typeof req.query.owner === 'string' && req.query.owner ? req.query.owner : null;
+        const from = typeof req.query.from === 'string' ? req.query.from : dayNDaysAgo(30);
+        const to = typeof req.query.to === 'string' ? req.query.to : dayNDaysAgo(0);
+        if (!ISO_DAY.test(from) || !ISO_DAY.test(to)) {
+            return res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'from and to must be YYYY-MM-DD'));
+        }
+        const grain = req.query.grain === 'hour' ? 'hour' : 'day';
+        try {
+            const data = await readUsageReport(storage, {
+                report,
+                scope: owner ? 'owner' : 'node',
+                // A bare owner name and a full GHII both work; the operator types whichever they have.
+                ownerGhii: owner ? (owner.includes('@') ? owner : `${owner}@${config.nodeId}`) : undefined,
+                from, to, grain,
+                series: req.query.series !== 'false',
+                limit: Number(req.query.limit) || undefined,
+            });
+            res.json(success(config.nodeId, data, [
+                { description: 'Raw calls behind these numbers', method: 'GET', url: '/v1/admin/usage/calls' },
+                { description: 'How fresh the serving layer is', method: 'GET', url: '/v1/admin/usage/status' },
+            ]));
+        }
+        catch (err) {
+            if (err instanceof UnknownReportError) {
+                return res.status(400).json(error(config.nodeId, 'INVALID_INPUT', err.message));
+            }
+            throw err;
+        }
+    });
+    // ── GET /v1/admin/usage/reports ── what may be asked for, in both scopes.
+    router.get('/v1/admin/usage/reports', requireAuth(), requireRole('operator'), (_req, res) => {
+        res.json(success(config.nodeId, {
+            node: Object.keys(NODE_REPORTS),
+            per_owner: Object.keys(OWNER_REPORTS),
+            note: 'Pass ?owner=<name|ghii> to read a per_owner report for one person; omit it for a node report.',
+        }));
+    });
+    // ── GET /v1/admin/usage/calls ── the raw drill. Audited, because this is where an operator reads
+    // one identifiable person's activity.
+    router.get('/v1/admin/usage/calls', requireAuth(), requireRole('operator'), async (req, res) => {
+        const ownerParam = typeof req.query.owner === 'string' && req.query.owner ? req.query.owner : '';
+        const ownerGhii = ownerParam
+            ? (ownerParam.includes('@') ? ownerParam : `${ownerParam}@${config.nodeId}`)
+            : undefined;
+        const filter = {
+            ownerGhii,
+            actorGaii: typeof req.query.actor === 'string' ? req.query.actor : undefined,
+            surface: typeof req.query.surface === 'string' ? req.query.surface : undefined,
+            appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
+            outcome: typeof req.query.outcome === 'string' ? req.query.outcome : undefined,
+            from: typeof req.query.from === 'string' ? req.query.from : undefined,
+            to: typeof req.query.to === 'string' ? req.query.to : undefined,
+            limit: Number(req.query.limit) || 200,
+        };
+        const stored = await storage.listUsageCalls(filter);
+        // Reader and writer share a process, so a call made seconds ago is shown rather than made to
+        // wait out a flush interval. An operator who cannot see the event they are investigating
+        // reasonably concludes the system is not recording it.
+        const buffered = pendingUsageCalls(filter);
+        const calls = [...buffered, ...stored]
+            .sort((a, b) => b.ts.localeCompare(a.ts))
+            .slice(0, Math.min(Math.max(filter.limit, 1), 2000));
+        // The audit row. Written BEFORE the response is sent, so an inspection cannot be performed
+        // and then have its record fail to exist because the operator disconnected.
+        const operatorGhii = ownerGhiiOf(resolveIdentity(req.auth, config.nodeId));
+        recordUsageCall({
+            ownerGhii: operatorGhii,
+            actorGaii: operatorGhii,
+            actorKind: 'operator',
+            surface: 'operator',
+            coordinate: 'usage.calls',
+            counterpartyGhii: ownerGhii ?? '',
+            outcome: 'ok',
+            meta: { inspected: ownerGhii ?? '(all owners)', returned: calls.length, from: filter.from, to: filter.to },
+        });
+        logger.info('admin-usage: operator read raw calls', {
+            operator: operatorGhii, inspected: ownerGhii ?? '(all owners)', returned: calls.length,
+        });
+        res.json(success(config.nodeId, {
+            count: calls.length,
+            hot_window_days: HOT_DAYS,
+            note: `Raw calls are kept ${HOT_DAYS} days here; older ones are in the archive and are not served by this endpoint.`,
+            audited: true,
+            calls,
+        }));
+    });
+    // ── GET /v1/admin/usage/status ── how fresh the serving layer is, and what the windows are.
+    router.get('/v1/admin/usage/status', requireAuth(), requireRole('operator'), async (_req, res) => {
+        const [llm, call, computedThrough] = await Promise.all([
+            storage.getUsageCursor('llm'),
+            storage.getUsageCursor('call'),
+            usageComputedThrough(storage),
+        ]);
+        res.json(success(config.nodeId, {
+            computed_through: computedThrough,
+            streams: {
+                llm: llm ? { last_ts: llm.lastTs, updated_at: llm.updatedAt } : null,
+                call: call ? { last_ts: call.lastTs, updated_at: call.updatedAt } : null,
+            },
+            hot_window_days: HOT_DAYS,
+            hour_rollup_days: Number(process.env.AIMEAT_USAGE_HOUR_ROLLUP_DAYS) || 30,
+        }));
+    });
+    // ── POST /v1/admin/usage/rollup/rebuild ── recompute a bucket range from raw.
+    //
+    // Needed after a new cut is declared (its history is otherwise empty, which on a chart is
+    // indistinguishable from "this was never used"). Clears the range first, because the fold ADDS.
+    router.post('/v1/admin/usage/rollup/rebuild', requireAuth(), requireRole('operator'), async (req, res) => {
+        const from = typeof req.body?.from === 'string' ? req.body.from : '';
+        if (!ISO_DAY.test(from)) {
+            return res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'from is required, as YYYY-MM-DD'));
+        }
+        const hotStart = dayNDaysAgo(HOT_DAYS);
+        if (from < hotStart) {
+            // Refuse before doing anything. A rebuild reaching past the hot window would DELETE rollup
+            // rows it then cannot refill, because the raw behind them is in the archive — turning a
+            // correction into permanent data loss. Named rather than silently clamped, so the operator
+            // decides what they actually want.
+            return res.status(400).json(error(config.nodeId, 'INVALID_INPUT', `Raw data only goes back to ${hotStart} (${HOT_DAYS}-day hot window). Rebuilding from ${from} would delete rollups that cannot be recomputed.`));
+        }
+        const grain = req.body?.grain === 'hour' ? 'hour' : req.body?.grain === 'day' ? 'day' : undefined;
+        const result = await rebuildUsageRollup(storage, { from, grain });
+        logger.info('admin-usage: rollup rebuilt', { from, grain: grain ?? 'all', cleared: result.cleared });
+        res.json(success(config.nodeId, {
+            from, grain: grain ?? 'all',
+            cleared_rows: result.cleared,
+            folded: result.folded,
+        }));
+    });
+    // ── POST /v1/admin/usage/archive/prune ── destroy archived rows before a date.
+    //
+    // Deliberately NOT a scheduled job. These rows are what answers a billing dispute or a legal
+    // question months later, and a cron that quietly destroys them is a cron nobody remembers
+    // approving. The date is required and is never defaulted.
+    router.post('/v1/admin/usage/archive/prune', requireAuth(), requireRole('operator'), async (req, res) => {
+        const before = typeof req.body?.before === 'string' ? req.body.before : '';
+        if (!ISO_DAY.test(before)) {
+            return res.status(400).json(error(config.nodeId, 'INVALID_INPUT', 'before is required, as YYYY-MM-DD. This destroys archived usage records and is never defaulted.'));
+        }
+        if (req.body?.confirm !== true) {
+            return res.status(400).json(error(config.nodeId, 'CONFIRMATION_REQUIRED', `This permanently deletes archived usage records before ${before}. Repeat with confirm: true.`));
+        }
+        const deleted = await storage.pruneUsageArchive(`${before}T00:00:00.000Z`);
+        logger.warn('admin-usage: archive pruned by operator', {
+            before, calls: deleted.usageCalls, events: deleted.usageEvents,
+        });
+        res.json(success(config.nodeId, { before, deleted }));
+    });
+    return router;
+}
+//# sourceMappingURL=admin-usage.js.map

package/dist/src/routes/admin-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"admin-usage.js","sourceRoot":"","sources":["../../../src/routes/admin-usage.ts"],"names":[],"mappings":"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"}

package/dist/src/routes/agent-conventions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-conventions.d.ts","sourceRoot":"","sources":["../../../src/routes/agent-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAsLjD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAqCnE"}
+{"version":3,"file":"agent-conventions.d.ts","sourceRoot":"","sources":["../../../src/routes/agent-conventions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAIjC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAwLjD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAqCnE"}

package/dist/src/routes/agent-conventions.js

@@ -94,7 +94,7 @@ Scopes are chosen by the owner when they approve an agent. A call outside the ap
 
 ## Reference
 
-- Full manual: ${b}/llms.txt
+- Full manual: ${b}/llms-full.txt · Index: ${b}/llms.txt
 - Orientation: ${b}/AGENTS.md · Vocabulary: ${b}/v1/glossary.md
 - Site map: ${b}/sitemap.md · Contract: ${b}/openapi.json
 - Skills published here: ${b}/.well-known/agent-skills/index.json
@@ -111,6 +111,7 @@ Allow: /
 
 # Read freely. Anything public here is public on purpose.
 Allow: /llms.txt
+Allow: /llms-full.txt
 Allow: /sitemap.md
 Allow: /AGENTS.md
 Allow: /v1/glossary.md
@@ -122,7 +123,8 @@ Identity: ${b}/auth.md
 Scopes: memory:read, memory:write, wallet:read, task:write and others, granted per agent
 
 # Machine-readable surfaces
-Manual: ${b}/llms.txt
+Manual: ${b}/llms-full.txt
+Index: ${b}/llms.txt
 Skill: ${b}/skill.md
 OpenAPI: ${b}/openapi.json
 MCP: ${b}/mcp

package/dist/src/routes/agent-conventions.js.map

@@ -1 +1 @@
-{"version":3,"file":"agent-conventions.js","sourceRoot":"","sources":["../../../src/routes/agent-conventions.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"agent-conventions.js","sourceRoot":"","sources":["../../../src/routes/agent-conventions.ts"],"names":[],"mappings":"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"}

package/dist/src/routes/agent-docs.d.ts

@@ -5,10 +5,10 @@
  *   Both are generated from the same sources as everything else — the public-page registry, the
  *   node config — so a page added in one place appears here without a second edit.
  *
- *   These sit alongside, not instead of, the documents we already serve. `sitemap.xml` addresses a
- *   crawler, `llms.txt` is the full builder's manual, and `sitemap.md` is the one-page answer to
- *   "what is here and where do I start" that neither of those gives: 989 OpenAPI operations and a
- *   145 kB manual are both poor first reads.
+ *   These sit alongside the documents we already serve. `sitemap.xml` addresses a crawler,
+ *   `llms-full.txt` is the full builder's manual with `llms.txt` as its index, and `sitemap.md` is
+ *   the one-page answer to "what is here and where do I start" that none of those gives: 989
+ *   OpenAPI operations and a 124 kB manual are both poor first reads.
  *
  * @structure
  *   - agentDocsRouter(config) — mounts the GET endpoints