@xopcai/xopc 0.0.388 → 0.0.390

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

@@ -8,6 +8,7 @@ import { getConnectorSyncPolicy, upsertConnectorSyncPolicy } from "../../../stor
 import { init_sqlite } from "../../../storage/sqlite/index.js";
 import { AgentCatalogRepository, init_repository } from "../../../agent-catalog/repository.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
+import { listUnderstandingSourceGrants, revokeUnderstandingSourceGrant } from "../../../user-context/sources/repository.js";
 import { activateComposioBackend, addComposioBackend, ensureComposioBackend, getComposioBackend, listComposioBackends, removeComposioBackend } from "../../../connectors/composio-backends.js";
 import { getAuthorizationAttempt } from "../../../connectors/authorization-attempts.js";
 import { ComposioSessionsAdapter, resolveComposioApiKey } from "../../../connectors/composio-sessions.js";
@@ -26,7 +27,6 @@ import { startConnectorAuthorization } from "../../../connectors/auth-provider-r
 import { composioLogoResponse } from "../../../connectors/composio-logo.js";
 import { inspectManagedComposioStatus } from "../../../connectors/composio-managed-client.js";
 import { appendComposioTriggerEvent, listComposioTriggerEvents } from "../../../connectors/composio-triggers.js";
-import { listUnderstandingSourceGrants, revokeUnderstandingSourceGrant } from "../../../user-context/sources/repository.js";
 import { ingestLocalFolderSource } from "../../../connectors/connected-source-ingestion.js";
 import { testConnectorInstance } from "../../../connectors/health.js";
 import { setConnectorEnabled } from "../../../connectors/lifecycle.js";

package/dist/src/gateway/hono/routes/context-sources.js

@@ -3,10 +3,10 @@ import { getConnectorAccount } from "../../../storage/sqlite/connector-account-r
 import { countKnowledgeSourceItems, deleteKnowledgeSourceItems } from "../../../storage/sqlite/knowledge-repository.js";
 import { init_sqlite } from "../../../storage/sqlite/index.js";
 import { init_agent_scope, resolveDefaultAgentId } from "../../../agent/agent-scope.js";
-import { listUserModelObservations } from "../../../user-model/observation-repository.js";
 import { getActiveUnderstandingConsent } from "../../../user-context/sources/consent-repository.js";
-import "../../../user-model/index.js";
 import { getUnderstandingSourceGrant, listUnderstandingSourceGrants, listUnderstandingSourceRuns, revokeUnderstandingSourceGrant, updateUnderstandingSourceGrantPolicies } from "../../../user-context/sources/repository.js";
+import { listUserModelObservations } from "../../../user-model/observation-repository.js";
+import "../../../user-model/index.js";
 import { listConnectedContentCandidates, readConnectedContent } from "../../../connectors/content-enrichment.js";
 import { listUnderstandingSourceDefinitions } from "../../../user-context/sources/catalog.js";
 //#region src/gateway/hono/routes/context-sources.ts

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/endpoint-tools.js

@@ -5,9 +5,9 @@ import { endpointPrincipalRegistrationSchema, endpointSessionBindingRequestSchem
 import { createEndpointPrincipal, getEndpointPrincipal, listEndpointPrincipals, revokeEndpointPrincipal } from "../../../storage/sqlite/endpoint-principal-repository.js";
 import { listEndpointToolInvocationAuditPage } from "../../../storage/sqlite/endpoint-tool-invocation-repository.js";
 import { init_sqlite } from "../../../storage/sqlite/index.js";
+import { getEndpointDeviceSettings, renameEndpointDevice } from "../../../storage/sqlite/endpoint-device-settings-repository.js";
 import { parseEndpointPublicKey } from "../../../endpoint-tools/auth.js";
 import { ENDPOINT_UPLOAD_MAX_BYTES, EndpointUploadError } from "../../../endpoint-tools/upload-service.js";
-import { getEndpointDeviceSettings, renameEndpointDevice } from "../../../storage/sqlite/endpoint-device-settings-repository.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { z } from "zod";
 //#region src/gateway/hono/routes/endpoint-tools.ts

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/home.js

@@ -3,9 +3,9 @@ import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { acknowledgeHomeAttention } from "../../../storage/sqlite/home-attention-repository.js";
 import { decideConnectorApproval } from "../../../storage/sqlite/connector-repository.js";
 import { init_sqlite } from "../../../storage/sqlite/index.js";
-import { resumeApprovedConnectorAction } from "../../../connectors/approval-resume.js";
 import { listGatewayAgents } from "../../agents-admin.js";
 import { HomeQueryService, buildHomeWorkbench, decisionFromTask } from "../../../tasks/home-query-service.js";
+import { resumeApprovedConnectorAction } from "../../../connectors/approval-resume.js";
 import { HomeOpportunityActionError, HomeOpportunityNotFoundError } from "../../../home-intelligence/application-service.js";
 //#region src/gateway/hono/routes/home.ts
 init_src();

package/dist/src/gateway/hono/routes/lazy-bundles.js

@@ -449,7 +449,7 @@ const AUTHENTICATED_LAZY_ROUTE_BUNDLES = [
 	},
 	{
 		id: "mcp",
-		match: (path) => path === "/api/mcp/servers" || /^\/api\/mcp\/servers\/[^/]+\/(tools|probe|auth)$/.test(path) || /^\/api\/mcp\/auth\/[^/]+(?:\/redirect)?$/.test(path),
+		match: (path) => path === "/api/mcp/servers" || /^\/api\/mcp\/servers\/[^/]+$/.test(path) || path === "/api/mcp/drafts" || /^\/api\/mcp\/drafts\/[^/]+(?:\/(?:probe|commit|tools|auth(?:\/redirect)?))?$/.test(path) || /^\/api\/mcp\/servers\/[^/]+\/(tools|probe|auth)$/.test(path) || /^\/api\/mcp\/auth\/[^/]+(?:\/redirect)?$/.test(path),
 		load: async () => {
 			const { registerMcpRoutes } = await import("./mcp.js");
 			return { register: registerMcpRoutes };

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

@@ -1,11 +1,70 @@
-import { isManagedConnectorServer } from "../../../connectors/materialize.js";
 import { getWorkspacePath } from "../../../config/workspace-path-helpers.js";
+import { isManagedConnectorServer } from "../../../connectors/materialize.js";
 import { loadMergedMcpConfig } from "../../../agent/mcp/config.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { discoverMcpTools } from "../../../agent/mcp/tool-catalog.js";
 import { cancelMcpAuthorization, getMcpAuthorization, probeMcpConnection, startMcpAuthorization, submitMcpRedirect } from "../../../agent/mcp/connection-setup.js";
+import { McpConnectionDrafts, McpDraftError, mcpConfigRevision } from "../../../agent/mcp/connection-drafts.js";
+import { withGatewayConfigWriteLock } from "../lib/config-write-lock.js";
 //#region src/gateway/hono/routes/mcp.ts
 function registerMcpRoutes(app, deps) {
+	const drafts = new McpConnectionDrafts({
+		readConfig: () => deps.service.currentConfig,
+		saveConfig: (config, expected) => deps.service.saveConfig(config, expected)
+	});
+	const owner = (c) => getGatewayPrincipal(c).principalId;
+	const draftRoute = (handler) => async (c) => {
+		try {
+			return c.json({
+				ok: true,
+				payload: await handler(c)
+			});
+		} catch (error) {
+			return c.json({
+				ok: false,
+				error: error instanceof McpDraftError ? error.message : "MCP draft operation failed."
+			}, error instanceof McpDraftError ? error.status : 500);
+		}
+	};
+	app.post("/api/mcp/drafts", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body || typeof body.serverId !== "string" || body.sourceServerId !== void 0 && typeof body.sourceServerId !== "string") throw new McpDraftError(400, "Invalid MCP draft request.");
+		return drafts.create(owner(c), body);
+	}));
+	app.post("/api/mcp/drafts/:id/probe", deps.strictRateLimitMiddleware, draftRoute((c) => drafts.probe(owner(c), c.req.param("id"))));
+	app.post("/api/mcp/drafts/:id/auth", deps.strictRateLimitMiddleware, draftRoute((c) => drafts.authorize(owner(c), c.req.param("id"))));
+	app.get("/api/mcp/drafts/:id/auth", draftRoute((c) => drafts.authorization(owner(c), c.req.param("id"))));
+	app.delete("/api/mcp/drafts/:id/auth", draftRoute((c) => drafts.cancelAuthorization(owner(c), c.req.param("id"))));
+	app.post("/api/mcp/drafts/:id/auth/redirect", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (typeof body?.url !== "string" || body.url.length >= 16384) throw new McpDraftError(400, "Invalid callback address.");
+		drafts.redirect(owner(c), c.req.param("id"), body.url);
+	}));
+	app.post("/api/mcp/drafts/:id/commit", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body || body.enable !== void 0 && typeof body.enable !== "boolean") throw new McpDraftError(400, "Invalid commit request.");
+		return withGatewayConfigWriteLock(deps.service, () => drafts.commit(owner(c), c.req.param("id"), body.enable === true));
+	}));
+	app.get("/api/mcp/drafts/:id/tools", deps.strictRateLimitMiddleware, draftRoute(async (c) => ({ tools: await drafts.tools(owner(c), c.req.param("id")) })));
+	app.delete("/api/mcp/drafts/:id", draftRoute((c) => drafts.remove(owner(c), c.req.param("id"))));
+	app.delete("/api/mcp/servers/:id", deps.strictRateLimitMiddleware, draftRoute(async (c) => {
+		const body = await c.req.json().catch(() => null);
+		if (!body?.expectedServer || typeof body.expectedServer !== "object" || Array.isArray(body.expectedServer)) throw new McpDraftError(400, "The expected server configuration is required.");
+		return withGatewayConfigWriteLock(deps.service, async () => {
+			const current = deps.service.currentConfig, id = c.req.param("id");
+			const server = Object.hasOwn(current.mcp?.servers ?? {}, id) ? current.mcp?.servers?.[id] : void 0;
+			if (!server || isManagedConnectorServer(server) || mcpConfigRevision(server) !== mcpConfigRevision(body.expectedServer)) throw new McpDraftError(409, "The custom server changed. Reload before removing it.");
+			const next = structuredClone(current);
+			delete next.mcp.servers[id];
+			const result = await deps.service.saveConfig(next, structuredClone(current));
+			if (result.conflict) throw new McpDraftError(409, "Configuration changed before removing the server.");
+			if (!result.saved && !result.persisted) throw new McpDraftError(500, "Could not remove the server.");
+			return {
+				serverId: id,
+				...!result.saved ? { reloadRequired: true } : {}
+			};
+		});
+	}));
 	app.post("/api/mcp/servers/:id/probe", deps.strictRateLimitMiddleware, async (c) => {
 		const config = deps.service.currentConfig;
 		const id = c.req.param("id");
@@ -101,12 +160,20 @@ function registerMcpRoutes(app, deps) {
 		return c.json({
 			ok: true,
 			payload: {
-				servers: Object.entries(merged.config.mcpServers).map(([id, server]) => ({
-					id,
-					plugin: server.xopcPlugin,
-					managed: isManagedConnectorServer(server),
-					connectorId: isManagedConnectorServer(server) ? server.xopcConnector.connectorId : void 0
-				})).sort((a, b) => a.id.localeCompare(b.id)),
+				servers: Object.entries(merged.config.mcpServers).map(([id, server]) => {
+					const { xopcConnectionCheck, ...configuration } = server;
+					const check = xopcConnectionCheck;
+					return {
+						id,
+						plugin: server.xopcPlugin,
+						lastCheck: check?.revision === mcpConfigRevision(configuration) ? {
+							checkedAt: check.checkedAt,
+							toolCount: check.toolCount
+						} : void 0,
+						managed: isManagedConnectorServer(server),
+						connectorId: isManagedConnectorServer(server) ? server.xopcConnector.connectorId : void 0
+					};
+				}).sort((a, b) => a.id.localeCompare(b.id)),
 				mergedServerIds: Object.keys(merged.config.mcpServers).sort(),
 				configured: cfg.mcp?.servers ?? {}
 			}

package/dist/src/gateway/hono/routes/memory-learning.js

@@ -3,12 +3,12 @@ import { getSessionMetadata } from "../../../storage/sqlite/session-read-reposit
 import { init_session_repository } from "../../../storage/sqlite/session-repository.js";
 import { getSessionConfig, init_config_repository } from "../../../storage/sqlite/config-repository.js";
 import { bindOwnerIdentity } from "../../../user-context/identity-bindings.js";
-import { resolveEffectiveAgentProfileForSession } from "../../../config/agent-profile.js";
-import { init_config, resolveKnowledgeReadPolicy } from "../../../user-context/config.js";
 import { canUseKnowledge, knowledgeExclusion } from "../../../knowledge-memory/usage-policy.js";
 import { getKnowledgeItem } from "../../../knowledge-memory/repository.js";
-import "../../../knowledge-memory/index.js";
+import { init_config, resolveKnowledgeReadPolicy } from "../../../user-context/config.js";
 import { enqueueConversationLearning, learningStatus } from "../../../memory-learning/repository.js";
+import "../../../knowledge-memory/index.js";
+import { resolveEffectiveAgentProfileForSession } from "../../../config/agent-profile.js";
 //#region src/gateway/hono/routes/memory-learning.ts
 init_config_repository();
 init_transaction();

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

@@ -1,6 +1,8 @@
-import { resolveModelsJsonPath } from "../../../config/paths.js";
+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";
 import { computerModelProfile, init_model_policy, isDedicatedComputerModel } from "../../../computer/model-policy.js";
 import { init_models_json, loadModelsJson, saveModelsJson, validateModelsConfig } from "../../../config/models-json.js";
 import { getModelCatalogStore, init_model_catalog_store } from "../../../providers/model-catalog-store.js";
@@ -10,21 +12,24 @@ import "../../../providers/constants.js";
 import { getProviderRegistry, init_plugin_registry } from "../../../providers/plugin-registry.js";
 import { PROVIDER_META, getAllModels, getAllProviders, getAvailableModels, getProviderAuthState, init_providers, isProviderConfigured, isProviderConfiguredSync } from "../../../providers/index.js";
 import { XopcCloudAccountError, XopcCloudAccountService } from "../../../providers/xopc-cloud-account-service.js";
-import { deleteCustomImageProvider, listCustomImageProviders, upsertCustomImageProvider } from "../../custom-image-providers.js";
-import { getImageGenerationProvider, reloadImageGenerationProviders, resolveImageGenerationCredentialMode } from "../../../agent/image/generation/provider-registry.js";
-import { applyImageGenerationCatalogUpdate, getAgentImageGenerationConfig, getDefaultImageGenerationConfig, getImageGenerationCatalog, prepareDefaultImageGenerationSetup, prepareImageGenerationSetup, verifyImageGenerationCredential } from "../../image-generation-setup.js";
 import { buildCapabilityPlansForConfig } from "../../../capabilities/readiness/from-config.js";
 import "../../../capabilities/readiness/index.js";
-import { SessionConfigStore } from "../../../session/config-store.js";
 import { getModelThinking } from "../../../providers/model-thinking.js";
+import { getImageGenerationProvider, reloadImageGenerationProviders, resolveImageGenerationCredentialMode } from "../../../agent/image/generation/provider-registry.js";
+import { SessionConfigStore } from "../../../session/config-store.js";
+import { deleteCustomImageProvider, listCustomImageProviders, upsertCustomImageProvider } from "../../custom-image-providers.js";
+import { applyImageGenerationCatalogUpdate, getAgentImageGenerationConfig, getDefaultImageGenerationConfig, getImageGenerationCatalog, prepareDefaultImageGenerationSetup, prepareImageGenerationSetup, verifyImageGenerationCredential } from "../../image-generation-setup.js";
 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/notes.js

@@ -5,9 +5,9 @@ import "../../../capabilities/runtime/dispatcher.js";
 import { init_session_key, resolveConversationId } from "../../../routing/session-key.js";
 import { agentExists, getDefaultAgentId, init_resolve_route } from "../../../routing/resolve-route.js";
 import { resolveGatewayEffectiveHost } from "../../../config/gateway-bind.js";
-import { resolveReverseProxyPublicUrl } from "../../public-url.js";
 import { getShareStore } from "../../../share/share-store.js";
 import { resolveShareUrl } from "../../../share/share-url.js";
+import { resolveReverseProxyPublicUrl } from "../../public-url.js";
 import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { capabilityHttpContext, capabilityHttpError } from "../../../capabilities/adapters/http.js";

package/dist/src/gateway/hono/routes/personal-agent.js

@@ -2,8 +2,8 @@ import { getDevice, init_device_access_repository } from "../../../storage/sqlit
 import { getPersonalRequest, init_request_repository, listPersonalRequests } from "../../../personal-agent/request-repository.js";
 import { getPersonalAgent } from "../../../personal-agent/repository.js";
 import { TaskOriginRepository } from "../../../tasks/task-origin-repository.js";
-import { cancelPersonalRequest, personalRequestSnapshot, publishPersonalRequest } from "../../../personal-agent/request-service.js";
 import { writeAgentAvatarFromBase64 } from "../../agents-admin.js";
+import { cancelPersonalRequest, personalRequestSnapshot, publishPersonalRequest } from "../../../personal-agent/request-service.js";
 import { PersonalOnboardingDraftSchema, PersonalOnboardingStepSchema, finishPersonalWelcome, getPersonalOnboarding, savePersonalOnboarding } from "../../../personal-agent/onboarding.js";
 import { PersonalAppearanceSchema, PersonalPreferencesSchema, createOrResumePersonalAgent, ensurePersonalConversationVisibility, listPersonalModels, patchPersonalProfile, refreshPersonalDelegationGuidance } from "../../../personal-agent/service.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";

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

@@ -9,6 +9,9 @@ import { ActivityService } from "../../../activity/service.js";
 import "../../../activity/index.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
+import { listKnowledgeItems, writeKnowledgeItem } from "../../../knowledge-memory/repository.js";
+import "../../../knowledge-memory/index.js";
+import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
 import { TaskReadModelProjector } from "../../../tasks/task-read-model-projector.js";
 import { ProjectWorkspaceConflictError, ProjectWorkspaceMissingError } from "../../../projects/workspace-project.js";
 import { inferProjectExecutionMode, inferProjectKind } from "../../../projects/project-kind.js";
@@ -16,12 +19,9 @@ import { ProjectDeletionBlockedError, ProjectWorkspaceInUseError } from "../../.
 import { resolveProjectAgentId } from "../../../projects/project-agent.js";
 import { inferSuggestedProjectDefaultAgentId } from "../../../projects/project-agent-suggestion.js";
 import { buildProjectLoopOverview } from "../../../projects/project-loop.js";
-import { resolveEffectiveAgentProfile } from "../../../config/agent-profile.js";
 import "../../../projects/index.js";
 import { defineTaskContract } from "../../../tasks/task-contract-definition.js";
 import { TaskApplicationService } from "../../../tasks/task-application-service.js";
-import { listKnowledgeItems, writeKnowledgeItem } from "../../../knowledge-memory/repository.js";
-import "../../../knowledge-memory/index.js";
 import { createProductDispatcher } from "../../../capabilities/runtime/product.js";
 import { ProjectOperatingViewService, summarizeProjectOperatingView } from "../../../tasks/project-operating-view-service.js";
 import "../../../tasks/index.js";

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 };

package/dist/src/gateway/hono/routes/runtime-tools.js

@@ -1,7 +1,7 @@
 import { init_paths_state, resolveStateDir } from "../../../config/paths-state.js";
+import { RuntimeToolsConfigSchema, init_schema } from "../../../config/schema.js";
 import { normalizeRuntimeVersionRequest } from "../../../runtime-tools/probe.js";
 import { ManagedRuntimeManager } from "../../../runtime-tools/manager.js";
-import { RuntimeToolsConfigSchema, init_schema } from "../../../config/schema.js";
 import { createGatewayRouteLogger } from "../lib/route-logger.js";
 import { pruneRuntimeTools } from "../../../runtime-tools/prune.js";
 import { streamSSE } from "hono/streaming";

package/dist/src/gateway/hono/routes/session-command-handler.js

@@ -5,12 +5,12 @@ import { sessionInputCommandSchema, sessionMaterializeCommandSchema } from "../.
 import { parseUserTurnDocument, userTurnDocumentRefIds } from "../../../../packages/gateway-contract/src/user-turn-document.js";
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
+import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
 import { parseSlashCommand } from "../../../chat-commands/command-parse.js";
 import { commandRegistry } from "../../../chat-commands/registry.js";
 import "../../../chat-commands/index.js";
-import { deviceTurnSourceContext, endpointClaimBelongsToPrincipal } from "../../../endpoint-tools/turn-context.js";
-import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
 import { isVoiceLikeAttachment } from "../../../channels/attachments/voice-stt-webchat.js";
+import { deviceTurnSourceContext, endpointClaimBelongsToPrincipal } from "../../../endpoint-tools/turn-context.js";
 import { SessionCommandError, getSessionInputReceipt, isConversationDeleted, retrySessionPreparation } from "../../../storage/sqlite/session-creation-repository.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { browserPageContextToAgentContext } from "../../../agent/source-context/browser-page.js";

package/dist/src/gateway/hono/routes/session-input-handler.js

@@ -7,16 +7,16 @@ import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import { endpointTurnClaimSchema, init_src as init_src$1 } from "../../../../packages/endpoint-tools-protocol/src/index.js";
 import { CapabilityError } from "../../../capabilities/runtime/errors.js";
 import "../../../capabilities/runtime/dispatcher.js";
-import { parseTurnContextRefs } from "../../../agent/source-context/types.js";
 import { init_providers, resolveModel } from "../../../providers/index.js";
+import { getModelThinking } from "../../../providers/model-thinking.js";
+import { parseTurnContextRefs } from "../../../agent/source-context/types.js";
+import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
+import { isTaskDestructiveCommand } from "../../../session/reset-triggers.js";
 import { parseSlashCommand } from "../../../chat-commands/command-parse.js";
 import { commandRegistry } from "../../../chat-commands/registry.js";
 import "../../../chat-commands/index.js";
-import { deviceTurnSourceContext, endpointClaimBelongsToPrincipal } from "../../../endpoint-tools/turn-context.js";
-import { validateWebchatAttachments, validateWebchatContent } from "../../chat-limits.js";
-import { isTaskDestructiveCommand } from "../../../session/reset-triggers.js";
-import { getModelThinking } from "../../../providers/model-thinking.js";
 import { isVoiceLikeAttachment } from "../../../channels/attachments/voice-stt-webchat.js";
+import { deviceTurnSourceContext, endpointClaimBelongsToPrincipal } from "../../../endpoint-tools/turn-context.js";
 import { withModelConfigLock } from "../../../session/model-config-lock.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { browserPageContextToAgentContext } from "../../../agent/source-context/browser-page.js";

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

@@ -3,11 +3,11 @@ import { SessionDiscoveryQuerySchema } from "../../../../packages/gateway-contra
 import { init_src } from "../../../../packages/gateway-contract/src/index.js";
 import "../../../session/types.js";
 import { SidebarLayoutConflictError, getSidebarLayout, init_sidebar_layout_repository, replaceSidebarLayout, sortBySidebarLayout } from "../../../storage/sqlite/sidebar-layout-repository.js";
-import { isPersonalConversation } from "../../../personal-agent/repository.js";
 import { summarizeAiUsageByConversations } from "../../../storage/sqlite/ai-usage-repository.js";
-import { SessionEnvironmentService } from "../../../execution-environments/session-environment-service.js";
-import { evictEmbeddedSessionRunner } from "../../../agent/embedded/session-runner.js";
+import { isPersonalConversation } from "../../../personal-agent/repository.js";
 import { messagesToClientHistory } from "../../../session/client-history.js";
+import { evictEmbeddedSessionRunner } from "../../../agent/embedded/session-runner.js";
+import { SessionEnvironmentService } from "../../../execution-environments/session-environment-service.js";
 import { deleteMediaUrisNoLongerReferenced } from "../../../media/session-references.js";
 import { getGatewayPrincipal } from "../../security/gateway-principal.js";
 import { createGatewayRouteLogger, logRouteError } from "../lib/route-logger.js";