@pellux/goodvibes-daemon-sdk 0.30.3 → 0.33.0

package/dist/knowledge-routes.js

@@ -1,9 +1,10 @@
 import { buildMissingScopeBody, resolvePrivateHostFetchOptions, } from './http-policy.js';
 import { GoodVibesSdkError, DaemonErrorCategory } from '@pellux/goodvibes-errors';
-import { jsonErrorResponse, summarizeErrorForRecord } from './error-response.js';
+import { jsonErrorResponse } from './error-response.js';
 import { createArtifactFromUploadRequest, isArtifactUploadRequest } from './artifact-upload.js';
-import { readBoundedPositiveInteger, readOptionalBoundedInteger } from './route-helpers.js';
+import { createRouteBodySchema, createRouteBodySchemaRegistry, readBoundedBodyInteger, readBoundedPositiveInteger, readOptionalBoundedInteger, readOptionalStringField, readStringArrayField, } from './route-helpers.js';
 import { createDaemonKnowledgeRefinementRouteHandlers } from './knowledge-refinement-routes.js';
+const MAX_KNOWLEDGE_INGEST_TAGS = 64;
 export function createDaemonKnowledgeRouteHandlers(context) {
     return {
         getKnowledgeStatus: async () => Response.json(await context.knowledgeService.getStatus()),
@@ -14,20 +15,20 @@ export function createDaemonKnowledgeRouteHandlers(context) {
             const item = context.knowledgeService.getItem(id);
             return item
                 ? Response.json(item)
-                : Response.json({ error: 'Unknown knowledge item' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge item' }, { status: 404 });
         },
         getKnowledgeConnectors: () => Response.json({ connectors: context.knowledgeService.listConnectors() }),
         getKnowledgeConnector: (id) => {
             const connector = context.knowledgeService.getConnector(id);
             return connector
                 ? Response.json({ connector })
-                : Response.json({ error: 'Unknown knowledge connector' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge connector' }, { status: 404 });
         },
         getKnowledgeConnectorDoctor: async (id) => {
             const report = await context.knowledgeService.doctorConnector(id);
             return report
                 ? Response.json({ report })
-                : Response.json({ error: 'Unknown knowledge connector' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge connector' }, { status: 404 });
         },
         getKnowledgeProjectionTargets: async (url) => Response.json({ targets: await context.knowledgeService.listProjectionTargets(readLimit(url, 25)) }),
         getKnowledgeMap: async (url) => Response.json(await context.knowledgeService.map({
@@ -74,33 +75,33 @@ export function createDaemonKnowledgeRouteHandlers(context) {
             const candidate = context.knowledgeService.getConsolidationCandidate(id);
             return candidate
                 ? Response.json({ candidate })
-                : Response.json({ error: 'Unknown knowledge consolidation candidate' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge consolidation candidate' }, { status: 404 });
         },
         getKnowledgeReports: async (url) => Response.json({ reports: context.knowledgeService.listConsolidationReports(readLimit(url, 100)) }),
         getKnowledgeReport: (id) => {
             const report = context.knowledgeService.getConsolidationReport(id);
             return report
                 ? Response.json({ report })
-                : Response.json({ error: 'Unknown knowledge consolidation report' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge consolidation report' }, { status: 404 });
         },
         getKnowledgeExtraction: (id) => {
             const extraction = context.knowledgeService.getExtraction(id);
             return extraction
                 ? Response.json({ extraction })
-                : Response.json({ error: 'Unknown knowledge extraction' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge extraction' }, { status: 404 });
         },
         getKnowledgeSourceExtraction: (id) => {
             const extraction = context.knowledgeService.getSourceExtraction(id);
             return extraction
                 ? Response.json({ extraction })
-                : Response.json({ error: 'Unknown source extraction' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown source extraction' }, { status: 404 });
         },
         getKnowledgeJobs: () => Response.json({ jobs: context.knowledgeService.listJobs() }),
         getKnowledgeJob: (jobId) => {
             const job = context.knowledgeService.getJob(jobId);
             return job
                 ? Response.json({ job })
-                : Response.json({ error: 'Unknown knowledge job' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge job' }, { status: 404 });
         },
         getKnowledgeJobRuns: (url) => {
             const jobId = url.searchParams.get('jobId') ?? undefined;
@@ -112,7 +113,7 @@ export function createDaemonKnowledgeRouteHandlers(context) {
             const schedule = context.knowledgeService.getSchedule(id);
             return schedule
                 ? Response.json({ schedule })
-                : Response.json({ error: 'Unknown knowledge schedule' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge schedule' }, { status: 404 });
         },
         postKnowledgeIngestUrl: async (request) => handleKnowledgeIngestUrl(context, request),
         postKnowledgeIngestArtifact: async (request) => handleKnowledgeIngestArtifact(context, request),
@@ -146,7 +147,7 @@ export function createDaemonKnowledgeRouteHandlers(context) {
             const deleted = await context.knowledgeService.deleteSchedule(id);
             return deleted
                 ? Response.json({ deleted: true })
-                : Response.json({ error: 'Unknown knowledge schedule' }, { status: 404 });
+                : jsonErrorResponse({ error: 'Unknown knowledge schedule' }, { status: 404 });
         },
         postKnowledgeSetScheduleEnabled: async (id, request) => handleKnowledgeSetScheduleEnabled(context, id, request),
         postKnowledgeRenderProjection: async (request) => handleKnowledgeRenderProjection(context, request),
@@ -189,6 +190,72 @@ function readStringList(url, ...names) {
         .map((value) => value.trim())
         .filter(Boolean);
 }
+const knowledgeBodySchemas = createRouteBodySchemaRegistry({
+    search: createRouteBodySchema('POST /api/knowledge/search', (body) => {
+        const query = readOptionalStringField(body, 'query');
+        if (!query)
+            return jsonErrorResponse({ error: 'Missing query' }, { status: 400 });
+        return {
+            query,
+            limit: readBoundedBodyInteger(body.limit, 10, 100),
+        };
+    }),
+    ask: createRouteBodySchema('POST /api/knowledge/ask', (body) => {
+        const query = readOptionalStringField(body, 'query');
+        if (!query)
+            return jsonErrorResponse({ error: 'Missing query' }, { status: 400 });
+        const mode = readKnowledgeAnswerMode(body.mode);
+        const knowledgeSpaceId = readOptionalStringField(body, 'knowledgeSpaceId');
+        const candidateSourceIds = readStringArrayField(body, 'candidateSourceIds');
+        const candidateNodeIds = readStringArrayField(body, 'candidateNodeIds');
+        return {
+            query,
+            ...(knowledgeSpaceId ? { knowledgeSpaceId } : {}),
+            ...(Object.hasOwn(body, 'limit') ? { limit: readBoundedBodyInteger(body.limit, 8, 50) } : {}),
+            ...(mode ? { mode } : {}),
+            ...(typeof body.includeSources === 'boolean' ? { includeSources: body.includeSources } : {}),
+            ...(typeof body.includeConfidence === 'boolean' ? { includeConfidence: body.includeConfidence } : {}),
+            ...(typeof body.includeLinkedObjects === 'boolean' ? { includeLinkedObjects: body.includeLinkedObjects } : {}),
+            ...(candidateSourceIds ? { candidateSourceIds } : {}),
+            ...(candidateNodeIds ? { candidateNodeIds } : {}),
+            ...(typeof body.strictCandidates === 'boolean' ? { strictCandidates: body.strictCandidates } : {}),
+        };
+    }),
+    packet: createRouteBodySchema('POST /api/knowledge/packet', (body) => {
+        const task = readOptionalStringField(body, 'task');
+        if (!task)
+            return jsonErrorResponse({ error: 'Missing task' }, { status: 400 });
+        const detail = readKnowledgePacketDetail(body.detail);
+        const budgetLimit = Object.hasOwn(body, 'budgetLimit')
+            ? readBoundedBodyInteger(body.budgetLimit, 6, 100)
+            : undefined;
+        return {
+            task,
+            writeScope: readStringArrayField(body, 'writeScope') ?? [],
+            limit: readBoundedBodyInteger(body.limit, 6, 50),
+            ...(detail ? { detail } : {}),
+            ...(typeof budgetLimit === 'number' ? { budgetLimit } : {}),
+        };
+    }),
+    runJob: createRouteBodySchema('POST /api/knowledge/jobs/:jobId/run', (body) => {
+        const mode = readKnowledgeJobRunMode(body.mode);
+        const sourceIds = readStringArrayField(body, 'sourceIds');
+        return {
+            ...(mode ? { mode } : {}),
+            ...(sourceIds ? { sourceIds } : {}),
+            ...(Object.hasOwn(body, 'limit') ? { limit: readBoundedBodyInteger(body.limit, 50, 500) } : {}),
+        };
+    }),
+});
+function readKnowledgeAnswerMode(value) {
+    return value === 'concise' || value === 'standard' || value === 'detailed' ? value : undefined;
+}
+function readKnowledgePacketDetail(value) {
+    return typeof value === 'string' ? value.toLowerCase() : undefined;
+}
+function readKnowledgeJobRunMode(value) {
+    return value === 'inline' || value === 'background' ? value : undefined;
+}
 function readKnowledgeProjectionRequest(body) {
     const rawKind = typeof body.kind === 'string' ? body.kind.trim().toLowerCase() : '';
     if (rawKind !== 'overview'
@@ -198,23 +265,24 @@ function readKnowledgeProjectionRequest(body) {
         && rawKind !== 'issue'
         && rawKind !== 'dashboard'
         && rawKind !== 'rollup') {
-        return Response.json({
+        return jsonErrorResponse({
             error: 'Projection kind must be one of overview, bundle, source, node, issue, dashboard, or rollup.',
+            code: 'INVALID_PROJECTION_KIND',
         }, { status: 400 });
     }
     const id = typeof body.id === 'string' ? body.id.trim() : '';
     if ((rawKind === 'source' || rawKind === 'node' || rawKind === 'issue' || rawKind === 'rollup') && !id) {
-        return Response.json({ error: `Projection kind ${rawKind} requires id.` }, { status: 400 });
+        return jsonErrorResponse({ error: `Projection kind ${rawKind} requires id.` }, { status: 400 });
     }
     return {
         kind: rawKind,
         ...(id ? { id } : {}),
-        ...(typeof body.limit === 'number' ? { limit: Math.max(1, body.limit) } : {}),
+        ...(Object.hasOwn(body, 'limit') ? { limit: readBoundedBodyInteger(body.limit, 20, 500) } : {}),
     };
 }
 function readKnowledgeSchedule(context, value) {
     if (typeof value !== 'object' || value === null) {
-        return Response.json({ error: 'Missing schedule object' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing schedule object' }, { status: 400 });
     }
     const schedule = value;
     const kind = typeof schedule.kind === 'string' ? schedule.kind.trim().toLowerCase() : '';
@@ -257,14 +325,14 @@ function readGraphqlVariables(value, parseJsonText) {
     if (typeof value === 'object') {
         return value;
     }
-    return Response.json({ error: 'GraphQL variables must be an object or JSON string.' }, { status: 400 });
+    return jsonErrorResponse({ error: 'GraphQL variables must be an object or JSON string.' }, { status: 400 });
 }
 async function parseKnowledgeGraphqlRequest(context, req) {
     if (req.method === 'GET') {
         const url = new URL(req.url);
         const query = url.searchParams.get('query')?.trim() ?? '';
         if (!query)
-            return Response.json({ error: 'Missing query' }, { status: 400 });
+            return jsonErrorResponse({ error: 'Missing query' }, { status: 400 });
         const variables = readGraphqlVariables(url.searchParams.get('variables'), context.parseJsonText);
         if (variables instanceof Response)
             return variables;
@@ -280,16 +348,16 @@ async function parseKnowledgeGraphqlRequest(context, req) {
         const query = (await req.text()).trim();
         return query
             ? { query }
-            : Response.json({ error: 'Missing query' }, { status: 400 });
+            : jsonErrorResponse({ error: 'Missing query' }, { status: 400 });
     }
     const body = await context.parseOptionalJsonBody(req);
     if (body instanceof Response)
         return body;
     if (!body)
-        return Response.json({ error: 'Missing query' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing query' }, { status: 400 });
     const query = typeof body.query === 'string' ? body.query.trim() : '';
     if (!query)
-        return Response.json({ error: 'Missing query' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing query' }, { status: 400 });
     const variables = readGraphqlVariables(body.variables, context.parseJsonText);
     if (variables instanceof Response)
         return variables;
@@ -304,12 +372,12 @@ async function handleKnowledgeGraphql(context, req) {
     const parsed = await parseKnowledgeGraphqlRequest(context, req);
     if (parsed instanceof Response)
         return parsed;
-    if (req.method === 'GET' && /\bmutation\b/.test(parsed.query)) {
-        return Response.json({ error: 'GraphQL mutations must use POST.' }, { status: 405 });
+    if (req.method === 'GET' && graphqlOperationLooksLikeMutation(parsed.query)) {
+        return jsonErrorResponse({ error: 'GraphQL mutations must use POST.' }, { status: 405 });
     }
     const principal = context.resolveAuthenticatedPrincipal(req);
     if (!principal) {
-        return Response.json({ error: 'Unauthorized' }, { status: 401 });
+        return jsonErrorResponse({ error: 'Unauthorized' }, { status: 401 });
     }
     let access;
     try {
@@ -323,7 +391,7 @@ async function handleKnowledgeGraphql(context, req) {
         return Response.json(scopeDenied, { status: 403 });
     }
     if (access.adminRequired && !principal.admin) {
-        return Response.json({ error: 'Knowledge GraphQL mutation requires admin access.' }, { status: 403 });
+        return jsonErrorResponse({ error: 'Knowledge GraphQL mutation requires admin access.' }, { status: 403 });
     }
     const result = await context.knowledgeGraphqlService.execute({
         query: parsed.query,
@@ -335,6 +403,13 @@ async function handleKnowledgeGraphql(context, req) {
     const status = result.errors?.length && !result.data ? 400 : 200;
     return Response.json(result, { status });
 }
+function graphqlOperationLooksLikeMutation(query) {
+    const withoutComments = query.replace(/#[^\n\r]*/g, '');
+    const withoutStrings = withoutComments
+        .replace(/"""[\s\S]*?"""/g, ' ')
+        .replace(/"(?:\\.|[^"\\])*"/g, ' ');
+    return /^\s*mutation\b/.test(withoutStrings);
+}
 function buildKnowledgePrivateHostFetchOptions(context, requested) {
     return resolvePrivateHostFetchOptions(requested, {
         configManager: context.configManager,
@@ -349,16 +424,17 @@ async function handleKnowledgeIngestUrl(context, request) {
         return body;
     const url = typeof body.url === 'string' ? body.url.trim() : '';
     if (!url)
-        return Response.json({ error: 'Missing url' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing url' }, { status: 400 });
     const privateHostFetchOptions = buildKnowledgePrivateHostFetchOptions(context, body.allowPrivateHosts);
     if (privateHostFetchOptions instanceof Response)
         return privateHostFetchOptions;
+    const tags = readStringArrayField(body, 'tags', MAX_KNOWLEDGE_INGEST_TAGS);
     try {
         return Response.json(await context.knowledgeService.ingestUrl({
             url,
             ...(typeof body.title === 'string' ? { title: body.title } : {}),
             ...(typeof body.folderPath === 'string' ? { folderPath: body.folderPath } : {}),
-            ...(Array.isArray(body.tags) ? { tags: body.tags.filter((entry) => typeof entry === 'string') } : {}),
+            ...(tags ? { tags } : {}),
             ...(typeof body.sessionId === 'string' ? { sessionId: body.sessionId } : {}),
             ...(typeof body.sourceType === 'string' ? { sourceType: body.sourceType } : {}),
             ...(typeof body.connectorId === 'string' ? { connectorId: body.connectorId } : {}),
@@ -394,6 +470,7 @@ async function handleKnowledgeIngestArtifact(context, request) {
     const privateHostFetchOptions = buildKnowledgePrivateHostFetchOptions(context, body.allowPrivateHosts);
     if (privateHostFetchOptions instanceof Response)
         return privateHostFetchOptions;
+    const tags = readStringArrayField(body, 'tags', MAX_KNOWLEDGE_INGEST_TAGS);
     try {
         return Response.json(await context.knowledgeService.ingestArtifact({
             ...(typeof body.artifactId === 'string' ? { artifactId: body.artifactId } : {}),
@@ -401,7 +478,7 @@ async function handleKnowledgeIngestArtifact(context, request) {
             ...(typeof body.uri === 'string' ? { uri: body.uri } : {}),
             ...(typeof body.title === 'string' ? { title: body.title } : {}),
             ...(typeof body.folderPath === 'string' ? { folderPath: body.folderPath } : {}),
-            ...(Array.isArray(body.tags) ? { tags: body.tags.filter((entry) => typeof entry === 'string') } : {}),
+            ...(tags ? { tags } : {}),
             ...(typeof body.sessionId === 'string' ? { sessionId: body.sessionId } : {}),
             ...(typeof body.sourceType === 'string' ? { sourceType: body.sourceType } : {}),
             ...(typeof body.connectorId === 'string' ? { connectorId: body.connectorId } : {}),
@@ -429,7 +506,7 @@ async function handleKnowledgeSyncBrowserHistory(context, request) {
         : undefined;
     try {
         return Response.json(await context.knowledgeService.syncBrowserHistory({
-            ...(typeof input.limit === 'number' ? { limit: Math.max(1, input.limit) } : {}),
+            ...(Object.hasOwn(input, 'limit') ? { limit: readBoundedBodyInteger(input.limit, 50, 500) } : {}),
             ...(typeof input.sinceMs === 'number' ? { sinceMs: input.sinceMs } : {}),
             ...(typeof input.homeOverride === 'string' ? { homeOverride: input.homeOverride } : {}),
             ...(typeof input.sessionId === 'string' ? { sessionId: input.sessionId } : {}),
@@ -451,7 +528,7 @@ async function handleKnowledgeImportBookmarks(context, request) {
         return body;
     const path = typeof body.path === 'string' ? body.path.trim() : '';
     if (!path)
-        return Response.json({ error: 'Missing path' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing path' }, { status: 400 });
     const privateHostFetchOptions = buildKnowledgePrivateHostFetchOptions(context, body.allowPrivateHosts);
     if (privateHostFetchOptions instanceof Response)
         return privateHostFetchOptions;
@@ -475,7 +552,7 @@ async function handleKnowledgeImportUrls(context, request) {
         return body;
     const path = typeof body.path === 'string' ? body.path.trim() : '';
     if (!path)
-        return Response.json({ error: 'Missing path' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing path' }, { status: 400 });
     const privateHostFetchOptions = buildKnowledgePrivateHostFetchOptions(context, body.allowPrivateHosts);
     if (privateHostFetchOptions instanceof Response)
         return privateHostFetchOptions;
@@ -499,7 +576,7 @@ async function handleKnowledgeIngestConnector(context, request) {
         return body;
     const connectorId = typeof body.connectorId === 'string' ? body.connectorId.trim() : '';
     if (!connectorId)
-        return Response.json({ error: 'Missing connectorId' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing connectorId' }, { status: 400 });
     const privateHostFetchOptions = buildKnowledgePrivateHostFetchOptions(context, body.allowPrivateHosts);
     if (privateHostFetchOptions instanceof Response)
         return privateHostFetchOptions;
@@ -521,48 +598,30 @@ async function handleKnowledgeSearch(context, request) {
     const body = await context.parseJsonBody(request);
     if (body instanceof Response)
         return body;
-    const query = typeof body.query === 'string' ? body.query.trim() : '';
-    if (!query)
-        return Response.json({ error: 'Missing query' }, { status: 400 });
-    const limit = typeof body.limit === 'number' ? body.limit : 10;
-    return Response.json({ results: context.knowledgeService.search(query, limit) });
+    const input = knowledgeBodySchemas.search.parse(body);
+    if (input instanceof Response)
+        return input;
+    return Response.json({ results: context.knowledgeService.search(input.query, input.limit) });
 }
 async function handleKnowledgeAsk(context, request) {
     const body = await context.parseJsonBody(request);
     if (body instanceof Response)
         return body;
-    const query = typeof body.query === 'string' ? body.query.trim() : '';
-    if (!query)
-        return Response.json({ error: 'Missing query' }, { status: 400 });
-    return Response.json(await context.knowledgeService.ask({
-        query,
-        ...(typeof body.knowledgeSpaceId === 'string' ? { knowledgeSpaceId: body.knowledgeSpaceId } : {}),
-        ...(typeof body.limit === 'number' ? { limit: Math.max(1, body.limit) } : {}),
-        ...(typeof body.mode === 'string' && ['concise', 'standard', 'detailed'].includes(body.mode) ? { mode: body.mode } : {}),
-        ...(typeof body.includeSources === 'boolean' ? { includeSources: body.includeSources } : {}),
-        ...(typeof body.includeConfidence === 'boolean' ? { includeConfidence: body.includeConfidence } : {}),
-        ...(typeof body.includeLinkedObjects === 'boolean' ? { includeLinkedObjects: body.includeLinkedObjects } : {}),
-        ...(Array.isArray(body.candidateSourceIds) ? { candidateSourceIds: body.candidateSourceIds.filter(isString) } : {}),
-        ...(Array.isArray(body.candidateNodeIds) ? { candidateNodeIds: body.candidateNodeIds.filter(isString) } : {}),
-        ...(typeof body.strictCandidates === 'boolean' ? { strictCandidates: body.strictCandidates } : {}),
-    }));
+    const input = knowledgeBodySchemas.ask.parse(body);
+    if (input instanceof Response)
+        return input;
+    return Response.json(await context.knowledgeService.ask(input));
 }
 async function handleKnowledgePacket(context, request) {
     const body = await context.parseJsonBody(request);
     if (body instanceof Response)
         return body;
-    const task = typeof body.task === 'string' ? body.task.trim() : '';
-    if (!task)
-        return Response.json({ error: 'Missing task' }, { status: 400 });
-    const writeScope = Array.isArray(body.writeScope) ? body.writeScope.filter((entry) => typeof entry === 'string') : [];
-    const limit = typeof body.limit === 'number' ? body.limit : 6;
-    const detail = typeof body.detail === 'string'
-        ? body.detail.toLowerCase()
-        : undefined;
-    const budgetLimit = typeof body.budgetLimit === 'number' ? body.budgetLimit : undefined;
-    return Response.json(await context.knowledgeService.buildPacket(task, writeScope, limit, {
-        ...(detail ? { detail } : {}),
-        ...(typeof budgetLimit === 'number' ? { budgetLimit } : {}),
+    const input = knowledgeBodySchemas.packet.parse(body);
+    if (input instanceof Response)
+        return input;
+    return Response.json(await context.knowledgeService.buildPacket(input.task, input.writeScope, input.limit, {
+        ...(input.detail ? { detail: input.detail } : {}),
+        ...(typeof input.budgetLimit === 'number' ? { budgetLimit: input.budgetLimit } : {}),
     }));
 }
 async function handleKnowledgeReviewIssue(context, id, request) {
@@ -574,7 +633,7 @@ async function handleKnowledgeReviewIssue(context, id, request) {
         return body;
     const action = typeof body?.action === 'string' ? body.action.trim().toLowerCase() : '';
     if (!['accept', 'reject', 'resolve', 'reopen', 'edit', 'forget'].includes(action)) {
-        return Response.json({ error: 'Action must be accept, reject, resolve, reopen, edit, or forget.' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Action must be accept, reject, resolve, reopen, edit, or forget.' }, { status: 400 });
     }
     try {
         return Response.json(await context.knowledgeService.reviewIssue({
@@ -585,10 +644,10 @@ async function handleKnowledgeReviewIssue(context, id, request) {
         }));
     }
     catch (error) {
-        const message = summarizeErrorForRecord(error);
-        return jsonErrorResponse(error, {
-            status: message.startsWith('Unknown knowledge issue:') ? 404 : 400,
-        });
+        // map status from error code, not English-prefix match.
+        const isNotFound = error instanceof Error && (error.code === 'NOT_FOUND'
+            || error.code === 'KNOWLEDGE_ISSUE_NOT_FOUND');
+        return jsonErrorResponse(error, { status: isNotFound ? 404 : 400 });
     }
 }
 async function handleKnowledgeDecideCandidate(context, id, request) {
@@ -600,7 +659,7 @@ async function handleKnowledgeDecideCandidate(context, id, request) {
         return body;
     const decision = typeof body.decision === 'string' ? body.decision.trim().toLowerCase() : '';
     if (decision !== 'accept' && decision !== 'reject' && decision !== 'supersede') {
-        return Response.json({ error: 'Decision must be accept, reject, or supersede.' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Decision must be accept, reject, or supersede.' }, { status: 400 });
     }
     try {
         return Response.json({
@@ -613,10 +672,10 @@ async function handleKnowledgeDecideCandidate(context, id, request) {
         });
     }
     catch (error) {
-        const message = summarizeErrorForRecord(error);
-        return jsonErrorResponse(error, {
-            status: message.startsWith('Unknown knowledge consolidation candidate:') ? 404 : 400,
-        });
+        // map status from error code, not English-prefix match.
+        const isNotFound = error instanceof Error && (error.code === 'NOT_FOUND'
+            || error.code === 'KNOWLEDGE_CANDIDATE_NOT_FOUND');
+        return jsonErrorResponse(error, { status: isNotFound ? 404 : 400 });
     }
 }
 async function handleKnowledgeRunJob(context, jobId, request) {
@@ -626,20 +685,19 @@ async function handleKnowledgeRunJob(context, jobId, request) {
     const body = await context.parseJsonBody(request);
     if (body instanceof Response)
         return body;
+    const input = knowledgeBodySchemas.runJob.parse(body);
+    if (input instanceof Response)
+        return input;
     try {
         return Response.json({
-            run: await context.knowledgeService.runJob(jobId, {
-                ...(typeof body.mode === 'string' ? { mode: body.mode.toLowerCase() } : {}),
-                ...(Array.isArray(body.sourceIds) ? { sourceIds: body.sourceIds.filter((entry) => typeof entry === 'string') } : {}),
-                ...(typeof body.limit === 'number' ? { limit: body.limit } : {}),
-            }),
+            run: await context.knowledgeService.runJob(jobId, input),
         });
     }
     catch (error) {
-        const message = summarizeErrorForRecord(error);
-        return jsonErrorResponse(error, {
-            status: message.startsWith('Unknown knowledge job:') ? 404 : 400,
-        });
+        // map status from error code, not English-prefix match.
+        const isNotFound = error instanceof Error && (error.code === 'NOT_FOUND'
+            || error.code === 'KNOWLEDGE_JOB_NOT_FOUND');
+        return jsonErrorResponse(error, { status: isNotFound ? 404 : 400 });
     }
 }
 async function handleKnowledgeSaveSchedule(context, request) {
@@ -651,7 +709,7 @@ async function handleKnowledgeSaveSchedule(context, request) {
         return body;
     const jobId = typeof body.jobId === 'string' ? body.jobId.trim() : '';
     if (!jobId)
-        return Response.json({ error: 'Missing jobId' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing jobId' }, { status: 400 });
     const schedule = readKnowledgeSchedule(context, body.schedule);
     if (schedule instanceof Response)
         return schedule;
@@ -679,12 +737,12 @@ async function handleKnowledgeSetScheduleEnabled(context, id, request) {
     if (body instanceof Response)
         return body;
     if (typeof body.enabled !== 'boolean') {
-        return Response.json({ error: 'Missing enabled boolean' }, { status: 400 });
+        return jsonErrorResponse({ error: 'Missing enabled boolean' }, { status: 400 });
     }
     const schedule = await context.knowledgeService.setScheduleEnabled(id, body.enabled);
     return schedule
         ? Response.json({ schedule })
-        : Response.json({ error: 'Unknown knowledge schedule' }, { status: 404 });
+        : jsonErrorResponse({ error: 'Unknown knowledge schedule' }, { status: 404 });
 }
 async function handleKnowledgeRenderProjection(context, request) {
     const body = await context.parseJsonBody(request);
@@ -720,6 +778,3 @@ async function handleKnowledgeMaterializeProjection(context, request) {
         return jsonErrorResponse(error, { status: 400 });
     }
 }
-function isString(value) {
-    return typeof value === 'string' && value.trim().length > 0;
-}

package/dist/media-route-types.d.ts

@@ -1,3 +1,4 @@
+import type { JsonRecord } from './route-helpers.js';
 export type ArtifactKind = string;
 export type FetchExtractMode = string;
 export type MediaArtifact = Record<string, unknown>;
@@ -68,7 +69,7 @@ export interface DaemonMediaRouteContext {
     readonly configManager: ConfigManagerLike;
     readonly mediaProviders: MediaProviderRegistryLike;
     readonly multimodalService: MultimodalServiceLike;
-    readonly parseJsonBody: (req: Request) => Promise<Record<string, unknown> | Response>;
+    readonly parseJsonBody: (req: Request) => Promise<JsonRecord | Response>;
     readonly requireAdmin: (req: Request) => Response | null;
     readonly voiceService: VoiceServiceLike;
     readonly webSearchService: WebSearchServiceLike;

package/dist/media-route-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-route-types.d.ts","sourceRoot":"","sources":["../src/media-route-types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"media-route-types.d.ts","sourceRoot":"","sources":["../src/media-route-types.ts"],"names":[],"mappings":"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"}

package/dist/media-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-routes.d.ts","sourceRoot":"","sources":["../src/media-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAK7D,OAAO,KAAK,EAEV,uBAAuB,EAUxB,MAAM,wBAAwB,CAAC;AA2BhC,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,uBAAuB,GAC/B,wBAAwB,CAgC1B"}
+{"version":3,"file":"media-routes.d.ts","sourceRoot":"","sources":["../src/media-routes.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AAY7D,OAAO,KAAK,EAEV,uBAAuB,EAUxB,MAAM,wBAAwB,CAAC;AAehC,wBAAgB,8BAA8B,CAC5C,OAAO,EAAE,uBAAuB,GAC/B,wBAAwB,CAkC1B"}