@oscharko-dev/keiko-contracts 0.2.8 → 0.2.9

package/dist/editor-agent-governance.js

@@ -0,0 +1,180 @@
+// Agent editor action governance, policy, and bounded audit (Issue #1395, ADR-0062).
+//
+// This leaf adds two things on top of the frozen editor-agent control-plane contract
+// (`editor-agent.ts`): a deterministic policy classifier that marks each action allowed,
+// review-required, or denied (AC2), and a content-free audit record shape + pure builder for the
+// bounded audit metadata every mutating action produces (AC1, AC3).
+//
+// Leaf-package rule (ADR-0019 direction 1): no `@oscharko-dev/keiko-*` imports. The classifier is a
+// pure function over its inputs; workspace-sensitivity (`isDenied`) is a `keiko-workspace` concern,
+// so the server computes that boolean and passes it in. Workspace containment reuses the existing
+// `isContainedAgentPath` guard, which already lives in this package.
+//
+// Audit invariant (mirrors `MemoryAuditEvent` and `patchApplyEvidence`): the record NEVER carries
+// raw source text, edit bodies, patch bodies, or secrets. The builder input type has no field that
+// could hold raw content — only enums, counts, identifiers, a workspace-relative path, and a bounded
+// summary — so a content leak is impossible by construction. The server additionally runs every
+// record through the `keiko-security` redactor (defense in depth) before it is stored or served.
+import { isContainedAgentPath, } from "./editor-agent.js";
+// ─── Schema version ───────────────────────────────────────────────────────────
+// Pinned to "1". A breaking change introduces a NEW literal rather than mutating "1", the same
+// evolution rule as `EDITOR_AGENT_SCHEMA_VERSION` and the other audit surfaces.
+export const EDITOR_AGENT_AUDIT_SCHEMA_VERSION = "1";
+// Maximum length for the bounded, redacted `summary`. Audit summaries are dense one-line rationales,
+// never bodies; the bound keeps a long target path or reason string from growing the record.
+export const EDITOR_AGENT_AUDIT_SUMMARY_MAX_CHARS = 200;
+export const EDITOR_AGENT_ACTION_EFFECT_CLASS = {
+    openFile: "navigation",
+    focusTab: "navigation",
+    setSelection: "navigation",
+    moveTab: "layout",
+    splitPane: "layout",
+    format: "content-mutation",
+    save: "content-mutation",
+    applyTextEdits: "content-mutation",
+    applyPatch: "content-mutation",
+};
+// The mutating action set — the classes that change buffer/file content or have an external effect.
+// AC1: every mutating action produces a bounded audit record. Today this resolves to the four write
+// action types; the predicate keeps that derived from the effect-class table rather than re-listed.
+export function isMutatingEditorAgentAction(type) {
+    const effectClass = EDITOR_AGENT_ACTION_EFFECT_CLASS[type];
+    return effectClass === "content-mutation" || effectClass === "external-effect";
+}
+export const EDITOR_AGENT_ACTION_DISPOSITIONS = [
+    "allowed",
+    "review-required",
+    "denied",
+];
+export const EDITOR_AGENT_ACTION_DENY_REASONS = [
+    "workspace-boundary-escape",
+    "denied-sensitive-path",
+];
+export const EDITOR_AGENT_ACTION_REVIEW_REASONS = [
+    "content-mutation-requires-review",
+    "external-effect-requires-review",
+];
+const ALLOWED = {
+    disposition: "allowed",
+    effectClass: "navigation",
+};
+function denyDecision(effectClass, denyReason) {
+    return { disposition: "denied", effectClass, denyReason };
+}
+function reviewDecision(effectClass, reviewReason) {
+    return { disposition: "review-required", effectClass, reviewReason };
+}
+// A content mutation is denied when its target escapes the workspace root or matches the deny-list,
+// otherwise it requires human review (the existing #1394 browser diff-review is the review gate).
+function classifyContentMutation(context) {
+    if (context.targetPath !== null && !isContainedAgentPath(context.targetPath)) {
+        return denyDecision("content-mutation", "workspace-boundary-escape");
+    }
+    if (context.targetSensitive) {
+        return denyDecision("content-mutation", "denied-sensitive-path");
+    }
+    return reviewDecision("content-mutation", "content-mutation-requires-review");
+}
+// Deterministic, fail-closed policy classifier (AC2). Pure: same (type, context) always yields the
+// same decision, which is required for replay-safe audit and for idempotent action handling. The
+// classifier governs policy posture only; it does NOT re-check the #1394 structural preconditions
+// (version/hash/overlap), which remain upstream gates.
+export function classifyEditorAgentAction(type, context) {
+    const effectClass = EDITOR_AGENT_ACTION_EFFECT_CLASS[type];
+    switch (effectClass) {
+        case "navigation":
+        case "layout":
+            return { ...ALLOWED, effectClass };
+        case "content-mutation":
+            return classifyContentMutation(context);
+        case "external-effect":
+            return reviewDecision("external-effect", "external-effect-requires-review");
+    }
+}
+function boundedSummary(text) {
+    return text.length <= EDITOR_AGENT_AUDIT_SUMMARY_MAX_CHARS
+        ? text
+        : text.slice(0, EDITOR_AGENT_AUDIT_SUMMARY_MAX_CHARS);
+}
+function buildAuditSummary(input) {
+    const parts = [
+        input.actionType,
+        input.decision.disposition,
+        `outcome=${input.outcome}`,
+    ];
+    if (typeof input.targetPath === "string" && input.targetPath.length > 0) {
+        parts.push(`file=${input.targetPath}`);
+    }
+    if (input.decision.denyReason !== undefined)
+        parts.push(`deny=${input.decision.denyReason}`);
+    if (input.decision.reviewReason !== undefined) {
+        parts.push(`review=${input.decision.reviewReason}`);
+    }
+    if (input.conflictCode !== undefined)
+        parts.push(`conflict=${input.conflictCode}`);
+    return boundedSummary(parts.join(" "));
+}
+// Pure builder for the bounded audit record. The summary is bounded here; secret redaction of the
+// summary and path happens at the server boundary (the leaf cannot import the redactor).
+export function buildEditorAgentActionAuditRecord(input) {
+    const targetPath = typeof input.targetPath === "string" && input.targetPath.length > 0
+        ? input.targetPath
+        : undefined;
+    return {
+        schemaVersion: EDITOR_AGENT_AUDIT_SCHEMA_VERSION,
+        auditId: input.auditId,
+        occurredAt: input.occurredAt,
+        sessionId: input.sessionId,
+        actionId: input.actionId,
+        actionType: input.actionType,
+        effectClass: input.decision.effectClass,
+        mutating: isMutatingEditorAgentAction(input.actionType),
+        disposition: input.decision.disposition,
+        ...(input.decision.denyReason === undefined ? {} : { denyReason: input.decision.denyReason }),
+        ...(input.decision.reviewReason === undefined
+            ? {}
+            : { reviewReason: input.decision.reviewReason }),
+        outcome: input.outcome,
+        ...(input.conflictCode === undefined ? {} : { conflictCode: input.conflictCode }),
+        ...(input.failureCode === undefined ? {} : { failureCode: input.failureCode }),
+        ...(targetPath === undefined ? {} : { targetPath }),
+        ...(input.editCount === undefined ? {} : { editCount: input.editCount }),
+        ...(input.patchByteLength === undefined ? {} : { patchByteLength: input.patchByteLength }),
+        summary: buildAuditSummary(input),
+    };
+}
+// ─── Guards ────────────────────────────────────────────────────────────────────
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function isEditorAgentActionDisposition(value) {
+    return (typeof value === "string" &&
+        EDITOR_AGENT_ACTION_DISPOSITIONS.includes(value));
+}
+export function isEditorAgentActionEffectClass(value) {
+    return (value === "navigation" ||
+        value === "layout" ||
+        value === "content-mutation" ||
+        value === "external-effect");
+}
+// Structural guard over a persisted/served audit record. Validates the schema version, required
+// identifiers, the enum members, and the bounded summary. It does not attempt secret detection — the
+// content-free input type plus server-side redaction already guarantee that — it guards shape so a
+// consumer reading the audit feed off the wire cannot be handed a malformed record.
+export function isEditorAgentActionAuditRecord(value) {
+    if (!isRecord(value))
+        return false;
+    return [
+        value.schemaVersion === EDITOR_AGENT_AUDIT_SCHEMA_VERSION,
+        typeof value.auditId === "string" && value.auditId.length > 0,
+        typeof value.occurredAt === "number" && Number.isFinite(value.occurredAt),
+        typeof value.sessionId === "string" && value.sessionId.length > 0,
+        typeof value.actionId === "string" && value.actionId.length > 0,
+        isEditorAgentActionEffectClass(value.effectClass),
+        typeof value.mutating === "boolean",
+        isEditorAgentActionDisposition(value.disposition),
+        typeof value.outcome === "string" && value.outcome.length > 0,
+        typeof value.summary === "string" &&
+            value.summary.length <= EDITOR_AGENT_AUDIT_SUMMARY_MAX_CHARS,
+    ].every(Boolean);
+}

package/dist/editor-agent.d.ts

@@ -2,6 +2,7 @@ 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 declare const DEFAULT_EDITOR_AGENT_SNAPSHOT_TEXT_MODE: EditorAgentSnapshotTextMode;
 export interface EditorAgentPaneSnapshot {
     readonly paneId: string;
     readonly activeFile: string | null;
@@ -26,6 +27,12 @@ export interface EditorAgentSessionSnapshot {
         readonly warnings: number;
         readonly infos: number;
     } | null;
+    readonly languageCapability?: {
+        readonly languageId: string;
+        readonly providerId: string | null;
+        readonly available: boolean;
+        readonly unavailableReason?: string | undefined;
+    } | null;
     readonly documentVersion?: EditorDocumentVersion | undefined;
     readonly activeFileContentHash?: string | undefined;
     readonly textMode: EditorAgentSnapshotTextMode;
@@ -56,6 +63,14 @@ export interface EditorAgentAction {
     readonly patch?: string | undefined;
 }
 export type EditorAgentActionStatus = "queued" | "succeeded" | "failed" | "conflict";
+export type EditorAgentConflictCode = "DIRTY" | "VERSION_MISMATCH" | "CONTENT_HASH_MISMATCH" | "NO_ACTIVE_SESSION" | "NO_ACTIVE_BRIDGE" | "INVALID_EDITS" | "OUT_OF_SCOPE" | "PRECONDITION_REQUIRED";
+export declare const EDITOR_AGENT_CONFLICT_CODES: readonly EditorAgentConflictCode[];
+export type EditorAgentFailureCode = "TIMED_OUT" | "QUEUE_FULL";
+export declare const EDITOR_AGENT_FAILURE_CODES: readonly EditorAgentFailureCode[];
+export interface EditorAgentActionFailure {
+    readonly code: EditorAgentFailureCode;
+    readonly message: string;
+}
 export interface EditorAgentActionResult {
     readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
     readonly actionId: string;
@@ -63,9 +78,10 @@ export interface EditorAgentActionResult {
     readonly status: EditorAgentActionStatus;
     readonly message?: string | undefined;
     readonly conflict?: {
-        readonly code: "DIRTY" | "VERSION_MISMATCH" | "CONTENT_HASH_MISMATCH" | "NO_ACTIVE_SESSION";
+        readonly code: EditorAgentConflictCode;
         readonly message: string;
     } | undefined;
+    readonly failure?: EditorAgentActionFailure | undefined;
 }
 export type EditorAgentEvent = {
     readonly schemaVersion: typeof EDITOR_AGENT_SCHEMA_VERSION;
@@ -125,7 +141,19 @@ export interface EditorAgentParseFail {
 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 const EDITOR_AGENT_WRITE_ACTION_TYPES: readonly EditorAgentActionType[];
+export declare function isEditorAgentWriteActionType(value: unknown): value is EditorAgentActionType;
+export declare function editorAgentActionHasWritePrecondition(action: EditorAgentAction): boolean;
+export declare function editorAgentWritePreconditionError(action: EditorAgentAction): string | null;
 export declare function isEditorAgentActionResult(value: unknown): value is EditorAgentActionResult;
+export declare function isEditorAgentConflictCode(value: unknown): value is EditorAgentConflictCode;
+export declare function isEditorAgentFailureCode(value: unknown): value is EditorAgentFailureCode;
+export declare function isEditorAgentEvent(value: unknown): value is EditorAgentEvent;
+export declare function validateAgentTextEdits(edits: readonly {
+    readonly range: LanguageRange;
+    readonly newText: string;
+}[]): string | null;
+export declare function isContainedAgentPath(candidate: string): boolean;
 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

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

package/dist/editor-agent.js

@@ -1,4 +1,23 @@
 export const EDITOR_AGENT_SCHEMA_VERSION = "1";
+// Issue #1391 AC1 — snapshot text defaults to `none`. An agent that does not explicitly opt into a
+// text mode never receives document content: the default is the content-free projection. The read
+// request parser fills this in when `textMode` is omitted (a present-but-invalid value is still
+// rejected), so the resolved request always carries a concrete, safe-by-default mode.
+export const DEFAULT_EDITOR_AGENT_SNAPSHOT_TEXT_MODE = "none";
+export const EDITOR_AGENT_CONFLICT_CODES = [
+    "DIRTY",
+    "VERSION_MISMATCH",
+    "CONTENT_HASH_MISMATCH",
+    "NO_ACTIVE_SESSION",
+    "NO_ACTIVE_BRIDGE",
+    "INVALID_EDITS",
+    "OUT_OF_SCOPE",
+    "PRECONDITION_REQUIRED",
+];
+export const EDITOR_AGENT_FAILURE_CODES = [
+    "TIMED_OUT",
+    "QUEUE_FULL",
+];
 const EDITOR_AGENT_ACTION_TYPES = [
     "openFile",
     "focusTab",
@@ -41,7 +60,7 @@ function isDocumentVersion(value) {
         isSha256Hex(value.contentHash));
 }
 function isPosition(value) {
-    return isRecord(value) && isNonNegativeInteger(value.line) && isNonNegativeInteger(value.character);
+    return (isRecord(value) && isNonNegativeInteger(value.line) && isNonNegativeInteger(value.character));
 }
 function isRange(value) {
     return isRecord(value) && isPosition(value.start) && isPosition(value.end);
@@ -52,6 +71,17 @@ function isDiagnosticsSummary(value) {
         isNonNegativeInteger(value.warnings) &&
         isNonNegativeInteger(value.infos));
 }
+// Issue #1379 AC4 — the content-free language-capability detail. languageId is a non-empty string,
+// providerId is a string or null, available is a boolean, and unavailableReason (when present) is a
+// string. Reuses the existing isRecord / string / isUndefinedOr helpers so the validator style
+// matches the rest of this module.
+function isLanguageCapability(value) {
+    return (isRecord(value) &&
+        isNonEmptyString(value.languageId) &&
+        (value.providerId === null || isString(value.providerId)) &&
+        typeof value.available === "boolean" &&
+        isUndefinedOr(value.unavailableReason, isString));
+}
 function isPaneSnapshot(value) {
     return (isRecord(value) &&
         isNonEmptyString(value.paneId) &&
@@ -79,6 +109,7 @@ export function isEditorAgentSessionSnapshot(value) {
         isNullOr(value.cursor, isPosition),
         isNullOr(value.selection, isRange),
         isNullOr(value.diagnosticsSummary, isDiagnosticsSummary),
+        isUndefinedOr(value.languageCapability, (c) => c === null || isLanguageCapability(c)),
         isUndefinedOr(value.documentVersion, isDocumentVersion),
         isUndefinedOr(value.activeFileContentHash, isSha256Hex),
         isSnapshotTextMode(value.textMode),
@@ -88,7 +119,7 @@ export function isEditorAgentSessionSnapshot(value) {
     ].every(Boolean);
 }
 function isActionType(value) {
-    return typeof value === "string" && EDITOR_AGENT_ACTION_TYPES.includes(value);
+    return (typeof value === "string" && EDITOR_AGENT_ACTION_TYPES.includes(value));
 }
 function isSplitDirection(value) {
     return value === "row" || value === "column";
@@ -128,16 +159,156 @@ export function isEditorAgentAction(value) {
         isUndefinedOr(value.patch, isString),
     ].every(Boolean);
 }
+// Issue #1391 AC2 — write actions. These four action types mutate buffer or file content and must
+// therefore assert an optimistic-concurrency precondition before they run. The remaining action types
+// (openFile, focusTab, moveTab, splitPane, setSelection) are navigation/inspection and carry no such
+// requirement. The server reuses this frozen table so "what is a write action" has a single source of
+// truth across the contract, the BFF preflight, and any future agent.
+export const EDITOR_AGENT_WRITE_ACTION_TYPES = [
+    "format",
+    "save",
+    "applyTextEdits",
+    "applyPatch",
+];
+export function isEditorAgentWriteActionType(value) {
+    return (typeof value === "string" &&
+        EDITOR_AGENT_WRITE_ACTION_TYPES.includes(value));
+}
+// True when the action pins the document revision it expects to write against — by document version
+// or by content hash. Either precondition is sufficient; both may be supplied. The mandatory
+// `idempotencyKey` (validated by `isEditorAgentAction`) covers safe retry; this covers safe write.
+export function editorAgentActionHasWritePrecondition(action) {
+    return action.expectedDocumentVersion !== undefined || action.expectedContentHash !== undefined;
+}
+// Issue #1391 AC2 — a write action must assert a version/hash precondition in addition to its
+// mandatory idempotency key, so an agent can never blind-write over a buffer whose revision it has
+// not pinned (lost-update prevention). Returns a stable, content-free error string when a write
+// action is missing the precondition, or null when the action satisfies it or is not a write action.
+// Pure and throw-free, consistent with the other editor-agent validators; consumers (the BFF
+// preflight, tests, future agents) reuse it rather than re-deriving the rule.
+export function editorAgentWritePreconditionError(action) {
+    if (!isEditorAgentWriteActionType(action.type))
+        return null;
+    if (editorAgentActionHasWritePrecondition(action))
+        return null;
+    return "Write actions require an expected document version or content hash precondition.";
+}
 function isActionStatus(value) {
     return value === "queued" || value === "succeeded" || value === "failed" || value === "conflict";
 }
+// A conflict detail, when present, must carry a code drawn from the taxonomy and a string message —
+// so a result that claims a conflict cannot smuggle an out-of-taxonomy code past the guard.
+function isEditorAgentConflictDetail(value) {
+    if (value === undefined)
+        return true;
+    return (isRecord(value) && isEditorAgentConflictCode(value.code) && typeof value.message === "string");
+}
+// Issue #1392 — a failure detail, when present, mirrors the conflict-detail guard against the
+// lifecycle-failure taxonomy, so a "failed" result cannot smuggle an out-of-taxonomy code past it.
+function isEditorAgentFailureDetail(value) {
+    if (value === undefined)
+        return true;
+    return (isRecord(value) && isEditorAgentFailureCode(value.code) && typeof value.message === "string");
+}
 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"));
+        (value.message === undefined || typeof value.message === "string") &&
+        isEditorAgentConflictDetail(value.conflict) &&
+        isEditorAgentFailureDetail(value.failure));
+}
+export function isEditorAgentConflictCode(value) {
+    return (typeof value === "string" &&
+        EDITOR_AGENT_CONFLICT_CODES.includes(value));
+}
+export function isEditorAgentFailureCode(value) {
+    return (typeof value === "string" &&
+        EDITOR_AGENT_FAILURE_CODES.includes(value));
+}
+// Issue #1391 — structural guard over the full editor-agent event union. Validates the shared
+// envelope fields (schemaVersion, eventId) and the payload of every event kind (session, action,
+// result, heartbeat). Consumers that read events off the SSE stream (the browser bridge today, any
+// future agent transport) use it to reject malformed frames at the trust boundary instead of casting
+// untyped JSON. Pure and throw-free.
+export function isEditorAgentEvent(value) {
+    if (!isRecord(value))
+        return false;
+    if (value.schemaVersion !== EDITOR_AGENT_SCHEMA_VERSION)
+        return false;
+    if (!isNonEmptyString(value.eventId))
+        return false;
+    switch (value.type) {
+        case "session":
+            return isEditorAgentSessionSnapshot(value.snapshot);
+        case "action":
+            return isEditorAgentAction(value.action);
+        case "result":
+            return isEditorAgentActionResult(value.result);
+        case "heartbeat":
+            return isNonNegativeInteger(value.updatedAt);
+        default:
+            return false;
+    }
+}
+function validateAgentTextEdit(edit, index) {
+    const { start, end } = edit.range;
+    const label = String(index);
+    if (start.line < 0 || start.character < 0 || end.line < 0 || end.character < 0) {
+        return `Edit ${label} has a negative line or character coordinate.`;
+    }
+    if (end.line < start.line || (end.line === start.line && end.character < start.character)) {
+        return `Edit ${label} has an inverted range (end before start).`;
+    }
+    return null;
+}
+function positionLessThan(a, b) {
+    return a.line < b.line || (a.line === b.line && a.character < b.character);
+}
+// Half-open ranges [start, end) overlap iff the later edit starts strictly before the earlier
+// edit ends. Adjacency (next.start === current.end) does not overlap and is allowed.
+function rangesOverlap(current, next) {
+    return positionLessThan(next.start, current.end);
+}
+function overlapError(edits) {
+    const ordered = edits
+        .map((edit, index) => ({ edit, index }))
+        .sort((a, b) => (positionLessThan(a.edit.range.start, b.edit.range.start) ? -1 : 1));
+    for (let i = 1; i < ordered.length; i += 1) {
+        const current = ordered[i - 1];
+        const next = ordered[i];
+        if (current === undefined || next === undefined)
+            continue;
+        if (rangesOverlap(current.edit.range, next.edit.range)) {
+            const [lo, hi] = [current.index, next.index].sort((x, y) => x - y);
+            return `Edits ${String(lo)} and ${String(hi)} overlap.`;
+        }
+    }
+    return null;
+}
+export function validateAgentTextEdits(edits) {
+    let index = 0;
+    for (const edit of edits) {
+        const error = validateAgentTextEdit(edit, index);
+        if (error !== null)
+            return error;
+        index += 1;
+    }
+    return overlapError(edits);
+}
+export function isContainedAgentPath(candidate) {
+    if (candidate.length === 0)
+        return false;
+    if (candidate.startsWith("/"))
+        return false;
+    if (/^[A-Za-z]:/u.test(candidate))
+        return false;
+    if (candidate.includes("\u0000"))
+        return false;
+    const segments = candidate.split(/[/\\]/u);
+    return !segments.includes("..");
 }
 function parseBridgeSnapshotRequest(value) {
     if (!isEditorAgentSessionSnapshot(value.snapshot)) {
@@ -156,7 +327,11 @@ function parseReadSnapshotRequest(value) {
     if (value.schemaVersion !== EDITOR_AGENT_SCHEMA_VERSION) {
         return { ok: false, errors: ["schemaVersion must be 1"] };
     }
-    if (!isSnapshotTextMode(value.textMode)) {
+    // AC1 (#1391): snapshot text defaults to `none`. An omitted `textMode` resolves to the content-free
+    // default so an agent never receives document content it did not explicitly request; a value that is
+    // present but not one of the three modes is still a hard error.
+    const textMode = value.textMode === undefined ? DEFAULT_EDITOR_AGENT_SNAPSHOT_TEXT_MODE : value.textMode;
+    if (!isSnapshotTextMode(textMode)) {
         return { ok: false, errors: ["textMode must be none, selection, or activeFile"] };
     }
     if (value.sessionId !== undefined && typeof value.sessionId !== "string") {
@@ -170,7 +345,7 @@ function parseReadSnapshotRequest(value) {
         value: {
             schemaVersion: EDITOR_AGENT_SCHEMA_VERSION,
             ...(value.sessionId === undefined ? {} : { sessionId: value.sessionId }),
-            textMode: value.textMode,
+            textMode,
             ...(value.maxBytes === undefined ? {} : { maxBytes: value.maxBytes }),
         },
     };
@@ -178,7 +353,9 @@ function parseReadSnapshotRequest(value) {
 export function parseEditorAgentSnapshotRequest(value) {
     if (!isRecord(value))
         return { ok: false, errors: ["request must be an object"] };
-    return value.kind === "snapshot" ? parseBridgeSnapshotRequest(value) : parseReadSnapshotRequest(value);
+    return value.kind === "snapshot"
+        ? parseBridgeSnapshotRequest(value)
+        : parseReadSnapshotRequest(value);
 }
 export function parseEditorAgentActionsPostBody(value) {
     if (isEditorAgentAction(value))

package/dist/editor-builtin-capabilities.d.ts

@@ -0,0 +1,13 @@
+export type EditorBuiltinFormattingSource = "monaco-builtin" | "keiko-language-service" | "none";
+export interface EditorBuiltinCapability {
+    readonly languageId: string;
+    readonly syntaxHighlighting: boolean;
+    readonly bracketMatching: boolean;
+    readonly documentFormatting: EditorBuiltinFormattingSource;
+}
+export declare const EDITOR_BUILTIN_CAPABILITIES: readonly EditorBuiltinCapability[];
+export declare const EDITOR_BUILTIN_CAPABILITY_BY_LANGUAGE: Readonly<Record<string, EditorBuiltinCapability>>;
+export declare function editorBuiltinCapability(languageId: string): EditorBuiltinCapability | null;
+export declare function editorBuiltinDocumentFormatting(languageId: string): EditorBuiltinFormattingSource;
+export declare function isBuiltinFormattingAvailable(languageId: string): boolean;
+//# sourceMappingURL=editor-builtin-capabilities.d.ts.map

package/dist/editor-builtin-capabilities.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"editor-builtin-capabilities.d.ts","sourceRoot":"","sources":["../src/editor-builtin-capabilities.ts"],"names":[],"mappings":"AAyBA,MAAM,MAAM,6BAA6B,GAAG,gBAAgB,GAAG,wBAAwB,GAAG,MAAM,CAAC;AAOjG,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,kBAAkB,EAAE,6BAA6B,CAAC;CAC5D;AAqGD,eAAO,MAAM,2BAA2B,EAAE,SAAS,uBAAuB,EAEzE,CAAC;AAGF,eAAO,MAAM,qCAAqC,EAAE,QAAQ,CAC1D,MAAM,CAAC,MAAM,EAAE,uBAAuB,CAAC,CASxC,CAAC;AAGF,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,GAAG,uBAAuB,GAAG,IAAI,CAE1F;AAID,wBAAgB,+BAA+B,CAAC,UAAU,EAAE,MAAM,GAAG,6BAA6B,CAEjG;AAID,wBAAgB,4BAA4B,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAExE"}