@oscharko-dev/keiko 0.2.0-beta.6 → 0.2.0-beta.8

package/node_modules/@oscharko-dev/keiko-server/dist/gateway-setup.js

@@ -9,7 +9,9 @@ import { apiKeyHeaderValue, ConfigInvalidError, DEFAULT_API_KEY_HEADER_NAME, Gat
 import { gatewayFetch, readJsonCapped } from "@oscharko-dev/keiko-model-gateway/internal/http";
 import { redact } from "@oscharko-dev/keiko-security";
 import { errorBody } from "./routes.js";
-import { currentGatewayEgressConfig } from "./deps.js";
+import { currentGatewayConfig, currentGatewayEgressConfig } from "./deps.js";
+import { classifyFigmaTransportError, FigmaConnectorError, } from "./qualityIntelligence/figma/figmaConnectorErrors.js";
+import { classifyTokenFailure } from "./qualityIntelligence/figma/figmaTokenSource.js";
 const MAX_BODY_BYTES = 64_000;
 // Issue #144: exported so discovery-normalization tests can pin the slice cap
 // without hardcoding the number. The discovery surface is a public seam.
@@ -18,8 +20,11 @@ const MAX_DEPLOYMENT_NAMES = 100;
 const MAX_MODEL_ID_LENGTH = 160;
 const DISCOVERED_MODEL_SMOKE_TIMEOUT_MS = 15_000;
 const DEPLOYMENT_SMOKE_TIMEOUT_MS = 30_000;
+const FIGMA_CREDENTIAL_SMOKE_TIMEOUT_MS = 15_000;
+const FIGMA_CREDENTIAL_SMOKE_RESPONSE_BYTES = 64_000;
 const SETUP_SMOKE_CONCURRENCY = 4;
 const CHAT_COMPATIBLE_MODES = new Set(["chat", "completion", "responses"]);
+const EMBEDDING_ID_PATTERN = /(?:^|[-_/. ])(?:text-)?embed(?:ding)?s?(?:[-_/. ]|$)|ada-002(?:$|[-_/. ])/i;
 class BodyTooLargeError extends Error {
     constructor() {
         super("request body too large");
@@ -99,7 +104,9 @@ function isAzureFoundryBaseUrl(baseUrl) {
     }
 }
 function providerRaw(modelId, baseUrl, apiKey, options = {}) {
-    const defaultCapability = createDefaultChatCapability(modelId);
+    const defaultCapability = options.embeddingModelIds?.includes(modelId) === true
+        ? createDefaultEmbeddingCapabilityForSetup(modelId)
+        : createDefaultChatCapability(modelId);
     return {
         modelId,
         baseUrl,
@@ -110,15 +117,80 @@ function providerRaw(modelId, baseUrl, apiKey, options = {}) {
             : defaultCapability,
         timeoutMs: options.timeoutMs ?? 30_000,
         maxRetries: options.maxRetries ?? 2,
-        retryBaseDelayMs: 500,
+        retryBaseDelayMs: options.retryBaseDelayMs ?? 500,
     };
 }
+function isLikelyEmbeddingModelId(modelId) {
+    return EMBEDDING_ID_PATTERN.test(modelId);
+}
+function createDefaultEmbeddingCapabilityForSetup(modelId) {
+    return {
+        id: modelId,
+        kind: "embedding",
+        contextWindow: 8_191,
+        maxOutputTokens: 0,
+        toolCalling: false,
+        structuredOutput: false,
+        streaming: false,
+        supportsImageInput: false,
+        supportsDocumentInput: false,
+        workflowEligible: false,
+        costClass: "low",
+        latencyClass: "fast",
+        throughputHint: "runtime-configured embedding endpoint",
+        preferredUseCases: ["Embeddings"],
+        knownLimitations: [
+            "Runtime-configured capability; validate against the target endpoint before production use",
+        ],
+    };
+}
+function mergeChatAndEmbeddingModelIds(chatModelIds, deploymentNames) {
+    const merged = [...chatModelIds];
+    const seen = new Set(merged);
+    for (const modelId of deploymentNames) {
+        if (!isLikelyEmbeddingModelId(modelId) || seen.has(modelId)) {
+            continue;
+        }
+        seen.add(modelId);
+        merged.push(modelId);
+    }
+    return merged;
+}
+function embeddingModelIdsFromDeployments(deploymentNames) {
+    return deploymentNames.filter(isLikelyEmbeddingModelId);
+}
 function buildRawConfig(baseUrl, apiKey, modelIds, options = {}) {
     return {
         providers: modelIds.map((modelId) => providerRaw(modelId, baseUrl, apiKey, options)),
         circuitBreaker: { failureThreshold: 5, cooldownMs: 30_000, halfOpenProbes: 2 },
     };
 }
+function currentImageInputModelIds(config) {
+    return (config?.capabilities
+        ?.filter((capability) => capability.kind === "chat" && capability.supportsImageInput)
+        .map((capability) => capability.id) ?? []);
+}
+function rawConfigFromCurrent(config, figmaAccessToken) {
+    return {
+        providers: config.providers.map((provider) => {
+            const capability = config.capabilities?.find((item) => item.id === provider.modelId);
+            return {
+                modelId: provider.modelId,
+                baseUrl: provider.baseUrl,
+                apiKey: provider.apiKey,
+                apiKeyHeaderName: provider.apiKeyHeaderName ?? DEFAULT_API_KEY_HEADER_NAME,
+                timeoutMs: provider.timeoutMs,
+                maxRetries: provider.maxRetries,
+                retryBaseDelayMs: provider.retryBaseDelayMs,
+                ...(capability === undefined ? {} : { capability }),
+            };
+        }),
+        circuitBreaker: config.circuitBreaker,
+        ...(config.capabilities === undefined ? {} : { capabilities: config.capabilities }),
+        ...(config.grounding === undefined ? {} : { grounding: config.grounding }),
+        ...(figmaAccessToken === undefined ? {} : { figma: { accessToken: figmaAccessToken } }),
+    };
+}
 function withInheritedEgress(rawConfig, egress) {
     if (egress === undefined || Object.hasOwn(rawConfig, "egress")) {
         return rawConfig;
@@ -382,6 +454,46 @@ async function defaultGatewaySetupTester(config, candidateModelIds) {
         });
     }, SETUP_SMOKE_CONCURRENCY);
 }
+const FIGMA_ME_ENDPOINT = "https://api.figma.com/v1/me";
+function figmaReason(body) {
+    if (!isRecord(body))
+        return undefined;
+    const reason = body.err ?? body.message;
+    return typeof reason === "string" ? reason : undefined;
+}
+async function defaultFigmaCredentialTester(accessToken, egress) {
+    try {
+        const response = await gatewayFetch(FIGMA_ME_ENDPOINT, {
+            method: "GET",
+            headers: {
+                Accept: "application/json",
+                "X-Figma-Token": accessToken,
+            },
+            redirect: "manual",
+            signal: AbortSignal.timeout(FIGMA_CREDENTIAL_SMOKE_TIMEOUT_MS),
+            ...(egress !== undefined ? { egress } : {}),
+        });
+        let body;
+        try {
+            body = await readJsonCapped(response, FIGMA_CREDENTIAL_SMOKE_RESPONSE_BYTES);
+        }
+        catch {
+            throw new FigmaConnectorError("FIGMA_RESPONSE_TOO_LARGE");
+        }
+        if (!response.ok) {
+            throw classifyTokenFailure(response.status, figmaReason(body));
+        }
+        if (!isRecord(body)) {
+            throw new FigmaConnectorError("FIGMA_INTERNAL");
+        }
+    }
+    catch (error) {
+        if (error instanceof FigmaConnectorError) {
+            throw error;
+        }
+        throw new FigmaConnectorError(classifyFigmaTransportError(error));
+    }
+}
 function savePrivateJson(path, raw) {
     const resolvedPath = resolve(path);
     const dir = dirname(resolvedPath);
@@ -456,39 +568,111 @@ function readSetupModelLists(raw) {
     }
     return { deploymentNames, imageInputModelIds };
 }
-function readSetupRequest(raw, env) {
-    if (!isRecord(raw)) {
-        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+function optionalSetupSecret(value, path) {
+    if (value === undefined) {
+        return undefined;
+    }
+    if (typeof value !== "string") {
+        return { status: 400, body: errorBody("BAD_REQUEST", `${path} must be a string.`) };
+    }
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function hasNonBlankStringField(raw, key) {
+    const value = raw[key];
+    return typeof value === "string" && value.trim().length > 0;
+}
+function hasNonEmptyListField(raw, key) {
+    const value = raw[key];
+    if (typeof value === "string") {
+        return normalizeDeploymentNames(deploymentNameValues(value) ?? []).length > 0;
     }
-    const baseUrl = typeof raw.baseUrl === "string" ? raw.baseUrl.trim() : "";
-    const apiKey = typeof raw.apiKey === "string" ? raw.apiKey.trim() : "";
+    return Array.isArray(value) && value.some((item) => typeof item === "string" && item.trim());
+}
+function shouldPreserveExisting(raw, current) {
+    return raw.preserveExisting === true && current !== undefined;
+}
+function firstProvider(current) {
+    return current?.providers[0];
+}
+function trimmedSubmittedString(raw, key) {
+    const value = raw[key];
+    if (typeof value !== "string")
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed.length === 0 ? undefined : trimmed;
+}
+function submittedOrInheritedString(raw, key, inherited, preserveExisting) {
+    return trimmedSubmittedString(raw, key) ?? (preserveExisting ? (inherited ?? "") : "");
+}
+function setupApiKeyHeaderSource(raw, provider, preserveExisting) {
+    if (raw.apiKeyHeaderName !== undefined || !preserveExisting) {
+        return raw.apiKeyHeaderName;
+    }
+    return provider?.apiKeyHeaderName ?? DEFAULT_API_KEY_HEADER_NAME;
+}
+function readSetupGatewayCredentials(raw, env, current, preserveExisting) {
+    const provider = firstProvider(current);
+    const baseUrl = submittedOrInheritedString(raw, "baseUrl", provider?.baseUrl, preserveExisting);
+    const apiKey = submittedOrInheritedString(raw, "apiKey", provider?.apiKey, preserveExisting);
     if (baseUrl.length === 0 || apiKey.length === 0) {
         return { status: 400, body: errorBody("BAD_REQUEST", "baseUrl and apiKey are required.") };
     }
-    const apiKeyHeaderName = normalizeSetupApiKeyHeaderName(raw.apiKeyHeaderName);
+    const apiKeyHeaderSource = setupApiKeyHeaderSource(raw, provider, preserveExisting);
+    const apiKeyHeaderName = normalizeSetupApiKeyHeaderName(apiKeyHeaderSource);
     if (isRouteResult(apiKeyHeaderName)) {
         return apiKeyHeaderName;
     }
+    const invalidConnection = validateSetupConnection(baseUrl, apiKey, apiKeyHeaderName, env);
+    if (invalidConnection !== undefined) {
+        return invalidConnection;
+    }
+    return { baseUrl, apiKey, apiKeyHeaderName };
+}
+function resolveSetupModelLists(modelLists, current, preserveExisting) {
+    const existing = preserveExisting ? current : undefined;
+    return {
+        deploymentNames: existing !== undefined && modelLists.deploymentNames.length === 0
+            ? existing.providers.map((item) => item.modelId)
+            : modelLists.deploymentNames,
+        imageInputModelIds: existing !== undefined && modelLists.imageInputModelIds.length === 0
+            ? currentImageInputModelIds(existing)
+            : modelLists.imageInputModelIds,
+    };
+}
+function setupRequiresGatewayVerification(raw, preserveExisting) {
+    return (!preserveExisting ||
+        hasNonBlankStringField(raw, "baseUrl") ||
+        hasNonBlankStringField(raw, "apiKey") ||
+        hasNonBlankStringField(raw, "apiKeyHeaderName") ||
+        hasNonEmptyListField(raw, "deploymentNames") ||
+        hasNonEmptyListField(raw, "imageInputModelIds"));
+}
+function readSetupRequest(raw, env, current) {
+    if (!isRecord(raw)) {
+        return { status: 400, body: errorBody("BAD_REQUEST", "Request body must be a JSON object.") };
+    }
+    const preserveExisting = shouldPreserveExisting(raw, current);
+    const credentials = readSetupGatewayCredentials(raw, env, current, preserveExisting);
+    if (isRouteResult(credentials)) {
+        return credentials;
+    }
     const modelLists = readSetupModelLists(raw);
     if (isRouteResult(modelLists)) {
         return modelLists;
     }
-    if (Object.hasOwn(raw, "figmaAccessToken")) {
-        return {
-            status: 400,
-            body: errorBody("BAD_REQUEST", "Figma access tokens must be configured server-side, not through gateway setup."),
-        };
-    }
-    const invalidConnection = validateSetupConnection(baseUrl, apiKey, apiKeyHeaderName, env);
-    if (invalidConnection !== undefined) {
-        return invalidConnection;
+    const figmaAccessToken = optionalSetupSecret(raw.figmaAccessToken, "figmaAccessToken");
+    if (isRouteResult(figmaAccessToken)) {
+        return figmaAccessToken;
     }
+    const resolvedModelLists = resolveSetupModelLists(modelLists, current, preserveExisting);
     return {
-        baseUrl,
-        apiKey,
-        apiKeyHeaderName,
-        deploymentNames: modelLists.deploymentNames,
-        imageInputModelIds: modelLists.imageInputModelIds,
+        ...credentials,
+        deploymentNames: resolvedModelLists.deploymentNames,
+        imageInputModelIds: resolvedModelLists.imageInputModelIds,
+        figmaAccessToken: figmaAccessToken ?? current?.figma?.accessToken,
+        verifyGateway: setupRequiresGatewayVerification(raw, preserveExisting),
+        verifyFigmaCredential: figmaAccessToken !== undefined,
     };
 }
 function safeError(error, secrets) {
@@ -506,34 +690,55 @@ function assertImageInputModelsWereTested(imageInputModelIds, testedModelIds) {
         throw new Error("imageInputModelIds must match tested chat-callable model ids.");
     }
 }
-async function verifySetupCandidate(baseUrl, apiKey, apiKeyHeaderName, deploymentNames, imageInputModelIds, tester, discovery, env, egress) {
+function validationConfigForSetup(input) {
+    const validationRawConfig = buildRawConfig(input.baseUrl, input.apiKey, ["setup-validation"], {
+        apiKeyHeaderName: input.apiKeyHeaderName,
+        imageInputModelIds: input.imageInputModelIds,
+    });
+    return parseGatewayConfig(withInheritedEgress(validationRawConfig, input.egress), input.env);
+}
+async function candidateModelIdsForSetup(input, validationConfig) {
+    return input.deploymentNames.length > 0
+        ? input.deploymentNames
+        : input.discovery(input.baseUrl, input.apiKey, input.apiKeyHeaderName, validationConfig.egress);
+}
+function finalRawConfigForSetup(input, testedModelIds) {
+    const embeddingModelIds = embeddingModelIdsFromDeployments(input.deploymentNames);
+    const configuredModelIds = mergeChatAndEmbeddingModelIds(testedModelIds, input.deploymentNames);
+    const rawConfig = buildRawConfig(input.baseUrl, input.apiKey, configuredModelIds, {
+        apiKeyHeaderName: input.apiKeyHeaderName,
+        imageInputModelIds: input.imageInputModelIds,
+        embeddingModelIds,
+    });
+    return {
+        ...rawConfig,
+        ...(input.current?.grounding === undefined ? {} : { grounding: input.current.grounding }),
+        ...(input.figmaAccessToken === undefined
+            ? {}
+            : { figma: { accessToken: input.figmaAccessToken } }),
+    };
+}
+async function verifySetupCandidate(input) {
     // Defence-in-depth: never send the credential to a candidate URL that has not passed the same
     // scheme/credential/loopback validation as the originally submitted base URL.
-    validateBaseUrl(baseUrl, "candidate");
-    const validationRawConfig = buildRawConfig(baseUrl, apiKey, ["setup-validation"], {
-        apiKeyHeaderName,
-        imageInputModelIds,
-    });
-    const validationConfig = parseGatewayConfig(withInheritedEgress(validationRawConfig, egress), env);
-    const candidateModelIds = deploymentNames.length > 0
-        ? deploymentNames
-        : await discovery(baseUrl, apiKey, apiKeyHeaderName, validationConfig.egress);
-    const smokeTimeoutMs = deploymentNames.length > 0 ? DEPLOYMENT_SMOKE_TIMEOUT_MS : DISCOVERED_MODEL_SMOKE_TIMEOUT_MS;
-    const candidateRawConfig = buildRawConfig(baseUrl, apiKey, candidateModelIds, {
-        apiKeyHeaderName,
+    validateBaseUrl(input.baseUrl, "candidate");
+    const validationConfig = validationConfigForSetup(input);
+    const candidateModelIds = await candidateModelIdsForSetup(input, validationConfig);
+    const smokeTimeoutMs = input.deploymentNames.length > 0
+        ? DEPLOYMENT_SMOKE_TIMEOUT_MS
+        : DISCOVERED_MODEL_SMOKE_TIMEOUT_MS;
+    const candidateRawConfig = buildRawConfig(input.baseUrl, input.apiKey, candidateModelIds, {
+        apiKeyHeaderName: input.apiKeyHeaderName,
         timeoutMs: smokeTimeoutMs,
         maxRetries: 0,
-        imageInputModelIds,
-    });
-    const candidateConfig = parseGatewayConfig(withInheritedEgress(candidateRawConfig, egress), env);
-    const testedModelIds = await tester(candidateConfig, candidateModelIds);
-    assertImageInputModelsWereTested(imageInputModelIds, testedModelIds);
-    const rawConfig = buildRawConfig(baseUrl, apiKey, testedModelIds, {
-        apiKeyHeaderName,
-        imageInputModelIds,
+        imageInputModelIds: input.imageInputModelIds,
     });
-    const config = parseGatewayConfig(withInheritedEgress(rawConfig, egress), env);
-    return { rawConfig, config, testedModelIds };
+    const candidateConfig = parseGatewayConfig(withInheritedEgress(candidateRawConfig, input.egress), input.env);
+    const testedModelIds = await input.tester(candidateConfig, candidateModelIds);
+    assertImageInputModelsWereTested(input.imageInputModelIds, testedModelIds);
+    const rawConfigWithOptionalBlocks = finalRawConfigForSetup(input, testedModelIds);
+    const config = parseGatewayConfig(withInheritedEgress(rawConfigWithOptionalBlocks, input.egress), input.env);
+    return { rawConfig: rawConfigWithOptionalBlocks, config, testedModelIds };
 }
 function setupSuccessResult(config, testedModelIds) {
     const testedModelId = testedModelIds[0] ?? "unknown";
@@ -555,6 +760,45 @@ function setupFailureResult(errors) {
         body: errorBody("GATEWAY_SETUP_FAILED", `Credentials could not be verified. ${errors.join(" ")}`),
     };
 }
+function figmaFailureStatus(code) {
+    switch (code) {
+        case "FIGMA_TOKEN_INVALID":
+        case "FIGMA_TOKEN_EXPIRED":
+        case "FIGMA_TOKEN_REVOKED":
+        case "FIGMA_INSUFFICIENT_SCOPE":
+        case "FIGMA_CONSENT_REQUIRED":
+            return 400;
+        case "FIGMA_RATE_LIMITED":
+            return 429;
+        default:
+            return 502;
+    }
+}
+function figmaCredentialFailureResult(error, request) {
+    if (error instanceof FigmaConnectorError) {
+        return {
+            status: figmaFailureStatus(error.code),
+            body: errorBody(error.code, error.message),
+        };
+    }
+    return {
+        status: 502,
+        body: errorBody("FIGMA_EGRESS_FAILED", safeError(error, [request.figmaAccessToken, request.apiKey, request.baseUrl])),
+    };
+}
+async function verifySubmittedFigmaCredential(request, deps) {
+    if (!request.verifyFigmaCredential || request.figmaAccessToken === undefined) {
+        return undefined;
+    }
+    const tester = deps.figmaCredentialTester ?? defaultFigmaCredentialTester;
+    try {
+        await tester(request.figmaAccessToken, currentGatewayEgressConfig(deps));
+        return undefined;
+    }
+    catch (error) {
+        return figmaCredentialFailureResult(error, request);
+    }
+}
 function deploymentNamesRequiredResult() {
     return {
         status: 400,
@@ -588,39 +832,60 @@ function gatewayUnavailableResult() {
         body: errorBody("GATEWAY_SETUP_UNAVAILABLE", "Gateway setup is unavailable."),
     };
 }
-async function trySetupCandidate(baseUrl, request, deps, gatewayConfig, tester, discovery) {
-    const verified = await verifySetupCandidate(baseUrl, request.apiKey, request.apiKeyHeaderName, request.deploymentNames, request.imageInputModelIds, tester, discovery, deps.env, currentGatewayEgressConfig(deps));
+async function trySetupCandidate(baseUrl, request, deps, gatewayConfig, tester, discovery, current) {
+    const verified = await verifySetupCandidate({
+        baseUrl,
+        apiKey: request.apiKey,
+        apiKeyHeaderName: request.apiKeyHeaderName,
+        deploymentNames: request.deploymentNames,
+        imageInputModelIds: request.imageInputModelIds,
+        tester,
+        discovery,
+        env: deps.env,
+        egress: currentGatewayEgressConfig(deps),
+        figmaAccessToken: request.figmaAccessToken,
+        current,
+    });
     savePrivateJson(gatewayConfig.storagePath, verified.rawConfig);
     gatewayConfig.set(verified.config, true);
     return setupSuccessResult(verified.config, verified.testedModelIds);
 }
 function setupCandidateError(error, request, baseUrl) {
-    return safeError(error, [request.apiKey, request.baseUrl, baseUrl]);
+    return safeError(error, [request.apiKey, request.baseUrl, baseUrl, request.figmaAccessToken]);
 }
-export async function handleGatewaySetup(ctx, deps) {
-    if (deps.gatewayConfig === undefined) {
-        return gatewayUnavailableResult();
-    }
-    const { gatewayConfig } = deps;
-    const bodyResult = await readJsonSetupBody(ctx);
-    if ("status" in bodyResult) {
-        return bodyResult;
-    }
-    const request = readSetupRequest(bodyResult.parsed, deps.env);
-    if ("status" in request) {
-        return request;
+function saveExistingConfigUpdate(request, current, deps, gatewayConfig) {
+    const rawConfig = rawConfigFromCurrent(current, request.figmaAccessToken);
+    const config = parseGatewayConfig(withInheritedEgress(rawConfig, currentGatewayEgressConfig(deps)), deps.env);
+    savePrivateJson(gatewayConfig.storagePath, rawConfig);
+    gatewayConfig.set(config, true);
+    return setupSuccessResult(config, config.providers.map((provider) => provider.modelId));
+}
+async function verifyAndSaveExistingConfigUpdate(request, current, deps, gatewayConfig) {
+    const figmaFailure = await verifySubmittedFigmaCredential(request, deps);
+    if (figmaFailure !== undefined) {
+        return figmaFailure;
     }
+    return saveExistingConfigUpdate(request, current, deps, gatewayConfig);
+}
+function shouldRequireDeploymentNames(request, baseUrlCandidates) {
+    return (request.deploymentNames.length === 0 &&
+        baseUrlCandidates.some((baseUrl) => isAzureFoundryBaseUrl(baseUrl)));
+}
+async function verifyAndSaveGatewaySetup(request, current, deps, gatewayConfig) {
     const tester = deps.gatewaySetupTester ?? defaultGatewaySetupTester;
     const discovery = deps.gatewayModelDiscovery ?? defaultGatewayModelDiscovery;
+    const figmaFailure = await verifySubmittedFigmaCredential(request, deps);
+    if (figmaFailure !== undefined) {
+        return figmaFailure;
+    }
     const baseUrlCandidates = candidateBaseUrls(request.baseUrl);
-    if (request.deploymentNames.length === 0 &&
-        baseUrlCandidates.some((baseUrl) => isAzureFoundryBaseUrl(baseUrl))) {
+    if (shouldRequireDeploymentNames(request, baseUrlCandidates)) {
         return deploymentNamesRequiredResult();
     }
     const errors = [];
     for (const baseUrl of baseUrlCandidates) {
         try {
-            return await trySetupCandidate(baseUrl, request, deps, gatewayConfig, tester, discovery);
+            return await trySetupCandidate(baseUrl, request, deps, gatewayConfig, tester, discovery, current);
         }
         catch (error) {
             errors.push(`candidate ${String(errors.length + 1)}: ${setupCandidateError(error, request, baseUrl)}`);
@@ -628,3 +893,22 @@ export async function handleGatewaySetup(ctx, deps) {
     }
     return setupFailureResult(errors);
 }
+export async function handleGatewaySetup(ctx, deps) {
+    if (deps.gatewayConfig === undefined) {
+        return gatewayUnavailableResult();
+    }
+    const { gatewayConfig } = deps;
+    const current = currentGatewayConfig(deps);
+    const bodyResult = await readJsonSetupBody(ctx);
+    if ("status" in bodyResult) {
+        return bodyResult;
+    }
+    const request = readSetupRequest(bodyResult.parsed, deps.env, current);
+    if ("status" in request) {
+        return request;
+    }
+    if (!request.verifyGateway && current !== undefined) {
+        return verifyAndSaveExistingConfigUpdate(request, current, deps, gatewayConfig);
+    }
+    return verifyAndSaveGatewaySetup(request, current, deps, gatewayConfig);
+}

package/node_modules/@oscharko-dev/keiko-server/dist/memory-conv-handlers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-conv-handlers.d.ts","sourceRoot":"","sources":["../src/memory-conv-handlers.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,sCAAsC,CAAC;AAe9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AA6G7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,eAAe,CAezE;AA8FD,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAyCtB;AAkED,wBAAsB,mCAAmC,CACvD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CA0BtB"}
+{"version":3,"file":"memory-conv-handlers.d.ts","sourceRoot":"","sources":["../src/memory-conv-handlers.ts"],"names":[],"mappings":"AA0BA,OAAO,EAEL,KAAK,eAAe,EAErB,MAAM,sCAAsC,CAAC;AAgB9C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAkH7D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,gBAAgB,GAAG,eAAe,CAezE;AAgJD,wBAAsB,2BAA2B,CAC/C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAwCtB;AAkED,wBAAsB,mCAAmC,CACvD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CA0BtB"}

package/node_modules/@oscharko-dev/keiko-server/dist/memory-conv-handlers.js

@@ -23,7 +23,7 @@
 // File budget: keep under 400 LOC per coordinator quality rules.
 import { randomUUID } from "node:crypto";
 import { retrieveMemoryContext, } from "@oscharko-dev/keiko-memory-retrieval";
-import { extractCandidatesFromUserText, } from "@oscharko-dev/keiko-memory-capture";
+import { extractCandidatesFromUserText, memoryTextEgressRejectionReason, } from "@oscharko-dev/keiko-memory-capture";
 import { MEMORY_TYPES } from "@oscharko-dev/keiko-contracts";
 import { errorBody } from "./routes.js";
 import { createMemoryTargetResolver } from "./memory-target-resolver.js";
@@ -31,6 +31,7 @@ import { conversationMemoryScopes, resolveConversationMemoryContext, } from "./m
 import { recordMemoryAudit } from "./memory-audit-handler.js";
 import { buildMemoryRecordFromProposal } from "./memory-record-builders.js";
 import { enforcePersistableMemoryOutcome, isPersistableMemoryCandidate, memoryCapturePolicyForDeps, } from "./memory-capture-policy.js";
+import { buildConversationRetrievalSignals, conversationFusionMode, } from "./memory-retrieval-signals.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const MAX_BODY_BYTES = 64_000;
 // ─── Body reading (mirrors memory-handlers.ts pattern) ────────────────────────
@@ -197,11 +198,12 @@ function parseContextInput(raw) {
         budgetTokens: budgetTokens ?? undefined,
     };
 }
-function buildRetrievalRequest(scopes, input) {
+function buildRetrievalRequest(scopes, input, nowMs, signals, fusion) {
     // exactOptionalPropertyTypes: omit undefined fields instead of assigning them.
     const req = {
         scopes,
-        nowMs: Date.now(),
+        nowMs,
+        fusion,
     };
     if (input.queryText !== undefined)
         req.queryText = input.queryText;
@@ -209,8 +211,36 @@ function buildRetrievalRequest(scopes, input) {
         req.types = input.types;
     if (input.budgetTokens !== undefined)
         req.budgetTokens = input.budgetTokens;
+    // Embedding-cosine (#204, O-F4), reinforcement (O-P1), and MMR-diversity (O-F3) signals, same as
+    // the chat path. Passed only when present so a vault with no embeddings / no access history ranks
+    // byte-identically.
+    if (signals.semanticById !== undefined)
+        req.semanticById = signals.semanticById;
+    if (signals.strengthById.size > 0)
+        req.strengthById = signals.strengthById;
+    if (signals.embeddingById.size > 0)
+        req.embeddingById = signals.embeddingById;
     return req;
 }
+// Builds the embedding + reinforcement signals, runs scoped retrieval, and records the reinforcement
+// reflex — the same pipeline the chat path uses. Extracted so the route handler stays a thin
+// parse/dispatch/audit shell.
+async function retrieveConversationMemory(deps, vault, scopes, input) {
+    const port = vaultAsQueryPort(vault);
+    const nowMs = Date.now();
+    // Embedding egress gate (#204, O-F4): only send the query to the secondary embedding model when it
+    // is not secret-shaped — matching the chat path's safeForSecondaryModel guard.
+    const safeForSecondaryModel = input.queryText === undefined ||
+        memoryTextEgressRejectionReason(input.queryText, memoryCapturePolicyForDeps(deps)) === null;
+    const signals = await buildConversationRetrievalSignals(deps, vault, input.queryText, scopes, nowMs, safeForSecondaryModel);
+    const result = retrieveMemoryContext(buildRetrievalRequest(scopes, input, nowMs, signals, conversationFusionMode(deps)), port);
+    // Reinforcement reflex (#204, O-P1): every recall is an access, same as the chat path.
+    const accessedIds = result.included.map((item) => item.memoryId);
+    if (accessedIds.length > 0) {
+        vault.recordAccess(accessedIds, Date.now());
+    }
+    return result;
+}
 export async function handleMemoryRetrieveContext(ctx, deps) {
     const vault = resolveVault(deps);
     if (isRouteResult(vault))
@@ -225,8 +255,7 @@ export async function handleMemoryRetrieveContext(ctx, deps) {
     if (isRouteResult(context))
         return context;
     const scopes = conversationMemoryScopes(context);
-    const port = vaultAsQueryPort(vault);
-    const result = retrieveMemoryContext(buildRetrievalRequest(scopes, input), port);
+    const result = await retrieveConversationMemory(deps, vault, scopes, input);
     if (result.included.length > 0) {
         const event = {
             schemaVersion: "1",

package/node_modules/@oscharko-dev/keiko-server/dist/memory-embedding.d.ts

@@ -1,6 +1,6 @@
 import { type GatewayConfig, type OpenAIEmbeddingOutcome, type OpenAIEmbeddingRequest } from "@oscharko-dev/keiko-model-gateway";
-import type { MemoryId } from "@oscharko-dev/keiko-contracts/memory";
-import type { MemoryEmbeddingInput, MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
+import type { MemoryId, MemoryRecord } from "@oscharko-dev/keiko-contracts/memory";
+import type { MemoryEmbeddingInput, MemoryEmbeddingRow, MemoryVaultStore } from "@oscharko-dev/keiko-memory-vault";
 import { type UiHandlerDeps } from "./deps.js";
 export declare function selectMemoryEmbeddingModelId(config: GatewayConfig | undefined): string | undefined;
 export type MemoryEmbedder = (text: string) => Promise<MemoryEmbeddingInput | null>;
@@ -8,4 +8,14 @@ export declare function createMemoryEmbedder(config: GatewayConfig | undefined,
 export declare function embedMemoryText(deps: UiHandlerDeps, text: string): Promise<MemoryEmbeddingInput | null>;
 export declare function embedAndStoreMemory(deps: UiHandlerDeps, vault: MemoryVaultStore, memoryId: MemoryId, text: string): Promise<void>;
 export declare function cosineSimilarity(a: Float32Array, b: Float32Array): number;
+export declare const SEMANTIC_DEDUP_COSINE_THRESHOLD = 0.95;
+export declare function findSemanticDuplicate(candidate: MemoryEmbeddingInput | null, neighbors: ReadonlyMap<MemoryId, MemoryEmbeddingRow>, threshold?: number): MemoryId | null;
+export declare const RELATED_LINK_COSINE_THRESHOLD = 0.82;
+export declare const MAX_AUTO_LINKS = 3;
+export declare function findRelatedNeighbors(candidate: MemoryEmbeddingInput | null, neighbors: ReadonlyMap<MemoryId, MemoryEmbeddingRow>, lower?: number, upper?: number, maxLinks?: number): readonly MemoryId[];
+export interface NoveltyInsertResult {
+    readonly inserted: MemoryRecord | null;
+    readonly mergedInto: MemoryId | null;
+}
+export declare function insertSalienceMemoryWithNoveltyGate(deps: UiHandlerDeps, vault: MemoryVaultStore, record: MemoryRecord): Promise<NoveltyInsertResult>;
 //# sourceMappingURL=memory-embedding.d.ts.map

package/node_modules/@oscharko-dev/keiko-server/dist/memory-embedding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory-embedding.d.ts","sourceRoot":"","sources":["../src/memory-embedding.ts"],"names":[],"mappings":"AAgBA,OAAO,EAEL,KAAK,aAAa,EAGlB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC5B,MAAM,mCAAmC,CAAC;AAC3C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sCAAsC,CAAC;AACrE,OAAO,KAAK,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AAC/F,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAIrE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAEpB;AAyDD,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAKpF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,WAAW,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,GAChF,cAAc,GAAG,IAAI,CAuBvB;AAKD,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAItC;AAKD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf;AAKD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAgBzE"}
+{"version":3,"file":"memory-embedding.d.ts","sourceRoot":"","sources":["../src/memory-embedding.ts"],"names":[],"mappings":"AAgBA,OAAO,EAEL,KAAK,aAAa,EAGlB,KAAK,sBAAsB,EAC3B,KAAK,sBAAsB,EAC5B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,KAAK,EAEV,QAAQ,EACR,YAAY,EAEb,MAAM,sCAAsC,CAAC;AAC9C,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EACjB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAIrE,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,MAAM,GAAG,SAAS,CAEpB;AAyDD,MAAM,MAAM,cAAc,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAAC;AAKpF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,WAAW,EAAE,CAAC,OAAO,EAAE,sBAAsB,KAAK,OAAO,CAAC,sBAAsB,CAAC,GAChF,cAAc,GAAG,IAAI,CAuBvB;AAKD,wBAAsB,eAAe,CACnC,IAAI,EAAE,aAAa,EACnB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC,CAItC;AAKD,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,gBAAgB,EACvB,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,IAAI,CAAC,CAQf;AAKD,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,EAAE,YAAY,GAAG,MAAM,CAgBzE;AAiBD,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAKpD,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,oBAAoB,GAAG,IAAI,EACtC,SAAS,EAAE,WAAW,CAAC,QAAQ,EAAE,kBAAkB,CAAC,EACpD,SAAS,GAAE,MAAwC,GAClD,QAAQ,GAAG,IAAI,CAYjB;AAeD,eAAO,MAAM,6BAA6B,OAAO,CAAC;AAGlD,eAAO,MAAM,cAAc,IAAI,CAAC;AAMhC,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,oBAAoB,GAAG,IAAI,EACtC,SAAS,EAAE,WAAW,CAAC,QAAQ,EAAE,kBAAkB,CAAC,EACpD,KAAK,GAAE,MAAsC,EAC7C,KAAK,GAAE,MAAwC,EAC/C,QAAQ,GAAE,MAAuB,GAChC,SAAS,QAAQ,EAAE,CAWrB;AA+CD,MAAM,WAAW,mBAAmB;IAElC,QAAQ,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC;IAEvC,QAAQ,CAAC,UAAU,EAAE,QAAQ,GAAG,IAAI,CAAC;CACtC;AAOD,wBAAsB,mCAAmC,CACvD,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,gBAAgB,EACvB,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,mBAAmB,CAAC,CAoB9B"}