@xopcai/xopc 0.0.389 → 0.0.391

package/dist/src/discussions/service.js

@@ -8,6 +8,10 @@ import { DiscussionServiceError } from "./errors.js";
 import { acknowledgeDiscussionCaptureConsent, correctDiscussionTranscriptSegment, createDiscussionCapture, createDiscussionTranscriptSegment, deleteDiscussionSegmentAudio, getDiscussionCapture, getDiscussionCaptureByClientRequestId, getDiscussionCaptureByNoteId, getDiscussionCaptureSettings, getDiscussionMetrics, getDiscussionTranscriptSegment, getLatestDiscussionOrganization, listDiscussionCaptures, listDiscussionTranscriptSegments, updateDiscussionCapture } from "./repository.js";
 import { assembleDiscussionTranscript } from "./transcript.js";
 import { readTranscriptRevision, refreshCanonicalTranscript, saveTranscriptRevision } from "./revisions.js";
+import { createProcessingRun, processingProgress, resetProcessingRetry } from "./processing.js";
+import { evidenceFor, putAnnotation, resolvedAnnotations } from "./review.js";
+import { longRecordingReview } from "./long-review.js";
+import { discussionAudioClip } from "./audio-clip.js";
 import { editMeeting } from "./edits.js";
 import { completeRecording, listRecordingChunks, removeRecordingChunks, saveRecordingChunk, validateRecordingManifest } from "./recording.js";
 import { cancelRecordingJob, claimRecordingJob, finishRecordingJob, getRecordingJob, getRecordingJobInput, renewRecordingJob, submitRecordingJob } from "./recordingJobs.js";
@@ -31,6 +35,18 @@ var DiscussionService = class {
 		this.projects = projects;
 		this.emit = emit;
 	}
+	audioClip(id, start, end, signal) {
+		return discussionAudioClip(id, start, end, this.notes, signal);
+	}
+	annotations(id) {
+		return resolvedAnnotations(id, this.notes);
+	}
+	saveAnnotation(id, input) {
+		return putAnnotation(id, input);
+	}
+	evidence(id, revision, ids) {
+		return evidenceFor(id, revision, ids, this.notes);
+	}
 	settings() {
 		return getDiscussionCaptureSettings();
 	}
@@ -238,6 +254,7 @@ var DiscussionService = class {
 			const capture = getDiscussionCapture(id);
 			if (!capture) throw new DiscussionServiceError("not_found", "Discussion not found");
 			if (!["completed", "needs_attention"].includes(capture.status) || !capture.canonicalTranscript) throw new DiscussionServiceError("conflict", "Transcript is not ready");
+			resetProcessingRetry(id);
 			const updated = updateDiscussionCapture(id, {
 				status: "organizing",
 				template,
@@ -338,24 +355,37 @@ var DiscussionService = class {
 			}
 		});
 	}
-	async retry(id) {
-		const capture = getDiscussionCapture(id);
-		if (!capture) return null;
-		if (capture.status !== "needs_attention") throw new DiscussionServiceError("conflict", "Only discussions needing attention can be retried");
-		if (getRecordingJob(id)?.state === "failed") {
+	async retry(id, mode = "resume") {
+		if (mode !== "resume" && mode !== "from_audio") throw new DiscussionServiceError("invalid_input", "Invalid retry mode");
+		if (mode === "resume" && getRecordingJob(id)?.state === "failed") {
 			await this.sealRecording(id, getRecordingJobInput(id));
 			return this.get(id);
 		}
-		const updated = updateDiscussionCapture(id, {
-			status: capture.canonicalTranscript ? "organizing" : "stopping",
-			...!capture.canonicalTranscript ? { recordingStoppedAt: Date.now() } : {},
-			failureStage: void 0,
-			failureCode: void 0,
-			failureMessage: void 0
-		}, ["needs_attention"]);
-		if (!updated) throw new DiscussionServiceError("conflict", "Discussion changed while retrying");
-		this.emit?.("discussion.updated", updated);
-		return this.detail(updated);
+		return this.enqueueMutation(id, async () => {
+			const capture = getDiscussionCapture(id);
+			if (!capture) return null;
+			if (mode === "from_audio") {
+				if (!["completed", "needs_attention"].includes(capture.status)) throw new DiscussionServiceError("conflict", "Wait for current processing to finish");
+				if (!capture.audioAttachmentId || capture.audioDeletedAt || !await this.notes.getAttachmentPath(capture.noteId, capture.audioAttachmentId)) throw new DiscussionServiceError("conflict", "Saved original audio is unavailable");
+			} else if (capture.status !== "needs_attention") throw new DiscussionServiceError("conflict", "Only discussions needing attention can be retried");
+			const updated = runSqliteWriteTransaction(() => {
+				if (mode === "from_audio") {
+					saveTranscriptRevision(id);
+					createProcessingRun(capture, true);
+				} else resetProcessingRetry(id);
+				const status = mode === "from_audio" || capture.failureStage === "transcript_sealing" ? "sealing" : capture.canonicalTranscript ? "organizing" : "stopping";
+				return updateDiscussionCapture(id, {
+					status,
+					...status === "stopping" ? { recordingStoppedAt: Date.now() } : {},
+					failureStage: void 0,
+					failureCode: void 0,
+					failureMessage: void 0
+				}, [capture.status]);
+			});
+			if (!updated) throw new DiscussionServiceError("conflict", "Discussion changed while retrying");
+			this.emit?.("discussion.updated", updated);
+			return this.detail(updated);
+		});
 	}
 	async cancel(id) {
 		const active = getDiscussionCapture(id);
@@ -389,6 +419,8 @@ var DiscussionService = class {
 			await removeRecordingChunks(capture);
 			cancelRecordingJob(id);
 			if (capture.audioAttachmentId) await this.notes.removeAttachment(capture.noteId, capture.audioAttachmentId);
+			const sourceNote = await this.notes.getNote(capture.noteId);
+			for (const attachment of sourceNote?.attachments ?? []) if (attachment.retainWithoutReference && (attachment.fileName.startsWith(`recording-part-${capture.id}-`) || attachment.fileName === `recording-sources-${capture.id}.json` || attachment.fileName === `recording-events-${capture.id}.json`)) await this.notes.removeAttachment(capture.noteId, attachment.id);
 			deleteDiscussionSegmentAudio(id);
 			const updated = updateDiscussionCapture(id, {
 				audioAttachmentId: void 0,
@@ -413,12 +445,16 @@ var DiscussionService = class {
 		this.emit?.("discussion.updated", updated);
 		return this.detail(updated);
 	}
+	review(id, options = {}) {
+		return longRecordingReview(id, this.notes, options);
+	}
 	async detail(capture) {
 		const note = await this.notes.getNote(capture.noteId);
 		if (!note) throw new DiscussionServiceError("not_found", "Discussion note not found");
 		const recordingJob = getRecordingJob(capture.id);
 		return {
 			discussion: capture,
+			processing: processingProgress(capture.id),
 			note,
 			transcript: this.transcript(capture.id),
 			...recordingJob ? { recordingJob } : {},

package/dist/src/discussions/types.d.ts

@@ -1,10 +1,11 @@
 export { DISCUSSION_STATUSES } from '@xopcai/gateway-contract';
-export type { DiscussionStatus, DiscussionSource, DiscussionProjectInferenceSource, DiscussionFailureStage, DiscussionFact, DiscussionChapter, DiscussionTemplate, DiscussionActionItem, DiscussionOrganization, DiscussionCapture, DiscussionTranscriptSegmentStatus, DiscussionTranscriptSegment, DiscussionTranscriptStats, DiscussionTranscript, DiscussionOrganizationRecord, DiscussionCaptureSettings, CreateDiscussionInput, ListDiscussionsQuery, DiscussionListResult, DiscussionMetrics, } from '@xopcai/gateway-contract';
+export type { DiscussionStatus, DiscussionSource, DiscussionProjectInferenceSource, DiscussionFailureStage, DiscussionFact, DiscussionChapter, DiscussionTemplate, DiscussionActionItem, DiscussionOrganization, DiscussionCapture, DiscussionTranscriptSegmentStatus, DiscussionTranscriptSegment, DiscussionTranscriptStats, DiscussionTranscript, DiscussionOrganizationRecord, DiscussionCaptureSettings, CreateDiscussionInput, ListDiscussionsQuery, DiscussionListResult, DiscussionMetrics, DiscussionProcessingProgress, DiscussionRetryMode, } from '@xopcai/gateway-contract';
 import type { DiscussionCapture, DiscussionTranscript, DiscussionOrganizationRecord } from '@xopcai/gateway-contract';
 export interface DiscussionDetail {
     discussion: DiscussionCapture;
     note: import('../notes/types.js').Note;
     transcript: DiscussionTranscript;
     organization?: DiscussionOrganizationRecord;
+    processing?: import('@xopcai/gateway-contract').DiscussionProcessingProgress;
     recordingJob?: import('@xopcai/gateway-contract').DiscussionRecordingJob;
 }

package/dist/src/gateway/agent-builtin-tools.d.ts

@@ -277,4 +277,4 @@ export declare const GATEWAY_BUILTIN_TOOLS: readonly [{
         readonly zh: "使用已验证的参数执行选定的外部工具。";
     };
 }];
-export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "user_context_search" | "user_context_get" | "user_context_update" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "clarify" | "xopc_tool_execute" | "web_extract" | "tool_manual" | "session_status" | "read_media" | "xopc_tool_search" | "xopc_tool_describe" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "computer_use" | "send_message" | "text_to_speech" | "execute_code" | "send_media" | "create_share" | "memory_maintenance" | "delegate_task" | "skill_install" | "create_desktop_pet")[];
+export declare const GATEWAY_BUILTIN_TOOL_IDS: ("automation" | "workflow" | "find" | "image" | "knowledge_search" | "knowledge_get" | "knowledge_write" | "user_context_search" | "user_context_get" | "user_context_update" | "web_search" | "web_fetch" | "browser_use" | "grep" | "session_search" | "read_file" | "list_dir" | "write_file" | "apply_patch" | "exec_command" | "update_plan" | "todo" | "web_extract" | "clarify" | "xopc_tool_execute" | "tool_manual" | "session_status" | "read_media" | "xopc_tool_search" | "xopc_tool_describe" | "image_generate" | "skills_list" | "skill_view" | "skill_manage" | "skills_marketplace_search" | "computer_use" | "send_message" | "text_to_speech" | "execute_code" | "send_media" | "create_share" | "memory_maintenance" | "delegate_task" | "skill_install" | "create_desktop_pet")[];

package/dist/src/gateway/global-defaults-admin.d.ts

@@ -6,6 +6,8 @@ export type GlobalDefaultsPayload = {
 };
 export type UpdateGlobalDefaultsBody = {
     defaults: AgentDefaults;
+    scope?: 'models' | 'agent';
+    expectedModels?: AgentDefaults['models'];
 };
 export type GlobalDefaultsAdminResult<T> = {
     ok: true;
@@ -13,7 +15,7 @@ export type GlobalDefaultsAdminResult<T> = {
 } | {
     ok: false;
     error: string;
-    status?: 400 | 404 | 500;
+    status?: 400 | 404 | 409 | 500;
 };
 export declare function listGlobalDefaults(): GlobalDefaultsPayload;
 export declare function prepareUpdateGlobalDefaults(body: UpdateGlobalDefaultsBody): GlobalDefaultsAdminResult<{

package/dist/src/gateway/global-defaults-admin.js

@@ -18,13 +18,25 @@ function listGlobalDefaults() {
 	};
 }
 function prepareUpdateGlobalDefaults(body) {
-	const parsed = AgentDefaultsSchema.safeParse(body.defaults);
+	const current = new AgentCatalogRepository().getSettings().defaults;
+	if (body.expectedModels && !isDeepStrictEqual(current.models, body.expectedModels)) return {
+		ok: false,
+		error: "Model settings changed. Refresh before retrying.",
+		status: 409
+	};
+	const requested = body.scope === "models" ? {
+		...current,
+		models: body.defaults.models
+	} : body.scope === "agent" ? {
+		...body.defaults,
+		models: current.models
+	} : body.defaults;
+	const parsed = AgentDefaultsSchema.safeParse(requested);
 	if (!parsed.success) return {
 		ok: false,
 		error: `defaults ${parsed.error.issues[0]?.message ?? "is invalid"}`,
 		status: 400
 	};
-	const current = new AgentCatalogRepository().getSettings().defaults;
 	try {
 		validateComputerModelChange(parsed.data.models.computerUse, current.models.computerUse);
 	} catch (error) {

package/dist/src/gateway/hono/lib/config-payload.d.ts

@@ -27,7 +27,11 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
                     primary: string;
                     fallbacks: string[];
                 };
-                intents?: Partial<Record<"review" | "coding" | "fast" | "reasoning" | "vision" | "understanding", {
+                background?: {
+                    primary: string;
+                    fallbacks: string[];
+                };
+                intents?: Partial<Record<"review" | "coding" | "vision" | "fast" | "reasoning" | "understanding", {
                     primary: string;
                     fallbacks: string[];
                 }>>;
@@ -71,10 +75,14 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
                     primary: string;
                     fallbacks: string[];
                 };
-                intents: Partial<Record<"review" | "coding" | "fast" | "reasoning" | "vision" | "understanding", {
+                intents: Partial<Record<"review" | "coding" | "vision" | "fast" | "reasoning" | "understanding", {
                     primary: string;
                     fallbacks: string[];
                 }>>;
+                background?: {
+                    primary: string;
+                    fallbacks: string[];
+                };
                 imageUnderstanding?: {
                     primary: string;
                     fallbacks: string[];
@@ -320,6 +328,7 @@ export declare function buildSafeWebConfigPayload(service: GatewayService, optio
             betaCheckIntervalHours: number;
         };
     };
+    voiceSettingsRevisions: Record<"conversation" | "transcription" | "speech", string>;
     stt: unknown;
     tts: unknown;
     voice: unknown;

package/dist/src/gateway/hono/lib/config-payload.js

@@ -14,6 +14,7 @@ import { buildChannelCatalogForConfig, buildChannelCatalogFromSnapshot, getChann
 import { resolveSessionConfigForWeb, resolveUpdateConfigForWeb } from "../../../config/web-patch.js";
 import { GENERIC_MASKED_SECRET, maskSecretLength } from "./mask-secret-length.js";
 import { safeToolsWebForGet } from "../../config-tools-web.js";
+import { voiceSettingsRevisions } from "./voice-settings-revisions.js";
 import { buildSafeProvidersConfigForWeb } from "./safe-providers-config.js";
 import { maskRealtimeVoiceConfigForWeb, maskSttConfigForWeb, maskTtsConfigForWeb } from "./safe-voice-config.js";
 //#region src/gateway/hono/lib/config-payload.ts
@@ -155,6 +156,7 @@ async function buildSafeWebConfigPayload(service, options = {}) {
 			transport: { tls: "broker_terminated" }
 		},
 		update: { ...resolveUpdateConfigForWeb(config) },
+		voiceSettingsRevisions: voiceSettingsRevisions(config),
 		stt: maskSttConfigForWeb(config.tools?.media?.audio),
 		tts: maskTtsConfigForWeb(config.messages?.tts),
 		voice: maskRealtimeVoiceConfigForWeb(config.voice),

package/dist/src/gateway/hono/lib/voice-settings-revisions.d.ts

@@ -0,0 +1,5 @@
+import type { Config } from '../../../config/schema.js';
+export declare const VOICE_SETTING_SCOPES: readonly ["transcription", "speech", "conversation"];
+export type VoiceSettingScope = typeof VOICE_SETTING_SCOPES[number];
+/** Opaque per-capability versions; credentials never appear in the public snapshot. */
+export declare function voiceSettingsRevisions(config: Config): Record<VoiceSettingScope, string>;

package/dist/src/gateway/hono/lib/voice-settings-revisions.js

@@ -0,0 +1,24 @@
+import { createHmac, randomBytes } from "node:crypto";
+//#region src/gateway/hono/lib/voice-settings-revisions.ts
+const revisionKey = randomBytes(32);
+const VOICE_SETTING_SCOPES = [
+	"transcription",
+	"speech",
+	"conversation"
+];
+/** Opaque per-capability versions; credentials never appear in the public snapshot. */
+function voiceSettingsRevisions(config) {
+	const values = {
+		transcription: {
+			stt: config.tools?.media?.audio,
+			language: config.voice?.language,
+			languageMode: config.voice?.languageMode,
+			input: config.voice?.input
+		},
+		speech: config.messages?.tts,
+		conversation: config.voice?.realtime
+	};
+	return Object.fromEntries(VOICE_SETTING_SCOPES.map((scope) => [scope, createHmac("sha256", revisionKey).update(JSON.stringify(values[scope]) ?? "null").digest("hex")]));
+}
+//#endregion
+export { VOICE_SETTING_SCOPES, voiceSettingsRevisions };

package/dist/src/gateway/hono/routes/commands-skills.js

@@ -1,3 +1,5 @@
+import { getSessionMetadata } from "../../../storage/sqlite/session-read-repository.js";
+import { init_session_repository } from "../../../storage/sqlite/session-repository.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
 import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
 import { effectiveWorkspacePathForSession, projectWorkspacePath } from "../../../session/session-workspace.js";
@@ -12,6 +14,7 @@ import { buildReviewContext, resolveGitRoot } from "../../../review/review-git.j
 import "../../../chat-commands/index.js";
 //#region src/gateway/hono/routes/commands-skills.ts
 init_agent_scope();
+init_session_repository();
 function parseMarketplaceProviderQuery(raw) {
 	const v = raw?.trim().toLowerCase();
 	if (v && isRegisteredProvider(v)) return v;
@@ -86,6 +89,10 @@ function registerCommandsSkillsRoutes(authenticated, deps) {
 	});
 	authenticated.get("/api/chat/skills", async (c) => {
 		const conversationId = c.req.query("conversationId")?.trim();
+		if (conversationId && !getSessionMetadata(conversationId)) return c.json({
+			ok: false,
+			error: "Conversation not found"
+		}, 404);
 		const agentId = c.req.query("agentId")?.trim() || resolveDefaultAgentId();
 		const payload = conversationId ? await service.marketplace.getSessionSkillsApi(conversationId) : service.marketplace.getAgentSkillsApi(agentId);
 		return c.json({
@@ -99,6 +106,10 @@ function registerCommandsSkillsRoutes(authenticated, deps) {
 			ok: false,
 			error: "Missing conversationId"
 		}, 400);
+		if (!getSessionMetadata(conversationId)) return c.json({
+			ok: false,
+			error: "Conversation not found"
+		}, 404);
 		const payload = await service.marketplace.getSessionWorkspaceTrustApi(conversationId);
 		return c.json({
 			ok: true,
@@ -120,6 +131,10 @@ function registerCommandsSkillsRoutes(authenticated, deps) {
 			ok: false,
 			error: "Expected { conversationId: string, trusted: boolean }"
 		}, 400);
+		if (!getSessionMetadata(conversationId)) return c.json({
+			ok: false,
+			error: "Conversation not found"
+		}, 404);
 		const payload = await service.marketplace.setSessionWorkspaceTrustApi(conversationId, body.trusted);
 		return c.json({
 			ok: true,

package/dist/src/gateway/hono/routes/config-patch/misc.js

@@ -216,7 +216,14 @@ async function applyMiscPatch(config, body) {
 		config.messages.tts = mergeTtsConfigPatch(config.messages.tts, body.tts);
 	}
 	if (body.voice !== void 0) {
-		const parsed = VoiceConfigSchema.safeParse(mergeRealtimeVoiceConfigPatch(config.voice, body.voice));
+		if (!body.voice || typeof body.voice !== "object" || Array.isArray(body.voice)) return patchError("voice must be an object");
+		if (body.voice.realtime !== void 0 && (!body.voice.realtime || typeof body.voice.realtime !== "object" || Array.isArray(body.voice.realtime))) return patchError("voice.realtime must be an object");
+		if (body.voicePatchMode !== void 0 && body.voicePatchMode !== "merge") return patchError("Invalid voice patch mode");
+		const voicePatch = body.voicePatchMode === "merge" ? {
+			...config.voice,
+			...body.voice
+		} : body.voice;
+		const parsed = VoiceConfigSchema.safeParse(mergeRealtimeVoiceConfigPatch(config.voice, voicePatch));
 		if (!parsed.success) return patchError(parsed.error.issues.map((i) => i.message).join("; "));
 		config.voice = parsed.data;
 	}

package/dist/src/gateway/hono/routes/config.js

@@ -1,5 +1,6 @@
 import { enumerateLanGatewayCandidates, init_host } from "../../host.js";
 import { getTunnelService } from "../../../tunnel/tunnel-service.js";
+import { VOICE_SETTING_SCOPES, voiceSettingsRevisions } from "../lib/voice-settings-revisions.js";
 import { buildSafeWebConfigPayload } from "../lib/config-payload.js";
 import { withGatewayConfigWriteLock } from "../lib/config-write-lock.js";
 import { applyChannelsPatch } from "./config-patch/channels.js";
@@ -39,6 +40,17 @@ function registerConfigRoutes(authenticated, deps) {
 		const body = await c.req.json();
 		const expectedConfig = structuredClone(service.currentConfig);
 		const config = structuredClone(expectedConfig);
+		if (body.expectedVoiceRevision !== void 0) {
+			const guard = body.expectedVoiceRevision;
+			if (!guard || typeof guard !== "object" || !VOICE_SETTING_SCOPES.includes(guard.capability) || typeof guard.revision !== "string" || !/^[a-f0-9]{64}$/.test(guard.revision)) return c.json({
+				ok: false,
+				error: "Invalid voice settings revision"
+			}, 400);
+			if (voiceSettingsRevisions(expectedConfig)[guard.capability] !== guard.revision) return c.json({
+				ok: false,
+				error: "Voice settings changed. Reload before saving to preserve the current model."
+			}, 409);
+		}
 		applyChannelsPatch(config, body);
 		const gatewayResult = applyGatewayPatch(config, body);
 		if (gatewayResult.ok === false) return c.json({

package/dist/src/gateway/hono/routes/discussions.js

@@ -79,10 +79,67 @@ function registerDiscussionRoutes(authenticated, deps) {
 		const detail = await service.discussions.getByNoteId(c.req.param("noteId"));
 		return detail ? c.json(detail) : c.json({ error: "Discussion not found" }, 404);
 	});
+	authenticated.get("/api/discussions/:id/review", async (c) => {
+		try {
+			return c.json(await service.discussions.review(c.req.param("id"), {
+				query: c.req.query("q"),
+				offset: Number(c.req.query("offset") ?? 0),
+				limit: Number(c.req.query("limit") ?? 20),
+				version: c.req.query("version")
+			}));
+		} catch (error) {
+			const response = errorResponse(error);
+			if (response) return c.json(response.body, response.status);
+			throw error;
+		}
+	});
 	authenticated.get("/api/discussions/:id", async (c) => {
 		const detail = await service.discussions.get(c.req.param("id"));
 		return detail ? c.json(detail) : c.json({ error: "Discussion not found" }, 404);
 	});
+	authenticated.get("/api/discussions/:id/audio-clip", mediaRateLimitMiddleware, async (c) => {
+		try {
+			const bytes = await service.discussions.audioClip(c.req.param("id"), Number(c.req.query("startMs")), Number(c.req.query("endMs")), c.req.raw.signal);
+			c.header("Cache-Control", "no-store");
+			c.header("Content-Type", "audio/wav");
+			return c.body(new Uint8Array(bytes));
+		} catch (error) {
+			const response = errorResponse(error);
+			if (response) return c.json(response.body, response.status);
+			throw error;
+		}
+	});
+	authenticated.get("/api/discussions/:id/annotations", async (c) => {
+		try {
+			return c.json(await service.discussions.annotations(c.req.param("id")));
+		} catch (error) {
+			const response = errorResponse(error);
+			if (response) return c.json(response.body, response.status);
+			throw error;
+		}
+	});
+	authenticated.put("/api/discussions/:id/annotations/:annotationId", strictRateLimitMiddleware, async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		try {
+			return c.json(service.discussions.saveAnnotation(c.req.param("id"), {
+				...body,
+				id: c.req.param("annotationId")
+			}));
+		} catch (error) {
+			const response = errorResponse(error);
+			if (response) return c.json(response.body, response.status);
+			throw error;
+		}
+	});
+	authenticated.get("/api/discussions/:id/evidence", async (c) => {
+		try {
+			return c.json(await service.discussions.evidence(c.req.param("id"), Number(c.req.query("revision")), (c.req.query("segments") ?? "").split(",").filter(Boolean).map(Number)));
+		} catch (error) {
+			const response = errorResponse(error);
+			if (response) return c.json(response.body, response.status);
+			throw error;
+		}
+	});
 	authenticated.get("/api/discussions/:id/transcript", (c) => {
 		const transcript = service.discussions.transcript(c.req.param("id"), c.req.query("revision") === void 0 ? void 0 : Number(c.req.query("revision")));
 		return transcript ? c.json(transcript) : c.json({ error: "Discussion not found" }, 404);
@@ -243,6 +300,8 @@ function registerDiscussionRoutes(authenticated, deps) {
 				chunkCount: Number(body.chunkCount),
 				mimeType: typeof body.mimeType === "string" ? body.mimeType : "",
 				fileName: typeof body.fileName === "string" ? body.fileName : "",
+				...body.events !== void 0 ? { events: body.events } : {},
+				...body.epochs !== void 0 ? { epochs: body.epochs } : {},
 				...body.containerMode === "independent_wav" ? { containerMode: "independent_wav" } : {}
 			}), 202);
 		} catch (error) {
@@ -252,8 +311,11 @@ function registerDiscussionRoutes(authenticated, deps) {
 		}
 	});
 	authenticated.post("/api/discussions/:id/retry", strictRateLimitMiddleware, async (c) => {
+		const body = await c.req.json().catch(() => ({}));
+		if (!body || typeof body !== "object" || Array.isArray(body)) return c.json({ error: "Invalid retry request" }, 400);
+		if (body.mode !== void 0 && body.mode !== "resume" && body.mode !== "from_audio") return c.json({ error: "Invalid retry mode" }, 400);
 		try {
-			const detail = await service.discussions.retry(c.req.param("id"));
+			const detail = await service.discussions.retry(c.req.param("id"), body.mode === "from_audio" ? "from_audio" : "resume");
 			return detail ? c.json(detail) : c.json({ error: "Discussion not found" }, 404);
 		} catch (error) {
 			const response = errorResponse(error);

package/dist/src/gateway/hono/routes/global-defaults.js

@@ -6,8 +6,15 @@ init_agent_config();
 function parsePatchBody(raw) {
 	if (raw === null || typeof raw !== "object" || Array.isArray(raw)) return { error: "body must be an object" };
 	const body = raw;
+	if (body.scope !== void 0 && body.scope !== "models" && body.scope !== "agent") return { error: "scope must be models or agent" };
+	const expected = body.expectedModels === void 0 ? void 0 : AgentDefaultsSchema.shape.models.safeParse(body.expectedModels);
+	if (expected && !expected.success) return { error: "expectedModels is invalid" };
 	const parsed = AgentDefaultsSchema.safeParse(body.defaults);
-	return parsed.success ? { defaults: parsed.data } : { error: `defaults ${parsed.error.issues[0]?.message ?? "is invalid"}` };
+	return parsed.success ? {
+		defaults: parsed.data,
+		...body.scope ? { scope: body.scope } : {},
+		...expected?.success ? { expectedModels: expected.data } : {}
+	} : { error: `defaults ${parsed.error.issues[0]?.message ?? "is invalid"}` };
 }
 function isParseError(value) {
 	return typeof value === "object" && value !== null && "error" in value && typeof value.error === "string";

package/dist/src/gateway/hono/routes/models.js

@@ -1,3 +1,5 @@
+import { getProviderSetupProfile, init_profiles } from "../../../providers/setup/profiles.js";
+import { init_model_usage, withModelUsageOrigin } from "../../../providers/model-usage.js";
 import { resolveEffectiveAgentConfigForAgent } from "../../../config/agent-profile.js";
 import { init_resolve_config_value, testApiKeyResolution } from "../../../config/resolve-config-value.js";
 import { resolveModelsJsonPath } from "../../../config/paths.js";
@@ -20,11 +22,14 @@ import { applyImageGenerationCatalogUpdate, getAgentImageGenerationConfig, getDe
 import { discoverProviderModels, isProviderApiDiscoverable } from "../../../providers/model-discovery.js";
 import { getXopcCloudCatalogCoordinator } from "../../../providers/xopc-cloud-catalog-coordinator.js";
 import { respondStartupUnavailable } from "../lib/startup-unavailable.js";
-import { dismissXopcCloudOnboarding, getXopcCloudOnboardingStatus } from "../../xopc-cloud-onboarding.js";
 import { getDomesticProviderPreset, getDomesticProviderPresetIds } from "../../../providers/domestic-presets.js";
-import { auditModelReferences } from "../../../providers/model-reference-auditor.js";
 import { getOnboardingFeaturedProviders, getProviderHint, getRecommendedModelsForProvider, isRecommendedModel, sortModelsForPicker, sortProvidersForPicker } from "../../../providers/presentation.js";
+import { dismissXopcCloudOnboarding, getXopcCloudOnboardingStatus } from "../../xopc-cloud-onboarding.js";
+import { auditModelReferences } from "../../../providers/model-reference-auditor.js";
+import { registerProviderSetupRoutes } from "./provider-setup.js";
 //#region src/gateway/hono/routes/models.ts
+init_model_usage();
+init_profiles();
 init_model_policy();
 init_models_json();
 init_resolve_config_value();
@@ -83,6 +88,7 @@ function mapPluginModel(providerId, model, available) {
 	};
 }
 function registerModelsRoutes(authenticated, deps) {
+	registerProviderSetupRoutes(authenticated, deps);
 	const { service, strictRateLimitMiddleware } = deps;
 	const catalogSync = service.getModelCatalogSync();
 	const xopcCloudAccount = new XopcCloudAccountService();
@@ -518,14 +524,14 @@ function registerModelsRoutes(authenticated, deps) {
 		}, 400);
 		const prompt = typeof body.prompt === "string" && body.prompt.trim() ? body.prompt.trim() : "A simple blue circle centered on a white background.";
 		try {
-			const result = await provider.generateImage({
+			const result = await withModelUsageOrigin("interactive", () => provider.generateImage({
 				provider: providerId,
 				model: modelId,
 				prompt,
 				count: 1,
 				cfg: service.currentConfig,
 				timeoutMs: 12e4
-			});
+			}));
 			return c.json({
 				ok: true,
 				payload: {
@@ -744,6 +750,7 @@ function registerModelsRoutes(authenticated, deps) {
 			const registryModelCount = getAllModels().filter((m) => m.provider === provider).length;
 			return {
 				id: provider,
+				setupProfile: getProviderSetupProfile(provider, PROVIDER_META[provider]?.name ?? domesticPreset?.displayName ?? provider, PROVIDER_META[provider]?.supportsOAuth, resolveProviderApiBaseUrl(provider)),
 				name: plugin?.name ?? domesticPreset?.displayName ?? PROVIDER_META[provider]?.name ?? provider,
 				category: plugin ? "extension" : PROVIDER_META[provider]?.category || (domesticPreset ? "domestic" : "specialty"),
 				supportsOAuth: plugin ? false : PROVIDER_META[provider]?.supportsOAuth ?? false,
@@ -766,6 +773,7 @@ function registerModelsRoutes(authenticated, deps) {
 			const extensionId = resolveExtensionIdForProvider(service, plugin.id);
 			meta.push({
 				id: plugin.id,
+				setupProfile: getProviderSetupProfile(plugin.id, plugin.name),
 				name: plugin.name,
 				category: "extension",
 				supportsOAuth: false,

package/dist/src/gateway/hono/routes/provider-setup.d.ts

@@ -0,0 +1,3 @@
+import type { Hono } from 'hono';
+import type { AuthenticatedRouteDeps } from './deps.js';
+export declare function registerProviderSetupRoutes(app: Hono, deps: AuthenticatedRouteDeps): void;

package/dist/src/gateway/hono/routes/provider-setup.js

@@ -0,0 +1,106 @@
+import { listGlobalDefaults, prepareUpdateGlobalDefaults, updateGlobalDefaults } from "../../global-defaults-admin.js";
+import { applySetupVoice } from "../../../providers/setup/voice.js";
+import { loadProviderSetupSnapshot } from "../../provider-model-setup.js";
+import { SetupConflictError, applyProviderSetup, previewProviderSetup } from "../../../providers/setup/engine.js";
+import { withGatewayConfigWriteLock } from "../lib/config-write-lock.js";
+import { isDeepStrictEqual } from "node:util";
+import { z } from "zod";
+//#region src/gateway/hono/routes/provider-setup.ts
+const use = z.enum([
+	"chat",
+	"vision",
+	"image",
+	"background",
+	"speech",
+	"transcription",
+	"conversation"
+]);
+const requestSchema = z.object({
+	mode: z.enum(["fill", "replace"]).optional(),
+	selected: z.array(use).max(7).optional(),
+	overrides: z.partialRecord(use, z.string().min(1).max(512)).optional(),
+	modelIds: z.array(z.string().min(1).max(512)).max(500).optional()
+}).strict();
+const applySchema = requestSchema.extend({ revision: z.string().regex(/^[a-f0-9]{64}$/) });
+function registerProviderSetupRoutes(app, deps) {
+	app.get("/api/models/setup/:providerId", async (c) => {
+		try {
+			return c.json({
+				ok: true,
+				payload: previewProviderSetup(await loadProviderSetupSnapshot(c.req.param("providerId"), deps.service.currentConfig))
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: { message: error instanceof Error ? error.message : String(error) }
+			}, 400);
+		}
+	});
+	app.post("/api/models/setup/:providerId/preview", deps.strictRateLimitMiddleware, async (c) => {
+		const parsed = requestSchema.safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success) return c.json({
+			ok: false,
+			error: { message: "Invalid setup preview request" }
+		}, 400);
+		try {
+			return c.json({
+				ok: true,
+				payload: previewProviderSetup(await loadProviderSetupSnapshot(c.req.param("providerId"), deps.service.currentConfig), parsed.data)
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: { message: error instanceof Error ? error.message : String(error) }
+			}, 400);
+		}
+	});
+	app.post("/api/models/setup/:providerId/apply", deps.strictRateLimitMiddleware, async (c) => withGatewayConfigWriteLock(deps.service, async () => {
+		const parsed = applySchema.safeParse(await c.req.json().catch(() => null));
+		if (!parsed.success) return c.json({
+			ok: false,
+			error: { message: "Invalid setup apply request" }
+		}, 400);
+		let voiceSaved = false;
+		try {
+			const expectedConfig = structuredClone(deps.service.currentConfig);
+			const snapshot = await loadProviderSetupSnapshot(c.req.param("providerId"), expectedConfig);
+			if (!isDeepStrictEqual(deps.service.currentConfig, expectedConfig)) throw new SetupConflictError("Configuration changed while preparing setup. Review and retry.");
+			const applied = applyProviderSetup(snapshot, parsed.data, parsed.data.revision);
+			const prepared = prepareUpdateGlobalDefaults({ defaults: applied.defaults });
+			if (prepared.ok === false) return c.json({
+				ok: false,
+				error: { message: prepared.error }
+			}, prepared.status ?? 400);
+			if (applied.voiceAssignments.length) {
+				const next = applySetupVoice(expectedConfig, applied.voiceAssignments);
+				const saved = await deps.service.saveConfig(next, expectedConfig);
+				if (!saved.saved) return c.json({
+					ok: false,
+					error: { message: `${saved.persisted ? "Voice settings persisted but runtime reload failed" : "Voice settings were not saved"}: ${saved.error ?? "Configuration write failed"}` }
+				}, saved.conflict ? 409 : 500);
+				voiceSaved = true;
+				if (!isDeepStrictEqual(listGlobalDefaults().defaults, snapshot.defaults)) return c.json({
+					ok: false,
+					error: { message: "Voice settings saved; model defaults changed concurrently. Review the refreshed configuration before applying model uses." }
+				}, 409);
+			}
+			const result = updateGlobalDefaults({ defaults: applied.defaults });
+			if (result.ok === false) return c.json({
+				ok: false,
+				error: { message: result.error }
+			}, result.status ?? 400);
+			if (result.data.changed) deps.service.refreshAgentCatalog();
+			return c.json({
+				ok: true,
+				payload: applied.preview
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: { message: (voiceSaved ? "Voice settings saved; model setup incomplete. " : "") + (error instanceof Error ? error.message : String(error)) }
+			}, error instanceof SetupConflictError ? 409 : 400);
+		}
+	}));
+}
+//#endregion
+export { registerProviderSetupRoutes };