@aphexcms/cms-core 9.6.0 → 9.8.0

package/dist/server/api/routes/agent-chat.js

@@ -0,0 +1,223 @@
+import { Hono } from 'hono';
+import { streamSSE } from 'hono/streaming';
+import { z } from 'zod';
+import { agentChatRequest } from '../../../api/schemas/agent-chat.js';
+import { recordWorkspaceOperationRequest } from '../../../api/schemas/agent-operations.js';
+import { authToContext } from '../../../local-api/auth-helpers.js';
+import { resolveAgentTools } from '../../../mcp/tools.js';
+import { runAgentTurn } from '../../../ai/run-agent-turn.js';
+import { DEFAULT_AGENT_SYSTEM_PROMPT } from '../../../ai/default-system-prompt.js';
+import { cmsLogger } from '../../../utils/logger.js';
+const SUMMARY_MAX_LENGTH = 200;
+// A mutating tool's `data` is `unknown` at this boundary (AgentToolResult.data) — every tool
+// returns a different shape (list_collections -> {collections}, upload_asset -> {asset, ...},
+// document tools -> {document, validation}), and this route dispatches by name against
+// whatever's registered, including plugin-contributed tools it's never seen at compile time.
+// There's no static type to give it, so the id is pulled out via a runtime-validated parse
+// (the same idiom `run-agent-turn.ts` already uses for tool arguments) rather than an `as`
+// cast asserting a shape without checking it.
+const toolResultWithDocumentId = z.object({ document: z.object({ id: z.string() }) });
+/** `create_document` has no `id` argument (nothing to reference before it exists) — its new
+ * id only shows up in the result. Falls back to that when the args don't have one, so a
+ * create is still attributable to a document instead of being silently dropped. */
+function resolveDocumentId(args, data) {
+    if (typeof args.id === 'string')
+        return args.id;
+    const parsed = toolResultWithDocumentId.safeParse(data);
+    return parsed.success ? parsed.data.document.id : null;
+}
+/**
+ * Best-effort audit record for one mutating tool call — looks up the two most recent
+ * document-version rows to capture `versionBefore`/`versionAfter` (the version an undo would
+ * restore to, and the one this write produced), then records the operation. Never throws: a
+ * failure to record the audit trail must never break the actual tool call or the SSE stream.
+ * Exported for unit testing — not part of the route's own public surface.
+ */
+export async function recordMutatingOperation(aphexCMS, context, changeSetId, toolName, args, success, error, data) {
+    const collection = typeof args.collection === 'string' ? args.collection : null;
+    // `resolveDocumentId` checks `args.id` first, so a failed update_document/publish_document
+    // (which does have `args.id`) is still attributable — it only falls through to parsing
+    // `data` for the rare case for `create_document`, whose result won't parse on failure anyway.
+    const documentId = resolveDocumentId(args, data);
+    if (!collection || !documentId)
+        return;
+    try {
+        const { databaseAdapter, localAPI } = aphexCMS;
+        const { versions } = await localAPI.versionService.listVersions(databaseAdapter, context.organizationId, documentId, { limit: 2 });
+        const [versionAfter, versionBefore] = versions;
+        await databaseAdapter.recordOperation({
+            changeSetId,
+            organizationId: context.organizationId,
+            collection,
+            documentId,
+            toolName,
+            arguments: args,
+            success,
+            error,
+            versionBefore: versionBefore?.versionNumber ?? null,
+            versionAfter: versionAfter?.versionNumber ?? null
+        });
+    }
+    catch (err) {
+        cmsLogger.error('[agent-chat] failed to record agent operation (continuing):', err);
+    }
+}
+export const agentChatRouter = new Hono();
+/**
+ * POST /api/agent/chat — the in-admin agent's streaming chat endpoint (Milestone 2 item 5
+ * of references/content-copilot-phase-1-plan.md). Stateless per call: the browser sends
+ * the full running conversation each time (conversation persistence is a separate,
+ * not-yet-built piece — see the plan). Requires an authenticated session; individual tool
+ * calls are separately capability-gated by `resolveAgentTools`/each tool's own checks —
+ * this endpoint is a dumb transport over the same tool-execution service MCP uses, not an
+ * additional authorization layer.
+ *
+ * 404s (rather than 401) when no `aiProvider` is configured, so the route doesn't exist as
+ * a surface at all on an instance that hasn't opted in — same "don't advertise an unset
+ * feature" posture as `workers-run.ts`'s worker secret gate.
+ *
+ * Also records an audit/undo trail (`cms_agent_change_sets`/`cms_agent_operations`): a
+ * change-set row is created eagerly for every turn (so token usage is captured even for a
+ * pure Q&A turn with no mutations), and every mutating tool call gets an operation row. All
+ * of this recording is best-effort — see `recordMutatingOperation` above and the try/catch
+ * around change-set creation/completion below — a failure here must never break the chat.
+ */
+agentChatRouter.post('/chat', async (c) => {
+    const { aphexCMS, auth } = c.var;
+    const { aiProvider, agentModel } = aphexCMS.config;
+    const { databaseAdapter } = aphexCMS;
+    if (!aiProvider)
+        return c.json({ success: false, error: 'Not found' }, 404);
+    if (!auth)
+        return c.json({ success: false, error: 'Unauthorized' }, 401);
+    if (!agentModel) {
+        return c.json({ success: false, error: 'Server misconfigured: no agentModel configured for aiProvider' }, 501);
+    }
+    const body = await c.req.json().catch(() => null);
+    const parsed = agentChatRequest.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ success: false, error: 'Invalid request', issues: parsed.error.issues }, 400);
+    }
+    const context = authToContext(auth);
+    const tools = resolveAgentTools({ aphexCMS, context }, { documentContext: parsed.data.documentContext });
+    const toolsByName = new Map(tools.map((t) => [t.definition.name, t]));
+    const model = parsed.data.model ?? agentModel;
+    const abortController = new AbortController();
+    // A turn paused for a workspace tool resumes as a brand-new HTTP request (see
+    // `types/agent-stream.ts`) — the client echoes back the change-set id from the leg that
+    // paused so every leg of one logical turn records against the same row, instead of a
+    // fresh `cms_agent_change_sets` row per leg.
+    let changeSetId = parsed.data.changeSetId ?? null;
+    if (!changeSetId) {
+        try {
+            const firstUserMessage = parsed.data.messages.find((m) => m.role === 'user')?.content ?? '';
+            const changeSet = await databaseAdapter.createChangeSet({
+                organizationId: context.organizationId,
+                createdBy: context.user?.id ?? null,
+                summary: firstUserMessage.slice(0, SUMMARY_MAX_LENGTH) || null,
+                provider: aiProvider.name,
+                model
+            });
+            changeSetId = changeSet.id;
+        }
+        catch (err) {
+            cmsLogger.error('[agent-chat] failed to create change-set (continuing without one):', err);
+        }
+    }
+    return streamSSE(c, async (stream) => {
+        c.req.raw.signal.addEventListener('abort', () => abortController.abort());
+        let promptTokens = parsed.data.priorUsage?.promptTokens ?? 0;
+        let completionTokens = parsed.data.priorUsage?.completionTokens ?? 0;
+        let turnFailed = false;
+        let turnPaused = false;
+        // toolCall args aren't repeated on the matching toolResult event, so stash them here
+        // to correlate the two when it's time to record a mutating operation.
+        const argsByToolCallId = new Map();
+        try {
+            for await (const event of runAgentTurn({
+                aiProvider,
+                model,
+                messages: parsed.data.messages,
+                tools,
+                toolContext: { aphexCMS, context },
+                systemPrompt: aphexCMS.config.agentSystemPrompt ?? DEFAULT_AGENT_SYSTEM_PROMPT,
+                signal: abortController.signal
+            })) {
+                if (event.type === 'usage') {
+                    promptTokens += event.promptTokens;
+                    completionTokens += event.completionTokens;
+                }
+                else if (event.type === 'toolCall') {
+                    argsByToolCallId.set(event.toolCallId, event.arguments);
+                }
+                else if (event.type === 'toolResult' && changeSetId) {
+                    const tool = toolsByName.get(event.name);
+                    const args = argsByToolCallId.get(event.toolCallId);
+                    if (tool?.definition.mutates && args) {
+                        await recordMutatingOperation(aphexCMS, context, changeSetId, event.name, args, event.success, event.error, event.data);
+                    }
+                }
+                else if (event.type === 'error') {
+                    turnFailed = true;
+                }
+                if (event.type === 'done') {
+                    event.changeSetId = changeSetId;
+                    if (event.finishReason === 'awaiting_workspace_tool')
+                        turnPaused = true;
+                }
+                await stream.writeSSE({ data: JSON.stringify(event) });
+            }
+        }
+        catch (err) {
+            turnFailed = true;
+            cmsLogger.error('[agent-chat] turn failed:', err);
+            await stream.writeSSE({
+                data: JSON.stringify({
+                    type: 'error',
+                    message: err instanceof Error ? err.message : 'Unknown error'
+                })
+            });
+        }
+        finally {
+            // A paused leg isn't the end of the turn — the client resumes with the same
+            // changeSetId, and only the truly-terminal leg should mark the change-set complete.
+            if (changeSetId && !turnPaused) {
+                try {
+                    await databaseAdapter.completeChangeSet(context.organizationId, changeSetId, {
+                        status: turnFailed ? 'failed' : 'completed',
+                        promptTokens,
+                        completionTokens
+                    });
+                }
+                catch (err) {
+                    cmsLogger.error('[agent-chat] failed to complete change-set (continuing):', err);
+                }
+            }
+        }
+    });
+});
+/**
+ * POST /api/agent/operations — records an audit/undo row for a tool the *client* executed
+ * against a live `DocumentWorkspace` (the `content_patch_fields`/`content_save_draft` bridge
+ * tools — see `ai/content-workspace-tools.ts`). `agent-chat.ts`'s own `recordMutatingOperation`
+ * call above only sees tool results resolved server-side inside `runAgentTurn`'s loop, so a
+ * workspace tool's result — resolved client-side after a paused turn — needs this separate
+ * path to reach the same `cms_agent_change_sets`/`cms_agent_operations` tables. Same
+ * session-authenticated posture as `/chat`; not itself a mutation of document data (the
+ * client already made that call directly via the normal document API), purely bookkeeping.
+ */
+agentChatRouter.post('/operations', async (c) => {
+    const { aphexCMS, auth } = c.var;
+    if (!aphexCMS.config.aiProvider)
+        return c.json({ success: false, error: 'Not found' }, 404);
+    if (!auth)
+        return c.json({ success: false, error: 'Unauthorized' }, 401);
+    const body = await c.req.json().catch(() => null);
+    const parsed = recordWorkspaceOperationRequest.safeParse(body);
+    if (!parsed.success) {
+        return c.json({ success: false, error: 'Invalid request', issues: parsed.error.issues }, 400);
+    }
+    const context = authToContext(auth);
+    await recordMutatingOperation(aphexCMS, context, parsed.data.changeSetId, parsed.data.toolName, { collection: parsed.data.collection, id: parsed.data.id, ...parsed.data.arguments }, parsed.data.success, parsed.data.error, parsed.data.data);
+    return c.json({ success: true });
+});

package/dist/server/api/routes/document-versions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"document-versions.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/document-versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,QAAQ,CAiK/C,CAAC"}
+{"version":3,"file":"document-versions.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/document-versions.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,QAAQ,CAsL/C,CAAC"}

package/dist/server/api/routes/document-versions.js

@@ -3,7 +3,8 @@ import { zValidator } from '@hono/zod-validator';
 import { authToContext } from '../../../local-api/auth-helpers.js';
 import { cmsLogger } from '../../../utils/logger.js';
 import { hasCapability } from '../../../types/capabilities.js';
-import { listVersionsQuery } from '../../../api/schemas/documents.js';
+import { RevisionConflictError } from '../../../db/interfaces.js';
+import { listVersionsQuery, restoreVersionRequest } from '../../../api/schemas/documents.js';
 export const documentVersionsRouter = new Hono()
     .get('/:id/versions', zValidator('query', listVersionsQuery, (result, c) => {
     if (!result.success) {
@@ -103,7 +104,12 @@ export const documentVersionsRouter = new Hono()
         if (isNaN(versionNumber)) {
             return c.json({ success: false, error: 'Version must be a number' }, 400);
         }
-        const document = await localAPI.versionService.restoreVersion(databaseAdapter, context.organizationId, id, versionNumber, context.user?.id);
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = restoreVersionRequest.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ success: false, error: 'Invalid request', issues: parsed.error.issues }, 400);
+        }
+        const document = await localAPI.versionService.restoreVersion(databaseAdapter, context.organizationId, id, versionNumber, context.user?.id, parsed.data.expectedRevision);
         if (!document) {
             return c.json({ success: false, error: 'Version not found or restore failed' }, 404);
         }
@@ -115,6 +121,14 @@ export const documentVersionsRouter = new Hono()
     }
     catch (error) {
         cmsLogger.error('Failed to restore document version:', error);
+        if (error instanceof RevisionConflictError) {
+            return c.json({
+                success: false,
+                error: 'Conflict',
+                message: error.message,
+                currentRevision: error.currentRevision
+            }, 409);
+        }
         return c.json({ success: false, error: 'Failed to restore version' }, 500);
     }
 });

package/dist/server/api/routes/documents-by-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents-by-id.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CAqN5C,CAAC"}
+{"version":3,"file":"documents-by-id.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAQ5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CAiO5C,CAAC"}

package/dist/server/api/routes/documents-by-id.js

@@ -3,6 +3,7 @@ import { zValidator } from '@hono/zod-validator';
 import { authToContext } from '../../../local-api/auth-helpers.js';
 import { PermissionError } from '../../../local-api/permissions.js';
 import { SingletonOperationError } from '../../../local-api/collection-api.js';
+import { RevisionConflictError } from '../../../db/interfaces.js';
 import { cmsLogger } from '../../../utils/logger.js';
 import { updateDocumentRequest } from '../../../api/schemas/documents.js';
 export const documentsByIdRouter = new Hono()
@@ -82,7 +83,8 @@ export const documentsByIdRouter = new Hono()
             }, 400);
         }
         const result = await collection.update(context, id, documentData, {
-            publish: shouldPublish
+            publish: shouldPublish,
+            expectedRevision: parsed.expectedRevision
         });
         if (!result) {
             return c.json({ success: false, error: 'Document not found' }, 404);
@@ -98,6 +100,14 @@ export const documentsByIdRouter = new Hono()
         if (error instanceof PermissionError) {
             return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
         }
+        if (error instanceof RevisionConflictError) {
+            return c.json({
+                success: false,
+                error: 'Conflict',
+                message: error.message,
+                currentRevision: error.currentRevision
+            }, 409);
+        }
         if (error instanceof Error && error.message.includes('validation errors')) {
             return c.json({ success: false, error: 'Validation failed', message: error.message }, 400);
         }

package/dist/server/api/routes/documents-publish.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents-publish.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents-publish.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAI5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,QAAQ,CA4J/C,CAAC"}
+{"version":3,"file":"documents-publish.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents-publish.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAU5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,sBAAsB,EAAE,IAAI,CAAC,QAAQ,CAkU/C,CAAC"}

package/dist/server/api/routes/documents-publish.js

@@ -1,8 +1,119 @@
 import { Hono } from 'hono';
 import { authToContext } from '../../../local-api/auth-helpers.js';
 import { PermissionError } from '../../../local-api/permissions.js';
+import { RevisionConflictError } from '../../../db/interfaces.js';
 import { cmsLogger } from '../../../utils/logger.js';
+import { scheduleDocumentRequest, publishDocumentRequest, unpublishDocumentRequest } from '../../../api/schemas/documents.js';
 export const documentsPublishRouter = new Hono()
+    .post('/:id/schedule', async (c) => {
+    try {
+        const { localAPI } = c.var.aphexCMS;
+        const context = authToContext(c.var.auth);
+        const id = c.req.param('id');
+        if (!id) {
+            return c.json({ success: false, error: 'Missing document ID' }, 400);
+        }
+        const parsed = scheduleDocumentRequest.safeParse(await c.req.json().catch(() => null));
+        if (!parsed.success) {
+            return c.json({ success: false, error: 'Invalid request', issues: parsed.error.issues }, 400);
+        }
+        const { action, runAt } = parsed.data;
+        const found = await localAPI.findDocumentById(context, id);
+        if (!found) {
+            return c.json({ success: false, error: 'Document not found' }, 404);
+        }
+        const collection = localAPI.getCollection(found.type);
+        if (!collection) {
+            return c.json({
+                success: false,
+                error: 'Invalid document type',
+                message: `Collection '${found.type}' not found`
+            }, 400);
+        }
+        const when = new Date(runAt);
+        const job = action === 'publish'
+            ? await collection.schedulePublish(context, id, when)
+            : await collection.scheduleUnpublish(context, id, when);
+        return c.json({
+            success: true,
+            data: { jobId: job.id, type: job.type, runAt: job.runAt.toISOString(), status: job.status },
+            message: `Document ${action} scheduled for ${job.runAt.toISOString()}`
+        });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to schedule document action:', error);
+        if (error instanceof PermissionError) {
+            return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
+        }
+        return c.json({
+            success: false,
+            error: 'Failed to schedule document action',
+            message: error instanceof Error ? error.message : 'Unknown error'
+        }, 500);
+    }
+})
+    .get('/:id/schedule', async (c) => {
+    // Pending scheduled publish/unpublish for this document — powers the editor's
+    // "scheduled for …" indicator. Read-gated inside the collection.
+    try {
+        const { localAPI } = c.var.aphexCMS;
+        const context = authToContext(c.var.auth);
+        const id = c.req.param('id');
+        if (!id)
+            return c.json({ success: false, error: 'Missing document ID' }, 400);
+        const found = await localAPI.findDocumentById(context, id);
+        if (!found)
+            return c.json({ success: false, error: 'Document not found' }, 404);
+        const collection = localAPI.getCollection(found.type);
+        if (!collection) {
+            return c.json({ success: false, error: 'Invalid document type' }, 400);
+        }
+        const jobs = await collection.getScheduled(context, id);
+        return c.json({
+            success: true,
+            data: jobs.map((j) => ({
+                jobId: j.id,
+                type: j.type,
+                runAt: j.runAt.toISOString(),
+                status: j.status,
+                createdAt: j.createdAt.toISOString()
+            }))
+        });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to read document schedule:', error);
+        if (error instanceof PermissionError) {
+            return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
+        }
+        return c.json({ success: false, error: 'Failed to read document schedule' }, 500);
+    }
+})
+    .delete('/:id/schedule', async (c) => {
+    // Cancel the pending schedule for this document.
+    try {
+        const { localAPI } = c.var.aphexCMS;
+        const context = authToContext(c.var.auth);
+        const id = c.req.param('id');
+        if (!id)
+            return c.json({ success: false, error: 'Missing document ID' }, 400);
+        const found = await localAPI.findDocumentById(context, id);
+        if (!found)
+            return c.json({ success: false, error: 'Document not found' }, 404);
+        const collection = localAPI.getCollection(found.type);
+        if (!collection) {
+            return c.json({ success: false, error: 'Invalid document type' }, 400);
+        }
+        const cancelled = await collection.cancelScheduled(context, id);
+        return c.json({ success: true, data: { cancelled } });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to cancel document schedule:', error);
+        if (error instanceof PermissionError) {
+            return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
+        }
+        return c.json({ success: false, error: 'Failed to cancel document schedule' }, 500);
+    }
+})
     .post('/:id/publish', async (c) => {
     try {
         const { localAPI } = c.var.aphexCMS;
@@ -31,7 +142,16 @@ export const documentsPublishRouter = new Hono()
                 message: `Collection '${found.type}' not found`
             }, 400);
         }
-        const publishedDocument = await collection.publish(context, id);
+        // Body is optional — a bare POST with no body is still valid, only
+        // carries the CAS guard when the caller has one to send.
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = publishDocumentRequest.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ success: false, error: 'Invalid request', issues: parsed.error.issues }, 400);
+        }
+        const publishedDocument = await collection.publish(context, id, {
+            expectedRevision: parsed.data.expectedRevision
+        });
         if (!publishedDocument) {
             return c.json({
                 success: false,
@@ -50,6 +170,14 @@ export const documentsPublishRouter = new Hono()
         if (error instanceof PermissionError) {
             return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
         }
+        if (error instanceof RevisionConflictError) {
+            return c.json({
+                success: false,
+                error: 'Conflict',
+                message: error.message,
+                currentRevision: error.currentRevision
+            }, 409);
+        }
         if (error instanceof Error && error.message.includes('validation errors')) {
             return c.json({
                 success: false,
@@ -92,7 +220,14 @@ export const documentsPublishRouter = new Hono()
                 message: `Collection '${found.type}' not found`
             }, 400);
         }
-        const unpublishedDocument = await collection.unpublish(context, id);
+        const body = await c.req.json().catch(() => ({}));
+        const parsed = unpublishDocumentRequest.safeParse(body);
+        if (!parsed.success) {
+            return c.json({ success: false, error: 'Invalid request', issues: parsed.error.issues }, 400);
+        }
+        const unpublishedDocument = await collection.unpublish(context, id, {
+            expectedRevision: parsed.data.expectedRevision
+        });
         if (!unpublishedDocument) {
             return c.json({
                 success: false,
@@ -111,6 +246,14 @@ export const documentsPublishRouter = new Hono()
         if (error instanceof PermissionError) {
             return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
         }
+        if (error instanceof RevisionConflictError) {
+            return c.json({
+                success: false,
+                error: 'Conflict',
+                message: error.message,
+                currentRevision: error.currentRevision
+            }, 409);
+        }
         return c.json({
             success: false,
             error: 'Failed to unpublish document',

package/dist/server/api/routes/jobs.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import type { AphexEnv } from '../index.js';
+export declare const jobsRouter: Hono<AphexEnv>;
+//# sourceMappingURL=jobs.d.ts.map

package/dist/server/api/routes/jobs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jobs.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/jobs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAK5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AA6CzC,eAAO,MAAM,UAAU,EAAE,IAAI,CAAC,QAAQ,CAkDnC,CAAC"}

package/dist/server/api/routes/jobs.js

@@ -0,0 +1,94 @@
+import { Hono } from 'hono';
+import { z } from 'zod';
+import { authToContext } from '../../../local-api/auth-helpers.js';
+import { hasCapability } from '../../../types/capabilities.js';
+import { cmsLogger } from '../../../utils/logger.js';
+import { withCreatedByNames } from './resolve-created-by.js';
+// Read-only history / observability for the durable spine. Gated on `document.read`:
+// the operational log of publish work is visible to anyone who can read content.
+// Mirrors JobStatus (types/events) as a zod enum — the API contract's source of truth.
+const jobStatus = z.enum(['pending', 'leased', 'completed', 'failed', 'cancelled']);
+const listJobsQuery = z.object({
+    status: jobStatus.optional(),
+    type: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+    offset: z.coerce.number().int().min(0).optional()
+});
+const listEventsQuery = z.object({
+    type: z.string().optional(),
+    limit: z.coerce.number().int().min(1).max(200).optional(),
+    offset: z.coerce.number().int().min(0).optional()
+});
+/** Map an adapter Page into the ApiResponse `pagination` shape the client expects. */
+function toPagination(page) {
+    const pageSize = page.limit || 1;
+    return {
+        total: page.total,
+        page: Math.floor(page.offset / pageSize) + 1,
+        pageSize,
+        totalPages: Math.max(1, Math.ceil(page.total / pageSize)),
+        hasNextPage: page.offset + page.limit < page.total,
+        hasPrevPage: page.offset > 0
+    };
+}
+function requireHistoryAccess(c) {
+    const auth = c.var.auth;
+    if (!auth || auth.type === 'partial_session') {
+        return { error: c.json({ success: false, error: 'Authentication required' }, 401) };
+    }
+    if (!hasCapability(auth, 'document.read')) {
+        return { error: c.json({ success: false, error: 'Insufficient permissions' }, 403) };
+    }
+    return { organizationId: authToContext(auth).organizationId };
+}
+export const jobsRouter = new Hono()
+    .get('/jobs', async (c) => {
+    try {
+        const gate = requireHistoryAccess(c);
+        if ('error' in gate)
+            return gate.error;
+        const parsed = listJobsQuery.safeParse(c.req.query());
+        if (!parsed.success) {
+            return c.json({ success: false, error: 'Invalid query', issues: parsed.error.issues }, 400);
+        }
+        const { status, type, limit, offset } = parsed.data;
+        const { databaseAdapter } = c.var.aphexCMS;
+        const page = await databaseAdapter.listJobs({
+            organizationId: gate.organizationId,
+            status,
+            type,
+            limit,
+            offset
+        });
+        return c.json({ success: true, data: page.items, pagination: toPagination(page) });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to list jobs:', error);
+        return c.json({ success: false, error: 'Failed to list jobs' }, 500);
+    }
+})
+    .get('/events', async (c) => {
+    try {
+        const gate = requireHistoryAccess(c);
+        if ('error' in gate)
+            return gate.error;
+        const parsed = listEventsQuery.safeParse(c.req.query());
+        if (!parsed.success) {
+            return c.json({ success: false, error: 'Invalid query', issues: parsed.error.issues }, 400);
+        }
+        const { type, limit, offset } = parsed.data;
+        const { databaseAdapter, auth } = c.var.aphexCMS;
+        const page = await databaseAdapter.listEvents({
+            organizationId: gate.organizationId,
+            type,
+            limit,
+            offset
+        });
+        const items = await withCreatedByNames(page.items, auth);
+        return c.json({ success: true, data: items, pagination: toPagination(page) });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to list events:', error);
+        return c.json({ success: false, error: 'Failed to list events' }, 500);
+    }
+});

package/dist/server/api/routes/resolve-created-by.d.ts

@@ -0,0 +1,13 @@
+import type { AuthProvider } from '../../../auth/provider.js';
+/**
+ * Resolves `createdBy` user ids on a list of rows to a display name (or `'API Key'` for a
+ * `apikey:<id>` synthetic id — see `authToContext`'s API-key branch). Shared by every
+ * read-only history view (`GET /api/events`, `GET /api/agent/change-sets`, ...) — an audit
+ * trail whose whole point is accountability needs to show *who*, not a raw id.
+ */
+export declare function withCreatedByNames<T extends {
+    createdBy: string | null;
+}>(rows: T[], auth: AuthProvider | undefined): Promise<Array<T & {
+    createdByName: string | null;
+}>>;
+//# sourceMappingURL=resolve-created-by.d.ts.map

package/dist/server/api/routes/resolve-created-by.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-created-by.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/resolve-created-by.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,wBAAwB,CAAC;AAE3D;;;;;GAKG;AACH,wBAAsB,kBAAkB,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,EAC9E,IAAI,EAAE,CAAC,EAAE,EACT,IAAI,EAAE,YAAY,GAAG,SAAS,GAC5B,OAAO,CAAC,KAAK,CAAC,CAAC,GAAG;IAAE,aAAa,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC,CAAC,CAyBtD"}

package/dist/server/api/routes/resolve-created-by.js

@@ -0,0 +1,30 @@
+/**
+ * Resolves `createdBy` user ids on a list of rows to a display name (or `'API Key'` for a
+ * `apikey:<id>` synthetic id — see `authToContext`'s API-key branch). Shared by every
+ * read-only history view (`GET /api/events`, `GET /api/agent/change-sets`, ...) — an audit
+ * trail whose whole point is accountability needs to show *who*, not a raw id.
+ */
+export async function withCreatedByNames(rows, auth) {
+    const userIds = [...new Set(rows.map((r) => r.createdBy).filter((id) => !!id))];
+    const userMap = new Map();
+    if (userIds.length > 0 && auth) {
+        await Promise.all(userIds.map(async (userId) => {
+            if (userId.startsWith('apikey:')) {
+                userMap.set(userId, 'API Key');
+                return;
+            }
+            try {
+                const user = await auth.getUserById(userId);
+                if (user)
+                    userMap.set(userId, user.name || user.email);
+            }
+            catch {
+                // User not found — skip
+            }
+        }));
+    }
+    return rows.map((r) => ({
+        ...r,
+        createdByName: r.createdBy ? (userMap.get(r.createdBy) ?? null) : null
+    }));
+}

package/dist/server/api/routes/workers-run.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import type { AphexEnv } from '../index.js';
+export declare const workersRunRouter: Hono<AphexEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=workers-run.d.ts.map

package/dist/server/api/routes/workers-run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workers-run.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/workers-run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAezC,eAAO,MAAM,gBAAgB,uDAAuB,CAAC"}