@oscharko-dev/keiko-server 0.2.0

package/dist/editor/completionRoutes.js

@@ -0,0 +1,411 @@
+// BFF route for the governed editor completion gateway (Issue #1199, ADR-0042 D4/D5/D6).
+//
+//   POST /api/editor/completion — produce completion items for an editor overlay. Two governed tiers:
+//     Tier 1 (always): deterministic, model-free language-service completion (#1198) — the source of
+//       truth and the always-available default.
+//     Tier 2 (gated):  model-assisted completion routed through the Model Gateway, run ONLY when the
+//       completion-model selection (#1210) elects an aligned ("instruct"/"edit-tuned") infilling model
+//       in budget. The as-you-type tier may run on a trigger character; the manual tier runs only on an
+//       explicit invoke. When no governed model is usable the route degrades to deterministic-only and
+//       records the content-free degrade reason — never a silent ungoverned fallback.
+//
+// Model-assisted completion enriches its prompt with governed coding context (#1211, repository search
+// plus — when a capsule/capsule-set is selected and the budget allows — Local Knowledge and retained
+// memory), assembled server-side and recorded as content-free evidence. The response is content-free
+// apart from reviewable `insertText`: per-item origin plus a source/provenance rollup with a SHA-256
+// prompt hash, never the prompt, the buffer, or any retrieved excerpt. The browser never reaches the
+// Model Gateway, retrieval, or any provider directly (Acceptance Criterion 5).
+import { CODING_CONTEXT_SCHEMA_VERSION, CODING_CONTEXT_BUDGETS, DEFAULT_LANGUAGE_SERVICE_LIMITS, EDITOR_COMPLETION_SCHEMA_VERSION, isValidScopePath, parseEditorCompletionRequest, stripUnsafeFormatChars, toCodingContextWirePack, } from "@oscharko-dev/keiko-contracts";
+import { Gateway, selectCompletionModel } from "@oscharko-dev/keiko-model-gateway";
+import { nodeWorkspaceFs } from "@oscharko-dev/keiko-workspace/internal/fs";
+import { errorBody } from "../routes.js";
+import { currentGatewayConfig } from "../deps.js";
+import { readJsonObject, resolveRoot, runFilesHandler } from "../files.js";
+import { assembleCodingContext } from "./codingContext.js";
+import { recordCodingContextEvidence } from "./codingContextEvidence.js";
+import { recordEditorCompletionModelEvidence } from "./completionModelEvidence.js";
+import { clientAbortSignal, resolveOverlayPath, STATUS_BY_CODE } from "./languageRoutes.js";
+import { runLanguageOperation } from "./languageService.js";
+import { buildModelCompletionPrompt, generateModelCompletions, } from "./editorCompletionModel.js";
+import { estimateEditorModelReservationTokens, settleModelUsage, sharedEditorModelTokenBudget, } from "./editorModelTokenBudget.js";
+// The overlay buffer may be up to the document-size cap; allow 64 KiB of JSON envelope on top.
+const MAX_COMPLETION_BODY_BYTES = DEFAULT_LANGUAGE_SERVICE_LIMITS.maxDocumentBytes + 64 * 1024;
+// Content-free identifier of the completion governance policy version (audit correlation).
+const COMPLETION_GATEWAY_POLICY_VERSION = "editor-completion/1";
+const MAX_MODEL_ITEMS = 8;
+const MAX_MODEL_INSERT_TEXT_CHARS = 2_000;
+const MAX_CONTEXT_CHANGED_FILES = 64;
+export const COMPLETION_LANGUAGE_SERVICE_LIMITS = {
+    ...DEFAULT_LANGUAGE_SERVICE_LIMITS,
+    deadlineMs: 500,
+};
+const MODEL_AS_YOU_TYPE_TIMEOUT_MS = 750;
+// Default chat seam: route the elected model through the Model Gateway, server-side only.
+function defaultChatFactory(config, modelId) {
+    const gateway = new Gateway(config);
+    return async (chatRequest, chatSignal) => {
+        const response = await gateway.chat({
+            modelId,
+            messages: [
+                { role: "system", content: chatRequest.system },
+                { role: "user", content: chatRequest.user },
+            ],
+            cancellationSignal: chatSignal,
+        });
+        return { content: response.content, usage: response.usage };
+    };
+}
+function isRouteResult(value) {
+    return typeof value === "object" && value !== null && "status" in value && "body" in value;
+}
+function redactPromptText(deps, value) {
+    const stripped = stripUnsafeFormatChars(value);
+    const redacted = deps.redactor(stripped);
+    return typeof redacted === "string" ? redacted : stripped;
+}
+const DETERMINISTIC_OUTCOME = (mode, degradeReason, modelId, latencyClass) => ({
+    items: [],
+    modelMode: mode,
+    degradeReason,
+    modelId,
+    latencyClass,
+    contextSources: [],
+    truncated: false,
+});
+function buildContextRequest(request) {
+    return {
+        schemaVersion: CODING_CONTEXT_SCHEMA_VERSION,
+        purpose: "completion",
+        documentPath: request.document.path,
+        symbol: request.context?.symbol,
+        queryText: request.context?.queryText,
+        changedFiles: request.context?.changedFiles,
+        capsuleId: request.context?.capsuleId,
+        capsuleSetId: request.context?.capsuleSetId,
+    };
+}
+function dedupeChangedFiles(paths) {
+    return [...new Set(paths)];
+}
+function invalidChangedFiles(message) {
+    return { status: 400, body: errorBody("INVALID_REQUEST", message) };
+}
+function sanitizeChangedFiles(realRoot, changedFiles) {
+    if (changedFiles === undefined) {
+        return undefined;
+    }
+    const deduped = dedupeChangedFiles(changedFiles);
+    if (deduped.length > MAX_CONTEXT_CHANGED_FILES) {
+        return invalidChangedFiles(`context.changedFiles must contain at most ${MAX_CONTEXT_CHANGED_FILES.toString()} paths.`);
+    }
+    for (const changed of deduped) {
+        if (!isValidScopePath(changed, { mustBeRelative: true })) {
+            return invalidChangedFiles(`context.changedFiles contains an invalid workspace-relative path: ${changed}`);
+        }
+        resolveOverlayPath(realRoot, changed);
+    }
+    return deduped.length > 0 ? deduped : undefined;
+}
+function sanitizeRequestContext(request, realRoot) {
+    const changedFiles = sanitizeChangedFiles(realRoot, request.context?.changedFiles);
+    if (isRouteResult(changedFiles)) {
+        return changedFiles;
+    }
+    if (request.context === undefined) {
+        return request;
+    }
+    return {
+        ...request,
+        context: {
+            ...(request.context.queryText === undefined ? {} : { queryText: request.context.queryText }),
+            ...(request.context.symbol === undefined ? {} : { symbol: request.context.symbol }),
+            ...(request.context.capsuleId === undefined ? {} : { capsuleId: request.context.capsuleId }),
+            ...(request.context.capsuleSetId === undefined
+                ? {}
+                : { capsuleSetId: request.context.capsuleSetId }),
+            ...(changedFiles === undefined ? {} : { changedFiles }),
+        },
+    };
+}
+function effectiveContextBudgetBytes(request) {
+    return Math.min(CODING_CONTEXT_BUDGETS.completion.budgetBytes, Math.max(0, Math.trunc(request.contextBudgetBytes)));
+}
+function modelSignal(selection, signal) {
+    if (selection.mode !== "as-you-type") {
+        return signal;
+    }
+    return AbortSignal.any([signal, AbortSignal.timeout(MODEL_AS_YOU_TYPE_TIMEOUT_MS)]);
+}
+// Map the coding-context source kinds that actually contributed an excerpt to the AC7 completion
+// source vocabulary. Source kinds outside that vocabulary (QI, workflow, files-focus) are not surfaced.
+function contextSourcesFromPack(pack) {
+    const mapping = {
+        "repo-search": "repository-context",
+        "local-knowledge": "local-knowledge",
+        memory: "memory",
+        "connected-context": "connected-context",
+    };
+    const sources = new Set();
+    for (const excerpt of pack.excerpts) {
+        const mapped = mapping[excerpt.citation.sourceKind];
+        if (mapped !== undefined) {
+            sources.add(mapped);
+        }
+    }
+    return [...sources];
+}
+function recordModelEvidence(input) {
+    recordEditorCompletionModelEvidence(input.deps.evidenceStore, input.deps.redactor, {
+        modelId: input.modelId,
+        modelMode: input.selection.mode,
+        latencyClass: input.selection.latencyClass,
+        gatewayPolicyVersion: COMPLETION_GATEWAY_POLICY_VERSION,
+        promptHash: input.promptHash,
+        itemCount: input.itemCount,
+        truncated: input.truncated,
+        usage: input.usage,
+    }, input.nowMs);
+}
+function completionGenerationInput(ctx, pack) {
+    return {
+        overlayText: ctx.request.document.text,
+        position: ctx.request.position,
+        languageId: ctx.request.document.languageId,
+        contextPack: pack,
+        maxItems: MAX_MODEL_ITEMS,
+        maxInsertTextChars: MAX_MODEL_INSERT_TEXT_CHARS,
+        redactText: (value) => redactPromptText(ctx.deps, value),
+    };
+}
+function maxOutputTokensForModel(config, modelId) {
+    const capability = config.capabilities?.find((candidate) => candidate.id === modelId);
+    return Math.max(1, capability?.maxOutputTokens ?? Math.ceil((MAX_MODEL_ITEMS * MAX_MODEL_INSERT_TEXT_CHARS) / 4));
+}
+function reserveModelCompletion(ctx, input) {
+    const prompt = buildModelCompletionPrompt(input);
+    return ctx.tokenBudget.tryReserve(ctx.realRoot, ctx.nowMs, estimateEditorModelReservationTokens(prompt, maxOutputTokensForModel(ctx.config, ctx.modelId)));
+}
+function modelOutcomeFromGenerated(ctx, pack, generated) {
+    return {
+        items: generated.items,
+        modelMode: ctx.selection.mode,
+        modelId: ctx.modelId,
+        latencyClass: ctx.selection.latencyClass,
+        promptHash: generated.promptHash,
+        contextSources: generated.items.length > 0 ? contextSourcesFromPack(pack) : [],
+        truncated: generated.truncated,
+        ...(generated.usage === undefined ? {} : { usage: generated.usage }),
+    };
+}
+// Runs the elected model: assembles coding context (#1211), records content-free evidence, and calls
+// the gateway through the injected chat factory. A failure throws to the caller, which degrades.
+async function runElectedModel(ctx) {
+    const pack = await assembleCodingContext(buildContextRequest(ctx.request), {
+        deps: ctx.deps,
+        realRoot: ctx.realRoot,
+        signal: ctx.signal,
+        nowMs: ctx.nowMs,
+        budgetBytes: effectiveContextBudgetBytes(ctx.request),
+    });
+    recordCodingContextEvidence(ctx.deps.evidenceStore, ctx.deps.redactor, toCodingContextWirePack(pack), ctx.nowMs);
+    const generationInput = completionGenerationInput(ctx, pack);
+    const reservation = reserveModelCompletion(ctx, generationInput);
+    if (reservation === undefined) {
+        return DETERMINISTIC_OUTCOME(ctx.selection.mode, ctx.selection.degradeReason, ctx.modelId, ctx.selection.latencyClass);
+    }
+    const generated = await generateModelCompletions(generationInput, ctx.chatFactory(ctx.config, ctx.modelId), ctx.signal);
+    settleModelUsage(reservation, generated.usage);
+    recordModelEvidence({
+        deps: ctx.deps,
+        modelId: ctx.modelId,
+        selection: ctx.selection,
+        promptHash: generated.promptHash,
+        itemCount: generated.items.length,
+        truncated: generated.truncated,
+        usage: generated.usage,
+        nowMs: ctx.nowMs,
+    });
+    return modelOutcomeFromGenerated(ctx, pack, generated);
+}
+// Decides whether the gated model tier runs for this request and, if so, runs it. The cost ceiling
+// (#1206) and the aligned-FIM guardrail (#1210) are enforced by `selectCompletionModel`.
+async function runModelTier(request, realRoot, signal, deps, chatFactory, tokenBudget, now) {
+    const config = currentGatewayConfig(deps);
+    if (config === undefined) {
+        return DETERMINISTIC_OUTCOME("deterministic", "no-infilling-model", undefined, undefined);
+    }
+    const selection = selectCompletionModel(config, request.maxCostClass === undefined ? {} : { maxCostClass: request.maxCostClass });
+    const modelId = selection.modelId;
+    // As-you-type-capable (fast) models may run on a trigger character; a manual-only model runs only on
+    // an explicit invoke, bounding per-keystroke cost (ADR-0042 D5/D6).
+    const triggerEligible = request.triggerKind === "invoked" || selection.mode === "as-you-type";
+    const degraded = () => DETERMINISTIC_OUTCOME(selection.mode, selection.degradeReason, modelId, selection.latencyClass);
+    // Skip the model for an ineligible trigger. The per-root token ceiling (#1206 LLM10) reserves
+    // immediately before the provider call once the prompt is known.
+    if (selection.mode === "deterministic" || modelId === undefined || !triggerEligible) {
+        return degraded();
+    }
+    try {
+        const outcome = await runElectedModel({
+            request,
+            realRoot,
+            signal: modelSignal(selection, signal),
+            deps,
+            selection,
+            modelId,
+            chatFactory,
+            config,
+            tokenBudget,
+            nowMs: now(),
+        });
+        return outcome;
+    }
+    catch {
+        // ADR-0042 D5 / AC4: a model or retrieval failure degrades to deterministic-only; it never breaks
+        // the route or surfaces partial junk to the editor.
+        return degraded();
+    }
+}
+// ─── Wire-response assembly ──────────────────────────────────────────────────────────────────────
+function wireItem(item, origin) {
+    return {
+        label: item.label,
+        kind: item.kind,
+        insertText: item.insertText,
+        origin,
+        ...(item.detail === undefined ? {} : { detail: item.detail }),
+        ...(item.sortText === undefined ? {} : { sortText: item.sortText }),
+    };
+}
+function deterministicWireItem(item) {
+    return wireItem({
+        label: item.label,
+        kind: item.kind,
+        // LSP completion items may omit `insertText` (the label is inserted verbatim).
+        insertText: item.insertText ?? item.label,
+        detail: item.detail,
+        sortText: item.sortText,
+    }, "deterministic");
+}
+function mergeItems(deterministic, model, maxItems) {
+    const items = [];
+    const seen = new Set();
+    let capped = false;
+    function push(candidate) {
+        if (seen.has(candidate.insertText)) {
+            return;
+        }
+        if (items.length >= maxItems) {
+            capped = true;
+            return;
+        }
+        seen.add(candidate.insertText);
+        items.push(candidate);
+    }
+    // Deterministic completions remain first and win de-dupe conflicts; model items are additive.
+    for (const item of deterministic) {
+        push(deterministicWireItem(item));
+    }
+    for (const item of model) {
+        push(wireItem(item, "model-assisted"));
+    }
+    return { items, capped };
+}
+// The model-identifying fields (modelId, latencyClass, gatewayPolicyVersion, promptHash) are present
+// only when model-assisted items were actually produced — they identify the model that produced THIS
+// response's items, matching the wire contract. `modelMode`/`degradeReason` always reflect the
+// selection, so an elected-but-unused model is still visible to the client without a misleading
+// model-identity/audit signal at the response level. (The model invocation itself, including the
+// invoked-but-empty case, is recorded server-side as content-free evidence by the route.)
+function buildProvenance(model, producedModelItems) {
+    const sources = ["deterministic-language-service"];
+    if (producedModelItems) {
+        sources.push("model-assisted", ...model.contextSources);
+    }
+    return {
+        sources: [...new Set(sources)],
+        modelMode: model.modelMode,
+        ...(model.degradeReason === undefined ? {} : { degradeReason: model.degradeReason }),
+        ...(producedModelItems && model.modelId !== undefined ? { modelId: model.modelId } : {}),
+        ...(producedModelItems && model.latencyClass !== undefined
+            ? { latencyClass: model.latencyClass }
+            : {}),
+        ...(producedModelItems ? { gatewayPolicyVersion: COMPLETION_GATEWAY_POLICY_VERSION } : {}),
+        ...(producedModelItems && model.promptHash !== undefined
+            ? { promptHash: model.promptHash }
+            : {}),
+    };
+}
+function buildWireResponse(deterministic, model) {
+    const { items, capped } = mergeItems(deterministic.items, model.items, DEFAULT_LANGUAGE_SERVICE_LIMITS.maxCompletionItems);
+    const producedModelItems = items.some((item) => item.origin === "model-assisted");
+    return {
+        schemaVersion: EDITOR_COMPLETION_SCHEMA_VERSION,
+        items,
+        isIncomplete: deterministic.isIncomplete || capped,
+        truncated: deterministic.truncated || model.truncated || capped,
+        provenance: buildProvenance(model, producedModelItems),
+    };
+}
+function runDeterministicCompletion(input) {
+    const langRequest = {
+        operation: "completion",
+        root: input.request.root,
+        document: input.request.document,
+        position: input.request.position,
+    };
+    const outcome = runLanguageOperation(langRequest, {
+        fs: nodeWorkspaceFs,
+        realRoot: input.realRoot,
+        overlayAbsolutePath: input.overlayAbsolutePath,
+        signal: input.signal,
+        limits: input.limits ?? COMPLETION_LANGUAGE_SERVICE_LIMITS,
+        now: input.now,
+    });
+    if (outcome.kind === "error") {
+        return {
+            status: STATUS_BY_CODE[outcome.code],
+            body: errorBody(outcome.code, outcome.message),
+        };
+    }
+    if (outcome.kind !== "completion") {
+        return { status: 500, body: errorBody("INTERNAL", "Unexpected language-service outcome.") };
+    }
+    return outcome.result;
+}
+// ─── Route ──────────────────────────────────────────────────────────────────────────────────────
+export async function handleEditorCompletion(ctx, deps, options = {}) {
+    const body = await readJsonObject(ctx.req, MAX_COMPLETION_BODY_BYTES);
+    if (isRouteResult(body)) {
+        return body;
+    }
+    const parsed = parseEditorCompletionRequest(body);
+    if (!parsed.ok) {
+        return { status: 400, body: errorBody("INVALID_REQUEST", parsed.errors.join("; ")) };
+    }
+    const request = parsed.value;
+    return runFilesHandler(async () => {
+        const root = await resolveRoot(deps.store, request.root, deps.redactor);
+        const overlayAbsolutePath = resolveOverlayPath(root.realRoot, request.document.path);
+        const sanitizedRequest = sanitizeRequestContext(request, root.realRoot);
+        if (isRouteResult(sanitizedRequest)) {
+            return sanitizedRequest;
+        }
+        const signal = clientAbortSignal(ctx);
+        // Tier 1: deterministic language-service completion (always).
+        const deterministic = runDeterministicCompletion({
+            request: sanitizedRequest,
+            realRoot: root.realRoot,
+            overlayAbsolutePath,
+            signal,
+            limits: options.languageServiceLimits,
+            now: options.languageServiceNow,
+        });
+        if (isRouteResult(deterministic)) {
+            return deterministic;
+        }
+        // Tier 2: gated model-assisted completion.
+        const model = await runModelTier(sanitizedRequest, root.realRoot, signal, deps, options.chatFactory ?? defaultChatFactory, options.tokenBudget ?? sharedEditorModelTokenBudget, options.now ?? Date.now);
+        return { status: 200, body: deps.redactor(buildWireResponse(deterministic, model)) };
+    });
+}

package/dist/editor/contextRoutes.d.ts

@@ -0,0 +1,6 @@
+import { type RouteContext, type RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export declare function handleEditorContext(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleEditorRepoSearch(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+export declare function handleEditorLocalKnowledgeRetrieve(ctx: RouteContext, deps: UiHandlerDeps): Promise<RouteResult>;
+//# sourceMappingURL=contextRoutes.d.ts.map

package/dist/editor/contextRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextRoutes.d.ts","sourceRoot":"","sources":["../../src/editor/contextRoutes.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAa,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAuHhD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CA4CtB;AA+PD,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAsBtB;AAqDD,wBAAsB,kCAAkC,CACtD,GAAG,EAAE,YAAY,EACjB,IAAI,EAAE,aAAa,GAClB,OAAO,CAAC,WAAW,CAAC,CAuBtB"}