@oscharko-dev/keiko-contracts 0.2.0

package/dist/conversation-budget.js

@@ -0,0 +1,97 @@
+// Conversation budget estimator (Issue #151 / Epic #142).
+//
+// Pure, deterministic helper that estimates how much of a chat model's context
+// window is consumed by a conversation turn. The UI uses this for the
+// pre-send pressure indicator (AC#1) and the "clear history" affordance
+// (AC#4). The breakdown carries connected-context byte counts so they can
+// be disclosed and removable from the next call (AC#5).
+//
+// Engineering note (from the issue): token counting is APPROXIMATE here.
+// We use bytes/4 as a rough proxy. UI copy and tests MUST state this
+// precisely — do not present byte estimates as exact tokens.
+// Average ASCII byte ≈ 4 chars per token in mainstream BPE tokenizers. This
+// is an over-simplification; we surface it as APPROXIMATE everywhere.
+const APPROX_BYTES_PER_TOKEN = 4;
+// Pressure thresholds, applied against the fraction of availableInputTokens
+// the approximate token count consumes.
+const PRESSURE_LOW = 0.5;
+const PRESSURE_MODERATE = 0.75;
+const PRESSURE_HIGH = 0.95;
+function coerceNonNegativeInt(value) {
+    if (value === undefined)
+        return 0;
+    if (!Number.isFinite(value))
+        return 0;
+    if (value <= 0)
+        return 0;
+    return Math.floor(value);
+}
+function utf8ByteLength(text) {
+    // Browsers and Node both expose TextEncoder. Falls back to char length
+    // when (in some legacy harness) it is absent — acceptable since the
+    // result is documented approximate.
+    if (typeof TextEncoder !== "undefined") {
+        return new TextEncoder().encode(text).length;
+    }
+    return text.length;
+}
+function sumHistoryBytes(history) {
+    let total = 0;
+    for (const message of history) {
+        total += utf8ByteLength(message.role);
+        total += utf8ByteLength(message.content);
+    }
+    return total;
+}
+function sumDocumentBytes(documents) {
+    if (documents === undefined)
+        return 0;
+    let total = 0;
+    for (const document of documents) {
+        total += coerceNonNegativeInt(document.extractedBytes);
+    }
+    return total;
+}
+function classifyPressure(tokens, availableInputTokens) {
+    if (availableInputTokens <= 0)
+        return "exceeded";
+    const ratio = tokens / availableInputTokens;
+    if (ratio > PRESSURE_HIGH)
+        return "exceeded";
+    if (ratio > PRESSURE_MODERATE)
+        return "high";
+    if (ratio > PRESSURE_LOW)
+        return "moderate";
+    return "low";
+}
+export function estimateConversationBudget(input) {
+    const contextWindowTokens = coerceNonNegativeInt(input.modelContextWindow);
+    const reservedOutputTokens = coerceNonNegativeInt(input.modelMaxOutputTokens);
+    const availableInputTokens = Math.max(0, contextWindowTokens - reservedOutputTokens);
+    const draftBytes = utf8ByteLength(input.userDraftText);
+    const historyBytes = sumHistoryBytes(input.conversationHistory);
+    const documentBytes = sumDocumentBytes(input.documentContext);
+    const repoContextBytes = coerceNonNegativeInt(input.repoContextPackBytes);
+    const knowledgeBytes = coerceNonNegativeInt(input.knowledgeCapsuleBytes);
+    const memoryBytes = coerceNonNegativeInt(input.memoryContextBytes);
+    const breakdown = {
+        draftBytes,
+        historyBytes,
+        documentBytes,
+        repoContextBytes,
+        knowledgeBytes,
+        memoryBytes,
+    };
+    const approximateBytes = draftBytes + historyBytes + documentBytes + repoContextBytes + knowledgeBytes + memoryBytes;
+    const approximateTokens = Math.ceil(approximateBytes / APPROX_BYTES_PER_TOKEN);
+    const pressure = classifyPressure(approximateTokens, availableInputTokens);
+    return {
+        approximateBytes,
+        approximateTokens,
+        contextWindowTokens,
+        reservedOutputTokens,
+        availableInputTokens,
+        pressure,
+        breakdown,
+    };
+}

package/dist/editor-agent.d.ts

@@ -0,0 +1,131 @@
+import type { EditorDocumentVersion } from "./editor-session.js";
+import type { LanguageRange } from "./language-service.js";
+export declare const EDITOR_AGENT_SCHEMA_VERSION: "1";
+export type EditorAgentSnapshotTextMode = "none" | "selection" | "activeFile";
+export interface EditorAgentPaneSnapshot {
+    readonly paneId: string;
+    readonly activeFile: string | null;
+    readonly openFiles: readonly string[];
+}
+export interface EditorAgentSessionSnapshot {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly sessionId: string;
+    readonly windowId: string;
+    readonly workspaceRoot: string;
+    readonly activePaneId: string | null;
+    readonly panes: readonly EditorAgentPaneSnapshot[];
+    readonly dirtyFiles: readonly string[];
+    readonly activeFile: string | null;
+    readonly cursor: {
+        readonly line: number;
+        readonly character: number;
+    } | null;
+    readonly selection: LanguageRange | null;
+    readonly diagnosticsSummary: {
+        readonly errors: number;
+        readonly warnings: number;
+        readonly infos: number;
+    } | null;
+    readonly documentVersion?: EditorDocumentVersion | undefined;
+    readonly activeFileContentHash?: string | undefined;
+    readonly textMode: EditorAgentSnapshotTextMode;
+    readonly text?: string | undefined;
+    readonly textTruncated?: boolean | undefined;
+    readonly updatedAt: number;
+}
+export type EditorAgentActionType = "openFile" | "focusTab" | "moveTab" | "splitPane" | "setSelection" | "format" | "save" | "applyTextEdits" | "applyPatch";
+export interface EditorAgentAction {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly actionId: string;
+    readonly idempotencyKey: string;
+    readonly sessionId: string;
+    readonly type: EditorAgentActionType;
+    readonly target?: {
+        readonly paneId?: string | undefined;
+        readonly file?: string | undefined;
+        readonly toPaneId?: string | undefined;
+        readonly splitDirection?: "row" | "column" | undefined;
+        readonly selection?: LanguageRange | undefined;
+    } | undefined;
+    readonly expectedDocumentVersion?: EditorDocumentVersion | undefined;
+    readonly expectedContentHash?: string | undefined;
+    readonly textEdits?: readonly {
+        readonly range: LanguageRange;
+        readonly newText: string;
+    }[] | undefined;
+    readonly patch?: string | undefined;
+}
+export type EditorAgentActionStatus = "queued" | "succeeded" | "failed" | "conflict";
+export interface EditorAgentActionResult {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly actionId: string;
+    readonly sessionId: string;
+    readonly status: EditorAgentActionStatus;
+    readonly message?: string | undefined;
+    readonly conflict?: {
+        readonly code: "DIRTY" | "VERSION_MISMATCH" | "CONTENT_HASH_MISMATCH" | "NO_ACTIVE_SESSION";
+        readonly message: string;
+    } | undefined;
+}
+export type EditorAgentEvent = {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly eventId: string;
+    readonly type: "session";
+    readonly snapshot: EditorAgentSessionSnapshot;
+} | {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly eventId: string;
+    readonly type: "action";
+    readonly action: EditorAgentAction;
+} | {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly eventId: string;
+    readonly type: "result";
+    readonly result: EditorAgentActionResult;
+} | {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly eventId: string;
+    readonly type: "heartbeat";
+    readonly updatedAt: number;
+};
+export interface EditorAgentSnapshotRequest {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly sessionId?: string | undefined;
+    readonly textMode: EditorAgentSnapshotTextMode;
+    readonly maxBytes?: number | undefined;
+}
+export interface EditorAgentBridgeSnapshotRequest {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly kind: "snapshot";
+    readonly snapshot: EditorAgentSessionSnapshot;
+}
+export interface EditorAgentActionResultRequest {
+    readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
+    readonly kind: "result";
+    readonly result: EditorAgentActionResult;
+}
+export type EditorAgentActionsPostBody = EditorAgentAction | EditorAgentActionResultRequest;
+export interface EditorAgentSessionsResponse {
+    readonly sessions: readonly EditorAgentSessionSnapshot[];
+}
+export interface EditorAgentActionQueuedResponse {
+    readonly result: EditorAgentActionResult;
+}
+export interface EditorAgentSnapshotResponse {
+    readonly snapshot: EditorAgentSessionSnapshot | null;
+}
+export interface EditorAgentParseOk<T> {
+    readonly ok: true;
+    readonly value: T;
+}
+export interface EditorAgentParseFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type EditorAgentParse<T> = EditorAgentParseOk<T> | EditorAgentParseFail;
+export declare function isEditorAgentSessionSnapshot(value: unknown): value is EditorAgentSessionSnapshot;
+export declare function isEditorAgentAction(value: unknown): value is EditorAgentAction;
+export declare function isEditorAgentActionResult(value: unknown): value is EditorAgentActionResult;
+export declare function parseEditorAgentSnapshotRequest(value: unknown): EditorAgentParse<EditorAgentSnapshotRequest | EditorAgentBridgeSnapshotRequest>;
+export declare function parseEditorAgentActionsPostBody(value: unknown): EditorAgentParse<EditorAgentActionsPostBody>;
+//# sourceMappingURL=editor-agent.d.ts.map

package/dist/editor-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-agent.d.ts","sourceRoot":"","sources":["../src/editor-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAE3D,eAAO,MAAM,2BAA2B,EAAG,GAAY,CAAC;AAExD,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,WAAW,GAAG,YAAY,CAAC;AAE9E,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,MAAM,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,SAAS,uBAAuB,EAAE,CAAC;IACnD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E,QAAQ,CAAC,SAAS,EAAE,aAAa,GAAG,IAAI,CAAC;IACzC,QAAQ,CAAC,kBAAkB,EACvB;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;KAAE,GAC9E,IAAI,CAAC;IACT,QAAQ,CAAC,eAAe,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IAC7D,QAAQ,CAAC,qBAAqB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;IAC/C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;IAC7C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,MAAM,qBAAqB,GAC7B,UAAU,GACV,UAAU,GACV,SAAS,GACT,WAAW,GACX,cAAc,GACd,QAAQ,GACR,MAAM,GACN,gBAAgB,GAChB,YAAY,CAAC;AAEjB,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,MAAM,CAAC,EAAE;QAChB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACrC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACnC,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;QACvC,QAAQ,CAAC,cAAc,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,SAAS,CAAC;QACvD,QAAQ,CAAC,SAAS,CAAC,EAAE,aAAa,GAAG,SAAS,CAAC;KAChD,GAAG,SAAS,CAAC;IACd,QAAQ,CAAC,uBAAuB,CAAC,EAAE,qBAAqB,GAAG,SAAS,CAAC;IACrE,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAClD,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,GAAG,SAAS,CAAC;IACxG,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACrC;AAED,MAAM,MAAM,uBAAuB,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErF,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;IACzC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,QAAQ,CAAC,QAAQ,CAAC,EACd;QACE,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,kBAAkB,GAAG,uBAAuB,GAAG,mBAAmB,CAAC;QAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,GACD,SAAS,CAAC;CACf;AAED,MAAM,MAAM,gBAAgB,GACxB;IACE,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C,GACD;IACE,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;CACpC,GACD;IACE,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C,GACD;IACE,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,2BAA2B,CAAC;IAC/C,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACxC;AAED,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;CAC/C;AAED,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,aAAa,EAAE,OAAO,2BAA2B,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAED,MAAM,MAAM,0BAA0B,GAAG,iBAAiB,GAAG,8BAA8B,CAAC;AAE5F,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,SAAS,0BAA0B,EAAE,CAAC;CAC1D;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,MAAM,EAAE,uBAAuB,CAAC;CAC1C;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,GAAG,IAAI,CAAC;CACtD;AAED,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;CACnB;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;CACpC;AAED,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI,kBAAkB,CAAC,CAAC,CAAC,GAAG,oBAAoB,CAAC;AA2F/E,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,0BAA0B,CAqBhG;AAgCD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,iBAAiB,CAc9E;AAMD,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,uBAAuB,CAS1F;AA0CD,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,gBAAgB,CAAC,0BAA0B,GAAG,gCAAgC,CAAC,CAGjF;AAED,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,OAAO,GACb,gBAAgB,CAAC,0BAA0B,CAAC,CAa9C"}

package/dist/editor-agent.js

@@ -0,0 +1,197 @@
+export const EDITOR_AGENT_SCHEMA_VERSION = "1";
+const EDITOR_AGENT_ACTION_TYPES = [
+    "openFile",
+    "focusTab",
+    "moveTab",
+    "splitPane",
+    "setSelection",
+    "format",
+    "save",
+    "applyTextEdits",
+    "applyPatch",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === "string";
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isSha256Hex(value) {
+    return typeof value === "string" && /^[a-f0-9]{64}$/u.test(value);
+}
+function isNullOr(value, guard) {
+    return value === null || guard(value);
+}
+function isUndefinedOr(value, guard) {
+    return value === undefined || guard(value);
+}
+function isDocumentVersion(value) {
+    return (isRecord(value) &&
+        isNonNegativeInteger(value.sizeBytes) &&
+        isNonNegativeInteger(value.modifiedAt) &&
+        isSha256Hex(value.contentHash));
+}
+function isPosition(value) {
+    return isRecord(value) && isNonNegativeInteger(value.line) && isNonNegativeInteger(value.character);
+}
+function isRange(value) {
+    return isRecord(value) && isPosition(value.start) && isPosition(value.end);
+}
+function isDiagnosticsSummary(value) {
+    return (isRecord(value) &&
+        isNonNegativeInteger(value.errors) &&
+        isNonNegativeInteger(value.warnings) &&
+        isNonNegativeInteger(value.infos));
+}
+function isPaneSnapshot(value) {
+    return (isRecord(value) &&
+        isNonEmptyString(value.paneId) &&
+        (value.activeFile === null || typeof value.activeFile === "string") &&
+        isStringArray(value.openFiles));
+}
+function isSnapshotTextMode(value) {
+    return value === "none" || value === "selection" || value === "activeFile";
+}
+function isPaneSnapshotArray(value) {
+    return Array.isArray(value) && value.every(isPaneSnapshot);
+}
+export function isEditorAgentSessionSnapshot(value) {
+    if (!isRecord(value))
+        return false;
+    return [
+        value.schemaVersion === EDITOR_AGENT_SCHEMA_VERSION,
+        isNonEmptyString(value.sessionId),
+        isNonEmptyString(value.windowId),
+        isNonEmptyString(value.workspaceRoot),
+        isNullOr(value.activePaneId, isString),
+        isPaneSnapshotArray(value.panes),
+        isStringArray(value.dirtyFiles),
+        isNullOr(value.activeFile, isString),
+        isNullOr(value.cursor, isPosition),
+        isNullOr(value.selection, isRange),
+        isNullOr(value.diagnosticsSummary, isDiagnosticsSummary),
+        isUndefinedOr(value.documentVersion, isDocumentVersion),
+        isUndefinedOr(value.activeFileContentHash, isSha256Hex),
+        isSnapshotTextMode(value.textMode),
+        isUndefinedOr(value.text, isString),
+        isUndefinedOr(value.textTruncated, (candidate) => typeof candidate === "boolean"),
+        isNonNegativeInteger(value.updatedAt),
+    ].every(Boolean);
+}
+function isActionType(value) {
+    return typeof value === "string" && EDITOR_AGENT_ACTION_TYPES.includes(value);
+}
+function isSplitDirection(value) {
+    return value === "row" || value === "column";
+}
+function isActionTarget(value) {
+    if (value === undefined)
+        return true;
+    if (!isRecord(value))
+        return false;
+    return [
+        isUndefinedOr(value.paneId, isString),
+        isUndefinedOr(value.file, isString),
+        isUndefinedOr(value.toPaneId, isString),
+        isUndefinedOr(value.splitDirection, isSplitDirection),
+        isUndefinedOr(value.selection, isRange),
+    ].every(Boolean);
+}
+function isTextEdit(value) {
+    return isRecord(value) && isRange(value.range) && typeof value.newText === "string";
+}
+function isTextEditArray(value) {
+    return Array.isArray(value) && value.every(isTextEdit);
+}
+export function isEditorAgentAction(value) {
+    if (!isRecord(value))
+        return false;
+    return [
+        value.schemaVersion === EDITOR_AGENT_SCHEMA_VERSION,
+        isNonEmptyString(value.actionId),
+        isNonEmptyString(value.idempotencyKey),
+        isNonEmptyString(value.sessionId),
+        isActionType(value.type),
+        isActionTarget(value.target),
+        isUndefinedOr(value.expectedDocumentVersion, isDocumentVersion),
+        isUndefinedOr(value.expectedContentHash, isSha256Hex),
+        isUndefinedOr(value.textEdits, isTextEditArray),
+        isUndefinedOr(value.patch, isString),
+    ].every(Boolean);
+}
+function isActionStatus(value) {
+    return value === "queued" || value === "succeeded" || value === "failed" || value === "conflict";
+}
+export function isEditorAgentActionResult(value) {
+    return (isRecord(value) &&
+        value.schemaVersion === EDITOR_AGENT_SCHEMA_VERSION &&
+        isNonEmptyString(value.actionId) &&
+        isNonEmptyString(value.sessionId) &&
+        isActionStatus(value.status) &&
+        (value.message === undefined || typeof value.message === "string"));
+}
+function parseBridgeSnapshotRequest(value) {
+    if (!isEditorAgentSessionSnapshot(value.snapshot)) {
+        return { ok: false, errors: ["snapshot must be a valid editor agent session snapshot"] };
+    }
+    return {
+        ok: true,
+        value: {
+            schemaVersion: EDITOR_AGENT_SCHEMA_VERSION,
+            kind: "snapshot",
+            snapshot: value.snapshot,
+        },
+    };
+}
+function parseReadSnapshotRequest(value) {
+    if (value.schemaVersion !== EDITOR_AGENT_SCHEMA_VERSION) {
+        return { ok: false, errors: ["schemaVersion must be 1"] };
+    }
+    if (!isSnapshotTextMode(value.textMode)) {
+        return { ok: false, errors: ["textMode must be none, selection, or activeFile"] };
+    }
+    if (value.sessionId !== undefined && typeof value.sessionId !== "string") {
+        return { ok: false, errors: ["sessionId must be a string when present"] };
+    }
+    if (value.maxBytes !== undefined && !isNonNegativeInteger(value.maxBytes)) {
+        return { ok: false, errors: ["maxBytes must be a non-negative integer when present"] };
+    }
+    return {
+        ok: true,
+        value: {
+            schemaVersion: EDITOR_AGENT_SCHEMA_VERSION,
+            ...(value.sessionId === undefined ? {} : { sessionId: value.sessionId }),
+            textMode: value.textMode,
+            ...(value.maxBytes === undefined ? {} : { maxBytes: value.maxBytes }),
+        },
+    };
+}
+export function parseEditorAgentSnapshotRequest(value) {
+    if (!isRecord(value))
+        return { ok: false, errors: ["request must be an object"] };
+    return value.kind === "snapshot" ? parseBridgeSnapshotRequest(value) : parseReadSnapshotRequest(value);
+}
+export function parseEditorAgentActionsPostBody(value) {
+    if (isEditorAgentAction(value))
+        return { ok: true, value };
+    if (isRecord(value) && value.kind === "result" && isEditorAgentActionResult(value.result)) {
+        return {
+            ok: true,
+            value: {
+                schemaVersion: EDITOR_AGENT_SCHEMA_VERSION,
+                kind: "result",
+                result: value.result,
+            },
+        };
+    }
+    return { ok: false, errors: ["body must be an editor agent action or action result"] };
+}

package/dist/editor-completion.d.ts

@@ -0,0 +1,62 @@
+import { type LanguageCompletionItemKind, type LanguageDocumentOverlay, type LanguagePosition } from "./language-service.js";
+import type { CompletionDegradeReason, CompletionInteractionMode, CostClass } from "./gateway.js";
+export declare const EDITOR_COMPLETION_SCHEMA_VERSION: "1";
+export type EditorCompletionWireTriggerKind = "invoked" | "trigger-character" | "incomplete";
+export declare const EDITOR_COMPLETION_WIRE_TRIGGER_KINDS: readonly EditorCompletionWireTriggerKind[];
+export type EditorCompletionItemOrigin = "deterministic" | "model-assisted";
+export declare const EDITOR_COMPLETION_ITEM_ORIGINS: readonly EditorCompletionItemOrigin[];
+export interface EditorCompletionWireItem {
+    readonly label: string;
+    readonly kind: LanguageCompletionItemKind;
+    readonly insertText: string;
+    readonly detail?: string;
+    readonly sortText?: string;
+    readonly origin: EditorCompletionItemOrigin;
+}
+export type EditorCompletionSource = "deterministic-language-service" | "model-assisted" | "repository-context" | "local-knowledge" | "memory" | "connected-context";
+export declare const EDITOR_COMPLETION_SOURCES: readonly EditorCompletionSource[];
+export interface EditorCompletionWireProvenance {
+    readonly sources: readonly EditorCompletionSource[];
+    readonly modelMode: CompletionInteractionMode;
+    readonly modelId?: string;
+    readonly latencyClass?: string;
+    readonly degradeReason?: CompletionDegradeReason;
+    readonly gatewayPolicyVersion?: string;
+    readonly promptHash?: string;
+}
+export interface EditorCompletionWireResponse {
+    readonly schemaVersion: typeof EDITOR_COMPLETION_SCHEMA_VERSION;
+    readonly items: readonly EditorCompletionWireItem[];
+    readonly isIncomplete: boolean;
+    readonly truncated: boolean;
+    readonly provenance: EditorCompletionWireProvenance;
+}
+export interface EditorCompletionContextSelectors {
+    readonly queryText?: string;
+    readonly symbol?: string;
+    readonly changedFiles?: readonly string[];
+    readonly capsuleId?: string;
+    readonly capsuleSetId?: string;
+}
+export interface EditorCompletionWireRequest {
+    readonly schemaVersion: typeof EDITOR_COMPLETION_SCHEMA_VERSION;
+    readonly root: string;
+    readonly document: LanguageDocumentOverlay;
+    readonly position: LanguagePosition;
+    readonly triggerKind: EditorCompletionWireTriggerKind;
+    readonly triggerCharacter?: string;
+    readonly contextBudgetBytes: number;
+    readonly context?: EditorCompletionContextSelectors;
+    readonly maxCostClass?: CostClass;
+}
+export interface EditorCompletionParseOk {
+    readonly ok: true;
+    readonly value: EditorCompletionWireRequest;
+}
+export interface EditorCompletionParseFail {
+    readonly ok: false;
+    readonly errors: readonly string[];
+}
+export type EditorCompletionParse = EditorCompletionParseOk | EditorCompletionParseFail;
+export declare function parseEditorCompletionRequest(value: unknown): EditorCompletionParse;
+//# sourceMappingURL=editor-completion.d.ts.map

package/dist/editor-completion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-completion.d.ts","sourceRoot":"","sources":["../src/editor-completion.ts"],"names":[],"mappings":"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"}

package/dist/editor-completion.js

@@ -0,0 +1,147 @@
+// Editor completion-gateway WIRE contract (Issue #1199, Epic #1189, ADR-0042 D4/D5/D6). These are
+// the request/response shapes the `POST /api/editor/completion` BFF route consumes and emits. The
+// route is the governed seam between the browser-tier `@oscharko-dev/keiko-editor` Monaco completion
+// provider (which renders only) and the server-owned completion sources: the deterministic
+// language service (#1198), governed coding-context retrieval (#1211), and — only when an aligned,
+// in-budget infilling model is configured (#1210) — model-assisted completion routed through the
+// Model Gateway.
+//
+// Content boundary: the REQUEST necessarily carries the in-editor buffer text (the overlay the
+// language service analyses), exactly like the language-service request (#1198) — it is the user's
+// own buffer travelling over the loopback BFF, never logged. The RESPONSE is content-free apart from
+// `insertText`, which is the reviewable code artifact the user accepts into their own buffer: no raw
+// prompt, no raw model reasoning, no retrieved excerpt, no secret. Provenance carries only ids,
+// hashes, enum literals, and counts (EU AI Act Reg. (EU) 2024/1689 Art. 12 record-keeping).
+//
+// Leaf-package rules (ADR-0019): pure types and frozen const tables plus throw-free validators only.
+// No filesystem, no clock, no crypto, no randomness, and no imports of other `@oscharko-dev/keiko-*`
+// packages. The item-kind set is reused from the language-service contract so the editor renders one
+// stable icon set across deterministic and model-assisted items.
+import { isLanguageDocumentOverlay, isLanguagePosition, } from "./language-service.js";
+// Schema version for the completion-gateway envelope. Bump as a new string member when the shape
+// changes incompatibly; consumers pin against the literal to detect skew.
+export const EDITOR_COMPLETION_SCHEMA_VERSION = "1";
+export const EDITOR_COMPLETION_WIRE_TRIGGER_KINDS = [
+    "invoked",
+    "trigger-character",
+    "incomplete",
+];
+export const EDITOR_COMPLETION_ITEM_ORIGINS = [
+    "deterministic",
+    "model-assisted",
+];
+export const EDITOR_COMPLETION_SOURCES = [
+    "deterministic-language-service",
+    "model-assisted",
+    "repository-context",
+    "local-knowledge",
+    "memory",
+    "connected-context",
+];
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isNonNegativeInteger(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0;
+}
+function isWireTriggerKind(value) {
+    return (typeof value === "string" &&
+        EDITOR_COMPLETION_WIRE_TRIGGER_KINDS.includes(value));
+}
+function isCostClass(value) {
+    return value === "low" || value === "medium" || value === "high";
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((entry) => typeof entry === "string");
+}
+// Collects the optional, content-bearing context selectors. Unknown-typed fields are rejected so a
+// malformed selector cannot silently widen retrieval; an absent `context` is valid (deterministic +
+// repo-search only).
+function collectContextErrors(context, errors) {
+    if (context === undefined) {
+        return;
+    }
+    if (!isRecord(context)) {
+        errors.push("context must be an object when provided");
+        return;
+    }
+    for (const field of ["queryText", "symbol", "capsuleId", "capsuleSetId"]) {
+        if (context[field] !== undefined && typeof context[field] !== "string") {
+            errors.push(`context.${field} must be a string when provided`);
+        }
+    }
+    if (context.changedFiles !== undefined && !isStringArray(context.changedFiles)) {
+        errors.push("context.changedFiles must be an array of strings when provided");
+    }
+    if (context.capsuleId !== undefined && context.capsuleSetId !== undefined) {
+        errors.push("context must not set both capsuleId and capsuleSetId");
+    }
+}
+function buildContextSelectors(context) {
+    return {
+        ...(typeof context.queryText === "string" ? { queryText: context.queryText } : {}),
+        ...(typeof context.symbol === "string" ? { symbol: context.symbol } : {}),
+        ...(isStringArray(context.changedFiles) ? { changedFiles: context.changedFiles } : {}),
+        ...(typeof context.capsuleId === "string" ? { capsuleId: context.capsuleId } : {}),
+        ...(typeof context.capsuleSetId === "string" ? { capsuleSetId: context.capsuleSetId } : {}),
+    };
+}
+// Collects every field-level invariant error in fixed order (kept separate from the assembly step so
+// the parser entry point stays low-complexity).
+function collectRequestErrors(value) {
+    const errors = [];
+    if (!isNonEmptyString(value.root)) {
+        errors.push("root must be a non-empty string");
+    }
+    if (!isLanguageDocumentOverlay(value.document)) {
+        errors.push("document must be { path, languageId, text }");
+    }
+    if (!isLanguagePosition(value.position)) {
+        errors.push("position must be { line, character }");
+    }
+    if (!isWireTriggerKind(value.triggerKind)) {
+        errors.push(`triggerKind must be one of: ${EDITOR_COMPLETION_WIRE_TRIGGER_KINDS.join(", ")}`);
+    }
+    if (value.triggerCharacter !== undefined && typeof value.triggerCharacter !== "string") {
+        errors.push("triggerCharacter must be a string when provided");
+    }
+    if (!isNonNegativeInteger(value.contextBudgetBytes)) {
+        errors.push("contextBudgetBytes must be a non-negative integer");
+    }
+    if (value.maxCostClass !== undefined && !isCostClass(value.maxCostClass)) {
+        errors.push("maxCostClass must be one of: low, medium, high");
+    }
+    collectContextErrors(value.context, errors);
+    return errors;
+}
+// Validates an `unknown` payload into an EditorCompletionWireRequest, reporting one error per failed
+// invariant. The BFF uses this to reject a malformed request with 400 INVALID_REQUEST.
+export function parseEditorCompletionRequest(value) {
+    if (!isRecord(value)) {
+        return { ok: false, errors: ["request must be an object"] };
+    }
+    const errors = collectRequestErrors(value);
+    if (errors.length > 0) {
+        return { ok: false, errors };
+    }
+    const context = isRecord(value.context) ? buildContextSelectors(value.context) : undefined;
+    return {
+        ok: true,
+        value: {
+            schemaVersion: EDITOR_COMPLETION_SCHEMA_VERSION,
+            root: value.root,
+            document: value.document,
+            position: value.position,
+            triggerKind: value.triggerKind,
+            ...(typeof value.triggerCharacter === "string"
+                ? { triggerCharacter: value.triggerCharacter }
+                : {}),
+            contextBudgetBytes: value.contextBudgetBytes,
+            ...(context !== undefined && Object.keys(context).length > 0 ? { context } : {}),
+            ...(isCostClass(value.maxCostClass) ? { maxCostClass: value.maxCostClass } : {}),
+        },
+    };
+}

package/dist/editor-dirty-close.d.ts

@@ -0,0 +1,17 @@
+export type EditorDirtyCloseReason = "tab-close" | "pane-close" | "root-change" | "window-close" | "reload-file";
+export interface EditorDirtyCloseIntent {
+    readonly paneId: string;
+    readonly files: readonly string[];
+    readonly reason: EditorDirtyCloseReason;
+}
+export type EditorDirtyCloseDecision = "save" | "discard" | "cancel";
+export interface EditorDirtyCloseResolution {
+    readonly decision: EditorDirtyCloseDecision;
+    readonly files: readonly string[];
+}
+export declare function createEditorDirtyCloseIntent(input: {
+    readonly paneId: string;
+    readonly files: readonly string[];
+    readonly reason: EditorDirtyCloseReason;
+}): EditorDirtyCloseIntent;
+//# sourceMappingURL=editor-dirty-close.d.ts.map