@oscharko-dev/keiko-server 0.2.0

package/dist/qualityIntelligence/figmaSnapshotScreenIds.d.ts

@@ -0,0 +1,19 @@
+/** Upper bound on the number of scoped screen ids in one figma-snapshot source (DoS / payload guard). */
+export declare const MAX_FIGMA_SCREEN_IDS = 200;
+/** Upper bound on a single screen id's length (mirrors the UI persistence reference-value cap). */
+export declare const MAX_FIGMA_SCREEN_ID_LENGTH = 256;
+export type FigmaScreenIdsResult = {
+    readonly ok: true;
+    readonly screenIds: readonly string[] | undefined;
+} | {
+    readonly ok: false;
+    readonly reason: string;
+};
+/**
+ * Validate and canonicalise the optional `screenIds` field of an incoming figma-snapshot source.
+ * Returns `{ ok: true, screenIds: undefined }` when the field is absent (whole-snapshot source),
+ * `{ ok: true, screenIds }` with a deduplicated, sorted, bounded list when it is a valid scope, or
+ * `{ ok: false, reason }` with a user-actionable message when it is malformed / empty / oversized.
+ */
+export declare function parseFigmaSnapshotScreenIds(raw: unknown): FigmaScreenIdsResult;
+//# sourceMappingURL=figmaSnapshotScreenIds.d.ts.map

package/dist/qualityIntelligence/figmaSnapshotScreenIds.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figmaSnapshotScreenIds.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/figmaSnapshotScreenIds.ts"],"names":[],"mappings":"AAkBA,yGAAyG;AACzG,eAAO,MAAM,oBAAoB,MAAM,CAAC;AAExC,mGAAmG;AACnG,eAAO,MAAM,0BAA0B,MAAM,CAAC;AAE9C,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,CAAA;CAAE,GACxE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,GAAG,EAAE,OAAO,GAAG,oBAAoB,CA+C9E"}

package/dist/qualityIntelligence/figmaSnapshotScreenIds.js

@@ -0,0 +1,75 @@
+// Shared validation + canonicalisation for figma-snapshot `screenIds` scoping (Epic #750, Issue #754).
+//
+// Both the start-run route (runRoutes.ts) and the drift re-check / regenerate route (reCheckRoutes.ts)
+// accept figma-snapshot sources that MAY carry an optional `screenIds` array scoping ingestion to
+// specific masks of a large board. This module is the SINGLE source of truth so the two routes can
+// never diverge on what they accept — the audit's run/recheck-parity requirement.
+//
+// Invariants enforced here:
+//   - `screenIds` ABSENT  → whole-snapshot source (returns `undefined`; the contract's "absent = whole").
+//   - `screenIds` PRESENT → must be a NON-EMPTY array of non-empty, bounded, string ids. An explicit
+//     empty array is REJECTED: a scoped source with zero screens is meaningless, and left unchecked the
+//     server's `scopedParsedScreens` treats an empty screen list as "all screens" — silently widening a
+//     scoped request to the whole board (the scoped-snapshot leak this guard closes).
+//   - Each id is trimmed, must be non-empty and within the length cap; the array count is capped.
+//   - The result is CANONICAL (deduplicated + sorted) so the derived envelope id / provenance ref is
+//     stable regardless of the order or duplicates the client sent, and dedupe across reconnections and
+//     re-check is exact.
+/** Upper bound on the number of scoped screen ids in one figma-snapshot source (DoS / payload guard). */
+export const MAX_FIGMA_SCREEN_IDS = 200;
+/** Upper bound on a single screen id's length (mirrors the UI persistence reference-value cap). */
+export const MAX_FIGMA_SCREEN_ID_LENGTH = 256;
+/**
+ * Validate and canonicalise the optional `screenIds` field of an incoming figma-snapshot source.
+ * Returns `{ ok: true, screenIds: undefined }` when the field is absent (whole-snapshot source),
+ * `{ ok: true, screenIds }` with a deduplicated, sorted, bounded list when it is a valid scope, or
+ * `{ ok: false, reason }` with a user-actionable message when it is malformed / empty / oversized.
+ */
+export function parseFigmaSnapshotScreenIds(raw) {
+    if (raw === undefined)
+        return { ok: true, screenIds: undefined };
+    if (!Array.isArray(raw)) {
+        return {
+            ok: false,
+            reason: "A figma-snapshot source screenIds field must be an array of screen ids.",
+        };
+    }
+    if (raw.length === 0) {
+        return {
+            ok: false,
+            reason: "A figma-snapshot source screenIds field, when present, must list at least one screen id.",
+        };
+    }
+    if (raw.length > MAX_FIGMA_SCREEN_IDS) {
+        return {
+            ok: false,
+            reason: `A figma-snapshot source may scope at most ${String(MAX_FIGMA_SCREEN_IDS)} screen ids.`,
+        };
+    }
+    const seen = new Set();
+    for (const item of raw) {
+        if (typeof item !== "string") {
+            return {
+                ok: false,
+                reason: "A figma-snapshot source screenIds field must contain non-empty strings.",
+            };
+        }
+        const screenId = item.trim();
+        if (screenId.length === 0) {
+            return {
+                ok: false,
+                reason: "A figma-snapshot source screenIds field must contain non-empty strings.",
+            };
+        }
+        if (screenId.length > MAX_FIGMA_SCREEN_ID_LENGTH) {
+            return {
+                ok: false,
+                reason: `A figma-snapshot source screen id exceeds the ${String(MAX_FIGMA_SCREEN_ID_LENGTH)}-character limit.`,
+            };
+        }
+        seen.add(screenId);
+    }
+    // Canonical: dedupe (Set) + sort so the derived envelope id / provenance ref is order- and
+    // duplicate-stable, and dedupe across reconnections / re-check is exact.
+    return { ok: true, screenIds: [...seen].sort() };
+}

package/dist/qualityIntelligence/generationPort.d.ts

@@ -0,0 +1,15 @@
+import type { QualityIntelligenceGenerationPort } from "@oscharko-dev/keiko-workflows";
+import type { UiHandlerDeps } from "../deps.js";
+export declare class QiGenerationError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export type QiGenerationTarget = string | {
+    readonly kind: "baseline";
+} | {
+    readonly kind: "model";
+    readonly modelId: string;
+    readonly requestedSeed?: number | undefined;
+};
+export declare function createQiGenerationPort(deps: UiHandlerDeps, target: QiGenerationTarget): QualityIntelligenceGenerationPort;
+//# sourceMappingURL=generationPort.d.ts.map

package/dist/qualityIntelligence/generationPort.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generationPort.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/generationPort.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EACV,iCAAiC,EAGlC,MAAM,+BAA+B,CAAC;AACvC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAIhD,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,SAAgB,IAAI,EAAE,MAAM,CAAC;gBACjB,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAmGD,MAAM,MAAM,kBAAkB,GAC1B,MAAM,GACN;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAA;CAAE,GAC7B;IACE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7C,CAAC;AAsHN,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,kBAAkB,GACzB,iCAAiC,CAMnC"}

package/dist/qualityIntelligence/generationPort.js

@@ -0,0 +1,185 @@
+// Quality Intelligence generation port (Epic #270, Issue #279).
+//
+// Backs the abstract `QualityIntelligenceGenerationPort` (consumed by the model-routed workflow run
+// entry) with the REAL Keiko Model Gateway via `deps.modelPortFactory` — the same seam the
+// Conversation Center / grounded-QA path uses. Applies the #279 capability gate before any request
+// is built (unsupported models fail before a network call), assembles trusted system + instruction
+// segments separately from `<qi-evidence>`-delimited untrusted source text, and scrubs evidence so
+// it cannot break the delimiter or smuggle control characters (Issue #284). No provider SDK import.
+import { QualityIntelligence as MgQI, findCapability, findConfiguredCapability, QualityIntelligenceSafeErrorException, } from "@oscharko-dev/keiko-model-gateway";
+import { QualityIntelligenceHardening, QualityIntelligenceGeneration, } from "@oscharko-dev/keiko-quality-intelligence";
+const BASELINE_GENERATION_OUTPUT = JSON.stringify({ testCases: [] });
+export class QiGenerationError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "QiGenerationError";
+    }
+}
+function capabilityFor(deps, modelId) {
+    return deps.config === undefined
+        ? findCapability(modelId)
+        : findConfiguredCapability(deps.config, modelId);
+}
+// Invisible / directional format controls that NFKC does NOT remove: zero-width characters
+// (ZWSP/ZWNJ/ZWJ and the BOM/ZWNBSP) and bidirectional controls (LRM/RLM, the LRE…RLO embedding/
+// override block, and the isolate block). They carry no legitimate meaning in untrusted source
+// evidence but can smuggle homoglyph/bidi deception into the model prompt — and into any candidate
+// rendered or exported from it. Stripping them is content-preserving for real text (#278 Audit
+// Addendum: normalise untrusted content before model prompt construction, rendering, or export).
+function isInvisibleFormatControl(cp) {
+    return ((cp >= 0x200b && cp <= 0x200f) || // ZWSP, ZWNJ, ZWJ, LRM, RLM
+        (cp >= 0x202a && cp <= 0x202e) || // LRE, RLE, PDF, LRO, RLO
+        (cp >= 0x2066 && cp <= 0x2069) || // LRI, RLI, FSI, PDI
+        cp === 0xfeff // BOM / ZWNBSP
+    );
+}
+// A code point that must be stripped from evidence text: C0 controls (except tab/LF/CR), DEL, C1
+// controls, or an invisible zero-width/bidi format control. Tab/LF/CR survive as legitimate text
+// whitespace so multi-line evidence keeps its structure.
+function isStrippableEvidenceCodePoint(cp) {
+    return ((cp <= 0x1f && cp !== 0x09 && cp !== 0x0a && cp !== 0x0d) ||
+        cp === 0x7f ||
+        (cp >= 0x80 && cp <= 0x9f) ||
+        isInvisibleFormatControl(cp));
+}
+// Strip control / invisible format characters via a code-point scan so the `no-control-regex` rule
+// stays satisfied; then neutralise any literal evidence delimiter so untrusted text cannot close the
+// <qi-evidence> block early.
+function scrubEvidenceText(text) {
+    const normalised = text.normalize("NFKC");
+    let out = "";
+    for (const ch of normalised) {
+        const cp = ch.codePointAt(0);
+        if (cp === undefined)
+            continue;
+        if (!isStrippableEvidenceCodePoint(cp))
+            out += ch;
+    }
+    return out.replace(/<\/?qi-evidence/giu, "[evidence]");
+}
+// Second line of defence behind the structural fence (Issue #284 AC1: "Untrusted content cannot
+// override system or workflow instructions"). After scrubbing, run the natural-language
+// prompt-injection scanner on each evidence block: a detected imperative ("ignore previous
+// instructions", a `system:` role line, a jailbreak token, …) is NOT silently passed through — the
+// block is tagged with the matched pattern names so the model sees the evidence is suspect (it is
+// already DATA, never instructions, per the system prompt). Non-blocking by design: a requirement
+// that legitimately quotes such a phrase must still produce a run, so detection annotates the block
+// rather than failing the run. The pattern names are corpus slugs (`[a-z-]`), inert in an attribute.
+function buildEvidenceBlocks(evidence) {
+    return evidence
+        .map((e) => {
+        const kind = e.kind.replace(/[^a-z0-9-]/giu, "");
+        const scrubbed = scrubEvidenceText(e.text);
+        const scan = QualityIntelligenceHardening.scanForPromptInjections(scrubbed);
+        const flagged = scan.safe ? "" : ` flagged="prompt-injection:${scan.injections.join(",")}"`;
+        return `<qi-evidence index="${String(e.index)}" kind="${kind}"${flagged}>\n${scrubbed}\n</qi-evidence>`;
+    })
+        .join("\n");
+}
+function buildMessages(args) {
+    const blocks = buildEvidenceBlocks(args.evidence);
+    const userContent = `${args.instruction}\n\n${blocks}`;
+    const size = QualityIntelligenceHardening.assertPromptSize(userContent);
+    if (!size.ok) {
+        throw new QiGenerationError("QI_PROMPT_TOO_LARGE", "The assembled prompt exceeds the model token budget; reduce the source size.");
+    }
+    return Object.freeze([
+        Object.freeze({ role: "system", content: args.systemPrompt }),
+        Object.freeze({ role: "user", content: userContent }),
+    ]);
+}
+/** Apply the qi:test-design capability gate and resolve the model port (Epic #761 / #279). */
+function resolveGenerationModel(deps, target) {
+    const { modelId } = target;
+    const capability = capabilityFor(deps, modelId);
+    if (capability === undefined) {
+        throw new QiGenerationError("QI_MODEL_NOT_CONFIGURED", "The selected model is not configured.");
+    }
+    const profile = MgQI.getQualityIntelligenceTaskProfile("qi:test-design");
+    try {
+        MgQI.assertProfileCompatibleWithModel(profile, capability);
+    }
+    catch (error) {
+        if (error instanceof QualityIntelligenceSafeErrorException) {
+            throw new QiGenerationError("QI_MODEL_INCOMPATIBLE", "The selected model cannot generate test cases because it is not a compatible chat model.");
+        }
+        throw error;
+    }
+    const model = deps.modelPortFactory(modelId);
+    if (model === undefined) {
+        throw new QiGenerationError("QI_MODEL_UNAVAILABLE", "The model gateway is not available.");
+    }
+    return {
+        model,
+        modelId,
+        useResponseFormat: capability.supportsResponseFormat === true,
+        useSeed: capability.supportsSeeding === true && target.requestedSeed !== undefined,
+        requestedSeed: target.requestedSeed,
+    };
+}
+function normalizeTarget(target) {
+    if (typeof target === "string") {
+        return { kind: "model", modelId: target };
+    }
+    return target;
+}
+function createBaselineGenerationPort() {
+    return {
+        generate: () => Promise.resolve({
+            rawText: BASELINE_GENERATION_OUTPUT,
+            modelCallCount: 0,
+        }),
+    };
+}
+function buildGenerationRequest(modelId, messages, useResponseFormat, useSeed, requestedSeed) {
+    return {
+        modelId,
+        messages,
+        stream: false,
+        ...(useSeed && requestedSeed !== undefined ? { seed: requestedSeed } : {}),
+        ...(useResponseFormat
+            ? {
+                responseFormat: {
+                    type: "json_schema",
+                    schema: { ...QualityIntelligenceGeneration.QI_TEST_DESIGN_RESPONSE_SCHEMA },
+                },
+            }
+            : {}),
+    };
+}
+function buildModelParameters(useResponseFormat, useSeed, requestedSeed) {
+    const modelParameters = {};
+    if (useResponseFormat)
+        modelParameters.responseFormat = "json_schema";
+    if (useSeed && requestedSeed !== undefined)
+        modelParameters.seed = requestedSeed;
+    return Object.keys(modelParameters).length > 0 ? modelParameters : undefined;
+}
+function createModelGenerationPort(resolved) {
+    const { model, modelId, useResponseFormat, useSeed, requestedSeed } = resolved;
+    return {
+        generate: async (args) => {
+            const messages = buildMessages(args);
+            const signal = args.signal ?? new AbortController().signal;
+            const request = buildGenerationRequest(modelId, messages, useResponseFormat, useSeed, requestedSeed);
+            const response = await model.call(request, signal);
+            const modelParameters = buildModelParameters(useResponseFormat, useSeed, requestedSeed);
+            return {
+                rawText: response.content,
+                modelCallCount: 1,
+                modelId,
+                seedUsed: useSeed && requestedSeed !== undefined ? requestedSeed : null,
+                ...(modelParameters !== undefined ? { modelParameters } : {}),
+            };
+        },
+    };
+}
+export function createQiGenerationPort(deps, target) {
+    const normalized = normalizeTarget(target);
+    if (normalized.kind === "baseline") {
+        return createBaselineGenerationPort();
+    }
+    return createModelGenerationPort(resolveGenerationModel(deps, normalized));
+}

package/dist/qualityIntelligence/handoffErrors.d.ts

@@ -0,0 +1,9 @@
+export type QiHandoffErrorCode = "QI_HANDOFF_BAD_REQUEST" | "QI_HANDOFF_PAYLOAD_TOO_LARGE" | "QI_HANDOFF_UNKNOWN_CHAT_MESSAGE" | "QI_HANDOFF_FORBIDDEN_PAYLOAD" | "QI_HANDOFF_INTERNAL";
+export interface QiHandoffErrorBody {
+    readonly error: {
+        readonly code: QiHandoffErrorCode;
+        readonly message: string;
+    };
+}
+export declare const qiHandoffErrorBody: (code: QiHandoffErrorCode) => QiHandoffErrorBody;
+//# sourceMappingURL=handoffErrors.d.ts.map

package/dist/qualityIntelligence/handoffErrors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffErrors.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/handoffErrors.ts"],"names":[],"mappings":"AAYA,MAAM,MAAM,kBAAkB,GAC1B,wBAAwB,GACxB,8BAA8B,GAC9B,iCAAiC,GACjC,8BAA8B,GAC9B,qBAAqB,CAAC;AAE1B,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACjF;AAaD,eAAO,MAAM,kBAAkB,GAAI,MAAM,kBAAkB,KAAG,kBAE5D,CAAC"}

package/dist/qualityIntelligence/handoffErrors.js

@@ -0,0 +1,21 @@
+// Quality Intelligence handoff route error shapes (Epic #270, Issue #281).
+//
+// Safe error JSON for the Conversation Center → QI workflow handoff route. Error bodies
+// NEVER carry credentials, raw payloads, chat content, envelope ids, header values, or
+// anything that could be mistaken for a secret. Every error message is a fixed string
+// keyed by a stable code. Mirrors the existing connector error envelope shape so the
+// dispatcher serialises it identically (`{ error: { code, message } }`).
+//
+// Note: kept separate from `connectorErrors.ts` to keep route-group code paths cleanly
+// addressable for review and to avoid widening that file's error-code union with handoff
+// concerns. Test parity with the connector error tests is enforced in `__tests__/`.
+const SAFE_MESSAGES = {
+    QI_HANDOFF_BAD_REQUEST: "The request body is not a valid Quality Intelligence handoff envelope.",
+    QI_HANDOFF_PAYLOAD_TOO_LARGE: "The Quality Intelligence handoff envelope exceeds the maximum permitted size.",
+    QI_HANDOFF_UNKNOWN_CHAT_MESSAGE: "The referenced Conversation Center chat message could not be located.",
+    QI_HANDOFF_FORBIDDEN_PAYLOAD: "The handoff envelope contained a forbidden field. Handoff envelopes may not carry chat content, credentials, headers, or URLs.",
+    QI_HANDOFF_INTERNAL: "The Quality Intelligence handoff route could not service the request.",
+};
+export const qiHandoffErrorBody = (code) => ({
+    error: { code, message: SAFE_MESSAGES[code] },
+});

package/dist/qualityIntelligence/handoffRoutes.d.ts

@@ -0,0 +1,15 @@
+import type { RouteContext, RouteDefinition, RouteResult } from "../routes.js";
+import type { UiHandlerDeps } from "../deps.js";
+export interface QiHandoffSuccessBody {
+    readonly handoffId: string;
+    readonly chatId: string;
+    readonly persistedMessageId: string;
+    readonly runId?: string;
+}
+export interface QiHandoffRouteOptions {
+    readonly now?: () => number;
+}
+export declare const createHandleQiHandoff: (options?: QiHandoffRouteOptions) => ((ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>);
+export declare const handleQiHandoff: (ctx: RouteContext, deps: UiHandlerDeps) => Promise<RouteResult>;
+export declare const QI_HANDOFF_ROUTE_GROUP: readonly RouteDefinition[];
+//# sourceMappingURL=handoffRoutes.d.ts.map

package/dist/qualityIntelligence/handoffRoutes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoffRoutes.d.ts","sourceRoot":"","sources":["../../src/qualityIntelligence/handoffRoutes.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC/E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAiUhD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED,eAAO,MAAM,qBAAqB,GAChC,UAAS,qBAA0B,KAClC,CAAC,CAAC,GAAG,EAAE,YAAY,EAAE,IAAI,EAAE,aAAa,KAAK,OAAO,CAAC,WAAW,CAAC,CAwCnE,CAAC;AAEF,eAAO,MAAM,eAAe,QA1ClB,YAAY,QAAQ,aAAa,KAAK,OAAO,CAAC,WAAW,CA0Cb,CAAC;AAKvD,eAAO,MAAM,sBAAsB,EAAE,SAAS,eAAe,EAM5D,CAAC"}