@hivemagnus/ardent-studio 0.2.1 → 0.4.0

package/dist/server/app.js

@@ -1,7 +1,9 @@
+import { requestContext } from '@hivemagnus/hive-common/hono';
 import { Hono } from 'hono';
 import { ARDENT_STUDIO_API_PREFIX } from '../shared/browser.js';
 import { errorResponse } from './errors.js';
 import { createRouter } from './routing.js';
+import { auditRoutes } from './routes/audit.js';
 import { agentStudioRoutes } from './routes/agent-studio.js';
 import { agentRoutes } from './routes/agents.js';
 import { fileRoutes } from './routes/files.js';
@@ -17,6 +19,9 @@ import { workRoutes } from './routes/work.js';
 /** The ArdentStudio HTTP API under /api/ardentstudio/v1. */
 export function createApp(deps) {
     const app = new Hono();
+    // x-request-id (or x-hive-request-id / x-correlation-id) and W3C traceparent: read, generated
+    // when absent, echoed as x-request-id, and attached to log lines written during the request.
+    app.use('*', requestContext());
     app.use('*', async (c, next) => {
         await next();
         c.header('x-content-type-options', 'nosniff');
@@ -39,6 +44,7 @@ export function createApp(deps) {
     roomRoutes(register, deps);
     workRoutes(register, deps);
     reviewRoutes(register, deps);
+    auditRoutes(register, deps);
     streamRoutes(register, deps);
     return app;
 }

package/dist/server/deps.d.ts

@@ -1,6 +1,6 @@
 import type { AgentDirectory } from '../agents/directory.js';
 import type { OperationRelay } from '../agents/operations.js';
-import type { Authenticator, Principal } from '../auth/oathweave.js';
+import type { Authenticator, Principal } from '../auth/authenticator.js';
 import type { BlobStore } from '../blobs/store.js';
 import type { HiveMemClient } from '../clients/hivemem.js';
 import type { MagnusClient } from '../clients/magnus.js';

package/dist/server/env.d.ts

@@ -1,4 +1,4 @@
-import type { Principal } from '../auth/oathweave.js';
+import type { Principal } from '../auth/authenticator.js';
 export interface AppEnv {
     Variables: {
         principal: Principal | undefined;

package/dist/server/errors.js

@@ -1,3 +1,4 @@
+import { HiveError } from '@hivemagnus/hive-common/errors';
 import { ZodError } from 'zod';
 export class ApiError extends Error {
     status;
@@ -17,6 +18,10 @@ export function errorResponse(c, error, logger) {
     if (error instanceof ApiError) {
         return c.json({ error: { code: error.code, message: error.message, ...(error.details !== undefined ? { details: error.details } : {}) } }, error.status);
     }
+    if (HiveError.is(error) && error.status === 400) {
+        // hive-common feed helpers: a malformed cursor or limit.
+        return c.json({ error: { code: 'VALIDATION_ERROR', message: error.message } }, 400);
+    }
     if (error instanceof ZodError) {
         return c.json({ error: { code: 'VALIDATION_ERROR', message: 'The request is invalid', details: error.issues.map(issue => ({ path: issue.path.join('.'), message: issue.message })) } }, 400);
     }

package/dist/server/routes/audit.d.ts

@@ -0,0 +1,3 @@
+import type { AppDeps } from '../deps.js';
+import type { createRouter } from '../routing.js';
+export declare function auditRoutes(register: ReturnType<typeof createRouter>, deps: AppDeps): void;

package/dist/server/routes/audit.js

@@ -0,0 +1,6 @@
+// The suite audit export (HiveAuditRecord v1). Read by Cindertrace with an Oathweave service
+// token holding ardentstudio:audit:read, or by a linked Studio admin.
+import { exportAuditPage } from '../../audit/export.js';
+export function auditRoutes(register, deps) {
+    register('GET', '/audit/export', c => ({ body: exportAuditPage(deps.store.audit, new URL(c.req.url).searchParams) }));
+}

package/dist/server/routes/health.js

@@ -1,28 +1,52 @@
+// Health runs on the suite's shared readiness helper (@hivemagnus/hive-common/health), but keeps
+// Studio's published body shape: HiveXUI parses it through the browser contract.
+import { readiness } from '@hivemagnus/hive-common/health';
 const CACHE_MS = 10_000;
-const failed = (error) => ({ status: 'unavailable', error: error instanceof Error ? error.message.slice(0, 200) : 'unavailable' });
+/** Above the Magnus client's own 20 s timeout, so the clients' timeouts decide, as before. */
+const CHECK_TIMEOUT_MS = 25_000;
+const toCheck = (report, maxError = 200) => report?.status === 'up'
+    ? { status: 'ok', error: null }
+    : { status: 'unavailable', error: (report?.error ?? 'unavailable').slice(0, maxError) };
 export function healthRoutes(register, deps) {
     let cached;
+    // Liveness never touches dependencies. Its body stays Studio's published `{status:'ok'}`.
     register('GET', '/health/live', () => ({ body: { status: 'ok' } }));
     register('GET', '/health/ready', async (c) => {
         if (!cached || Date.now() - cached.at > CACHE_MS) {
-            let database = { status: 'ok', error: null };
-            try {
-                deps.store.db.prepare('SELECT 1').get();
-            }
-            catch (error) {
-                database = failed(error);
-            }
-            const [agents, hivemem] = await Promise.all([
-                deps.agents.list().then(list => list.magnus.state === 'ok'
-                    ? { magnus: { status: 'ok', error: null }, available: list.available_count }
-                    : { magnus: { status: 'unavailable', error: list.magnus.error }, available: 0 }),
-                deps.hivemem.health().then(() => ({ status: 'ok', error: null }), failed),
-            ]);
-            // Ardent Project Studio requires at least one reachable Ardent agent.
-            const ready = database.status === 'ok' && agents.magnus.status === 'ok' && hivemem.status === 'ok' && agents.available > 0;
+            // One Magnus listing serves both the magnus and the agents checks.
+            const listing = deps.agents.list();
+            listing.catch(() => undefined);
+            const report = await readiness({
+                timeoutMs: CHECK_TIMEOUT_MS,
+                exposeErrors: true,
+                checks: [
+                    { name: 'database', check: () => { deps.store.db.prepare('SELECT 1').get(); } },
+                    { name: 'magnus', check: async () => {
+                            const list = await listing;
+                            if (list.magnus.state !== 'ok')
+                                throw new Error(list.magnus.error ?? 'unavailable');
+                        } },
+                    { name: 'hivemem', check: async () => { await deps.hivemem.health(); } },
+                    // Ardent Project Studio requires at least one reachable Ardent agent.
+                    { name: 'agents', check: async () => {
+                            const list = await listing;
+                            const available = list.magnus.state === 'ok' ? list.available_count : 0;
+                            return { ok: available > 0, details: { available } };
+                        } },
+                ],
+            });
+            const { checks } = report.body;
+            const agents = checks['agents'];
+            const available = typeof agents?.details?.['available'] === 'number' ? agents.details['available'] : 0;
+            const ready = report.status === 200;
             cached = { at: Date.now(), ready, body: {
                     status: ready ? 'ready' : 'not_ready',
-                    checks: { database, magnus: agents.magnus, hivemem, agents: { status: agents.available > 0 ? 'ok' : 'unavailable', available: agents.available } },
+                    checks: {
+                        database: toCheck(checks['database']),
+                        magnus: toCheck(checks['magnus'], 300),
+                        hivemem: toCheck(checks['hivemem']),
+                        agents: { status: agents?.status === 'up' ? 'ok' : 'unavailable', available },
+                    },
                 } };
         }
         c.header('cache-control', 'no-store');

package/dist/server/routes/projects.js

@@ -27,6 +27,11 @@ export function projectRoutes(register, deps) {
             const needing = store.summaries.needingReview();
             projects = projects.filter(project => needing.has(project.id) === (filter.needs_review === 'true'));
         }
+        if (filter.agentRef !== undefined) {
+            // Narrows the list the caller can already read; it never adds a project.
+            const bound = store.team.projectsForAgent(filter.agentRef);
+            projects = projects.filter(project => bound.has(project.id));
+        }
         return { body: { projects: projects.map(summary) } };
     });
     register('POST', '/projects', (_c, { body, principal, idempotencyKey }) => {

package/dist/server/routes/stream.js

@@ -1,5 +1,5 @@
 import { streamSSE } from 'hono/streaming';
-import { STREAM_RECHECK_MS } from '../../auth/oathweave.js';
+import { STREAM_RECHECK_MS } from '../../auth/authenticator.js';
 import { requireProject } from '../deps.js';
 import { bearerToken } from '../routing.js';
 export const HEARTBEAT_MS = 15_000;

package/dist/server/routing.d.ts

@@ -1,5 +1,5 @@
 import type { Context, Hono } from 'hono';
-import { type Authenticator, type Principal } from '../auth/oathweave.js';
+import { type Authenticator, type Principal } from '../auth/authenticator.js';
 import type { Store } from '../db/store.js';
 import { type ArdentStudioBrowserRoute } from '../shared/browser.js';
 import type { AppEnv } from './env.js';
@@ -22,7 +22,10 @@ export declare function routeDefinition(method: ArdentStudioBrowserRoute['method
 /** `/projects/{projectId}` → `/projects/:projectId` */
 export declare function honoPath(path: string): string;
 export declare function bearerToken(c: Context): string | undefined;
-export declare function authenticateRequest(c: Context, authenticate: Authenticator, permissions: readonly string[]): Promise<Principal>;
+export declare function authenticateRequest(c: Context, authenticate: Authenticator, permissions: readonly string[], options?: {
+    accept?: 'user' | 'any';
+    orPermission?: string | undefined;
+}): Promise<Principal>;
 export declare function createRouter(app: Hono<AppEnv>, deps: {
     store: Store;
     authenticate: Authenticator;

package/dist/server/routing.js

@@ -1,7 +1,7 @@
 // Every route is registered from its entry in the browser contract, so the permissions,
 // idempotency rule, query and body schemas the contract publishes are the ones enforced.
 import { createHash } from 'node:crypto';
-import { AccessDenied } from '../auth/oathweave.js';
+import { AccessDenied } from '../auth/authenticator.js';
 import { ARDENT_STUDIO_API_PREFIX, ardentStudioBrowserRoutes, IDEMPOTENCY_HEADER, idempotencyKeySchema } from '../shared/browser.js';
 import { ApiError } from './errors.js';
 export const JSON_BODY_LIMIT = 1024 * 1024;
@@ -20,21 +20,24 @@ export function bearerToken(c) {
     const match = header ? /^Bearer ([A-Za-z0-9._~+/-]+=*)$/.exec(header) : null;
     return match?.[1];
 }
-export async function authenticateRequest(c, authenticate, permissions) {
+export async function authenticateRequest(c, authenticate, permissions, options = {}) {
     const token = bearerToken(c);
     if (!token)
         throw new ApiError(401, 'UNAUTHENTICATED', 'A bearer token is required');
     let principal;
     try {
-        principal = await authenticate(token);
+        principal = await authenticate(token, options.accept === 'any' ? { accept: 'any' } : {});
     }
     catch (error) {
         if (error instanceof AccessDenied)
             throw new ApiError(403, 'NO_ACCOUNT_LINK', 'This identity has no Ardent Project Studio account link');
         throw new ApiError(401, 'UNAUTHENTICATED', 'The bearer token is not valid');
     }
-    const missing = permissions.filter(permission => !principal.permissions.includes(permission));
-    if (missing.length)
+    const holds = (permission) => principal.permissions.includes(permission);
+    const missing = permissions.filter(permission => !holds(permission));
+    // The alternative is for linked people (admins); a service only ever holds SERVICE_PERMISSIONS.
+    const admitted = principal.kind !== 'service' && options.orPermission !== undefined && holds(options.orPermission);
+    if (missing.length && !admitted)
         throw new ApiError(403, 'FORBIDDEN', 'Missing permission', { missing });
     return principal;
 }
@@ -64,7 +67,7 @@ export function createRouter(app, deps) {
     return function register(method, path, handler) {
         const route = routeDefinition(method, path);
         app.on(method, honoPath(path), async (c) => {
-            const principal = route.permissions.length ? await authenticateRequest(c, deps.authenticate, route.permissions) : undefined;
+            const principal = route.permissions.length ? await authenticateRequest(c, deps.authenticate, route.permissions, { accept: route.accept ?? 'user', orPermission: route.orPermission }) : undefined;
             c.set('principal', principal);
             let idempotencyKey;
             if (route.idempotent) {

package/dist/service.d.ts

@@ -1,5 +1,5 @@
 import { type ServerType } from '@hono/node-server';
-import { type Authenticator } from './auth/oathweave.js';
+import { type Authenticator } from './auth/authenticator.js';
 import { ChatterMostClient } from './clients/chattermost.js';
 import { HiveMemClient } from './clients/hivemem.js';
 import { MagnusClient } from './clients/magnus.js';

package/dist/service.js

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { serve } from '@hono/node-server';
 import { AgentDirectory } from './agents/directory.js';
 import { OperationRelay } from './agents/operations.js';
-import { createAuthenticator, createOathweaveVerifier } from './auth/oathweave.js';
+import { createAuthenticator, createOathweaveVerifier } from './auth/authenticator.js';
 import { BlobStore } from './blobs/store.js';
 import { ChatterMostClient } from './clients/chattermost.js';
 import { HiveMemClient } from './clients/hivemem.js';
@@ -44,7 +44,7 @@ export function createService(config, options = {}) {
     const chattermost = config.chattermost ? new ChatterMostClient(config.chattermost.webhookUrl, options.fetch) : undefined;
     const knowledge = new KnowledgeSync(store, blobs, hivemem, logger);
     const agents = new AgentDirectory(magnus, store);
-    const authenticate = options.authenticate ?? createAuthenticator(createOathweaveVerifier({ issuer: config.oathweave.issuer, jwksUrl: config.oathweave.jwksUrl, userinfoUrl: config.oathweave.userinfoUrl }), config.oathweave.identities);
+    const authenticate = options.authenticate ?? createAuthenticator(createOathweaveVerifier({ issuer: config.oathweave.issuer, jwksUrl: config.oathweave.jwksUrl, userinfoUrl: config.oathweave.userinfoUrl, nativeIssuers: config.oathweave.nativeIssuers }), config.oathweave.identities);
     const live = new LiveText(bus);
     const conductor = new Conductor({ store, blobs, magnus, agents, live, logger });
     const importer = attachReview({ store, blobs, magnus, conductor, logger });

package/dist/shared/browser.d.ts

@@ -2,7 +2,7 @@ import { z } from 'zod';
 export declare const ardentStudioBrowserContractVersion = 1;
 export declare const ARDENT_STUDIO_API_PREFIX = "/api/ardentstudio/v1";
 export declare const ARDENT_STUDIO_AUDIENCE = "ardentstudio";
-export declare const ARDENT_STUDIO_PERMISSIONS: readonly ["ardentstudio:projects:read", "ardentstudio:projects:write", "ardentstudio:templates:read", "ardentstudio:templates:write", "ardentstudio:review:write", "ardentstudio:agents:admin"];
+export declare const ARDENT_STUDIO_PERMISSIONS: readonly ["ardentstudio:projects:read", "ardentstudio:projects:write", "ardentstudio:templates:read", "ardentstudio:templates:write", "ardentstudio:review:write", "ardentstudio:agents:admin", "ardentstudio:audit:read"];
 export declare const permissionSchema: z.ZodEnum<{
     "ardentstudio:projects:read": "ardentstudio:projects:read";
     "ardentstudio:projects:write": "ardentstudio:projects:write";
@@ -10,6 +10,7 @@ export declare const permissionSchema: z.ZodEnum<{
     "ardentstudio:templates:write": "ardentstudio:templates:write";
     "ardentstudio:review:write": "ardentstudio:review:write";
     "ardentstudio:agents:admin": "ardentstudio:agents:admin";
+    "ardentstudio:audit:read": "ardentstudio:audit:read";
 }>;
 export type ArdentStudioPermission = z.infer<typeof permissionSchema>;
 /** Every mutation sends this header. A repeated key replays the first answer; a different request with the same key is a 409. */
@@ -337,6 +338,7 @@ export declare const listProjectsQuerySchema: z.ZodObject<{
         true: "true";
         false: "false";
     }>>;
+    agentRef: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const listProjectsResponseSchema: z.ZodObject<{
     projects: z.ZodArray<z.ZodObject<{
@@ -5802,6 +5804,86 @@ export declare const readyResponseSchema: z.ZodObject<{
         }, z.core.$strip>;
     }, z.core.$strip>;
 }, z.core.$strip>;
+export declare const hiveAuditRecordSchema: z.ZodObject<{
+    id: z.ZodString;
+    product: z.ZodEnum<{
+        ardentstudio: "ardentstudio";
+        hivemem: "hivemem";
+        hiveskills: "hiveskills";
+        embermend: "embermend";
+    }>;
+    occurredAt: z.ZodISODateTime;
+    action: z.ZodString;
+    outcome: z.ZodEnum<{
+        success: "success";
+        failure: "failure";
+    }>;
+    actor: z.ZodObject<{
+        type: z.ZodEnum<{
+            agent: "agent";
+            user: "user";
+            system: "system";
+            service: "service";
+        }>;
+        id: z.ZodString;
+        issuer: z.ZodOptional<z.ZodString>;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    target: z.ZodOptional<z.ZodObject<{
+        type: z.ZodOptional<z.ZodString>;
+        id: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    subject: z.ZodOptional<z.ZodObject<{
+        actorId: z.ZodOptional<z.ZodString>;
+        agentRef: z.ZodOptional<z.ZodString>;
+        nodeId: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    details: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+}, z.core.$strict>;
+export type HiveAuditRecord = z.infer<typeof hiveAuditRecordSchema>;
+export declare const auditExportQuerySchema: z.ZodObject<{
+    after: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const auditExportResponseSchema: z.ZodObject<{
+    data: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        product: z.ZodEnum<{
+            ardentstudio: "ardentstudio";
+            hivemem: "hivemem";
+            hiveskills: "hiveskills";
+            embermend: "embermend";
+        }>;
+        occurredAt: z.ZodISODateTime;
+        action: z.ZodString;
+        outcome: z.ZodEnum<{
+            success: "success";
+            failure: "failure";
+        }>;
+        actor: z.ZodObject<{
+            type: z.ZodEnum<{
+                agent: "agent";
+                user: "user";
+                system: "system";
+                service: "service";
+            }>;
+            id: z.ZodString;
+            issuer: z.ZodOptional<z.ZodString>;
+            displayName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        target: z.ZodOptional<z.ZodObject<{
+            type: z.ZodOptional<z.ZodString>;
+            id: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        subject: z.ZodOptional<z.ZodObject<{
+            actorId: z.ZodOptional<z.ZodString>;
+            agentRef: z.ZodOptional<z.ZodString>;
+            nodeId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+        details: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>>;
+    }, z.core.$strict>>;
+    nextCursor: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
 export interface ArdentStudioBrowserRoute {
     method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE';
     /** Relative to ARDENT_STUDIO_API_PREFIX, with `{name}` for each path parameter. */
@@ -5814,6 +5896,10 @@ export interface ArdentStudioBrowserRoute {
     response: z.ZodType | null;
     /** Every listed permission is required. An empty list means no authentication. */
     permissions: readonly ArdentStudioPermission[];
+    /** A linked person holding this permission passes instead of `permissions` (Studio admins). */
+    orPermission?: ArdentStudioPermission;
+    /** `any` also accepts Oathweave service (client-credentials) tokens; the default is people only. */
+    accept?: 'user' | 'any';
     /** The route requires the x-idempotency-key header. */
     idempotent: boolean;
     successStatus?: 201;

package/dist/shared/browser.js

@@ -15,6 +15,7 @@ export const ARDENT_STUDIO_PERMISSIONS = [
     'ardentstudio:templates:write',
     'ardentstudio:review:write',
     'ardentstudio:agents:admin',
+    'ardentstudio:audit:read',
 ];
 export const permissionSchema = z.enum(ARDENT_STUDIO_PERMISSIONS);
 /** Every mutation sends this header. A repeated key replays the first answer; a different request with the same key is a 409. */
@@ -149,6 +150,8 @@ export const listProjectsQuerySchema = z.object({
     q: z.string().trim().max(200).optional(),
     /** true: only projects with review_pending > 0. */
     needs_review: z.enum(['true', 'false']).optional(),
+    /** Only projects where this agent (<magnusNodeId>~<profile>) is bound to a role in the published or the draft team. */
+    agentRef: agentRefSchema.optional(),
 });
 export const listProjectsResponseSchema = z.object({ projects: z.array(projectSummarySchema) });
 export const projectResponseSchema = projectSchema;
@@ -1211,18 +1214,52 @@ export const readyResponseSchema = z.object({
         agents: z.object({ status: z.enum(['ok', 'unavailable']), available: z.number().int() }),
     }),
 });
+// ── Audit export (HiveAuditRecord v1, shared across the suite) ──
+/** The suite-wide audit record. Every product serves the same shape so one collector can parse them all. */
+const auditScalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const hiveAuditRecordSchema = z.object({
+    id: z.string().regex(/^(hivemem|hiveskills|ardentstudio|embermend):audit:[A-Za-z0-9._:-]{1,200}$/),
+    product: z.enum(['hivemem', 'hiveskills', 'ardentstudio', 'embermend']),
+    occurredAt: z.iso.datetime(),
+    action: z.string().regex(/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$/).max(128),
+    outcome: z.enum(['success', 'failure']),
+    actor: z.object({
+        type: z.enum(['user', 'service', 'agent', 'system']),
+        id: z.string().min(1).max(256),
+        issuer: z.string().max(512).optional(),
+        displayName: z.string().max(256).optional(),
+    }).strict(),
+    /** Omitted when empty. */
+    target: z.object({ type: z.string().max(64).optional(), id: z.string().max(256).optional() }).strict().optional(),
+    /** Omitted when empty. */
+    subject: z.object({ actorId: z.string().max(256).optional(), agentRef: z.string().max(257).optional(), nodeId: z.string().max(128).optional() }).strict().optional(),
+    /** Flat scalars, at most 4 KB serialized, already redacted. Never secrets, memory content, prompts or file contents. */
+    details: z.record(z.string(), auditScalarSchema),
+}).strict();
+export const auditExportQuerySchema = z.object({
+    /** The opaque nextCursor of the previous page. Omit for the oldest record. */
+    after: z.string().max(512).optional(),
+    /** 1 to 200; default 100. Larger values are clamped to 200. */
+    limit: z.string().regex(/^\d{1,6}$/).optional(),
+});
+export const auditExportResponseSchema = z.object({
+    data: z.array(hiveAuditRecordSchema),
+    /** The last record's cursor whenever `data` is not empty, even on the last page; null only when `data` is empty (caught up). Send it as `after` to read on. */
+    nextCursor: z.string().nullable(),
+});
 const READ = ['ardentstudio:projects:read'];
 const WRITE = ['ardentstudio:projects:write'];
 const TEMPLATES_READ = ['ardentstudio:templates:read'];
 const TEMPLATES_WRITE = ['ardentstudio:templates:write'];
 const REVIEW = ['ardentstudio:review:write'];
 const AGENTS_ADMIN = ['ardentstudio:agents:admin'];
+const AUDIT_READ = ['ardentstudio:audit:read'];
 export const ardentStudioBrowserRoutes = [
     // Health
     { method: 'GET', path: '/health/live', response: liveResponseSchema, permissions: [], idempotent: false },
     { method: 'GET', path: '/health/ready', response: readyResponseSchema, permissions: [], idempotent: false, note: 'Answers 503 with the same body when not ready. Checks are cached for 10 seconds.' },
     // Projects
-    { method: 'GET', path: '/projects', query: listProjectsQuerySchema, response: listProjectsResponseSchema, permissions: READ, idempotent: false, note: 'q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0.' },
+    { method: 'GET', path: '/projects', query: listProjectsQuerySchema, response: listProjectsResponseSchema, permissions: READ, idempotent: false, note: 'q matches name, brief and tags. needs_review=true keeps projects with review_pending > 0. agentRef keeps projects where that agent is bound to a role in the published or the draft team; an agent with no roles gets an empty list. 400 VALIDATION_ERROR for a malformed agentRef.' },
     { method: 'POST', path: '/projects', requestBody: 'json', request: createProjectRequestSchema, response: projectResponseSchema, permissions: WRITE, idempotent: true, successStatus: 201, note: 'Creates the project HiveMem workspace; when HiveMem is unavailable hivemem.state stays pending and is retried.' },
     { method: 'GET', path: '/projects/{projectId}', response: projectResponseSchema, permissions: READ, idempotent: false },
     { method: 'PATCH', path: '/projects/{projectId}', requestBody: 'json', request: updateProjectRequestSchema, response: projectResponseSchema, permissions: WRITE, idempotent: true, note: 'An archived project is read-only (409) except last_area.' },
@@ -1309,6 +1346,9 @@ export const ardentStudioBrowserRoutes = [
     { method: 'POST', path: '/projects/{projectId}/exports', requestBody: 'json', request: createExportRequestSchema, response: exportResponseSchema, permissions: REVIEW, idempotent: true, successStatus: 201, note: 'A zip of the final revisions with manifest.json (Ardent manifest fields, review status and decisions). Deliverables without a final revision are listed as excluded; none at all answers 409 NOTHING_FINAL.' },
     { method: 'GET', path: '/files/{fileId}/docx', response: docxDocumentResponseSchema, permissions: READ, idempotent: false, note: 'Answers 501 DOCX_CONVERTER_UNAVAILABLE until the canvas Word codec package is installed.' },
     { method: 'GET', path: '/revisions/{revisionId}/docx', response: docxDocumentResponseSchema, permissions: READ, idempotent: false, note: 'Answers 501 DOCX_CONVERTER_UNAVAILABLE until the canvas Word codec package is installed.' },
+    // Audit
+    { method: 'GET', path: '/audit/export', query: auditExportQuerySchema, response: auditExportResponseSchema, permissions: AUDIT_READ, orPermission: 'ardentstudio:agents:admin', accept: 'any', idempotent: false,
+        note: 'Every audit record, oldest first, as HiveAuditRecord v1, keyset-paged on the record id. Accepts an Oathweave service token with ardentstudio:audit:read (no account link needed; native-issuer service tokens too when OATHWEAVE_NATIVE_ISSUERS lists the issuer), or a linked person with ardentstudio:audit:read or ardentstudio:agents:admin. 400 for a malformed cursor or limit. nextCursor is the last record\'s cursor whenever data is not empty, and null only when data is empty (caught up).' },
     // Stream
     {
         method: 'GET', path: '/projects/{projectId}/stream', query: streamQuerySchema, response: null, permissions: READ, idempotent: false,