@spotpatch/dev-server 0.7.0 → 0.9.0

package/dist/index.js

@@ -169,6 +169,10 @@ function createAgentJobManager(options) {
     job.updatedAt = dependencies.now();
     emitSnapshot(job);
     emitPhase(job, phaseMessage);
+    if (!isActive(status)) {
+      job.lease?.release();
+      job.lease = void 0;
+    }
   };
   const probeResolved = async (selection, signal) => {
     const key = capabilityCacheKey(selection.provider, selection.model);
@@ -358,6 +362,7 @@ function createAgentJobManager(options) {
         [...jobs.values()].map((job) => job.runPromise).filter((promise) => promise !== void 0)
       );
       capabilityCache.clear();
+      for (const job of jobs.values()) job.lease?.release();
       jobs.clear();
     },
     create(request) {
@@ -382,8 +387,13 @@ function createAgentJobManager(options) {
         request.providerProfileId,
         request.modelProfileId
       );
+      const lease = options.coordinator?.acquire("change");
+      if (options.coordinator !== void 0 && lease === void 0) {
+        throw new SpotPatchError(ERROR_CODES.AGENT_BUSY);
+      }
       const id = dependencies.createJobId();
       if (!JOB_ID_PATTERN.test(id) || jobs.has(id)) {
+        lease?.release();
         throw new SpotPatchError(ERROR_CODES.INTERNAL_ERROR);
       }
       const timestamp = dependencies.now();
@@ -397,6 +407,7 @@ function createAgentJobManager(options) {
         events: [],
         id,
         listeners: /* @__PURE__ */ new Set(),
+        lease,
         model: selection.model,
         phaseMessage: "Agent job queued.",
         preparedChange: void 0,
@@ -439,6 +450,11 @@ function createAgentJobManager(options) {
           hasActiveJob(job.id) ? ERROR_CODES.AGENT_BUSY : ERROR_CODES.APPLY_CONFLICT
         );
       }
+      const lease = options.coordinator?.acquire("change");
+      if (options.coordinator !== void 0 && lease === void 0) {
+        throw new SpotPatchError(ERROR_CODES.AGENT_BUSY);
+      }
+      job.lease = lease;
       transition(job, "reverting", "Reverting the applied Agent change.");
       try {
         await dependencies.revertChange(job.preparedChange);
@@ -1249,12 +1265,12 @@ function createExternalHandoffStore(options) {
     }
     return current.snapshot;
   };
-  const findReplay = (requestId, fingerprint) => {
+  const findReplay = (requestId, fingerprint2) => {
     requireOpen();
     sweep();
     const record = idempotency.get(requestId);
     if (record === void 0) return void 0;
-    if (record.fingerprint !== fingerprint) {
+    if (record.fingerprint !== fingerprint2) {
       throw new SpotPatchError5(ERROR_CODES5.HANDOFF_VALIDATION_FAILED);
     }
     return replayResult(record);
@@ -1499,12 +1515,12 @@ function createExternalHandoffService(options) {
     },
     async publish(request, authorize) {
       requireReady();
-      const fingerprint = fingerprintExternalHandoffAnnotation(request.annotation);
-      const replayed = store.replay(request.requestId, fingerprint);
+      const fingerprint2 = fingerprintExternalHandoffAnnotation(request.annotation);
+      const replayed = store.replay(request.requestId, fingerprint2);
       if (replayed !== void 0) return replayed;
       const pending = inFlight.get(request.requestId);
       if (pending !== void 0) {
-        if (pending.fingerprint !== fingerprint) {
+        if (pending.fingerprint !== fingerprint2) {
           throw new SpotPatchError6(ERROR_CODES6.HANDOFF_VALIDATION_FAILED);
         }
         return asReplay(await pending.promise);
@@ -1514,12 +1530,12 @@ function createExternalHandoffService(options) {
         const annotation = await authorize(request.annotation);
         return store.publish({
           annotation,
-          fingerprint,
+          fingerprint: fingerprint2,
           requestId: request.requestId,
           reserve: activeRegistry.reserve
         });
       })();
-      const activePublish = Object.freeze({ fingerprint, promise });
+      const activePublish = Object.freeze({ fingerprint: fingerprint2, promise });
       inFlight.set(request.requestId, activePublish);
       try {
         return await promise;
@@ -1840,6 +1856,8 @@ import {
   MAX_ANNOTATION_TARGETS,
   SPOTPATCH_EDITOR_PREFERENCES,
   SPOTPATCH_LOCALE_PREFERENCES,
+  contextualAskOptionsSchema,
+  CONTEXTUAL_ASK_LIMITS,
   DEFAULT_DATA_FLOW_LIMITS
 } from "@spotpatch/shared";
 import { z } from "zod";
@@ -1878,7 +1896,8 @@ var DEFAULT_OPTIONS = Object.freeze({
     runtime: "dispatch",
     limits: DEFAULT_DATA_FLOW_LIMITS
   }),
-  externalAgent: Object.freeze({ enabled: false })
+  externalAgent: Object.freeze({ enabled: false }),
+  contextualAsk: Object.freeze({ enabled: false })
 });
 var PROFILE_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
 var ENV_NAME_PATTERN = /^[A-Z][A-Z0-9_]{1,127}$/;
@@ -2188,6 +2207,35 @@ function resolveDataFlowOptions(options) {
     limits: DEFAULT_DATA_FLOW_LIMITS
   });
 }
+function resolveContextualAskOptions(value, ai) {
+  if (value === void 0 || value === false) return DEFAULT_OPTIONS.contextualAsk;
+  const parsed = contextualAskOptionsSchema.safeParse(value);
+  if (!parsed.success) {
+    throw new RangeError("SpotPatch contextualAsk configuration is invalid.");
+  }
+  const configured = typeof parsed.data === "boolean" ? {} : parsed.data;
+  const preference = configured.defaultExecutor;
+  if (preference?.kind === "configured-key") {
+    const provider = ai === false ? void 0 : ai.providers[preference.providerProfileId];
+    if (provider?.models[preference.modelProfileId] === void 0) {
+      throw new RangeError(
+        "SpotPatch contextualAsk default Key executor must reference a configured AI model."
+      );
+    }
+  }
+  if (ai !== false && Object.values(ai.providers).reduce(
+    (total, provider) => total + Object.keys(provider.models).length,
+    0
+  ) >= CONTEXTUAL_ASK_LIMITS.maximumExecutors) {
+    throw new RangeError(
+      "SpotPatch contextualAsk configuration exceeds the executor limit."
+    );
+  }
+  return Object.freeze({
+    enabled: true,
+    ...preference === void 0 ? {} : { defaultExecutor: Object.freeze({ ...preference }) }
+  });
+}
 function createRuntimeDataFlowConfig(options) {
   return Object.freeze({
     enabled: options.enabled,
@@ -2226,6 +2274,7 @@ function resolveOptions(options = {}, environmentAi) {
       `SpotPatch maxTargets must be an integer between 1 and ${String(MAX_ANNOTATION_TARGETS)}.`
     );
   }
+  const ai = resolveAiOptions(options.ai ?? environmentAi);
   const resolved = {
     enabled: options.enabled ?? DEFAULT_OPTIONS.enabled,
     include: Object.freeze([...options.include ?? DEFAULT_OPTIONS.include]),
@@ -2238,11 +2287,12 @@ function resolveOptions(options = {}, environmentAi) {
     debug: options.debug ?? DEFAULT_OPTIONS.debug,
     locale,
     maxTargets,
-    ai: resolveAiOptions(options.ai ?? environmentAi),
+    ai,
     dataFlow: resolveDataFlowOptions(options.dataFlow),
     externalAgent: Object.freeze({
       enabled: options.externalAgent ?? DEFAULT_OPTIONS.externalAgent.enabled
-    })
+    }),
+    contextualAsk: resolveContextualAskOptions(options.contextualAsk, ai)
   };
   if (resolved.shortcut.trim().length === 0 || resolved.shortcut.length > 128 || resolved.shortcut.includes("\0")) {
     throw new RangeError("SpotPatch shortcut is invalid.");
@@ -2478,10 +2528,14 @@ function createSourceRegistry(options = {}) {
         );
       }
       componentIdsByPath.set(normalizedPath, currentIds);
+      return fileId;
     },
     resolve(fileId) {
       return idToPath.get(fileId);
     },
+    findRegisteredId(absolutePath) {
+      return pathToId.get(normalizeAbsolutePath(absolutePath));
+    },
     resolveDataFlowComponent(componentSourceId) {
       return componentAnchors.get(componentSourceId);
     },
@@ -2494,21 +2548,1342 @@ function createSourceRegistry(options = {}) {
   });
 }
 
+// src/contextual-ask/manager.ts
+import { createHash as createHash4, randomBytes as randomBytes9 } from "crypto";
+import {
+  askAnswerDraftSchema,
+  askAnswerResultSchema,
+  askJobCreateRequestSchema,
+  askJobEventSchema,
+  askJobResultResponseSchema,
+  askJobSnapshotSchema,
+  contextualAskCapabilitySchema,
+  contextualAskExecutorCapabilitySchema,
+  CONTEXTUAL_ASK_LIMITS as CONTEXTUAL_ASK_LIMITS3,
+  CONTEXTUAL_ASK_SCHEMA_VERSION
+} from "@spotpatch/shared";
+
+// src/contextual-ask/error.ts
+import { ContextualAskExecutorError } from "@spotpatch/agent";
+var ContextualAskError = class extends Error {
+  code;
+  constructor(code, options = {}) {
+    super(code, options.cause === void 0 ? void 0 : { cause: options.cause });
+    this.name = "ContextualAskError";
+    this.code = code;
+  }
+};
+function asContextualAskError(error) {
+  if (error instanceof ContextualAskError) return error;
+  if (error instanceof ContextualAskExecutorError) {
+    return new ContextualAskError(error.code, { cause: error });
+  }
+  return new ContextualAskError("ASK_EXECUTOR_UNAVAILABLE", { cause: error });
+}
+
+// src/contextual-ask/read-snapshot.ts
+import { createHash as createHash3, randomBytes as randomBytes8 } from "crypto";
+import { constants } from "fs";
+import { lstat as lstat4, open as open2, realpath as realpath3 } from "fs/promises";
+import path5 from "path";
+import {
+  CONTEXTUAL_ASK_LIMITS as CONTEXTUAL_ASK_LIMITS2
+} from "@spotpatch/shared";
+import { parseSync, Visitor } from "oxc-parser";
+var SOURCE_EXTENSIONS = Object.freeze([
+  ".ts",
+  ".tsx",
+  ".js",
+  ".jsx",
+  ".mjs",
+  ".cjs",
+  ".css",
+  ".scss",
+  ".sass",
+  ".less"
+]);
+var PROTECTED_DIRECTORIES = /* @__PURE__ */ new Set([
+  ".git",
+  ".ssh",
+  ".spotpatch",
+  "coverage",
+  "dist",
+  "node_modules"
+]);
+var PROTECTED_FILES = /* @__PURE__ */ new Set([
+  ".gitmodules",
+  ".git-credentials",
+  ".netrc",
+  ".npmrc",
+  ".pnpmrc",
+  ".pypirc",
+  ".yarnrc",
+  "bun.lock",
+  "bun.lockb",
+  "npm-shrinkwrap.json",
+  "package-lock.json",
+  "pnpm-lock.yaml",
+  "yarn.lock"
+]);
+var decoder = new TextDecoder("utf-8", { fatal: true });
+function deny(code) {
+  throw new ContextualAskError(code);
+}
+function toPosixRelative(realRoot, absolutePath) {
+  const relative = path5.relative(realRoot, absolutePath);
+  if (relative.length === 0 || relative === ".." || relative.startsWith(`..${path5.sep}`) || path5.isAbsolute(relative)) {
+    return deny("ASK_SOURCE_SCOPE_DENIED");
+  }
+  const normalized = relative.split(path5.sep).join("/");
+  const segments = normalized.toLowerCase().split("/");
+  const fileName = segments.at(-1) ?? "";
+  if (segments.some((segment) => PROTECTED_DIRECTORIES.has(segment)) || PROTECTED_FILES.has(fileName) || fileName === ".env" || fileName === ".envrc" || fileName === ".dev.vars" || fileName.startsWith(".env.") || fileName.endsWith(".pem") || fileName.endsWith(".key") || fileName.endsWith(".p12") || fileName.endsWith(".pfx") || fileName.startsWith("id_rsa")) {
+    return deny("ASK_SOURCE_SCOPE_DENIED");
+  }
+  return normalized;
+}
+async function assertNoSymlinkPath(realRoot, absolutePath) {
+  const relative = toPosixRelative(realRoot, absolutePath);
+  let current = realRoot;
+  for (const segment of relative.split("/")) {
+    current = path5.join(current, segment);
+    const metadata = await lstat4(current).catch(() => void 0);
+    if (metadata === void 0 || metadata.isSymbolicLink()) {
+      deny("ASK_SOURCE_SCOPE_DENIED");
+    }
+  }
+}
+async function readSecureSource(realRoot, absolutePath) {
+  const normalizedAbsolute = path5.normalize(path5.resolve(absolutePath));
+  const relativePath = toPosixRelative(realRoot, normalizedAbsolute);
+  await assertNoSymlinkPath(realRoot, normalizedAbsolute);
+  const canonical = await realpath3(normalizedAbsolute).catch(() => void 0);
+  if (canonical === void 0 || canonical !== normalizedAbsolute) {
+    return deny("ASK_SOURCE_SCOPE_DENIED");
+  }
+  let handle;
+  try {
+    handle = await open2(normalizedAbsolute, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const before = await handle.stat();
+    if (!before.isFile() || before.nlink !== 1) {
+      return deny("ASK_SOURCE_SCOPE_DENIED");
+    }
+    if (before.size > CONTEXTUAL_ASK_LIMITS2.maximumReadBytesPerFile) {
+      throw new ContextualAskError("ASK_LIMIT_EXCEEDED");
+    }
+    const bytes = await handle.readFile();
+    const after = await handle.stat();
+    if (bytes.byteLength !== before.size || before.dev !== after.dev || before.ino !== after.ino || before.size !== after.size || before.mtimeMs !== after.mtimeMs || bytes.includes(0)) {
+      return deny("ASK_SOURCE_SCOPE_DENIED");
+    }
+    let content;
+    try {
+      content = decoder.decode(bytes);
+    } catch (error) {
+      throw new ContextualAskError("ASK_SOURCE_SCOPE_DENIED", { cause: error });
+    }
+    return Object.freeze({
+      content,
+      contentHash: createHash3("sha256").update(bytes).digest("hex"),
+      relativePath,
+      size: bytes.byteLength
+    });
+  } finally {
+    await handle?.close().catch(() => void 0);
+  }
+}
+function confidence(value) {
+  return value === "exact" || value === "probable" ? value : "approximate";
+}
+async function authorizeSeeds(selection, registry, root, realRoot) {
+  const byPath = /* @__PURE__ */ new Map();
+  for (const target of selection.targets) {
+    let fileId = target.react.source?.fileId ?? target.source.fileId;
+    let sourceVersion;
+    if (target.react.componentSourceId !== void 0) {
+      const anchor = registry.resolveDataFlowComponent(target.react.componentSourceId);
+      if (anchor === void 0 || target.react.sourceVersion !== anchor.sourceVersion) {
+        deny("ASK_SELECTION_STALE");
+      }
+      fileId = anchor.fileId;
+      sourceVersion = anchor.sourceVersion;
+    }
+    if (fileId === void 0) continue;
+    const registered = registry.resolve(fileId);
+    if (registered === void 0) deny("ASK_SELECTION_STALE");
+    const canonical = await realpath3(registered).catch(() => void 0);
+    if (canonical === void 0) deny("ASK_SELECTION_STALE");
+    const absolutePath = path5.normalize(canonical);
+    const registeredRelative = toPosixRelative(realRoot, absolutePath);
+    const claimedRelative = target.react.source?.relativePath ?? target.source.relativePath;
+    if (claimedRelative !== void 0 && claimedRelative.split("\\").join("/") !== registeredRelative) {
+      deny("ASK_SELECTION_STALE");
+    }
+    const existing = byPath.get(absolutePath);
+    const targetIds = Object.freeze([
+      ...existing?.targetIds ?? [],
+      ...existing?.targetIds.includes(target.targetId) === true ? [] : [target.targetId]
+    ]);
+    byPath.set(
+      absolutePath,
+      Object.freeze({
+        absolutePath,
+        fileId,
+        confidence: confidence(
+          target.react.source?.confidence ?? target.source.confidence
+        ),
+        targetIds,
+        ...sourceVersion === void 0 ? {} : { sourceVersion }
+      })
+    );
+  }
+  for (const target of selection.targets) {
+    for (const rule of target.styles.matchedRules) {
+      const claimed = rule.source;
+      if (claimed === void 0 || claimed.startsWith("/") || claimed.includes("\\") || claimed.includes("\0") || claimed.split("/").some((segment) => segment === "" || segment === "." || segment === "..")) {
+        continue;
+      }
+      const registeredPath = path5.resolve(root, ...claimed.split("/"));
+      const fileId = registry.findRegisteredId(registeredPath);
+      if (fileId === void 0) continue;
+      const canonical = await realpath3(registeredPath).catch(() => void 0);
+      if (canonical === void 0) continue;
+      const absolutePath = path5.normalize(canonical);
+      toPosixRelative(realRoot, absolutePath);
+      const existing = byPath.get(absolutePath);
+      const targetIds = Object.freeze([
+        ...existing?.targetIds ?? [],
+        ...existing?.targetIds.includes(target.targetId) === true ? [] : [target.targetId]
+      ]);
+      byPath.set(
+        absolutePath,
+        Object.freeze({
+          absolutePath,
+          fileId,
+          confidence: existing?.confidence ?? "probable",
+          targetIds,
+          ...existing?.sourceVersion === void 0 ? {} : { sourceVersion: existing.sourceVersion }
+        })
+      );
+    }
+  }
+  if (byPath.size === 0) deny("ASK_SELECTION_REQUIRED");
+  return [...byPath.values()];
+}
+function localSpecifiers(filePath, content) {
+  const found = /* @__PURE__ */ new Set();
+  if (/\.(?:css|scss|sass|less)$/iu.test(filePath)) {
+    const pattern = /@import\s+(?:url\(\s*)?["']([^"']+)["']/gu;
+    for (const match of content.matchAll(pattern)) {
+      if (match[1]?.startsWith(".")) found.add(match[1]);
+    }
+    return [...found].sort();
+  }
+  try {
+    const parsed = parseSync(filePath, content, { sourceType: "module" });
+    if (parsed.errors.length > 0) return [];
+    const add = (value) => {
+      if (typeof value === "string" && value.startsWith(".")) found.add(value);
+    };
+    const visitor = new Visitor({
+      ImportDeclaration(node) {
+        add(node.source.value);
+      },
+      ExportNamedDeclaration(node) {
+        add(node.source?.value);
+      },
+      ExportAllDeclaration(node) {
+        add(node.source.value);
+      },
+      ImportExpression(node) {
+        if ("value" in node.source) add(node.source.value);
+      }
+    });
+    visitor.visit(parsed.program);
+  } catch {
+    return [];
+  }
+  return [...found].sort();
+}
+function importCandidates(importer, specifier) {
+  const base = path5.resolve(path5.dirname(importer), specifier);
+  if (path5.extname(base) !== "") return Object.freeze([base]);
+  return Object.freeze([
+    ...SOURCE_EXTENSIONS.map((extension) => `${base}${extension}`),
+    ...SOURCE_EXTENSIONS.map((extension) => path5.join(base, `index${extension}`))
+  ]);
+}
+function countLines(content) {
+  return content.length === 0 ? 1 : content.split("\n").length;
+}
+function publicSourceEntry(source) {
+  return Object.freeze({
+    handleId: source.handleId,
+    fileId: source.fileId,
+    relativePath: source.relativePath,
+    label: source.label,
+    lineCount: source.lineCount,
+    size: source.size,
+    contentHash: source.contentHash,
+    confidence: source.confidence,
+    targetIds: source.targetIds,
+    ...source.sourceVersion === void 0 ? {} : { sourceVersion: source.sourceVersion }
+  });
+}
+function assertSelectionEvidenceCurrent(selection, captured) {
+  for (const target of selection.targets) {
+    if (target.code === void 0) continue;
+    const source = captured.find(
+      (candidate) => candidate.relativePath === target.code?.relativePath
+    );
+    if (source === void 0) deny("ASK_SELECTION_STALE");
+    const lines = source.content.split(/\r?\n/u);
+    if (target.code.endLine > lines.length) deny("ASK_SELECTION_STALE");
+    const currentExcerpt = lines.slice(target.code.startLine - 1, target.code.endLine).join("\n");
+    if (currentExcerpt !== target.code.excerpt) deny("ASK_SELECTION_STALE");
+  }
+}
+async function captureAskReadSnapshot(options) {
+  options.signal?.throwIfAborted();
+  const realRoot = await realpath3(options.root).catch(() => void 0);
+  if (realRoot === void 0) deny("ASK_SOURCE_SCOPE_DENIED");
+  const seeds = await authorizeSeeds(
+    options.selection,
+    options.registry,
+    options.root,
+    realRoot
+  );
+  const createHandleId = options.createHandleId ?? (() => randomBytes8(16).toString("base64url"));
+  const captured = [];
+  const capturedPaths = /* @__PURE__ */ new Set();
+  const queue = [...seeds];
+  let totalBytes = 0;
+  let truncated = false;
+  while (queue.length > 0) {
+    options.signal?.throwIfAborted();
+    const candidate = queue.shift();
+    if (candidate === void 0 || capturedPaths.has(candidate.absolutePath)) continue;
+    if (captured.length >= CONTEXTUAL_ASK_LIMITS2.maximumReadFiles) {
+      truncated = true;
+      break;
+    }
+    let read;
+    try {
+      read = await readSecureSource(realRoot, candidate.absolutePath);
+      options.signal?.throwIfAborted();
+    } catch (error) {
+      if (captured.length < seeds.length) throw error;
+      truncated = true;
+      continue;
+    }
+    if (totalBytes + read.size > CONTEXTUAL_ASK_LIMITS2.maximumReadBytesTotal) {
+      if (captured.length < seeds.length)
+        throw new ContextualAskError("ASK_LIMIT_EXCEEDED");
+      truncated = true;
+      continue;
+    }
+    capturedPaths.add(candidate.absolutePath);
+    totalBytes += read.size;
+    const entry = Object.freeze({
+      handleId: createHandleId(),
+      fileId: candidate.fileId,
+      relativePath: read.relativePath,
+      label: path5.basename(read.relativePath),
+      lineCount: countLines(read.content),
+      size: read.size,
+      contentHash: read.contentHash,
+      confidence: candidate.confidence,
+      targetIds: Object.freeze([...candidate.targetIds]),
+      ...candidate.sourceVersion === void 0 ? {} : { sourceVersion: candidate.sourceVersion },
+      absolutePath: candidate.absolutePath,
+      content: read.content
+    });
+    captured.push(entry);
+    for (const specifier of localSpecifiers(candidate.absolutePath, read.content)) {
+      options.signal?.throwIfAborted();
+      for (const importPath of importCandidates(candidate.absolutePath, specifier)) {
+        if (capturedPaths.has(importPath)) continue;
+        const metadata = await lstat4(importPath).catch(() => void 0);
+        if (metadata?.isFile() !== true || metadata.isSymbolicLink()) continue;
+        const fileId = options.registry.findRegisteredId(importPath) ?? options.registry.register(importPath);
+        queue.push(
+          Object.freeze({
+            absolutePath: path5.normalize(importPath),
+            fileId,
+            confidence: "probable",
+            targetIds: candidate.targetIds
+          })
+        );
+        break;
+      }
+    }
+  }
+  assertSelectionEvidenceCurrent(options.selection, captured);
+  const sourceByHandle = new Map(captured.map((source) => [source.handleId, source]));
+  const publicEntries = Object.freeze(
+    captured.map((source) => publicSourceEntry(source))
+  );
+  const contextHash = createHash3("sha256").update(
+    JSON.stringify({
+      selectionId: options.selection.selectionId,
+      sources: publicEntries.map((source) => ({
+        relativePath: source.relativePath,
+        contentHash: source.contentHash,
+        targetIds: source.targetIds,
+        sourceVersion: source.sourceVersion ?? null
+      }))
+    })
+  ).digest("hex");
+  let disposed = false;
+  const requireSource = (handleId) => {
+    if (disposed) throw new ContextualAskError("ASK_RESULT_EXPIRED");
+    const source = sourceByHandle.get(handleId);
+    if (source === void 0) throw new ContextualAskError("ASK_SOURCE_SCOPE_DENIED");
+    return source;
+  };
+  const snapshot2 = Object.freeze({
+    manifest: () => {
+      if (disposed) throw new ContextualAskError("ASK_RESULT_EXPIRED");
+      return publicEntries;
+    },
+    read(handleId, range = {}) {
+      const source = requireSource(handleId);
+      const startLine = range.startLine ?? 1;
+      const endLine = range.endLine ?? source.lineCount;
+      if (!Number.isSafeInteger(startLine) || !Number.isSafeInteger(endLine) || startLine < 1 || endLine < startLine || endLine > source.lineCount) {
+        throw new ContextualAskError("ASK_SOURCE_SCOPE_DENIED");
+      }
+      return Object.freeze({
+        handleId,
+        startLine,
+        endLine,
+        content: source.content.split("\n").slice(startLine - 1, endLine).join("\n")
+      });
+    },
+    search(query) {
+      if (query.length === 0 || query.length > CONTEXTUAL_ASK_LIMITS2.maximumSearchQueryCharacters || query.includes("\0")) {
+        throw new ContextualAskError("ASK_SOURCE_SCOPE_DENIED");
+      }
+      const normalized = query.toLocaleLowerCase("en-US");
+      const matches = [];
+      for (const source of captured) {
+        for (const [index, line] of source.content.split("\n").entries()) {
+          if (line.toLocaleLowerCase("en-US").includes(normalized)) {
+            matches.push(
+              Object.freeze({
+                handleId: source.handleId,
+                line: index + 1,
+                preview: line.slice(
+                  0,
+                  CONTEXTUAL_ASK_LIMITS2.maximumSearchPreviewCharacters
+                )
+              })
+            );
+            if (matches.length >= CONTEXTUAL_ASK_LIMITS2.maximumSearchResults) {
+              return Object.freeze(matches);
+            }
+          }
+        }
+      }
+      return Object.freeze(matches);
+    }
+  });
+  return Object.freeze({
+    grant: Object.freeze({ contextHash, truncated, sources: publicEntries }),
+    snapshot: snapshot2,
+    dispose() {
+      disposed = true;
+      sourceByHandle.clear();
+      captured.splice(0, captured.length);
+    },
+    async isStale() {
+      for (const source of captured) {
+        try {
+          const current = await readSecureSource(realRoot, source.absolutePath);
+          if (current.contentHash !== source.contentHash) return true;
+        } catch {
+          return true;
+        }
+      }
+      return false;
+    },
+    projectCitation(handleId, startLine, endLine) {
+      const source = requireSource(handleId);
+      if (!Number.isSafeInteger(startLine) || !Number.isSafeInteger(endLine) || startLine < 1 || endLine < startLine || endLine > source.lineCount) {
+        throw new ContextualAskError("ASK_ANSWER_INVALID");
+      }
+      return Object.freeze({ ...publicSourceEntry(source), startLine, endLine });
+    }
+  });
+}
+
+// src/contextual-ask/manager.ts
+var ACTIVE_STATUSES = /* @__PURE__ */ new Set([
+  "queued",
+  "authorizing",
+  "running",
+  "cancelling"
+]);
+var TERMINAL_STATUSES = /* @__PURE__ */ new Set(["answered", "cancelled", "failed"]);
+var DEFAULT_DEPENDENCIES2 = Object.freeze({
+  captureSnapshot: captureAskReadSnapshot,
+  createId: () => randomBytes9(16).toString("base64url"),
+  now: () => /* @__PURE__ */ new Date()
+});
+function fingerprint(request) {
+  return createHash4("sha256").update(
+    JSON.stringify({
+      envelope: request.envelope,
+      executorId: request.executorId,
+      providerDataConsent: request.providerDataConsent
+    })
+  ).digest("hex");
+}
+function fileCountBucket(count) {
+  if (count <= 1) return "one";
+  if (count <= 5) return "few";
+  return "many";
+}
+function raceWithAbort(operation, signal) {
+  const reason = () => signal.reason instanceof Error ? signal.reason : new ContextualAskError("ASK_CANCELLED");
+  if (signal.aborted) return Promise.reject(reason());
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      reject(reason());
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    operation.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(
+          error instanceof Error ? error : new ContextualAskError("ASK_EXECUTOR_UNAVAILABLE", { cause: error })
+        );
+      }
+    );
+  });
+}
+function createContextualAskManager(options) {
+  const dependencies = Object.freeze({
+    ...DEFAULT_DEPENDENCIES2,
+    ...options.dependencies
+  });
+  const executors = /* @__PURE__ */ new Map();
+  for (const executor of options.executors ?? []) {
+    if (executors.has(executor.executorId)) {
+      throw new TypeError("Contextual Ask executor IDs must be unique.");
+    }
+    executors.set(executor.executorId, executor);
+  }
+  const jobs = /* @__PURE__ */ new Map();
+  const requests = /* @__PURE__ */ new Map();
+  const pendingRequests = /* @__PURE__ */ new Map();
+  let closed = false;
+  const isClosed = () => closed;
+  const cleanupExpired = () => {
+    const now = dependencies.now().getTime();
+    for (const [jobId, job] of jobs) {
+      if (job.expiresAt !== void 0 && now >= job.expiresAt) {
+        job.snapshot?.dispose();
+        jobs.delete(jobId);
+        const request = requests.get(job.request.requestId);
+        if (request?.jobId === jobId) requests.delete(job.request.requestId);
+      }
+    }
+  };
+  const requireJob = (jobId) => {
+    cleanupExpired();
+    const job = jobs.get(jobId);
+    if (job === void 0) throw new ContextualAskError("ASK_RESULT_EXPIRED");
+    return job;
+  };
+  const publicSnapshot = (job) => askJobSnapshotSchema.parse({
+    schemaVersion: CONTEXTUAL_ASK_SCHEMA_VERSION,
+    jobId: job.id,
+    selectionId: job.request.envelope.selection.selectionId,
+    status: job.status,
+    executor: {
+      executorId: job.executorCapability.executorId,
+      kind: job.executorCapability.kind,
+      label: job.executorCapability.label,
+      modelLabel: job.executorCapability.effectiveModelLabel
+    },
+    ...job.phaseMessage === void 0 ? {} : { phaseMessage: job.phaseMessage },
+    createdAt: job.createdAt,
+    updatedAt: job.updatedAt,
+    canCancel: ["queued", "authorizing", "running"].includes(job.status),
+    ...job.errorCode === void 0 ? {} : { errorCode: job.errorCode }
+  });
+  const appendEvent = (job, event) => {
+    job.events.push(askJobEventSchema.parse(event));
+    if (job.events.length > CONTEXTUAL_ASK_LIMITS3.maximumRetainedEvents) {
+      job.events.splice(
+        0,
+        job.events.length - CONTEXTUAL_ASK_LIMITS3.maximumRetainedEvents
+      );
+    }
+    for (const listener of job.listeners) listener(event);
+  };
+  const eventBase = (job) => {
+    job.sequence += 1;
+    return {
+      schemaVersion: CONTEXTUAL_ASK_SCHEMA_VERSION,
+      sequence: job.sequence,
+      jobId: job.id,
+      status: job.status,
+      timestamp: dependencies.now().toISOString()
+    };
+  };
+  const emitSnapshot = (job) => {
+    appendEvent(job, {
+      ...eventBase(job),
+      type: "snapshot",
+      snapshot: publicSnapshot(job)
+    });
+  };
+  const emitPhase = (job, message) => {
+    appendEvent(job, { ...eventBase(job), type: "phase", message });
+  };
+  const emitReadActivity = (job, entry, state) => {
+    appendEvent(job, {
+      ...eventBase(job),
+      type: "read-activity",
+      activity: entry === void 0 ? {
+        kind: "file-count",
+        bucket: fileCountBucket(job.snapshot?.grant.sources.length ?? 0)
+      } : {
+        kind: "source",
+        sourceId: entry.fileId,
+        relativePath: entry.relativePath
+      },
+      state
+    });
+  };
+  const transition = (job, status, phaseMessage, errorCode) => {
+    job.status = status;
+    job.phaseMessage = phaseMessage;
+    job.errorCode = errorCode;
+    job.updatedAt = dependencies.now().toISOString();
+    emitSnapshot(job);
+    if (!TERMINAL_STATUSES.has(status)) emitPhase(job, phaseMessage);
+  };
+  const finish = (job) => {
+    job.expiresAt = dependencies.now().getTime() + CONTEXTUAL_ASK_LIMITS3.resultTtlMs;
+    job.lease.release();
+    job.snapshot?.dispose();
+    job.snapshot = void 0;
+  };
+  const fail = (job, error) => {
+    if (TERMINAL_STATUSES.has(job.status)) return;
+    const normalized = asContextualAskError(error);
+    const abortReason = job.controller.signal.reason;
+    const cancelled = normalized.code === "ASK_CANCELLED" || abortReason instanceof ContextualAskError && abortReason.code === "ASK_CANCELLED";
+    transition(
+      job,
+      cancelled ? "cancelled" : "failed",
+      cancelled ? "Question cancelled." : "Question failed.",
+      cancelled ? "ASK_CANCELLED" : normalized.code
+    );
+    appendEvent(job, {
+      ...eventBase(job),
+      type: "error",
+      errorCode: cancelled ? "ASK_CANCELLED" : normalized.code
+    });
+    finish(job);
+  };
+  const instrumentSnapshot = (job, snapshot2, onLimitExceeded) => {
+    const byHandle = new Map(
+      snapshot2.manifest().map((entry) => [entry.handleId, entry])
+    );
+    let readOperations = 0;
+    const beginOperation = () => {
+      readOperations += 1;
+      if (readOperations > CONTEXTUAL_ASK_LIMITS3.maximumToolCalls) {
+        onLimitExceeded();
+        throw new ContextualAskError("ASK_LIMIT_EXCEEDED");
+      }
+    };
+    return Object.freeze({
+      manifest: () => snapshot2.manifest(),
+      read(handleId, range) {
+        beginOperation();
+        const entry = byHandle.get(handleId);
+        if (job.status === "running") emitReadActivity(job, entry, "started");
+        try {
+          const result = snapshot2.read(handleId, range);
+          if (job.status === "running") emitReadActivity(job, entry, "succeeded");
+          return result;
+        } catch (error) {
+          if (job.status === "running") emitReadActivity(job, entry, "failed");
+          throw error;
+        }
+      },
+      search(query) {
+        beginOperation();
+        if (job.status === "running") emitReadActivity(job, void 0, "started");
+        try {
+          const result = snapshot2.search(query);
+          if (job.status === "running") {
+            emitReadActivity(job, void 0, "succeeded");
+          }
+          return result;
+        } catch (error) {
+          if (job.status === "running") emitReadActivity(job, void 0, "failed");
+          throw error;
+        }
+      }
+    });
+  };
+  const projectAnswer = async (job, draft, captured) => {
+    const sourceIds = /* @__PURE__ */ new Map();
+    const sources = /* @__PURE__ */ new Map();
+    const projectCitations = (citations) => citations.map((citation) => {
+      const key = `${citation.handleId}:${String(citation.startLine)}:${String(citation.endLine)}`;
+      let sourceId = sourceIds.get(key);
+      if (sourceId === void 0) {
+        sourceId = dependencies.createId();
+        sourceIds.set(key, sourceId);
+        sources.set(
+          sourceId,
+          captured.projectCitation(
+            citation.handleId,
+            citation.startLine,
+            citation.endLine
+          )
+        );
+      }
+      return sourceId;
+    });
+    const blocks = draft.blocks.map((block) => {
+      if (block.kind === "list") {
+        return {
+          kind: "list",
+          items: block.items.map((item) => ({
+            text: item.text,
+            sourceIds: projectCitations(item.citations)
+          }))
+        };
+      }
+      return Object.freeze({
+        kind: block.kind,
+        ...block.kind === "paragraph" ? { text: block.text } : { code: block.code },
+        ...block.kind === "code" && block.language !== void 0 ? { language: block.language } : {},
+        sourceIds: projectCitations(block.citations)
+      });
+    });
+    const warnings = [...draft.warnings];
+    if (captured.grant.truncated && !warnings.some((warning) => warning.code === "source-truncated")) {
+      warnings.push(Object.freeze({ code: "source-truncated" }));
+    }
+    if (await captured.isStale() && !warnings.some((warning) => warning.code === "source-stale")) {
+      warnings.push(Object.freeze({ code: "source-stale" }));
+    }
+    const created = dependencies.now();
+    return askAnswerResultSchema.parse({
+      schemaVersion: CONTEXTUAL_ASK_SCHEMA_VERSION,
+      jobId: job.id,
+      selectionId: job.request.envelope.selection.selectionId,
+      contextHash: captured.grant.contextHash,
+      executor: {
+        executorId: job.executorCapability.executorId,
+        kind: job.executorCapability.kind,
+        label: job.executorCapability.label,
+        modelLabel: job.executorCapability.effectiveModelLabel
+      },
+      blocks,
+      sources: [...sources].map(([sourceId, source]) => ({
+        sourceId,
+        label: source.label,
+        relativePath: source.relativePath,
+        fileId: source.fileId,
+        startLine: source.startLine,
+        endLine: source.endLine,
+        confidence: source.confidence,
+        targetIds: source.targetIds,
+        ...source.sourceVersion === void 0 ? {} : { sourceVersion: source.sourceVersion },
+        contentHash: source.contentHash
+      })),
+      warnings,
+      createdAt: created.toISOString(),
+      expiresAt: new Date(
+        created.getTime() + CONTEXTUAL_ASK_LIMITS3.resultTtlMs
+      ).toISOString()
+    });
+  };
+  const run = async (job) => {
+    const timeout = setTimeout(() => {
+      job.controller.abort(new ContextualAskError("ASK_TIMEOUT"));
+    }, CONTEXTUAL_ASK_LIMITS3.jobTimeoutMs);
+    timeout.unref();
+    try {
+      transition(job, "authorizing", "Authorizing selected sources.");
+      const captured = await dependencies.captureSnapshot({
+        root: options.root,
+        registry: options.registry,
+        selection: job.request.envelope.selection,
+        signal: job.controller.signal,
+        createHandleId: dependencies.createId
+      });
+      if (job.controller.signal.aborted) {
+        captured.dispose();
+      }
+      job.controller.signal.throwIfAborted();
+      job.snapshot = captured;
+      transition(job, "running", "Analyzing the authorized snapshot.");
+      emitReadActivity(job, void 0, "succeeded");
+      const readLimit = { exceeded: false };
+      const execution = await raceWithAbort(
+        job.executor.execute(
+          {
+            jobId: job.id,
+            envelope: job.request.envelope,
+            grant: captured.grant,
+            snapshot: instrumentSnapshot(job, captured.snapshot, () => {
+              readLimit.exceeded = true;
+            })
+          },
+          job.controller.signal
+        ),
+        job.controller.signal
+      );
+      const draft = askAnswerDraftSchema.parse(execution);
+      const effectiveModelLabel = job.executor.effectiveModelLabel?.();
+      if (effectiveModelLabel !== void 0) {
+        job.executorCapability = contextualAskExecutorCapabilitySchema.parse({
+          ...job.executorCapability,
+          effectiveModelLabel
+        });
+      }
+      if (readLimit.exceeded) throw new ContextualAskError("ASK_LIMIT_EXCEEDED");
+      job.controller.signal.throwIfAborted();
+      const result = await projectAnswer(job, draft, captured);
+      job.controller.signal.throwIfAborted();
+      job.result = result;
+      transition(job, "answered", "Answer ready.");
+      appendEvent(job, { ...eventBase(job), type: "answer-ready" });
+      finish(job);
+    } catch (error) {
+      fail(
+        job,
+        error instanceof Error && error.name === "ZodError" ? new ContextualAskError("ASK_ANSWER_INVALID", { cause: error }) : asContextualAskError(error)
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+  };
+  return Object.freeze({
+    async capability(signal) {
+      if (!options.enabled || closed) {
+        return contextualAskCapabilitySchema.parse({
+          schemaVersion: CONTEXTUAL_ASK_SCHEMA_VERSION,
+          enabled: false,
+          executors: [],
+          safety: {
+            selectionRequired: true,
+            singleTurn: true,
+            writesAllowed: false,
+            historyStored: false
+          },
+          checkedAt: dependencies.now().toISOString()
+        });
+      }
+      const capabilities = (await Promise.all(
+        [...executors.values()].map(async (executor) => {
+          try {
+            return contextualAskExecutorCapabilitySchema.parse(
+              await raceWithAbort(executor.capability(signal), signal)
+            );
+          } catch {
+            return void 0;
+          }
+        })
+      )).filter((capability) => capability !== void 0);
+      return contextualAskCapabilitySchema.parse({
+        schemaVersion: CONTEXTUAL_ASK_SCHEMA_VERSION,
+        enabled: true,
+        executors: capabilities,
+        safety: {
+          selectionRequired: true,
+          singleTurn: true,
+          writesAllowed: false,
+          historyStored: false
+        },
+        checkedAt: dependencies.now().toISOString()
+      });
+    },
+    async create(rawRequest) {
+      cleanupExpired();
+      if (!options.enabled || closed) throw new ContextualAskError("ASK_DISABLED");
+      const parsed = askJobCreateRequestSchema.safeParse(rawRequest);
+      if (!parsed.success) throw new ContextualAskError("ASK_QUESTION_INVALID");
+      const request = parsed.data;
+      const requestFingerprint = fingerprint(request);
+      const previous = requests.get(request.requestId);
+      if (previous !== void 0) {
+        if (previous.fingerprint !== requestFingerprint) {
+          throw new ContextualAskError("ASK_IDEMPOTENCY_CONFLICT");
+        }
+        return publicSnapshot(requireJob(previous.jobId));
+      }
+      const pending = pendingRequests.get(request.requestId);
+      if (pending !== void 0) {
+        if (pending.fingerprint !== requestFingerprint) {
+          throw new ContextualAskError("ASK_IDEMPOTENCY_CONFLICT");
+        }
+        return await pending.promise;
+      }
+      if ([...jobs.values()].some((job) => ACTIVE_STATUSES.has(job.status))) {
+        throw new ContextualAskError("ASK_BUSY");
+      }
+      const executor = executors.get(request.executorId);
+      if (executor === void 0)
+        throw new ContextualAskError("ASK_EXECUTOR_UNAVAILABLE");
+      const lease = options.coordinator.acquire("ask");
+      if (lease === void 0) throw new ContextualAskError("ASK_BUSY");
+      const controller = new AbortController();
+      let leaseTransferred = false;
+      const creation = (async () => {
+        try {
+          const capabilitySignal = AbortSignal.any([
+            controller.signal,
+            AbortSignal.timeout(CONTEXTUAL_ASK_LIMITS3.capabilityTimeoutMs)
+          ]);
+          const capability = contextualAskExecutorCapabilitySchema.parse(
+            await raceWithAbort(
+              executor.capability(capabilitySignal),
+              capabilitySignal
+            )
+          );
+          if (isClosed()) throw new ContextualAskError("ASK_DISABLED");
+          if (capability.executorId !== executor.executorId || capability.state !== "ready" || !capability.readOnlyProven) {
+            throw new ContextualAskError("ASK_EXECUTOR_UNAVAILABLE");
+          }
+          for (const [jobId, existing] of jobs) {
+            if (TERMINAL_STATUSES.has(existing.status)) {
+              existing.snapshot?.dispose();
+              jobs.delete(jobId);
+              requests.delete(existing.request.requestId);
+            }
+          }
+          const createdAt = dependencies.now().toISOString();
+          const job = {
+            controller: new AbortController(),
+            createdAt,
+            events: [],
+            executor,
+            executorCapability: capability,
+            fingerprint: requestFingerprint,
+            id: dependencies.createId(),
+            lease,
+            listeners: /* @__PURE__ */ new Set(),
+            request,
+            errorCode: void 0,
+            expiresAt: void 0,
+            phaseMessage: "Question queued.",
+            result: void 0,
+            runPromise: void 0,
+            sequence: 0,
+            snapshot: void 0,
+            status: "queued",
+            updatedAt: createdAt
+          };
+          jobs.set(job.id, job);
+          requests.set(request.requestId, {
+            fingerprint: requestFingerprint,
+            jobId: job.id
+          });
+          leaseTransferred = true;
+          emitSnapshot(job);
+          emitPhase(job, "Question queued.");
+          job.runPromise = run(job);
+          return publicSnapshot(job);
+        } catch (error) {
+          throw error instanceof ContextualAskError ? error : new ContextualAskError("ASK_EXECUTOR_UNAVAILABLE", {
+            cause: error
+          });
+        } finally {
+          if (!leaseTransferred) lease.release();
+          pendingRequests.delete(request.requestId);
+        }
+      })();
+      pendingRequests.set(request.requestId, {
+        controller,
+        fingerprint: requestFingerprint,
+        promise: creation
+      });
+      return await creation;
+    },
+    cancel(jobId) {
+      const job = requireJob(jobId);
+      if (TERMINAL_STATUSES.has(job.status)) return publicSnapshot(job);
+      if (job.status !== "cancelling") {
+        transition(job, "cancelling", "Cancelling question.");
+        job.controller.abort(new ContextualAskError("ASK_CANCELLED"));
+        job.snapshot?.dispose();
+        job.snapshot = void 0;
+      }
+      return publicSnapshot(job);
+    },
+    events(jobId, afterSequence = 0) {
+      if (!Number.isSafeInteger(afterSequence) || afterSequence < 0) {
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+      }
+      return Object.freeze(
+        requireJob(jobId).events.filter((event) => event.sequence > afterSequence)
+      );
+    },
+    async result(jobId) {
+      const job = requireJob(jobId);
+      await job.runPromise;
+      const current = requireJob(jobId);
+      return askJobResultResponseSchema.parse({
+        snapshot: publicSnapshot(current),
+        ...current.result === void 0 ? {} : { result: current.result }
+      });
+    },
+    snapshot(jobId) {
+      return publicSnapshot(requireJob(jobId));
+    },
+    subscribe(jobId, listener) {
+      const job = requireJob(jobId);
+      if (job.listeners.size >= CONTEXTUAL_ASK_LIMITS3.maximumEventSubscribers) {
+        throw new ContextualAskError("ASK_LIMIT_EXCEEDED");
+      }
+      job.listeners.add(listener);
+      return () => job.listeners.delete(listener);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      for (const pending of pendingRequests.values()) {
+        pending.controller.abort(new ContextualAskError("ASK_CANCELLED"));
+      }
+      await Promise.allSettled(
+        [...pendingRequests.values()].map((pending) => pending.promise)
+      );
+      for (const job of jobs.values()) {
+        if (ACTIVE_STATUSES.has(job.status)) {
+          job.controller.abort(new ContextualAskError("ASK_CANCELLED"));
+        }
+      }
+      await Promise.allSettled(
+        [...jobs.values()].map((job) => job.runPromise ?? Promise.resolve())
+      );
+      for (const job of jobs.values()) {
+        job.snapshot?.dispose();
+        job.listeners.clear();
+        job.lease.release();
+      }
+      jobs.clear();
+      requests.clear();
+      pendingRequests.clear();
+      await Promise.allSettled(
+        [...executors.values()].map(async (executor) => executor.dispose?.())
+      );
+    }
+  });
+}
+
+// src/contextual-ask/configured-key-executors.ts
+import {
+  createConfiguredKeyAskExecutor,
+  resolveProviderCredential as resolveProviderCredential2
+} from "@spotpatch/agent";
+function createConfiguredKeyAskExecutors(options) {
+  const preferred = options.defaultExecutor?.kind === "configured-key" ? options.defaultExecutor : Object.freeze({
+    kind: "configured-key",
+    providerProfileId: options.ai.defaultProvider,
+    modelProfileId: options.ai.providers[options.ai.defaultProvider]?.defaultModel ?? ""
+  });
+  const providers = Object.values(options.ai.providers).sort(
+    (left, right) => left.id === preferred.providerProfileId ? -1 : right.id === preferred.providerProfileId ? 1 : 0
+  );
+  return Object.freeze(
+    providers.flatMap((provider) => {
+      const credential = resolveProviderCredential2(
+        provider.apiKeyEnv,
+        options.environment
+      );
+      const models = Object.values(provider.models).sort(
+        (left, right) => provider.id !== preferred.providerProfileId ? 0 : left.id === preferred.modelProfileId ? -1 : right.id === preferred.modelProfileId ? 1 : 0
+      );
+      return models.map(
+        (model) => createConfiguredKeyAskExecutor({
+          provider,
+          model,
+          credential,
+          limits: options.ai.execution.limits,
+          ...options.fetch === void 0 ? {} : { fetch: options.fetch }
+        })
+      );
+    })
+  );
+}
+
+// src/contextual-ask/executors.ts
+function composeContextualAskExecutors(options) {
+  return Object.freeze(
+    options.defaultExecutor?.kind === "managed-codex" ? [options.managedCodex, ...options.configuredKey] : [...options.configuredKey, options.managedCodex]
+  );
+}
+
+// src/workspace/activity-coordinator.ts
+function createWorkspaceActivityCoordinator() {
+  let active;
+  return Object.freeze({
+    acquire(kind) {
+      if (active !== void 0) return void 0;
+      active = kind;
+      let released = false;
+      return Object.freeze({
+        release() {
+          if (released) return;
+          released = true;
+          if (active === kind) active = void 0;
+        }
+      });
+    },
+    current() {
+      return active;
+    }
+  });
+}
+
 // src/server/middleware.ts
 import {
   ERROR_CODES as ERROR_CODES16,
   SPOTPATCH_API_BASE,
-  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS4,
+  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS5,
   SpotPatchError as SpotPatchError16,
   openEditorRequestSchema,
   sourceContextRequestSchema
 } from "@spotpatch/shared";
 
+// src/contextual-ask/http.ts
+import {
+  askJobActionRequestSchema,
+  askJobCreateRequestSchema as askJobCreateRequestSchema2,
+  askJobEventsRequestSchema,
+  CONTEXTUAL_ASK_LIMITS as CONTEXTUAL_ASK_LIMITS4,
+  SPOTPATCH_ENDPOINTS
+} from "@spotpatch/shared";
+var STATUS_BY_ERROR = Object.freeze({
+  ASK_DISABLED: 404,
+  ASK_SELECTION_REQUIRED: 422,
+  ASK_SELECTION_STALE: 409,
+  ASK_QUESTION_INVALID: 422,
+  ASK_EXECUTOR_UNAVAILABLE: 503,
+  ASK_TIMEOUT: 504,
+  ASK_CONSENT_REQUIRED: 403,
+  ASK_BUSY: 409,
+  ASK_IDEMPOTENCY_CONFLICT: 409,
+  ASK_SOURCE_SCOPE_DENIED: 403,
+  ASK_LIMIT_EXCEEDED: 413,
+  ASK_ANSWER_INVALID: 502,
+  ASK_WRITE_ATTEMPTED: 403,
+  ASK_CANCELLED: 409,
+  ASK_RESULT_EXPIRED: 410,
+  ASK_PROTOCOL_INCOMPATIBLE: 400
+});
+var PUBLIC_MESSAGES = Object.freeze({
+  ASK_DISABLED: "Contextual Ask is not enabled.",
+  ASK_SELECTION_REQUIRED: "Select at least one source-backed element.",
+  ASK_SELECTION_STALE: "The selected source is stale.",
+  ASK_QUESTION_INVALID: "The question is invalid.",
+  ASK_EXECUTOR_UNAVAILABLE: "The selected Ask executor is unavailable.",
+  ASK_TIMEOUT: "The Ask executor did not answer before the deadline.",
+  ASK_CONSENT_REQUIRED: "Provider data consent is required.",
+  ASK_BUSY: "Another workspace task is active.",
+  ASK_IDEMPOTENCY_CONFLICT: "The request ID was reused with different content.",
+  ASK_SOURCE_SCOPE_DENIED: "The requested source scope was denied.",
+  ASK_LIMIT_EXCEEDED: "The Ask request exceeded a safety limit.",
+  ASK_ANSWER_INVALID: "The executor returned an invalid answer.",
+  ASK_WRITE_ATTEMPTED: "Ask executors cannot write project files.",
+  ASK_CANCELLED: "The Ask job was cancelled.",
+  ASK_RESULT_EXPIRED: "The Ask result has expired.",
+  ASK_PROTOCOL_INCOMPATIBLE: "The Ask protocol request is incompatible."
+});
+function writeJson2(response, status, data) {
+  response.statusCode = status;
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Content-Type", "application/json; charset=utf-8");
+  response.end(JSON.stringify({ ok: true, data }));
+}
+function writeError(response, error, logger) {
+  const normalized = error instanceof ContextualAskError ? error : new ContextualAskError("ASK_EXECUTOR_UNAVAILABLE", { cause: error });
+  if (normalized.code === "ASK_EXECUTOR_UNAVAILABLE" && error !== normalized) {
+    logger?.warn("[spotpatch:ask] Internal contextual Ask request failure.");
+  }
+  response.statusCode = STATUS_BY_ERROR[normalized.code];
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Content-Type", "application/json; charset=utf-8");
+  response.end(
+    JSON.stringify({
+      ok: false,
+      error: {
+        code: normalized.code,
+        message: PUBLIC_MESSAGES[normalized.code]
+      }
+    })
+  );
+}
+function matchContextualAskPath(pathname) {
+  if (pathname === SPOTPATCH_ENDPOINTS.askCapability) {
+    return Object.freeze({ kind: "capability" });
+  }
+  if (pathname === SPOTPATCH_ENDPOINTS.askJobs) {
+    return Object.freeze({ kind: "create" });
+  }
+  const prefix = `${SPOTPATCH_ENDPOINTS.askJobs}/`;
+  if (!pathname.startsWith(prefix)) return void 0;
+  const segments = pathname.slice(prefix.length).split("/");
+  if (segments.length !== 2) return void 0;
+  let jobId;
+  try {
+    jobId = decodeURIComponent(segments[0] ?? "");
+  } catch {
+    return void 0;
+  }
+  const action = segments[1];
+  if (!/^[A-Za-z0-9_-]{1,128}$/u.test(jobId) || action !== "events" && action !== "result" && action !== "cancel") {
+    return void 0;
+  }
+  return Object.freeze({ kind: "job", action, jobId });
+}
+function parseAfterSequence(request) {
+  let url;
+  try {
+    url = new URL(request.url ?? "/", "http://spotpatch.invalid");
+  } catch {
+    throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+  }
+  if ([...url.searchParams.keys()].some((key) => key !== "afterSequence")) {
+    throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+  }
+  const raw = url.searchParams.get("afterSequence");
+  if (raw === null) return 0;
+  if (!/^\d+$/u.test(raw)) throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+  const parsed = askJobEventsRequestSchema.safeParse({ afterSequence: Number(raw) });
+  if (!parsed.success || !Number.isSafeInteger(parsed.data.afterSequence)) {
+    throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+  }
+  return parsed.data.afterSequence ?? 0;
+}
+function streamEvents(request, response, manager, jobId) {
+  const afterSequence = parseAfterSequence(request);
+  response.statusCode = 200;
+  response.setHeader("Cache-Control", "no-store");
+  response.setHeader("Content-Type", "application/x-ndjson; charset=utf-8");
+  response.setHeader("X-Content-Type-Options", "nosniff");
+  let unsubscribe = () => void 0;
+  const heartbeat = setInterval(
+    () => response.write("\n"),
+    CONTEXTUAL_ASK_LIMITS4.eventHeartbeatMs
+  );
+  heartbeat.unref();
+  const cleanup = () => {
+    clearInterval(heartbeat);
+    unsubscribe();
+  };
+  unsubscribe = manager.subscribe(jobId, (event) => {
+    response.write(`${JSON.stringify(event)}
+`);
+    if (["answered", "cancelled", "failed"].includes(event.status)) {
+      cleanup();
+      response.end();
+    }
+  });
+  const replay = manager.events(jobId, afterSequence);
+  for (const event of replay) response.write(`${JSON.stringify(event)}
+`);
+  const latest = replay.at(-1);
+  const currentStatus = latest?.status ?? manager.snapshot(jobId).status;
+  if (["answered", "cancelled", "failed"].includes(currentStatus)) {
+    cleanup();
+    response.end();
+    return;
+  }
+  request.once("close", cleanup);
+  response.once("close", cleanup);
+}
+function hasEmptySelection(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const envelope = value.envelope;
+  if (typeof envelope !== "object" || envelope === null) return false;
+  const selection = envelope.selection;
+  if (typeof selection !== "object" || selection === null) return false;
+  return Array.isArray(selection.targets) && selection.targets.length === 0;
+}
+function lacksProviderDataConsent(value) {
+  return typeof value === "object" && value !== null && value.providerDataConsent !== true;
+}
+async function handleContextualAskRequest(request, response, route, manager, logger) {
+  try {
+    if (manager === void 0) throw new ContextualAskError("ASK_DISABLED");
+    if (route.kind === "capability") {
+      if (request.method !== "GET")
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+      writeJson2(
+        response,
+        200,
+        await manager.capability(
+          AbortSignal.timeout(CONTEXTUAL_ASK_LIMITS4.capabilityTimeoutMs)
+        )
+      );
+      return;
+    }
+    if (route.kind === "create") {
+      if (request.method !== "POST")
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+      const raw = await readJsonRequestBody(
+        request,
+        CONTEXTUAL_ASK_LIMITS4.maximumRequestBodyBytes
+      ).catch((error) => {
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE", { cause: error });
+      });
+      const parsed = askJobCreateRequestSchema2.safeParse(raw);
+      if (!parsed.success) {
+        throw new ContextualAskError(
+          hasEmptySelection(raw) ? "ASK_SELECTION_REQUIRED" : lacksProviderDataConsent(raw) ? "ASK_CONSENT_REQUIRED" : "ASK_PROTOCOL_INCOMPATIBLE"
+        );
+      }
+      writeJson2(response, 202, await manager.create(parsed.data));
+      return;
+    }
+    if (route.action === "events") {
+      if (request.method !== "GET")
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+      streamEvents(request, response, manager, route.jobId);
+      return;
+    }
+    if (route.action === "result") {
+      if (request.method !== "GET")
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+      writeJson2(response, 200, await manager.result(route.jobId));
+      return;
+    }
+    if (request.method !== "POST")
+      throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+    const action = askJobActionRequestSchema.safeParse(
+      await readJsonRequestBody(request).catch((error) => {
+        throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE", { cause: error });
+      })
+    );
+    if (!action.success) throw new ContextualAskError("ASK_PROTOCOL_INCOMPATIBLE");
+    writeJson2(response, 200, manager.cancel(route.jobId));
+  } catch (error) {
+    writeError(response, error, logger);
+  }
+}
+
 // src/external-handoff/browser-http.ts
 import {
   ERROR_CODES as ERROR_CODES10,
   EXTERNAL_HANDOFF_LIMITS as EXTERNAL_HANDOFF_LIMITS5,
-  SPOTPATCH_ENDPOINTS,
+  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS2,
   SpotPatchError as SpotPatchError10,
   externalHandoffCapabilityRequestSchema,
   externalHandoffPublishRequestSchema,
@@ -2517,8 +3892,8 @@ import {
 } from "@spotpatch/shared";
 
 // src/server/annotation-authorizer.ts
-import { realpath as realpath5 } from "fs/promises";
-import path7 from "path";
+import { realpath as realpath6 } from "fs/promises";
+import path8 from "path";
 import {
   ERROR_CODES as ERROR_CODES9,
   SpotPatchError as SpotPatchError9,
@@ -2527,8 +3902,8 @@ import {
 } from "@spotpatch/shared";
 
 // src/server/source-context.ts
-import { readFile as readFile3, realpath as realpath4 } from "fs/promises";
-import path6 from "path";
+import { readFile as readFile3, realpath as realpath5 } from "fs/promises";
+import path7 from "path";
 import {
   ERROR_CODES as ERROR_CODES8,
   SpotPatchError as SpotPatchError8
@@ -2536,8 +3911,8 @@ import {
 
 // src/server/extract-code-context.ts
 import {
-  parseSync,
-  Visitor
+  parseSync as parseSync2,
+  Visitor as Visitor2
 } from "oxc-parser";
 function isComponentName(name) {
   return /^[A-Z]/u.test(name);
@@ -2621,7 +3996,7 @@ function findComponentSpan(options) {
   }
   let parseResult;
   try {
-    parseResult = parseSync(options.sourcePath, options.source, {
+    parseResult = parseSync2(options.sourcePath, options.source, {
       sourceType: "module"
     });
   } catch {
@@ -2632,7 +4007,7 @@ function findComponentSpan(options) {
   }
   const jsxNodes = [];
   const components = [];
-  const visitor = new Visitor({
+  const visitor = new Visitor2({
     JSXElement(node) {
       jsxNodes.push(node);
     },
@@ -2764,8 +4139,8 @@ function extractCodeContext(options) {
 }
 
 // src/server/source-file.ts
-import { realpath as realpath3, stat as stat2 } from "fs/promises";
-import path5 from "path";
+import { realpath as realpath4, stat as stat2 } from "fs/promises";
+import path6 from "path";
 import { ERROR_CODES as ERROR_CODES7, SpotPatchError as SpotPatchError7 } from "@spotpatch/shared";
 var ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([".jsx", ".tsx"]);
 function isMissingFileError(error) {
@@ -2776,8 +4151,8 @@ async function assertInsideRoot(root, candidate) {
   let realCandidate;
   try {
     [realRoot, realCandidate] = await Promise.all([
-      realpath3(root),
-      realpath3(candidate)
+      realpath4(root),
+      realpath4(candidate)
     ]);
   } catch (error) {
     if (isMissingFileError(error)) {
@@ -2787,8 +4162,8 @@ async function assertInsideRoot(root, candidate) {
     }
     throw error;
   }
-  const relative = path5.relative(realRoot, realCandidate);
-  const outside = relative.startsWith(`..${path5.sep}`) || relative === ".." || path5.isAbsolute(relative);
+  const relative = path6.relative(realRoot, realCandidate);
+  const outside = relative.startsWith(`..${path6.sep}`) || relative === ".." || path6.isAbsolute(relative);
   if (outside) {
     throw new SpotPatchError7(ERROR_CODES7.SOURCE_OUTSIDE_ROOT);
   }
@@ -2800,7 +4175,7 @@ async function resolveSourceFile(options) {
     throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND);
   }
   const sourcePath = await assertInsideRoot(options.root, registeredPath);
-  if (!ALLOWED_EXTENSIONS.has(path5.extname(sourcePath).toLowerCase())) {
+  if (!ALLOWED_EXTENSIONS.has(path6.extname(sourcePath).toLowerCase())) {
     throw new SpotPatchError7(ERROR_CODES7.SOURCE_NOT_FOUND);
   }
   let sourceStat;
@@ -2825,7 +4200,7 @@ async function resolveSourceFile(options) {
 
 // src/server/source-context.ts
 function toDisplayPath(root, sourcePath) {
-  return path6.relative(root, sourcePath).split(path6.sep).join("/");
+  return path7.relative(root, sourcePath).split(path7.sep).join("/");
 }
 async function readSourceContext(options) {
   const sourcePath = await resolveSourceFile({
@@ -2848,11 +4223,11 @@ async function readSourceContext(options) {
   if (options.request.line > lines.length) {
     throw new SpotPatchError8(ERROR_CODES8.INVALID_REQUEST);
   }
-  const extension = path6.extname(sourcePath).toLowerCase();
+  const extension = path7.extname(sourcePath).toLowerCase();
   return extractCodeContext({
     source,
     sourcePath,
-    relativePath: toDisplayPath(await realpath4(options.root), sourcePath),
+    relativePath: toDisplayPath(await realpath5(options.root), sourcePath),
     language: extension === ".tsx" ? "tsx" : "jsx",
     line: options.request.line,
     column: options.request.column,
@@ -2894,7 +4269,7 @@ async function authorizeSourceRef(source, registry, root) {
     return compactSourceRef(source);
   }
   const sourcePath = await resolveSourceFile({ fileId: source.fileId, registry, root });
-  const relativePath = path7.relative(await realpath5(root), sourcePath).split(path7.sep).join("/");
+  const relativePath = path8.relative(await realpath6(root), sourcePath).split(path8.sep).join("/");
   if (source.relativePath !== void 0 && source.relativePath !== relativePath) {
     throw new SpotPatchError9(ERROR_CODES9.INVALID_REQUEST);
   }
@@ -2997,11 +4372,11 @@ async function authorizeAnnotation(input) {
 }
 
 // src/external-handoff/browser-http.ts
-function matchExternalHandoffBrowserPath(path9) {
-  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffCapability) return "capability";
-  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffPublish) return "publish";
-  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffStatus) return "status";
-  if (path9 === SPOTPATCH_ENDPOINTS.externalHandoffResolveDelivery) {
+function matchExternalHandoffBrowserPath(path10) {
+  if (path10 === SPOTPATCH_ENDPOINTS2.externalHandoffCapability) return "capability";
+  if (path10 === SPOTPATCH_ENDPOINTS2.externalHandoffPublish) return "publish";
+  if (path10 === SPOTPATCH_ENDPOINTS2.externalHandoffStatus) return "status";
+  if (path10 === SPOTPATCH_ENDPOINTS2.externalHandoffResolveDelivery) {
     return "resolve-delivery";
   }
   return void 0;
@@ -3081,7 +4456,7 @@ async function handleExternalHandoffBrowserRequest(request, response, route, opt
 import {
   ERROR_CODES as ERROR_CODES11,
   EXTERNAL_AGENT_CONTROL_LIMITS,
-  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS2,
+  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS3,
   SpotPatchError as SpotPatchError11,
   externalAgentControlCancelRequestSchema,
   externalAgentControlConnectRequestSchema,
@@ -3093,15 +4468,15 @@ import {
   externalAgentManagedResultSchema,
   externalAgentResultRequestSchema
 } from "@spotpatch/shared";
-function matchExternalAgentBrowserPath(path9) {
-  if (path9 === SPOTPATCH_ENDPOINTS2.externalAgentControlStatus) return "status";
-  if (path9 === SPOTPATCH_ENDPOINTS2.externalAgentControlConnect) return "connect";
-  if (path9 === SPOTPATCH_ENDPOINTS2.externalAgentControlDisconnect) {
+function matchExternalAgentBrowserPath(path10) {
+  if (path10 === SPOTPATCH_ENDPOINTS3.externalAgentControlStatus) return "status";
+  if (path10 === SPOTPATCH_ENDPOINTS3.externalAgentControlConnect) return "connect";
+  if (path10 === SPOTPATCH_ENDPOINTS3.externalAgentControlDisconnect) {
     return "disconnect";
   }
-  if (path9 === SPOTPATCH_ENDPOINTS2.externalAgentControlCancel) return "cancel";
-  if (path9 === SPOTPATCH_ENDPOINTS2.externalAgentEvents) return "events";
-  if (path9 === SPOTPATCH_ENDPOINTS2.externalAgentResult) return "result";
+  if (path10 === SPOTPATCH_ENDPOINTS3.externalAgentControlCancel) return "cancel";
+  if (path10 === SPOTPATCH_ENDPOINTS3.externalAgentEvents) return "events";
+  if (path10 === SPOTPATCH_ENDPOINTS3.externalAgentResult) return "result";
   return void 0;
 }
 function writeEvent(response, event) {
@@ -3240,7 +4615,7 @@ function createExternalAgentBrowserController(port) {
 // src/server/agent-http.ts
 import {
   ERROR_CODES as ERROR_CODES12,
-  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS3,
+  SPOTPATCH_ENDPOINTS as SPOTPATCH_ENDPOINTS4,
   SpotPatchError as SpotPatchError12,
   agentCapabilityRequestSchema,
   agentJobActionRequestSchema,
@@ -3285,21 +4660,21 @@ var EVENT_STREAM_END_STATUSES = /* @__PURE__ */ new Set([
   "reverted",
   "failed"
 ]);
-function matchAgentRequestPath(path9) {
-  if (path9 === SPOTPATCH_ENDPOINTS3.agentCapability) {
+function matchAgentRequestPath(path10) {
+  if (path10 === SPOTPATCH_ENDPOINTS4.agentCapability) {
     return Object.freeze({ kind: "capability" });
   }
-  if (path9 === SPOTPATCH_ENDPOINTS3.agentWorkspaceHealth) {
+  if (path10 === SPOTPATCH_ENDPOINTS4.agentWorkspaceHealth) {
     return Object.freeze({ kind: "workspace-health" });
   }
-  if (path9 === SPOTPATCH_ENDPOINTS3.agentJobs) {
+  if (path10 === SPOTPATCH_ENDPOINTS4.agentJobs) {
     return Object.freeze({ kind: "create-job" });
   }
-  const prefix = `${SPOTPATCH_ENDPOINTS3.agentJobs}/`;
-  if (!path9.startsWith(prefix)) {
+  const prefix = `${SPOTPATCH_ENDPOINTS4.agentJobs}/`;
+  if (!path10.startsWith(prefix)) {
     return void 0;
   }
-  const segments = path9.slice(prefix.length).split("/");
+  const segments = path10.slice(prefix.length).split("/");
   const jobId = segments[0];
   const action = segments[1];
   if (segments.length !== 2 || jobId === void 0 || !AGENT_JOB_ID_PATTERN.test(jobId) || action === void 0 || !AGENT_JOB_ACTIONS.has(action)) {
@@ -3493,13 +4868,13 @@ function detectIntegratedEditor(environment) {
 function editorCommand(editor) {
   return editor === "cursor" ? "cursor" : "code";
 }
-var DEFAULT_DEPENDENCIES2 = Object.freeze({
+var DEFAULT_DEPENDENCIES3 = Object.freeze({
   environment: process.env,
   fallbackLauncher: launchEditor,
   processSpawner: (command, arguments_, options) => spawn(command, [...arguments_], options),
   startupGraceMs: EDITOR_STARTUP_GRACE_MS
 });
-function createEditorLauncher(dependencies = DEFAULT_DEPENDENCIES2) {
+function createEditorLauncher(dependencies = DEFAULT_DEPENDENCIES3) {
   return (target, configuredEditor) => {
     const integratedEditor = detectIntegratedEditor(dependencies.environment);
     const resolvedEditor = configuredEditor === "auto" ? integratedEditor : configuredEditor;
@@ -3554,7 +4929,7 @@ function createEditorLauncher(dependencies = DEFAULT_DEPENDENCIES2) {
 var launchConfiguredEditor = createEditorLauncher();
 
 // src/server/data-flow-http.ts
-import { createHash as createHash3 } from "crypto";
+import { createHash as createHash5 } from "crypto";
 import {
   createStaticDataFlowAnalyzer
 } from "@spotpatch/analyzer";
@@ -3683,7 +5058,7 @@ async function handlePageDataFlowReport(request, analyzer, options) {
   const analyzedVersions = new Set(
     componentReports.flatMap((report2) => report2.baseline.analyzedSourceVersions)
   );
-  const reportId = `page_${createHash3("sha256").update(componentReports.map((report2) => report2.reportId).join("\0")).digest("base64url").slice(0, 22)}`;
+  const reportId = `page_${createHash5("sha256").update(componentReports.map((report2) => report2.reportId).join("\0")).digest("base64url").slice(0, 22)}`;
   const complete = componentReports.every((report2) => report2.completeness.complete);
   const report = Object.freeze({
     schemaVersion: DATA_FLOW_SCHEMA_VERSION,
@@ -3776,6 +5151,9 @@ function parseOrigin(value) {
     return void 0;
   }
 }
+function isSameOriginBrowserGet(request) {
+  return request.method === "GET" && getSingleHeader(request, "sec-fetch-site")?.toLowerCase() === "same-origin" && getSingleHeader(request, "sec-fetch-mode")?.toLowerCase() === "cors" && getSingleHeader(request, "sec-fetch-dest")?.toLowerCase() === "empty";
+}
 function assertRequestAuthorized(request, options) {
   const actualToken = getSingleHeader(request, SPOTPATCH_TOKEN_HEADER);
   if (!tokensMatch2(actualToken, options.sessionToken)) {
@@ -3785,10 +5163,16 @@ function assertRequestAuthorized(request, options) {
   const originHeader = getSingleHeader(request, "origin");
   const host = hostHeader === void 0 ? void 0 : parseHost(hostHeader);
   const origin = originHeader === void 0 ? void 0 : parseOrigin(originHeader);
-  if (host === void 0 || origin === void 0) {
+  if (host === void 0) {
     throw new SpotPatchError14(ERROR_CODES14.ORIGIN_NOT_ALLOWED);
   }
   const hostIsLoopback = isLoopbackHostname(host.hostname);
+  if (origin === void 0) {
+    if (!isSameOriginBrowserGet(request) || !options.allowLan && !hostIsLoopback) {
+      throw new SpotPatchError14(ERROR_CODES14.ORIGIN_NOT_ALLOWED);
+    }
+    return;
+  }
   const originIsLoopback = isLoopbackHostname(origin.hostname);
   if (!options.allowLan) {
     if (!hostIsLoopback || !originIsLoopback) {
@@ -3861,7 +5245,7 @@ async function readRuntimeBootstrap(request, options) {
 }
 
 // src/server/middleware.ts
-var STATUS_BY_ERROR = Object.freeze({
+var STATUS_BY_ERROR2 = Object.freeze({
   [ERROR_CODES16.INVALID_REQUEST]: 400,
   [ERROR_CODES16.INVALID_TOKEN]: 401,
   [ERROR_CODES16.ORIGIN_NOT_ALLOWED]: 403,
@@ -3917,7 +5301,7 @@ var STATUS_BY_ERROR = Object.freeze({
   [ERROR_CODES16.APPLY_CONFLICT]: 409,
   [ERROR_CODES16.INTERNAL_ERROR]: 500
 });
-var PUBLIC_MESSAGES = Object.freeze({
+var PUBLIC_MESSAGES2 = Object.freeze({
   [ERROR_CODES16.INVALID_REQUEST]: "The request is invalid.",
   [ERROR_CODES16.INVALID_TOKEN]: "The session token is invalid.",
   [ERROR_CODES16.ORIGIN_NOT_ALLOWED]: "The request origin is not allowed.",
@@ -3973,7 +5357,7 @@ var PUBLIC_MESSAGES = Object.freeze({
   [ERROR_CODES16.APPLY_CONFLICT]: "The change conflicts with the current worktree.",
   [ERROR_CODES16.INTERNAL_ERROR]: "The request could not be completed."
 });
-function writeJson2(response, status, payload) {
+function writeJson3(response, status, payload) {
   response.statusCode = status;
   response.setHeader("Cache-Control", "no-store");
   response.setHeader("Content-Type", "application/json; charset=utf-8");
@@ -3982,16 +5366,16 @@ function writeJson2(response, status, payload) {
 function asSpotPatchError(error) {
   return error instanceof SpotPatchError16 ? error : new SpotPatchError16(ERROR_CODES16.INTERNAL_ERROR, void 0, { cause: error });
 }
-function writeError(response, error, logger) {
+function writeError2(response, error, logger) {
   const normalized = asSpotPatchError(error);
   if (normalized.code === ERROR_CODES16.INTERNAL_ERROR) {
     logger?.warn("[spotpatch:server] Internal request failure.");
   }
-  writeJson2(response, STATUS_BY_ERROR[normalized.code], {
+  writeJson3(response, STATUS_BY_ERROR2[normalized.code], {
     ok: false,
     error: {
       code: normalized.code,
-      message: PUBLIC_MESSAGES[normalized.code]
+      message: PUBLIC_MESSAGES2[normalized.code]
     }
   });
 }
@@ -4047,44 +5431,55 @@ function createSpotPatchMiddleware(options) {
   const dataFlowAnalyzer = createDataFlowAnalyzer(options);
   const externalAgentController = options.externalAgentControl === void 0 ? void 0 : createExternalAgentBrowserController(options.externalAgentControl);
   const middleware = (request, response, next) => {
-    const path9 = requestPath(request);
-    const agentRoute = matchAgentRequestPath(path9);
-    const externalAgentRoute = matchExternalAgentBrowserPath(path9);
-    const externalHandoffRoute = matchExternalHandoffBrowserPath(path9);
-    if (path9 !== SPOTPATCH_ENDPOINTS4.sourceContext && path9 !== SPOTPATCH_ENDPOINTS4.openEditor && path9 !== SPOTPATCH_ENDPOINTS4.dataFlowComponentReport && path9 !== SPOTPATCH_ENDPOINTS4.dataFlowPageReport && agentRoute === void 0 && externalAgentRoute === void 0 && externalHandoffRoute === void 0 && !path9.startsWith(`${SPOTPATCH_API_BASE}/`)) {
+    const path10 = requestPath(request);
+    const agentRoute = matchAgentRequestPath(path10);
+    const askRoute = matchContextualAskPath(path10);
+    const externalAgentRoute = matchExternalAgentBrowserPath(path10);
+    const externalHandoffRoute = matchExternalHandoffBrowserPath(path10);
+    if (path10 !== SPOTPATCH_ENDPOINTS5.sourceContext && path10 !== SPOTPATCH_ENDPOINTS5.openEditor && path10 !== SPOTPATCH_ENDPOINTS5.dataFlowComponentReport && path10 !== SPOTPATCH_ENDPOINTS5.dataFlowPageReport && agentRoute === void 0 && askRoute === void 0 && externalAgentRoute === void 0 && externalHandoffRoute === void 0 && !path10.startsWith(`${SPOTPATCH_API_BASE}/`)) {
       next();
       return;
     }
     const handle = async () => {
-      if (path9 === SPOTPATCH_ENDPOINTS4.bootstrap && bootstrap !== void 0) {
+      if (path10 === SPOTPATCH_ENDPOINTS5.bootstrap && bootstrap !== void 0) {
         const data = await readRuntimeBootstrap(
           request,
           bootstrap
         );
-        writeJson2(response, 200, { ok: true, data });
+        writeJson3(response, 200, { ok: true, data });
         return;
       }
       assertRequestAuthorized(request, {
         allowLan: options.options.allowLan,
         sessionToken: options.session.token
       });
-      if (path9 === SPOTPATCH_ENDPOINTS4.sourceContext) {
+      if (askRoute !== void 0) {
+        await handleContextualAskRequest(
+          request,
+          response,
+          askRoute,
+          options.contextualAskManager,
+          options.logger
+        );
+        return;
+      }
+      if (path10 === SPOTPATCH_ENDPOINTS5.sourceContext) {
         if (request.method !== "POST") {
           throw new SpotPatchError16(ERROR_CODES16.INVALID_REQUEST);
         }
         const data = await handleSourceContext(request, options);
-        writeJson2(response, 200, { ok: true, data });
+        writeJson3(response, 200, { ok: true, data });
         return;
       }
-      if (path9 === SPOTPATCH_ENDPOINTS4.openEditor) {
+      if (path10 === SPOTPATCH_ENDPOINTS5.openEditor) {
         if (request.method !== "POST") {
           throw new SpotPatchError16(ERROR_CODES16.INVALID_REQUEST);
         }
         const data = await handleOpenEditor(request, options);
-        writeJson2(response, 200, { ok: true, data });
+        writeJson3(response, 200, { ok: true, data });
         return;
       }
-      if (path9 === SPOTPATCH_ENDPOINTS4.dataFlowComponentReport) {
+      if (path10 === SPOTPATCH_ENDPOINTS5.dataFlowComponentReport) {
         if (request.method !== "POST") {
           throw new SpotPatchError16(ERROR_CODES16.INVALID_REQUEST);
         }
@@ -4093,15 +5488,15 @@ function createSpotPatchMiddleware(options) {
           dataFlowAnalyzer,
           options
         );
-        writeJson2(response, 200, { ok: true, data });
+        writeJson3(response, 200, { ok: true, data });
         return;
       }
-      if (path9 === SPOTPATCH_ENDPOINTS4.dataFlowPageReport) {
+      if (path10 === SPOTPATCH_ENDPOINTS5.dataFlowPageReport) {
         if (request.method !== "POST") {
           throw new SpotPatchError16(ERROR_CODES16.INVALID_REQUEST);
         }
         const data = await handlePageDataFlowReport(request, dataFlowAnalyzer, options);
-        writeJson2(response, 200, { ok: true, data });
+        writeJson3(response, 200, { ok: true, data });
         return;
       }
       if (externalAgentRoute !== void 0) {
@@ -4113,7 +5508,7 @@ function createSpotPatchMiddleware(options) {
           response,
           externalAgentRoute,
           (target, status, data) => {
-            writeJson2(target, status, { ok: true, data });
+            writeJson3(target, status, { ok: true, data });
           }
         );
         return;
@@ -4130,7 +5525,7 @@ function createSpotPatchMiddleware(options) {
             ...options.externalHandoffService === void 0 ? {} : { service: options.externalHandoffService }
           },
           (target, status, data) => {
-            writeJson2(target, status, { ok: true, data });
+            writeJson3(target, status, { ok: true, data });
           }
         );
         return;
@@ -4144,12 +5539,12 @@ function createSpotPatchMiddleware(options) {
         options,
         agentRoute,
         (target, status, data) => {
-          writeJson2(target, status, { ok: true, data });
+          writeJson3(target, status, { ok: true, data });
         }
       );
     };
     void handle().catch((error) => {
-      writeError(response, error, options.logger);
+      writeError2(response, error, options.logger);
     });
   };
   return Object.assign(middleware, {
@@ -4161,17 +5556,33 @@ function createSpotPatchMiddleware(options) {
 
 // src/server/source-registration.ts
 import { timingSafeEqual as timingSafeEqual3 } from "crypto";
-import { lstat as lstat4, realpath as realpath6 } from "fs/promises";
-import path8 from "path";
-import { createSourceFilter } from "@spotpatch/compiler";
+import { lstat as lstat5, readFile as readFile4, realpath as realpath7 } from "fs/promises";
+import path9 from "path";
+import {
+  createDataFlowSourceFilter,
+  createDataFlowSourceVersion,
+  createSourceFilter
+} from "@spotpatch/compiler";
+import { DEFAULT_DATA_FLOW_LIMITS as DEFAULT_DATA_FLOW_LIMITS2 } from "@spotpatch/shared";
 import { z as z2 } from "zod";
-var REGISTRATION_BODY_LIMIT_BYTES = 4096;
+var REGISTRATION_BODY_LIMIT_BYTES = DEFAULT_DATA_FLOW_LIMITS2.protocolRequestMaxBytes;
 var REGISTRATION_IDENTITY_PATTERN = /^[A-Za-z0-9_-]{16,128}$/u;
+var DATA_FLOW_IDENTITY_PATTERN = /^[A-Za-z0-9_-]{1,128}$/u;
 var INTERNAL_SECRET_HEADER = "x-spotpatch-internal";
 var FORBIDDEN_SOURCE_SEGMENTS = /* @__PURE__ */ new Set([".next", "node_modules"]);
 var registrationRequestSchema = z2.strictObject({
   epoch: z2.string().regex(REGISTRATION_IDENTITY_PATTERN),
-  resourcePath: z2.string().min(1).max(3072)
+  resourcePath: z2.string().min(1).max(3072),
+  dataFlow: z2.strictObject({
+    sourceVersion: z2.string().regex(DATA_FLOW_IDENTITY_PATTERN),
+    components: z2.array(
+      z2.strictObject({
+        componentSourceId: z2.string().regex(DATA_FLOW_IDENTITY_PATTERN),
+        line: z2.number().int().positive().max(1e7),
+        column: z2.number().int().positive().max(1e7)
+      })
+    ).max(DEFAULT_DATA_FLOW_LIMITS2.sourceMaxComponents)
+  }).optional()
 });
 function getSingleHeader3(request, name) {
   const value = request.headers[name.toLowerCase()];
@@ -4186,13 +5597,13 @@ function identitiesMatch(actual, expected) {
   return actualBytes.byteLength === expectedBytes.byteLength && timingSafeEqual3(actualBytes, expectedBytes);
 }
 function isWithinRoot(root, candidate) {
-  const relative = path8.relative(root, candidate);
-  return relative === "" || !relative.startsWith(`..${path8.sep}`) && relative !== ".." && !path8.isAbsolute(relative);
+  const relative = path9.relative(root, candidate);
+  return relative === "" || !relative.startsWith(`..${path9.sep}`) && relative !== ".." && !path9.isAbsolute(relative);
 }
 function hasForbiddenSegment(root, candidate) {
-  return path8.relative(root, candidate).split(path8.sep).some((segment) => FORBIDDEN_SOURCE_SEGMENTS.has(segment));
+  return path9.relative(root, candidate).split(path9.sep).some((segment) => FORBIDDEN_SOURCE_SEGMENTS.has(segment));
 }
-function writeJson3(response, statusCode, payload) {
+function writeJson4(response, statusCode, payload) {
   const body = JSON.stringify(payload);
   response.statusCode = statusCode;
   response.setHeader("Cache-Control", "no-store");
@@ -4212,15 +5623,15 @@ function requestComesFromLoopbackWorker(request) {
   }
 }
 async function resolveAuthorizedSource(root, requestedPath, shouldTransform) {
-  if (!path8.isAbsolute(requestedPath) || requestedPath.includes("\0")) {
+  if (!path9.isAbsolute(requestedPath) || requestedPath.includes("\0")) {
     return void 0;
   }
   try {
-    const sourceStat = await lstat4(requestedPath);
+    const sourceStat = await lstat5(requestedPath);
     if (!sourceStat.isFile() || sourceStat.isSymbolicLink()) {
       return void 0;
     }
-    const resolvedPath = await realpath6(requestedPath);
+    const resolvedPath = await realpath7(requestedPath);
     if (!isWithinRoot(root, resolvedPath) || hasForbiddenSegment(root, resolvedPath) || !shouldTransform(resolvedPath)) {
       return void 0;
     }
@@ -4233,8 +5644,35 @@ async function createSourceRegistrationService(input) {
   if (!REGISTRATION_IDENTITY_PATTERN.test(input.internalSecret) || !REGISTRATION_IDENTITY_PATTERN.test(input.registryEpoch)) {
     throw new TypeError("The source registration identity is invalid.");
   }
-  const root = await realpath6(input.root);
+  const root = await realpath7(input.root);
   const sourceFilter = createSourceFilter(root, input.options);
+  const dataFlowFilter = createDataFlowSourceFilter(root, input.options);
+  const registrationQueues = /* @__PURE__ */ new Map();
+  async function registerCurrentSource(sourcePath, dataFlow) {
+    if (dataFlow === void 0) {
+      return input.registry.register(sourcePath);
+    }
+    let fileId;
+    const previous = registrationQueues.get(sourcePath) ?? Promise.resolve();
+    const current = previous.catch(() => void 0).then(async () => {
+      const currentSource = await readFile4(sourcePath, "utf8");
+      if (createDataFlowSourceVersion(currentSource) !== dataFlow.sourceVersion) {
+        return;
+      }
+      fileId = input.registry.registerDataFlowComponents(
+        sourcePath,
+        dataFlow.sourceVersion,
+        dataFlow.components
+      );
+    });
+    registrationQueues.set(sourcePath, current);
+    await current.finally(() => {
+      if (registrationQueues.get(sourcePath) === current) {
+        registrationQueues.delete(sourcePath);
+      }
+    });
+    return fileId;
+  }
   const handler = (request, response) => {
     const handle = async () => {
       const contentType = getSingleHeader3(request, "content-type")?.split(";", 1)[0]?.trim().toLowerCase();
@@ -4242,33 +5680,35 @@ async function createSourceRegistrationService(input) {
         getSingleHeader3(request, INTERNAL_SECRET_HEADER),
         input.internalSecret
       )) {
-        writeJson3(response, 403, { ok: false });
+        writeJson4(response, 403, { ok: false });
         return;
       }
       const parsed = registrationRequestSchema.safeParse(
         await readJsonRequestBody(request, REGISTRATION_BODY_LIMIT_BYTES)
       );
       if (!parsed.success || parsed.data.epoch !== input.registryEpoch) {
-        writeJson3(response, 400, { ok: false });
+        writeJson4(response, 400, { ok: false });
         return;
       }
       const sourcePath = await resolveAuthorizedSource(
         root,
         parsed.data.resourcePath,
-        (absolutePath) => sourceFilter.shouldTransform(absolutePath, "<")
+        (absolutePath) => parsed.data.dataFlow === void 0 ? sourceFilter.shouldTransform(absolutePath, "<") : dataFlowFilter.shouldTransform(absolutePath, "")
       );
       if (sourcePath === void 0) {
-        writeJson3(response, 403, { ok: false });
+        writeJson4(response, 403, { ok: false });
         return;
       }
-      writeJson3(response, 200, {
-        epoch: input.registryEpoch,
-        fileId: input.registry.register(sourcePath)
-      });
+      const fileId = await registerCurrentSource(sourcePath, parsed.data.dataFlow);
+      if (fileId === void 0) {
+        writeJson4(response, 409, { ok: false });
+        return;
+      }
+      writeJson4(response, 200, { epoch: input.registryEpoch, fileId });
     };
     void handle().catch(() => {
       if (!response.headersSent) {
-        writeJson3(response, 400, { ok: false });
+        writeJson4(response, 400, { ok: false });
       } else {
         response.destroy();
       }
@@ -4278,11 +5718,11 @@ async function createSourceRegistrationService(input) {
 }
 
 // src/session/session.ts
-import { randomBytes as randomBytes8 } from "crypto";
+import { randomBytes as randomBytes10 } from "crypto";
 function createSession() {
   return Object.freeze({
-    id: randomBytes8(16).toString("base64url"),
-    token: randomBytes8(16).toString("base64url")
+    id: randomBytes10(16).toString("base64url"),
+    token: randomBytes10(16).toString("base64url")
   });
 }
 
@@ -4293,6 +5733,7 @@ var OPTION_KEYS = Object.freeze([
   "budget",
   "debug",
   "dataFlow",
+  "contextualAsk",
   "editor",
   "enabled",
   "externalAgent",
@@ -4384,6 +5825,9 @@ function serializeResolvedSpotPatchOptions(options) {
     dataFlow: options.dataFlow.enabled ? Object.freeze({
       runtime: options.dataFlow.runtime
     }) : false,
+    contextualAsk: options.contextualAsk.enabled ? Object.freeze({
+      ...options.contextualAsk.defaultExecutor === void 0 ? {} : { defaultExecutor: options.contextualAsk.defaultExecutor }
+    }) : false,
     editor: options.editor,
     enabled: options.enabled,
     externalAgent: options.externalAgent.enabled,
@@ -4436,6 +5880,33 @@ function parseDataFlow(value) {
     runtime: value.runtime
   });
 }
+function parseContextualAsk(value) {
+  if (value === false || value === true) return value;
+  if (!isRecord2(value)) {
+    throw new TypeError("The SpotPatch contextual Ask transport is invalid.");
+  }
+  const keys = Object.keys(value);
+  if (keys.length === 0) return Object.freeze({});
+  if (!hasExactKeys(value, ["defaultExecutor"]) || !isRecord2(value.defaultExecutor)) {
+    throw new TypeError("The SpotPatch contextual Ask transport is invalid.");
+  }
+  const preference = value.defaultExecutor;
+  if (preference.kind === "managed-codex" && hasExactKeys(preference, ["kind"])) {
+    return Object.freeze({
+      defaultExecutor: Object.freeze({ kind: "managed-codex" })
+    });
+  }
+  if (preference.kind === "configured-key" && hasExactKeys(preference, ["kind", "modelProfileId", "providerProfileId"]) && typeof preference.providerProfileId === "string" && typeof preference.modelProfileId === "string") {
+    return Object.freeze({
+      defaultExecutor: Object.freeze({
+        kind: "configured-key",
+        providerProfileId: preference.providerProfileId,
+        modelProfileId: preference.modelProfileId
+      })
+    });
+  }
+  throw new TypeError("The SpotPatch contextual Ask transport is invalid.");
+}
 function parseSerializedSpotPatchOptions(value) {
   if (!isRecord2(value) || !hasExactKeys(value, OPTION_KEYS)) {
     throw new TypeError("The SpotPatch options transport is invalid.");
@@ -4450,6 +5921,7 @@ function parseSerializedSpotPatchOptions(value) {
       budget: parseBudget(value.budget),
       debug: value.debug,
       dataFlow: parseDataFlow(value.dataFlow),
+      contextualAsk: parseContextualAsk(value.contextualAsk),
       editor: value.editor,
       enabled: value.enabled,
       externalAgent: value.externalAgent,
@@ -4467,10 +5939,15 @@ function parseSerializedSpotPatchOptions(value) {
   }
 }
 export {
+  ContextualAskError,
   DEFAULT_EXCLUDE,
   DEFAULT_OPTIONS,
   applyIntegrationPlan,
+  captureAskReadSnapshot,
+  composeContextualAskExecutors,
   createAgentJobManager,
+  createConfiguredKeyAskExecutors,
+  createContextualAskManager,
   createExternalHandoffService,
   createIntegrationFileChange,
   createRuntimeAiConfig,
@@ -4479,9 +5956,12 @@ export {
   createSourceRegistrationService,
   createSourceRegistry,
   createSpotPatchMiddleware,
+  createWorkspaceActivityCoordinator,
   discoverProjectValidationCheck,
+  handleContextualAskRequest,
   integrationPathExists,
   isLoopbackHostname,
+  matchContextualAskPath,
   parseSerializedSpotPatchOptions,
   readIntegrationFile,
   readJsonRequestBody,